前言¶

在本地跑 DeepSeek Harness（DSH）時，Agent 可能長時間執行 shell、拉依賴或等模型響應。若操作系統按電源策略進入睡眠或鎖屏，進程會被掛起或中斷，任務往往只能重來。常見做法是手動改系統電源設置，或在另一個終端裏常駐 caffeinate、systemd-inhibit 等命令，但這與 Agent 生命週期不同步：Agent 已結束，抑制仍可能佔着；多個 Agent 並行時，也很難靠手工數清楚何時該釋放。

@lightjunction/dsh-caffeinate 是社區維護的 DSH 客戶端類插件，由 LIghtJUNction 發佈。它隨 DSH 內 Agent 的啓停自動申請和釋放本機休眠抑制，面向在 Linux 或 macOS 上本地運行 DSH 0.2.1-rc.2、Node 24+ 的環境。插件不替代遠程機器或沙箱上的策略，只作用於運行 DSH 進程的那臺主機。

這是什麼¶

插件一句話定位：Keep the computer awake while DSH agents run（在 DSH Agent 運行期間保持計算機清醒）。實現上通過 bundle patch 接入 Agent 生命週期：有 Agent 在跑時拉起平臺相關的抑制進程，最後一個 Agent 空閒、顯式關閉或卸載插件時再釋放。

維護者與源碼倉庫見 GitHub：LIghtJUNction/dsh-caffeinate。社區目錄頁：skillhub.cn 插件頁。DSH 生態強調「一切皆插件」；SkillHub 等目錄爲獨立社區站點，與 DeepSeek / 幻方無官方從屬關係。

核心功能¶

平臺後端¶

• Linux：使用 systemd-inhibit --what=sleep（mode: display 時爲 idle:sleep），以前臺 Node 進程持有 stdin；需要 logind 可用且允許 inhibit 請求。DSH 異常退出時 stdin EOF 會釋放 Linux 側的 holder。
• macOS：使用 caffeinate -i -w <DSH-pid>；mode: display 時附加 -d。-w 將抑制綁定到 DSH 進程 PID。

子進程由插件持有；spawn 失敗或異常退出會通過工具狀態中的 error 上報，不會拖垮 Agent。

配置模式¶

可選 profile 配置中：

• mode: sleep：阻止系統睡眠。
• mode: display：在 sleep 基礎上再請求顯示/空閒抑制（Linux 爲 logind idle inhibition；部分 compositor 可能忽略，且無 D-Bus ScreenSaver portal 回退）。

Agent 引用與生命週期¶

同一插件實例內，多個運行中的 Agent 形成集合：重複 transition 不會重複計數；某一個 Agent 空閒不會誤釋放其他 Agent 仍需要的抑制。串行化的生命週期操作保證每個插件實例最多擁有一個抑制進程；兩個 Agent 同時運行時可共享同一 PID。最後一個 idle/disposed、顯式 disable 或插件 unload 會關閉 stdin、對進程組發 SIGTERM，必要時 SIGKILL 並等待回收。

Agent 工具¶

插件暴露 caffeinate 工具，用於查詢與控制（revision 需與 status 返回一致；Agent 狀態變化也會改變 revision）：

caffeinate {"action":"status"}
caffeinate {"action":"disable","revision":2}
caffeinate {"action":"enable","revision":3}

status 返回 enabled、activeAgents、pid（0 表示當前無存活的所有制進程）、mode、revision、error。文檔強調：僅有 PID 不能證明 OS 已授予抑制，應閱讀 error。Agent 仍在跑時若啓用失敗會重試啓動，不做自動 crash loop。

可選配置項 command（argv 數組）可覆蓋後端命令，用於特殊主機或診斷；示例 ["node", "-e", "process.stdin.resume()"] 不會抑制睡眠，且無 shell 展開；覆蓋命令須保持前臺並在 stdin EOF 時釋放。

安裝與啓用¶

README 說明：在 release 發佈後，從 GitHub release tarball 安裝（示例不表示 release 一定已發佈）。官方示例命令如下：

dsh plugin --profile headless add https://github.com/LIghtJUNction/dsh-caffeinate/releases/download/v0.1.0/lightjunction-dsh-caffeinate-0.1.0.tgz

bundle 內含 patch，用於自動跟蹤生命週期。若未啓用 HMR，安裝或改配置後需重啓 DSH。

可選 profile patch 配置示例：

- id: dsh-caffeinate
  name: '@lightjunction/dsh-caffeinate'
  config:
    enabled: true
    mode: sleep

在 TypeScript 中也可直接註冊：import * as plugin 後 await ctx.plugin(plugin, { enabled: true, mode: 'sleep' })。

安裝前建議閱讀倉庫源碼與 MIT 許可證；插件以當前 DSH 進程的權限運行，OS 策略、缺失可執行文件或權限不足都可能導致無法抑制。

典型用法¶

1、按上述命令安裝插件並（按需）寫入 enabled 與 mode。

2、正常啓動 DSH 並運行 Agent；有 Agent 活躍時插件應自動維持抑制（可通過 caffeinate {"action":"status"} 查看 activeAgents 與 pid）。

3、需要臨時關閉抑制時，先 status 取 revision，再 disable；重新開啓時用新的 revision 調用 enable。

4、長時間無人值守任務前，若還擔心滅屏，可在支持的環境嘗試 mode: display，並理解 Linux 上顯示抑制並非在所有桌面環境都有效。

適用場景與限制¶

適合：在 Linux 或 macOS 本機用 DSH 跑可能超過系統空閒閾值的 Agent 任務，希望抑制與 Agent 生命週期綁定、少手工改電源或另開終端。

不適合或未實現：

• 不控制 remote world、遠程文件系統、遠程機器或 sandbox；無 Windows / WSL PowerShell 後端。
• 引用計數僅在同一 DSH 進程內的單個插件實例上共享，不跨多個獨立 DSH 進程或重複插件實例（OS 層鎖通常仍可疊加）。
• 無 Raspberry Pi 菜單/狀態欄、保存偏好或與 Pi 環境變量的兼容層。
• 斷電、對 DSH 的 SIGKILL、或惡意自定義 command 程序等，超出插件保證範圍。

倉庫內測試對真實 DSH Agent 循環與前臺 Node 進程做集成校驗（含雙 Agent 共享 PID、取消其一保留另一引用等）；進程 fixture 不證明真實 OS 睡眠行爲或 macOS 設備接受度。上游說明見倉庫中的 UPSTREAM.md、NOTICE。

結尾¶

@lightjunction/dsh-caffeinate（v0.1.0）把「本機在 Agent 運行期間別睡」做成 DSH 插件：Linux 用 systemd-inhibit，macOS 用 caffeinate，並配合工具與 revision 做顯式管控。若你在本地 headless 或長任務場景用 DSH，可在目錄頁查看條目說明，並在 GitHub 跟蹤 issue 與 release。

• 目錄頁：https://www.skillhub.cn/plugins/LIghtJUNction/dsh-caffeinate
• GitHub：https://github.com/LIghtJUNction/dsh-caffeinate