前言¶

DSH 的理念是「一切皆插件」，装一个插件往往就是一条命令。但 DSH 插件生态还在快速迭代，不少插件停留在 rc 版本阶段：插件声明的 peerDependencies 写的是 @deepseek-ai/dsh-tools@^0.0.1，你本机装的却是 0.1.0-rc.6。这种不匹配装进去轻则工具不工作，重则 web 界面直接起不来。

逐个打开 package.json 人工核对显然不现实。下面介绍的 dsh-plugin-doctor 把「装之前先检查」变成一句话：让 DSH 自己对目标插件做一次体检，拿到结论再决定装不装。

这是什么¶

dsh-plugin-doctor 是 lin-cheng-lab 维护的开源 DSH 插件（MIT 许可，社区目录归类为 admin-security），定位是「DSH 插件体检工具」：在安装任何 DSH 插件之前，先检查仓库可访问性、bundle 声明、peer 依赖与本地版本兼容性、构建产物，防止 rc 版本不匹配导致的启动崩溃。

实现上，它通过 ctx.tools.register(defineTool(...)) 把自己注册为一个工具，随 profile 加载和卸载。也就是说，不需要离开 DSH 去跑单独的脚本，直接用自然语言让它干活。

它检查什么¶

体检共五项：

1、本地环境：读取本机 DSH / cordis / dsh-tools / dsh-workflow 版本，作为后续比对的基准。
2、仓库可访问性：插件仓库是否公开，404 直接拦下，防止装「幽灵插件」。
3、bundle 声明：是否声明 dsh.bundle.patch（官方可安装格式）。
4、peer 兼容性（核心）：插件要求的版本与本机实际版本逐项做 semver 匹配，正确处理 prerelease（rc）规则——这正是开头说的启动崩溃场景的根源。
5、构建产物：main 指向的入口文件是否已提交到仓库。

两点实现细节：

• 网络检查走 DSH 内置 web 服务（ctx.web.fetch），本机版本走 fs 服务读取全局安装的 DSH 包清单，不需要额外权限。
• semver 匹配是内置纯函数实现，零依赖，支持 ^ ~ >= <= > < = * 与多条件范围。

体检结论怎么读¶

结论分三档：ok（可以装）、warn（谨慎，注意风险项）、danger（别装，装了会崩）。

报告是结构化的 JSON，包含 target、verdict、summary、checks、recommendation 字段，其中 checks 逐项给出 name / status / detail / items。下面是 README 中的输出示例（节选），可以看到 peer 兼容性不通过时的样子：

{
  "target": "dsh-external/dsh-deep-research",
  "verdict": "danger",
  "summary": "体检不通过，不要安装",
  "checks": [
    { "name": "本地环境", "status": "pass", "detail": "DSH 0.1.0-rc.6 · cordis 4.0.1 · dsh-tools 0.1.0-rc.6 ..." },
    { "name": "仓库可访问", "status": "pass", "detail": "github.com/dsh-external/dsh-deep-research 可访问" },
    {
      "name": "peer 兼容性",
      "status": "fail",
      "detail": "2 个 peer 依赖与本地版本不匹配（rc 不匹配风险！）",
      "items": [
        { "dep": "@deepseek-ai/dsh-tools", "required": "^0.0.1", "installed": "0.1.0-rc.6", "ok": false },
        { "dep": "@deepseek-ai/dsh-workflow", "required": "^0.0.1", "installed": "0.1.0-rc.6", "ok": false }
      ]
    }
  ],
  "recommendation": "不要安装：存在不兼容项，装进去可能导致启动崩溃。等插件更新适配后再装。"
}

recommendation 会给出对应的处理建议，比如等插件更新适配后再装。

安装与启用¶

README 给出两种安装方式。GitHub 方式的命令目前标注「发布后」且带占位符，发布前请以仓库 README 为准：

# 从 GitHub 安装（发布后）
dsh plugin --profile web add "github:<你的用户名>/dsh-plugin-doctor"

现阶段更直接的是本地源码安装。先把仓库拉到本地任意路径，再执行：

dsh plugin --profile web add "file:/path/to/dsh-plugin-doctor"

安装后需要重启 profile 才能生效：

dsh --profile web

注意插件自身声明了 peer 依赖 @deepseek-ai/dsh-tools ^0.1.0-rc.6 与 @deepseek-ai/cordis ^4.0.1，本机 DSH 环境需要满足。

典型用法¶

经过上面的步骤，向 DSH 说一句话即可触发体检：

帮我用 plugin_doctor 检查一下 dsh-external/dsh-deep-research

工具接受三种输入：

• GitHub 仓库 URL：https://github.com/owner/repo
• owner/repo 简写：owner/repo
• npm 包名：@scope/name 或 name

本地构建¶

如果想改代码或自行构建，先装依赖再编译：

npm install --legacy-peer-deps   # 安装 typescript（跳过未发布的 @deepseek-ai peer）
npm run build                    # tsc → lib/

类型解析依赖本机 DSH 安装中的 @deepseek-ai/cordis 与 @deepseek-ai/dsh-tools，需要先建 symlink：

ln -sfn <dsh安装>/node_modules/@deepseek-ai/cordis  node_modules/@deepseek-ai/cordis
ln -sfn <dsh安装>/node_modules/@deepseek-ai/dsh-tools node_modules/@deepseek-ai/dsh-tools

适用场景与注意¶

适合两类人：一是经常从 GitHub 或 npm 尝试第三方 DSH 插件的使用者，装之前跑一次体检，可以避开 rc 不匹配和「幽灵插件」；二是插件作者，发布前用它自查 bundle 声明、peer 范围和构建产物是否完整。

几点注意：

• 插件以当前 dsh 进程的权限运行。安装任何第三方插件（包括本插件）之前，应先检查其源码与许可证。
• 体检结论是装前参考：warn 档要逐项看清风险，danger 档不要装。
• 项目当前版本 0.1.0，package.json 标记 private: true，还处于早期阶段。

小结¶

dsh-plugin-doctor 解决的问题很具体：在「一切皆插件」的生态里，把装前核对从人工逐项检查变成一句话的体检报告。功能范围就是这五项检查，胜在结论直接、不需要额外权限。

• 社区目录页：https://www.skillhub.cn/plugins/lin-cheng-lab/dsh-plugin-doctor
• GitHub 仓库：https://github.com/lin-cheng-lab/dsh-plugin-doctor