DeerFlow 2.0 深度调研报告

**Harness（运行时）而非 Framework（框架）**

DeerFlow 2.0 深度调研报告

一、项目概述

1.1 基本信息

属性	内容
项目名称	DeerFlow
全称	Deep Exploration and Efficient Research Flow
维护者	ByteDance（字节跳动）
GitHub	https://github.com/bytedance/deer-flow
官网	https://deerflow.tech
License	MIT
主要语言	Python + TypeScript
Stars	33,679+
创建时间	2025年5月7日
当前版本	DeerFlow 2.0

1.2 项目定位

DeerFlow 是字节跳动开源的 SuperAgent Harness（超级智能体运行时），核心理念是：

Harness（运行时）而非 Framework（框架）

关键区别：

维度	Framework（框架）	Harness（运行时）
设计理念	提供构建块，自行组装	开箱即用，电池内置
执行环境	开发者自行处理	内置沙箱、文件系统、进程隔离
决策权	开发者定义工作流	Agent 自主规划、分解、执行
扩展方式	插件/中间件	Skills + MCP Server + Sub-agents
开发成本	高（需要大量胶水代码）	低（约定优于配置）

1.3 核心特性

特性	说明
🤖 Sub-Agent 编排	Lead Agent + Sub-Agent 架构，自主任务分解
🧠 长期记忆	三层记忆结构，跨会话持久化
📦 内置沙箱	Local / Docker / K8s 三种执行环境
🔧 Skills 系统	Markdown 定义，渐进式加载
🔌 MCP 支持	原生支持 MCP Server，OAuth 认证
📱 IM 集成	Telegram / Slack / 飞书多渠道
🔍 Deep Research	系统化多角度网络研究能力

二、核心架构

2.1 系统架构图

┌─────────────────────────────────────────────────────────────────┐
│                    DeerFlow 2.0 架构                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    User Interface                        │  │
│   │   Web UI (Next.js)  │  Telegram  │  Slack  │  Feishu   │  │
│   └─────────────────────────┬───────────────────────────────┘  │
│                             │                                   │
│                             ▼                                   │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    nginx (Port 2026)                     │  │
│   │          反向代理 + 负载均衡                              │  │
│   └──────────┬────────────────────────┬──────────────────────┘  │
│              │                        │                          │
│              ▼                        ▼                          │
│   ┌──────────────────┐    ┌──────────────────┐                 │
│   │   Gateway API    │    │  LangGraph Server │                 │
│   │   (Port 8001)    │    │   (Port 2024)     │                 │
│   │   FastAPI 管理    │    │   Agent 运行时    │                 │
│   └────────┬─────────┘    └────────┬─────────┘                 │
│            │                       │                            │
│            └───────────┬───────────┘                            │
│                        │                                        │
│                        ▼                                        │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    Lead Agent                            │  │
│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │  │
│   │  │   Memory    │  │   Skills    │  │   Tools     │     │  │
│   │  │   System    │  │   Loader    │  │   Manager   │     │  │
│   │  └─────────────┘  └─────────────┘  └─────────────┘     │  │
│   └─────────────────────────┬───────────────────────────────┘  │
│                             │                                   │
│              ┌──────────────┼──────────────┐                   │
│              ▼              ▼              ▼                   │
│   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐          │
│   │ Sub-Agent 1  │ │ Sub-Agent 2  │ │ Sub-Agent 3  │          │
│   │ (隔离上下文)  │ │ (隔离上下文)  │ │ (隔离上下文)  │          │
│   └──────┬───────┘ └──────┬───────┘ └──────┬───────┘          │
│          │                │                │                   │
│          └────────────────┼────────────────┘                   │
│                           │                                    │
│                           ▼                                    │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    Sandbox Layer                         │  │
│   │   ┌─────────┐   ┌─────────┐   ┌─────────┐              │  │
│   │   │  Local  │   │ Docker  │   │   K8s   │              │  │
│   │   └─────────┘   └─────────┘   └─────────┘              │  │
│   └─────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

2.2 目录结构

deer-flow/
├── backend/                  # Python 后端核心
│   ├── src/
│   │   ├── agents/           # Lead Agent、Middlewares
│   │   ├── channels/         # IM 集成（Telegram, Slack, 飞书）
│   │   ├── community/        # 社区工具和沙箱实现
│   │   ├── config/           # 配置加载
│   │   ├── gateway/          # FastAPI 网关
│   │   ├── mcp/              # MCP Server 集成
│   │   ├── models/           # 模型适配器
│   │   ├── sandbox/          # 沙箱执行引擎
│   │   ├── skills/           # Skills 加载器
│   │   ├── subagents/        # Sub-agent 管理
│   │   └── tools/            # 内置工具
│   └── docs/
│       ├── ARCHITECTURE.md   # 架构文档
│       ├── CONFIGURATION.md  # 配置指南
│       └── API.md            # API 文档
├── frontend/                 # Next.js + React 前端
├── skills/                   # Markdown Skill 定义
│   └── public/               # 内置 Skills
└── docker/                   # Docker 配置

2.3 技术栈

