用 dsh-plugin-development 給 DeepSeek Harness 裝上插件開發與審計技能

DeepSeek Harness 插件 DeepSeek DSH 插件開發 界面增強 Agent Skill 2026-08-18 95 閱讀

前言

DeepSeek Harness（以下簡稱 DSH）的核心理念是「一切皆插件」。官方倉庫 deepseek-ai/deepseek-harness 把運行時、工具、界面能力都做成可組合的 Cordis 插件；社區裏也出現了大量可安裝 bundle。動手寫第一個插件時，問題通常不是「會不會寫 TypeScript」，而是分不清三種形態：進程內動態插件、倉庫裏的 workspace 包、以及用 dsh plugin 裝進 profile 的外部 bundle。三種形態的源碼格式、加載路徑、驗收證據都不一樣，把一種規則套到另一種上，很容易寫出能編譯、卻裝不進去或無法卸載的包。

dsh-plugin-development 就是爲這件事準備的。它不是又一個改網頁皮膚的界面插件，而是一份可移植的 Agent Skill：把設計、實現、打包、審查和診斷 DSH 插件的流程寫進 SKILL.md，讓 Codex、Claude Code 和 DSH 共用同一份規範。倉庫另外提供一個可選的 DSH bundle 適配器，方便用 dsh plugin 做 profile 級安裝和卸載。本文按社區目錄頁、GitHub README、package.json、SKILL.md 和 v0.2.0-beta.1 發行說明交叉覈對後整理。

這是什麼

dsh-plugin-development 由 GitHub 用戶 w2112515 維護，許可證爲 MIT。社區目錄 deepseek-harness-plugin.com 把它歸在「界面增強」，收錄時標註的安裝命令是 dsh plugin add github:w2112515/dsh-plugin-development。GitHub 倉庫創建於 2026-08-14，截至 2026-08-17 有 10 顆星，當前包裝版本是 0.2.0-beta.1（預發佈）。

倉庫 README 把產品邊界寫得很清楚：真正維護的是一份符合 Agent Skills 規範 的 canonical Skill 目錄 skills/dsh-plugin-development；index.js 和 cordis.patch.yml 只是薄適配層，把這份 Skill 註冊進 DSH 的 ctx.skills。它不引入 MCP 服務，也不依賴賬號、密鑰或遠程接口。項目聲明自己是 Beta、非官方社區項目，與 DeepSeek 沒有從屬或背書關係；DSH 目前仍處於 developer preview，插件清單、類型和 Loader 行爲以當前 DSH 倉庫爲準，而不是以這份 Skill 的記憶爲準。

它解決的是這類任務：

  • 在活的 DSH 進程裏用 cordis_define / cordis_run 做動態 Cordis 插件
  • 改 DSH 倉庫 packages/ 下隨發行版一起走的 workspace 插件
  • 給外部包補上 dsh.bundle 和 cordis.patch.yml，做成可安裝 bundle
  • 審查 Loader 導出、Service / Provider / Consumer 歸屬、Client Slot、CLI 表面、配置、生命週期和 profile 合成

明確不做的事：市場上架、整合包、dsh.pack.json、dsh-plugin-pack。那一類工作屬於另一個倉庫 dsh-marketplace-publish。

核心功能

先分類，再寫規則

SKILL.md 要求助手在動手前先判定插件模式，不要把一種模式的規則直接搬到另一種上：

模式 典型信號 完成時要拿出的證據
動態運行時 Cordis 插件 cordis_define、cordis_run、活的 Host / Client、Slot、@pluginId 現場 Provider 與 Slot 檢查、define/run 狀態、最終診斷
DSH workspace 插件 目標在 packages/ 下，作爲 DSH 倉庫能力一起發佈 當前倉庫權威文件、針對性測試、真實 Loader 合成、生命週期證明
可安裝 DSH bundle dsh.bundle、cordis.patch.yml、dsh plugin、npm / tarball 打包文件列表、隔離 profile 安裝、--dump-config、打包入口啓動與清理證據

模式選錯時，產物會完全不同。證據不夠、三種模式會寫出不同文件時，Skill 要求只問一個問題：結果應該是進程內的、隨 DSH 倉庫發佈的、裝進 profile 的，還是市場上的整合包。

固定工作流：發現到彙報

選定模式之後，流程是固定的六步：

  1. 發現：看目標、當前配置、鄰近實現、倉庫狀態和真實加載路徑。
  2. 規劃組件：找出消費者、當前所有者、需要的插件角色、配置所有者、生命週期所有者、可觀察結果和證據。跨角色時用一張簡表。
  3. 敲定決策：入口與前置條件、動作與輸入、結果或狀態、失敗與恢復、清理、對模型可見的副作用、授權邊界。
  4. 實現：只改必要組件，並按所選模式更新對應文檔。
  5. 驗證：走真實的動態工具、Loader、打包或消費者入口；靜態檢查不能代替這條路徑。
  6. 彙報：先寫結果、所選模式、改動或審計發現、實際跑過的檢查、未關閉風險和下一步。

