white-sand-grand/dsh-plugin-doctor

dsh-plugin-doctor

英文版本：README.en.md

Awesome DSH Plugin

dsh-plugin-doctor 是 DSH 插件生态的诊断与决策工具。它可以搜索社区插件、比较功能重复、识别聚合 bundle 提供的子插件、检查批量安装冲突、审计实际使用量、生成插件全景关系图，并检查本地安装与官方发行版的差距。
灵感来源自 claude code 的命令 "/doctor" 以及无数次下载插件造成的崩溃和冲突。

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

安装

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

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

然后按你自己的方式启动 DSH Web：

dsh web

打开 http://127.0.0.1:3080 后直接用自然语言提问。插件不会替你启动 Web，也不会改变已有 profile 的其他插件。

更新

使用移除后重新添加的确定性流程：

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

更新后是否启动 Web 由你决定：

dsh web

能做什么

| 用户需求 | 工具行为 |
| --- | --- |
| 找一个插件 | 搜索 GitHub dsh-plugin 主题和降级数据源，返回匹配度、功能标签、stars、更新时间和安装引用 |
| 判断功能是否重复 | 比较说明文本、功能标签和依赖，并给出去重或自研建议 |
| 询问插件有什么联系 | 生成相似度关系图；节点带中文功能解释，连线说明相似度及重叠来源 |
| 安装多个仓库前检查风险 | 预检包名、工具名、Cordis patch 行和 peer 依赖；冲突或无法检查时返回 INSTALL BLOCKED |
| 检查聚合 bundle | 展开已安装的 DSH 插件形依赖；子插件标记 providedBy，不会被建议单独卸载 |
| 查看实际使用情况 | 扫描本地已落盘 session 日志，按 dsh.tools 统计调用量、会话数和最近使用时间 |
| 查看插件总体格局 | 生成 Mermaid 关系图，并按 core、active、idle、review 分层 |
| 安装前了解官方已知问题 | 在搜索、推荐或收到仓库链接准备安装时，询问是否检查官方仓库的未关闭 Issue，并显示相关链接和风险 |
| 检查本地落后官方多少 | 对比本地 DSH 版本与官方最新发行版；落后时报告发行版新改动以及可能重复或冲突的已装插件 |

七个工具

- plugin_community_search：社区插件搜索与过滤。
- plugin_similarity_analyze：相似度、重复组和不可替代性分析。
- plugin_recommend：综合搜索和本地库存做安装、去重或自研决策。
- plugin_install_guard：批量安装预检，只读不安装。
- plugin_usage_audit：本地 session 用量审计，不上传日志。
- plugin_landscape：插件全景与关系图，可把社区候选加入图中。
- plugin_official_sync：官方版本同步检查，本地落后时报告新改动与重复/冲突插件。

Agent 会根据问题自动选择工具。

安装前官方 Issue 检查

当用户通过社区搜索寻找可安装插件、请求推荐插件，或直接发送多个仓库链接要求安装时，插件会先询问是否检查这些官方仓库的未关闭 Issue。检查内容包括 Issue 标题和正文与用户需求或故障现象的匹配度，并提供官方链接，例如递归文件监视导致 Web UI 卡顿的未解决报告。

用户明确选择“不检查本会话”后，本会话不会再次弹出这个提醒；下一次新会话会重新询问。用户取消弹窗或当前环境没有交互能力时，插件会说明检查未完成，不会把它误报成“没有已知问题”。Issue API 暂时不可用只影响提醒信息，不会绕过 plugin_install_guard 的失败关闭规则。

具体使用例子

安装前先询问官方 Issue（实际故障场景）

我想安装一个 Web UI 插件，先帮我查一下官方仓库有没有未修复的问题，避免再次出现历史加载失败、模型无法选择或文件操作卡住。

