DeerFlow 2.0 学习教程

一、快速开始

1.1 什么是 DeerFlow？

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

传统框架 (Framework)
├── 提供构建块
├── 你自己组装
└── 需要大量胶水代码

DeerFlow (Harness)
├── 开箱即用
├── 电池内置
└── 约定优于配置

1.2 核心能力

能力	说明
自主规划	Agent 自动分解任务、规划执行
沙箱执行	安全隔离的代码执行环境
长期记忆	跨会话的持久化记忆
Sub-Agent	并行子智能体协作
Skills	Markdown 定义的能力扩展
MCP 支持	原生支持 MCP 协议

1.3 5 分钟上手

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

# 2. 生成配置
make config

# 3. Docker 启动（推荐）
make docker-init
make docker-start

# 4. 访问 Web UI
open http://localhost:2026

# 5. 开始对话
# 输入: "帮我研究一下 LangGraph 框架的架构和特点"

二、安装配置

2.1 系统要求

要求	说明
Docker	20.10+（推荐）
Python	3.12+（本地开发）
Node.js	22+（前端开发）
内存	建议 8GB+
磁盘	10GB+

2.2 Docker 安装（推荐）

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

# 生成配置文件
make config

# 初始化 Docker 环境
make docker-init

# 启动服务
make docker-start

# 查看日志
make docker-logs

# 停止服务
make docker-stop

2.3 本地开发安装

# 检查依赖
make check

# 安装依赖
make install

# 启动开发服务器
make dev

# 或分别启动前后端
make backend-dev  # 后端 :8001
make frontend-dev # 前端 :3000

2.4 配置文件

.env 配置：

# LLM 配置
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4

# 或使用 DeepSeek
DEEPSEEK_API_KEY=your-deepseek-key
DEEPSEEK_MODEL=deepseek-chat

# 或使用火山引擎
VOLCENGINE_API_KEY=your-volcengine-key
VOLCENGINE_MODEL=Doubao-Seed-2.0-Code

# 沙箱配置
SANDBOX_TYPE=docker  # local | docker | k8s

# 记忆配置
MEMORY_ENABLED=true
MEMORY_MAX_TOKENS=2000

# MCP 配置
MCP_CONFIG_PATH=./mcp_config.json

mcp_config.json 示例：

{
  "mcpServers": {
    "filesystem": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
    },
    "web-search": {
      "enabled": true,
      "type": "http",
      "url": "https://api.tavily.com/mcp"
    }
  }
}

2.5 推荐模型配置

# config/models.yaml

# 推荐模型
models:
  - name: doubao-seed
    provider: volcengine
    model: Doubao-Seed-2.0-Code
    api_key: ${VOLCENGINE_API_KEY}

  - name: deepseek
    provider: deepseek
    model: deepseek-chat
    api_key: ${DEEPSEEK_API_KEY}

  - name: kimi
    provider: moonshot
    model: moonshot-v1-128k
    api_key: ${MOONSHOT_API_KEY}

三、核心概念

3.1 Lead Agent

Lead Agent 是 DeerFlow 的核心，负责：

┌─────────────────────────────────────────────────────────────────┐
│                    Lead Agent 职责                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. 理解用户意图                                                 │
│     └── 解析用户请求，理解任务目标                               │
│                                                                 │
│  2. 任务分解                                                     │
│     └── 将复杂任务分解为可执行的子任务                           │
│                                                                 │
│  3. Sub-Agent 编排                                               │
│     └── 创建和管理 Sub-Agents                                    │
│     └── 分配任务，控制并发                                       │
│                                                                 │
│  4. 结果综合                                                     │
│     └── 收集 Sub-Agents 结果                                     │
│     └── 整合生成最终答案                                         │
│                                                                 │
│  5. 记忆管理                                                     │
│     └── 更新用户记忆                                             │
│     └── 注入相关上下文                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

3.2 Sub-Agent

Sub-Agent 是隔离的执行单元：

# Sub-Agent 特点
├── 隔离上下文（看不到其他 Agent）
├── 独立的工具集
├── 独立的状态
├── 明确的终止条件
└── 超时控制

