环境诊断医生 coppynight/dsh-doctor

dsh-doctor

DeepSeek Harness 的 flutter-doctor 风格诊断与修复工具一个官方 repository-plugin（.dsh-plugin 格式）＋同名终端 CLI：安装级 + harness 内检查，能修的自动修（settings 恢复 / 交互补 key），不能修的输出可直接复制的手动命令。

能力地图

| 能力面 | 入口 | 说明 |
| /doctor 命令 | 在会话输入 /doctor | harness 内运行全部检查（含 harness 级），输出 flutter 风格报告 |
| 终端 CLI | node bin/dsh-doctor.mjs | web 挂掉时仍可运行；--fix 应用安全修复并交互补 key |
| 安装级检查 | 两个入口共用 | privilege / node / git / pnpm / 安装布局 / staging 残留 / PATH / 所有权 / hooks / 凭据 / git 状态 |
| harness 级检查 | 仅 /doctor | 挂载插件状态 / repository 插件 / sessions / settings / 凭据链 / web.log |
| 修复 | --fix | settings 备份恢复（自动）；凭据交互补写（CLI）；其余输出精确手动命令 |

安装

本插件是官方 repository-plugin（.dsh-plugin/ + package.json#dsh.entry）。安装 = 在 $DSH_HOME/cordis.patch.yml（机器级补丁层，对每个 profile 生效）里加一条 patch 条目——按 id 命中 dsh-base bundle 内置的空 repository-plugins 行，用你的源列表覆盖它的 config：

$DSH_HOME/cordis.patch.yml —— 顶层必须是一个 patch 条目「数组」，写成 repository-plugins: 开头的 keyed map 会被 dsh 拒绝加载。

- id: repository-plugins # ① 目标行：dsh-base 已内置该 id（空配置） name: '@deepseek-ai/dsh-repository-plugin' # ② 行的插件名：与内置行一致，仅声明、不修改 config: repositories: # ③ 要安装的 repository 插件源（可列多个）
- 'github:coppynight/dsh-doctor#c4683a9eba5102681fd399c3e292a34ef7f3616d&path:/.dsh-plugin'

源字符串解剖（每个字段的意思与改法）：

| 片段 | 含义 | 何时改 |
| github: | 源类型（只支持 GitHub） | 不 |
| dsh-external/dsh-doctor | owner/repo | 不 |
| #c4683a9e… | commit 哈希——安装按它锁定，缓存按它不可变 | 更新插件时换成新提交哈希 |
| &path:/.dsh-plugin | 插件子目录；省略则默认 /.dsh-plugin | 本仓库只有一个插件，无需改 |

本仓库是公开镜像（开发主场：dsh-external/dsh-doctor）。公开源安装无需凭据。
改完配置后重启 dsh（Node half 改动需重启，仅凭据变化则不需要）。

案例 1：首次安装（可照抄）

1. 把上面那段 YAML 写进 $DSH_HOME/cordis.patch.yml
2. 预填充安装缓存（官方 @deepseek-ai/dsh-repository-plugin 未发布期的过渡步骤，见下文）
node scripts/prepare-cache.mjs
3. 重启 dsh（Node half 改动需重启）
4. 在会话里输入 /doctor 验证：应输出 flutter 风格报告，plugins 检查显示全部 active

案例 2：更新插件

1. 克隆仓库并切到新提交（或直接拿 GitHub 上的新哈希）
SHA=$(git -C rev-parse HEAD)
2. 把 cordis.patch.yml 里的 #c4683a9e… 换成 #$SHA
3. 重新预填充缓存（ref 变了，缓存键随之变化）
node scripts/prepare-cache.mjs --ref=$SHA
4. 重启 dsh

案例 3：卸载

把该条目从 $DSH_HOME/cordis.patch.yml 删掉（或整条注释掉）→ 重启 dsh。
缓存可顺手清掉：rm -rf $DSH_HOME/cache/repository-plugins（不清也不影响运行）。
安装前置（官方私有 rc 库阶段，2026-08-13 实测）：@deepseek-ai/dsh-repository-plugin（dsh-plugin-prepare 的提供者）尚未发布到任何可达 registry，而它是 loader 硬校验的 devDep（不能移除），RepositoryCache 的 pnpm install 会 404。上面的 scripts/prepare-cache.mjs 按 loader 的 cache 契约预填充，让 loader 跳过安装（详见 decisions/implemented/process/2026-08-13-repository-plugin-prepack-bridge.md）。官方发布该包后删除此步骤即可。

使用

/doctor（harness 内）

/doctor # 全部检查，flutter 风格报告 /doctor --check plugins # 单项检查 /doctor --fix # 诊断 + 应用安全修复（settings 恢复） /doctor --json # 机器可读输出 /doctor -v # 每条结论附明细

终端 CLI（web 挂掉也能用）

node bin/dsh-doctor.mjs # 诊断（有 error 时 exit 1）
node bin/dsh-doctor.mjs --fix # 诊断 + 修复（settings 自动；DEEPSEEK_API_KEY 隐藏输入补写）
node bin/dsh-doctor.mjs --json # 机器可读
node bin/dsh-doctor.mjs --list # 检查目录

修复边界（诚实原则）

| 修复 | 方式 |
| settings.yaml 缺失/为空 | --fix 自动备份并写入最小合法文档 |
| DEEPSEEK_API_KEY 缺失 | 终端 --fix 隐藏输入补写 ~/.dsh/.env（chmod 600，绝不回显）；harness 内给指引不代输密钥 |
| PATH / 所有权 / staging / hooks | 不越权代劳——输出可直接复制的手动命令 |

检查目录

| id | 说明 | 级别 |
| privilege | 不得以 root 运行 | 安装 |
| node | Node 须满足 ^22.19.0 \|\| >=24.0.0 | 安装 |
| git | git 存在且 ≥2.26（worktree hooks） | 安装 |
| pnpm | pnpm 可用 | 安装 |
| install-layout | source 容器 / current 链接 / launcher 解析 | 安装 |
| staging-leftovers | 失败运行不得堆积 staging 工作树 | 安装 |
| path | dsh bin 目录在 PATH | 安装 |
| ownership | dsh home 无 root 属主残留 | 安装 |
| hooks-path | 全局 core.hooksPath 不得被静默替换 | 安装 |
| credentials | DEEPSEEK_API_KEY 已配置 | 安装 |
| repository-git-state | 仓库 git 状态可写 | 安装 |
| plugins | 已挂插件全部 active（failed/pending 点名） | harness |
| repository-plugins | 声明的 repository 源有安装痕迹、形状合法 | harness |
| sessions | 会话存储可写 | harness |
| settings | settings.yaml 存在且非空 | harness |
| credentials-chain | 进程环境 → cwd/.env → $DSH_HOME/.env 某层提供 key（不回显值） | harness |
| web-log | web.log 无近期错误行 | harness |

与 out-of-band 医生的关系

本插件运行在 harness 内（能看挂载插件、repository 列表、sessions 等内部状态），终端 CLI 与 web 解耦。它不替代任何 out-of-band 医生（如 web 全挂时的 dsh-doctor 自助脚本）：一个在内、一个在外，按场景互补。

开发

node scripts/gates/run.mjs # 门禁：package-contract / secrets / prepared / unit（58 测试）

生成的 dsh-plugin.mjs 与 dsh-plugin-assets/ 是 dsh-plugin-prepare 的产物（入库，勿手改；prepared 门禁守护存在性与 manifest 名）。每次非平凡改动随附 decisions/implemented/ 决策记录。