DeepSeek 在 2026 年 8 月 13 日開源 DeepSeek Harness。到 8 月 24 日，GitHub 已經累積約 19.2 萬個 Stars。

但 Star 成長得快，不等於我們已經看懂它為什麼重要。DeepSeek Harness 目前仍是 developer preview，官方也明確提醒未來可能出現 breaking changes。

真正值得研究的，不是它現在有多熱門，而是它把一個 AI Agent 背後經常被混在一起的責任，拆成了一套可以替換、追蹤與重組的 runtime。

為了真正理解這套架構，我做了 Learn DeepSeek Harness：使用 Python 標準函式庫，分成 4 個 Phase、14 個 Section，從零重建一個最小但可以運作的 Mini-dsh。

這篇文章想分享兩件事：DeepSeek Harness 的核心概念，以及我如何把一個龐大的 TypeScript codebase，轉成一條可以動手驗證的學習路徑。

Agent 不等於 Model，也不只是一個 Loop

最常見的簡化方式，是把 Agent 描述成「模型反覆呼叫工具的迴圈」。

這個說法沒有錯，但只描述了 happy path。

模型可以提出下一步，Harness 才負責讓這一步在真實環境中變成可執行的行動。它必須回答：

• 模型這一輪能看到哪些上下文？
• 哪些工具可以使用，參數如何驗證？
• 一次工具呼叫需要詢問、拒絕或套用什麼 policy？
• 串流、工具結果與中斷狀態要記在哪裡？
• Process crash 後能否恢復、重播或 fork？
• Web、CLI、SDK 能否共享同一份執行真相？
• Model、sandbox、storage 或 agent loop 能否單獨替換？

因此，DeepSeek 官方用一個很精準的等式描述它：

Agent = Model + Harness

模型決定推理能力的上限，Harness 則決定這個能力能否安全、持續、可觀察地作用在真實世界。

「Everything is a Plugin」真正代表什麼？

DeepSeek Harness 最醒目的設計理念是 Everything is a Plugin。

Model、tools、skills、sessions、sandboxes、storage、loops、scheduling，甚至 UI 都是 plugin。

不過，plugin 並不只是「把功能拆成很多模組」。

如果模組只能安裝，不能安全卸載；可以替換 provider，卻無法保留狀態與追蹤執行；可以新增工具，卻沒有統一的 guard pipeline，那仍然只是一組鬆散的擴充點。

我把這套架構整理成四個不能互相取代的面向：

這四個面向都重要，但不能互相代替。

多加一個 tool registry，不會自動得到可恢復的 session；有 agent loop，也不代表拒絕與錯誤已經被正確結算；把 class 命名為 plugin，更不代表它真的可以安全卸載。

為什麼我要再做一份教學？

DeepSeek Harness 是一個大型 TypeScript monorepo，底層還建立在 Cordis plugin framework 上。

直接閱讀原始碼，很容易遇到三個問題：

1. 設計意圖分散在不同套件。 同一個 tool call 可能跨過 registry、permission、scheduler、session 與 UI。
2. 術語先於直覺出現。 Fiber、Effect、Surface、Capability Seam 等名詞，會讓人先記名稱，卻還不知道它們防止了什麼錯誤。
3. 只看 happy path 很容易誤判架構。 真正決定系統品質的，通常是拒絕、取消、crash、compaction 與卸載。

所以 Learn DeepSeek Harness 不照 package 名稱逐一翻譯，而是每次只回答一個設計問題，並加入一個可以獨立驗證的 Mechanism。

我如何重建 Mini-dsh

整份教學固定使用同一個閱讀 Lens：

1. Opening：先說清楚這個 Section 要解決的設計問題。
2. Mechanism：用最小 Python 實作重建該機制，搭配流程圖與程式碼片段。
3. In real dsh：把 Mini-dsh 的類別與函式，對照到真正 dsh 的檔案、symbol 與官方文件。
4. Failure modes：說明缺少這個機制時，系統會怎麼壞。

專案固定研究 dsh 0.1.0-rc.7 的 commit 99f6f02。

即使上游持續快速變動，文章裡的每個原始碼連結仍然可以復核，不會因為 main branch 更新而失去對應關係。

每個 Section 還採用 Carry-forward：完整複製前一章的 src/，只加入一個新 Mechanism。