授權也一次性寫死：問答、審查、診斷默認只讀；創建和修復可以改本地文件並跑非破壞性檢查；發佈、外部寫入、破壞性刪除、執行不可信依賴的安裝期腳本，必須先確認。

三種模式各自卡什麼

動態插件只存在於當前進程。參考文檔要求先檢查活的 Host / Client Provider，再用 cordis_define 定義不可變包、用 cordis_run 激活。函數體必須是普通 JavaScript，不能用 import、require、TypeScript 或 JSX；Client 側用 React.createElement，UI 只能掛到查詢到的 Slot。沒有現場 cordis_inspect_* 工具時，Skill 只允許做設計和診斷，並明確寫出哪些激活結果尚未覈實，不能假裝插件已經跑起來。

workspace 插件跟 DSH 倉庫走，權威來源是當前 checkout 裏的文檔、類型和 Loader，而不是教程裏抄來的舊清單。

可安裝 bundle 是 profile 上的一層配置，不是 profile 本身。package.json 裏聲明 dsh.bundle.patch，profile 的 dsh.profile.bundles 由 dsh plugin 維護，不要手改。這個倉庫自己的適配器就是這種形態：package.json 指向 ./cordis.patch.yml，補丁插入一行 id: dsh-plugin-development-skill、name: dsh-plugin-development。index.js 讀打包進去的 SKILL.md frontmatter，調用 ctx.skills.register()；卸載時只撤銷這次註冊，不會刪除用戶另外裝到個人目錄或項目目錄裏的 Skill 副本。項目本地的同名 Skill 仍可按宿主發現規則覆蓋這次運行時註冊。

自帶的靜態預檢腳本

Skill 目錄裏有隻讀腳本 scripts/check-artifact.mjs，給插件作者做早期檢查，不能當成完成證據：

node skills/dsh-plugin-development/scripts/check-artifact.mjs workspace-function path/to/index.ts
node skills/dsh-plugin-development/scripts/check-artifact.mjs bundle path/to/package
  • workspace-function：檢查 workspace 函數插件源文件
  • bundle：檢查 package.json、dsh.bundle.patch 和補丁文件是否對得上

bundle 模式的參考文檔寫明：它不能證明 npm 打包文件列表、運行時模塊解析、補丁語義、profile 優先級或啓動行爲。發佈前仍要在隔離 profile 裏安裝真實產物，跑 dsh --profile --dump-config，再驗證註冊、Fiber 清理和卸載。

安裝與啓用

社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端裏運行：

dsh plugin add github:w2112515/dsh-plugin-development

如需可復現安裝，目錄頁建議固定 commit：

dsh plugin add github:w2112515/dsh-plugin-development#commit

把 commit 換成已經審過的 SHA，不要釘會移動的分支。

倉庫 README 把 DSH 適配器寫成可選路徑，只在希望由 dsh plugin 管理 profile 安裝、版本、合成和卸載時使用。當前發行是 v0.2.0-beta.1，上一個 v0.1.0-beta.1 保持不可變。推薦用發行 tarball：

dsh plugin --profile web add https://github.com/w2112515/dsh-plugin-development/releases/download/v0.2.0-beta.1/dsh-plugin-development-0.2.0-beta.1.tgz
dsh --profile web --dump-config

導出的配置裏應出現 dsh-plugin-development 這一層，以及行 ID dsh-plugin-development-skill。也可以釘標籤從 Git 安裝；適配器是普通 JavaScript 和 Markdown，沒有 prepare、install 或 postinstall：

dsh plugin --profile web add github:w2112515/dsh-plugin-development#v0.2.0-beta.1

本地開發適配器時，在倉庫根目錄執行：

dsh plugin --profile web add .

不經過 bundle、只把 Skill 目錄交給宿主發現也可以。DSH 會從項目下的 .dsh/skills/dsh-plugin-development、.agents/skills/dsh-plugin-development 或 skills/dsh-plugin-development 讀取同一份目錄。.agents/skills 可與 Codex 共用。Codex 還可裝到 ~/.codex/skills/dsh-plugin-development，用 $dsh-plugin-development 顯式調用；Claude Code 可裝到 ~/.claude/skills/dsh-plugin-development 或項目內 .claude/skills/dsh-plugin-development，用 /dsh-plugin-development 調用。倉庫刻意沒有 .codex-plugin / .claude-plugin，這兩個宿主都不需要再包一層插件才能用這份 Skill。

package.json 聲明運行環境爲 Node.js ^22.19.0 || >=24.0.0。倉庫自檢命令是：

