深入理解 DeerFlow 2.0：字节跳动开源 SuperAgent 架构设计与实战

作者：wuyiyi日期：2026-03-23来源：GitHub Trending（37,297 stars）

前言

2026年2月28日，字节跳动开源的 DeerFlow 2.0 强势登陆 GitHub Trending 第一名。这款名为「DeerFlow」（Deep Exploration and Efficient Research Flow）的开源项目，在短短数月内就积累了超过 37,000+ stars，成为2026年最受关注的 AI Agent 框架之一。

DeerFlow 2.0 是一个彻底重写的版本，与 v1 没有任何共用代码。它不再只是一个「深度研究框架」，而是一个功能完备的 SuperAgent Harness——、开箱即用、高度可扩展的 AI Agent 运行时基础设施。

本文将深入剖析 DeerFlow 的核心架构设计，带你全面理解这个强大的开源 SuperAgent 框架。

---

一、DeerFlow 是什么？

DeerFlow 是字节跳动开源的 SuperAgent Harness，它将 sub-agents（子代理）、memory（记忆）和 sandbox（沙箱）组织在一起，配合可扩展的 Skills（技能），让 AI Agent 可以完成「几乎任何事情」。

1.1 核心定位

从 Deep Research 到 SuperAgent Harness，DeerFlow 经历了重大演变：

• v1 时代：专注于深度研究任务的框架
• v2.0 时代：开箱即用的 SuperAgent 运行时，可直接用于数据管道搭建、演示文稿生成、Dashboard 创建、内容工作流自动化等场景

1.2 技术栈基础

DeerFlow 2.0 基于以下核心技术构建：

技术栈	作用
LangGraph	多 Agent 编排与工作流管理
LangChain	LLM 交互与 Chains
Docker	隔离执行环境（Sandbox）
Python	后端核心语言
Node.js 22+	前端服务

---

二、核心架构设计

2.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                        DeerFlow 架构                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐   │
│  │   Frontend   │     │   Gateway    │     │  LangGraph   │   │
│  │   (Next.js)  │◄───►│   (FastAPI)  │◄───►│    Server    │   │
│  └──────────────┘     └──────────────┘     └──────────────┘   │
│                              │                    │              │
│                              ▼                    ▼              │
│                       ┌──────────────┐     ┌──────────────┐   │
│                       │  MCP Server  │     │   Sandbox    │   │
│                       │   & Skills   │     │ (Docker/K8s) │   │
│                       └──────────────┘     └──────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                      Sub-Agents                          │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │  │
│  │  │Research │  │ Report  │  │ Slide   │  │  Web    │    │  │
│  │  │ Agent   │  │ Agent   │  │ Agent   │  │ Agent   │    │  │
│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                    Long-Term Memory                      │  │
│  │         (用户画像 + 偏好 + 知识沉淀)                       │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

2.2 核心组件详解

2.2.1 Gateway（网关）

Gateway 是 DeerFlow 的统一入口，负责：

• 接收用户请求
• 管理会话和线程
• 路由到 LangGraph Server
• 处理认证和限流

核心配置示例：

# config.yaml
channels:
  langgraph_url: http://localhost:2024
  gateway_url: http://localhost:8001
  
  session:
    assistant_id: lead_agent
    config:
      recursion_limit: 100
      context:
        thinking_enabled: true
        is_plan_mode: false
        subagent_enabled: false

2.2.2 LangGraph Server

基于开源的 langgraph dev CLI 服务，提供：

• Agent 状态管理
• 节点执行控制
• 流式响应（SSE 协议）

2.2.3 Sandbox（沙箱执行环境）

DeerFlow 最核心的创新之一：每个任务都运行在隔离的容器中。

支持的 Sandbox 模式：

模式	说明
Local	直接在宿主机运行
Docker	在隔离的 Docker 容器中运行
K8s	通过 provisioner 在 Kubernetes Pod 中运行

Sandbox 容器内目录结构：

/mnt/user-data/
├── uploads/      # 用户上传的文件
├── workspace/    # Agent 工作目录
└── outputs/      # 最终交付物

/mnt/skills/public/
├── research/SKILL.md
├── report-generation/SKILL.md
├── slide-creation/SKILL.md
├── web-page/SKILL.md
└── image-generation/SKILL.md

/mnt/skills/custom/
└── your-custom-skill/SKILL.md  # 自定义技能

---

三、Skills 与 Tools 机制

3.1 Skills（技能）系统

Skills 是 DeerFlow 的灵魂所在。它们是结构化的能力模块，通过 Markdown 文件定义工作流、最佳实践和参考资源。

内置 Skills（开箱即用）：

