dsh-restart-guard
适用于 DeepSeek Harness web 的看门狗插件：独立于宿主进程运行，检测重启和升级失败，修复可修复的问题，并通过 IM、webhooks 或日志进行报告。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-restart-guard@0.1.6Restart Guard 以 dsh-restart-guard 发布，当前版本为 0.1.6。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English · 简体中文
为 DeepSeek Harness 的 Web 服务加一个能在宿主进程死掉后继续存活的守护进程：发现重启没起来，按一组小规则判断原因，能修的自己修，修不了就把过程和结论发到你指定的渠道（IM、Webhook、命令或本地日志）。
它解决的问题很具体：容器/脚本里 dsh web 是后台启动、启动器随后 exec 成代理，没有任何 supervisor 会在插件加载失败、patch 写坏、端口被占时把服务拉起来。页面 502 到有人发现为止，中间没有任何信息。
DSH 宿主 (dsh web) 独立 watcher
┌───────────────────────┐ spawn ┌──────────────────────────────┐
│ 插件：体检 / 路由 / │ ─────────► │ 每 2s 探测 127.0.0.1:<port>/ │
│ 设置页 │ │ 字节偏移确认就绪 → 诊断 → 修复 │
│ │ ◄───────── │ → 通知 │
└───────────────────────┘ state.json└──────────────────────────────┘
│ 崩溃 / 被杀 │
▼ ▼
端口消失 ─────────────────────────► 重启 / 回滚 patch / 停下并告警
kill -9 DSH 不会带走它。401 且正文是 DSH 的鉴权文案，或 200 且含 __DSH_BOOT__ 才算 DSH；普通的 200 HTML 是陌生监听者，既不算健康，也绝不会被当成 DSH 杀掉。dsh web: 访问行，再 settle 复验。整文件 grep 会命中旧行、拿到旧 token，这里刻意不做。cordis.patch.yml 回滚到能通过 --dump-config 的最新备份；或者停下并把证据交给人。每个事件最多启动 2 次；10 分钟 3 次崩溃进入 30 分钟暂停，避免重启风暴。<pkgRoot>.prev-* 等兄弟目录、包管理器进程、$DSH_HOME/upgrade 最新目录、慢启动六路信号任一命中即进入维护态：不启动、不回滚、不杀进程。exit(0) 被当作“操作者有意停的”，不拉起。dsh-im 插件（宿主不在线时先落盘，回来后补发）。设置页点“扫描 dsh-im”可直接从已装插件里列出 bot 与 target，不用手抄 ID。# 1. 本地目录或 npm 包
cd /path/to/dsh-restart-guard
pnpm install --ignore-scripts
# 2. 链接进 profile（会备份 package.json 并跑 pnpm install）
npx dsh-restart-guard install --profile web
# 或：dsh plugin --profile web add dsh-restart-guard
# 然后手动把 "dsh-restart-guard" 加进 profiles/web/package.json 的 dsh.profile.bundles
# 3. 重启 DSH，让插件加载（watcher 随宿主启动）
重启后打开 设置 → 重启守护：顶部体检报告会列出还缺什么（Webhook 地址、IM 的 botId/targetId、启动日志路径……），在页面里补完，点 测试通知。
命令行核对：
dsh-restart-guard status # watcher / 阶段 / 最近健康状态
dsh-restart-guard doctor # 与设置页同一套体检
dsh-restart-guard logs -f # 跟随守护日志
| 项 | 要求 |
|---|---|
| Node | ≥ 22 |
| DSH | ≥ 0.2.1（用到 host 插件 API 与 webServer.tapIndex） |
| 系统 | Linux 完整支持（依赖 /proc）；macOS 可用探测与监督逻辑，进程/端口映射回退到 lsof |
| 运行时依赖 | 无 |
照常升级即可。升级脚本通常会杀掉旧进程、换树、再拉起；watcher 能从换树/兄弟目录/升级目录/包管理器进程/restarter 进程识别出“这是维护”，只观察、不抢端口、不中途回滚文件。维护窗口是锚定的：同一信号沿用原截止时间，不会因为进程还在而每 2 秒往后顺延；每个窗口只通知一次（信号变化才再发），显式窗口（maintenance start --minutes N）严格按 N 分钟结束、不额外加 graceMs。
探测失败 → 宽限 → 诊断 → 计划：
| 诊断（先匹配者优先） | 日志示例 | 动作 |
|---|---|---|
yaml-config | YAMLException、bad indentation | 回滚到最新可用备份，再启动 |
patch-incompatible | cannot get property "webRuntime" without inject | 首次回滚，之后仅重启 |
wildcard-host | host "0.0.0.0" is an unspecified (wildcard) address | 停下，需改配置 |
port-in-use | EADDRINUSE | 端口被占：停下（开启 killStaleDshHolder 时只清理旧 DSH） |
module-missing | Cannot find module | 停下，依赖缺失 |
permission-disk-memory | EACCES、ENOSPC、ENOMEM | 停下，环境问题 |
crash | Segmentation fault、Killed | 重启 |
startup-failed / plugin-failed | entries did not activate、failed to apply loader entry | 重启 |
stalled | 进程在、端口静默超过 stalledExitMs | 杀掉僵死进程再启动 |
timeout | 超时未就绪 | 重启 |
unknown | 其它 | 重启 |
每个事件都会写 incidents/*.json、ALERT.md、一行日志，并按配置发通知。不自动修复的情形：非 DSH 进程占着端口、维护窗口内、包树不完整、通配地址绑定、缺模块、权限/磁盘问题、以及开启尊重主动停止时的 exit(0)。
开启后守护多一档修复手段，分两种模式：
cordis.patch.yml 及最近备份、启动日志路径与大小、端口监听者、诊断与证据、/proc 抓到的启动命令），再附上脱敏后的日志尾部；AI 可以读文件、改配置、补依赖、回滚 patch、重启服务，随后守护复验端口。先试 dsh 本体（dsh --profile <p> headless "<prompt>"，继承 DSH 自己的模型凭据与工具权限），再试插件直连（HTTP / 桥接）；两者都不行才回退到原来的规则阶梯（重启 → 回滚 → 人工）。retry/rollback-patch/wait/manual），映射到已有白名单动作；模型输出永远不会被当作命令执行。安全边界：维护窗口、包树不完整、有真正的监督者（systemd/pm2）时 AI 也不会动手；发送的日志已脱敏，环境变量只发键名，密钥与访问令牌不外发；不开启就没有任何外发。硬停与“非 DSH 进程占端口”同样不会被覆盖。
在 设置 → 重启守护 → AI 修复 里开启，选择模式与尝试顺序（dsh-agent-first / direct-first / dsh-agent-only / direct-only），再配服务商与密钥来源。密钥默认直接借用 DSH 自己的：读 $DSH_HOME/.credentials.yaml 的 refs: 块（DEEPSEEK_API_KEY、XIAOMI_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY），所以即使 dsh web 本身起不来，AI 修复仍然可用；也可改成只读环境变量（ai.credentialSource: "env"）、只读 DSH 凭据库（"dsh"）或指定凭据名（ai.keyRef）。密钥只读、不写配置、不落日志。
ai.dshAgent 控制“dsh 本体”通道（command 默认 dsh、args 默认 ["headless"]、timeoutMs 默认 300000）。不想让守护直接连 API 时开桥接（ai.bridge）：提示词写程序 stdin、判定从 stdout 读。点 测试 AI 验证链路，命令行等价命令 dsh-restart-guard ai-test。
全局文件：$DSH_HOME/restart-guard/config.json（0600）。设置页可改，watcher 自动重载。
{
"enabled": true,
"locale": "auto",
"watchdog": {
"probeIntervalMs": 2000,
"probeTimeoutMs": 3000,
"startupGraceMs": 30000,
"bootTimeoutMs": 120000,
"settleMs": 5000,
"stalledExitMs": 20000,
"maxRestartAttempts": 2,
"rollbackProfilePatch": true,
"killStaleDshHolder": false,
"respectIntentionalStop": true,
"crashLoop": { "windowMs": 600000, "maxIncidents": 3, "pauseMs": 1800000 }
},
"maintenance": { "autoDetect": true, "graceMs": 900000, "lookbackMs": 1800000 },
"logs": { "bootLogPath": "", "mirrorToHostLog": true },
"ai": {
"enabled": false, "preset": "deepseek", "endpoint": "", "model": "",
"keyEnv": "DEEPSEEK_API_KEY", "keyRef": "", "credentialSource": "auto",
"bridge": { "enabled": false, "program": "", "args": [] }
},
"notify": {
"webhook": { "enabled": false, "preset": "generic", "url": "" },
"command": { "enabled": false, "program": "", "args": [] },
"im": { "enabled": false, "botId": "", "targetId": "", "format": "markdown" }
},
"supervision": { "mode": "auto" },
"security": { "allowRemoteMutations": false, "dangerousActions": false }
}
bootLogPath 通常不需要：宿主健康时守护会从 /proc/<pid>/fd/1 抓真实 stdout。若启动器把 stdout 接成管道，再手动指定。
logs.mirrorToHostLog（默认 true）：守护把自己的日志行以 [dsh-restart-guard] 前缀追加进宿主的 stdout（即 bootLogPath 或抓到的 stdout 文件），所以容器部署时 docker logs <container> 里能直接看到“谁在修、修到哪一步”，不必再进容器翻 $DSH_HOME/restart-guard/。它只写这一行前缀，不会伪造 DSH 自己的访问行，就绪判定不受影响。
supervision.mode 决定“谁负责重启”：auto（默认）识别 systemd、pm2、supervisord 和容器；none 表示没有别的程序会重启 DSH，让守护照常动手（适合 CI，或 PID 1 是 systemd 但平台并不会重启服务的容器）；supervised 表示只报告、不动手，用于检测不到真正归属者的场景。
$DSH_HOME/restart-guard/ 必须能跨重启保留。| 渠道 | 配置 | 说明 |
|---|---|---|
| 日志 | 恒开 | .../instances/<profile>-<port>/restart-guard.log，5 MB 轮转、保留 2 份 |
| Webhook | notify.webhook 或 DSH_RESTART_GUARD_WEBHOOK_URL | 预设：feishu、wecom、dingtalk、slack、telegram、discord、ntfy、healthchecks、generic |
| 命令 | notify.command | argv 直传（不经过 shell），消息写 stdin |
| IM | notify.im 或环境变量 | 需要 dsh-im 插件；发不出去先落 outbox，宿主回来后补发 |
消息按事件节流（60 秒），默认附 40 行日志尾部，token/cookie 已脱敏；除非显式开启，不含启动 token 与访问地址。
dsh-restart-guard status [--json] watcher/阶段/健康摘要
dsh-restart-guard doctor 环境体检 + 提示
dsh-restart-guard logs [-f] [-n N] 守护日志
dsh-restart-guard incidents 最近事件
dsh-restart-guard outbox 待补发的 IM 消息
dsh-restart-guard restart|start|rollback|simulate-crash
dsh-restart-guard pause --minutes 30 暂停自动修复
dsh-restart-guard resume
dsh-restart-guard maintenance start|end [--minutes 60] [--reason upgrade]
dsh-restart-guard notify-test 发测试消息
dsh-restart-guard ai-test 征询一次 AI 判定（不执行动作）
dsh-restart-guard reload 重载配置
dsh-restart-guard install|uninstall [--profile web] [--dry-run]
dsh-restart-guard purge 清空全部守护状态
CLI 通过控制文件与 watcher 通信（不需要页面 token）；动作需要存活 watcher，否则退出码 3。
security.allowRemoteMutations）。$DSH_HOME/restart-guard/：目录 0700、配置与计划 0600；写入不跟随符号链接。细节见 SECURITY.md、PRIVACY.md。
| 现象 | 检查 |
|---|---|
| 没有 watcher | dsh-restart-guard status；宿主启动后 10 秒内会拉起，插件日志里有 watcher-spawn |
| 端口起来了但守护没反应 | 体检里的 boot-log：没抓到 stdout 时仍能靠 HTTP 判定，但无法确认新 token |
| 不重启 | 状态是 maintenance/supervised：升级期和 systemd 下这是预期行为 |
| 反复重启 | state 文件里有诊断；修好后 resume |
| IM 没动静 | 先从 设置 → IM Bot 复制 botId/targetId，用“测试通知”验证 |
QQ 机器人只暴露
Bot ID：targetId可以留空，守护会在该 bot 只有一个投递目标时自动使用它；还没有目标时，先和机器人私聊一次（或拉进群），再到 dsh-im 里“新建目标”，然后回到设置页重新扫描。
pnpm install --ignore-scripts
pnpm run typecheck # tsc --noEmit，无构建步骤
pnpm test # node:test，含针对假 dsh 的 e2e
pnpm run build:client # 由 src/client.jsx 重新生成 lib/client.js
node scripts/build-client.mjs --check # CI：bundle 已提交且是最新
架构与不变量见 docs/ARCHITECTURE.md。
MIT，见 LICENSE。