五萬顆星背後的 Agent 設計：ByteDance DeerFlow 2.0 的架構拆解

——

▍TL;DR

1. DeerFlow 2.0 不是框架，是 Harness——它提供 Agent 運行所需的一切基礎設施（檔案系統、沙箱、記憶體、子 Agent 調度），但不規定你怎麼組裝 Agent
2. 核心架構是 Middleware Pipeline：每則訊息通過 15 層中間件，從上下文壓縮、迴圈偵測到記憶體萃取，全部解耦成獨立模組
3. 嚴格的 Harness 邊界：App 可以 import Harness，但 Harness 永遠不能 import App——這條規則用自動化測試強制執行
4. 每個對話 Thread 對應一個真實的檔案系統目錄，Agent 看到的是虛擬路徑 /mnt/user-data/，底層映射到隔離的工作空間
5. 從 v1 到 v2 完全重寫，零共用程式碼——這本身就是一個值得研究的架構決策

——

DeerFlow（bytedance/deer-flow）是 ByteDance 開源的 Agent 基礎設施專案，MIT 授權。目前 50,700+ 星、6,000+ fork，技術棧是 Python + TypeScript，底層用 LangGraph + LangChain 做 Agent 編排，FastAPI 做 Gateway，前端用 Next.js。

v1 在 2025 年 5 月發佈，定位是「Deep Research 多 Agent 框架」，走的是經典的 Coordinator-Executor 模式：Planner 拆解問題、Researcher 搜集資料、Coder 執行程式碼、Reporter 產出報告。這個架構在做研究型任務時表現不錯，但團隊顯然不滿足於此。

2026 年 2 月，v2 上線，與 v1 零共用程式碼。他們把定位從「框架」改成「Harness」——這個詞選得很精準。框架規定你的程式碼怎麼跑；Harness 提供環境讓你的 Agent 能跑。

——

▍Middleware Pipeline：DeerFlow 最核心的設計模式

如果只能記住 DeerFlow 的一個設計決策，就是這個。

傳統的 Agent 系統通常是一個大迴圈：接收訊息 → LLM 思考 → 呼叫工具 → 回傳結果。所有邏輯（記憶體管理、錯誤處理、token 限制、迴圈偵測）都塞在同一個迴圈裡，互相纏繞。DeerFlow 把這些關注點拆成一條 15 層的 Middleware Chain，每則訊息在到達 Lead Agent 之前，依序通過：

1. ThreadDataMiddleware — 隔離每個 Thread 的工作目錄
2. UploadsMiddleware — 注入使用者上傳的檔案上下文
3. SandboxMiddleware — 取得執行環境（Local / Docker / K8s）
4. SummarizationMiddleware — 壓縮已完成子任務的上下文，避免撞 token 上限
5. TodoListMiddleware — 追蹤跨步驟的任務清單
6. TitleMiddleware — 自動產生對話標題
7. MemoryMiddleware — 非同步排隊記憶體萃取
8. ViewImageMiddleware — 注入多模態視覺資料
9. ClarificationMiddleware — 需要時中斷流程向人類確認
10. LoopDetectionMiddleware — 偵測並阻止 Agent 無限迴圈
11. SubagentLimitMiddleware — 限制子 Agent 的生成數量
12. TokenUsageMiddleware — 追蹤 token 消耗
13. ToolErrorHandlingMiddleware — 優雅處理工具呼叫失敗
14. DanglingToolCallMiddleware — 清理未完成的工具呼叫
15. DeferredToolFilterMiddleware — 管理延遲載入的工具

這個設計的好處是顯而易見的：每層 Middleware 只管一件事，可以獨立測試、獨立替換。想加一個新的安全檢查？寫一個 Middleware 插進去就好。想改記憶體策略？只動 MemoryMiddleware，不影響其他層。

這讓我想到 Express.js 或 Koa 的中間件模式——只是這次處理的不是 HTTP Request，而是 Agent 的訊息流。Web 框架用了二十年的模式，終於被搬到 Agent 架構上了。

——

▍Lead Agent + Sub-Agent：不是多 Agent 對話，是委派與隔離

DeerFlow v2 的 Agent 模型跟 AutoGen 那種「多 Agent 對話」很不一樣。它的核心是一個 Lead Agent（用 LangGraph 編譯的狀態圖），由 make_lead_agent(config) 建立。Lead Agent 是唯一的主推理節點，負責理解使用者意圖、規劃步驟、呼叫工具。

