d86e/dsh-doctor

dsh-doctor

CI
License: MIT
Node
DSH

面向 DeepSeek Harness web profile 的自愈看门狗。可在 60 秒的停机预算内从插件引发的启动失败中恢复。通过官方 tools/ 事件钩子捕获每一次工具错误。监视每一个活动会话，并将卡住的回合重新唤醒。（面向已损坏安装的 dsh doctor CLI 子命令计划在 v0.3.0 中推出。）

dsh-doctor 作为独立的 Node 进程运行（macOS 上为 LaunchAgent，Linux 上为 systemd 用户单元，Windows 上为任务计划程序），因此即使 dsh web 无法派生子进程，它也能存活。它完全独立于 dsh-daemon：不调用它、不依赖它，也不与它冲突。如果两者都已安装，你将获得分层保护。

目录

- 它做什么
- 何时使用它
- 安装
- 用法
- 架构
- 配置
- 工具
- 工具错误处理
- 会话监视
- 安全保证
- 故障排除
- 路线图
- 开发
- 贡献
- 安全
- 许可证

它做什么

一个插件，四项职责：

| 职责 | 运行位置 | 时间预算 | 触发条件 |
| --- | --- | --- | --- |
| 1. Web 启动恢复 | 独立 Node 进程（LaunchAgent / systemd / 任务计划程序） | 每次事件 60 秒 | dsh web 健康探测连续失败 N 次 |
| 2. CLI doctor | _（计划在 v0.3.0 中推出）_ | — | — |
| 3. 工具错误捕获 | 进程内，挂接到 tools/ cordis 事件瀑布流 | 被动——从不阻塞宿主 | 任意会话中的任意工具调用失败 |
| 4. 活动会话监视 | 进程内，挂接到 session/event | 每 30 秒滴答一次，不丢失事件 | 某个回合处于 running 状态，且 watchIdleThresholdMs（默认 3 分钟）内没有新事件 |

1. Web 启动恢复（60 秒预算）

看门狗每 30 秒探测一次 http://127.0.0.1:$DSH_WEB_PORT/health。连续 3 次失败后，它进入分诊状态机，每次事件的总停机时间硬性上限为 60 秒。

简单路径（约 10 秒）——最常见的情况，单个插件损坏：

1. 读取 dsh web 日志的最后 200 行。
2. 针对正则模式表运行分诊（EADDRINUSE、重复的 loader 条目、schema 解析错误、模块未找到、插件加载错误……）。
3. 如果确定了失败的 bundle，在 ~/.dsh/profiles/web/cordis.patch.yml 中禁用那一行（将更改写入同级的 cordis.patch.yml.dr-disabled- 文件——你的原始文件永远不会被编辑）。
4. 重启 dsh web。启动成功，因为出问题的 bundle 已经不存在了。

复杂路径（≤60 秒）——多个 bundle、简单路径无效，或者失败原因未知：

1. 向 profile 中放入一个安全模式补丁，用空操作配置（safeMode: true）覆盖每一个 bundle，但显式允许列表（safeModeBundles，默认 ["dsh-core"]）除外。
2. 重启 dsh web。profile 以安全模式启动——你所有的 dsh_doctor_* 工具仍然可用，其他所有插件都被静默。
3. 写入一个 restart-lock 标记，这样并行运行的 dsh doctor 调用可以跳过 60 秒预算，不受限制地工作，直到安全模式解除。

每次恢复都强制执行的不可变规则：

- 看门狗只会杀死它从 ~/.dsh/profiles/web/.dsh-web.pid 读取到的 PID。它从不调用 pkill、killall 或任何按模式杀进程的工具。进程内 doctor 在 apply() 时用 process.pid 写入该文件（它运行在 dsh web 内部，所以那个 pid 就是 web 的 pid）；过期的 pid 会被读作已经死亡的情况，这正是 kill 分支存在的原因。
- 同级文件模式意味着你真正的 cordis.patch.yml 永远不会被悄悄修改。可以随时检查/还原。
- 如果 60 秒过去仍没有健康探测，看门狗会退避，并在下一个探测 tick 重试，而不是反复折腾。

2. CLI doctor（计划于 v0.3.0 推出）

