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