當任務複雜到需要並行處理，Lead Agent 會 spawn Sub-Agent。內建兩種：general-purpose（通用型）和 bash（終端執行型）。Sub-Agent 跑在隔離的上下文裡，完成後把結果回傳給 Lead Agent 做整合。

這裡的關鍵是「隔離」而不是「對話」。Sub-Agent 不會跟 Lead Agent 來回討論；它拿到一個任務、執行、回報。這比多 Agent 對話的模式更可預測、更容易 debug。

SubagentExecutor 負責管理背景執行，AgentRegistry 追蹤可用的 Agent 定義，配合 subagents_config.py 和 config.yaml 做設定。整個子 Agent 系統的設計哲學是：Lead Agent 是大腦，Sub-Agent 是手腳——手腳不需要自己的世界觀。

——

▍Thread-as-Workspace：每個對話都是一個真實的檔案系統

這是 DeerFlow 裡我覺得最巧妙的設計之一。

每個對話 Thread 在底層對應一個實體目錄：

backend/.deer-flow/threads/{thread_id}/
  user-data/
    workspace/    # Agent 的工作目錄
    uploads/      # 使用者上傳的檔案
    outputs/      # Agent 產出的結果

但 Agent 看到的路徑是虛擬化的：/mnt/user-data/workspace/、/mnt/user-data/uploads/、/mnt/user-data/outputs/。這層路徑虛擬化帶來幾個好處：

• Agent 的檔案操作是真實的 I/O，不是模擬的狀態——它可以真的寫檔案、讀檔案、跑程式
• 不同 Thread 的檔案完全隔離，不會互相干擾
• Agent 不需要知道自己跑在哪台機器、哪個目錄，虛擬路徑是統一的介面

這個設計解決了很多 Agent 框架的一個根本問題：Agent 的「記憶」和「工作成果」到底存在哪裡？很多框架用 JSON 狀態來模擬，但真實世界的任務（寫程式碼、產生報告、處理資料）需要真實的檔案系統。DeerFlow 直接給你一個。

——

▍Harness 邊界：一條用測試守護的架構紅線

DeerFlow 的 codebase 裡有一個檔案叫 tests/test_harness_boundary.py。它做一件事：確保 harness 套件永遠不會 import app 套件的任何東西。

這條規則聽起來簡單，但含義深遠。它意味著 DeerFlow 的核心 Agent 基礎設施（Middleware、記憶體、沙箱、Sub-Agent 調度）完全不依賴上層應用邏輯。你可以把 Harness 拿去接一個完全不同的前端、一個完全不同的 API Gateway，它都能跑。

這跟很多「全家桶」框架的做法相反。CrewAI、AutoGen 通常把 Agent 邏輯和應用邏輯綁在一起——方便快速上手，但一旦要客製化就會撞牆。DeerFlow 選擇在第一天就畫這條線，犧牲一點入門便利性，換取長期的可組合性。

在套件結構上，harness/deerflow/ 底下有 16 個以上的 config 模組（model、sandbox、skills、subagents、tools、guardrails、extensions、summarization、token_usage、tracing 等等），每一個都是獨立可配置的。config.yaml 用 version 3 的格式統一管理，支援環境變數插值。

——

▍記憶體系統：雙層架構 + 信心分數

DeerFlow 的記憶體分兩層：

短期記憶：在 LangGraph 的 context window 內，由 SummarizationMiddleware 管理。當對話太長，已完成的子任務結果會被壓縮（offload 到檔案系統），只保留摘要在 context 裡。這讓長時間運行的任務不會因為 token 上限而崩潰。

長期記憶：存在 memory.json 裡，每條記憶有信心分數。MemoryMiddleware 會非同步分析對話內容，萃取出有價值的使用者偏好和事實，標上信心分數後存入。下次對話時，高信心分數的記憶會被注入到 Agent 的 prompt 裡。

信心分數這個設計很有意思。不是所有從對話中萃取的「事實」都一樣可靠——使用者隨口提到的偏好，和明確要求你記住的指令，可靠度當然不同。用數值量化這個差異，比單純的「記住 / 不記住」更細緻。

——

▍沙箱：三種隔離等級

Agent 執行程式碼需要沙箱，DeerFlow 提供三種：