因此比較相鄰兩個 Section，diff 就是這一章真正新增的概念，不會混入重構或無關改動。

最後，每章都有一組 deterministic Offline check。它們不需要 API key、不需要網路，也不依賴模型輸出的運氣。目前 14 個 Section 的檢查都能獨立通過。

需要觀察真實模型行為的章節，才另外提供可選的 Live demo。

四個讓我印象最深的機制

1. Plugin 的重點不是掛載，而是可逆

在 Mini-dsh 中，每次註冊 listener 或 service，都必須同時產生一個撤銷動作，交給擁有該 plugin 的 fiber。卸載時，framework 會依相反順序執行這些動作。

這讓「清理」不再依賴每個 plugin 作者記得手寫完整的 cleanup()。

同一套基礎也能支撐 profile 切換、HMR、測試收尾與 subagent 關閉。

對我來說，這才是 Everything is a Plugin 最重要的前提：每一次註冊都必須知道由誰擁有，也必須可以撤銷。

2. Log 是事實，Model history 只是投影

一般實作常直接維護一份 messages 清單，但 model、持久化與 compaction 其實需要三種不同視圖。

DeepSeek Harness 把 session 設計成 append-only event log。所有發生過的事情只追加，不回頭修改；模型真正看到的歷史，則從 log 的 surface 動態推導。

這樣一來，streaming chunk 可以保留供重播，卻不會污染 model history；compaction 可以替換 surface 的一段投影，卻不必刪除原始事件；Web、CLI 與恢復流程，也可以從同一份 log 建立自己的 projection。

3. 被拒絕與執行失敗，也必須正常結算

一次 tool call 不是直接從 registry 跳到 function。

它會經過 pre、ask、guard、execute、post 等階段，再交給 scheduler 判斷哪些可以平行、哪些必須互斥。

其中一個很重要的設計是：就算呼叫被拒絕、被取消或執行失敗，仍然要產生正常的 tool/result。

否則 model history 會留下沒有結果的 tool call，下一步推理就建立在一段不完整的協定上。

錯誤不只是 exception，它也是 agent 必須看見並處理的狀態。

4. 最後，Harness 本身變成資料

前面所有 plugin 最終會被整理成一份 entry 清單。Bundle、profile 與使用者 patch 依序疊加，決定一個 runtime 實際掛載哪些能力。

DeepSeek Harness 的 patch 不做 deep merge，而是用 id 指定 entry，整份替換 config。

這犧牲了一點簡短，卻換來更清楚的責任邊界：最後修改該 entry 的那一層，就包含完整真相，不必回放所有上游設定才知道某個欄位從哪裡漏進來。

到了這一步，Web 與 headless 不再是兩套程式。它們是同一批 plugin 的不同組合，產品差異變成一份可讀、可 diff、可替換的資料。

14 個 Section 的學習路徑

建議怎麼讀這個專案

如果你想真正吸收這套架構，而不只是把範例跑完，我建議：

1. 先看根目錄的架構圖，建立 kernel、loop、log 與 seams 的相對位置。
2. 依順序閱讀 Section，每次只理解一個設計問題。
3. 跑該章的 Offline check，確認 Mechanism 真的滿足它宣稱的不變量。
4. 比較相鄰 Section 的 src/，觀察這一章唯一增加的機制。
5. 最後再沿著 In real dsh 的固定連結，回到官方 TypeScript 實作。

你可以從單一章開始，也可以一次跑完所有檢查：

git clone https://github.com/hardness1020/learn-deepseek-harness.git
cd learn-deepseek-harness
python sections/01-kernel/src/test.py

結語

DeepSeek Harness 最值得學的，不是「plugin 越多越好」，而是它如何把 agent runtime 拆成可逆的生命週期、可結算的執行、可介入的控制，以及可重播的真相。

這些能力不能互相取代。

Agent loop 讓模型繼續工作，session log 讓系統知道發生過什麼，tool pipeline 讓行動可以被治理，composition 才讓同一套機制組成不同產品。

如果你也在打造 AI Agent，希望這個專案能幫你少走一點只看 happy path 的路，並把 DeepSeek Harness 的設計轉成能帶回自己系統的架構能力。

• 專案：Learn DeepSeek Harness
• 官方專案：DeepSeek Harness
• 官方介紹：Everything is a Plugin
• 官方架構文件：DeepSeek Harness Architecture