插件体检 GlariaLuminous/dsh-plugin-health-check

装 DSH 插件之前，先模拟一遍。
只读、静态，在你真实的配置档上按官方算法合成，再告诉你哪里会出问题。

安装 ·原理 ·示例输出 ·安装前模拟 ·边界 ·参考文档 ·

DSH 的插件不是装进 node_modules 就生效。能不能加载，取决于配置档选了哪些 bundle、patch 按什么顺序覆盖、包声明的版本 DSH 认不认。这些问题大多要重启之后才暴露，表现往往只是「某个东西悄悄没了」。

dsh-plugin-health-check 沿着 配置档 → bundle → patch → 配置条目 把这条链路在装之前走一遍。它不启动任何插件，不执行任何命令，不改动你的配置。

| 你遇到的现象 | 常见原因 | 对应发现 |
| 装完重启，插件没出现 | bundle 解析不到、没声明 dsh.bundle.patch、版本不被当前 DSH 接纳 | DSH_PACKAGE · DSH_VERSION |
| 配置被另一层悄悄换掉 | patch 按 id 整体替换 config；id 重复、覆盖未命中、include 成环 | DSH_PATCH |
| 两个 MCP 服务只剩一个 | 同一作用域里 serverName 重复，重复注册会被拒绝 | R1 · R8 |
| 检查结果为空，不知道算不算健康 | 动态表达式、未解析的模块、服务隔离 | DSH_COVERAGE，状态为 incomplete |

安装

作为 DSH 插件装进配置档，一条命令：

dsh plugin --profile web add github:GlariaLuminous/dsh-plugin-health-check

重启 DSH，然后直接对智能体说：

检查我的 DSH 插件。

我想装 /path/to/plugin，会不会和现有插件冲突？

智能体会调用只读工具 plugin_health_check，后一句会把目录作为 candidate 传进去。

状态：实验性。 检查引擎（命令行）已在 DSH Desktop 0.2.1-rc.2 上验证。智能体工具入口较新：注册流程有不依赖宿主的测试覆盖，但还没有在真实 DSH 里长期使用。DSH 仍是开发者预览版，升级后请重新检查。遇到问题请带上 DSH 版本提交 issue。

只想跑命令行、不装进配置档：

git clone https://github.com/GlariaLuminous/dsh-plugin-health-check.git
cd dsh-plugin-health-check
npm ci --ignore-scripts
node scripts/dsh_health_check.mjs --profile desktop

需要 Node.js 22+。默认读取 $DSH_HOME，未设置时使用 ~/.dsh；--profile web 检查 Web 配置档，--json 输出结构化报告。参数全表见 参考文档。

原理

- 按宿主的规则读，不自己发明规则。 patch 合成用的是官方 @deepseek-ai/cordis-plugin-include 的算法；版本准入遵循 DSH 的 engines.dsh 优先、否则看 DSH peers 的规则，预发布版本参与比较。
- 覆盖层顺序一致。 bundle → 配置档 → home → 命令行 --patch，处理 disabled、分组、静态 include 和循环引用。
- 读得到 Desktop 内置包。 直接读取 Electron ASAR 里的包元数据，不需要启动 Electron。

示例输出

| 退出码 | 状态 | 含义 |
| 0 | pass | 已覆盖的静态配置检查通过 |
| 1 | fail | 存在致命发现 |
| 2 | error | 参数、路径或运行环境错误 |
| 3 | incomplete | 覆盖不完整，需要补充信息或运行态核实 |

JSON 报告包含 packages、entries、findings、coverage、status 和 exit_code。配置正文、凭据和 YAML 错误片段不会写进报告；本地安装路径会保留，便于定位，分享报告前请留意。

安装前模拟

把候选插件的本地源码或解包目录交给 --candidate：

node scripts/dsh_health_check.mjs --profile desktop --candidate /path/to/plugin --json

- 候选包不会被安装，也不会执行它的构建脚本或 apply。
- 同名包按包身份替换旧版本，不会被重复计入；否则作为新的一层加入。
- 报告只列出新增的问题，并保留原环境的 baseline。原环境本身失败或不完整时，不会给出干净的通过结论。

边界

这是静态检查。未验证的内容：运行时注册的工具、命令和 hook，Agent preset 的激活，MCP 的实际连接与 tools/list，会话里的实际权限。!!js 表达式只当数据，不会求值。

所以 STATIC PASS 的意思是「已覆盖的配置没有发现问题」，不是「插件能成功运行」，更不是「插件是安全的」。没有发现插件、版本未知或遇到动态配置时，结果会标记为 incomplete，不会因为没采集到数据就说「一切正常」。

相关工具

DSH 生态里已有几个体检类项目，侧重点不同，有重叠，也互补。以下据各项目的公开说明，细节以它们自己的 README 为准。

| 项目 | 侧重 |
| dsh-plugin-doctor | 插件作者侧：manifest、patch、入口、文件、构建，以及打包后在全新 profile 里的安装验证 |
| dsh-doctor | profile 层：被整体替换丢掉的配置字段、指向不存在条目 id 的 patch、工具名冲突 |
| dsh-xray | 运行中的 DSH：实际加载了什么、上下文成本、运行时健康 |
| dsh-plugin-health-check | 用户侧：在你真实的 profile 上按官方算法合成后做静态检查，并支持安装前模拟候选插件 |

作为 skill 使用

不装成插件时，也可以把完整仓库放到下面任一位置，并在该目录执行 npm ci --ignore-scripts：

- $DSH_HOME/skills/dsh-plugin-health-check/
- <项目根目录>/.dsh/skills/dsh-plugin-health-check/

保留 SKILL.md 和 scripts/ 的相对位置，然后使用 /dsh-plugin-health-check，或直接说「检查我的 DSH 插件」。skill 会指引 agent 从自己的目录执行检查，并在总结里保留覆盖范围。

开发

npm ci --ignore-scripts
npm test

测试会创建临时 profile 和 ASAR，不依赖本机 DSH。CI 在 Ubuntu 和 Windows 上，用 Node 22 与 24 运行。

src/ # DSH 插件入口与 plugin_health_check 工具 index.js tool.js report.js cordis.patch.yml # bundle patch：把插件插入 profile scripts/ dsh_health_check.mjs # 命令行入口 plugin_health_check.py # 可选 Python 启动器 dsh/ # 包解析 · patch 合成 · 静态扫描 tests/ # 回归测试 docs/dsh.md # 参考文档 SKILL.md # skill 工作流

遇到漏报或误报，欢迎提交最小的 DSH profile/patch 示例、宿主版本和预期行为。分享前请移除配置里的凭据和个人路径。

MIT