DeepSeek Harness Agent Framework：插件与工作流解析

症狀：你發現模型、工具、工作狀態和介面彼此糾纏，換一個元件就要改動整條執行鏈。
最快解法：先用 DeepSeek Harness Agent Framework 的模組邊界檢查可替換性，再決定是否採用完整框架；簡單問答或單函式呼叫，不必承擔這套架構的複雜度。

這篇文章適合三類讀者：需要理解 DeepSeek Harness 內部職責邊界的 Agent 工程師、準備開發或審查第三方插件的框架維護者，以及正在比較自研 Agent Loop 與現成 Harness 的技術負責人。

最後更新於 2026 年 8 月 17 日；資料核實自官方儲存庫的架構文件、核心介面、工具執行流程與開發文件。當插件協議、核心循環或官方穩定性聲明變更時，本文應重新審閱。

先用五個模組確認框架邊界

評估 DeepSeek Harness Agent Framework 時，不要先看「能不能叫模型」。真正要看的，是模型請求以外的執行責任是否被拆開，而且每個責任能否透過正式介面替換。

官方架構文件把系統拆成幾個關鍵區域：

1. 模型適配器：負責訊息格式、串流輸出與模型供應商介面。
2. Agent Loop：負責接收輸入、組裝提示內容、送出模型請求、處理下一步。
3. 工具註冊與執行：負責工具描述、權限、沙盒、逾時、結果標準化與回傳。
4. 會話狀態：透過事件記錄保存訊息、工具結果與可重播的執行歷史。
5. 使用者介面或無頭執行器：讀取 Agent 與會話事件，不應直接接管核心循環。

官方文件明確指出，模型適配器、工具註冊、會話記錄與 Agent Loop 都以插件形式存在，並由 Cordis 共用上下文、事件及可逆效果組合。這代表「可擴充」不只是額外加一個命令，而是可以替換模型、工具後端、狀態儲存或循環控制層。(github.com)

不過，你不能把「Everything is a Plugin」直接解讀成「所有部分都能無限制替換」。替換仍受三項條件約束：插件是否註冊在正確的服務介面、事件是否符合既定生命週期，以及替換後是否仍能滿足會話記錄和模型輸入的可重建要求。

按啟動層級檢查插件系統如何工作

DeepSeek Harness 插件系統如何工作？
它不是單純掃描一個資料夾後載入命令，而是先從 Profile 組成插件樹，再按 Bundle、Profile patch、使用者層級 patch 和命令列 overlay 的順序套用設定。官方文件說明，dsh-base 提供模型、工具、持久化、沙盒、核准政策、憑證與遙測等基礎能力；Web 或 headless 介面則在其上增加不同執行形態。(github.com)

這種設計對維護者有三個實際影響：

• 發現機制：插件需要以套件宣告方式進入 Bundle 或 Profile，不能假設隨意放入目錄就會自動獲得完整上下文。
• 生命週期：註冊行為是可撤銷效果。插件卸載時，服務註冊和事件掛勾應一併退場，避免留下失效工具或重複監聽器。
• 替換機制：patch 以識別碼定位設定列，替換的是整個設定，而不是必然進行深層合併。你在覆寫插件設定時，必須重新檢查憑證、權限和依賴欄位是否被意外移除。

因此，插件審查不能只問「有沒有 API」。你還要確認它的依賴注入是否顯式、卸載是否乾淨、設定覆寫後是否仍能啟動，以及它是否把不可替換的假設藏在全域單例或 UI 程式碼裡。

用工具呼叫鏈定位可靠性風險

工具呼叫的真正難點，不在模型能否產生函式名稱，而在一次呼叫失敗後，系統能否留下可理解、可恢復、可重試的結果。

在 DeepSeek Harness 中，一次工具流程大致會經過以下階段：