# 状态流转
PENDING -> RUNNING -> COMPLETED
                   -> FAILED
                   -> TIMED_OUT

并发控制：

# Sub-Agent 并发限制
MIN_SUBAGENT_LIMIT = 2
MAX_SUBAGENT_LIMIT = 4

# 超出限制时的多批次执行
Turn 1: 启动 Sub-Agent 1-3 -> 等待结果
Turn 2: 启动下一批 -> 等待结果
...
最终: 综合所有结果

3.3 沙箱 (Sandbox)

三种沙箱实现：

┌─────────────────────────────────────────────────────────────────┐
│                    沙箱实现对比                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Local Sandbox                                                  │
│  ├── 直接在主机执行                                              │
│  ├── 适合: 开发调试                                              │
│  └── 风险: 无隔离                                               │
│                                                                 │
│  Docker Sandbox (推荐)                                          │
│  ├── 容器隔离                                                    │
│  ├── HTTP API 调用                                              │
│  ├── 暖池设计 (LRU 淘汰)                                        │
│  └── 适合: 生产环境                                              │
│                                                                 │
│  K8s Sandbox                                                    │
│  ├── Kubernetes Pods                                            │
│  ├── PersistentVolume 挂载                                      │
│  ├── 通过 Provisioner 管理                                       │
│  └── 适合: 大规模生产                                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

3.4 Skills

Skill = 目录 + SKILL.md

skills/
└── my-skill/
    ├── SKILL.md          # Skill 定义
    ├── templates/        # 模板文件
    └── scripts/          # 脚本

SKILL.md 格式：

---
name: my-skill
description: 简短描述（用于匹配）...
---

# My Skill

## 概述
详细说明...

## 使用方法
...

## 示例
...

四、Skills 开发

4.1 创建自定义 Skill

# 创建 Skill 目录
mkdir -p skills/my-skill

# 创建 SKILL.md
cat > skills/my-skill/SKILL.md << 'EOF'
---
name: code-review
description: 用于代码审查任务，自动检测代码问题和改进建议...
---

# Code Review Skill

## 概述
这是一个专业的代码审查技能，能够：

1. 检测代码质量问题
2. 发现潜在 Bug
3. 提供改进建议

## 审查流程

### 步骤 1: 静态分析
- 检查代码风格
- 检测重复代码
- 分析复杂度

### 步骤 2: 安全检查
- SQL 注入风险
- XSS 漏洞
- 敏感信息泄露

### 步骤 3: 改进建议
- 性能优化
- 可读性改进
- 最佳实践

## 输出格式
- 问题列表
- 严重程度
- 修复建议
EOF

4.2 Skill 模板

# SKILL.md 模板

---
name: skill-name
description: 简短描述，用于任务匹配（约 100 词）
---

# Skill Name

## 概述
详细描述这个 Skill 的用途和能力。

## 前置条件
- 需要什么环境
- 需要什么配置

## 执行步骤

### 阶段 1: 准备
...

### 阶段 2: 执行
...

### 阶段 3: 输出
...

## 示例

输入:

示例输入


输出:

示例输出


## 注意事项
- 注意点 1
- 注意点 2

4.3 内置 Skills 使用

Deep Research Skill：

用户: 帮我研究一下多智能体框架的对比

# DeerFlow 自动调用 deep-research skill
# 系统化地研究多个角度
# 生成结构化报告

Data Analysis Skill：

用户: 分析这个 sales.csv 文件，告诉我销售趋势

# 自动使用 DuckDB 分析
# 生成统计结果和图表

Frontend Design Skill：

用户: 帮我创建一个现代化的登录页面

# 生成高质量前端代码
# 包含响应式设计

五、MCP Server 集成

5.1 添加 MCP Server

stdio 模式（本地工具）：

{
  "mcpServers": {
    "filesystem": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/dir"
      ]
    },
    "sqlite": {
      "enabled": true,
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/db.sqlite"]
    }
  }
}

HTTP 模式（远程服务）：

{
  "mcpServers": {
    "tavily": {
      "enabled": true,
      "type": "http",
      "url": "https://api.tavily.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TAVILY_API_KEY}"
      }
    }
  }
}