层级	技术
前端	Next.js 15, React 19, TypeScript
后端	Python 3.12+, FastAPI
Agent 运行时	LangGraph, LangChain
沙箱	Docker, Kubernetes
数据库	SQLite / PostgreSQL
反向代理	nginx

三、核心组件详解

3.1 Lead Agent + Sub-Agent 架构

DeerFlow 采用 Lead Agent（主智能体） + Sub-Agent（子智能体） 的编排架构：

┌─────────────────────────────────────────────────────────────────┐
│                    Agent 编排模式                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   用户任务: "帮我研究 AI Agent 框架并写一份报告"                  │
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    Lead Agent                            │  │
│   │  1. 理解任务                                              │  │
│   │  2. 分解为子任务                                          │  │
│   │  3. 分配给 Sub-Agents                                     │  │
│   │  4. 综合结果                                              │  │
│   └─────────────────────────┬───────────────────────────────┘  │
│                             │                                   │
│           ┌─────────────────┼─────────────────┐                │
│           ▼                 ▼                 ▼                │
│   ┌───────────────┐ ┌───────────────┐ ┌───────────────┐       │
│   │ Sub-Agent 1   │ │ Sub-Agent 2   │ │ Sub-Agent 3   │       │
│   │ 研究 CrewAI   │ │ 研究 AutoGen  │ │ 研究 MetaGPT  │       │
│   │ (隔离上下文)   │ │ (隔离上下文)   │ │ (隔离上下文)   │       │
│   └───────┬───────┘ └───────┬───────┘ └───────┬───────┘       │
│           │                 │                 │                │
│           └─────────────────┼─────────────────┘                │
│                             │                                   │
│                             ▼                                   │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    结果综合                              │  │
│   │  合并三个 Sub-Agent 的研究结果                           │  │
│   │  生成完整的对比报告                                      │  │
│   └─────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Sub-Agent 状态机：

PENDING ──> RUNNING ──> COMPLETED
                  │
                  ├──> FAILED
                  │
                  └──> TIMED_OUT

并发控制：

MIN_SUBAGENT_LIMIT = 2
MAX_SUBAGENT_LIMIT = 4

3.2 三层记忆系统

DeerFlow 的记忆系统采用三层结构：

{
    "version": "1.0",

    # 第一层：用户画像
    "user": {
        "workContext": {...},       # 角色、公司、技术栈
        "personalContext": {...},   # 语言、偏好、兴趣
        "topOfMind": {...}          # 当前关注点（最频繁更新）
    },

    # 第二层：时间线
    "history": {
        "recentMonths": {...},      # 1-3 月详细活动
        "earlierContext": {...},    # 3-12 月模式
        "longTermBackground": {...} # 长期背景
    },

    # 第三层：结构化事实
    "facts": [...]
}

Facts 分类：

类别	含义	示例
`preference`	用户偏好	"偏好 Vim 胜过 VS Code"
`knowledge`	专业知识	"精通 Rust 和 WebAssembly"
`context`	背景事实	"字节跳动高级工程师"
`behavior`	行为模式	"测试先行开发"
`goal`	目标意图	"计划 Q2 发布 v2.0"

记忆更新流程：

对话完成 → MemoryMiddleware.after_agent → MemoryUpdateQueue
    → 防抖 (30秒) → 去重 → LLM 提取 → 原子写入

3.3 沙箱执行系统

DeerFlow 内置三种沙箱实现：

实现	类名	使用场景
Local	`LocalSandbox`	开发/调试，直接在主机执行
Docker	`AioSandbox`	容器隔离，通过 HTTP API
K8s	`RemoteSandboxBackend`	生产环境，Kubernetes Pods

虚拟文件系统：

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

/mnt/skills/          # Skills 目录

沙箱抽象接口：

class Sandbox(ABC):
    @abstractmethod
    def execute_command(self, command: str) -> str: ...

    @abstractmethod
    def read_file(self, path: str) -> str: ...

    @abstractmethod
    def write_file(self, path: str, content: str) -> None: ...

    @abstractmethod
    def list_dir(self, path: str, max_depth=2) -> list[str]: ...

3.4 Skills 系统

Skill 定义：一个目录 + 一个 SKILL.md 文件

---
name: deep-research
description: 用于需要网络研究的问题，比 WebSearch 更系统化...
---

# Deep Research Skill

## 概述
...

## 研究方法论

### 阶段 1: 广泛探索
...

渐进式加载（三层）：

层级	内容	加载时机	大小限制
1	name + description	始终加载	~100 词
2	SKILL.md 正文	任务匹配时	推荐 <500 行
3	脚本、引用、模板	执行时	无限制

内置 Skills：

Skill	用途
`deep-research`	系统化多角度网络研究
`data-analysis`	DuckDB 分析 Excel/CSV
`chart-visualization`	智能图表类型选择
`frontend-design`	高质量前端代码生成
`image-generation`	结构化提示词图像生成
`video-generation`	视频生成
`ppt-generation`	带图像的 PPT 生成
`github-deep-research`	GitHub 仓库分析

四、MCP Server 集成

4.1 三种传输模式