• 📚 research - 深度研究
• 📝 report-generation - 报告生成
• 📊 slide-creation - 演示文稿制作
• 🌐 web-page - 网页生成
• 🖼️ image-generation - 图像/视频生成

Skill 文件结构示例（SKILL.md）：

---
name: custom-research
version: 1.0.0
author: developer
description: 自定义研究技能
---

# Custom Research Skill

## 目标
执行特定领域的深度研究

## 工作流
1. 收集基础信息
2. 分析竞品
3. 生成报告

## 最佳实践
- 使用多个数据源
- 交叉验证信息
- 保持客观中立

渐进式加载机制：

Skills 采用按需加载策略
        │
        ▼
┌───────────────────────┐
│  用户发起任务请求      │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│  分析任务所需 Skill   │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│  仅加载相关 Skill     │
│  （不一次性加载所有）  │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│  执行任务             │
└───────────────────────┘

3.2 Tools（工具）生态

DeerFlow 自带核心工具集，同时支持扩展：

内置工具	功能
🌐 web-search	网页搜索
📄 web-fetch	网页抓取
📁 file-operations	文件操作
💻 bash	命令执行
🖼️ image-viewer	图片查看

MCP Server 扩展：

# MCP Server 配置示例
mcp_servers:
  - name: filesystem
    type: http
    url: http://localhost:8080
    # 支持 OAuth token 流程
    oauth:
      client_credentials: true
      refresh_token: true

---

四、Sub-Agents（子代理）架构

4.1 动态任务分解

DeerFlow 的核心能力之一：复杂任务自动分解与 并行 执行。

┌─────────────────────────────────────────────────────────┐
│                    复杂任务处理流程                       │
└─────────────────────────────────────────────────────────┘
                              │
                              ▼
                  ┌───────────────────────┐
                  │   Lead Agent 接收任务  │
                  └───────────────────────┘
                              │
                              ▼
                  ┌───────────────────────┐
                  │     任务分析与拆解      │
                  └───────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌─────────┐    ┌─────────┐    ┌─────────┐
        │ Sub-    │    │ Sub-    │    │ Sub-    │
        │ Agent 1 │    │ Agent 2 │    │ Agent 3 │
        └─────────┘    └─────────┘    └─────────┘
           │               │               │
           ▼               ▼               ▼
        ┌─────────┐    ┌─────────┐    ┌─────────┐
        │ 结果 A  │    │ 结果 B  │    │ 结果 C  │
        └─────────┘    └─────────┘    └─────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
                  ┌───────────────────────┐
                  │  Lead Agent 汇总合成   │
                  └───────────────────────┘
                              │
                              ▼
                  ┌───────────────────────┐
                  │     最终输出           │
                  │  (报告/网站/幻灯片...) │
                  └───────────────────────┘

4.2 隔离的子代理上下文

关键设计：每个 Sub-Agent 运行在完全独立的上下文中

# 隔离上下文的核心逻辑
class SubAgentContext:
    def __init__(self, task_id: str):
        # 创建独立上下文
        self.context = {
            "task_id": task_id,
            "memory": {},  # 独立记忆
            "tools": self._get_isolated_tools(),  # 独立工具集
            "workspace": f"/tmp/{task_id}"  # 独立工作空间
        }
    
    def _get_isolated_tools(self):
        """子代理只能访问其任务所需的工具"""
        return self.task_tools
    
    # 子代理看不到主 Agent 的上下文
    # 子代理看不到其他子代理的上下文
    # 专注于当前任务，避免信息干扰

优势：

• 🎯 专注：子代理只聚焦当前任务
• 🔒 安全：隔离执行，防止数据泄露
• ⚡ 并行：可同时运行多个子代理
• 📊 可审计：每个子任务可追溯

---

五、Memory（记忆）系统

5.1 短期记忆（Session 内存）

在单个 Session 内，DeerFlow 采用摘要压缩策略管理上下文：

class ContextManager:
    def __init__(self, max_tokens: int = 100000):
        self.max_tokens = max_tokens
        self.current_tokens = 0
    
    def compress_context(self, messages: list) -> list:
        """压缩上下文，保留关键信息"""
        # 1. 总结已完成子任务
        completed_summary = self._summarize_completed_tasks()
        
        # 2. 将中间结果转存到文件系统
        self._offload_to_filesystem()
        
        # 3. 压缩不重要的历史消息
        compressed = self._compress_messages(messages)
        
        return compressed
    
    def _summarize_completed_tasks(self) -> str:
        """生成已完成任务摘要"""
        # 将长串的中间结果压缩为简短摘要
        return f"完成 {len(self.completed)} 个子任务，\
                关键发现：{self.key_findings}"

5.2 长期记忆（跨 Session）

