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