dsh-keepalive

English | 中文

状态：功能插件（含兼容补丁），仅在 DeepSeek Harness 0.1.0-rc.6 上测试过。

dsh-keepalive 为 DSH Web 进程运行一个分离的看门狗。显式启用后，看门狗会在进程退出后把 DSH 重新拉起来。可选的修复代理会检查反复出现的启动失败、修改插件工作区，并从快照重试。

问题

进程一旦退出，Web 自己无法重启。DSH 内置了流空闲看门狗和浏览器重连退避，但这些机制都不负责监督宿主进程。

行为

• 为看门狗配置添加一张 Plugins 设置卡片。
• 仅当 enabled 为 true 时启动分离的 Node 看门狗。
• 检查进程健康状态，用相同的 DSH 二进制和参数重新拉起。
• 手动重启：设置卡片「手动重启」按钮（或 POST /api/keepalive/restart）——当前进程退出后由看门狗拉起；看门狗未运行时由兜底重启器（restarter.mjs）以相同命令拉起。
• 为设置命名空间和 Windows 隐藏子进程应用守卫式兼容补丁。
• 启动反复失败后，可选地运行修复代理。
• 对允许修复的工作区做快照，校验结果路径/配置/语法，失败的修复回滚。
• 修复范围扩展：对 web profile 中 link:/file:（目录）依赖指向的开发目录，修复代理可在其 node_modules 下新增 junction 补齐依赖解析；新增链接被快照追踪、失败回滚时移除，现有条目与源码/配置一律不动。
• 修复进度页：web 启动失败进入修复时，看门狗在 web 端口（默认 3080）上提供零依赖状态页——显示"启动发生错误，正在修复"、修复代理实时进度与已用时间；修复成功后页面自动跳回 web 界面，失败则显示修复代理的结论。
• 修复代理可对【本次报错插件所属的 link 目标开发目录】内的源码做最小修复（如补变量声明、修正 import、修复语法），该目录被内容快照覆盖、失败回滚；禁止删除文件。
• 修复代理的工作区根自动取所有用户 link 目标开发目录的公共父目录（如 D:\Code），官方 @deepseek-ai/* 的 link 包被排除、不可写；沙箱写入由快照审计兜底。
• 前端插件失败上报：web 存活但某个 client 插件模块加载失败时上报（仅限浏览器对动态 import() 失败的明确包装消息，如 "Failed to fetch dynamically imported module"；不监听 window error、不使用 slots.onEntryError——普通脚本错误与 entry 渲染崩溃（如 React #130）都不是插件模块故障，误报只会骚扰正常使用），看门狗触发"降级修复"（跳过 live 目录快照，修复后自动重启 web 重载插件；若修复代理未做任何改动则不重启，直接清除上报）。
• 全局修复进度浮层：任何页面右下角实时显示"正在修复：阶段 + agent 进度行"；仅在 status=repairing 时展示，修复结束自动消失，失败显示原因。

enabled 和 autoRepair 都需要显式选择启用；自动修复默认 false。

非目标

本包不是高可用集群、服务管理器、沙箱、恶意软件边界或秘密清洗器，也不保证失败的 DSH 实例能被自动修复。它替代不了 systemd、Windows 服务控制管理器、容器或外部监控。

兼容补丁

本插件精确针对：

• @deepseek-ai/dsh-host-apiproxy@0.1.0-rc.6：允许 Web 设置 API 使用 keepalive 设置命名空间。
• @deepseek-ai/dsh-subprocess-local@0.1.0-rc.6：Windows 上本地工具子进程使用 windowsHide: true。

版本策略默认自适应：如果已安装副本的版本不是 0.1.0-rc.6，但每个锚点仍然唯一匹配，就照常打补丁（记为 adaptive 匹配）；锚点漂移则跳过并说明原因。编程选项 strict 可恢复"只打精确版本"的旧行为。单个漂移副本不会阻塞另一个目标，补丁应用在 host 或看门狗启动期间也绝不会抛错。设置命名空间这一行插在允许列表数组的顶部，避免占用与 dsh-tavily-search-provider 共享的尾部锚点——两个插件无论按什么顺序安装都能共存。还原（卸载）在任何模式下都严格校验版本。写入走临时文件加重命名的原子写入，替换后校验语法，校验失败则恢复原有字节。

兼容性

需要 DeepSeek Harness 0.1.0-rc.6、Node.js ^22.19.0 || >=24、pnpm >=10。看门狗针对当前 DSH CLI 的布局设计，已在 Windows 上测试。

安装

dsh plugin --profile web add "github:xiaohj233/dsh-keepalive#v0.1.0"

重启 Web profile。只安装并不会启用看门狗重启或修复。

配置

通过 Plugins 卡片或设置文件配置 keepalive 设置区块：

keepalive:
  enabled: false
  autoRepair: false
  checkIntervalMs: 3000
  bootWaitMs: 15000
  repairProvider: ""
  repairModel: ""

provider、model、base URL、API 名称和凭据引用都以单行 YAML 安全字符串序列化。所选模型和凭据路径验证过之前，先保持修复禁用。

还原与卸载

从 profile 移除插件之前，先运行本包的卸载命令：

pnpm --dir "$DSH_HOME/profiles/web" exec dsh-keepalive-uninstall
dsh plugin --profile web remove dsh-keepalive

未设置 $DSH_HOME 时，profile 位于用户主目录下（POSIX 为 ~/.dsh/profiles/web，Windows PowerShell 为 %USERPROFILE%\.dsh\profiles\web）；Windows 上请把解析后的路径传给 pnpm --dir，不要用 ~。

命令会禁用 keepalive 状态、只终止记录的看门狗进程，并还原两个被打补丁的官方文件；任一步骤不完整都以非零状态退出。正常的 Web 关闭不会撤销补丁——关闭恰恰是看门狗要监督的事件。

安全

修复代理把启动诊断作为 prompt 输入接收。这些诊断不可信，可能夹带误导性的指令。修复运行时使用 workspace-write，继承启动进程可见的环境信息，可以修改插件工作区——这不是完整的隔离或保密边界。快照、路径、语法和回滚检查能减少意外损坏，但并不能让任意的 agent 输出变得安全。

每次修复后都要审查改动。不要在包含修复进程不该读取的凭据的机器或插件目录上启用修复。

其他已知限制：

• 看门狗监督和卸载只凭记录的 PID 识别看门狗。看门狗死后若该 PID 被无关进程复用，监督会静默失效，dsh-keepalive-uninstall 还可能终止那个无关进程。卸载前先确认看门狗是否在运行。
• 连续多次轮询无响应后，看门狗会强制终止监听所配置端口的任何进程（也就是预期的重启目标）；恰好占着该端口的无关服务也会被一并杀掉。
• 启动失败的诊断和最近一次修复代理的输出（上限 4 KB）会持久化在 keepalive 状态里，同源或受信任的页面可以从 /api/keepalive/status 读取。启动失败日志可能夹带环境中的秘密。
• 快照/差异/回滚层追踪 link 目标 node_modules 的顶层条目：修复代理在那里新增的 junction 会被发现并在回滚时移除；但普通插件工作区仍只遍历普通文件和目录，仍建议保持工作区无链接。
• Host 与看门狗都会重写 keepalive.json；并发写入可能暂时丢掉一次更新（下一次写入会自行纠正）。

测试

npm test
npm run check:syntax
npm pack --dry-run

测试覆盖：默认值、YAML 注入与往返、补丁/还原的精确行为、歧义锚点、语法回滚、快照、一次真实的分离进程卸载、看门狗启动，以及 --unpatch 参数约定。

局限性与上游现状

DSH 社区已有重启/自愈类插件，上游也可能推出官方的 keepalive 实现。本包只做一个对 Windows 友好的分离式看门狗，外加可选启用、带快照校验的修复。它无法从操作系统关机、账户注销、Node/DSH 二进制不可用或主机级资源耗尽中恢复。

License

MIT。补丁目标均为 MIT 许可，详见 THIRD_PARTY_NOTICES.md。