前言¶
用 DeepSeek Harness（DSH）折腾插件久了，难免遇到这种情况：DSH 崩溃、启动失败，或者某个插件把 profile 改坏了。DSH 没有内置 doctor 命令，多数时候只能对着报错猜原因，靠重启进程碰运气，或者手动翻配置文件排查。
下面介绍的 dsh-doctor 就是针对这个问题：先只读诊断，告诉你哪里坏了、为什么；再分级修复，每一步改动都可逆；改坏了还能一键回滚。
这是什么¶
dsh-doctor（@jorinyang/dsh-doctor，当前版本 0.3.2）是 jorinyang 维护的 DSH 插件，定位是「诊断 + 修复 + 回滚」一体化工具，同时也是一个运行时自愈服务。它采用 MIT 许可证，是独立插件加独立 CLI，不修改 DSH 核心，与 DSH 自带命令不冲突。
核心功能¶
只读诊断¶
提供 dsh_doctor 工具和 dsh-doctor CLI 两种形态，做只读检查，覆盖 9 大类，报告哪里坏了、为什么，不会改动任何文件。
分级修复¶
对应工具是 dsh_doctor_fix，命令行是 dsh-doctor fix。修复分三档范围：
| 范围 | 动作 | 风险 |
|---|---|---|
safe（默认） |
创建缺失目录/文件、修复 allowBuilds 占位符 | 低，仅涉及文件/配置 |
deps |
safe 全部 + pnpm install --fix-lockfile |
中，涉及网络与依赖 |
full |
deps 全部 + 停止残留进程（健康时跳过） | 较高，涉及进程终止 |
每次修复都会生成一个 journal，记录每个改动的 undo 步骤。具体来说：覆盖的文件会保存原始内容，回滚时恢复；新建的文件/目录回滚时删除（仅空目录）；系统边界操作（如 pnpm install、杀进程）会标记「需手动补偿」。
回滚¶
对应工具是 dsh_doctor_rollback，命令行是 dsh-doctor rollback。回滚按 LIFO 逆序执行，恢复到修复前。rollback --list 可以列出所有修复日志，rollback --id <id> 可以回滚指定的一条。
运行时自愈服务¶
除了离线 CLI，dsh-doctor 还以 Cordis 服务的形态接入运行中的 DSH：
- 通过
ctx.provide暴露诊断/修复/回滚 API 给其他插件（服务名dsh-doctor）； - 通过
ctx.on('internal/status')响应式监控插件生命周期，检测到 FAILED 自动告警； - 通过
ctx.effect()声明可逆效应，卸载无残留。
也就是说，DSH 存活时它能动态诊断和监控，而不是只能停机修。
自包含 CLI 与跨平台¶
dsh-doctor 是自包含 CLI，不依赖 DSH 运行。即使 DSH 崩溃到插件都加载不了，也能直接执行 dsh-doctor fix。支持 Windows / macOS / Linux / fish，安装后自动注册到系统 PATH，也可用 dsh-doctor setup 手动注册。
安装与启用¶
方式一，作为 DSH 插件安装，在 Agent 内使用：
dsh plugin --profile web add @jorinyang/dsh-doctor
dsh web
第一条命令从 npm 安装插件，第二条重启 dsh web 使其生效。
方式二，全局安装 CLI，在命令行直接使用：
npm install -g @jorinyang/dsh-doctor
# 或者免安装直接运行
npx @jorinyang/dsh-doctor
插件的 peerDependencies 为 @deepseek-ai/cordis ^4.0.1-rc.1、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery ^3.18.1-rc.1。
典型用法¶
最基础的流程是先诊断、再修复：
dsh-doctor # 只读诊断（默认行为，别名 diagnose / check）
dsh-doctor fix # 修复（别名 repair）
诊断输出长这样（示例来自项目 README）：
DSH Diagnostic Report (profile: web, port: 3080)
DSH home: ~/.dsh
[OK] Node.js v24.15.0
[OK] pnpm 11.9.0
[OK] DSH 0.1.0-rc.6
...
[XX] bundle missing: some-broken-plugin
fix: Run pnpm install in profile dir
48 pass 0 fail 3 warn
回滚相关：
dsh-doctor rollback # 回滚最近一次修复
dsh-doctor rollback --list # 列出所有修复日志
dsh-doctor rollback --id <id> # 回滚指定日志
在 Agent 内使用时，直接在对话中告诉 agent：
运行 dsh_doctor # 诊断
用 safe 范围运行 dsh_doctor_fix # 修复
运行 dsh_doctor_rollback # 需要时回滚
通用选项有三个：--profile <name> 指定 DSH profile（默认 web）、--port <number> 指定 Web 端口（默认 3080）、--scope <level> 指定修复范围（safe / deps / full，默认 safe）。
关于范围选择，三档是按风险递进的：建议从 safe 开始，只动文件和配置；没解决再升级到 deps 重装依赖；最后才考虑 full 清理进程。
适用场景与注意¶
适合的人群：经常折腾 DSH 插件和 profile 的开发者，尤其是需要保证 DSH 可用、不想在崩溃排查上耗时间的人。它不要求你读懂报错，诊断报告会直接给出问题点和修复建议。
使用前有几点需要注意：
full范围会终止残留进程，执行前确认没有正在运行的关键任务；- 系统边界操作（如
pnpm install、杀进程）无法自动撤销，journal 中会标记「需手动补偿」，回滚后留意这类改动； - 插件以当前 dsh 进程的权限运行，安装前建议检查源码与许可证。dsh-doctor 采用 MIT 许可证，源码在 GitHub 上可以直接查看。
结尾¶
dsh-doctor 把 DSH 崩溃后的处理流程收敛成了三步：dsh-doctor 诊断、dsh-doctor fix 修复、dsh-doctor rollback 回滚，配合运行时自愈服务，让「修坏了」这件事本身也可控。
项目主页：https://github.com/jorinyang/dsh-doctor
社区目录页：https://www.skillhub.cn/plugins/jorinyang/dsh-doctor（社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系）