5.2 OAuth 认证

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "type": "refresh_token",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "refresh_token": "your-refresh-token",
        "token_url": "https://github.com/login/oauth/access_token",
        "refresh_skew_seconds": 60
      }
    }
  }
}

5.3 常用 MCP Server

Server	功能	类型
`@modelcontextprotocol/server-filesystem`	文件系统访问	stdio
`@modelcontextprotocol/server-sqlite`	SQLite 数据库	stdio
`@modelcontextprotocol/server-github`	GitHub API	stdio
`mcp-server-brave-search`	Brave 搜索	stdio
Tavily MCP	网络搜索	http

六、Sub-Agent 编排

6.1 自动编排

DeerFlow 自动进行 Sub-Agent 编排：

用户任务: "研究 AI Agent 框架并写一份对比报告"

# DeerFlow 自动:
1. 分析任务，识别需要研究的框架
2. 创建多个 Sub-Agents
   - Sub-Agent 1: 研究 AutoGen
   - Sub-Agent 2: 研究 CrewAI
   - Sub-Agent 3: 研究 LangGraph
3. 并行执行（最多 4 个）
4. 综合结果，生成报告

6.2 手动控制

# 通过配置控制 Sub-Agent 行为
subagent_config = {
    "max_concurrent": 3,      # 最大并发数
    "timeout": 300,           # 超时时间（秒）
    "max_iterations": 10,     # 最大迭代次数
}

6.3 Sub-Agent 隔离

┌─────────────────────────────────────────────────────────────────┐
│                    Sub-Agent 上下文隔离                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Lead Agent                                                    │
│   ├── 可以看到所有 Sub-Agents 结果                              │
│   └── 可以访问全局记忆                                          │
│                                                                 │
│   Sub-Agent 1          Sub-Agent 2          Sub-Agent 3        │
│   ├── 独立上下文        ├── 独立上下文        ├── 独立上下文      │
│   ├── 看不到 Agent 2    ├── 看不到 Agent 1    ├── 看不到 Agent 1 │
│   └── 看不到 Agent 3    └── 看不到 Agent 3    └── 看不到 Agent 2 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

七、记忆系统

7.1 记忆结构

memory = {
    "version": "1.0",

    # 用户画像
    "user": {
        "workContext": {
            "role": "软件工程师",
            "company": "某科技公司",
            "techStack": ["Python", "Go", "Kubernetes"]
        },
        "personalContext": {
            "language": "中文",
            "preferences": ["简洁代码", "测试驱动开发"]
        },
        "topOfMind": {
            "currentProject": "重构支付系统",
            "deadline": "2026-04-01"
        }
    },

    # 时间线
    "history": {
        "recentMonths": [...],
        "earlierContext": [...],
        "longTermBackground": [...]
    },

    # 结构化事实
    "facts": [
        {"type": "preference", "content": "偏好微服务架构", "confidence": 0.9},
        {"type": "knowledge", "content": "精通分布式系统", "confidence": 0.85},
    ]
}

7.2 查看记忆

# 通过 IM 命令
/memory

# 或通过 API
curl http://localhost:8001/api/memory

7.3 记忆更新

记忆更新是自动的：

对话完成
    ↓
MemoryMiddleware.after_agent
    ↓
MemoryUpdateQueue（防抖 30s）
    ↓
去重
    ↓
LLM 提取 Facts
    ↓
原子写入文件

7.4 记忆配置

memory:
  enabled: true
  max_injection_tokens: 2000  # 注入到上下文的最大 Token
  max_facts: 100              # 最大 Facts 数量
  confidence_threshold: 0.7   # Facts 置信度阈值
  update_debounce: 30         # 更新防抖（秒）

八、IM 渠道集成

8.1 Telegram 集成

# config/channels.yaml
channels:
  telegram:
    enabled: true
    bot_token: ${TELEGRAM_BOT_TOKEN}

步骤：

通过 @BotFather 创建 Bot
获取 Bot Token
配置到 TELEGRAM_BOT_TOKEN
启动服务
向 Bot 发送消息

8.2 Slack 集成