插件会先询问是否进行官方 Issue 检查，来避免由于插件本身问题导致用户不得不使用其他 agent 来找出 bug 并尝试修复。举例：实际排查时，官方仓库曾发现与“右侧文件面板卡顿、历史加载失败、整个聊天对话无法继续使用”高度一致的未关闭 Issue：根因并不是远程 Web 插件，而是某个文件面板插件的递归监视行为。报告会显示插件名，例如 @example-org/ui-panel-plugin，并附上官方 [Issue #119]供用户核对。用户在本会话明确拒绝后，后续安装请求不再重复提醒。

搜索并检查重复

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

结果会列出候选插件、匹配原因、与本地插件的重叠分数，以及“保留哪个、移除哪个”的命令。需要生成自研规格或执行去重时，Agent 会先请求确认。

批量安装前阻止冲突

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

如果 GitHub 返回 403/429，或仓库元数据无法读取，结果会是 INSTALL BLOCKED，并告诉你配置 token 或等待限流重置；它不会因为“暂时查不到”而放行。

查看插件关系

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

plugin_landscape 会返回关系图。每个节点有中文功能解释，每条连线说明相似度来自说明文本、功能标签还是依赖重叠；传入具体意图时，社区候选会以虚线加入图中。

识别聚合 bundle

我想安装任务看板，需要再安装一个 task-board 插件吗？
推荐逻辑会读取已安装聚合 bundle 的插件形依赖。如果功能已经由 bundle 提供，会显示 providedBy 来源，不会建议把子插件单独卸载或重复安装。

审计使用量

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

结果来自本地已落盘 session 日志，不上传内容。当前尚未结束或尚未刷盘的会话可能尚未计入，报告会明确提示。

检查官方版本同步

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

plugin_official_sync 会对比本地 DSH 版本和官方最新发行版。版本一致时只回答一句；本地落后时报告发行版新增改动，并列出可能重复或冲突的已装插件：peer 依赖范围排除新版本、声明的工具名出现在官方发行说明里、能力关键词与新改动重叠。全部发现仅供参考，不会替代安装守卫的判定。

直接提问与使用 doctor 的区别

直接对 DSH 说“帮我找个插件”时，模型通常只能根据已有上下文给出一般性建议，不能稳定地搜索社区、读取本地包元数据、量化相似度或检查 Cordis 注册冲突。安装多个仓库时也可能跳过预检。

安装 doctor 后，同样的问题会获得可复核的结构化结果：

| 直接提问 DSH | 使用 dsh-plugin-doctor |
| --- | --- |
| 依赖模型记忆或临时搜索 | 使用 GitHub、缓存和 registry 降级链，并注明数据来源 |
| “看起来重复”但没有数值依据 | 返回文本、功能标签、依赖三类相似度和重复组 |
| 可能漏掉聚合 bundle 内的子插件 | 读取已安装 bundle 依赖并标记 providedBy |
| 多个仓库直接尝试安装 | 先检查包名、工具名、patch 行和 peer 依赖；无法验证时失败关闭 |
| 很难知道插件是否真正被使用 | 从本地 session 日志统计调用量、会话数和最近使用时间 |
| 只能用文字描述插件关系 | 输出 Mermaid 关系图和逐对中文解释 |

安全与降级

plugin_install_guard 在检查不到仓库元数据时保持失败关闭。GitHub 403 或 429 会提示配置 token 或等待限流重置，未知状态不会被当作安全。

社区搜索按以下顺序降级：实时 GitHub、进程内缓存、第三方 registry 页面、内置静态快照。结果会注明数据来源。

用量审计只读取已经写入磁盘的 session 文件。当前尚未结束或尚未刷盘的会话可能不会计入，报告会明确提示。损坏文件会跳过并计数；Node 不支持 zstd 时，压缩日志会跳过，但不会阻止其他工具加载。

官方版本检查按发行版列表读取并带进程内缓存；GitHub 不可用时降级为陈旧缓存或明确的不可用提示。该降级只是提示性的，绝不会影响 plugin_install_guard 的失败关闭判定。

可选配置

| 配置 | 默认值 | 作用 |
| --- | --- | --- |
| githubTokenEnv | DSH_PLUGIN_DOCTOR_GITHUB_TOKEN | GitHub token 的环境变量名 |
| githubToken | 无 | 直接提供 token，不建议写入文件 |
| similarityThreshold | 0.8 | 判定功能重复的相似度阈值 |
| cacheTtlMinutes | 30 | 社区搜索缓存时长 |
| enableRegistryFallback | true | GitHub 失败时启用 registry 和静态快照降级 |
| allowExecuteActions | false | 允许在明确交互确认后执行 add/remove；默认只输出命令 |

推荐只配置 token 环境变量：

export DSH_PLUGIN_DOCTOR_GITHUB_TOKEN='你的 GitHub token'

从源码开发

git clone https://github.com/white-sand-grand/dsh-plugin-doctor.git
cd dsh-plugin-doctor
pnpm install
pnpm test
pnpm run build
node verify-boot.mjs

当前验证基线：84 个测试通过，TypeScript 构建通过，七个工具注册和冒烟调用通过。算法和数据流见 ARCHITECTURE.md，贡献流程见 CONTRIBUTING.md。Windows 和 WSL 不要混用同一个 node_modules。

许可证

MIT。