本週建議：先用 1 天確認插件場景與邊界，再用 2–3 天完成單一能力的最小插件；不要一開始就做複合套件。 DeepSeek Harness 插件開發應先區分工具、模型提供方、介面功能與工作流編排，再從最小可驗證單元開始。由於官方目前仍標示為開發者預覽，架構與 API 可能出現破壞性變更，配置、權限及相容性驗證必須獨立交付。官方 README 也明確提醒預覽期會有相容性破壞變更，詳見官方 README。

本文適合三類讀者：需要把內部腳本封裝成 DeepSeek Harness 工具的 AI Agent 工程師；需要接入自訂模型端點或團隊閘道的平台開發者；以及負責統一遠端開發環境與插件驗收流程的技術負責人。

提醒： 截至 2026 年 8 月 18 日，本文只依照官方 master 分支、官方架構文件、開發指南、package.json 與 Cordis 官方專案核對。具體插件 API、目錄約定及指令，日後應以你實際驗證的提交或套件版本為準。

01

先把擴展目標切成四種插件邊界

DeepSeek Harness 採用「一切皆為插件」的設計。官方架構文件指出，模型適配器、工具註冊、工作階段紀錄、Agent 循環與 Web 應用程式都可以由插件組成；Cordis 則負責把服務、型別事件與可回復效果掛載到共享上下文。相關判斷可參考官方架構文件。

你可以先用下面的分類判斷插件邊界：

擴展場景 適合承載的能力 建議是否獨立插件 主要成功信號
工具呼叫 搜尋、檔案操作、內部 API、資料庫查詢 是 工具可載入、可發現、錯誤可診斷
模型提供方 API Key、端點、模型目錄、路由策略 是 模型可選取，請求能通過，失敗原因清楚
介面功能 Web UI 按鈕、面板、工作階段操作 通常是 瀏覽器資源可建置，遠端呼叫可驗證
工作流編排 profile、插件依賴、配置覆蓋層 以組合為主 不改程式碼即可切換執行組合

如果能力有不同權限、不同失敗方式或不同更新週期，就拆成多個可獨立啟停的插件；如果只是同一工具的純邏輯步驟，才保留在單一插件內。

例如，「讀取 Git 差異」和「將差異送到外部審查服務」不一定要綁成一個套件。前者需要本機檔案權限，後者需要網路與憑據。拆開後，你可以在唯讀 profile 中啟用前者，在受控 profile 中才啟用後者。這比依靠提示詞提醒 Agent「不要寫入檔案」更可靠，因為真正的工具面與權限面已經被分開。

02

工具插件先做最小可驗證結構

如果你的目標是把內部腳本封裝成 DSH 工具，第一版不要同時加入 Web UI、模型路由與複雜工作流。先完成一個輸入契約明確的工具，讓它能被載入、被發現，並在失敗時回傳可追查訊息。

社群常把這類專案標記為 dsh-plugin，但標籤只利於發現，不代表官方保證相容。你仍應以官方文件和實際 profile 啟動結果為準。

dsh 插件最小目錄結構怎麼安排？

目前官方專案採用 TypeScript、Host 與 Client 分離的建置面；普通 Client 插件可在 Client 階段產生 Node loader 與瀏覽器資源，而涉及遠端服務的特殊套件則需要更嚴格的建置順序。相關細節可對照官方開發指南。

對外部工具插件而言，建議先維持以下概念結構，再按當日官方範例調整檔名：

my-dsh-tool/
├── package.json
├── src/
│   ├── index.ts
│   ├── tool.ts
│   └── types.ts
├── test/
│   └── tool.test.ts
├── tsconfig.json
└── README.md

package.json 應負責描述套件入口，以及官方要求的 DSH 註冊欄位；src/index.ts 負責插件入口；tool.ts 只處理工具註冊與執行邏輯；types.ts 保存輸入輸出契約；測試則驗證正常輸出與錯誤路徑。不要把 API Key、工作區絕對路徑或個人設定寫入 README.md 範例以外的程式碼。

目前官方根專案的 package.json 將套件管理器、Node.js 引擎條件、workspace 路徑與建置腳本集中管理。你可以用官方 package.json核對當日的版本與執行條件，但不要把根專案的所有 workspace 設定原封不動複製到獨立插件。

工具插件的三個成功信號

  1. 插件可被載入：啟動時沒有 loader、套件入口或依賴解析錯誤。
  2. 工具可被發現：Agent 的工具清單或開發者檢查介面中，能看到穩定的工具名稱與描述。
  3. 錯誤可診斷：缺少輸入、權限不足、外部 API 失敗時，回傳錯誤類型、操作名稱與下一步，而不是只顯示模糊的「failed」。