1. 模型產生工具呼叫，先寫入 tool/call 會話事件。
2. tools/pre-execute 進行插件掛勾、權限檢查與沙盒判斷。
3. 已註冊的防護器決定允許、拒絕或要求人工核准。
4. tools/execute 包住實際執行，可放入逾時、重試與指標收集。
5. tools/post-execute 可接受、阻擋、改寫結果或追加上下文。
6. 結果經過標準化後寫入 tool/result，再進入下一次模型請求。

官方工具執行流程特別標出權限、核准、沙盒、檔案系統防護、結果改寫和 UI 呈現等位置。這使插件可以在不直接改動 Agent Loop 的前提下加入政策控制，但也增加了故障入口。(github.com)

你至少要驗證以下五項：

• 模式校驗：缺少欄位、型別錯誤或額外參數應在執行前拒絕。
• 權限控制：檔案寫入、子程序啟動、外部網路請求應有明確政策，不要只依賴提示詞。
• 逾時與取消：工具卡住時，Agent Loop 必須能結束等待，不可讓整個工作流永久佔用執行緒。
• 幂等性：重試前要判斷工具是否已產生副作用，例如檔案已寫入、部署已提交或付款請求已送出。
• 結構化錯誤：錯誤要區分權限拒絕、參數無效、工具逾時、外部服務失敗與系統例外，否則下一輪模型只會收到一段難以判讀的文字。

工具呼叫結果如何進入下一輪推理？
結果不是直接塞進 UI，也不是由插件自行修改任意歷史。工具執行完成後，系統會先建立單一的模型可見結果，再透過會話事件投影成下一次模型歷史。官方文件要求，任何會進入模型請求的內容都必須能從會話記錄重建；這是重播、恢復、壓縮和稽核能否成立的基礎。(github.com)

用里程碑區分 Agent Loop 與確定性工作流

DeepSeek Harness 的 Agent Loop 適合處理「下一步要做什麼」仍由模型判斷的任務，例如檢查程式碼、選擇工具、根據結果修正方案。但它不等於完整的工作流引擎。

你可以用以下里程碑理解一次任務：

官方生命週期文件把 turn、step、agent/pre-step、agent/request、工具事件與 agent/turn-stopping 分開。這種分層讓你可以在模型請求前改寫輸入、在工具執行前攔截權限，也可以在錯誤後選擇重試或保留原始錯誤。(github.com)

DeepSeek Harness 的 Agent Loop 能否替換？
從官方架構定義看，預設循環是掛在 ctx.agentLoop 的插件；因此替換點存在，並非只能修改框架原始碼。但「能替換」不等於「替換成本低」。新的循環仍要遵守 Agent 介面、事件語意、會話持久化與工具結果投影，否則 UI 可能看似正常，重播或恢復時卻缺少必要資料。(github.com)

如果你的團隊需要固定審批、明確重試次數、不可跳過的驗證階段，建議把確定性部分放在工作流控制器，而不是把所有規則塞進提示詞。開放式 Agent Loop 可以負責探索與工具選擇，但不能取代交易、部署或權限流程中的硬性狀態機。

以可觀測性和隔離條件驗收插件

DeepSeek Harness 適合生產環境嗎？
截至 2026 年 8 月 17 日，官方儲存庫仍把 DeepSeek Harness 標示為 Developer Preview，並明確提醒可能出現相容性破壞變更。因此，它可以作為受控環境中的原型、內部工具或插件驗證平台，但不應在未鎖定版本、未建立回滾方案的情況下直接承擔不可中斷的生產流程。(github.com)

生產評估時，請把觀測資料分成三層：

1. 決策層：模型請求使用了哪些提示區段、工具模式和上下文。
2. 執行層：工具輸入、核准結果、逾時、重試、沙盒政策和插件版本。
3. 產物層：檔案變更、外部 API 副作用、任務狀態和最終交付內容。

