DeepSeek Harness 架構：Plugin、Profile 與事件

DeepSeek Harness 是建構在 Cordis 上的 Plugin 型程式開發 Agent Runtime。理解它時，不妨把 dsh 想成一棵 Plugin Tree：Profile 選擇一套具名組合，Bundle 掛載成組能力，核心 Service 提供穩定介面，Event 則串起 Agent Loop、Session 持久化與即時控制。

本文依照 DeepSeek Harness 官方中文架構文件 重新編排，聚焦在設定覆寫、功能歸屬、事件持久化等開發時最常遇到的判斷。

Cordis Plugin Tree 是什麼

Cordis 是 Harness 底層的 Plugin Framework。元件以 Plugin 掛載，並應註冊可復原的 Side Effect：Plugin 卸載時，建立的 Service、Listener 與資源也能可靠清除。

程式開發 Agent Runtime 往往同時組合模型供應商、工具、Session Storage、Web 介面與 Policy Layer。Plugin Tree 讓每項責任都有明確註冊位置和生命週期。除錯時，先問「哪個 Plugin 註冊了這項行為」與「它掛載在哪個 Context」，通常比從單一入口檔一路盲查有效。

Profile、Bundle 與設定覆寫順序

Profile 是存放在 Harness Home 的具名組合，決定 Runtime 要安裝哪些 Bundle 與 Patch。Bundle 封裝一組相關設定和掛載邏輯；官方架構列出的例子包括 dsh-base、dsh-web-app、dsh-headless。

設定依序疊加：

1. Profile Bundles；
2. Profile Patch；
3. Harness Home Patch；
4. CLI Overlay。

後面的層級可以調整前面的結果。與其猜測哪一份設定最後生效，不如直接查看解析後設定：

dsh --profile web --dump-config

Profile 適合定義 Web、Headless 等完整執行模式；本機 Patch 則適合環境差異。不要為了改一個值複製整套 Bundle，否則後續很難接收 Upstream 更新。

Harness 核心 Service

官方架構列出 Cordis Context 上的重要能力，包括 sessions、system prompt、tools、agents、agent loop、scope 與 LLM。它們是協作介面，不代表實作永遠固定。

工具 Package 可以依賴 Tool Service，卻不必知道目前使用 Web UI 還是終端機；Agent Loop 可以使用 LLM 能力，卻不負責保存供應商金鑰；Session 負責持久化事件，也不必接管介面的暫時 Loading State。這樣才能維持清楚的相依方向。

若想從使用情境看工具能力，請接著閱讀 DeepSeek Harness 工具目錄。

持久事件與即時 Agent Event

DeepSeek Harness 的 Event Domain 各有用途：

• Session Event 是追加至 Session Log 的持久事實；
• agent/* Event 是執行期間的即時控制、狀態與攔截；
• Capability Seam Event 讓 Provider 和 Consumer 在不直接相依的情況下合作。

若「正在串流」只需要暫時顯示，就不該單純因 UI 會用到而寫入歷史。相反地，重新啟動後必須透過 Replay 恢復的事實，也不能只存在即時 Event。Agent 生命週期 會把這些事件放回完整流程中。

Turn、Step 與 Append-only Session Log

一個 Step 是一次模型請求及其相關工具工作；一個 Turn 由輸入觸發，可能包含零個或多個 Step。模型要求使用工具後，工具結果可能再觸發下一次模型請求，因此一則使用者訊息不一定只對應一次 LLM Call。

Session 採用 Append-only Event Log：新事實追加到歷史，而非改寫過去。這有利於 Replay 和 Audit，但也要求開發者判斷哪些資訊值得持久化。User Message 與最終 Tool Result 可能屬於 Session Fact；目前產生到哪個 Token 通常只是即時狀態。

Capability Seam

Capability Seam 把三種角色分開：

1. Service Definition 描述 Contract；
2. 一個或多個 Provider 提供實作；
3. Consumer 只呼叫能力，不直接 Import 具體 Provider。

Shell 執行、LLM 存取等可替換能力適合這種設計。本機、遠端與測試 Provider 可以滿足相同 Contract，Consumer 保持穩定。但不是每個 Function 都需要抽象成 Seam；只有替換 Provider 或跨 Package 邊界是真實需求時，額外的生命週期和錯誤處理成本才合理。

新功能該放在哪一層

• 可重用、可掛載的行為放進 Plugin；
• 一組互相搭配的 Plugin 和設定放進 Bundle；
• 使用者可選的一套執行模式交給 Profile 組合；
• 只有 Replay 必須保留的事實才寫 Session Event；
• 執行中的狀態和介入使用 agent/* Event；
• 明確需要替換 Provider 時才建立 Capability Seam。

功能跨越 Host 與 Client 時，請一併閱讀 API Gateway 指南；改動模型請求或工具排程時，先沿著 Agent 生命週期 完整追蹤。

官方原文

本文依據 DeepSeek Harness 官方架構文件（中文） 獨立編寫，查核日期為 2026-08-20。實際 Package、Service 與 Event 實作，請以官方儲存庫目前版本為準。