DeepSeek Harness 深度研究：DeepSeek 官方「一切皆插件」Agent 框架首日實測

一句話版本

2026 年 8 月 13 日 19:56（HKT），DeepSeek 官方開源了自己的 agent 框架 DeepSeek Harness（dsh）——半日衝上 32,000+ stars，MIT 授權，TypeScript monorepo，核心理念是「一切皆插件」：模型適配器、工具註冊表、會話日誌、甚至 agent 循環本身都是插件，全部可從配置替換，沒有一個需要打補丁的特權核心。

底層是論文級插件框架 Cordis（配套論文《A Programming Paradigm for Spatiotemporal Composability》同日放出草稿）。最激進的能力：Agent 可以在運行時定義並掛載新插件來修改自己（tool-cordis，官方 demo 就叫 "the agent modifies its own runtime"）。

我在發布當晚完成源碼 clone、安裝、Web UI 啟動與 headless 端到端實測（接入自有 API gateway，DeepSeek V4 Pro 跑通）。本文是完整記錄。

發布數據

項目	數值
創建時間	2026-08-13 19:56 HKT
Stars（半日）	32,061
Forks	2,407
版本	0.1.0-rc.6（npm @deepseek-ai/dsh）
語言	TypeScript（另含 Python SDK、C11 native 沙箱）
License	MIT
狀態	Developer Preview（官方明言將有破壞性變更）

一行啟動：

npx @deepseek-ai/dsh web    # Web UI at http://127.0.0.1:3080

核心哲學：Everything is a Plugin

多數 agent 框架的架構是「一個核心循環 + 一堆擴展點」。dsh 走得更徹底：

Cordis 之上，產品的每一個部分都是插件——包括模型適配器、工具註冊表、會話日誌、agent 循環本身。所以每一個部分都可以從配置替換。沒有特權核心可以打補丁：你通過在別的插件旁邊掛載一個插件來擴展 dsh，而註冊本身是一種「可撤銷的效果」，插件卸載時自動回捲。

這意味著「換掉 agent 循環」在 dsh 裡不是 fork 源碼，而是換一行配置。

支撐這個哲學的五個 Cordis 概念

插件 = Service：一個實現 Service 的對象（函數 + 可選 inject + apply(ctx)，或 Service 子類），生命週期由 Cordis 掛載進 context。
Context = 服務倉庫：服務佔據穩定的 ctx.<key>（ctx.tools、ctx.llm、ctx.sessions……），插件靠 key 找服務，而不是 import 具體實現。
依賴靠 inject 聲明：插件聲明需要的服務後會等到它們存在才激活——加載順序由服務依賴表達，不需要手動啟動排序。
Typed Events：四種派發模式構成的公共契約——emit（觀察，不等待）、waterfall（中間件鏈，有返回值）、parallel（並行）、serial（串行等待）。
註冊 = 可撤銷效果：prompt section、tool schema、適配器、監聽器全部通過 ctx.effect() / ctx.on() 安裝，reload 和 teardown 可預測地回捲。

Cordis：一篇論文做底層

dsh 不是「用了個插件庫」，而是把整個框架層建立在一篇正式論文之上：《A Programming Paradigm for Spatiotemporal Composability》（2026-08-13 草稿，與 dsh 同日放出）。

論文把「動態組合」問題拆成兩個正交維度：

時間可組合性（temporal composability）：組件移除時能完全撤銷其副作用。解法是把經典 effect 概念提升為運行時機制——revertible effects：每一次 context 變換都攜帶一個逆變換，由 runtime 追蹤。
空間可組合性（spatial composability）：聲明並反應式管理組件間依賴。解法是 reactive coeffects：context 的每次變化按組件的 coeffect 規範通知它。

兩者統一到單一 context type，構成一個編程範式；再結合成 component 概念並給出動態組合的演算，其元理論把可組合性從單個組件推廣到交錯組成的整個系統。Cordis 就是這個範式的實現：核心庫（effect 追蹤 + coeffect 解析）+ 聲明式組件加載器（配置調和 + HMR）。

