主题
项目概览
本章目标:
- 用一句话说清 DeerFlow 2.0 到底是什么、它跟 1.x 的本质区别在哪
- 理解「super agent harness」这个定位解决了什么问题,以及它由哪几块能力拼成
- 建立全局心智地图:四个进程组件 + harness/app 双层 + 各核心子系统的位置,知道后续每一章在讲哪一块
TL;DR
DeerFlow 2.0 是一个开源的「超级 agent 运行底座」(super agent harness):在 LangGraph / LangChain 之上,把一个 agent 真正干活所需的基础设施——文件系统、长期记忆、技能(skills)、沙箱化执行、子代理(sub-agent)派生——打包成开箱即用又可拆解替换的整体。它是对 1.x「Deep Research 框架」的从零重写,两者不共享代码 README.md:16-17。运行形态是一个嵌入了 LangGraph 兼容 agent runtime 的 Gateway API,前端为 Next.js,统一经 Nginx 反向代理。代码分为可独立发布的 deerflow.* harness 包与不发布的 app.* 应用层。
Overview(为什么会有 DeerFlow 2.0)
要理解 DeerFlow 2.0,先看它要回答的问题:一个大模型 agent 想真正「干活」,缺的不是模型,而是干活的环境。
只有一个会调用工具的 LLM,会立刻撞上四堵墙:
- 没有持久工作区:agent 生成的文件、中间产物放哪?多轮之间怎么留存?
- 没有记忆:换个对话就失忆,无法积累对用户/任务的认知。
- 没有隔离:让模型执行
bash、写文件,直接跑在宿主机上是安全灾难。 - 不会分解复杂任务:单个 agent 上下文有限,长任务需要能派生子代理并行推进。
DeerFlow 团队的原话点明了这个转变:项目最初是一个 Deep Research 框架,但社区把它用去做数据管线、生成幻灯片、搭看板、自动化内容流水线——这说明它本质不是「研究工具」,而是一个给 agent 提供「真正把事做完」所需基础设施的 harness,于是被从零重写为 2.0 README.md:466-476。
所以 DeerFlow 2.0 的设计答案是:不做「又一个 agent 框架让你自己接线」,而是电池全含、又完全可拆——文件系统、记忆、skills、沙箱感知执行、规划与派生子代理全部内建,可原样用,也可拆开改成自己的 README.md:12。
这套「harness」由五块能力支撑:
Architecture
DeerFlow 2.0 在进程拓扑和代码分层两个维度上各有一套结构,先看进程拓扑。
| 组件 | 端口 | 角色 | 说明 |
|---|---|---|---|
| Gateway API | 8001 | REST API + 内嵌 LangGraph 兼容 agent runtime | agent 运行时不是独立进程,而是跑在 Gateway 里 |
| Frontend | 3000 | Next.js Web 界面 | 通过 nginx 连后端 |
| Nginx | 2026 | 统一反向代理入口 | /api/langgraph/*→Gateway runtime,/api/*→Gateway REST,/→前端 |
| Provisioner | 8002 | 沙箱供给(可选) | 仅 sandbox 配为 provisioner/K8s 模式时启动 |
关键设计:agent runtime 内嵌在 Gateway 进程里,经
RunManager+run_agent()+StreamBridge驱动;Nginx 把对外的 LangGraph 兼容路径/api/langgraph/*重写到 Gateway 原生/api/*路由 backend/CLAUDE.md。langgraph.json把名为lead_agent的图指向deerflow.agents:make_lead_agent,这就是整个 agent 的图入口 backend/langgraph.json:8-9。
再看代码分层——这是阅读源码时最重要的一张地图:
deerflow.* 是一个独立命名、可发布的包 deerflow-harness(version 0.1.0,描述为 "DeerFlow agent harness framework")backend/packages/harness/pyproject.toml:2-4。依赖方向是单向的:app 可以 import deerflow,但 deerflow 永不 import app——这条边界由 CI 中的 tests/test_harness_boundary.py 强制(详见 Harness 与 App 分层边界)。
Components / 核心子系统
下面是这份 wiki 会逐章展开的子系统清单,本章只给「是什么 + 在哪 + 去哪一章看」,不展开实现:
| 子系统 | 一句话职责 | 代码位置 | 详见章节 |
|---|---|---|---|
| Lead Agent | LangGraph 主代理,组装模型/工具/中间件/系统提示词 | deerflow/agents/lead_agent/agent.py | 10 |
| 中间件链 | 18 个 middleware 按严格顺序拦截 model/tool 调用 | deerflow/agents/middlewares/ | 12 |
| Sandbox | 抽象隔离执行环境(本地/Docker/K8s) | deerflow/sandbox/ | 17 |
| 子代理 | task 工具派生后台子代理并发推进 | deerflow/subagents/ | 19 |
| 工具 / MCP | web search/fetch、文件、bash、MCP 外部工具 | deerflow/tools/、deerflow/mcp/ | 20、21 |
| Skills | Markdown 定义的能力模块,渐进式加载 | deerflow/skills/、skills/ | 22 |
| 长期记忆 | LLM 抽取事实/上下文,按用户隔离持久化 | deerflow/agents/memory/ | 23 |
| Gateway API | FastAPI,REST + LangGraph 兼容 runtime | app/gateway/ | 13 |
| IM 通道 | 把外部聊天平台桥接到 agent | app/channels/ | 26 |
| 嵌入式客户端 | 进程内直接调用 agent,无需 HTTP 服务 | deerflow/client.py | 32 |
DeerFlowClient 提供「无 HTTP 服务」的进程内访问方式,可直接 client.chat(...) 或 client.stream(...),它 import 与 Gateway 完全相同的 deerflow 模块,共享同一份配置与数据目录 backend/packages/harness/deerflow/client.py:1-16。
Data Flow / 一次请求的全景
下面这张时序图展示一条 Web 用户消息从浏览器到 agent 再回流的主干路径(细节在各专章展开):
逐步说明:
- 浏览器请求走 Nginx 的 LangGraph 兼容路径,被重写到 Gateway 原生路由。
- Gateway 通过
RunManager创建一个后台 run。 - run 驱动
make_lead_agent(config)编译出来的 LangGraph 图 backend/packages/harness/deerflow/agents/lead_agent/agent.py:343。 - 图执行过程中,中间件链在模型/工具调用前后插入逻辑(注入 sandbox、uploads、memory,做 guardrail、审计、循环检测等)。
- 产出经
StreamBridge以 SSE 流回 Gateway → Nginx → 浏览器。
核心特性速查表
DeerFlow 的「能做几乎任何事」靠的是 skills + tools 的可扩展哲学,而非把功能写死。下表是 README 列出的核心能力面:
| 特性 | 关键点 | Source |
|---|---|---|
| Skills & Tools | Markdown 定义能力模块,渐进式加载(用到才载,省 context);工具可经 MCP / Python 函数自定义 | README.md:478-492 |
| Sub-Agents | 复杂多步任务可规划并派生子代理 | README.md:12 |
| Sandbox & 文件系统 | 三种执行模式:本地 / Docker / Kubernetes(provisioner) | README.md:322-331 |
| 长期记忆 | 按用户隔离持久化,自动注入系统提示词 | README.md:73 |
| IM 通道 | Telegram/Slack/Feishu/WeChat/WeCom/DingTalk,均无需公网 IP | README.md:341-351 |
| 可观测性 | 内建 LangSmith / Langfuse tracing,可同时启用 | README.md:553-585 |
Common Pitfalls / 实战 Tips
- 别在 1.x 找 2.0 的代码:2.0 是从零重写,与 1.x 不共享任何代码;原 Deep Research 框架在
main-1.x分支维护,活跃开发已迁到 2.0 README.md:16-17。 - agent runtime 不是独立服务:它内嵌在 Gateway 进程里。想直接调 agent 而不起 HTTP,用
DeerFlowClient(见第 32 章),它和 Gateway 走的是同一套deerflow模块与配置 backend/packages/harness/deerflow/client.py:1-16。 - 改 harness 代码前先记住边界:任何在
packages/harness/deerflow/下from app...的 import 都会让 CI 失败(见第 9 章)。
References
- README.md:12 — 项目一句话定位:super agent harness
- README.md:16-17 — 2.0 是从零重写,与 1.x 不共享代码
- README.md:466-476 — 从 Deep Research 到 super agent harness 的演进动机
- backend/langgraph.json:1-13 — LangGraph 图入口/auth/checkpointer 注册
- backend/packages/harness/pyproject.toml:2-4 — harness 作为可发布包
deerflow-harness - backend/packages/harness/deerflow/agents/lead_agent/agent.py:343 —
make_lead_agent图入口 - backend/packages/harness/deerflow/client.py:1-16 — 嵌入式客户端定位
- backend/CLAUDE.md — 后端架构全景(项目内开发文档)
Related Pages
| Page | Relationship |
|---|---|
| 系统整体架构 | 本章给出全景,该章详细拆解四组件与请求流 |
| Harness 与 App 分层边界 | 本章提到的 deerflow.*/app.* 单向依赖在该章深入 |
| Lead Agent 与 Agent 工厂 | 本章提到的 make_lead_agent 图入口在该章展开 |
| 快速开始与安装 | 读完概览后,该章给出最短上手路径 |