前言¶

在本地跑 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