DeepSeek Harness：用「一切皆插件」架構打造可替換的 AI Agent 工作台

先講結論：Agent 的核心不該是不能拆的黑盒子

許多 AI Agent 專案一開始都很像一個函式：收到 prompt，呼叫模型，執行幾個工具，再把結果回傳。當需求增加，模型供應商、工具註冊、session log、檔案工作區、sandbox、權限審批與 Web UI 逐一加入，這個函式很快就會變成一個難以替換的單體。

DeepSeek Harness（dsh）選擇另一條路：官方文件把它描述成「一切皆插件」的 agent harness。模型 adapter、tool registry、session log、agent loop，甚至 Web 與 headless 執行模式，都以 plugin 形式組成。這個設計的價值不只是模組化，而是讓替換行為成為系統的一級能力：你可以在不修改 privileged core 的前提下，用另一個 plugin 疊加、覆寫或卸載既有能力。

但要先說清楚，DeepSeek Harness 目前仍是 developer preview，官方明確警告會有 breaking changes。因此，它更適合拿來研究可組合的 Agent 架構、建立內部原型與評估 plugin 邊界，不適合直接當成穩定的生產平台。

它解決的是哪一種問題？

如果團隊只是想呼叫一次 LLM API，dsh 可能太重。它真正瞄準的是「一個 Agent 工作流會持續變動」的場景：

今天使用 DeepSeek model adapter，明天想切換其他 provider 或 OpenAI-compatible endpoint。
同一套 agent loop 需要在 Web UI、headless job 或 ACP automation 中重用。
工具、記憶、session persistence 與 approval policy 必須能獨立替換。
需要讓不同團隊以 profile 組合出各自的工作環境，而不是複製整個應用程式。

這些需求的共同點，是「變動發生在組成方式」，而不是只有 prompt 改了幾個字。若每次替換都要 fork 核心、修改多個相依模組，Agent 的維護成本會隨功能數量快速上升。

架構重點：Plugin、Cordis、Profile 與 Bundle

1. Plugin 是統一的組成單位

DeepSeek Harness 以 Cordis 作為底層框架。依官方 architecture 文件，plugin 可以向共享 context 貢獻 services、typed events 與可逆 effects；plugin 卸載時，註冊的效果也能反向清理。這讓「安裝一個能力」和「撤銷一個能力」使用同一種生命週期模型。

更重要的是，系統沒有一個必須被直接 patch 的 privileged core。模型 adapter、工具註冊、session log、agent loop 都是可替換的組件。對開發者而言，擴充點不是在核心檔案中尋找一個永遠不變的 hook，而是建立一個能掛載到 context 的 plugin。

2. Profile 描述一個可執行的環境

Profile 是儲存在 Harness home 中的命名組合，列出要堆疊的 bundles，也保存額外安裝的 out-of-tree plugins 與使用者自己的 cordis.patch.yml。官方提供 web 和 headless 作為 profile template。

可以把 profile 想成「某種工作模式的配方」：Web profile 需要瀏覽器介面與 server，headless profile 則適合一次性執行或自動化工作。團隊可以根據部署場景保留不同 profile，而不是把所有條件塞進同一個全域設定檔。

3. Bundle 讓分發與覆寫有邊界

Bundle 是 Cordis config rows 與其所掛載程式碼的分發格式。Bundle 會在 profile 中按順序套用，較上層的 layer 可以對前一層插入的內容進行 patch。官方架構文件以 dsh-base、dsh-web-app 與 dsh-headless 說明這種組合：base 提供 model adapters、tools、persistence、sandbox、approval policy、settings、credentials 與 telemetry；web app 加入瀏覽器應用程式；headless 則提供不需要 server 的 one-shot runner。

這裡的關鍵不是名詞，而是組合順序被明確化。當你要替換 approval policy 或調整工具清單時，應該優先思考「在哪一層加入 patch」，而不是直接改掉基礎 bundle。

實際上手：先跑起 Web UI，再驗證第一個任務

前置條件

官方 README 的最短路徑是使用 npm 的 npx。只需要安裝 Node.js；若要從 source 開發，development guide 另外要求 Node.js 22.19+ 或 24+、Corepack-enabled pnpm，以及 Git 2.26+。要讓 Web UI 執行真實模型任務，還需要在設定頁填入 DeepSeek API key；本文不會在指令或 log 中放入任何憑證。

方式一：使用 npm 啟動

npx @deepseek-ai/dsh web

成功啟動後，官方說明預設 Web UI 位於 http://127.0.0.1:3080。先用瀏覽器確認頁面能開啟，再進入 Settings → Models 設定模型 provider。接著按 Choose workspace，加入你啟動 dsh 時所在的專案目錄；沒有 workspace 時，session composer 會保持不可用。