模式	Provider	適用場景
Local	LocalSandboxProvider	開發環境，直接用本機檔案系統
Docker	AioSandboxProvider (local)	測試環境，每個 Agent 一個容器
Kubernetes	AioSandboxProvider (remote)	生產環境，透過 Provisioner 服務動態分配

每個沙箱提供：真實的檔案系統、Bash 終端、程式碼執行、瀏覽器存取。系統會自動偵測是否在 Docker 環境中運行並選擇適當的 Provider。

這個分層設計讓開發者可以在本機用 Local 模式快速迭代，CI 用 Docker 模式跑測試，生產環境用 K8s 模式確保隔離。同一份 config.yaml 改一個欄位就切換。

——

▍跟其他框架比，DeerFlow 的定位在哪？

	DeerFlow 2.0	CrewAI	AutoGen	裸 LangGraph
定位	Harness（基礎設施）	角色扮演框架	多 Agent 對話	底層圖原語
Agent 模型	Lead + Sub-Agent + Middleware	角色分工的 Crew	Agent 間對話協商	自己組裝
沙箱	內建（三種等級）	需外接	可配置	無
記憶體	雙層 + 信心分數	短期 + 外部存儲	對話歷史	只有 Checkpointing
部署型態	完整應用棧	Library	Library	Library / Server
IM 整合	Telegram / Slack / 飛書	無	無	無

DeerFlow 最大的差異化在於：它是唯一一個以完整應用棧（nginx + Gateway + LangGraph Server + 沙箱 + IM 頻道）而非 Library 形式發佈的。你 docker compose up 就有一整套可用的 Agent 基礎設施，不需要自己黏合。

但這也是它的門檻：你需要 Docker、YAML、CLI 的經驗，比起 pip install crewai 然後寫二十行 Python，上手成本高得多。

——

▍對 Agent 系統設計的幾個啟示

看完 DeerFlow 的架構，有幾個 takeaway 我覺得不限於這個專案：

Middleware 模式應該被更多 Agent 框架採用。 把記憶體、錯誤處理、迴圈偵測、token 管理這些橫切關注點抽成可插拔的中間件，比塞在一個大迴圈裡好維護一個數量級。Web 框架證明了這點二十年了，Agent 框架不應該重新犯同樣的錯。

「隔離」比「對話」更實用。 多 Agent 對話聽起來很酷，但在實際的工程任務中，你更需要的是一個 Agent 把任務拆開、分給子 Agent 各自執行、收回結果。不需要它們互相討論——那只會增加不可預測性和 token 消耗。

給 Agent 真實的檔案系統，不要模擬。 Thread-as-Workspace 這個設計看似簡單，但它解決了「Agent 的工作成果存在哪裡」這個根本問題。JSON 狀態管理在玩具範例裡夠用，真實任務需要真實的 I/O。

架構邊界要用測試守護，不能靠文件。 test_harness_boundary.py 只有幾行，但它比任何架構文件都管用。人會忘記規則，import 語句不會忘記繞過測試。

——

DeerFlow 2.0 從零重寫這個決策本身就很有意思。v1 有幾千顆星，社群已經在用了，但他們還是決定全部打掉重來。這說明他們在 v1 的開發過程中發現了一些根本性的架構問題，是修修補補解決不了的。從結果來看，v2 的 Middleware Pipeline + Harness 邊界 + Thread 隔離這套設計，確實比 v1 的 Coordinator-Executor 模式成熟了不只一個層次。

對於正在設計 Agent 系統的人來說，DeerFlow 的原始碼是非常好的學習材料——不是因為它一定是最好的方案，而是因為它的每一個設計決策都有明確的理由，而且那些理由用測試和架構邊界強制執行，而不是寫在文件裡祈禱大家遵守。

相關資源：

• bytedance/deer-flow — GitHub repo（MIT 授權）
• DeerFlow 2.0 發佈文章 — MarkTechPost
• DeepWiki 架構分析 — 詳細的程式碼層級分析

<h2>延伸閱讀</h2> <ul> <li><a href="/blog/anatomy-of-agent-harness">拆解 Agent Harness — 你以為的 AI Agent 其實 90% 是 harness</a></li> <li><a href="/blog/kensho-financial-agent-with-langgraph-practical-analysis-of-multi-agent-system">Kensho 用 LangGraph 做金融 Agent — 多 Agent 系統實戰解析</a></li> <li><a href="/blog/how-we-monitor-internal-coding-agents-for-misalignment">How we monitor internal coding agents for misalignment</a></li> </ul>