class LongTermMemory:
    """持久化记忆系统"""
    
    def __init__(self, storage_path: str = "./memory"):
        self.storage_path = storage_path
        self.user_profile = {}      # 用户画像
        self.preferences = {}       # 偏好设置
        self.knowledge = {}         # 知识沉淀
    
    def update(self, user_id: str, interaction: dict):
        """更新用户记忆"""
        # 1. 提取关键信息
        facts = self._extract_facts(interaction)
        
        # 2. 去重（避免重复积累）
        if self._is_duplicate(facts):
            return  # 跳过重复
        
        # 3. 分类存储
        if facts["type"] == "preference":
            self.preferences[user_id].update(facts["data"])
        elif facts["type"] == "knowledge":
            self.knowledge[user_id].append(facts["data"])
        
        # 4. 持久化
        self._save()
    
    def get_context(self, user_id: str) -> dict:
        """获取增强上下文"""
        return {
            "profile": self.user_profile.get(user_id, {}),
            "preferences": self.preferences.get(user_id, {}),
            "knowledge": self.knowledge.get(user_id, [])
        }

记忆积累效果：

用户使用时间越长，DeerFlow 越了解：
  ├── 写作风格
  ├── 技术栈偏好
  ├── 常用工作流
  └── 特定领域知识

---

六、IM 渠道集成

DeerFlow 支持多种即时通讯渠道接入，不需要公网 IP：

渠道	传输方式	上手难度
📱 Telegram	Bot API (Long-polling)	⭐ 简单
💬 Slack	Socket Mode	⭐⭐ 中等
🏠 飞书/ Lark	WebSocket	⭐⭐ 中等

6.1 飞书配置示例

# config.yaml
channels:
  feishu:
    enabled: true
    app_id: $FEISHU_APP_ID
    app_secret: $FEISHU_APP_SECRET
  
  session:
    assistant_id: mobile_agent
    context:
      thinking_enabled: false
    users:
      "123456789":
        assistant_id: vip_agent
        config:
          recursion_limit: 150
          context:
            thinking_enabled: true
            subagent_enabled: true

飞书应用权限：

{
  "permissions": [
    "im:message",
    "im:message.p2p_msg:readonly", 
    "im:resource"
  ],
  "events": [
    "im.message.receive_v1"
  ]
}

6.2 命令系统

渠道连接后，支持以下命令：

命令	说明
/new	开启新对话
/status	查看当前线程信息
/models	列出可用模型
/memory	查看记忆
/help	查看帮助

---

七、实战：本地部署 DeerFlow

7.1 环境准备

# 1. 克隆项目
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 2. 生成本地配置
make config

# 3. 检查依赖
make check
# 输出示例：
# ✓ Node.js 22+ OK
# ✓ pnpm OK  
# ✓ uv OK
# ✓ nginx OK

7.2 模型配置

编辑 config.yaml，配置至少一个模型：

models:
  # OpenAI 模型
  - name: gpt-4
    display_name: GPT-4
    use: langchain_openai:ChatOpenAI
    model: gpt-4
    api_key: $OPENAI_API_KEY
    max_tokens: 4096
    temperature: 0.7
  
  # OpenRouter 模型
  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENAI_API_KEY
    base_url: https://openrouter.ai/api/v1
  
  # Claude Code (推荐)
  - name: claude-sonnet-4.6
    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-6
    max_tokens: 4096
    supports_thinking: true

7.3 环境变量

创建 .env 文件：

# 必需的环境变量
TAVILY_API_KEY=your-tavily-api-key
OPENAI_API_KEY=your-openai-api-key

# 可选
INFOQUEST_API_KEY=your-infoquest-api-key

# IM 渠道（如需要）
TELEGRAM_BOT_TOKEN=your-telegram-token
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
FEISHU_APP_ID=cli_xxxx
FEISHU_APP_SECRET=your_secret

7.4 启动服务

开发模式（推荐）：

make docker-init  # 首次拉取 sandbox 镜像
make docker-start # 启动服务
# 访问 http://localhost:2026

本地开发模式：

make install   # 安装依赖
make dev       # 启动本地服务
# 访问 http://localhost:2026

---

八、踩坑记录与解决方案

8.1 常见问题

❌ 问题1：Claude Code OAuth 认证失败

症状： macOS 上 Claude Code 无法自动认证

解决方案：

# 手动导出 OAuth Token
eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"

❌ 问题2：模型配置无效

症状： 启动后提示模型配置错误

排查步骤：

# 1. 检查 config.yaml 语法
cat config.yaml | python3 -m yaml

# 2. 验证 API Key
echo $OPENAI_API_KEY

# 3. 测试 API 连接
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

❌ 问题3：Sandbox 模式选择困惑

症状： 不确定该用哪种 Sandbox 模式

选择指南：