⚠️ 尚未发布。 未来的版本将添加一个 dsh doctor 子命令，
它会在前台运行相同的分诊 + 恢复引擎，且没有
时间预算，面向那些 dsh web 坏到根本无法启动的用户。
目前，唯一的恢复路径是进程内插件 +
独立看门狗（上面的任务 1 + 3 + 4）。

在那之前，恢复一个完全死掉的安装的推荐方式是：
让任何可用的 dsh agent 调用 dsh_doctor_diagnose 来识别
失败的 bundle，然后手动在
~/.dsh/profiles/web/cordis.patch.yml 中禁用那个 bundle，并重启 dsh web。

跟踪进度：

3. 工具错误捕获

dsh 中的每次工具调用都会经过一个 tools/ cordis 事件瀑布流。dsh-doctor 订阅 tools/execute 和 tools/post-execute，并将每个失败结果通过一个分类器（默认：transient / agent / business）和一个策略（默认：记录 + 日志，可选延迟）处理。doctor 从不修改瀑布流本身——它只观察。

第 9 个面向模型的工具 dsh_doctor_drain_deferred(sessionId) 让 agent 在当前回合的安静时刻拉取排队的错误，并决定如何处理。

4. 实时会话监视

dsh 进程中的每个会话都会发出 session/event（turn/start、turn/end、tool/call、tool/result、user/message、assistant/message……）。dsh-doctor 为每个会话维护一个状态机：

┌──────────────┐
│  事件触发    │ ◀── 每个会话事件
└──────┬───────┘
│
┌──────▼───────┐
│  重置空闲    │
│   计数器     │
└──────┬───────┘
│
(每隔 watchTickIntervalMs)
│
┌──────▼───────────────────┐
│ 轮次正在运行吗？         │
│ 无事件时间 > N 吗？      │
│ 冷却时间已过吗？         │
│ nudgesSent  dsh_doctor_status
{
"installed": true,
"running": true,
"pid": 25632,
"platform": "darwin",
...
}

选择退出自动安装

在 cordis.patch.yml 中设置 autoInstall: false：
yaml
- insert:
- id: dsh-doctor
name: '@d86e/dsh-doctor'
config:
autoInstall: false

或设置环境变量 DSH_DOCTOR_AUTO_INSTALL=0。然后你可以通过
面向模型的 dsh_doctor_install 工具手动安装 watchdog：
text
dsh_doctor_install

dsh_doctor_install 支持 dryRun: true 来预览写入内容而不
实际注册服务，并在 dsh_doctor_uninstall 中支持 purgeLogs: true 标志
以同时删除 ~/.dsh/doctor/logs/。

选项 B —— npm 包

如果你更喜欢 npm，同一份源码也发布为 @d86e/dsh-doctor：
bash
dsh plugin --profile web add @d86e/dsh-doctor

dsh plugin add 接受 git URL、/ 简写或 npm
包名 —— 它们最终都会落到同一个地方。

选项 C —— 动态（沙箱化的一次性使用）

适用于单次会话，无需安装。向任何 agent 请求：

Use the dsh doctor from https://raw.githubusercontent.com/d86e/dsh-doctor/v0.2.0/lib/index.js

然后在你准备好将其永久化时调用 dsh_doctor_install。

用法

安装后，你可以向 agent 请求：

dsh_doctor_status
dsh_doctor_diagnose
dsh_doctor_watch_list
dsh_doctor_safe_mode_enter
dsh_doctor_drain_deferred

从 shell 中：
bash
(Planned) dsh doctor                  # unbounded CLI doctor (foreground)
(Planned) dsh doctor --dry-run        # triage only, no writes

卸载：

dsh_doctor_uninstall

架构
完整的状态机、文件布局和进程间协议请参见 docs/ARCHITECTURE.md。

