五萬顆星背後的 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，不影響其他層。

<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>