使用 DeepSeek Harness Creator 構建小型外掛
DeepSeek-V4 Team · 2026年10月8日 · 10 min read
第一個 Harness 外掛，最好只承擔一項職責，並且讓結果一眼可見。顯示固定專案清單的面板，就比同時修改檔案、呼叫外部服務、管理憑證的擴充套件更適合入門。小版本能穩定工作後，後續變化才有可比較的基礎。
2026 年 10 月 3 日釋出的 Harness dsh-v0.2.1-alpha.1 在外掛管理器中新增了 Creator 入口，可以帶著草稿進入外掛建立流程。下面依據該版本文件，說明如何提出需求、檢查程式碼並驗收一個本地外掛。這是一套供讀者執行的驗收練習，並非已經在 Harness 中執行透過的成品外掛。
準備一個便於檢查的工作區
先確認安裝的 Harness 版本，配置模型提供方，再為練習準備一個空目錄。尚未安裝的讀者，可以先完成本地快速入門。不要直接拿重要專案的唯一副本做試驗。
預期產物應包含外掛原始碼目錄，以及針對當前 Harness 版本的載入說明。要求智慧體解釋包入口、依賴和外掛包（bundle）配置，不要把“生成了一個 TypeScript 檔案”當成“已經可以從外掛管理器安裝”。
把第一版的驗收目標限定為一個名叫 Project checklist 的面板，顯示三行固定內容。暫時不做檔案自動發現或狀態儲存。它們可以以後新增，但每增加一項能力，就多一組需要檢查的行為。
開啟 Creator，先看草稿再傳送
在側邊欄開啟 Plugins，點選 Add plugin 旁邊的箭頭，然後選擇 Let the agent create a plugin。外掛管理器參考文件說明，該入口由相應的預設介面外掛提供。
進入 Creator 並不等於已經開始生成。傳送前，檢查當前工作區，以及草稿中沿用的檔案、資料夾或會話引用。一箇舊目錄引用，就可能讓智慧體誤判應該修改哪個專案。
可以從下面這段需求開始：
在這個空工作區建立本地 Harness 外掛。以這裡實際安裝的 Harness 版本為目標，選擇 API 前先查閱可用文件。新增名為 Project checklist 的面板，只顯示三行固定內容：Review inputs、Inspect output、Record result。不使用網路請求、憑證、自動檔案寫入或後臺計時器。編輯前列出計劃建立的檔案；完成後解釋如何載入本地外掛包和禁用它，並說明哪些驗證沒有實際執行。
這些約束讓練習保持簡單，也便於發現多餘依賴。一個靜態面板，通常沒有引入 HTTP 客戶端或排程服務的必要。
安裝前，讀懂生成的檔案結構
官方第一個 Cordis 外掛教程介紹了基礎模型：外掛匯出 apply 函式，透過傳入的上下文註冊能力。因此，檢視 apply 如何使用上下文，是理解生成程式碼的合適起點。
不過，入門示例不等於完整的可分發 UI 外掛包。對於這個面板，應要求智慧體從真正的入口檔案，解釋到註冊與渲染程式碼。每個原始檔為什麼存在，都應該有清楚的答案，而不需要先閱讀一套無關框架的教程。
還要檢查包清單和安裝指令碼：依賴是否必要，引用的檔案是否存在，命令是否在正確目錄執行。如果智慧體聲稱構建透過，應保留實際命令和退出結果。對構建過程的解釋不能代替真實輸出。
| 檢查項 | 應看到的證據 |
|---|---|
| 入口 | 包清單或外掛包配置指向實際存在的檔案 |
| 面板註冊 | 能指出哪處呼叫把外掛接入可見介面 |
| 依賴 | 每個新增包都有明確用途 |
| 生命週期 | 禁用外掛後，其介面元素能完整移除 |
| 驗證 | 列明執行命令、結果和未測試的部分 |
安裝本地外掛包，核對載入版本
回到 Plugins → Add plugin。除了包倉庫和 Git 來源，管理器也接受絕對本地路徑。填寫生成說明中標明的外掛包根目錄，不要隨意選擇一個恰好含有原始碼檔案的子目錄。
閱讀安裝預覽和信任提示，隨後安裝並啟用對應外掛包或外掛行。外掛管理器中的已安裝專案，與 Settings 中的內建外掛清單不是同一列表。如果面板沒有出現，先檢查相應外掛行是否啟用，再修改原始碼。
在測試記錄中保留包標識和顯示版本。十月版本改進了版本顯示和程式碼來源資訊；如果實際載入的還是舊包，正確修改也可能看起來沒有生效。開發目錄監聽與更換已安裝包版本是兩種情況，後者仍然需要重啟。
完整測試一次啟用、禁用和過載
先啟用外掛，檢查面板是否出現、三行內容是否齊全、順序和文字是否與需求一致。然後禁用，確認面板消失。再次啟用時，應只出現一個面板，不能有重複入口或殘留元素。
接著按該外掛包的開發說明，修改原始碼中的一行文字，觀察面板是否更新。如果沒有更新，先確認載入的原始碼路徑及重啟要求，不要立即讓智慧體重寫整個元件。
最後重新開啟應用，重複可見結果的檢查。記錄哪些步驟直接生效，哪些需要重啟。這些資訊比一張成功截圖更能說明外掛生命週期是否正常。
按故障發生的環節排查
面板不出現，可能是包路徑沒有解析成功、外掛包未啟用、註冊失敗，也可能是渲染失敗。按這個順序檢查更容易縮小範圍。Cordis 入門文件特別提醒，啟動早期的路徑解析錯誤有時不明顯；新增入口看起來毫無反應時，應先檢查路徑拼寫。
參考舊示例時，還要留意已經移除的 invariant 匯出，以及輸入框統計區域從 stats 拆成 activity、usage 的變化。這些是 0.2.1 釋出說明列出的版本遷移問題，不應透過普遍關閉相容性檢查來繞過。
靜態面板驗收透過後，再一次增加一項能力。例如，在路徑和失敗處理明確的前提下讀取一個指定檔案，就適合作為下一步。持久化和外部請求留到單獨的迭代，並保留已驗證可用的最小版本，便於比較新問題。
升級背景可參見 Harness 0.2.1 更新解讀。如果原本只是想寫一個觸發提醒的外掛，可以先看看內建自動化教程，宿主可能已經提供了所需的排程功能。