前言¶

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