回退方式也要同步設計。若工具需要寫入檔案，第一版先提供唯讀模式；若外部服務無法連線，回傳結構化錯誤並保留原始輸入；若插件載入失敗，從指定 profile 移除插件，而不是直接修改全域配置。

若你只需要新增一個可呼叫能力，就選工具插件；若同時需要模型路由或 UI 控制，先拆成多個插件，再用 profile 組合。

03

模型提供方插件要把憑據隔離在配置層

模型插件與普通工具插件的責任不同。工具插件通常接收 Agent 輸入並回傳結果；模型提供方插件則需要處理端點、模型名稱、認證、串流與錯誤重試。兩者混在一起，測試時很難判斷問題到底來自工具契約還是模型連線。

官方開發指南示範以環境變數或被 Git 忽略的 .env 管理 DEEPSEEK_API_KEY，並支援以 DEEPSEEK_BASE_URL 指向自訂端點；沒有設定金鑰時，真實 API 的端對端測試會跳過。

配置項目 可放置位置 不應放置位置 驗證方式
API Key 環境變數、受控密鑰管理 原始碼、測試 fixture、公開 README 啟動時確認存在，不輸出完整內容
API 端點 profile 配置或環境變數 寫死在工具函式內 以健康檢查或最小請求確認
模型目錄 配置層、模型插件 各工具內重複定義 顯示可選模型並測試未知模型錯誤
權限與重試 profile 或插件設定 只寫在提示詞 以拒絕、超時與回退案例測試

模型提供方插件的成功信號，不是「畫面上出現模型名稱」而已。你至少要確認：無效金鑰不會被誤報為模型不存在；端點逾時會顯示網路錯誤；模型不支援某種工具呼叫時，能回退至明確的錯誤處理。

在團隊環境中，建議把 dev、test 和 task 的端點配置分開。測試 profile 使用假的或受限端點，持續任務 profile 才注入正式憑據。這能避免工程師把正式金鑰帶入本機除錯流程。

04

Web UI 插件必須先處理 Host 與 Client 邊界

介面型插件的難點不在於畫一個按鈕，而在於你必須確認哪段程式在 Host 執行，哪段程式在瀏覽器執行。官方開發指南將專案分成 tsconfig.host.json 和 tsconfig.client.json 兩個 aggregate，原因是兩邊對 Cordis Context 的宣告合併不同，直接混在同一個 TypeScript 程式中可能產生衝突。

因此，涉及 Web UI 的插件應依照以下順序驗證：

  1. 先確認 Host 端服務與資料型別能通過型別檢查。
  2. 再確認 Host 建置產生瀏覽器端需要的遠端契約。
  3. 然後建置 Client 資源與 Web 應用程式。
  4. 最後在瀏覽器確認按鈕、面板與遠端呼叫。

官方建置順序目前是先建置 Host TypeScript，再執行 Host tsdown；接著建置 Client TypeScript、Client tsdown，最後建置 Web。這個順序應直接對照你使用的 master 分支，因為預覽期腳本名稱與輸出位置都可能調整。

如果你的 UI 只是顯示本地 session 資料，回退方案可以是保留 CLI 工具，不讓 UI 失敗阻斷核心功能。如果 UI 依賴遠端接口，則應提供「服務不可用」狀態，而不是讓整個頁面白屏。你也可以先參考本站的 DeepSeek Harness Web UI 故障排查，把瀏覽器 Console、Host 日誌與 profile 配置分開記錄。

05

工作流用 profile 組合，不要複製整個工程

工作流場景最容易失控。很多團隊會為「試驗版、測試版、正式版」各複製一份插件專案，結果三份程式逐漸分叉，修正一個權限問題要同步修改多個目錄。

官方架構文件把 profile 定義為儲存在 Harness home 的命名組合，會列出要堆疊的 bundles、外部插件與自己的 cordis.patch.yml；web 和 headless 則是隨附的模板。配置層會依序套用 bundle、profile patch、home 層及命令列 overlay。

DeepSeek Harness 插件怎麼載入到指定 profile？

先不要猜測目錄位置。依官方架構，應把插件安裝或加入指定 profile，再用配置傾印確認實際啟動樹：

dsh plugin --profile web add <plugin>
dsh --profile web --dump-config

上面的插件安裝語法應以你當日使用的 CLI 版本和官方插件指南為準；若命令在預覽版本中改名，優先採用該版本 README 的寫法。官方架構文件確認了 --profile web 和 --dump-config 的 profile 檢查方式，但社群插件的安裝行為不能視為官方承諾。