传输方式	机制	使用场景
stdio	子进程 stdin/stdout	本地工具（文件系统、DB CLI）
sse	HTTP Server-Sent Events	有服务端推送的远程服务
http	HTTP 请求/响应	无状态远程 API

4.2 配置格式

{
  "mcpServers": {
    "filesystem": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
    },
    "remote-api": {
      "enabled": true,
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "type": "refresh_token",
        "client_id": "...",
        "refresh_token": "..."
      }
    }
  }
}

4.3 OAuth 支持

client_credentials: 服务间调用
refresh_token: 用户委托操作
自动 Token 刷新（默认 60 秒提前刷新）

五、IM 渠道集成

5.1 支持的渠道

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

5.2 配置示例

channels:
  langgraph_url: http://localhost:2024
  gateway_url: http://localhost:8001

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN

  slack:
    enabled: true
    bot_token: $SLACK_BOT_TOKEN
    app_token: $SLACK_APP_TOKEN

  feishu:
    enabled: true
    app_id: $FEISHU_APP_ID
    app_secret: $FEISHU_APP_SECRET

5.3 命令列表

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

六、内置工具

6.1 核心工具

工具	用途	超时
`bash`	命令执行	600s
`ls`	目录列表（最大 2 层）	-
`read_file`	文件读取（支持行范围）	-
`write_file`	文件写入/追加	-
`str_replace`	精确字符串替换	-
`task`	Sub-Agent 委托	-
`ask_clarification`	用户交互	-
`present_files`	文件展示	-
`view_image`	图像查看（多模态）	-

6.2 社区工具

工具	来源	用途
`web_search`	Tavily	网络搜索
`web_fetch`	Tavily/Jina	网页抓取
`image_search`	DuckDuckGo	图像搜索

七、与其他框架对比

7.1 vs AutoGen

维度	DeerFlow	AutoGen
架构定位	Harness（运行时）	Framework（框架）
执行环境	内置沙箱	开发者自行处理
记忆系统	跨会话持久化	会话级别
扩展方式	Skills (Markdown) + MCP	代码定义 Agent
状态管理	LangGraph Checkpointer	开发者选择

7.2 vs CrewAI

维度	DeerFlow	CrewAI
任务编排	动态 LLM 驱动	预定义任务/角色
沙箱	内置（3 种模式）	外部
记忆	长期 + Facts	短期
协议支持	MCP 原生	自定义工具

7.3 vs MetaGPT

维度	DeerFlow	MetaGPT
专注领域	通用 Agent 运行时	软件开发
角色定义	动态 Sub-Agents	预定义（PM、架构师等）
输出	文件、报告、网站	代码、文档
记忆	跨会话持久化	任务级别

7.4 vs LangGraph（独立使用）

维度	DeerFlow	LangGraph
抽象层级	完整平台	图编排库
工具	预构建 + MCP	开发者提供
沙箱	集成	外部
记忆	内置系统	仅 Checkpointer
Skills	Markdown 定义	代码定义

八、适用场景

8.1 最佳场景

深度研究任务：需要系统化网络调研
长期运行任务：分钟到小时级别的复杂任务
多步骤工作流：需要自主规划和分解
需要隔离执行：代码执行、文件操作
多渠道部署：Web、Telegram、Slack、飞书

8.2 长时程 Agent 特征

长运行时间：分钟到小时（非简单 Q&A）
自主决策：动态任务分解
可交付输出："初稿"质量的产物

8.3 推荐模型

Doubao-Seed-2.0-Code（字节/火山引擎）
DeepSeek v3.2
Kimi 2.5

模型要求： - 长上下文窗口（100k+ tokens） - 推理能力 - 多模态输入 - 可靠的工具调用

九、安装与部署

9.1 快速开始

# 克隆仓库
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 生成配置
make config

# Docker 开发模式（推荐）
make docker-init
make docker-start

# 或本地开发
make check
make install
make dev

# 访问: http://localhost:2026

9.2 部署模式

模式	命令	说明
Docker 开发	`make docker-start`	推荐，快速启动
本地开发	`make dev`	需要本地环境
生产部署	K8s	Kubernetes 部署

十、总结

10.1 优势

开箱即用：Harness 设计，电池内置
生产就绪：内置沙箱、记忆、Skills
灵活扩展：MCP 协议、Markdown Skills
多渠道支持：Web、Telegram、Slack、飞书
企业级：字节跳动出品，MIT 开源
长时程优化：专为长时间任务设计

10.2 局限

学习曲线：概念较多，需要时间理解
资源需求：Docker/K8s 部署需要资源
模型依赖：需要支持长上下文的模型
中文文档：主要文档为英文

10.3 适用人群

需要 AI Agent 平台的团队
研究和分析型任务开发者
企业级 Agent 应用构建者
对 Agent 编排有深入需求的开发者

参考资源

GitHub 仓库：https://github.com/bytedance/deer-flow
官方网站：https://deerflow.tech
架构文档：backend/docs/ARCHITECTURE.md
配置指南：backend/docs/CONFIGURATION.md
API 文档：backend/docs/API.md

报告生成时间：2026-03-22