🦌 DeerFlow 2.0 架构分析报告

报告生成时间：2026-04-02

项目版本：DeerFlow 2.0 (彻底重写版)

分析范围：后端架构、前端架构、核心模块、扩展系统

📑 目录

1. 执行摘要
2. 系统架构概览
3. 后端架构详解
4. 前端架构详解
5. 核心模块分析
6. 扩展系统
7. 部署架构
8. 安全机制
9. 总结与建议

1. 执行摘要

DeerFlow 2.0 是字节跳动开源的 Super Agent Harness 框架，从 Deep Research 工具演进为通用的 Agent 运行时基础设施。基于 LangGraph 和 LangChain 构建，提供开箱即用的多 Agent 编排能力。

核心定位：DeerFlow 不只是一个研究工具，而是一个真正让 Agents 把事情做完的运行时基础设施。

关键特性

Sub-Agents 架构：Lead Agent 可动态拉起多个 Sub-Agent 并行执行复杂任务
Sandbox 执行环境：隔离的 Docker 容器或本地沙箱，支持文件操作和命令执行
Skills 系统：可扩展的能力模块，支持按需加载和组合
长期记忆：跨 Session 的持久化记忆，支持用户偏好和工作习惯学习
Context Engineering：智能上下文管理，包括摘要压缩和子任务隔离
IM 渠道集成：支持 Telegram、Slack、飞书等即时通讯工具

2. 系统架构概览

