前言¶

在 DSH 插件生态里，社区插件很多，实际使用时常见的问题不只是“找不到合适的插件”，还包括：这个插件和本地已安装插件是否重复？聚合 bundle 是否已经提供了某个子插件？批量安装多个仓库是否会冲突？官方仓库是否有尚未关闭的 Issue？本地 DSH 是否落后官方发行版？

直接手动搜索、安装、卸载，容易依赖临时判断，也容易出现重复安装、漏掉子插件、跳过预检的情况。dsh-plugin-doctor 就是用来处理这类插件诊断与决策问题的工具。

下面介绍它适合做什么、怎么安装、典型用法，以及使用时需要注意的边界。

这是什么¶

dsh-plugin-doctor 是 DSH 插件生态的诊断与决策工具，由 white-sand-grand 维护，许可证为 MIT。

它面向 DSH 插件社区使用场景，提供社区插件搜索、功能重复判断、插件关系图、批量安装前检查、聚合 bundle 子插件识别、本地用量审计和官方版本同步检查。

该插件要求 Node.js >=22.19。默认只读，不会自行安装、卸载或启动 Web UI。

核心能力¶

社区插件搜索与重复判断¶

它可以搜索社区插件，并返回匹配度、功能标签、stars、更新时间和安装引用。

在判断是否重复时，它会比较插件说明文本、功能标签和依赖，给出保留、移除或自研的建议。

社区搜索按以下顺序降级：

1. 实时 GitHub
2. 进程内缓存
3. 第三方 registry
4. 内置静态快照

结果会标注数据来源。

插件关系与全景图¶

它可以生成插件相似度关系图，说明两个插件之间的相似度以及重叠来源。

它也可以生成 Mermaid 插件全景关系图，并按以下层级划分：

• core
• active
• idle
• review

这类图适合用来查看已安装插件之间的功能关系，而不是只靠文字描述。

批量安装前检查¶

在批量安装前，它会检查：

• 包名
• 工具名
• Cordis patch 行
• peer 依赖

如果无法完成检查，plugin_install_guard 会失败关闭。仓库元数据无法读取、GitHub 403/429 或未知状态时，不会因为“暂时查不到”而放行。

官方仓库未关闭 Issue 检查¶

在安装前，它会询问是否检查官方仓库的未关闭 Issue，并显示相关链接与风险。

这是一个提醒性流程。Issue API 不可用只影响提醒信息，不会绕过 plugin_install_guard 的失败关闭规则。

聚合 bundle 子插件识别¶

它可以展开聚合 bundle 的插件形依赖，并标记 providedBy 子插件。

当某个功能已经由聚合 bundle 提供时，它会把对应子插件标记为 providedBy，避免重复安装，也不会建议单独卸载该子插件。

本地用量审计¶

它会扫描本地已落盘的 session 日志，并按 dsh.tools 统计：

• 调用量
• 会话数
• 最近使用时间

这个审计只读取本地已落盘 session 日志，不上传内容。尚未结束或尚未刷盘的会话可能未被计入，结果中会明确提示。

官方版本同步检查¶

它会对比本地 DSH 版本与官方最新发行版。

如果本地落后，它会报告官方发行版的新改动，并列出可能与本地已安装插件重复或冲突的项目。

安装与启用¶

在运行 DSH 的同一环境中执行：

dsh plugin --profile web add github:white-sand-grand/dsh-plugin-doctor

安装后，按你自己的方式启动 DSH Web。dsh-plugin-doctor 不会替你启动 Web，也不会改变已有 profile 的其他插件。

典型用法¶

安装前先询问官方 Issue¶

可以这样提问：

我想安装一个 Web UI 插件，先帮我查一下官方仓库有没有未修复的问题。

插件会先询问是否检查官方仓库未关闭 Issue，再执行安装前检查，并显示相关链接与风险。

搜索并检查重复¶

可以这样提问：

帮我找一个记忆插件，并检查它是否和 web profile 里已有插件重复。

结果会列出候选插件、匹配原因、与本地已有插件的重叠，以及保留或移除建议。

批量安装前检查冲突¶

可以这样提问：

我要同时安装以下仓库，请先检查它们会不会冲突：
github:owner/plugin-a
github:owner/plugin-b
github:owner/plugin-c

如果 GitHub 返回 403/429，或仓库元数据无法读取，结果会是 INSTALL BLOCKED。

查看已安装插件之间的关系¶

可以这样提问：

之前安装的插件之间有什么联系？哪些功能相似？

它会返回相似度关系，并说明重叠来源。

识别聚合 bundle 提供的功能¶

可以这样提问：

我想安装任务看板，需要再安装一个 task-board 插件吗？

如果相关功能已经由已安装的聚合 bundle 提供，它会显示 providedBy 来源，不建议重复安装或单独卸载子插件。

审计声明了工具但从未使用的插件¶

可以这样提问：

列出 web profile 中声明了工具但从未使用的插件。

结果只基于本地已落盘 session 日志，不上传内容。尚未结束或尚未刷盘的会话可能未计入。

检查本地 DSH 是否落后官方版本¶

可以这样提问：

我的 DSH 落后官方多少了？升级会影响已装的插件吗？

它会对比本地 DSH 版本与官方最新发行版，报告新改动，以及可能重复或冲突的已安装插件。

适用场景与注意¶

适合 DSH 智能体开发者在添加、替换、审查插件时使用，尤其是以下场景：

• 想找一个社区插件，但不确定是否已有本地插件覆盖
• 准备批量安装多个插件仓库，需要先检查冲突
• 想查看已安装插件之间的功能重叠
• 想确认某个功能是否已经由聚合 bundle 提供
• 想知道本地 DSH 是否落后官方版本
• 想审计本地插件是否真的被使用

注意以下几点：

1. 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
2. dsh-plugin-doctor 默认只读，不会自行安装、卸载或启动 Web UI。
3. allowExecuteActions 默认为 false，默认只输出命令；明确交互确认后才允许执行 add/remove。
4. plugin_install_guard 在仓库元数据无法读取、GitHub 403/429 或未知状态时失败关闭。
5. 官方 Issue 检查是提醒性流程，不能替代安装前守卫。
6. 用量审计只读取本地已落盘 session 日志，不上传内容。
7. 社区搜索依赖实时 GitHub、进程内缓存、第三方 registry 和内置静态快照，并会标注来源。

链接¶

GitHub：

https://github.com/white-sand-grand/dsh-plugin-doctor

插件线索中还有目录页 URL，但未见于已抓取资料，仅供查找参考：

https://www.skillhub.cn/plugins/white-sand-grand/dsh-plugin-doctor