dsh-doctor

「插件装了没反应」不该靠猜。 一条只读命令体检 DSH，输出问题清单 + 每条的下一步。

dsh_doctor()                  # 体检：插件行 / 技能提供方 / patch / HMR
dsh_doctor({ card: true })    # 输出可贴进 issue 的 markdown 卡片（默认脱敏）
/dsh-doctor card              # 人也可以直接敲

它查什么（四类，都是真实踩过的）

段	查什么	典型症状
① 插件行	哪些行没在运行、哪些被 disabled、为什么	「我装了插件但工具没出现」
② 技能提供方	逐个 provider 调 list()，把抛错的抓出来	「磁盘上有技能，会话里一个都看不见」
③ patch 层	重复 entry id、同一包多行、声明了没装上的 bundle	「装了但没生效 / 行为诡异」
④ HMR	是否 watch 源码、node_modules 是否被跳过	「改了插件代码没反应」

重点在 ②：技能注册表遇到某个 provider 抛错时只会跳过它并标记观察不完整 —— 模型侧完全看不到诊断信息。dsh-doctor 把那条错误原文摊开给你看。

为什么值得单独做一个

DSH 里三类完全不同的故障，在界面上长得一模一样：插件行没起来、技能提供方整体失败、 patch 行冲突。用户只能反复重启碰运气。dsh-doctor 把它们分开，并且每条结论都带下一步动作。

与同名包的区别（重要）

dsh-doctor 这个名字在生态里已经有好几个更成熟的项目。先说结论：如果你要的是「坏了能救回来」， 装下面这些，不要装这个仓库。

同类	覆盖范围
jorinyang/dsh-doctor	环境诊断 + 分级修复 + 一键回滚 + 运行期自愈服务。覆盖面比本仓库大。
henrytian1998/dsh-doctor	诊断 DSH home、残留进程、端口、超大 session，产出可以粘贴的 /doctor 报告。
asdf17128/dsh-doctor	注册一个 config_doctor 工具，专查启动时静默失败的配置字段。
astra3294/dsh-doctor（npm 上的同名包）	诊断 + 恢复：浏览器侧 Doctor 按钮、宿主侧恢复服务、启动探针与回滚。

本仓库不做投稿（2026-10-03 决定，2026-10-04 复查维持）：registry 里名字就叫 dsh-doctor 的已有 3 条， 投进去只是第 4 个同名，而且位置上没有不可替代的东西 —— 给读者省下挑选的时间也是价值。

那这个仓库还剩下什么？只读地把「为什么」讲清楚，而且只讲一件别人没覆盖的事： 「我装了插件/改了配置，为什么没生效」 —— 哪个插件行没运行、哪个技能提供方整体失败、 patch 里有没有重复 id、以及要不要重启。结论是一张默认脱敏、可以直接贴进 issue 的英文卡片。 它不改任何东西、也不替你恢复（那正是上面几个项目在做的事）。

本仓库没有发布到 npm（名字也被占了），安装走 GitHub 路径或 scripts/install.sh。

安装

dsh plugin --profile <profile> add github:louisyeaaah/dsh-doctor

或本仓库内：

scripts/install.sh [profile]     # 拷进 profile + 合并 patch 行
scripts/verify.sh                # 静态自检（不需要 DSH 在跑）

输出示例

DSH 体检报告
  采集时间   2026-10-03T03:45:00.000Z
  运行环境   node 24.18.1 / Electron 44.0.0 · darwin arm64
  Loader API v2

插件行     180 运行中 / 206 总行数（26 disabled）
技能       12 个可见；提供方 7 个（有失败）
patch      <HOME>/.dsh/profiles/desktop/cordis.patch.yml

结论：1 个问题，1 个警告。

❌ 1 个技能提供方整体失败
   scope#3/filesystem: cannot list "<HOME>/…/app.asar/…/dsh-agent-preset/skills":
   Cannot mix BigInt and other types, use explicit conversions
   → 注册表遇到失败会跳过该提供方并标记观察不完整 —— 所以它的技能在会话里全部不可见。
     典型原因：某个技能根目录读不了（例如 app.asar 内的目录）。

ℹ️ 改了代码为什么没生效
   HMR 的 root 是空数组 —— 不 watch 任何源码文件，所以改代码不会自动生效
   → 用 dsh-reload 的 reload_plugin 手动重载插件，或按需要打开 HMR 的 root

脱敏

体检卡默认把家目录替换成 <HOME>、把疑似 token 替换成 <redacted-token>、长 hex 替换成 <redacted-hex> —— 因为它就是拿来贴到公开 issue 里的。要看原文传 raw: true。

只读保证

不写任何文件、不改 profile、不动 Loader 树里的任何行。唯一的副作用是在页面/引擎里调用 各 provider 的 list()（注册表本来也会调）。

已知限制

• 依赖宿主内部结构（ctx.loader / ctx.skills / ctx.hmr / profileContext）。 DSH 升级后可能失效 —— 输出里始终带 Node / Electron / Loader API 版本，方便定位。
• 「插件行为不对」查不出来：它只回答加载与可见性层面的问题。
• 技能提供方的 list() 会被真的调用一次：极慢的 provider 会让体检变慢。

文件

文件	作用
lib/index.js	插件入口：dsh_doctor 工具 + /dsh-doctor 命令
lib/collect.js	只读采集四类事实
lib/render.js	脱敏、结论提炼、文本报告与 markdown 卡片
scripts/selftest.mjs	15 项纯逻辑自检（脱敏 / 结论 / 渲染）
scripts/verify.sh	静态自检（语法 + manifest + patch + 单测）

---

作者 @louisyeaah（悉尼）—— 发了什么、翻车了什么都会写。 作品站：louisyeaaah.github.io · 全部工具：github.com/louisyeaaah