┌──────────────────────────────────────────────────────────────────────────┐ │ Client (Browser) │ └─────────────────────────────────┬────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────────────┐ │ Nginx (Port 2026) │ │ 统一反向代理入口 │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ /api/langgraph/* → LangGraph Server (2024) │ │ │ │ /api/* → Gateway API (8001) │ │ │ │ /* → Frontend (3000) │ │ │ └────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────┬────────────────────────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ LangGraph Server │ │ Gateway API │ │ Frontend │ │ (Port 2024) │ │ (Port 8001) │ │ (Port 3000) │ │ │ │ │ │ │ │ - Agent Runtime │ │ - Models API │ │ - Next.js App │ │ - Thread Mgmt │ │ - MCP Config │ │ - React UI │ │ - SSE Streaming │ │ - Skills Mgmt │ │ - Chat Interface │ │ - Checkpointing │ │ - File Uploads │ │ │ │ │ │ - Thread Cleanup │ │ │ │ │ │ - Artifacts │ │ │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘

端口规划

端口	服务	协议	说明
`2026`	Nginx	HTTP/WS	统一入口，反向代理
`2024`	LangGraph Server	HTTP/SSE	Agent 运行时，核心引擎
`8001`	Gateway API	HTTP	REST API，非 Agent 操作
`3000`	Frontend	HTTP	Next.js 前端应用

3. 后端架构详解

3.1 技术栈

Python 3.12+ YAML JSON

核心依赖

LangGraph: 多 Agent 编排框架
LangChain: LLM 交互和 Chains
FastAPI: Gateway API 框架
Uvicorn: ASGI 服务器

3.2 目录结构

backend/
├── app/                          # 应用层
│   ├── gateway/                  # Gateway API
│   │   ├── app.py               # FastAPI 应用入口
│   │   ├── routers/             # API 路由
│   │   │   ├── agents.py        # Agents 管理
│   │   │   ├── mcp.py           # MCP 配置
│   │   │   ├── skills.py        # Skills 管理
│   │   │   ├── threads.py       # Threads 管理
│   │   │   ├── uploads.py       # 文件上传
│   │   │   └── ...
│   │   └── services.py          # 业务服务
│   └── channels/                 # IM 渠道
│       ├── manager.py           # 渠道管理器
│       ├── telegram.py          # Telegram Bot
│       ├── slack.py             # Slack Bot
│       └── feishu.py            # 飞书 Bot
├── packages/harness/deerflow/   # 核心 Harness
│   ├── agents/                  # Agent 系统
│   │   ├── lead_agent/          # Lead Agent
│   │   ├── middlewares/         # 中间件链
│   │   ├── memory/              # 记忆系统
│   │   └── checkpointer/        # 检查点
│   ├── tools/                   # 工具系统
│   │   └── builtins/            # 内置工具
│   ├── subagents/               # Sub-Agent 系统
│   │   └── builtins/            # 内置 Sub-Agent
│   ├── sandbox/                 # 沙箱系统
│   │   └── local/               # 本地沙箱
│   ├── skills/                  # Skills 系统
│   ├── models/                  # 模型工厂
│   ├── mcp/                     # MCP 客户端
│   ├── config/                  # 配置系统
│   └── runtime/                 # 运行时
│       ├── store/               # 状态存储
│       ├── runs/                # 运行管理
│       └── stream_bridge/       # 流式桥接
└── tests/                       # 测试

3.3 Agent 架构

┌─────────────────────────────────────────────────────────────────────────┐ │ make_lead_agent(config) │ └────────────────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Middleware Chain │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ 1. ThreadDataMiddleware - 初始化 workspace/uploads/outputs │ │ │ │ 2. UploadsMiddleware - 处理上传文件 │ │ │ │ 3. SandboxMiddleware - 获取沙箱环境 │ │ │ │ 4. SummarizationMiddleware - 上下文压缩 (如启用) │ │ │ │ 5. TitleMiddleware - 自动生成标题 │ │ │ │ 6. TodoListMiddleware - 任务追踪 (plan_mode) │ │ │ │ 7. ViewImageMiddleware - 视觉模型支持 │ │ │ │ 8. ClarificationMiddleware - 澄清处理 │ │ │ └──────────────────────────────────────────────────────────────────┘ │ └────────────────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Agent Core │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ │ │ Model │ │ Tools │ │ System Prompt │ │ │ │ (from factory) │ │ (configured + │ │ (with skills) │ │ │ │ │ │ MCP + builtin) │ │ │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘

ThreadState 结构

class ThreadState(AgentState):
    messages: list[BaseMessage]      # 消息历史
    sandbox: dict                    # 沙箱环境信息
    artifacts: list[str]             # 生成的文件路径
    thread_data: dict                # {workspace, uploads, outputs}
    title: str | None                # 自动生成的标题
    todos: list[dict]                # 任务追踪 (plan mode)
    viewed_images: dict              # 视觉模型图像数据

3.4 Sandbox 系统

模式	实现	场景	隔离级别
Local	`LocalSandboxProvider`	开发环境	进程级
Docker	`AioSandboxProvider`	生产环境	容器级
Kubernetes	Provisioner	大规模部署	Pod 级

虚拟路径映射

虚拟路径	物理路径
`/mnt/user-data/workspace`	`backend/.deer-flow/threads/{thread_id}/user-data/workspace`
`/mnt/user-data/uploads`	`backend/.deer-flow/threads/{thread_id}/user-data/uploads`
`/mnt/user-data/outputs`	`backend/.deer-flow/threads/{thread_id}/user-data/outputs`
`/mnt/skills`	`deer-flow/skills/`

3.5 工具系统

工具来源

内置工具：packages/harness/deerflow/tools/builtins/
- task_tool.py - 任务管理
- invoke_acp_agent_tool.py - ACP Agent 调用
- present_file_tool.py - 文件展示
- view_image_tool.py - 图像查看
- tool_search.py - 工具搜索
配置工具：config.yaml 定义
MCP 工具：通过 MCP Server 动态获取

4. 前端架构详解

4.1 技术栈

TypeScript React 19 Next.js 16

核心依赖

Next.js 16: 应用框架
React 19: UI 库
Tailwind CSS 4: 样式系统
Radix UI: 无头组件库
CodeMirror 6: 代码编辑器
LangGraph SDK: Agent 通信

4.2 目录结构

frontend/
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── api/                  # API 路由
│   │   │   ├── auth/             # 认证
│   │   │   └── memory/           # 记忆 API
│   │   ├── workspace/            # 工作区页面
│   │   ├── layout.tsx            # 根布局
│   │   └── page.tsx              # 首页
│   ├── components/               # React 组件
│   │   ├── workspace/            # 工作区组件
│   │   │   ├── messages/         # 消息列表
│   │   │   ├── artifacts/        # 工件展示
│   │   │   ├── agents/           # Agent 卡片
│   │   │   └── settings/         # 设置页面
│   │   ├── ui/                   # 基础 UI 组件
│   │   └── ai-elements/          # AI 元素
│   ├── core/                     # 核心逻辑
│   │   ├── agents/               # Agent 状态
│   │   ├── threads/              # Thread 管理
│   │   ├── messages/             # 消息处理
│   │   ├── tools/                # 工具调用
│   │   ├── memory/               # 记忆管理
│   │   ├── skills/               # Skills 状态
│   │   ├── mcp/                  # MCP 状态
│   │   └── api/                  # API 客户端
│   ├── hooks/                    # 自定义 Hooks
│   ├── lib/                      # 工具库
│   ├── styles/                   # 全局样式
│   └── typings/                  # 类型定义
├── public/                       # 静态资源
└── package.json

4.3 核心模块

Threads 管理 (`frontend/src/core/threads/`)

hooks.ts - Thread 相关 Hooks
export.ts - Thread 导出功能
types.ts - 类型定义

消息系统 (`frontend/src/core/messages/`)

utils.ts - 消息处理工具
usage.ts - Token 使用统计

工作区组件 (`frontend/src/components/workspace/`)

input-box.tsx - 输入框 (33KB，核心交互)
message-list.tsx - 消息列表
code-editor.tsx - 代码编辑器
artifact-file-detail.tsx - 工件详情
command-palette.tsx - 命令面板

5. 核心模块分析

5.1 Sub-Agent 系统

目录结构

backend/packages/harness/deerflow/subagents/
├── executor.py          # Sub-Agent 执行器 (21KB)
├── registry.py          # Sub-Agent 注册表
├── config.py            # 配置
└── builtins/
    ├── general_purpose.py  # 通用 Sub-Agent
    └── bash_agent.py       # Bash 执行 Agent

执行流程

Lead Agent 分析任务，决定是否需要 Sub-Agent
创建 Sub-Agent 配置（独立上下文、工具、终止条件）
并行执行多个 Sub-Agent（条件允许时）
Sub-Agent 返回结构化结果
Lead Agent 汇总结果，生成最终输出

5.2 记忆系统

目录结构

backend/packages/harness/deerflow/agents/memory/
├── storage.py           # 记忆存储 (7KB)
├── updater.py           # 记忆更新器 (17KB)
├── queue.py             # 记忆队列 (7KB)
└── prompt.py            # 记忆提示词 (15KB)

记忆类型

短期记忆：Session 内的上下文管理
长期记忆：跨 Session 的持久化记忆
- 用户偏好
- 知识背景
- 工作习惯

记忆更新策略

Debouncing: 30 秒防抖，避免频繁更新
置信度阈值：0.7 以上才存储
最大事实数：100 条，超出时淘汰旧记忆

5.3 Skills 系统

目录结构

backend/packages/harness/deerflow/skills/
├── installer.py         # Skills 安装器 (6KB)
├── loader.py            # Skills 加载器 (4KB)
├── parser.py            # Skills 解析器 (2KB)
├── types.py             # 类型定义 (2KB)
└── validation.py        # 验证器 (3KB)

Skills 分类

类别	路径	示例
内置 Skills	`skills/public/`	deep-research, report-generation
自定义 Skills	`skills/custom/`	用户自定义工作流

内置 Skills 列表

bootstrap/ - 初始化引导
deep-research/ - 深度研究
report-generation/ - 报告生成
ppt-generation/ - PPT 生成
image-generation/ - 图像生成
video-generation/ - 视频生成
podcast-generation/ - 播客生成
skill-creator/ - Skill 创建
github-deep-research/ - GitHub 研究
claude-to-deerflow/ - Claude Code 集成

5.4 中间件系统

目录结构

backend/packages/harness/deerflow/agents/middlewares/
├── thread_data_middleware.py       # Thread 数据初始化
├── uploads_middleware.py           # 文件上传处理
├── sandbox_audit_middleware.py     # 沙箱审计
├── summarization_middleware.py     # 上下文摘要
├── title_middleware.py             # 标题生成
├── todo_middleware.py              # 任务追踪
├── view_image_middleware.py        # 图像查看
├── clarification_middleware.py     # 澄清处理
├── memory_middleware.py            # 记忆注入
├── tool_error_handling_middleware.py # 工具错误处理
└── ...

中间件执行顺序

ThreadDataMiddleware - 初始化工作目录
UploadsMiddleware - 处理上传文件
SandboxMiddleware - 获取沙箱环境
SummarizationMiddleware - 上下文压缩
TitleMiddleware - 生成标题
TodoListMiddleware - 任务追踪
ViewImageMiddleware - 视觉支持
ClarificationMiddleware - 澄清处理

5.5 配置系统

目录结构

backend/packages/harness/deerflow/config/
├── app_config.py          # 应用配置 (14KB)
├── agents_config.py       # Agent 配置
├── model_config.py        # 模型配置
├── sandbox_config.py      # 沙箱配置
├── skills_config.py       # Skills 配置
├── memory_config.py       # 记忆配置
├── subagents_config.py    # Sub-Agent 配置
├── extensions_config.py   # 扩展配置 (11KB)
└── paths.py               # 路径管理 (12KB)

配置文件

config.yaml - 主配置文件
- Models 定义
- Tools 配置
- Sandbox 模式
- Skills 设置
- 记忆配置
extensions_config.json - 扩展配置
- MCP Servers
- Skills 状态
.env - 环境变量
- API Keys
- 数据库连接

6. 扩展系统

6.1 MCP (Model Context Protocol)

目录结构

backend/packages/harness/deerflow/mcp/
├── client.py            # MCP 客户端
├── cache.py             # MCP 缓存
├── oauth.py             # OAuth 认证
└── tools.py             # MCP 工具

支持的认证方式

client_credentials - 客户端凭证
refresh_token - 刷新令牌

6.2 IM 渠道集成

目录结构

backend/app/channels/
├── manager.py           # 渠道管理器 (31KB)
├── base.py              # 基础类
├── service.py           # 渠道服务
├── telegram.py          # Telegram (13KB)
├── slack.py             # Slack (9KB)
├── feishu.py            # 飞书 (25KB)
└── message_bus.py       # 消息总线

支持渠道

渠道	传输方式	难度
Telegram	Bot API (long-polling)	简单
Slack	Socket Mode	中等
飞书/Lark	WebSocket	中等

渠道命令

/new - 开启新对话
/status - 查看 thread 信息
/models - 列出可用模型
/memory - 查看记忆
/help - 查看帮助

6.3 Community 贡献

目录结构

backend/packages/harness/deerflow/community/
├── aio_sandbox/         # 异步沙箱
├── ddg_search/          # DuckDuckGo 搜索
├── tavily/              # Tavily 搜索
├── jina_ai/             # Jina AI 工具
├── firecrawl/           # Firecrawl 爬取
├── image_search/        # 图像搜索
└── infoquest/           # InfoQuest 搜索

7. 部署架构

7.1 Docker 部署

目录结构

docker/
├── docker-compose.yaml        # 生产环境编排
├── docker-compose-dev.yaml    # 开发环境编排
├── nginx/
│   └── nginx.local.conf       # Nginx 配置
└── provisioner/               # Kubernetes Provisioner

开发模式启动

# 初始化沙箱镜像
make docker-init

# 启动服务
make docker-start

生产模式启动

# 构建并启动
make up

# 停止服务
make down

7.2 本地开发

# 检查依赖
make check

# 安装依赖
make install

# 启动服务
make dev

7.3 脚本工具

scripts/
├── serve.sh                    # 启动服务脚本
├── config-upgrade.sh           # 配置升级
├── cleanup-containers.sh       # 容器清理
├── docker.sh                   # Docker 工具
├── deploy.sh                   # 部署脚本
├── start-daemon.sh             # 守护进程启动
└── wait-for-port.sh            # 端口等待

8. 安全机制

8.1 Sandbox 隔离

容器隔离：每个任务运行在独立 Docker 容器
文件系统隔离：虚拟路径映射，防止跨 Session 污染
审计日志：SandboxMiddleware 记录所有操作

8.2 访问控制

本地绑定：默认仅监听 127.0.0.1
渠道白名单：Telegram/Slack 支持用户白名单
API 鉴权：Better Auth 集成

8.3 数据安全

敏感数据保护：API Keys 通过环境变量管理
记忆加密：本地存储，用户控制
会话隔离：Thread 级数据隔离

⚠️ 安全警告： DeerFlow 具备系统指令执行、资源操作等高权限能力，默认设计为部署在本地可信环境（仅本机 127.0.0.1 回环访问）。部署到公网必须采取严格安全措施（IP 白名单、前置认证、网络隔离）。

9. 总结与建议

9.1 架构优势

模块化设计：清晰的职责分离，易于扩展和维护
灵活部署：支持本地、Docker、Kubernetes 多种部署方式
强大扩展性：Skills、MCP、Sub-Agents 提供无限扩展可能
生产就绪：完善的中间件、错误处理、日志追踪
生态集成：支持主流 IM 渠道和 MCP 协议

9.2 技术亮点

Context Engineering：智能上下文管理，适合长链路任务
Sub-Agent 并行：复杂任务拆解和并行执行
长期记忆：跨 Session 学习和个性化
Sandbox 执行：真正具备执行能力的 Agent，不是"聊天机器人"

9.3 适用场景

✅ 深度研究和报告生成
✅ 数据流水线和自动化
✅ 内容生成（文档、PPT、图像、视频）
✅ 复杂多步骤任务编排
✅ 需要文件操作和代码执行的场景
❌ 简单问答（杀鸡用牛刀）
❌ 实时性要求极高的场景

9.4 改进建议

文档完善：部分模块缺少详细文档
测试覆盖：核心模块测试覆盖率可提升
监控告警：生产环境监控体系待完善
性能优化：大规模并发下的性能测试

总体评价： DeerFlow 2.0 是一个设计精良、功能强大的 Super Agent Harness 框架。从 Deep Research 工具成功转型为通用 Agent 运行时，展现了优秀的架构演进能力。适合需要构建复杂 Agent 工作流的团队使用。

报告生成时间：2026-04-02 | DeerFlow 2.0 架构分析 | 基于 GitHub 最新版本

🦌 DeerFlow 2.0 架构分析报告

📑 目录

1. 执行摘要

关键特性

2. 系统架构概览

端口规划

3. 后端架构详解

3.1 技术栈

核心依赖

3.2 目录结构

3.3 Agent 架构

ThreadState 结构

3.4 Sandbox 系统

虚拟路径映射

3.5 工具系统

工具来源

4. 前端架构详解

4.1 技术栈

核心依赖

4.2 目录结构

4.3 核心模块

Threads 管理 (frontend/src/core/threads/)

消息系统 (frontend/src/core/messages/)

工作区组件 (frontend/src/components/workspace/)

5. 核心模块分析

5.1 Sub-Agent 系统

目录结构

执行流程

5.2 记忆系统

目录结构

记忆类型

记忆更新策略

5.3 Skills 系统

目录结构

Skills 分类

内置 Skills 列表

5.4 中间件系统

目录结构

中间件执行顺序

5.5 配置系统

目录结构

配置文件

6. 扩展系统

6.1 MCP (Model Context Protocol)

目录结构

支持的认证方式

6.2 IM 渠道集成

目录结构

支持渠道

渠道命令

6.3 Community 贡献

目录结构

7. 部署架构

7.1 Docker 部署

目录结构

开发模式启动

生产模式启动

7.2 本地开发

7.3 脚本工具

8. 安全机制

8.1 Sandbox 隔离

8.2 访问控制

8.3 数据安全

9. 总结与建议

9.1 架构优势

9.2 技术亮点

9.3 适用场景

9.4 改进建议

Threads 管理 (`frontend/src/core/threads/`)

消息系统 (`frontend/src/core/messages/`)

工作区组件 (`frontend/src/components/workspace/`)