channels:
  slack:
    enabled: true
    bot_token: ${SLACK_BOT_TOKEN}
    app_token: ${SLACK_APP_TOKEN}

步骤：

创建 Slack App
启用 Socket Mode
获取 Bot Token 和 App Token
配置 OAuth Scopes
安装到工作区

8.3 飞书集成

channels:
  feishu:
    enabled: true
    app_id: ${FEISHU_APP_ID}
    app_secret: ${FEISHU_APP_SECRET}

8.4 命令列表

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

九、进阶主题

9.1 自定义工具

# backend/src/tools/custom_tool.py

from langchain_core.tools import tool

@tool
def analyze_code(code: str) -> str:
    """分析代码质量，返回改进建议。

    Args:
        code: 要分析的代码字符串

    Returns:
        分析结果和建议
    """
    # 实现分析逻辑
    issues = []

    # 检查代码长度
    if len(code) > 500:
        issues.append("代码过长，建议拆分")

    # 检查命名
    # ...

    return "\n".join(issues) if issues else "代码质量良好"

9.2 自定义中间件

# backend/src/agents/middlewares/custom_middleware.py

from langchain.agents.middleware import AgentMiddleware

class LoggingMiddleware(AgentMiddleware):
    """日志记录中间件"""

    async def before_agent(self, state, config):
        # 执行前记录
        print(f"开始执行: {state.get('input', '')}")
        return state

    async def after_agent(self, state, config):
        # 执行后记录
        print(f"执行完成: {state.get('output', '')[:100]}...")
        return state

9.3 自定义沙箱

# backend/src/sandbox/custom_sandbox.py

from backend.src.sandbox.base import Sandbox

class CustomSandbox(Sandbox):
    """自定义沙箱实现"""

    def execute_command(self, command: str) -> str:
        # 实现命令执行
        pass

    def read_file(self, path: str) -> str:
        # 实现文件读取
        pass

    def write_file(self, path: str, content: str) -> None:
        # 实现文件写入
        pass

    def list_dir(self, path: str, max_depth: int = 2) -> list[str]:
        # 实现目录列表
        pass

9.4 K8s 部署

# k8s/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deerflow
spec:
  replicas: 3
  selector:
    matchLabels:
      app: deerflow
  template:
    metadata:
      labels:
        app: deerflow
    spec:
      containers:
      - name: deerflow
        image: deerflow:latest
        ports:
        - containerPort: 2026
        env:
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: deerflow-secrets
              key: openai-api-key

十、常见问题

Q1: Docker 启动失败？

# 检查 Docker 状态
docker info

# 查看日志
make docker-logs

# 重新初始化
make docker-stop
make docker-init
make docker-start

Q2: 模型调用失败？

# 检查 API Key
echo $OPENAI_API_KEY

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

# 检查配置
cat .env | grep API_KEY

Q3: Skill 没有被触发？

检查 Skill 描述是否匹配任务
确认 Skill 文件格式正确
查看 debug 日志

# 启用 debug 日志
LOG_LEVEL=debug make dev

Q4: Sub-Agent 超时？

# 增加超时时间
subagent:
  timeout: 600  # 10 分钟
  max_iterations: 20

Q5: 记忆没有更新？

检查记忆是否启用
确认置信度阈值
查看更新日志

# 查看记忆文件
cat ~/.deerflow/memory.json

十一、速查表

常用命令

命令	说明
`make config`	生成配置
`make docker-init`	初始化 Docker
`make docker-start`	启动服务
`make docker-stop`	停止服务
`make docker-logs`	查看日志
`make dev`	本地开发

IM 命令

命令	说明
`/new`	新对话
`/status`	线程状态
`/memory`	查看记忆
`/models`	可用模型

配置文件

文件	说明
`.env`	环境变量
`mcp_config.json`	MCP 配置
`config/models.yaml`	模型配置
`config/channels.yaml`	渠道配置

目录结构

目录	说明
`backend/`	Python 后端
`frontend/`	Next.js 前端
`skills/`	Skill 定义
`docker/`	Docker 配置

参考资源

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

教程生成时间：2026-03-22