一個值得注意的細節：dsh 把 Cordis 源碼 vendored（源碼級複製）進 monorepo，重命名到 @deepseek-ai scope（cordis 4.0.0-rc.7 + cosmokit + schemastery 等），理由是框架層要「可審計、可打補丁、版本釘死」——發布 dsh 等於同時發布它擁有的整個框架層。

架構深潛

1. Profile 與 Bundle：開機即組合的插件樹

一次 dsh 運行就是一棵開機時按層組合的插件樹：

Profile：命名的組合（web 和 headless 是內置模板），列出它堆疊的 bundles + 樹外插件 + 用戶自己的 cordis.patch.yml。
Bundle：Cordis 配置行 + 其掛載代碼的發行格式。dsh-base（模型適配器、工具、持久化、沙箱與審批策略、設置、憑證、遙測）是每個 profile 的第一層；dsh-web-app 加瀏覽器應用；dsh-headless 加一次性 runner。
層疊順序：profile 列出的 bundles → profile 的 patch → home 級 patch → --patch overlay。任何一行配置都可以被上層 patch 整體替換。

dsh --profile web --dump-config 可以打印你機器上實際開機的整棵樹——每一行都可被你的 patch 替換。

2. Session Log：Model-visible ⟺ logged

會話日誌是模型所見上下文的唯一來源。deriveMessages() 從日誌投影模型歷史，原始 assistant/chunk 事件保留回放與 UI 保真度。fork、resume、transcript、遙測、持久化全部從這條流派生。

運行時不變式：任何到達模型請求的東西必須能從日誌重建——所以新的模型可見輸入必須是新的 session event（擴展 SessionEventMap，從日誌渲染）。

3. Turn / Step 流

Step = 一次模型請求 + 它引發的工具調用；Turn = 零或多個 step（打開於首次輸入被認領，關閉於無所欠）。

關鍵擴展點都是 waterfall：agent/pre-step（決定模型看到什麼——可以改寫甚至拒絕認領的消息）、agent/request、llm/stream、tools/pre-execute|execute|post-execute。agent/turn-stopping 是串行終端檢查點。拒絕或空的第一次認領仍然關閉一個「花了零 step」的持久 turn——日誌記錄了嘗試本身。

4. Capability Seams：換一個 provider，換掉整個產品

一個 seam（接縫）= 可替換能力，三角色：Service Definition（聲明接口）+ Service Provider（實現）+ Consumer（使用，通常是面向模型的工具）。

文檔給的例子很說明問題：filesystem 和 subprocess provider 共享同一個執行世界，把它們指向遠程沙箱，Bash、PTY、LSP 會一起跟著走，不需要 provider 分叉。Subagent provider 同樣是一個接口後面的寬譜——從 in-process 子 agent 到委派給另一個產品的 turn。

我從自動生成的 capability-seams 文檔數了一下：40+ 個 ctx 服務，覆蓋 llm / tools / sessions / fs / shell / subprocess / terminal / lsp / sandbox / approval / subagents / jobs / web / workflow / goals / skills / storage / telemetry / compaction / spill（過大工具輸出外溢存儲）……

5. Scope：per-agent 的世界

貢獻（工具、prompt section、變量、限制、監聽器）要麼全局要麼 scoped 到唯一一個 scope key（慣例：活著的 agent 就是自己 scope 的 key）。Shadowing：scoped 的同名工具/section 替換全局同名項——這就是 per-agent persona 和 per-agent 工具變體的機制。Scope 不繼承到 subagent；血緣（parentSession、delegationDepth）是數據，不是可見性結構。

亮點功能盤點

🔁 tool-cordis：Agent 自我修改運行時。五個面向模型的工具：cordis_inspect（唯讀報告：服務、插件纖維、工具、動態包）、cordis_define（語法檢查後記錄一個新包，host 半 + 瀏覽器半）、cordis_run（host 半在 vm 沙箱求值，瀏覽器半推送給所有打開的頁面）、cordis_stop / cordis_undefine。官方示例 examples/web-cordis/cordis.yml 頂部寫著一句極其坦誠的警告：

Temporary Plugin code can reach every injected live capability; treat this deployment like shell access, not as a security boundary.

