插件诊断面板 Ragnoryok1/dsh-plugin-doctor

@ragnoryok1/dsh-plugin-doctor

DeepSeek Harness 插件诊断

一个面向 DeepSeek Harness Web GUI（dsh）的诊断面板。

检查内容

| 分类 | 含义 |
| 加载失败 | 插件在启动时报告了错误，会显示它自己给出的消息。 |
| 已声明但未运行 | 某个包声明了这一行，但没有任何运行中的条目承载它——这正是更新失败后留下的痕迹。 |
| 无法在此管理 | 条目存在，但不能在这里切换。会显示具体原因：management-required、unaddressable 等。 |
| 已禁用 | 被有意关闭。 |
| 版本警告 | 不致命，但在下次更新前值得一读。 |

只有错误才算作问题。参考类分类始终可见，但绝不会让一个健康的配置档看起来像是坏掉了。

界面外观

插件清单旁的“诊断”标签页

安装

dsh plugin --profile web add @ragnoryok1/dsh-plugin-doctor

然后打开 Settings → Built-in plugins → Diagnostics。

为什么它能经受住多次更新

本插件从不读取其他包的文件或内部实现。它展示的一切都来自受支持的服务：插件管理器通过 Remote 协议（remote.pluginManager）上报状态，返回结果再从 { ok, value } 信封中解包出来。

由此衍生出两个特性，而这两点都很容易做错：

- “未发现问题”总是附带检查数量——否则它与“这次检查什么都没看到”无法区分；
- 参考信息不是问题：配置档自身拥有的内置模块属于正常情况，而不是故障。

如何验证

像“能找出损坏的插件”这样的说法，如果没有真正弄坏一个插件就毫无价值，因此我们在一台实际运行的 harness 上，用一个刻意弄坏的插件做了验证：fixtures/canary/ 里存放着一个 apply() 始终抛异常的 fixture。

| 配置档状态 | 面板显示的内容 |
| 已安装 canary | “发现 1 个问题” → “已声明但未运行 (1)：doctor-canary”，并附带模块名和建议 |
| 已移除 canary | “未发现问题。所有插件均已加载且兼容。” |

复现步骤见 fixtures/canary/README.md。

有一个细节值得了解：在宿主端失败的行永远不会进入运行中插件列表，因此已经没有谁还能承载 meta.error——正是包级条目检查抓到了它。两种检查都必不可少，实践也证实了这一点。

两个部分：面板与磁盘扫描

面板通过受支持的服务读取插件状态——但这些服务运行在浏览器里，看不到文件系统。而那些我们总要手动一点点排查的故障恰恰存在于磁盘上，所以由另一个脚本来报告它们：

node bin/doctor-scan.mjs
or, when the package is installed on its own: npx dsh-doctor

| 查找对象 | 为什么重要 |
| .parked 目录 | 被搁置的插件副本——更新时绕过“重命名被占用”留下的痕迹 |
| _tmp_ 目录 | 安装失败后的残留；正是它让更新以 EPERM 失败 |
| 损坏的 file: 链接 | 配置档指向了一个已经不在的文件：安装还没开始就会以 ENOENT 失败 |
| 启动失败报告 | logs/startup-.log：启动器自己列出未能激活的插件，含包名、错误与等待其服务的插件数量 |

在真实残留物上验证过。 该脚本先在干净的配置档上运行，再在刻意制造了残留文件的配置档上运行（两类残留都被找到），然后再次在干净的配置档上运行——没有任何发现。期间它还发现了一个真实的 .parked 目录，是某次插件更新中为绕过 EPERM 而遗留在配置档里的；那个目录已被删除。

为什么残留文件没有出现在面板里。 要在界面中展示它们，就需要本插件自己的 remote 服务，而 ctx.remote.* 下的名称是由 harness 构建流水线生成的。生成器（@deepseek-ai/dsh-typert-generator）已经发布，所以这条路是存在的——但那是另一项工作，本文档并不宣称它已经完成。

它不做什么

- 不做任何修复：它只负责报告；
- 不向任何地方发送数据：一切都在本地计算。

为什么 peer 范围这么长

peerDependencies 里不是一个短范围，而是九条带显式预发布标签的分支。这不是装饰：node-semver 只有在范围中存在同一个 major.minor.patch 元组、且自身带预发布标签的比较符时，才允许预发布版本通过。所以看起来很宽的 >=0.1.0-rc.2 <0.3.0 既匹配不到 0.1.7-alpha.2，也匹配不到 0.2.1-alpha.1，用户会撞上 ERESOLVE。已用 npm 本身验证：短范围只解析出 0.1.0-rc.2 … 0.1.0-rc.8，长范围覆盖我们需要的每个版本。

构建

npm install
npm run build # tsdown -> lib/index.js (host half) + lib/client.js (client bundle)
npm pack

lib/client.js 以 dsh 客户端加载器能够识别的格式构建（__ModuleLoader__.load），并导出 inject/apply。React 与 harness 相关包保持为外部依赖，由加载器负责解析。

目录结构

- src/client/index.ts —— 面板、各项检查以及标签页注册；
- src/client/locales.ts —— 本插件自身界面所用的 ru、zh 和 en 词典；
- src/index.ts —— 空的宿主端部分（它的作用是提供一个可加载的 node 入口）；
- cordis.patch.yml —— 配置档补丁（为 plugin-doctor 客户端行添加 - insert:）；
- bin/doctor-scan.mjs —— 磁盘扫描（残留文件与损坏链接）；
- fixtures/canary/ —— 用于验证面板的 canary fixture。

许可证

MIT。这是一个社区包，与 DeepSeek 无隶属关系。