dsh-plugin-doctor

English version: README.en.md

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。