前言¶
DSH 的理念是「一切皆插件」，一个 profile 的最终行为通常来自多组 patch 层叠加。问题在于，某些配置错误不会让 dsh 启动失败，而是让配置静默不生效。dsh-doctor 是 asdf17128 维护的健康检查工具，用于检查 DeepSeek Harness（dsh）profile 中被补丁丢掉、失效或未被加载的配置项。下面介绍它的检查范围、用法和需要注意的边界。
这是什么¶
dsh-doctor 的定位是：Health check for your DeepSeek Harness (dsh) profile — finds config fields your patches silently dropped, dead patches, and unmaintained plugins.
它可以用两种方式使用：
- 作为命令行工具，直接检查一个 dsh profile。
- 作为 dsh 插件安装到 profile，注册
config_doctor工具。
许可证为 MIT。
核心检查项¶
dsh-doctor 会检查以下类型的问题：
config-clobber：补丁整体替换某个 entry 的config后，未重写的默认字段丢失。dead-patch：补丁指向不存在的 entry id，导致补丁不生效。tool-collision：两个挂载插件注册相同工具名，导致 dsh 拒绝启动。plugin-not-mounted：已安装但从未被加载的插件。plugin-stale：180 天以上无 npm 发布的第三方插件。entry-removed：补丁层移除的 shipped entry。entry-toggled/entry-added：与 shipped profile 的其他差异，作为 info 提示。
先做基本检查，再用 --explain 查看当前 profile 树，是比较顺手的使用顺序。
工作原理¶
dsh-doctor 通过 dsh 自己的配置合成结果做差分：
dsh --profile <p> --dump-config
dsh --profile <p> --dump-default-config
第一条命令给出实际启动的 profile 树，第二条命令给出不带用户层的默认树。dsh-doctor 将两者差异归因到用户补丁层。检查过程中不会启动插件，也不会评估配置中的 !!js 表达式。
安装与启用¶
作为命令行工具，可以直接运行：
npx dsh-doctor
如果要作为 DSH 插件安装到 web profile：
dsh plugin --profile web add github:asdf17128/dsh-doctor
安装后，它会在该 profile 注册 config_doctor 工具。移除时使用：
dsh plugin --profile web remove dsh-doctor
典型用法¶
常用命令如下。
基本检查：
npx dsh-doctor
检查另一个 profile：
npx dsh-doctor --profile headless
查看 profile 树：
npx dsh-doctor --explain
--explain 会描述 profile 树中的 active、disabled、conditional 等状态。对于 disabled: 为 !!js 表达式的 entry，报告会将其标为 conditional，因为实际启用状态取决于启动机器，而不是检查时求值。
输出与运行选项：
npx dsh-doctor --verbose
npx dsh-doctor --json
npx dsh-doctor --offline
npx dsh-doctor --quiet
如果确认需要修复合并丢失字段：
npx dsh-doctor --fix
–fix 的边界¶
--fix 会写入文件。它只将被标记的丢失字段重新写入同一个 config 块，并在写入前创建 .bak。dead-patch 不会自动修复，因为重命名还是删除由用户决定。
退出码¶
0：干净或仅警告。1：至少一个错误。2：无法检查。
经过上面的步骤，可以在本地工作流中根据退出码判断是否需要继续处理。
适用场景与注意¶
适合：
- 维护 DSH profile 的智能体开发者。
- 在 dsh 版本变更后确认 patch 是否仍有效。
- 需要把 profile 配置问题作为错误信号处理的工作流。
注意：
- 需要 Node 18+ 和可用的
dsh；优先使用本地node_modules/.bin/dsh，否则使用PATH中的dsh。 - 已验证兼容
@deepseek-ai/dsh 0.1.0-rc.5。dsh 处于开发者预览，并可能引入破坏性变更。 --fix会写入文件，但只写入被标记的config块，并先创建.bak。- 在尚无 profile 的
$DSH_HOME上运行，可能由 dsh 创建profiles/<name>/模板目录。 - 作为 DSH 插件安装并启用后，它运行在当前 dsh 进程可用的权限范围内。安装前应检查源码，并确认 MIT 许可证符合你的使用要求。
链接¶
GitHub：https://github.com/asdf17128/dsh-doctor
目录页：资料未给出具体 URL，避免拼造；可在 DSH 社区目录中搜索 dsh-doctor。