┌──────────────────────────────────────────────────────────────┐
│  dsh web 进程（cordis 组合行）                                │
│                                                              │
│   ┌────────────────────┐  ┌────────────────────┐            │
│   │ tools/ 事件钩子     │  │ session/事件钩子   │            │
│   └────────┬───────────┘  └─────────┬──────────┘            │
│            │                       │                         │
│            ▼                       ▼                         │
│   ┌──────────────────────────────────────────────┐          │
│   │  dsh-doctor（apply）                          │          │
│   │   ├ 工具错误捕获（waterfall 监听器）           │          │
│   │   ├ 会话监视（定时器 + ctx.agents）            │          │
│   │   └ 12 个 dsh_doctor_ 工具                   │          │
│   └──────────────────────────────────────────────┘          │
└──────────────────────────┬───────────────────────────────────┘
│ （文件系统状态）
▼
┌──────────────────────────────────────────────────┐
│  $DSH_HOME/doctor/                               │
│   ├ watchdog.js      独立无依赖脚本               │
│   ├ watchdog.pid     当前 watchdog 进程 ID        │
│   ├ installed-marker  插件版本标记                │
│   ├ stopped-marker   暂停标志                     │
│   ├ safe-mode.patch  自动生成的禁用配置           │
│   └ logs/                                        │
│     ├ watchdog.log   （5MB × 3 轮转）            │
│     ├ doctor.log     （5MB × 3 轮转）            │
│     └ tool-errors.log                          │
└──────────────────────────────────────────────────┘
▲
│ （HTTP /health 探测）
│
┌────────────────────────┴─────────────────────────┐
│  watchdog.js（LaunchAgent / systemd / 任务计划程序）│
│   - 30 秒健康探测                                 │
│   - 分诊 + 简单/复杂恢复                          │
│   - 不使用 pkill、不使用 killall、不进行远程拉取   │
└────────────────────────────────────────────────────┘

配置

所有可调项既可以在 cordis.patch.yml 中设置（位于 config: 下），也可以通过 DSH_DOCTOR_ 环境变量设置。

| 字段 | 环境变量 | 默认值 | 描述 |
| --- | --- | --- | --- |
| healthIntervalMs | DSH_DOCTOR_HEALTH_INTERVAL | 30000 | 健康探测周期 |
| healthFailuresToRecover | DSH_DOCTOR_HEALTH_FAILURES | 3 | 触发分诊前的失败次数 |
| recoveryBudgetMs | DSH_DOCTOR_BUDGET_MS | 60000 | 每次事件的硬性上限（watchdog） |
| logMaxBytes | — | 5242880 | 单个日志的轮转大小 |
| logBackups | — | 3 | 保留的轮转日志文件数 |
| safeModeBundles | — | ["dsh-core"] | 安全模式下保留的 bundle |
| toolErrorCapture | DSH_DOCTOR_TOOL_ERROR_CAPTURE | true | 订阅 tools/ |
| toolErrorMaxQueue | DSH_DOCTOR_TOOL_ERROR_QUEUE | 500 | 每会话队列上限 |
| watchEnabled | DSH_DOCTOR_WATCH_ENABLED | true | 会话监视总开关 |
| watchIdleThresholdMs | DSH_DOCTOR_WATCH_IDLE_MS | 600000 | 空闲超时（10 分钟） |
| watchNudgeCooldownMs | DSH_DOCTOR_WATCH_COOLDOWN_MS | 300000 | 两次提醒之间的最小间隔 |
| watchMaxNudgesPerSession | DSH_DOCTOR_WATCH_MAX_NUDGES | 3 | 放弃前的提醒次数上限 |
| watchContinueText | DSH_DOCTOR_WATCH_TEXT | "继续" | 要注入的文本（支持 {elapsed}、{turn}、{sessionId}） |
| watchTickIntervalMs | DSH_DOCTOR_WATCH_TICK_MS | 30000 | 空闲检查周期 |

工具错误分类器 — 替换它

如果默认分类（网络/5xx/429 → transient，401/403/quota/context-overflow → agent，否则 → business）不适合你的技术栈，可以在从包装器 bundle 注册插件时传入你自己的分类器 / 策略。这两个函数都会接收完整的 ToolErrorContext 并同步返回。

会话监视文本 — 本地化它

watchContinueText 接受占位符 {elapsed}（自上次事件以来的秒数）、{turn}（当前轮次编号）、{sessionId}。因此 "已经过去 {elapsed} 了，请继续第 {turn} 步" 是可行的。

工具

13 个面向模型的工具，全部以 dsh_doctor_* 为前缀。