npm test
npm pack --dry-run

有一份已構建的 DSH checkout 時，還可以跑：

node scripts/verify-dsh-runtime.mjs path/to/deepseek-harness

典型用法

裝好之後，直接向當前助手描述 DSH 插件任務即可。Skill 的 description 會匹配設計、創建、修改、打包、安裝、審查、審計、診斷這類請求；也可以在 Codex 裏寫 $dsh-plugin-development，在 Claude Code 裏寫 /dsh-plugin-development。

下面是 README 和 SKILL.md 裏能直接復現的用法，不是虛構案例。

  1. 先讓助手判定模式。 例如：「給當前 DSH 進程加一個 Client Slot 面板」應走動態運行時；「改 packages/ 裏某個隨倉庫發佈的包」應走 workspace；「把這個外部 npm 包做成 dsh plugin add 能裝的 bundle」應走可安裝 bundle。如果其實是整合包或目錄上架，助手應按 Skill 要求停下來，改用 dsh-marketplace-publish。

  2. 動態插件按現場工具走。 參考文檔給出的順序是：cordis_inspect_list 列出 Provider → 只查詢會用到的 Service / Event / Slot / Tool → 已有 @pluginId 時用 cordis_inspect_self 讀源碼和診斷 → cordis_define 定義包 → cordis_run 激活。awaiting-approval 和 starting 都不是成功，這一輪應結束等待系統引導，而不是在同一回合裏輪詢。停用走 cordis_stop；cordis_undefine 是破壞性刪除，需要明確授權。

  3. bundle 先做靜態預檢，再裝隔離 profile。 在包根目錄運行上面的 check-artifact.mjs bundle，然後 npm pack --dry-run 看打進去的文件是否包含補丁和運行時入口、是否混入密鑰或本機文件。真正驗收要按發行說明：把精確 tarball 裝進一次性 DSH home，檢查 --dump-config，加載已安裝入口，驗證註冊、銷燬和卸載。不要爲了取證去覆蓋用戶正在用的 profile。

  4. 審查請求默認不改代碼。 把倉庫或補丁交給助手做審計時，Skill 要求只檢查並彙報，除非請求裏同時要求修改。

適用場景與注意事項

適合這些人：

  • 要在 DSH 裏寫第一個插件，但分不清動態插件、workspace 包和 bundle
  • 已經有一個外部包，想按當前 DSH 的 dsh.bundle 合同打包、安裝和卸載
  • 需要審查別人的 DSH 插件：Loader 導出、依賴注入、生命週期、Git 安裝是否會執行構建腳本
  • 同時用 Codex / Claude Code / DSH，希望三份宿主讀同一套插件開發規範

不適合、或者說會主動拒絕的任務：做市場上的整合包、把教程或過期 Agent Note 當成當前 API、在沒有現場 Cordis 工具時聲稱動態插件已經運行。

使用前注意下面幾點。

插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。目錄頁和倉庫都要求先檢查源碼與許可證。本倉庫適配器沒有安裝期腳本，但這隻說明這一份包的聲明；第三方依賴仍要單獨看。Git 安裝若帶 prepare 構建，等於允許在本機執行依賴代碼，需要明確授權，並釘 commit。

DSH 和這份 Skill 都還在預覽 / Beta。Skill 明確禁止用記憶中的包列表或教程清單覆蓋當前倉庫裏的可執行約束；文檔和實現衝突時必須同時引用兩邊，不能 silently 調和。社區插件目錄是獨立站點，不是 DeepSeek / 幻方的官方應用商店。

卸載 bundle 只會撤銷適配器註冊的那條 Skill，個人目錄或項目目錄裏另行放置的 dsh-plugin-development 不會被刪掉。

小結

dsh-plugin-development 把 DSH 插件開發裏最容易混的三件事分開了：進程內動態插件、倉庫 workspace 包、profile 可安裝 bundle，並給審查和診斷補上「證據是什麼」而不是「代碼能不能編譯」。同一份 Skill 目錄可以給 Codex、Claude Code 和 DSH 用；可選的 bundle 適配器只負責把它註冊進當前 profile，並在卸載時乾淨地撤掉。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-plugin-development/

GitHub：https://github.com/w2112515/dsh-plugin-development

相關文章

快速從零部署一個DeepSeek-R1服務 2025-04-05 使用 dsh-anchored-standard 爲 DeepSeek Harness 配置兩階段 Agent 預設 2026-08-17 用 dsh-web-ui 把 DeepSeek Harness 網頁界面補成工作臺 2026-08-17 用 modlens 給 DeepSeek Harness 的純文本模型補上視覺 2026-08-17 用 dsh-TUI 給 DeepSeek Harness 補上全屏終端界面 2026-08-17
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