DeepSeek Harness 系統架構與運行原理深度解析如果你只把dsh當成一個能跑 Agent 的命令行工具那你只看到了它的殼。DeepSeek Harness 真正有意思的地方在于它把一個智能體能跑起來這件復雜的事拆成了一棵可以被任意插拔、疊加、替換的插件樹。本文不堆術語而是順著它從哪一層開始一層層怎么拼起來一條消息最終怎么變成一個 turn這條線把它的系統架構和運行原理講透。如果你讀過它的使用教程應該對dsh web、dsh --profile headless 任務這些命令有印象。那些命令只是冰山水面上的一角——你敲的命令越簡單底下替你兜住復雜度的架構就越厚。為什么配置要分層 patch為什么換模型不用改源碼為什么 headless 任務結束時能給你一個干凈的退出碼答案全在這套架構里。所以這篇文章不只是講原理更是給你一張以后排查問題、寫插件時隨手能翻的地圖。一、先建立一張四層心智模型理解 DeepSeek Harness下文簡稱 dsh最關鍵的一步是別把它當成一個單體程序。它實際上是一組分層疊加的東西從外到內大致可以分成四層用戶入口層你敲的dsh命令、Web 界面默認http://127.0.0.1:3080以及無界面的headless模式。這一層只負責把人/腳本和運行時連起來本身幾乎不含業務邏輯。組合層Profile Bundle決定這次啟動到底加載哪些能力、按什么順序、用什么配置。web和headless就是這一層給出的兩個預置組合模板。運行時內核層Cordis一個被 DeepSeek fork 并獨立發版為deepseek-ai/cordis的元框架。它負責插件掛載、依賴編排、副作用回收——換句話說它才是讓插件系統成立的那塊地基。能力層Plugins真正干活的部分。模型適配器、工具注冊表、會話日志、Agent 循環……全都是插件連Agent 循環本身都只是其中一個插件。記住一句話dsh 里沒有需要被 patch 的特權核心no privileged core。你想擴展它不是去改某個核心文件而是在別的插件旁邊再掛一個插件插件卸載時它注冊的一切都會作為可逆副作用被自動撤回。這一點是后面所有設計的前提。二、內核Cordis 與時空可組合性要理解 dsh 的架構必須先理解它的底座 Cordis。Cordis 的作者 Shigma 同時也是開源聊天機器人框架 Koishi 的核心開發者——Cordis 就是把 Koishi v4 里跑了四年的插件管理代碼抽象成一個與業務無關的元框架meta-framework。所謂元框架意思是它自己不提供任何業務能力沒有 HTTP、沒有數據庫、沒有調度器只提供怎么把業務能力組合起來的范式插件化、依賴注入、生命周期管理。它的設計哲學集中在一篇配套論文《A Programming Paradigm for Spatiotemporal Composability》時空可組合性的編程范式里。這個名字聽著嚇人其實拆成兩個維度就很好懂2.1 時間可組合性副作用必須能完整逆轉傳統插件系統最大的坑是裝上去容易、卸干凈難。一個插件可能注冊了事件監聽、開了文件句柄、改了全局狀態等它被移除時這些副作用常常殘留下來慢慢累積成內存泄漏、狀態污染甚至把進程搞崩。Cordis 的要求很硬任何組件在撤出時必須能完整逆轉它產生的所有副作用。機制是ctx.effect()——插件注冊一個副作用時返回一個逆操作清理函數運行時把這個逆操作存起來卸載時按注冊的逆序自動調用。這和 C 的 RAII、Rust 的Drop是同一個思想只是被提升到了運行時層面哪怕不同團隊寫的插件也能在卸載時干凈利落地退場。在 Cordis 內部每個插件實例對應一個Fiber生命周期狀態機 副作用回收器。插件從PENDING → LOADING → ACTIVE → DISPOSED走確定性的狀態轉換卸載時同步清空它的_disposables列表并反向執行 dispose。這也是為什么基于 Cordis 的 Koishi 服務能三年無數次更新插件而進程從不重啟。2.2 空間可組合性依賴必須被顯式聲明復雜系統里組件之間有一堆隱式依賴。A 模塊依賴 B 的某個功能但如果沒有顯式聲明系統既不知道 B 必須在 A 之前加載也不知道 B 不可用時該怎么優雅地處理 A。Cordis 的要求是任何組件必須顯式聲明它依賴的服務框架據此自動編排加載順序。插件通過inject聲明所需服務例如inject: [tools, llm]Cordis 會等服務就緒后才啟動該插件如果服務一直不來插件就安靜地等著而不是崩潰。這就是聲明式依賴——插件聲明我需要什么而不是你塞給我什么避免構造函數注入那種強耦合。更進一步Cordis 還提供Service Isolation服務隔離可以為某個服務創建一個隔離上下文使得上下文內外的插件互相不可感知。這對多租戶、沙箱場景至關重要。空間可組合性的底層實現很巧妙Context對象本身是一個Proxy你寫ctx.foo看起來像普通屬性訪問但底層路由到具體 Fiber 的 service 存儲而 service 的存儲 key 是Symbol在 root 首次 provide 時分配不是字符串——所以同一個名字db在不同的isolate下對應不同的 Symbol天然互不干擾。Context 提供三種嵌套操作extend(meta)創建子 context原型鏈繼承父級isolate(name, label?)把 name 映射到新的 Symbol共享 label 即共享 service用于會話/請求隔離intercept(name, config)在原型鏈上累積 intercept 配置用于不改 service 實現就改配置。2.3 路徑無關性讓熱替換變安全時間 空間兩個維度合到一起產生一個對 Agent 運行時極其關鍵的性質——路徑無關性path independence一個 Cordis 應用的最終狀態只取決于哪些插件被啟用而不取決于它們被加載/卸載的先后順序。這意味著你可以編輯一個插件的源碼、熱替換HMR它系統狀態不會亂。Cordis 的 HMR 用的是模塊緩存備份 全量重導入 插件重注冊的工程實現基于 chokidar 監聽 ModuleLoader.loadCache與require.cache雙清 回滾做到不停機改代碼。對長時間運行的 Agent 服務來說這個性質不是錦上添花而是生死線——我們后面會解釋為什么。2.4 內核內部五個服務與五種事件分派如果你愿意往 Cordis 源碼里多看一眼會發現它的核心層出奇地克制整個packages/core的運行時依賴只有兩個——cosmokit基礎工具庫和standard-schema/spec配置校驗標準接口核心代碼不到三千行卻密度極高。它把全部能力收斂到掛在同一個Context上的五個服務Fiber生命周期狀態機 副作用回收器一個插件實例對應一個 FiberRegistry插件注冊表負責插件去重與Inject依賴聲明Reflect服務注冊表同時也是Context這個Proxy的陷阱trap處理器Events事件系統提供五種分派模式Logger日志緩沖與導出機制。這里最值得玩味的是Events 的五種分派模式被合并到同一條_resolve路徑里emit發完就走、parallel并行、serial串行、bail遇錯即停、waterfall鏈式委托。dsh 上層那些agent/pre-step、tools/*的waterfall vs serial區別根源就在這里——同一個事件系統按你聲明的方式決定監聽器之間如何協作。理解這一點你寫插件時就不會搞混我該調next()還是該獨占返回。還有一處實現細節對理解isolate至關重要Cordis 用tracker Proxy 雙層機制utils.ts里的createTraceable讓一個 service 方法被調用時this會被替換成一個帶著當前調用方 ctx的 shadow receiver。也就是說service 內部寫this.ctx拿到的永遠是當前調用方的 ctx而不是創建這個 service 時的 ctx——這正是isolate語義能成立的物理基礎。沒有這層所謂的會話/請求隔離在方法內部就會串味。三、為什么 Agent 運行時特別需要這套內核你可能會問IDE、瀏覽器都有插件系統dsh 的一切皆插件到底特殊在哪答案在于Agent 運行時把插件系統拉伸到了它從未被設計去承受的方向。一個 Agent 循環不是一個掛擴展的靜態宿主——它是一個跨多個 step 管理狀態、持有上下文、調用工具、而且最要命的是可以在運行中要求修改自身行為的系統。當系統里某個組件被移除或替換時所有依賴它的下游要么適配、要么優雅失敗。文本編輯器可以容忍一個插件留下懸空引用但一個已經承諾了多步計劃的 Agent 不能。Cordis 要填的就是這個坑它不把插件管理當成一個便利特性而是把組合本身當成一個要被形式化解決的問題。這也是 DeepSeek 選它做 Agent runtime 底座、而不是從零寫一個傳統插件管理器的根本原因。舉一個具體的反面例子你就明白差別在哪。假設一個樸素的 Agent 宿主用傳統插件管理器插件 A 提供了記憶檢索服務插件 B 依賴它來做帶上下文的回答。運行過程中系統決定熱卸載 A比如要換一套檢索后端。在傳統系統里A 的代碼被移除了但它之前注冊的定時刷新、文件句柄、全局事件監聽可能沒清干凈更糟的是B 此時正處在一個多步計劃的中間下一輪它還要調 A 的接口——A 沒了B 要么拿到一個懸空引用直接崩要么 silently 走錯分支。而 Cordis 下A 卸載會先按逆序跑完它所有的ctx.effect()逆操作并且因為 B 聲明了依賴 A 的服務B 會在 A 不可用時被暫停/優雅降級而不是在半路暴斃。對一個一旦承諾就難以回滾的 Agent 來說這個區別是結構性的不是工程細節。四、組合層Profile 與 Bundle 的疊加機制理解了內核再往上回到 dsh 自己的組合層。這里有兩個核心概念Profile和Bundle。4.1 Profile一份命名好的能力組合一個跑起來的dsh本質是一棵在啟動時按有序層次組合出來的插件樹。Profile就是這份組合方案的名字存放在 Harness 的 home 目錄里。它干三件事列出它要堆疊的Bundle持有它安裝的樹外插件out-of-tree plugins保存用戶自己的cordis.patch.yml補丁文件。web和headless就是官方隨包提供的兩個 Profile 模板——一個帶瀏覽器管理界面一個是無服務器的一次性運行器。4.2 Bundle可分發的能力單元Bundle是 Cordis 配置行config rows和它們掛載的代碼的分發格式。換句話說一個 Bundle 既能聲明我要往配置里插哪些行又帶著實現這些配置的代碼。關鍵在于它插入的任何東西都能被它上面的層繼續 patch——這正是 Cordis 分層組合的體現。每個 Bundle 在自己的package.json里用一個dsh字段聲明自己dsh.profile列出這個 Profile 包含哪些 Bundledsh.bundle指向這個 Bundle 的補丁文件。dsh 里幾乎所有東西都以 Bundle 形式存在其中dsh-base是每一個 Profile 的第一層它提供模型適配器、工具、持久化、沙箱與審批策略、設置項、憑證、遙測。在此之上dsh-web-app加上瀏覽器應用dsh-headless加上一個完全沒有服務器的單次運行器。4.3 分層疊加的順序這是整篇文章里最該記住的一張順序表。當 dsh 啟動時它對著一個空的插件入口列表按以下順序疊加各層Profile 里按順序列出的每個 Bundle該 Profile 自己的cordis.patch.ymlHarness home 級別的cordis.patch.yml命令行傳入的任意--patch覆蓋層。每一層對配置的修改都是按 id 定位某一行、整行替換其配置或者插入新行。想看清你本機實際啟動的是一棵什么樹一條命令就夠了dsh--profileweb --dump-config它打印出來的每一行配置你都可以用自己的 patch 去替換。這就是沒有特權核心在操作上的含義你不需要改源碼只要知道某行配置的 id就能在任意層把它換掉。4.4 一個具體的疊加例子光說分層疊加有點抽象給一個貼合文檔描述的結構例子以下字段結構源自官方對dsh字段與 patch 機制的說明用于說明組合方式一個 Bundle 在自己的package.json里聲明它指向的補丁文件{name:my-dsh-bundle,dsh:{bundle:./dsh-bundle.yml}}而那份dsh-bundle.yml就是一組帶 id 的配置行# 這個 bundle 往配置里插入一行模型適配-id:model.deepseekconfig:provider:deepseekbaseURL:https://api.deepseek.commodel:deepseek-chat當你想在不碰這個 Bundle 源碼的情況下把模型從deepseek-chat換成deepseek-reasoner你只需要在你的 Profile 或 home 級cordis.patch.yml里用同一個 id 寫一行覆蓋# 你的 cordis.patch.yml-id:model.deepseekconfig:model:deepseek-reasoner因為疊加順序是Bundle 在前、用戶 patch 在后這一行會整行替換掉 Bundle 里那行的config——注意是整行替換不是深度合并里面的字段。這就是一切皆插件、沒有特權核心在操作上的真實手感你永遠是在某一層用 id 定位、整行換掉而不是去改別人的代碼。五、核心包長在 Cordis 樹上的服務dsh 把功能拆成了一組核心包每個包向共享的ctx貢獻一個服務一個ctxkey。官方架構文檔列出了這些核心包包負責什么ctxkeycore/session只追加的SessionEvent日志 內存存儲ctx.sessionscore/system-prompt提示詞分段與工具 schema 的裝配ctx.systemPromptcore/tools作用域化的工具注冊表 帶護欄的執行流水線ctx.toolscore/agentAgent接口、活動注冊表、agent/*事件ctx.agentscore/agent-loop實現該接口的默認驅動器ctx.agentLoopcore/scope每個 Agent 的作用域化注冊原語庫無 key—llm/llm消息與流式詞匯 適配器接縫ctx.llm注意一個共同點它們都是插件都是往ctx上掛一個服務。模型適配器掛在ctx.llm工具掛在ctx.toolsAgent 循環掛在ctx.agentLoop。正因為如此你才可以用掛一個新插件的方式把模型換成另一個、把工具集換一套、把循環邏輯換一種——而核心代碼一行都不用動。逐個看這幾個包會更清楚能力是怎么長出來的core/session它維護的SessionEvent日志是整個系統的記憶地基。別的包都不自己存狀態而是往這條日志里追加事件再從日志里派生自己需要的東西。core/system-prompt負責把分散在各插件里的提示詞分段和工具 schema裝配成一次請求真正發給模型的那段內容。你加一個工具它的 schema 會自動被這里收編。core/tools不只是個注冊表它還有一個帶護欄的執行流水線——工具調用不是想執行就執行而是要過pre-execute/execute/post-execute三道關卡這正是后面權限、沙箱能插手的地方。core/agent與core/agent-loop前者定義Agent接口和當前有哪些 Agent 活著的注冊表后者是這套接口的默認實現驅動器。把循環邏輯也做成可替換的插件意味著理論上你能換一套完全不同的調度策略。core/scope這是一個很關鍵的庫——它提供把一次注冊限定到單個 Agent的原語。配合前面說的isolate你就能做到給會話 A 一套能力、給會話 B 另一套能力而它們跑在同一個進程里互不串味。llm/llm它定義的是消息和流式的詞匯表外加一個適配器接縫。模型廠商千差萬別但 dsh 只認這一套詞匯廠商差異被擋在適配器后面。把這些合起來看ctx其實是一張能力地圖每個包往上面釘一個 key運行時按 key 取用。插件之間不直接 import 彼此只通過ctx上聲明好的服務協作——這正是 Cordis 依賴注入想達成的松耦合。六、執行回路從一條消息到一個 turn這是運行原理里最硬核的一段。先定義兩個詞step步一次模型請求 這次請求里調用的工具。一個 step 一輪模型說話 工具干活。turn輪零個或多個 step。它在該 turn 的第一條輸入被認領前打開在什么都不欠了時關閉。一條消息從進來到變成一個 turn官方文檔給出的時序大致是這樣的用文字版序列圖表示turn/start 認領下一步的輸入 一條排隊消息 裝配提示詞分段 工具 schema - agent/pre-step reject | enter(消息) 若 reject或首條 enter 被重寫為空 - 不消耗 step 直接關 turn step/start 把 enter 的消息追加為 user/message 從日志推導出模型歷史 agent/request - llm/stream - assistant/chunk* - assistant/message tool/call* - tools/pre-execute - tools/execute - tools/post-execute - tool/result* step/end 工具還欠一次請求或下一步輸入已到達 - 認領 - 下一個 step - agent/turn-stopping turn/end這里有幾個必須點破的設計細節第一事件分兩類。turn/*、step/*、user/message、assistant/*、tool/*是持久化的會話事件durable session events會被寫進日志、跨重載存活其余的agent/pre-step、agent/request、llm/stream、tools/*是活著的擴展點只在本次運行里有效。第二事件有不同的分派模式。agent/pre-step、agent/request、llm/stream以及三個tools/*是waterfall瀑布流——監聽器必須調用next()才能把控制權往下傳而agent/turn-stopping是serial串行的沒有next()用來做是否該停的最終裁決。這種區分決定了你在寫插件時到底是該鏈式委托還是該獨占判斷。第三輸入走一個 inbox。Agent 驅動只通過一個收件箱接收輸入。有的消息會立刻喚醒它有的注入上下文會在收件箱里等著直到另一條消息把它帶進一輪對話。第四agent/pre-step決定模型看到什么。監聽器可以改寫被認領的消息也可以直接 reject 掉。即便首條認領被 reject 或重寫成了空系統仍然會關閉一個沒消耗 step的持久化 turn——也就是說日志會如實記錄這次嘗試發生過而不是悄悄吞掉。6.1 一個具體場景編碼 Agent 跑測試把上面的時序落到真實場景里會更好懂。假設你給 Agent 下了一條給parser.ts加單元測試并跑通。它大概會這樣走turn/start驅動認領這條輸入裝配提示詞分段來自core/system-prompt和工具 schema來自core/tools此刻ctx.tools里已經注冊了fs、shell等工具。step 1agent/pre-step放行 →agent/request→llm/stream流出assistant/chunk*最終合成一條assistant/message內容可能是我先讀一下parser.ts。step 1 的工具調用模型決定調fs/read觸發tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result*把文件內容作為tool/result*寫回日志。step 2因為工具還欠一次請求模型看到結果后還要繼續驅動器認領下一個 step模型這次決定寫測試文件fs/write再決定跑測試shell/run。step 3測試掛了模型看到tool/result*里的報錯進入修復step改代碼后重跑。結束當模型不再調用工具、也沒有新輸入時agent/turn-stopping做最后裁決turn 關閉最終答案“已加測試并跑通覆蓋率 XX%”被打印。注意整條鏈路里每一次模型輸出和每一次工具結果都是一條SessionEvent——這正是下一節要說的日志即真相。也正是因為它全進了日志你才可以在中途 fork 出一條分支“如果當時讓它用另一種寫法會怎樣”而不用重頭跑一遍。七、會話日志模型所見即所記dsh 有一條很強的運行時不變量值得單獨成節Model-visible means logged模型能看到的必然已被記錄。意思是任何抵達一次模型請求的內容都必須能從會話日志里重建出來運行時甚至會用斷言來強制這一點。這就是為什么一條新的、模型可見的輸入必然對應一條新的會話事件——如果它沒進日志它就不該進模型。會話日志core/session維護的那條SessionEvent流是模型所看到上下文的唯一真相來源。deriveMessages()從這條日志投影出模型歷史原始的assistant/chunk事件被保留下來是為了支持回放和 UI 保真。這套設計的紅利是巨大的會話的fork分叉、resume恢復、轉寫transcript、遙測、持久化全部都從這一條流派生出來。你不用為每個功能單獨設計存儲——只要它進了日志上面那些能力自然就有了。這也是為什么官方文檔會強調要加一個模型可見的新狀態正確做法是擴展SessionEventMap并從日志里渲染而不是偷偷塞個變量給模型。這條不變量還順手給了你一個極省事的排查心法當一個 Agent 行為反常先別去翻代碼去看它的會話日志。因為模型看到的每一字節都在這條SessionEvent流里你幾乎總能從某一行事件里定位到它那一刻到底看到了什么進而反推是哪一層 patch、或哪個插件把不該出現的內容塞了進去。換句話說會話日志在這里不是事后的審計附件而是運行時的第一現場。八、能力縫合Capability Seamsdsh 把可替換的能力抽象成一個叫seam接縫的概念。一個 seam 由三個角色組成Service Definition服務定義聲明接口Service Provider服務提供者實現接口Consumer消費者使用它通常是一個面向模型的工具。一個包可以身兼多角但只有單一角色的不能算一個 seam加一項能力意味著要把這三個角色都設計齊。用一個最小例子體會這三角色怎么配合。假設你想要一個文檔摘要能力Service Definition定義聲明接口Summarizer簽名是輸入長文本、輸出摘要不關心背后是誰算的Service Provider實現你可以寫一個本地用 DeepSeek API 實現的 provider也可以后面換成調用一個獨立的摘要微服務的實現Consumer消費一個叫summarize的模型可見工具它只依賴Summarizer接口調用時完全不知道底下是本地還是遠程。這樣一來把摘要從本地 DeepSeek 換成遠程服務這件事只需要換 ProviderConsumer工具和模型側一行都不用改——這就是 seam 的價值能力被接口化了替換發生在接縫處而不波及調用方。seam 的意義在于換一個服務提供者就能改變整個產品的行為。文檔舉了一個很能說明問題的例子——文件系統fs和子進程subprocess的 provider 共享同一個執行世界。所以當你把這套 provider 指向一個遠程沙箱時Bash、PTY、LSP 會一起被搬過去而沒有任何 provider 需要為這種遷移寫分支。子 Agentsubagent的 provider 也在一套接口后面千變萬化從一個全新的子 Agent到在另一個產品里委托的一輪對話。甚至還有一個實驗性的Agent Teams一個私有的、可選開啟的協調 seam掛在ctx.agentTeams上提供持久化的花名冊、任務板和信箱疊在可續跑的子 Agent之上。順帶說一個安全邊界。dsh-base這一層除了模型適配器還負責沙箱與審批策略sandbox and approval policy——也就是說一個工具到底能不能真的去執行、執行前要不要先問人一眼是由這一層把關的而不是工具自己說了算。這正是護欄該放在接縫處、而不是散落在各插件里的體現。另外在 Cordis 的配置體系里YAML 支持一種能直接寫 JS 表達式的!jstag能力很強但顯然也是安全隱患當你用 patch 往配置里塞東西時要對這份配置即代碼的權力保持清醒。九、擴展點全景新行為該往哪放官方架構文檔給了一張新行為映射到機制的表非常實用這里轉述核心部分你想做的事該用的機制加一個模型 provider在ctx.llm上注冊它的適配器加一個面向模型的能力在ctx.tools上注冊它的 schema 會自動并入提示詞裝配給某個會話不同的能力集組合一個 agent preset對應 service 行需要isolate一個 realm加 shell 執行注冊一個ctx.shell后端本地的通過ctx.subprocess拉起加持久終端執行注冊ctx.terminals后端 dsh-tool-terminal加一個人工命令注冊在ctx.commands它不走模型 turn直接分派加后臺工作注冊在ctx.jobsjob_*工具負責收集或停止加文件系統訪問或策略注冊ctx.fsprovider或監聽fs/*事件約束被拉起的進程用ctx.sandbox后端消費者在拉起前包裹 argv攔截一次請求/工具/turn用對應的agent/*或tools/*事件agent/turn-stopping能停掉一輪加面向模型的上下文調agent.inject()它會落到下一次被接納的請求里加 UI 或編輯器集成驅動ctx.agents并從session/event渲染加一個 Web Client Chat 節點注冊ConversationNodeDefinition 帶 key 的渲染器加持久會話狀態擴展SessionEventMap從日志渲染與回放生成會話標題注冊唯一的ctx.sessionTitleprovider在同一會話里管理目標用ctx.goals通過agent/*續跑分叉一個活躍會話ctx.sessions.fork(source, boundary?, childSessionId?)把注冊限定到單個 Agent用那個 Agent 的agent.ctx這張表幾乎就是 dsh 的能力地圖。你會發現無論你想加什么路徑都是同一句話找到一個文檔化的擴展點掛一個插件上去而不是去改核心。十、串一遍一次 headless 任務的完整生命周期把前面所有層串起來一次dsh --profile headless 運行這個項目的測試套件到底發生了什么入口層dsh解析參數識別出--profile headless加載headless這個 Profile 模板。組合層按Bundle 順序 → profile patch → home patch → --patch疊加出一棵插件樹其中dsh-base先就位模型適配器、工具、持久化、沙箱策略、憑證等dsh-headless再疊上無服務器的一次性運行器。內核層Cordis 按依賴聲明編排所有插件的加載順序等ctx.llm、ctx.tools、ctx.agentLoop等服務都就緒后讓core/agent-loop進入 ACTIVE 狀態。輸入進入任務描述字符串作為一條消息進入驅動器的 inbox喚醒它開啟一個 turn。裝配agent/pre-step決定模型看到什么core/system-prompt裝配提示詞分段core/tools提供工具 schema。執行回路agent/request → llm/stream → assistant/chunk* → assistant/message若模型決定調用工具則走tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result*。如果工具還欠一次請求就認領下一個 step繼續循環。落日志上述每一步的user/message、assistant/*、tool/*都作為SessionEvent寫進會話日志——這就是模型所見即所記。結束不再有欠下的請求、也沒有新輸入到達時觸發agent/turn-stopping做最終裁決turn 關閉驅動器打印最終答案并以退出碼0成功或非零失敗退出。整個過程中沒有任何一步是寫死在核心里的特權邏輯——模型怎么連、工具怎么跑、循環怎么驅動全都是樹上掛著的插件任何一個都可以被你自己的 patch 或插件替換掉。這里也順手解釋了使用教程里提到的headless 退出碼turn/end正常走完、最終答案成功產出進程就以0退出如果中途agent/turn-stopping裁決為停止、或在某個 step 的執行流水線里出錯退出碼就是非0。所以你才能在 CI 腳本里直接拿退出碼判斷任務成敗——因為一輪對話在 dsh 里是一個有清晰起止邊界、可被外部觀測的對象而不是一個糊在進程里的黑箱循環。十一、與其它框架的架構對照把 dsh 的底座 Cordis 放進更大的框架版圖里看會更清楚它補的是哪塊空白。Node.js 生態里其實沒有一個框架同時做到插件化 自動 effect 清理 Context 嵌套隔離NestJS有依賴注入DI但沒有 effect tracking——寫 NestJS 插件的人仍然要手動清理 timer、listener漏一個就是線上 bugPluggypytest 的插件系統有 hook 系統但沒有 DI——插件之間不能聲明依賴加載順序得靠人肉約定Effect-TS有 effect 模型但它不是框架——生命周期要用戶自己處理Vue / React 的 plugin context只覆蓋 UI 層沒有應用級的 lifecycle。Cordis 的差異化賣點恰恰是把插件編排 依賴注入 資源自動清理這三件事塞進同一個被形式化過的 Context 類型里。對 dsh 這種 Agent runtime 來說這個組合不是可選項它既要空間上的依賴編排模型適配器沒就緒工具插件就別啟動又要時間上的副作用可逆換個 provider 不能留下半個狀態的殘局還要路徑無關運行時自我重配不能 corruption 自身。這三點單獨看都有人做但只有被同一個統一 Context 從一開始串起來它們才能可靠地組合——這正是那篇論文想論證的核心。十二、結語這套架構真正值錢的地方回過頭看DeepSeek Harness 最值得關注的不是它能跑 Agent而是它用Cordis 的時空可組合性當底座把一個能自我重配而不 corruption 自身狀態的運行時這件事從一句口號變成了有論文背書、有四年 Koishi 實戰沉淀的工程現實。對想基于它做二次開發的人來說這套架構最大的紅利其實是可控的不確定性Agent 系統天生充滿不確定但 dsh 把不確定性關進了插件樹 會話日志這兩個確定性結構里——你能替換任何一部分也能回放任何一段歷史。理解了這兩點你就不會在它快速迭代時迷失反而能借著它的可組合性把自己的業務穩穩長在它上面。對使用者來說這帶來兩個很實在的好處可替換性想換模型、換工具集、換執行環境不需要 fork 改源碼掛個插件、寫個 patch 就行可演進性因為副作用可逆、組合路徑無關系統可以長期運行、熱替換、反復實驗而不必動不動重啟進程。當然必須誠實地說dsh 目前處于Developer Preview官方明確警告會有不兼容的破壞性更新命令和配置都可能變。但無論表層怎么改支撐它的那幾個核心概念——Profile 組合、插件樹、Cordis 運行時、會話日志即真相、能力 seam——大概率會長期存在。抓住這幾個你就能在它持續演進的過程里不迷路。給想深入源碼或寫插件的開發者幾點建議如果你讀到這里想動手幾點實在的經驗讀源碼的入口別一上來翻packages/下的所有東西先讀 Cordis 的 primerdocs/cordis-primer.md和 tutorial再去看core/session、core/tools、core/agent-loop這幾個包——它們是理解日志、工具、循環三條主線的鑰匙。調試先看樹任何為什么我的配置沒生效類的問題第一步永遠是dsh --profile web --dump-config看實際啟動的插件樹里那一行到底長什么樣再決定用哪一層 patch 去改。寫插件時記兩條鐵律一是副作用一定要通過ctx.effect()返回清理函數別自己ctx.on()注冊后不管二是分清你要掛的事件是 waterfall 還是 serial該調next()的地方不調鏈路就斷了。尊重模型可見必進日志這條不變量任何你想讓模型看到的新信息老老實實發一條SessionEvent別圖省事直接塞變量——否則 fork、resume、遙測全都會失真。把這三篇文章連起來看會更完整使用教程帶你把dsh跑起來、把命令用熟概念綜述幫你建立它是什么的整體印象而這篇架構文則是把前兩篇里那些為什么配置要分層“為什么換模型不用改源碼的疑問落到一套可驗證的設計語言上。三篇合起來從會用到懂它為什么這么設計”算是把 DeepSeek Harness 這條線摸透了。本文基于 deepseek-ai/deepseek-harness 官方docs/architecture.md、cordis官方倉庫及社區源碼解讀floatboat.ai、iceyao.com 等整理。dsh 處于快速迭代階段架構細節請以你安裝版本的官方文檔與dsh --profile web --dump-config的實際輸出為準。