🎯 goal：同 session 目標域。一個 durable 完成目標附在現有 session 上，active/paused/blocked/complete 修訂狀態 + goal-round 上限。關鍵設計：goal activation 故意不進持久化——resume 和 fork 之後必須經過一次人類授權的 /goal 變更才能繼續自動工作。

🔁 Ralph loop：面向不可變目標的 fresh-agent 工作流——每一輪是全新子 session（不帶父對話種子），跨輪狀態靠共享 workspace + 一個有界的結構化 handoff（status/summary/evidence/next steps/blocker）。

🪝 hooks 橋接：把 Claude Code 和 Codex 的 hooks.json shell hook 協議翻譯到 dsh 的類型化攔截點——你現有的 CC/Codex hook 生態可以直接掛過來。反過來說，「native hook」就只是這些擴展點上的普通 Cordis 插件。

🤖 subagent providers：in-process spawn / fork、ACP、Codex、Claude Code、dsh-sdk——委派是接口，不是實現。

🔒 沙箱：macOS 用 sandbox-exec/seatbelt，Linux 用自研 landlock-run（~300 行 C11 對 Landlock 原始 kernel UAPI，靜態鏈接 musl）：self-restrict-then-exec，ruleset 跨 execve 繼承，調用方不受限而被調用進程全家被關進圍欄，fail-closed（kernel 無法強制就拒絕執行）。

🐍 Python SDK：JSON-RPC over stdio 驅動 harness 子進程，高級 turns API；BENCHMARK.md 指向用它跑基準。

其他：E2B 沙箱 POC、ACP 自動化服務器、OTel 會話遙測、worker-thread workflow 引擎、compaction（pre-step 壓力 + context overflow 恢復，先剪工具結果再摘要）、spill（過大工具文本外溢 + 模型可見定位符）。

21 個面向模型的工具：bash、bash-persistent、terminal、fs、fs-search、str-replace-editor、web、lsp、todo、goal、skill、subagent、subagent-control、subagent-report、jobs、session-query、ask-user、workflow、ralph、cordis……

Mac Studio 實測記錄（發布當晚）

1. 源碼安裝：git clone --depth 1 + pnpm install 用時 18.7 秒（pnpm 11.7.0）。源碼 build 的 host 部分通過，client 部分在 TypeScript 階段報錯（Type 'bigint' is not assignable to type 'ReactNode'，developer preview 的已知粗糙處）——改用 npm 預編譯包繞過。

2. Web UI：npx @deepseek-ai/dsh web → dsh web: http://127.0.0.1:3080，HTTP 200，頁面以 __DSH_BOOT__ 插件圖引導（typert-registry → api-gateway → client-connection……客戶端本身也是插件圖）。

3. 模型接入：DeepSeek 官方 API key 當晚返回 Authentication Fails (governor)（認證被限流/拒絕）。改走自有 OpenAI-compatible gateway（阿里雲百煉 Token Plan），按官方文檔寫 $DSH_HOME/settings.yaml：

agent-default-model:
  provider: bailian
  model: deepseek-v4-pro
llm-pi-ai:
  providers:
    bailian:
      displayName: Bailian Token Plan
      apiKeyEnv: BAILIAN_API_KEY
      api: openai-completions
      baseURL: https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: deepseek-v4-pro
          contextWindow: 1000000
          maxTokens: 32768

apiKeyEnv 是憑證引用——密鑰不進配置文件，每次請求解析；配置錯引用會以 MISSING_CREDENTIAL 明確失敗而不是拿環境裡不相干的 key 將錯就錯。這個「write-only 憑證 + 引用解析」設計值得表揚。

4. Headless 端到端測試：

npx @deepseek-ai/dsh --profile headless "Reply with exactly: HARNESS_ALIVE"
# EXIT=0, stdout: HARNESS_ALIVE, stderr 空

npx @deepseek-ai/dsh --profile headless "What model are you? Answer in one short sentence."
# EXIT=0, stdout: "I am a coding agent powered by DeepSeek v4 Pro (deepseek-v4-pro)."