建議保留至少三個 profile：

  • 試驗 profile：允許快速換模型、換工具與調整 UI。
  • 測試 profile：固定插件版本、端點與權限，供 CI 或驗收使用。
  • 持續任務 profile：只保留已通過驗收的插件，避免測試功能干擾長時間任務。

決策條件如下：

  • 若插件只在單一工作流使用，選獨立 profile；否則回退到共用基礎 profile。
  • 若兩個插件需要不同權限，選分開啟用；否則回退到同一套件內的純函式模組。
  • 若配置需要經常覆蓋，選 profile patch；若每次都要改原始碼，回退並重新檢查插件邊界。
  • 若插件更新可能影響全隊，選固定版本或提交；若只是本機試驗，才使用未固定來源。

需要注意的是，官方文件指出 patch 會以整行配置取代原有配置，而不是自動深度合併。這代表你在覆蓋某個插件設定時，可能意外遺失原本欄位。因此每次改 patch 都要重新執行 --dump-config，檢查端點、權限、依賴與插件順序。

06

交付前用五步完成相容性驗收

預覽期插件開發不能只測「本機能跑」。你要把環境、建置、權限、乾淨安裝與回退都納入驗收。

第一步：固定驗證基線

記錄官方 master 提交、插件套件版本、Node.js 版本、pnpm 版本及復核日期。官方開發指南目前列出 Node.js 22.19 以上及 24 為支援範圍，CI 另涵蓋 22.19、24 與 26；這類條件可能隨專案更新，不能永久視為固定規格。正式提交前，也應按照官方貢獻指南核對分支、檢查與提交要求，避免插件本身可運作，卻在團隊交付流程中被退回。

第二步：完成型別與建置檢查

至少執行：

pnpm install
pnpm run typecheck
pnpm run build

如果你是獨立插件，則依插件自己的 package.json 執行對應的 TypeScript 型別檢查、單元測試及建置指令。不要直接複製官方主專案的所有腳本，先確認你的插件是否真的需要 Host、Client 或遠端契約。

第三步：驗證最小執行路徑

測試正常輸入、空輸入、格式錯誤、外部服務超時、權限不足及插件缺失。工具插件要確認工具可發現；模型插件要確認端點與模型可選取；UI 插件要確認瀏覽器資源與 Host 遠端呼叫都能完成。

第四步：做權限與秘密檢查

確認 API Key 不在 Git 差異、建置產物、測試輸出或錯誤訊息中。把檔案、Shell、外部網路與資料庫權限逐項列出。沒有必要的權限不要預先開啟，因為插件架構的優勢正是可以按 profile 組成不同能力面。

第五步：用乾淨環境安裝並演練回退

在沒有既有插件、沒有本機快取、沒有個人 patch 的環境中安裝。測試卸載、停用、切回上一個 profile，並確認核心 Agent 仍能啟動。若插件失敗會令整棵插件樹無法載入，就應把該問題列為發佈阻斷項，而不是只在文件中提醒使用者手動刪檔。

插件發佈前需要測試哪些能力？ 至少包括載入、發現、輸入輸出契約、錯誤可診斷性、權限邊界、憑據隔離、乾淨安裝、卸載回退及不同 Node.js 條件下的建置結果。若插件涉及 Web UI，再加上 Host/Client 建置順序、遠端接口與瀏覽器資源驗證。

07

建立可長期保留的開發環境

如果你每週只修改一次工具，直接在本機開發通常足夠。但當插件需要頻繁建置、多人共用測試 profile，或要長時間保留一套可重現的 Node.js、pnpm、Git 與 TypeScript 環境時，遠端 Mac 的價值會轉向「環境一致性」而不只是算力。

你可以先閱讀本站的 AI Agent 插件開發環境驗收 與 雲端 Mac 持續開發環境配置，再按插件建置耗時、測試頻率、協作人數與是否需要長時間保留工作區作決定。

若你目前的方案是多人共用本機 Mac、臨時伺服器或一次性雲端工作站，常見缺點是 Node.js 與 pnpm 版本不一致、profile 被直接覆蓋、插件快取污染乾淨測試，以及環境關閉後無法保留完整上下文。這些問題會把真正的相容性風險藏在「某個人的電腦可以跑」背後。

當你的 DeepSeek Harness 插件已經進入持續建置、反覆測試或團隊協作階段，租用 VpsMesh 的 Mac 開發環境會更適合用來保留固定工作區、遠端連線與可重複驗收流程；但若你需要長期滿載運算、實體 USB 設備或特殊本地網路，直接購買並管理自己的 Mac 仍然更合理。真正值得租用的情況，是你需要一套可隨時接入、可按週期保留、又不必先承擔長期硬體管理成本的插件開發環境。