若只記錄最後一段回答，你無法回答「模型為何選這個工具」、「哪個插件改了檔案」或「重試前是否已經完成副作用」。官方文件將 session/event 定義為可持久化事實，將 agent/* 定義為即時協調介面；部署時應分別保存，不能只保留前端畫面上的訊息。(github.com)

插件隔離則至少要檢查：

• 是否能讀取不必要的環境變數與 API 金鑰。
• 是否能寫入工作目錄以外的檔案。
• 是否能自行啟動未經核准的子程序。
• 是否能建立外部網路連線。
• 是否能修改其他 Agent 或全域插件的註冊。
• 插件卸載或版本回退後，是否仍殘留事件監聽器與工作狀態。

官方架構把檔案系統、子程序、沙盒、工具和核准政策設計成能力接縫，這有利於替換執行後端；但你仍需在部署層限制密鑰、檔案和網路權限，不能把「插件可替換」誤當成「插件可信任」。(github.com)

按五步完成插件驗證與部署判斷

你可以在正式採用前，依照以下順序做一次小型驗證：

1. 鎖定來源與版本：記錄官方儲存庫提交版本、插件套件版本、Node.js 執行環境與設定 patch。官方開發文件目前列出的 Node.js 支援條件包括 22.19+ 與 24+，並要求使用 Corepack 管理指定的 pnpm 版本；這些條件應納入建置映像檔。(github.com)
2. 列出實際插件樹：用 dsh --profile web --dump-config 查看機器真正啟動的組合，不要只看原始 Bundle 或文件範例。
3. 建立最小工具案例：測試正常回傳、模式錯誤、權限拒絕、逾時、重試和重複執行，並確認每種結果都能在會話記錄中還原。
4. 驗證中斷與恢復：在模型請求前、工具執行中、工具結果寫入後分別中斷，檢查重新啟動後是否能判斷已完成的步驟，避免重複產生副作用。
5. 驗收隔離與稽核：用無敏感權限的帳號執行插件，檢查檔案、網路、子程序和金鑰存取範圍，再把插件版本、輸入輸出和產物雜湊寫入部署日誌。

若團隊只需要一次模型請求加一個函式，這五步反而會暴露出框架過度設計的成本。此時使用輕量 API 包裝器或自建短循環通常更合理。相反，如果任務包含多個工具、長時間執行、人工核准、上下文壓縮或可恢復會話，DeepSeek Harness 的插件邊界才有機會抵銷整合成本。

依專案形態做最後選擇

適合採用 DeepSeek Harness 的情況包括：

• 需要替換模型適配器、檔案系統或遠端沙盒。
• 需要讓不同 Agent 使用不同工具集合。
• 任務會跨越多輪工具呼叫，且必須支援恢復。
• 團隊需要從事件記錄重建模型決策與工具副作用。
• 你願意承擔 Developer Preview 階段的相容性維護。

不適合直接採用的情況包括：

• 只有聊天介面，沒有工具或長期狀態。
• 只需執行單一函式，且錯誤處理可以由 API 層完成。
• 團隊沒有能力維護插件版本、權限政策和事件記錄。
• 任務要求極高的版本穩定性，但框架尚未完成穩定承諾。
• 執行環境需要實體介面、特殊硬體或嚴格固定的本機依賴。

如果你正準備在遠端 Mac 環境驗證插件，除了算力，還要確認工作階段是否能保留日誌、是否能透過遠端連線檢查檔案權限，以及中斷後是否能重新取得同一份任務狀態。你可以先查看 Kvmkit 幫助中心 的環境與連線說明，再決定測試流程需要哪些持久化條件。

對比自建 Linux 或 Windows 執行環境，常見缺點是插件驗證時需要自行處理相依套件、桌面工具鏈、權限隔離和遠端除錯；雲端容器則可能在檔案、網路或長時間工作階段上有額外限制。若你只是要短期驗證 DeepSeek Harness 插件、測試工具呼叫鏈或重現任務恢復問題，租用一台可遠端操作的 Mac 往往比先購置實體設備更快形成可重複的測試環境。你可再比較 Mac mini 租用方案，把預算留給插件測試、日誌保留與安全驗收，而不是先承擔長期硬體維護成本。