前言¶
在 DeepSeek Harness（DSH）裏做 bundle 插件，常見摩擦不在「能不能寫工具」，而在三個時間點：從零開目錄時缺 manifest、patch、測試與 CI；本地能跑，貼進 Plugins 卻被 incompatible-version 或 patch 結構擋住；別人給的 npm 包或 GitHub 鏈接，裝進 profile 前沒有隻讀手段先看 tarball 哈希、install 腳本與兼容性。手動對照 @deepseek-ai/dsh-app-boot 的規則既慢又容易漏。
下面介紹維護者 Joker2377 發佈的 dsh-plugin-devkit（GitHub：Joker2377/dsh-plugin-devkit，社區目錄分類 admin-security）。它是純 host 端插件：沒有 UI、沒有常駐服務、不改 profile，提供三支工具對應插件生命週期的三個時刻，同一套邏輯也包成 CLI，不安裝 DSH 插件也能在取得源碼後用 node scripts/cli.mjs 調用。
這是什麼¶
一句話：用一個指令生成可測試的插件骨架，用 doctor 復現 DSH 安裝時的結構與兼容性判定，用 audit 在把別人包裝進 profile 之前做只讀供應鏈覈查。
| 工具 | 作用 |
|---|---|
plugin_scaffold |
開插件骨架；產物預期能跑、能過測試、能通過 doctor |
plugin_doctor |
讀本地目錄，說出 DSH 安裝時會被哪一條攔下 |
plugin_audit |
讀已發佈包 spec，判斷現在裝進 profile 是否合理 |
運行環境要求（README 原文）：Node.js >=22.19，DeepSeek Harness >=0.1.1-rc.2 <0.3.0；純 JavaScript，無原生模塊。包版本在 package.json 中爲 0.2.0，許可證 MIT。
核心功能¶
骨架一次到位¶
plugin_scaffold 會產出 package.json（含 dsh.bundle.patch）、cordis.patch.yml、入口 lib/index.js、工具定義 lib/tools.js、示例測試 test/bundle.test.mjs、面向使用者的 README.md、LICENSE、.gitignore 以及 .github/workflows/test.yml。骨架自帶一個工具與測試，README 說明 npm test 不需安裝依賴即可通過。目標文件已存在時默認跳過並回報，可用 dryRun 先看會寫哪些文件。
與 DSH 安裝一致的 doctor¶
plugin_doctor 只讀檢查 manifest、patch（含 insert 合法性）、入口 apply、README 是否含安裝段、LICENSE、測試與 CI 等。兼容性規則與 host 一致：存在 engines.dsh 時只看它；否則逐條檢查 @deepseek-ai/dsh* peers；prerelease 參與比較（例如 0.3.0-rc.5 落在 <0.3.0 內）。未傳 hostVersion 時不做兼容性判定。
安裝前 audit（供應鏈）¶
plugin_audit 回答「別人寫的包現在裝進我的 profile 可不可以」：比對 tarball 哈希、掃 install 腳本（含 tarball 內依賴的 preinstall / install / postinstall）、依賴面與 provenance、判 engines.dsh 兼容性、比對 profile 內版本等。只讀：不寫文件、不安裝、不執行包代碼。allow 只代表已覈查的供應鏈信號對得上，不代表代碼無惡意行爲。
安裝與啓用¶
官方方式是在 DSH 側邊欄 Plugins 貼倉庫首頁網址並 Install，然後重新加載 App。步驟如下。
1、複製倉庫網址：
https://github.com/Joker2377/dsh-plugin-devkit
2、在 Plugins 安裝欄貼上上述網址，按 Install。
3、重新加載 App 後，對話中可使用 plugin_scaffold、plugin_doctor、plugin_audit。
注意：須貼倉庫首頁網址；形如 https://github.com/.../tree/main 的頁面會被拒絕（a URL must point at a git repository or a tarball）。
不安裝插件時，在取得源碼後可用：
node scripts/cli.mjs doctor <目錄>
node scripts/cli.mjs audit <spec>
CLI 與三支工具共用同一核心；也可使用 bin 名稱 dsh-plugin-devkit（見 README 命令行一節）。
典型用法¶
開一個新插件¶
在對話中請 agent 使用 plugin_scaffold 建立例如 dsh-foo，確認名稱與目錄後，先做本地驗證：
cd dsh-foo
npm test
node scripts/cli.mjs doctor .
再將 lib/tools.js 中的示例工具換成實際需求，在 README 安裝段補上你的倉庫網址，推送到 GitHub 後即可用相同「貼首頁 URL」方式分發。
命令行等價示例：
dsh-plugin-devkit scaffold dsh-foo --desc "一行說明" --author "你的名字"
dsh-plugin-devkit scaffold dsh-foo --dry-run
檢查本地 bundle¶
工具調用示例（README）：
plugin_doctor(dir: "C:/path/to/dsh-foo", hostVersion: "0.2.1-rc.5")
命令行：
dsh-plugin-devkit doctor . --host-version 0.2.1-rc.5
dsh-plugin-devkit doctor . --json
結束碼：0 通過，1 有 error，2 指令本身失敗。
安裝前核查遠端包¶
適用時機包括：貼未知 npm 或 GitHub 插件進 Plugins 前、大版本升級前、或收到 github:owner/repo 想先看兼容性。
node scripts/cli.mjs audit lodash@4.17.21
node scripts/cli.mjs audit dsh-foo-bar@^0.2 --host=0.2.1-rc.5 --json
node scripts/cli.mjs audit github:owner/repo --registry=https://registry.npmmirror.com
audit 結束碼：0 allow，1 block，2 參數或環境問題，3 not-audited（例如部分 spec 無 registry 側數據，不能當成通過）。報告第一行爲 spec，第二行爲 可以安裝 / 不可以安裝 / 未覈查；未給 hostVersion 且環境無 DSH_VERSION 時，兼容性項目不會被算作通過。
適用場景與注意¶
適合誰： 正在維護 DSH bundle 插件的開發者，以及需要在 profile 裏引入第三方包、希望先對齊 DSH 安裝規則與基本供應鏈信號的管理員場景。
權限與信任： 與其他 DSH 插件一樣，devkit 在當前 DSH host 進程權限下運行；plugin_audit 雖不執行對方代碼，但會從 registry 讀取 tarball。安裝任何插件前仍應自行查看源碼與 LICENSE，並理解 audit 的界限（非沙箱、非完整惡意代碼分析）。
疑難排解（README 摘要）： DSH 沙箱內若 npm test 出現 spawn EPERM，可改 npm run test:sandbox 或直接 node test/bundle.test.mjs；安裝被拒 incompatible-version 時，用 plugin_doctor(hostVersion: ...) 對照是哪一條範圍；工具未出現時確認已重載 App 並用 doctor 檢查 patch insert。
結尾¶
dsh-plugin-devkit 把「開骨架、對齊安裝規則、裝別人包前先讀 registry」收進三支 host 工具與同一 CLI，規則來源對應 DSH 實際的 unmetRequirements() 與 bundle patch 檢查，而不是主觀 lint 清單。