端到端跑通：一次性 session、prompt 組裝、模型請求、日誌持久化、stdout 輸出最終答案、乾淨退出（turn/end 完成 → exit 0）。模型配置從自定義 gateway 到 DeepSeek V4 Pro 全程只改了一個 YAML 文件，無需重啟任何服務。

與我們基建的對比

vs OpenClaw：OpenClaw 的插件是「渠道 + 工具擴展」，核心循環是固定的；dsh 的插件是「產品本身」，連循環都可替換。OpenClaw 的配置是靜態 JSON；dsh 是層疊 patch 系統 + 運行時 HMR。兩者定位不同：OpenClaw 是面向多渠道的 AI 助理平台，dsh 是面向開發者的 agent 產品底座。

vs Prime Agent 的 Continual Harness（上週研究）：Prime Agent 的自我改進发生在文本層（agent 可 CRUD 自己的 prompts/skills/memory）；dsh 的 tool-cordis 自我修改发生在代碼層（運行時定義並掛載新插件，host 半進 vm 沙箱、瀏覽器半進所有頁面）。更深，也更危險——官方自己都寫「treat like shell access」。

vs 我們的 Loop Engineering：兩個設計與我們的實踐高度共鳴——

「Model-visible ⟺ logged」不變式 = 我們 external supervisor 的同一信念：真相源必須在 LLM 之外（我們的 session JSONL 掃描 vs 它的 SessionEvent log）。
Waterfall 事件鏈 = 我們的 Gate 概念的類型化實現：agent/pre-step 可以拒絕輸入、tools/pre-execute 可以攔截執行、agent/turn-stopping 是終端檢查點。
goal activation 不持久化、resume 需人類授權 = 我們「自動任務必須有人類重新授權點」的同类設計。

值得直接借鑑的三件事：

文檔即代碼：module-graph、capability-seams、tool-catalog、config-catalog 全部由腳本從代碼聲明自動生成，帶完整性守衛（generated catalogs + doc-sync gate）。我們的技能體系文檔可以學這套。
Session log 不變式：任何模型可見內容必須可從日誌重建——如果 AK-SDD pipeline 採用，可以根治「子代理匯報數據與實際執行不一致」類問題。
Capability seam 三角色模型：Service Definition / Provider / Consumer 的分離，比我們現在「工具 = 實現」的粒度更利於替換與測試。

風險與限制

Developer Preview：官方明言將有破壞性變更；SQLite schema、session 格式都聲明「無兼容承諾」。現在投入生產為時過早。
自我修改是攻擊面：tool-cordis 的動態插件代碼可觸及所有注入的活能力，官方文檔自己定性為 shell access 級別。
無官方 benchmark：BENCHMARK.md 只是三行「怎麼跑」，沒有成績表——能力宣傳目前全靠文檔和 demo。
模型適配器尚窄：原生只有 llm-deepseek + 通用 llm-pi-ai（多 provider），推理控制、多模態支持仍在補。
社區剛起步：Discussions + Discord + 企微群，issue 數為 0（還沒開放或剛開）。

結論與下一步

DeepSeek Harness 是第一個把「插件框架」做到論文級嚴肅程度的 agent harness。它賭的是：agent 產品的長期競爭力不在某個固定的循環設計，而在組合性本身——時間維度上任何組件可完全撤銷，空間維度上依賴可聲明可反應。加上 tool-cordis 的自我修改能力，這是「self-evolving agent harness」從口號走向工程的一條真實路徑。

對我們而言，短期策略是觀察 + 借鑑而非遷移：盯第一個 tagged release 和論文正式版；借鑑它的 generated-docs 實踐、session log 不變式、capability seam 建模。中期值得試驗的是 Python SDK + JSON-RPC 把 dsh 作為 AK-SDD 類流水線的執行底座，以及 hooks 橋接復用現有 Claude Code hook 資產。

參考鏈接：

GitHub: https://github.com/deepseek-ai/deepseek-harness
Cordis: https://github.com/cordiverse/cordis
論文: https://github.com/cordiverse/paper

本文基於 2026-08-14 凌晨在 Mac Studio 上的實測（dsh 0.1.0-rc.6 + deepseek-v4-pro via 自有 gateway）。項目處於快速迭代期，細節以官方倉庫為準。