第一個可驗證任務可以使用官方 guide 的例子：

Summarize this repository and identify its main packages.

這一步同時驗證了三件事：模型設定生效、workspace 權限可用，以及 agent 能讀取並整理專案檔案。Web UI 在需要 approval 的操作前會依目前 permission policy 詢問確認。

方式二：從 source 啟動

需要檢查 Node.js、pnpm 與 Git 版本，然後執行：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

首次安裝會執行 repository 的 postinstall 設定，包括 worktree-local Lefthook hooks 與 dsh-translation-pairing merge driver。若 hook 沒有安裝，可以依 development guide 的說明執行 node scripts/install-lefthook.mjs，再用 pnpm run typecheck 做第一次檢查。這些設定屬於開發流程的一部分，不是啟動 Web UI 的額外 runtime 功能。

從「能跑」走向「可維護」的實作順序

第一步：先固定執行模式，再談客製化

先用 web profile 確認模型、workspace 與 approval policy 的基本行為，再評估 headless。不要一開始就同時改模型 adapter、工具和權限；否則出錯時很難判斷是組合問題還是單一 plugin 問題。

第二步：把變更放在 plugin 或 patch layer

若需求是新增工具，先確認是否應該建立 plugin；若需求是調整既有設定，則研究 profile 的 bundle 順序與 cordis.patch.yml。直接修改 packages/ 內的基礎程式碼，會讓升級與回溯變得更困難，也背離「沒有 privileged core」的設計。

第三步：用最小任務驗證 approval 邊界

不要只測試「能不能回答問題」。應該分別測試讀檔、寫檔、執行命令與多步驟任務，記錄哪些操作會要求 approval、拒絕後 agent 如何回復，以及 session log 是否保留足夠資訊。這些結果會直接影響團隊是否能把 dsh 放入內部工作流。

第四步：把 profile 當成可審查的部署單位

當 Web、headless 與自動化 job 使用不同權限時，為它們保留不同 profile，比在執行時用一堆環境變數切換更容易審查。profile 中的 bundles、外部 plugins 與 patch 應該一起進行版本管理，並在升級 developer preview 時重新跑 typecheck 與關鍵任務。

限制與風險：為什麼現在不該盲目上線

第一個限制是相容性。官方 README 把專案標為 developer preview，並明說會有 compatibility-breaking changes；因此不能把目前的 CLI、plugin API 或 profile 格式視為長期穩定契約。

第二個限制是生態系仍在形成。Everything-is-a-plugin 能提供很好的替換性，但也代表團隊需要理解 Cordis context、生命週期、layer 順序與 patch 行為。若沒有測試與版本鎖定，組合自由度也可能變成除錯負擔。

第三個限制是安全責任不會因為有 approval UI 就消失。workspace、shell、sandbox、credentials 與 telemetry 的設定仍需要由團隊定義威脅模型；Web UI 的確認視窗只能協助執行時決策，不能取代最小權限、隔離、審計與敏感資料管理。

第四個限制是導入成本。對只需要單一 API 呼叫的服務，直接使用 SDK 或簡單的 tool-calling loop 可能更合適。dsh 的價值要在「需要反覆替換 Agent 組件」時才會顯現。

哪些團隊適合先試？

我會把適用者分成三類：

AI 平台團隊：需要同時支援多個 model adapter、工具組與權限策略，希望把差異放在 plugin／profile，而不是維護多個 fork。
內部自動化團隊：需要 Web 操作與 headless job 共用 Agent 能力，並且願意先建立 workspace、approval 和 audit 的測試矩陣。
Agent 基礎設施研究者：想研究可逆 plugin、分層組合與可替換 agent loop，並能接受 developer preview 的 API 變動。

相反地，如果產品需要本週就鎖定穩定 API、完整的長期支援或大規模 production SLA，應先做隔離的技術評估，不要因為 GitHub 星數或品牌名稱就直接把它當成成熟平台。

結論

DeepSeek Harness 值得注意的地方，不是它又提供了一個 Agent UI，而是它把 Agent 的主要組成——model、tools、sessions、permissions 與 loop——放進同一套 plugin composition 模型。Cordis 負責 context、events 與可逆 effects，profile 負責工作模式，bundle 負責可分發、可 patch 的層次。

對實作團隊而言，最務實的路徑是：先用 npx @deepseek-ai/dsh web 跑通一個最小任務，再用 source checkout 理解 profile／bundle，最後才建立自己的 plugin 與 permission policy。把它當成可組合 Agent 架構的 developer preview 來學習與驗證，會比把它誤認為已經穩定的全能平台更符合官方現況。

參考資料