前言¶
在 macOS 上合盖使用笔记本时，系统往往会睡眠或打断长时间跑在 DeepSeek Harness（DSH）里的任务。ClamAwake 一类方案用「虚拟显示 + 显示断言」让机器在合盖时仍能工作，但若保活与 DSH 启停不同步，容易出现：DSH 已退出、后台仍占着虚拟屏和 caffeinate，或反过来 DSH 在跑却没有保活。
dsh-clamawake 是维护者 zhangweijian97 发布的 DSH 工作流类插件：把与 ClamAwake 应用相同的合盖保活配方接到 DSH 宿主生命周期上——DSH 启动则保活跟着起，DSH 停止则保活跟着停。无 Web 面板，纯宿主侧后台逻辑；引擎随包分发，不要求单独安装 ClamAwake 应用。
这是什么¶
- 仓库 / 插件名：
dsh-clamawake（GitHub：zhangweijian97/dsh-clamawake） - 平台：macOS（Apple Silicon），
package.json中os为darwin，engines.dsh要求>=0.2.0 - 定位：宿主
apply阶段注册ctx.effect，在 start 时拉起保活子进程，在 dispose 时只结束本插件自己 spawn 的进程
社区目录页见 SkillHub 插件页。该目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
保活配方在做什么¶
与 ClamAwake 应用侧同一套两件套：
- 虚拟屏：子进程执行
vd-engine create 1800 1169 --hidpi --hold --mirror-main。虚拟屏生命周期绑在持有进程上；对子进程发 SIGTERM 后引擎退出，屏随之消失。--mirror-main表示每次宿主启动都会新建屏并镜像主屏，合盖后由镜像接管，而不是纯扩展屏。 caffeinate -d：独立子进程维持显示断言，停止时一并 SIGTERM。
插件包内自带 arm64 的 bin/vd-engine，无需另装 ClamAwake。引擎源码来自 ClamAwake 的 src/vd-engine.swift。
生命周期与所有权¶
启动（start）¶
解析 vd-engine 路径 → 确认 /usr/bin/caffeinate 存在 → 只读执行一次 vd-engine list → 若已有带 kya=yes 的屏（与 vd-engine doctor 中 keepalive_running 同源的 KYA 标记）则复用、不重建 → 否则 spawn 建屏进程与 caffeinate 进程，并在异步尾段读回屏 id、再 list 交叉核验。
停止（dispose）¶
仅对本插件 spawn 的 vd-engine 建屏子进程与 caffeinate 发 SIGTERM；3 秒未退出再 SIGKILL。不由本插件 dispose 的外部 vd-engine 或他人持有的 kya 屏一律不碰。
若引擎子进程意外退出，插件会打显著日志并按退避策略自动重启（1 秒起、每次翻倍、上限 30 秒）；caffeinate 断言单独保留。宿主控制台日志统一带前缀 [clamawake]。
环境变量¶
| 变量 | 含义 | 默认 |
|---|---|---|
CLAMAWAKE_ENGINE |
vd-engine 绝对路径（解析链第一优先） |
未设置 |
CLAMAWAKE_REUSE |
设为 0 / false / no 强制走新建虚拟屏路径（测试用；生产勿设） |
开启复用 |
无 Config 导出 UI，与 README「已知边界」一致，配置仅通过环境变量。
引擎路径解析顺序¶
CLAMAWAKE_ENGINE<插件目录>/bin/vd-engine（主路径，随包分发）- 已安装
ClamAwake.app内 Resources 等兜底路径（开发便利，非必需）
安装与启用¶
README 记载两种等价装载方式（须为 profile 下实体目录并完成双登记；手工符号链接会导致宿主 import 失败）。
经插件管理器（推荐）：
plugin_manager(action=install_bundle, target=<本插件目录绝对路径>)
装成的是 profile 下指向该目录的 link，改代码后重新启用插件即可生效，无需整包拷贝。
文件级：
- 将本目录放到
~/.dsh/profiles/<profile>/node_modules/dsh-clamawake/ - 在该 profile 的
package.json中同时登记dependencies与dsh.profile.bundles
完成装载后重启 DSH（插件在应用启动时加载）。若已装好仅改 index.js，可通过 set_plugin 关→开让宿主重新读模块，无需全量重启。
验证：
- 宿主控制台出现
[clamawake]启动日志（复用或建屏且核验通过） vd-engine list中可见kya=yes屏（若此前没有）- 退出 DSH 后该屏消失，本插件挂的
caffeinate释放
移除：remove_bundle，或文件级删除后重启。更新插件代码后需按上述流程重装/重载并重启。
package.json 的 dsh 段仅有 bundle.patch（指向 cordis.patch.yml，往宿主 bundle 插入 dsh-clamawake），无 dsh.client（无 Web 客户端模块）。
本地自测（不经宿主）¶
在插件目录执行：
node test-lifecycle.mjs
脚本模拟 cordis 的 effect(setup) 协议：阶段 A（CLAMAWAKE_REUSE=0）走建屏→dispose→屏消失；阶段 B（默认）走复用→dispose 不动外部屏；终态屏集合与测试前一致。全程只 SIGTERM 自己 spawn 的子进程。
发布前如需重编包内引擎（禁止手工拷贝）：
scripts/build-engine.sh # 从兄弟仓 ../ClamAwake 源码编译
scripts/build-engine.sh --copy # 从已安装的 ClamAwake.app 复制
适用场景与注意¶
适合：在 Apple Silicon Mac 上长期用 DSH 跑智能体或自动化，希望合盖不睡、且保活与 DSH 同开同关；可与已运行的 ClamAwake 或外部 kya 屏共存（复用模式不抢外部屏）。
注意：
- 插件以当前 DSH 进程权限运行，安装前应阅读
index.js与许可证：插件 JS 为 MIT（LICENSE），bin/vd-engine为 GPL-3.0（见NOTICE与 ClamAwake 源码仓）。 - 正常退出会走 dispose；若宿主被
kill -9强杀，dispose 不执行，vd-engine / caffeinate 可能成为孤儿进程继续保活，需手动结束（下次启动插件可按 kya 标记复用该屏）。 - 当前包版本为 0.1.0（见
package.json）。
结尾¶
dsh-clamawake 把 ClamAwake 合盖保活配方收到 DSH 宿主生命周期里：自包含引擎、可复用已有 kya 屏、dispose 边界清晰，适合不想单独开菜单栏应用、又要在合盖时稳住 DSH 的场景。
