前言¶

在 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 应用侧同一套两件套：

1. 虚拟屏：子进程执行 vd-engine create 1800 1169 --hidpi --hold --mirror-main。虚拟屏生命周期绑在持有进程上；对子进程发 SIGTERM 后引擎退出，屏随之消失。--mirror-main 表示每次宿主启动都会新建屏并镜像主屏，合盖后由镜像接管，而不是纯扩展屏。
2. 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]。

环境变量¶

无 Config 导出 UI，与 README「已知边界」一致，配置仅通过环境变量。

引擎路径解析顺序¶

1. CLAMAWAKE_ENGINE
2. <插件目录>/bin/vd-engine（主路径，随包分发）
3. 已安装 ClamAwake.app 内 Resources 等兜底路径（开发便利，非必需）

安装与启用¶

README 记载两种等价装载方式（须为 profile 下实体目录并完成双登记；手工符号链接会导致宿主 import 失败）。

经插件管理器（推荐）：

plugin_manager(action=install_bundle, target=<本插件目录绝对路径>)

装成的是 profile 下指向该目录的 link，改代码后重新启用插件即可生效，无需整包拷贝。

文件级：

1. 将本目录放到 ~/.dsh/profiles/<profile>/node_modules/dsh-clamawake/
2. 在该 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 的场景。

• 社区目录：https://www.skillhub.cn/plugins/zhangweijian97/dsh-clamawake
• 源码与完整说明：https://github.com/zhangweijian97/dsh-clamawake