场景	推荐模式
本地快速测试	Local
生产环境单机器	Docker
企业级大规模部署	K8s

# config.yaml 配置示例
sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  # Docker 模式
  # provisioner: (留空)
  
  # K8s 模式
  # provisioner_url: http://k8s-provisioner:8080

❌ 问题4：Context Window 溢出

症状： 长任务执行到一半失败

解决方案：

# 1. 调整递归限制
session:
  config:
    recursion_limit: 150  # 默认 100

# 2. 启用思考模式（减少 token）
context:
  thinking_enabled: true

# 3. 任务拆分
# 将大任务拆分为多个小任务

8.2 性能优化技巧

# 1. 使用流式响应减少内存占用
async def stream_response(query: str):
    async for event in client.stream(query):
        if event.type == "messages-tuple":
            yield event.data["content"]

# 2. 合理设置 max_tokens
model_config = {
    "max_tokens": 4096,  # 不要设太大
    "temperature": 0.7
}

# 3. 使用轻量级模型处理简单任务
# 简单查询用 Gemini Flash，复杂分析用 GPT-4

---

九、代码示例：嵌入式使用

DeerFlow 也可以作为 Python 库 直接使用，无需启动 HTTP 服务：

from deerflow.client import DeerFlowClient

# 初始化客户端
client = DeerFlowClient()

# 1. 发送聊天消息
response = client.chat(
    "分析这篇论文的主要贡献",
    thread_id="research-001"
)
print(response)

# 2. 流式响应
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"], end="", flush=True)

# 3. 列出可用模型
models = client.list_models()
print(models["models"])

# 4. 列出可用技能
skills = client.list_skills()
print(skills["skills"])

# 5. 启用/禁用技能
client.update_skill("web-search", enabled=True)

# 6. 文件上传
result = client.upload_files(
    "thread-1", 
    ["./report.pdf", "./data.csv"]
)
print(result)  # {"success": True, "files": [...]}

---

十、与 Claude Code 集成

DeerFlow 提供了官方的 Claude Code Skill，让你在终端里直接使用 DeerFlow：

# 1. 安装 skill
npx skills add https://github.com/bytedance/deer-flow \
  --skill claude-to-deerflow

# 2. 在 Claude Code 中使用
/claude-to-deerflow

# 可用命令：
# - flash: 快速模式
# - standard: 标准模式  
# - pro: 规划模式
# - ultra: 子代理模式

环境变量 （可选）：

DEERFLOW_URL=http://localhost:2026
DEERFLOW_GATEWAY_URL=http://localhost:2026
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph

---

十一、推荐模型

DeerFlow 对模型没有强绑定，但以下模型表现最佳：

模型	推荐场景	优势
Doubao-Seed-2.0-Code	中文开发	字节官方优化
DeepSeek v3.2	推理任务	开源性价比高
Kimi 2.5	长上下文	中文理解强
Claude Sonnet 4.6	复杂分析	思考能力强
GPT-4	通用任务	稳定性好

---

十二、相关论文与参考资料

1. LangChain: Building applications with LLMs through composable components

   1. 论文地址：arxiv.org/abs/2402.05…

2. LangGraph: Multi-Agent Orchestration Framework

   1. 官网：langchain-ai.github.io/langgraph/

3. ReAct : Synergizing Reasoning and Acting in Language Models

   1. 论文地址：arxiv.org/abs/2210.03…

4. Toolformer: Language Models Can Teach Themselves to Use Tools

   1. 论文地址：arxiv.org/abs/2302.04…

5. DeepSeek-R1: Incentivizing Reasoning Capability in LLMs

   1. 论文地址：arxiv.org/abs/2501.12…

---

总结

DeerFlow 2.0 是字节跳动开源的一款功能完备的 SuperAgent 框架，它将 AI Agent 的能力推向了一个新的高度。

核心亮点：

特性	说明
🔥 37K+ Stars	GitHub Trending 第一
🏗️ 开箱即用	无需自行拼装框架
🛡️ 安全 沙箱	Docker/K8s 隔离执行
🧠 多Agent编排	复杂任务自动分解
💾 长期记忆	越用越懂你
🔌 多渠道接入	Telegram/Slack/飞书
🧩 可扩展	Skills + MCP

适用场景：

• 📚 深度研究与知识发现
• 📝 自动报告生成
• 📊 数据分析与可视化
• 🌐 网页与应用开发
• 🤖 自动化工作流

作为 2026 年最受关注的开源 AI Agent 项目之一，DeerFlow 展现了字节跳动在 AI 基础设施领域的深厚积累。无论你是 AI 开发者、研究人员还是企业用户，DeerFlow 都值得一试。

---

🚀 立即体验：github.com/bytedance/d… 官网：deerflow.tech