前言¶
在 Mac 上跑 DSH、让 Agent 长时间执行任务时，系统往往会按电源策略进入睡眠或锁屏，任务可能被挂起或中断。有人会用 caffeinate 手工占住断言，或在 profile 里挂常驻 LaunchAgent；这些做法要么和 DSH 生命周期脱节，要么需要额外维护。dsh-caffeinate 是 Host 侧 DSH（Cordis）插件：加载时用系统自带的 /usr/bin/caffeinate 拉起子进程，并在参数末尾固定 -w <DSH 主进程 PID>，断言随宿主退出而释放；同时提供 /keepawake（别名 /caffeinate）查看状态与切换模式。下面介绍它的行为、安装与用法。
这是什么¶
- 名称与维护：插件包名
dsh-caffeinate，维护者 veritaswiki，GitHub 仓库 veritaswiki/dsh-caffeinate，社区目录页 SkillHub 条目，分类为 admin-security。 - 版本与许可：
package.json标注版本0.1.0，许可证 MIT。 - 平台：仅 macOS（
darwin）；非 macOS 不会spawn，错误会记入状态并在斜杠指令报告中说明。 - 定位：不做跨平台封装；与 npm 上的
dsh-keep-awake（bearice）相比，本插件只走 macOS 原生caffeinate与-w生命周期，交互集中在斜杠指令，配置在插件标准设置表单里。
核心功能¶
子进程与参数¶
插件加载时在 Host 侧 spawn("/usr/bin/caffeinate", args)，stdio: "ignore"、detached: false，随后对子进程 unref()，避免拖住宿主退出。参数由配置项拼装，末尾固定 -w 加当前 DSH 宿主 process.pid（不是 caffeinate 自己的 pid）。
默认配置下（preventDisplaySleep 为 false，不带 -d）实际命令行等价于：
/usr/bin/caffeinate -i -s -m -w <DSH 主进程 PID>
各配置键与 caffeinate(8) 参数的对应关系如下。
| 配置键 | 默认 | 参数 | 含义 |
|---|---|---|---|
preventIdleSystemSleep |
true |
-i |
阻止系统空闲休眠 |
preventSystemSleepOnAC |
true |
-s |
阻止整机睡眠（交流电下有效） |
preventDiskSleep |
true |
-m |
阻止磁盘空闲休眠 |
preventDisplaySleep |
false |
-d |
阻止显示器休眠 |
| 四个全关 | — | 兜底 -i |
flags 为空时代码补 -i |
运行模式与 reconcile¶
enabled：总开关；为false时停掉子进程。mode：always表示 DSH 打开期间只要启用就维持caffeinate；running-only表示仅当宿主agents服务里存在status === "running"的 agent 时才拉起，否则停止。- 每 15 秒执行一次
reconcile()；子进程异常退出会在下一次轮询重拉（always）或按 agent 状态起停（running-only），起停最多有约 15 秒延迟。 - 卸载插件时清理定时器并对子进程发
SIGTERM；宿主进程消失时，由caffeinate -w自行释放断言并退出，不遗留孤儿进程。
斜杠指令¶
/keepawake 与 /caffeinate 为同一套逻辑。常用子命令：
| 输入 | 作用 |
|---|---|
空、status 或未识别参数 |
只报告，不改状态 |
on / start |
enabled=true、mode=always，屏幕策略恢复为配置里的 preventDisplaySleep |
display / screen |
enabled=true、mode=always、preventDisplaySleep=true |
nodisplay / headless |
enabled=true、mode=always、preventDisplaySleep=false |
running / auto |
enabled=true、mode=running-only |
off / stop |
enabled=false，停子进程 |
每次执行后返回统一报告：守护状态、mode、实际启动参数、屏幕策略、最近异常（若有），以及 pmset -g assertions 中过滤后的相关行（超时 4 秒，非 macOS 会说明不支持）。斜杠指令只改内存状态，不写配置文件；重载插件后回到设置表单里的值。
安装与启用¶
本插件是 DSH bundle。README 给出两种装法；包名已定为 dsh-caffeinate，尚未发布到 npm registry，发布前请用 github: 或 file: spec。
方式 A：通过 Agent 调用 plugin_manager¶
在 DSH 里让 Agent 安装 dsh-caffeinate 时，会调用 plugin_manager：
action: "install_bundle"，target填其一：
- 本地目录：file:/abs/path/to/dsh-caffeinate
- GitHub：github:veritaswiki/dsh-caffeinate
- 已发布后可用 npm 包名：dsh-caffeinate- 安装完成后
action: "set_bundle"启用。
方式 B：手动挂到 profile¶
- 将仓库放在任意目录（记作
/abs/path/to/dsh-caffeinate）。 - 编辑
~/.dsh/profiles/<profile>/package.json：
-dependencies增加："dsh-caffeinate": "link:/abs/path/to/dsh-caffeinate"
-dsh.profile.bundles数组增加："dsh-caffeinate" - 在 profile 目录安装依赖；DSH 下次启动时也会自行安装。
依赖说明：index.js 需要 @deepseek-ai/schemastery（Host 侧配置校验），DSH 自带，为 peerDependencies（>=3.0.0-0），正常安装不必另装。
典型用法¶
在设置里定策略¶
在插件标准设置表单中配置：
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled |
boolean | true |
是否启用守护 |
mode |
"always" | "running-only" |
"always" |
全程防休眠或仅 agent 执行时防休眠 |
preventIdleSystemSleep |
boolean | true |
对应 -i |
preventSystemSleepOnAC |
boolean | true |
对应 -s |
preventDiskSleep |
boolean | true |
对应 -m |
preventDisplaySleep |
boolean | false |
对应 -d；默认关，屏幕仍可息屏锁屏 |
配置在 apply() 时读一次即定型，代码未监听运行时配置变更。
用斜杠指令临时切换¶
长时间跑任务、希望默认息屏但系统别睡：
/keepawake nodisplay
需要同时保持屏幕常亮（会强制 mode=always）：
/keepawake display
只想在 agent 真正 running 时占断言：
/keepawake running
查看当前子进程 PID、绑定宿主 PID、运行秒数与 pmset 片段：
/keepawake status
适用场景与注意¶
适合：仅在 Mac 上使用 DSH，希望防休眠与 DSH 宿主生命周期一致，接受用斜杠指令而非独立可视化面板调参的用户。
运行权限：插件在 DSH Host 进程侧执行，以该进程权限拉起 caffeinate；安装前宜浏览 仓库源码 与 MIT 许可证，自行判断是否纳入 profile。
已知限制（摘自 README）：
- 需要本机存在
/usr/bin/caffeinate；spawn失败只记入lastError，不做安装向导。 -w只监视 DSH 主进程；fork 出的子进程不在绑定范围内。running-only依赖宿主暴露agents服务；取不到服务时不会拉起caffeinate。/keepawake display与running-only不能同时满足「屏幕常亮 + 仅任务时防休眠」，需二选一。- 若系统另有常驻
caffeinate（如仓库中examples/com.user.caffeinate.plist仅为示例，插件不安装也不读取），/keepawake off只关插件这一层断言。 -s仅在交流电下有效，属caffeinate自身语义。
DSH 社区插件目录（如 SkillHub）是独立站点，与 DeepSeek / 幻方无官方从属关系；选用插件属于个人环境决策。
结尾¶
dsh-caffeinate 用 macOS 自带工具和 -w 绑定，在 DSH 运行期间按需维持睡眠断言，并在退出时自动收尾；需要跨平台或可视化设置页时可考虑 dsh-keep-awake，只需 Mac 上安静防休眠时，本插件足够直接。
- 目录页：https://www.skillhub.cn/plugins/veritaswiki/dsh-caffeinate
- GitHub：https://github.com/veritaswiki/dsh-caffeinate
