前言¶
DSH 生態裏插件倉庫越來越多，清單協議、patch 格式、TypeScript 構建配置、hub 收錄狀態各自有一套約定。人工逐條對照容易漏項，CI 或模型側也缺少統一門禁。下面介紹 omdsh-dev/dsh-plugin-check：對插件目錄做靜態掃描，輸出合規報告與修復建議，不修改、不構建被檢查倉庫。
這是什麼¶
dsh-plugin-check 由 omdsh-dev 維護，在 SkillHub 分類爲聯網工具（目錄頁）。它在 DSH 中註冊 plugin_check 工具（row id：tool-plugin-check），掃描單個或批量插件倉庫，診斷清單協議、patch 格式、構建陷阱與 hub 收錄狀態，統一輸出 JSON 文本報告。
設計要點：
- 只讀：僅使用
readdir/stat/readFile，不改動被檢倉庫 - 零業務依賴：運行時只用 Node 內置模塊（
fs/path/child_process） - 不執行 tsc：構建相關檢查全部靠靜態文本掃描
許可爲 MIT；npm 包名 @omdsh-dev/dsh-plugin-check，當前版本 0.1.0，要求 Node ^22.19.0 || >=24.0.0。
核心功能¶
三種 action¶
| action | 作用 |
|---|---|
check |
檢查單個插件倉庫目錄，返回 verdict / errors / warnings / suggestions |
scan |
掃描父目錄下所有帶 package.json 的 dsh-* 插件倉庫，彙總報告 |
schema |
輸出全部檢測項清單與判定標準，供模型或人工覈對 |
工具參數：
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
action |
string | ✅ | check / scan / schema |
path |
string | 插件目錄（check）或父目錄（scan）；默認當前工作目錄 | |
strict |
boolean | 爲 true 時 warning 升級爲 error 並影響 verdict；默認 false |
形態識別與 33 項檢測¶
工具按倉庫形態（registry / skill / collection / tool-bundle / bundle / infra / unknown）套用不同檢查集，共 33 項，覆蓋四類問題：
| 類別 | 典型 error | 典型 warning |
|---|---|---|
| 清單協議 | no-manifest、invalid-name-format、missing-main-or-types、no-patch | incomplete-files、missing-peer、no-bundle-decl |
| patch 格式 | malformed-patch、patch-name-mismatch、duplicate-row-id | unexpected-fields |
| 構建陷阱 | no-source-entry、no-tsconfig、missing-ts-ext-imports、lib-layout-mismatch、stale-ts-imports | missing-rewrite-imports、types-path-mismatch、implicit-node-types、no-build-script |
| 生態合規（Profile Bundle） | core-row-id、missing-profile-install-example、manual-install-only、core-modification-required | — |
| hub 收錄 | — | not-in-hub（hub 檢查被跳過時標註爲 info，不算 warning） |
判定規則：
verdict：0 個 error →pass；有 error →fail；僅 warning →warnchecks字段記錄固定檢查項的執行結果（total / passed / failed / warned / skipped），而非 issue 條數
命名策略上，invalid-name-format 僅表示 npm 格式錯誤；合法的個人 scoped / unscoped 名稱只會產生 non-org-recommended-name（warning）。推薦範圍爲 @deepseek-ai/*、@dsh-external/*、@omdsh/* 和 dsh-*。
hub 檢查與安全模型¶
hub 收錄檢查離線優先：先讀本地 hub catalog（DSH_HUB_SOURCE 或 cwd/hub/），再通過 gh 讀取公開 omdsh-dev/dsh-hub-workshop/catalog.json；兼容 dsh-hub-index/v0.4 與舊 repos[].name 格式。全部失敗時靜默降級爲 skipped，報告如實標註，不記爲 warning。
安裝與啓用¶
推薦通過 Profile Bundle 安裝到 DSH 0.1.1-rc.1（npm）profile。web 與 headless 是不同 profile：dsh run 默認使用 headless，在 web 安裝不會自動覆蓋 headless。
交互式（web）profile：
dsh plugin --profile web add github:omdsh-dev/dsh-plugin-check
一次性任務（headless）profile：
dsh plugin --profile headless add github:omdsh-dev/dsh-plugin-check
包內 dsh.bundle.patch 會在安裝後把插件加入 profile 的 layer stack。缺失的 peer 依賴（cordis、@deepseek-ai/dsh-tools）由 profile 的 healed profiles/node_modules 回退安裝提供。
本地構建後用 tarball 安裝（不依賴 GitHub）：
npm pack
dsh plugin --profile web add <npm pack 產物 tarball 路徑>
驗證是否加載成功：
dsh --profile web --dump-config | grep tool-plugin-check
啓動 DSH（npm 0.1.1-rc.1 線，lib 生產模式）：
npx -p @deepseek-ai/dsh@0.1.1-rc.1 dsh web
典型用法¶
檢查單個插件倉庫：
plugin_check { action: "check", path: "C:/Users/admin/Desktop/dshext/dsh-tool-csv" }
→ {"repo":"dsh-tool-csv","kind":"tool-bundle","verdict":"pass","checks":{"total":24,"passed":24,...}}
掃描父目錄下全部 dsh-* 插件：
plugin_check { action: "scan", path: "C:/Users/admin/Desktop/dshext" }
→ {"root":"...","scanned":11,"reports":[...]}
通過 DSH 會話調用：
dsh run "使用 plugin_check 工具檢查一個插件倉庫"
查看全部檢測項定義：
plugin_check { action: "schema" }
適用場景與注意¶
適合誰
- 插件作者在提交前自檢清單、patch、構建配置與 Profile Bundle 合規性
- CI 或模型工作流中對
dsh-*倉庫目錄跑門禁，拿結構化 JSON 報告 - 維護 hub catalog 前批量
scan父目錄，定位不合規倉庫
使用前注意
- 插件以當前 DSH 進程的權限運行；安裝前應閱讀 GitHub 源碼 與 MIT 許可證
- hub 檢查依賴本地 catalog 或
gh訪問公開倉庫；環境不滿足時 hub 項會skipped，不影響其他檢查 - 舊版 monorepo 集成、不支持 Profile Bundle 的快照，需參考 README「手動安裝與舊版本兼容」段落
- SkillHub 爲獨立社區目錄，與 DeepSeek / 幻方無官方從屬關係
結尾¶
dsh-plugin-check 把組織內實測踩過的清單、patch、構建與 hub 合規問題收斂成可自動執行的只讀門禁。裝好 profile 後，對目標目錄調用 plugin_check 即可拿到 verdict 與修復建議。
