DeepSeek 開源的智能體框架憑什麼「一切皆插件」？11 頁圖解，一次拆透
從插件生命週期、主循環、會話日誌到分層配置，用 11 頁圖解理解 DeepSeek Harness 的架構、組合方式與交付邊界。
DeepSeek 開源了智能體框架 DeepSeek Harness（下文簡稱 DSH）。本文討論的是開發者預覽版，採用 MIT 許可，源碼在 GitHub 上（deepseek-ai/deepseek-harness）。
先解釋一下 harness 這個詞。DeepSeek 官方的說法是：Agent = Model + Harness。模型是智能體的靈魂，但光有靈魂乾不了活——理解環境、調用工具、在真實系統里持續工作，這些靠的是 harness。你可以把它理解成一輛車的底盤、方向盤和儀錶盤：不產生動力，但決定動力能不能安全地用到路上。
DSH 的特點是：沒有寫死的智能體業務核心。主循環、日誌、重試、審批、上下文壓縮、模型接入、界面，都由可替換的插件提供。官方口號是 Everything is a plugin，一切皆插件。這裡的“沒有內核”是一種圖解表達：底層仍有 Cordis 內核，負責插件加載、卸載與依賴關係，只是不把智能體能力寫死在內核里。
這篇文章用 11 頁圖解把它拆開講清楚：積木怎麼拼、怎麼配合、為什麼這樣設計。不需要任何技術背景，適合正在給團隊選型 agent 框架的人讀完。
一、它是什麼：一個沒有固定業務核心的框架
先把整張地圖攤開。在 DSH 里，審批、重試、上下文壓縮、會話日誌、沙箱、模型接入、網頁界面，全部是插件，和你自己寫的插件使用同一套機制。底下的基座負責插件的加載、卸載和依賴關係。
這和多數框架的思路是反著的。常見的框架是“一個寫死的核心，加幾個允許你插手的口子”：核心管主循環、管記憶、管重試，作者心情好就給你留個 hook。口子留多少、留在哪，全看框架作者。
DSH 把這個邏輯倒過來了：
別人留口子，它給你整塊地。連主循環、日誌、重試都是插件，和你寫的沒有區別——不存在「官方能做、第三方做不了」的事。
舉一個具體例子：DSH 有一個「兼容 Claude Code 鈎子」的功能。按照別的框架的做法，這種官方功能多半要走特權通道。在 DSH 里，它就是一塊普通插件——和你在社區里下載的、自己寫的插件走完全相同的裝卸流程。
但這個設計有代價，圖解里沒有回避，我們也不回避：行為由很多積木共同決定，出了問題更難查。傳統框架出了 bug，你翻框架源碼；DSH 出了問題，你要先弄清楚是哪幾塊插件在哪個環節互相影響。自由換來的是排查成本，這是一筆明賬，不是免費午餐。
DSH 的基座構建在開源插件系統 Cordis 之上。選擇已有的插件系統做底座，而不是從零自造一套，是一個值得注意的工程判斷。
二、積木怎麼拼：登記、狀態、主循環
插件不是補丁，是一位新入職的同事
DSH 插件的擴展方式是向系統登記自己能提供什麼：像新同事入職，登記自己的職責和能力，通過宿主接口參與工作。這是一種設計方式，不是“插件代碼無法修改共享狀態”的安全保證。
常用的登記有五種，正好對應插件能提供的五類能力：
① 加一個工具——讓模型多一樣能調用的能力，比如一個查數據庫的工具；
② 加一段提示詞——告訴模型要守的規矩，比如“輸出前必須引用來源”；
③ 訂閱一個事件——在某個環節被通知或攔截，比如“每輪結束前讓我看一眼”；
④ 提供一項服務——讓別的插件來調用，插件之間這樣分工協作；
⑤ 掛一塊界面——把自己做的界面放進網頁的預留位置。
關鍵規則是：登記和撤銷成對出現，撤銷由生命週期管理。插件卸載時，通過受管理接口登記的工具、提示詞、事件、服務和界面會被清理。它能減少插件增多後的殘留；但插件自行創建的外部副作用、未納入管理的資源，不會因此自動回滾。
每個插件只有三種狀態：等、幹、走
基座怎麼決定一塊插件什麼時候上崗？每個插件要事先聲明“我離不開誰”（依賴），基座據此安排生命週期，一共三個狀態：
等——依賴沒到齊，先不啓動；
乾——依賴到齊，啓動並登記；
走——被關掉或依賴消失，登記全部撤銷；依賴回來時，自動重新上崗。
這帶來三個實際好處：可以支持不重啓替換插件；不同對話掛不同能力；智能體在運行中擴展能力。最後一條是這套架構值得關注的可能性，實際能做什麼，仍取決於部署提供的插件和權限。
主循環：AI 每走一步，都繞這個錶盤一圈
最核心的主循環，本身樸素得讓人意外——就是右邊這個錶盤，六步一圈：
① 整理資料（提示詞＋工具＋歷史）→ ② 開工前檢查（可攔截）→ ③ 問模型（出錯可重試）→ ④ 記下回復寫入日誌 → ⑤ 執行工具（執行前可攔截）→ ⑥ 記下結果寫入日誌。轉到模型不再調用工具為止，這一步才算完。
那重試、壓縮、審批這些“聰明”的行為在哪？答案是：都不在循環里。它們是別的插件在錶盤的紅點處插手實現的——紅點就是插件可以喊“等一下”的位置。比如你的合規插件想在工具執行前做一次檢查，不需要改框架代碼，寫一塊插件掛在第 ⑤ 步的紅點上就行。
在這份圖解描述的主循環中，沒有寫死最大步數限制；設上限也是可以加上的策略。評估實際部署時，應檢查所用版本與配置中的停止條件和預算控制，不能假定默認行為適合所有任務。
三、一本賬：會話日誌為什麼是被低估的設計
如果整套架構里只讓記一條設計，我們選會話日誌。它的規則簡單到近乎笨拙：只有一本賬，只能往後追加，不能修改。對話不是存在內存里的某個對象，而是一條只增不改的日誌——連繫統提示詞都是日誌里的一條記錄，和用戶提問、模型回復平起平坐。
這本賬為六類能力提供了共同的數據基礎：
模型看到的對話——每步從日誌推導上下文，減少“內存里的對話”和“日誌里的對話”不一致的問題；
界面上的狀態——從同一份記錄展示運行軌跡，便於對照模型獲得的上下文；
崩潰後恢復——通過重放恢復已記錄的會話狀態；外部工具已產生的副作用仍需另行處理；
從任意處分叉——複製前半段，另起一條線試別的方案；
上下文壓縮——只是“隱藏”早期內容，原文還在賬上，隨時可查；
審計留痕——誰在什麼時候讓模型看了什麼、調了什麼工具，賬上全有。
我們的看法是：只增不改的日誌，是智能體框架中被低估的設計。它在演示時不顯眼，卻決定團隊能否還原一次運行。DSH 給可追溯性提供了數據結構基礎；生產環境里的審計，仍需要保存期限、訪問權限、完整性保護以及外部系統記錄等配套措施。
這一頁還有一句話值得單獨抄下來：
模型看到的內容，應當能在日誌中找到對應記錄。日誌與上下文構建，應該能夠互相對照。
反過來看更有用：想知道插件對模型做了什麼，檢查它追加了什麼記錄，以及上下文如何由這些記錄生成。文檔描述意圖，運行軌跡幫助你核對實際發生的事。
插件之間不用認識，靠廣播和閘門
幾十塊插件互不認識，怎麼配合？靠事件系統，一共兩種：
通知型——“某件事發生了”。發出的一方不知道誰在聽，聽的一方也不需要對方同意，只能知道、不能改變結果。例：一輪對話結束了，自動起個標題；工具跑完了，抄送一份給審計。
攔截型——“某件事要發生了，誰有意見”。事件逐個經過每個訂閱者：放行、修改、或者拒絕。例：工具執行前做合規檢查；請求出錯後，決定要不要重試。
攔截型事件是 DSH 最強的擴展點——重試、壓縮、審批、沙箱、計劃模式，這些聽起來很“核心”的能力，全部是用它實現的。這也再次印證了第一部分那句話：官方功能和你寫的插件，走的是同一條路。
但圖解里有一條警告必須原樣轉述，因為它是實際使用中最容易踩的坑：多個插件守同一道閘時，結果和先後順序有關，而基座不替你排順序。比如插件 A 想攔截並修改，插件 B 也想攔截並修改，誰先誰後，最終結果可能不同。這是組合插件時最該測試的地方——不是“能不能跑”，而是“多個攔截器疊在一起時，行為是否符合你的預期”。
四、怎麼裝配：清單層層疊加
“裝哪些插件”就是一份清單。對清單的修改只有三種：插入、替換、關閉。而真正的關鍵在於，清單不是一份，是層層疊加的——上層覆蓋下層，一共四層：
第一層 · 廠商的安裝包（bundle）——一組插件＋怎麼裝配它們，帶版本號發佈；
第二層 · 這家客戶的調整——開關、閾值、模型路由；
第三層 · 個人的調整——我自己加的、關掉的；
第四層 · 啓動參數里的臨時修改——最後生效，優先級最高。
這套疊法解決的是廠商升級與客戶定制如何共存：廠商升級基礎層，客戶與個人修改保留在各自的層里。配置沒有被覆蓋，不等於升級絕不會產生兼容問題。插件接口與行為變化後，仍需驗證上層配置能否繼續工作。
注意圖解里那句話：這不是一項額外開發的功能，是裝配方式自帶的性質。分層清單這種結構，天然就把“誰的修改記在誰那一層”分開了。
插件、bundle、patch、profile、preset：一條裝配線上的五個位置
讀 DSH 資料會反復遇到五個詞，容易繞暈。其實真正在跑的只有插件，其餘四個詞回答的都是同一個問題：哪些插件、以什麼配置、裝給誰。
① 插件——一塊積木，真正在跑的代碼；
② bundle 安裝包——一盒積木＋一張裝配說明，廠商發佈、帶版本號（裝配說明本身就是一份內置的 patch）；
③ patch 調整單——對清單的修改，只有插入、替換、關閉三種；
④ profile 運行環境——一個目錄：用哪些 bundle＋自己的 patch，層層疊加（啓動時的臨時 patch 優先級最高）；
⑤ 進程與 preset 崗位配方——啓動後是一個進程；每個對話再各選一份 preset，決定這個“AI 員工”會什麼。
最後一層值得展開。進程分兩層：宿主層全進程共用（模型、日誌、工具表、網頁界面，由 profile 決定）；agent 層每個對話各掛各的，由 preset 決定。preset 也是一份“一行一個插件”的清單，語法和 profile 完全相同——刪掉 bash 那一行，這個崗位就沒有 bash。
所以同一個進程里，對話 1 可以是投研崗，對話 2 可以是合規崗，對話 3 可以是宏觀崗。拼出來的不是一個“產品”，是一個正在運行的、千人千面的進程。
五、放回坐標系：它和 MCP、Skill、Hook 是什麼關係
讀到這裡你可能會問：已經有 MCP 和 Skill 了，為什麼還需要一整套插件體系？一張圖說清分工：
MCP——給模型加工具，像請外部供應商；
Skill——教模型怎麼做事的操作手冊；
Hook——在關鍵環節攔截的門口檢查崗；
DSH 插件——像常駐員工：既可以參與工具、提示詞和事件機制，也能提供服務、擴展界面、保留狀態。這裡比較的是擴展範圍，不代表插件直接替代了 MCP 協議或 Skill 的封裝形式。
更貼切的類比是瀏覽器擴展：常駐宿主，參與宿主本身的行為。這個比喻描述架構角色，不是技術標準之間的嚴格等價。
MCP 和 Skill 在支持它們的平台之間通常更容易復用，但仍要檢查兼容性。選型時，可把數據接入與方法沈澱為便於遷移的 MCP 和 Skill；把與運行時緊密相關的攔截、上下文注入和界面擴展放進 DSH 插件。
這套架構對“駐場式交付”意味著什麼
駐場式交付（FDE，Forward Deployed Engineering）的難點，從來不是給第一家客戶做出第一個 agent——而是做到第十家客戶時，還能不能復用前九家的積累。用這個標準看 DSH 的架構，會發現它的幾個設計幾乎逐條對上了交付場景的真實需求：
做過的東西要能復用 → 插件打成 bundle，帶版本號，一次開發、多家交付；
每家客戶都不一樣 → 差異寫成 patch 和 preset，不用改插件代碼；
持續升級保留定制 → 廠商配置與客戶修改分層保存，升級時仍需驗證兼容性；
要深入改造 AI 行為（合規、審計、記憶）→ 沒有內核＋攔截型事件，任何環節都能插手；
運行過程可追溯 → 只增不改的會話日誌為排查、恢復、分叉提供基礎，再補齊實際部署所需的控制；
支持本地模型與數據 → 模型接入可通過插件替換；但本地運行不等於數據不會出網，仍需檢查模型端點、工具、插件和外部連接；
長期運營，調用成本要可控 → 整體架構圍繞緩存命中設計。
圖解報告了 95% 以上的緩存命中率，我們自己的環境尚未復測，應當視為未經驗證的參考值。緩存效果取決於對話結構和使用方式，別人的數字不能替代自己的成本測試。
提供的材料還列出三條短板，評估時需要對照實際部署版本：
接口仍在演進；插件共享進程，並不自動獲得安全隔離；多用戶訪問、團隊記憶與協作空間還需要額外的產品建設。
這些問題也指出了值得動手的位置：運行時隔離、團隊記憶與會話日誌的關係、多用戶權限模型。交付團隊可以把這些工作逐步積累成可復用的產品能力。
你可以先做什麼
如果只做一件事，建議是這個：跑一次 DSH，把一次完整任務的會話日誌導出來，從頭看到尾。裝好 Node.js 之後一行命令：
npx @deepseek-ai/dsh web重點檢查：系統提示詞以及每項傳給模型的上下文，是否都能在記錄中對應起來。再嘗試只憑日誌還原一次任務。這能為判斷恢復、分叉和可追溯能力建立一個具體標準。
最後提醒一句：DSH 還在開發者預覽期，官方明確說核心插件和接口還會變。現階段值得投入的是看懂架構的時間，不是押注的時間。架構判斷做對了，接口怎麼變都接得住；架構沒看懂，追 API 文檔追得再緊也是白忙。
參考資料
2. GitHub · deepseek-ai/deepseek-harness
3. 本文由所提供的公眾號原稿及 11 頁圖解改編，英文配圖採用 DSH-Core-Mechanisms-EN-v3，繁中配圖由中文圖解轉換。圖解用於解釋架構，具體實現以官方文檔和實際使用版本為準。