| 工具 | 用途 |
| --- | --- |
| dsh_doctor_install | 生成独立看门狗和平台服务 |
| dsh_doctor_uninstall | 注销、删除状态文件（日志可选） |
| dsh_doctor_status | 已安装？运行中？运行时长？最近 5 次恢复？监视快照？ |
| dsh_doctor_pause | 停止恢复，继续探测 |
| dsh_doctor_resume | 重新启用恢复 |
| dsh_doctor_diagnose | 一次性诊断，不写入 |
| dsh_doctor_recent_log | 跟踪 doctor 管理的某个日志（web / watchdog / doctor / tool-errors）的末尾 |
| dsh_doctor_safe_mode_enter | 手动放置安全模式补丁 |
| dsh_doctor_safe_mode_exit | 移除安全模式补丁 |
| dsh_doctor_drain_deferred | 拉取某会话排队的 agent 类工具错误 |
| dsh_doctor_watch_list | 列出 doctor 正在跟踪的每个会话 |
| dsh_doctor_watch_nudge | 手动向某会话注入一条“继续”消息 |
| dsh_doctor_watch_cancel | 取消某会话的当前轮次（kind=user） |

工具错误处理

默认情况下，doctor 观察工具错误；它从不重试，也从不修改 waterfall。要改变这一点，installToolErrorCapture API 已导出，供包装器 bundle 使用：
ts
import { installToolErrorCapture, defaultClassify, defaultPolicy } from '@d86e/dsh-doctor/tool-errors'

installToolErrorCapture(ctx, config, log, {
// user classifier: nil-pointers count as agent-class
(ctx) => ctx.message.includes('panic') ? 'agent' : null,
}, defaultPolicy)

完整契约见 src/tool-errors.ts。

会话监视
医生在进程内维护一个按会话划分的状态机。对于模型和 agent 的工具调用而言，它是只读的——它唯一执行的操作是 agent.followup({content: [{type: 'text', text: '继续'}], source: {kind: 'user'}})。

针对过度触发的三重保护：

1. 冷却——对同一会话的两次提醒之间必须至少间隔 watchNudgeCooldownMs。
2. 上限——一个会话在其生命周期内被提醒 watchMaxNudgesPerSession 次后，将被搁置，直到下一次 turn/end:completed。
3. 用户覆盖——如果在候选提醒时间的 5 秒内到达了一条真实的 user/message（source.kind === 'user'），医生会退让，并假定由人类在主导。

如果 dsh 宿主未暴露 ctx.agents（即较旧版本的 dsh），该监视会静默降级。12 个工具仍然可用，看门狗仍然可用——只是进程内的提醒功能消失了。

安全保障

- 看门狗不进行网络调用（它仅探测 127.0.0.1）。
- 任何地方都不使用 pkill / killall。仅向已记录的 ~/.dsh/profiles/web/.dsh-web.pid 发送信号。
- 不会静默修改你的 cordis.patch.yml。禁用 / 安全模式操作会写入同级文件（cordis.patch.yml.dr-disabled-、cordis.patch.yml.dr-safemode）。
- 看门狗无依赖（仅使用 node:fs/path/os/http/child_process/crypto）。即使 dsh 无法启动自己的 node_modules，它也能运行。
- 无遥测、无分析、无回传。
- dsh_doctor_safe_mode_exit 是幂等的——运行两次是安全的。
- 提醒从不修改模型状态——它们仅通过 dsh-auto-continue 社区插件所使用的同一原语发送一条用户消息。

故障排查

参见 docs/TROUBLESHOOTING.md。

路线图

已完成：

- ✅ 0.2.0——带空闲检测 + 提醒 + 取消的实时会话监视。
- ✅ 0.1.0——Web 启动恢复、CLI 医生、工具错误捕获。

未来：

- 可选的浏览器通知桥接（面向运行 dsh Web UI 的用户）。
- 可插拔的分诊模式（从文件加载你自己的正则表达式表）。
- dsh_doctor_simulate——针对测试配置文件端到端运行一次模拟故障，以验证看门狗。

开发
bash
git clone https://github.com/d86e/dsh-doctor
cd dsh-doctor
pnpm install
pnpm test          # 83 unit tests
pnpm run build     # tsc → lib/
pnpm run typecheck

tests/dsh-smoke.sh 是一个仅用 shell 的冒烟测试，它会构建 → 打包 → 执行 dsh plugin add。它在 CI 中被跳过，因为 CI 主机未安装 dsh。

贡献

参见 CONTRIBUTING.md。

安全

参见 SECURITY.md。请通过 GitHub Security 选项卡报告漏洞——不要提交公开 issue。

许可证

MIT——2026 Tommy (d86e)。