DeerFlow - 完整学习教程
DeerFlow - 完整学习教程
教程级别： 从零到一 预计学习时间： 4-6 小时 前置知识： Python 基础（理解虚拟环境、pip 安装）、Docker 基础（拉取镜像、运行容器）、命令行基本操作、了解 LLM API 的基本概念（API Key、模型选择）
环境搭建指南
系统要求
- 操作系统：Linux（推荐 Ubuntu 22.04+）/ macOS / Windows（WSL2 推荐）
- Python：3.12 及以上
- Node.js：22 及以上
- Docker：24.0 及以上（用于沙盒隔离模式）
- Git：2.30 及以上
- LLM API Key：至少一个 LLM 提供商的 API Key（推荐 DeepSeek 或 OpenAI）
安装步骤
第一步：安装前置依赖
# 检查 Python 版本（需要 3.12+）
python3 --version
# 如果未安装或版本过低
# macOS:
brew install python@3.12
# Ubuntu/Debian:
# sudo apt update && sudo apt install python3.12 python3.12-venv python3-pip
# 检查 Node.js 版本（需要 22+）
node --version
# 如果未安装或版本过低
# macOS:
brew install node@22
# Ubuntu/Debian:
# curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# sudo apt install nodejs
# 检查 Docker 版本
docker --version
第二步：克隆并安装 DeerFlow
# 基于 DeerFlow 2.0 官方 README（GitHub 仓库 bytedance/deer-flow）
# 克隆仓库
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
# 方式一：Docker 一键部署（推荐生产环境）
# 复制环境配置文件
cp .env.example .env
# 编辑 .env 文件，填入 API Key
# 必填项:
# LLM_API_KEY=your-api-key-here
# LLM_MODEL=deepseek/deepseek-v3.2
# LLM_BASE_URL=https://api.deepseek.com/v1
# 可选:
# SANDBOX_PROVIDER=aio # 使用 Docker 沙盒
# 使用 Docker Compose 启动
docker compose up -d
# 方式二：本地开发模式
# 后端
cd backend
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
pip install -r requirements.txt
# 前端
cd ../frontend
npm install
# 启动后端（在 backend/ 目录）
python -m deerflow.server
# 启动前端（在 frontend/ 目录，新终端）
npm run dev
第三步：配置 LLM API
# 编辑 .env 文件或 backend/config.yaml
# 基于 DeerFlow 2.0 官方 README
# 方式一：使用 DeepSeek（推荐，性价比高）
LLM_API_KEY=sk-your-deepseek-key
LLM_MODEL=deepseek/deepseek-v3.2
LLM_BASE_URL=https://api.deepseek.com/v1
# 方式二：使用 OpenAI
LLM_API_KEY=sk-your-openai-key
LLM_MODEL=gpt-4o
LLM_BASE_URL=https://api.openai.com/v1
# 方式三：使用 OpenRouter（接入多种模型）
LLM_API_KEY=sk-or-your-openrouter-key
LLM_MODEL=anthropic/claude-sonnet-4-6
LLM_BASE_URL=https://openrouter.ai/api/v1
验证安装
# 检查 Docker 容器是否运行（Docker 部署方式）
docker compose ps
# 预期输出:
# NAME STATUS PORTS
# deerflow-backend Up 30 seconds 0.0.0.0:2024->2024/tcp
# deerflow-gateway Up 30 seconds 0.0.0.0:8001->8001/tcp
# deerflow-frontend Up 30 seconds 0.0.0.0:3000->3000/tcp
# deerflow-nginx Up 30 seconds 0.0.0.0:2026->2026/tcp
# 检查后端 API 是否可用
curl http://localhost:8001/health
# 预期输出: {"status": "ok"}
# 打开 Web 前端
# 浏览器访问 http://localhost:3000
# 典型验证输出
$ docker compose ps
NAME IMAGE COMMAND SERVICE STATUS PORTS
deerflow-backend deerflow-backend "python -m deerflow.…" backend Up 30 seconds 0.0.0.0:2024->2024/tcp
deerflow-gateway deerflow-gateway "python -m gateway.s…" gateway Up 30 seconds 0.0.0.0:8001->8001/tcp
deerflow-frontend deerflow-frontend "npm run dev" frontend Up 30 seconds 0.0.0.0:3000->3000/tcp
deerflow-nginx deerflow-nginx "nginx -g 'daemon of…" nginx Up 30 seconds 0.0.0.0:2026->2026/tcp
$ curl http://localhost:8001/health
{"status": "ok", "version": "2.0.0"}
基于 DeerFlow 2.0 官方 README 和 Docker Compose 配置（docker-compose.yml）
第一部分：入门篇
1.1 第一个任务：通过 Web 前端提交研究任务
概念讲解：
DeerFlow 的最基本使用方式是通过 Web 前端提交任务。DeerFlow 的 Web 前端基于 Next.js 构建，提供了直观的对话界面，类似于 ChatGPT，但功能远超普通对话——DeerFlow 会自动将复杂任务分解为子任务、派生子智能体并行执行、在沙盒环境中运行代码。
理解"任务提交 → 子智能体编排 → 结果聚合"的基本流程是使用 DeerFlow 的基础。DeerFlow 内置了"深度研究"技能（Skills），当你提交一个研究类问题时，它会自动加载该技能并按照结构化工作流执行。
操作步骤：
# 基于 DeerFlow 2.0 官方 README
# 1. 确保 DeerFlow 正在运行
docker compose ps
# 2. 打开浏览器访问 http://localhost:3000
# 3. 在对话框中输入研究任务，例如:
# "研究 2026 年最流行的 Python Web 框架，对比它们的性能、生态和学习曲线"
# 4. 观察 DeerFlow 的工作过程:
# - Lead Agent 分析任务
# - 自动加载"深度研究"技能
# - 派生子智能体并行研究不同方面
# - 实时显示每个子智能体的进度
# - 综合所有结果生成最终报告
执行结果：
# DeerFlow Web 前端的典型任务执行过程（模拟）
[Lead Agent] 正在分析任务: "研究 2026 年最流行的 Python Web 框架..."
[Lead Agent] 加载技能: 深度研究 (research)
[Lead Agent] 任务分解为 3 个子任务:
1. 研究 FastAPI 的架构、性能和生态
2. 研究 Django 5.x 的新特性和性能
3. 研究 其他新兴框架（Litestar, Starlette 等）
[Sub-Agent 1] 正在搜索 FastAPI 相关资料...
[Sub-Agent 2] 正在搜索 Django 5.x 相关资料...
[Sub-Agent 3] 正在搜索 Litestar, Starlette 等框架...
[Sub-Agent 1] 完成: 收集了 12 篇技术文章和 3 个基准测试
[Sub-Agent 2] 完成: 收集了 8 篇技术文章和 Django 官方文档
[Sub-Agent 3] 完成: 收集了 6 篇技术文章和社区讨论
[Lead Agent] 正在综合研究结果...
=== 最终报告 ===
# 2026 年 Python Web 框架对比
## 1. FastAPI
- 性能: 基准测试显示 FastAPI 在异步场景下性能最优
- 生态: 丰富的中间件和插件生态
...
## 2. Django 5.x
- 性能: 同步场景下的全栈框架首选
- 生态: 最成熟的 Python Web 生态
...
## 3. 新兴框架
- Litestar: 渐进式增长的现代框架
...
以上输出为基于 DeerFlow 深度研究技能的预期执行过程。实际输出取决于 LLM 模型和搜索结果。
练习题： 1. 提交一个你感兴趣的研究任务（如"对比 Docker 和 Kubernetes 的适用场景"），观察 DeerFlow 的任务分解和子智能体编排过程。 2. 尝试在任务执行过程中查看子智能体的实时状态，理解并行执行的概念。
1.2 理解 Lead Agent 和子智能体：任务编排机制
概念讲解：
DeerFlow 的核心是 Lead Agent 和子智能体（Sub-Agent）的协作模式。理解这个模式对于有效使用 DeerFlow 至关重要。
Lead Agent 是任务的主控者，负责： - 分析用户请求，决定是否需要派生子智能体 - 加载所需的技能（Skills）到上下文 - 协调子智能体的并行执行 - 综合所有子智能体的结果生成最终输出
子智能体（Sub-Agent） 是任务的执行者，每个子智能体： - 拥有独立的上下文（Context Isolation），不会看到其他子智能体的中间结果 - 拥有独立的工具集和终止条件 - 完成后向 Lead Agent 汇报结构化结果
这种设计的核心优势是：子智能体的上下文隔离确保了信息不会混淆，并行执行提高了效率，结构化汇报使 Lead Agent 能够有效综合结果。
代码示例：
# 基于 DeerFlow 2.0 架构（backend/docs/ARCHITECTURE.md）
# config.yaml 中的 Agent 配置示例
agent:
# Lead Agent 配置
lead:
model: "deepseek/deepseek-v3.2"
temperature: 0.3
max_sub_agents: 5 # 最大并行子智能体数
max_iterations: 20 # 最大迭代次数
timeout: 3600 # 任务超时（秒），1 小时
# 子智能体配置
sub_agent:
model: "deepseek/deepseek-v3.2"
temperature: 0.1 # 更低的温度，更精确的执行
max_iterations: 10 # 单个子智能体最大迭代次数
timeout: 600 # 子智能体超时（秒），10 分钟
# 上下文管理
context:
summarization: true # 启用自动摘要
max_context_tokens: 8000 # 最大上下文 token 数
执行结果：
# DeerFlow 日志中观察子智能体编排的典型输出
2026-04-13 10:00:01 [Lead Agent] Task received: "研究 AI Agent 框架对比"
2026-04-13 10:00:03 [Lead Agent] Loading skill: research
2026-04-13 10:00:05 [Lead Agent] Spawning Sub-Agent 1: "研究 LangGraph"
2026-04-13 10:00:05 [Lead Agent] Spawning Sub-Agent 2: "研究 CrewAI"
2026-04-13 10:00:05 [Lead Agent] Spawning Sub-Agent 3: "研究 AutoGen"
2026-04-13 10:00:05 [Lead Agent] 3 Sub-Agents running in parallel
2026-04-13 10:03:12 [Sub-Agent 2] Completed: CrewAI research done
2026-04-13 10:03:45 [Sub-Agent 1] Completed: LangGraph research done
2026-04-13 10:04:01 [Sub-Agent 3] Completed: AutoGen research done
2026-04-13 10:04:02 [Lead Agent] All Sub-Agents completed
2026-04-13 10:04:15 [Lead Agent] Final report generated (2,450 words)
练习题： 1. 提交一个需要多个子智能体协作的任务，观察日志中的子智能体创建和完成时间，分析并行执行的效果。 2. 尝试提交一个不需要子智能体的简单任务（如"解释什么是 REST API"），对比 DeerFlow 的处理方式有何不同。
1.3 技能系统初探：理解渐进式加载
概念讲解：
DeerFlow 的技能（Skills）是其能力扩展的核心机制。每个技能是一个 SKILL.md 文件，包含工作流、最佳实践和参考资源。关键特点是渐进式加载——技能仅在任务需要时才加载到上下文中。
这意味着 DeerFlow 可能拥有 20 个技能，但在处理一个"深度研究"任务时，只会加载"研究"相关的技能，保持上下文窗口精简。当你需要生成幻灯片时，才会加载"幻灯片创建"技能。
代码示例：
# 基于 DeerFlow 2.0 官方 README
# 1. 查看内置技能列表
ls skills/public/
# 2. 查看某个技能的内容
# 深度研究技能示例
cat skills/public/research/SKILL.md
<!-- skills/public/research/SKILL.md 内容示例 -->
---
name: "深度研究"
description: "对给定主题进行多轮深度研究，生成结构化报告"
license: "MIT"
allowed-tools: ["web_search", "web_fetch", "read_file", "write_file"]
---
## 工作流
1. **需求分析**: 理解研究目标，分解为可执行的子任务
2. **信息收集**: 对每个子任务进行多源搜索和资料收集
3. **交叉验证**: 使用至少 2 个独立来源验证关键信息
4. **结构化输出**: 按照标准模板生成研究报告
## 最佳实践
- 优先搜索学术来源和官方文档
- 记录每条信息的来源 URL
- 使用多源交叉验证确保准确性
## 参考资源
- 学术搜索策略文档
- 可靠信息源评级标准
# 3. 创建自定义技能（简单示例）
mkdir -p skills/custom/summarizer
<!-- skills/custom/summarizer/SKILL.md -->
---
name: "文章摘要"
description: "对给定文章或文档生成简洁的中文摘要"
license: "MIT"
allowed-tools: ["read_file", "write_file"]
---
## 工作流
1. 使用 read_file 读取目标文档
2. 识别文档的核心论点和关键数据
3. 生成 300 字以内的中文摘要
4. 保存摘要到 /mnt/user-data/outputs/ 目录
## 最佳实践
- 摘要应保留原文的关键数据和结论
- 使用客观描述，避免主观评价
- 标注原文来源和摘要生成时间
执行结果：
# 查看内置技能的典型输出
$ ls skills/public/
claude-to-deerflow report research slides video web
# 每个目录包含一个 SKILL.md 文件
$ ls skills/public/research/
SKILL.md resources/
# 创建自定义技能后
$ ls skills/custom/
summarizer/
基于 DeerFlow 2.0 技能系统架构。实际技能目录结构以官方仓库为准。
练习题：
1. 查看内置的 report 和 slides 技能的 SKILL.md 内容，比较它们的工作流和 allowed-tools 有何不同。
2. 创建一个简单的自定义技能（如"翻译"或"代码审查"），测试它是否被正确加载。
第二部分：进阶篇
2.1 配置模型和多模型策略
概念讲解：
DeerFlow 的模型工厂（Model Factory）通过反射机制从 config.yaml 中解析模型配置。你可以为 Lead Agent 和子智能体配置不同的模型，根据任务特点平衡成本和质量。
例如，Lead Agent 负责任务分解和结果综合，需要较强的推理能力，可以配置高端模型；子智能体负责具体的资料收集和执行，可以配置性价比更高的模型。
代码示例：
# 基于 DeerFlow 2.0 配置（config.yaml）
# 多模型配置示例
models:
# Lead Agent 使用高端模型（更强的推理能力）
lead:
provider: "openai"
model: "deepseek/deepseek-v3.2"
api_key: "${DEEPSEEK_API_KEY}"
base_url: "https://api.deepseek.com/v1"
temperature: 0.3
max_tokens: 4096
# 子智能体使用轻量模型（更快响应，更低成本）
sub:
provider: "openai"
model: "deepseek/deepseek-chat"
api_key: "${DEEPSEEK_API_KEY}"
base_url: "https://api.deepseek.com/v1"
temperature: 0.1
max_tokens: 8192
# 可选: 通过 OpenRouter 接入 Claude（用于需要高质量推理的场景）
# premium:
# provider: "openai"
# model: "anthropic/claude-sonnet-4-6"
# api_key: "${OPENROUTER_API_KEY}"
# base_url: "https://openrouter.ai/api/v1"
# 修改配置后重启服务
docker compose restart backend
# 或本地开发模式，直接重启后端进程
# Ctrl+C 停止后端，然后重新启动
python -m deerflow.server
注意事项：
- provider 字段对应 LangChain 的模型类前缀，DeerFlow 的 Model Factory 通过反射机制自动加载对应的类。大多数实现 OpenAI API 的提供商都可以使用 provider: "openai"。
- temperature 参数影响输出的创造性。Lead Agent 建议使用 0.2-0.4（平衡创造性和准确性），子智能体建议使用 0.0-0.2（更精确的执行）。
- 修改 config.yaml 后需要重启服务才能生效。
练习题： 1. 配置 Lead Agent 和子智能体使用不同的模型，提交一个任务并观察两者使用的模型是否不同（查看日志）。 2. 尝试通过 OpenRouter 配置一个不同的模型提供商，验证多模型支持。
2.2 沙盒执行环境：安全运行用户代码
概念讲解：
DeerFlow 的沙盒系统（Sandbox）是 Agent 安全执行代码的核心机制。理解沙盒的工作方式对于在 DeerFlow 中运行代码、处理文件和管理任务输出至关重要。
沙盒提供了两种模式： - LocalSandboxProvider：开发环境使用，命令在本地进程空间执行。简单快速，但隔离性较弱。 - AioSandboxProvider：生产环境使用，命令在隔离的 Docker 容器中异步执行。提供完整的隔离和安全保障。
Agent 通过 bash 工具在沙盒中执行命令，所有文件操作都在虚拟文件系统中进行。
代码示例：
# 基于 DeerFlow 2.0 配置（config.yaml）
# 沙盒配置示例
sandbox:
# 开发环境使用本地沙盒
provider: "local"
# 生产环境使用 Docker 沙盒（取消注释以下配置）
# provider: "aio"
# docker:
# image: "deerflow-sandbox:latest"
# memory_limit: "2g"
# cpu_limit: "1.0"
# timeout: 300
# 虚拟路径映射（两种模式共享）
paths:
workspace: "/mnt/user-data/workspace"
uploads: "/mnt/user-data/uploads"
outputs: "/mnt/user-data/outputs"
skills: "/mnt/skills"
# 基于 DeerFlow 2.0 架构
# 在 DeerFlow 中，Agent 通过 bash 工具执行命令时:
# Agent 发出工具调用: bash("python /mnt/user-data/workspace/analyze.py")
#
# 沙盒内部处理:
# 1. 虚拟路径映射: /mnt/user-data/workspace → 实际物理路径
# 2. 安全检查: 防止路径穿越（如 ../../etc/passwd）
# 3. 命令执行: 在沙盒环境中运行
# 4. 结果返回: 捕获 stdout 和 stderr
# 切换到 Docker 沙盒模式
# 编辑 config.yaml 或 .env:
# SANDBOX_PROVIDER=aio
docker compose restart backend
注意事项：
- 在 Docker 沙盒模式下，需要预先构建沙盒镜像（deerflow-sandbox:latest）。镜像应包含 Agent 可能需要的基础工具（Python、pip 常用包等）。
- 沙盒的超时设置很重要。如果任务需要长时间运行（如模型训练），需要适当增加 timeout 值。
- 文件上传后会自动存储到 /mnt/user-data/uploads/ 虚拟路径。Agent 可以通过 read_file 或 bash 工具访问这些文件。
练习题： 1. 提交一个需要执行 Python 代码的任务（如"用 Python 计算斐波那契数列的前 20 项并保存结果"），观察沙盒的执行过程。 2. 尝试切换沙盒模式（local ↔ aio），对比两种模式的执行差异。
2.3 IM 渠道集成：从聊天应用驱动 Agent
概念讲解：
DeerFlow 支持五大即时通讯平台的集成：Telegram、Slack、飞书/Lark、微信、企业微信。配置后，用户可以直接从聊天应用向 DeerFlow 提交任务，无需打开 Web 界面。
每个 IM 渠道支持以下交互命令：
- /new — 创建新任务
- /status — 查看当前任务状态
- /models — 查看和切换可用模型
- /memory — 查看和管理长期记忆
- /help — 显示帮助信息
IM 集成的核心优势是将 AI Agent 嵌入到用户已有的工作流中，降低使用门槛。
代码示例：
# 基于 DeerFlow 2.0 配置（config.yaml）
# IM 渠道配置示例
channels:
# Telegram 配置
telegram:
enabled: true
bot_token: "${TELEGRAM_BOT_TOKEN}"
# 获取 Bot Token: 在 Telegram 中找 @BotFather 创建 Bot
# Slack 配置
slack:
enabled: true
bot_token: "${SLACK_BOT_TOKEN}"
app_token: "${SLACK_APP_TOKEN}"
# 获取 Token: 在 Slack API 管理页面创建 App
# 飞书/Lark 配置
lark:
enabled: false
app_id: "${LARK_APP_ID}"
app_secret: "${LARK_APP_SECRET}"
# 获取凭证: 在飞书开放平台创建应用
# 微信配置（需要企业微信或个人微信的开发者权限）
wechat:
enabled: false
# 配置方式因微信版本而异
# 配置 IM 渠道后，DeerFlow 会在启动时自动连接
docker compose restart backend
# 查看日志确认渠道已连接
docker compose logs backend | grep -i channel
# 预期输出:
# [Channel] Telegram bot connected: @YourDeerFlowBot
# [Channel] Slack bot connected to workspace
注意事项： - IM 渠道配置后自动启动，无需公网 IP。DeerFlow 使用长轮询（Long Polling）或 WebSocket 连接到 IM 平台。 - 不同 IM 平台对消息长度有限制。DeerFlow 会自动将长结果拆分为多条消息或提供文件下载链接。 - Telegram 和 Slack 的配置最为简单，建议从这两个平台开始。
练习题：
1. 配置 Telegram 或 Slack 渠道，从聊天应用中提交一个研究任务，对比与 Web 前端提交的体验差异。
2. 尝试使用 /memory 命令查看和管理长期记忆，理解跨会话记忆的工作方式。
第三部分：高级篇
3.1 开发自定义技能（Custom Skills）
概念讲解：
自定义技能是扩展 DeerFlow 能力的主要方式。每个技能是一个包含 SKILL.md 的目录，DeerFlow 会自动发现 skills/custom/ 目录下的所有技能。
一个高质量的技能需要包含： 1. YAML Frontmatter：定义技能的元数据（名称、描述、允许的工具） 2. 工作流（Workflow）：清晰定义 Agent 应该遵循的步骤 3. 最佳实践（Best Practices）：帮助 Agent 避免常见错误 4. 参考资源（References）：提供相关的知识和模板
代码示例：
<!-- skills/custom/data-analysis/SKILL.md -->
---
name: "数据分析"
description: "对上传的数据文件进行统计分析，生成可视化报告"
license: "MIT"
allowed-tools: ["bash", "read_file", "write_file", "view_image"]
---
## 工作流
### 步骤 1: 数据探索
- 使用 `read_file` 读取上传的数据文件
- 识别文件格式（CSV、JSON、Excel 等）
- 检查数据的基本统计信息（行数、列数、缺失值）
### 步骤 2: 数据清洗
- 使用 `bash` 运行 Python 脚本进行数据清洗
- 处理缺失值（删除或填充）
- 处理异常值（标记或移除）
### 步骤 3: 统计分析
- 根据数据特征选择合适的分析方法
- 生成描述性统计（均值、中位数、标准差）
- 执行相关性分析或分组比较
### 步骤 4: 可视化
- 使用 matplotlib 或 seaborn 生成图表
- 图表保存到 /mnt/user-data/outputs/ 目录
- 使用 `view_image` 工具在对话中展示图表
### 步骤 5: 生成报告
- 将分析结果和图表整合为结构化报告
- 报告保存为 Markdown 文件
- 提供关键发现和建议
## 最佳实践
- 始终先检查数据质量再进行分析
- 可视化图表应包含清晰的标题、轴标签和图例
- 分析结果应标注统计显著性
- 对于大数据集，先采样再分析以提高速度
## 参考资源
- Python pandas 数据分析常用操作清单
- matplotlib 图表类型选择指南
- 统计分析方法速查表
# 创建技能目录和文件
mkdir -p skills/custom/data-analysis
# 将上述 SKILL.md 内容写入文件
# 重启服务（某些版本需要重启才能发现新技能）
docker compose restart backend
# 测试自定义技能
# 在 Web 前端或 IM 渠道中提交:
# "分析我上传的 sales_data.csv 文件，找出销售趋势和异常点"
# DeerFlow 会自动加载"数据分析"技能
注意事项：
- allowed-tools 字段非常重要，它限制了技能可以使用的工具范围。例如，"数据分析"技能不需要 web_search 工具，不应包含它。
- 工作流描述越详细，Agent 执行得越好。模糊的工作流描述会导致 Agent 不确定下一步该做什么。
- 技能的 resources/ 子目录可以放置辅助文件（如模板、参考数据），Agent 可以通过 read_file 工具读取。
3.2 MCP 工具集成：连接外部系统
概念讲解：
Model Context Protocol（MCP）是 DeerFlow 连接外部工具的主要方式。通过 MCP，DeerFlow 可以集成第三方 API、内部系统、数据库等外部资源，无需修改核心代码。
DeerFlow 的 MCP 客户端支持三种传输协议： - stdio：启动本地子进程作为 MCP 服务器，适合集成命令行工具 - SSE（Server-Sent Events）：连接远程 SSE 端点，适合集成 Web 服务 - HTTP：连接 HTTP API，适合集成 REST 服务
配置文件 extensions_config.json 变更后，DeerFlow 会自动重载 MCP 工具，无需重启。
代码示例：
// 基于 DeerFlow 2.0 配置（extensions_config.json）
// MCP 工具集成配置示例
{
"mcpServers": {
"database-query": {
"transport": "stdio",
"command": "python",
"args": ["-m", "mcp_db_query"],
"env": {
"DB_CONNECTION_STRING": "${DATABASE_URL}"
}
},
"web-search": {
"transport": "stdio",
"command": "python",
"args": ["-m", "mcp_web_search"],
"env": {
"SEARCH_API_KEY": "${SEARCH_API_KEY}"
}
},
"internal-api": {
"transport": "sse",
"url": "http://api.internal:8080/sse",
"headers": {
"Authorization": "Bearer ${INTERNAL_API_TOKEN}"
}
}
}
}
# 添加 MCP 配置后，DeerFlow 会自动检测变化并重载
# 查看已加载的 MCP 工具
docker compose logs backend | grep -i "mcp"
# 预期输出:
# [MCP] Loaded tools from: database-query
# [MCP] Loaded tools from: web-search
# [MCP] Loaded tools from: internal-api
注意事项： - MCP 服务器进程独立于 DeerFlow 主进程运行。如果 MCP 服务器崩溃，不影响 DeerFlow 的其他功能。 - stdio 模式的 MCP 服务器需要预先安装在 Docker 镜像或本地环境中。 - SSE 和 HTTP 模式的 MCP 服务器需要确保网络可达性。
3.3 长期记忆管理与优化
概念讲解：
DeerFlow 的长期记忆（Long-Term Memory）使 Agent 能够跨会话积累用户偏好和知识。理解记忆的工作方式有助于优化 Agent 的个性化效果。
记忆系统的工作流程：
1. 读取（同步）：Agent 处理请求前，ThreadData 中间件从记忆系统加载用户画像
2. 更新（异步）：任务完成后，新的偏好和知识被加入防抖队列，延迟写入
3. 管理：用户可通过 /memory 命令查看、删除特定记忆
代码示例：
# 基于 DeerFlow 2.0 架构
# 通过 IM 渠道管理记忆
# 查看当前记忆
/memory
# 输出:
# 记忆条目 (5):
# 1. 用户偏好: 报告使用中文撰写
# 2. 用户偏好: 代码使用 Python
# 3. 知识: 用户从事数据科学工作
# 4. 知识: 用户常用 matplotlib 进行可视化
# 5. 偏好: 研究报告包含执行摘要
# 删除特定记忆
/memory delete 3
# 输出: 已删除记忆条目 #3
# 清除全部记忆
/memory clear
# 输出: 已清除全部记忆
注意事项： - 记忆的防抖写入意味着更新可能有几秒延迟。频繁提交任务时，最新的记忆可能不会立即生效。 - 记忆系统使用 TIAMAT 作为云后端。在本地部署时，确保 TIAMAT 服务可用或配置本地存储替代方案。 - 过多的记忆条目可能影响 Agent 的上下文效率。建议定期清理不再需要的记忆。
第四部分：实战项目
项目需求
构建一个"自动化研究助手"，综合运用以下知识点： 1. Web 前端任务提交（知识点 1.1）：通过 Web 界面提交研究任务 2. 子智能体编排（知识点 1.2）：理解并行研究的工作方式 3. 自定义技能开发（知识点 3.1）：创建"技术调研"技能 4. 沙盒执行环境（知识点 2.2）：在沙盒中运行数据处理脚本 5. 模型配置（知识点 2.1）：为不同任务类型配置合适的模型
功能要求： - 接受用户的技术调研需求（如"调研 LangGraph 的架构和生态"） - 自动分解为多个子任务并行研究 - 收集官方文档、技术博客、社区评价等多源信息 - 在沙盒中运行分析脚本处理收集的数据 - 生成结构化的技术调研报告
项目设计
tech-research-assistant/
│
├── skills/
│ └── custom/
│ └── tech-research/ # 自定义技能
│ ├── SKILL.md # 技能定义
│ └── resources/
│ └── report-template.md # 报告模板
│
├── config/
│ └── models.yaml # 模型配置（覆盖默认配置）
│
├── scripts/
│ └── analyze.py # 分析脚本（在沙盒中运行）
│
└── outputs/ # 输出目录
└── reports/ # 生成的报告
完整实施代码
第一步：创建技术调研技能
<!-- skills/custom/tech-research/SKILL.md -->
---
name: "技术调研"
description: "对给定技术进行系统化调研，生成包含架构、生态、竞品对比的结构化报告"
license: "MIT"
allowed-tools: ["web_search", "web_fetch", "bash", "read_file", "write_file"]
---
## 工作流
### 阶段 1: 信息收集（并行执行）
1. 搜索该技术的官方文档和 GitHub 仓库
2. 搜索技术博客和深度分析文章
3. 搜索社区评价和讨论（Reddit、Hacker News）
4. 搜索竞品和同类技术对比
### 阶段 2: 数据分析
1. 使用 `read_file` 读取报告模板
2. 使用 `bash` 运行分析脚本整理收集的数据
3. 生成统计数据（Stars、下载量、版本历史等）
### 阶段 3: 报告生成
1. 按照报告模板结构组织内容
2. 生成技术概述、架构分析、竞品对比、适用场景等章节
3. 保存报告到 /mnt/user-data/outputs/reports/ 目录
## 最佳实践
- 每条信息必须标注来源 URL
- 竞品对比至少包含 3 个竞品
- 架构分析需引用官方文档
- 性能数据需标注测试环境和日期
## 参考资源
- 技术调研方法论
- 架构分析框架
第二步：创建报告模板
<!-- skills/custom/tech-research/resources/report-template.md -->
# {{技术名称}} - 技术调研报告
## 1. 基本信息
- 技术名称:
- 官方地址:
- GitHub 仓库:
- 当前版本:
- License:
- 主要语言:
- 创建者/维护团队:
## 2. 核心特性
1. 特性名称 - 描述
2. ...
## 3. 技术架构
### 3.1 整体架构
（架构图或分层描述）
### 3.2 核心模块
- 模块1 - 职责
- ...
### 3.3 扩展机制
（如何扩展）
## 4. 竞品对比
| 维度 | 本技术 | 竞品A | 竞品B |
|------|--------|-------|-------|
| ... | ... | ... | ... |
## 5. 适用场景
### 最佳场景
1. ...
### 不适用场景
1. ...
## 6. 总结与建议
（综合评价和使用建议）
## 信息来源
- 来源1
- 来源2
第三步：创建数据分析脚本
# scripts/analyze.py
# 在 DeerFlow 沙盒中运行的数据分析脚本
# 基于 DeerFlow 2.0 沙盒虚拟文件系统
import json
import sys
from datetime import datetime
from pathlib import Path
def analyze_research_data(input_path: str, output_path: str) -> None:
"""分析收集的研究数据，生成统计摘要"""
# 读取收集的研究数据（JSON 格式）
input_file = Path(input_path)
if not input_file.exists():
print(f"错误: 输入文件不存在: {input_path}")
sys.exit(1)
with open(input_file, "r", encoding="utf-8") as f:
data = json.load(f)
# 统计分析
summary = {
"analysis_time": datetime.now().isoformat(),
"tech_name": data.get("tech_name", "unknown"),
"sources_count": len(data.get("sources", [])),
"features_count": len(data.get("features", [])),
"competitors_count": len(data.get("competitors", [])),
"github_stars": data.get("github_stars", "N/A"),
"license": data.get("license", "N/A"),
"source_categories": {},
}
# 按来源类型分类统计
for source in data.get("sources", []):
category = source.get("type", "other")
summary["source_categories"][category] = (
summary["source_categories"].get(category, 0) + 1
)
# 保存分析结果
output_file = Path(output_path)
output_file.parent.mkdir(parents=True, exist_ok=True)
with open(output_file, "w", encoding="utf-8") as f:
json.dump(summary, f, ensure_ascii=False, indent=2)
print(f"分析完成:")
print(f" 技术名称: {summary['tech_name']}")
print(f" 信息来源: {summary['sources_count']} 条")
print(f" 核心特性: {summary['features_count']} 个")
print(f" 竞品数量: {summary['competitors_count']} 个")
print(f" GitHub Stars: {summary['github_stars']}")
print(f" 来源分类: {summary['source_categories']}")
print(f" 结果保存到: {output_path}")
if __name__ == "__main__":
input_path = sys.argv[1] if len(sys.argv) > 1 else "/mnt/user-data/uploads/research_data.json"
output_path = sys.argv[2] if len(sys.argv) > 2 else "/mnt/user-data/outputs/analysis_summary.json"
analyze_research_data(input_path, output_path)
代码解析
知识点运用说明：
-
Web 前端任务提交（1.1 节）：用户通过 DeerFlow 的 Web 前端提交技术调研任务，如"调研 LangGraph 的架构和生态"。DeerFlow 自动将任务路由到 Lead Agent 处理。
-
子智能体编排（1.2 节）：Lead Agent 将调研任务分解为多个子任务（信息收集、数据分析、报告生成），并行派生子智能体执行。每个子智能体独立收集不同来源的信息。
-
自定义技能开发（3.1 节）：
tech-research/SKILL.md定义了技术调研的完整工作流，包括信息收集策略、分析方法和报告模板。allowed-tools限制了技能只能使用必要的工具。 -
沙盒执行环境（2.2 节）：
analyze.py脚本在 DeerFlow 的沙盒环境中运行，通过虚拟路径/mnt/user-data/uploads/和/mnt/user-data/outputs/读写文件。 -
模型配置（2.1 节）：可以通过覆盖配置为技术调研任务指定更适合的模型。例如，信息收集阶段使用快速模型，报告生成阶段使用高质量模型。
扩展挑战
-
添加自动化评分：在技能中添加自动化的技术评分逻辑，根据 Stars、活跃度、文档质量等维度生成量化评分。
-
集成 MCP 搜索工具：将专业的学术搜索 API（如 Semantic Scholar）通过 MCP 集成到技能中，提升信息收集质量。
-
定期自动调研：配置定期任务，自动对关注的技术栈进行调研并生成对比报告。
第五部分：常见问题与排查指南
常见错误及解决方案
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
docker compose up 失败，端口被占用 |
2024/3000/8001/2026 端口已被其他服务使用 | 修改 docker-compose.yml 中的端口映射，或停止占用端口的服务 |
LLM_API_KEY not set |
未配置 LLM API Key | 编辑 .env 文件，填入有效的 API Key |
ModuleNotFoundError: No module named 'langgraph' |
后端依赖未安装 | 在 backend/ 目录执行 pip install -r requirements.txt |
Sandbox timeout |
沙盒执行超时 | 增加 config.yaml 中的 sandbox.timeout 值 |
Sub-Agent failed: context window exceeded |
子智能体上下文超出限制 | 减少任务的子任务数量，或增加 context.max_context_tokens |
MCP server connection failed |
MCP 服务器不可达 | 检查 MCP 服务器的网络连通性和配置。查看日志 docker compose logs backend |
Permission denied: /mnt/user-data/ |
沙盒文件系统权限问题 | 检查 Docker 卷挂载权限。执行 chmod -R 777 ./data/（开发环境） |
Docker sandbox image not found |
未构建沙盒 Docker 镜像 | 执行 docker build -t deerflow-sandbox -f Dockerfile.sandbox . |
Telegram bot not responding |
Telegram Bot Token 无效或网络问题 | 验证 Bot Token 是否正确。检查网络是否能连接 Telegram API |
基于 DeerFlow 2.0 官方 README 和常见部署问题
调试技巧
-
查看详细日志：使用
docker compose logs -f backend实时查看后端日志。日志中包含 Lead Agent 的决策过程、子智能体的创建和执行、工具调用详情等关键信息。对于任务执行失败，重点关注[Lead Agent]和[Sub-Agent]标签的日志行。 -
检查沙盒状态：在 Docker 沙盒模式下，使用
docker ps | grep sandbox查看沙盒容器是否正常运行。如果容器频繁重启，检查内存限制（memory_limit）是否足够。使用docker exec -it <sandbox-id> bash进入沙盒容器手动排查。 -
逐步调试技能：如果自定义技能不生效，首先检查
skills/custom/目录结构是否正确（必须包含SKILL.md）。然后在日志中搜索技能加载记录，确认 DeerFlow 是否发现了该技能。如果技能已加载但执行不符合预期，检查 SKILL.md 的工作流描述是否足够清晰。
第六部分：学习路线推荐
官方文档推荐阅读顺序
- GitHub README 快速入门 — 安装、Docker 部署、配置基础
- 地址：https://github.com/bytedance/deer-flow#readme
-
重点：Docker Compose 部署、环境变量配置、LLM 模型配置
-
ARCHITECTURE.md 架构文档 — 系统架构、中间件链、沙盒系统详解
- 地址：https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md
-
重点：中间件链设计、虚拟文件系统、MCP 集成、安全机制
-
Skills 系统文档 — 技能开发和管理
- 地址：skills/public/ 目录下的内置技能示例
-
重点：SKILL.md 格式、allowed-tools 配置、渐进式加载机制
-
Configuration Guide — 完整配置参考
- 地址：config.yaml 和 .env.example 文件
- 重点：模型配置、沙盒配置、IM 渠道配置、MCP 工具配置
推荐进阶资源
- dev.to - DeerFlow 2.0: The Deep Dive
- https://dev.to/
-
社区深度分析文章，涵盖架构、沙盒、技能、记忆等核心机制
-
LangGraph 官方文档
- https://langchain-ai.github.io/langgraph/
-
DeerFlow 的核心编排引擎。理解 LangGraph 的 StateGraph、节点、边等概念有助于深入理解 DeerFlow 的编排机制
-
LangChain 官方文档
- https://python.langchain.com/
- DeerFlow 使用 LangChain 进行 LLM 交互。了解 LangChain 的模型抽象、工具调用、消息格式有助于自定义模型和工具
进阶方向建议
完成本教程后，建议按以下方向深入学习：
- 深入 LangGraph：学习 StateGraph 的高级用法（条件分支、循环、并行节点），理解 DeerFlow 如何在 LangGraph 上构建中间件链
- 开发 MCP 工具：学习 MCP 协议规范，开发自定义的 MCP 工具服务器，连接内部系统
- 生产环境部署：研究 Kubernetes 部署方案、安全加固、监控和日志集成
信息来源与版本说明
- 教程基于版本： DeerFlow 2.0（2026-02-27 发布）
- 信息获取日期： 2026-04-13
- 信息来源列表：
- GitHub 仓库 bytedance/deer-flow — 源码、README、配置文件
- GitHub API - bytedance/deer-flow — Stars: 60,751, Forks: 7,767
- 官方网站 deerflow.tech — 项目介绍和演示
- 官方 ARCHITECTURE.md — 完整系统架构
- dev.to - DeerFlow 2.0: The Deep Dive — 社区深度分析
- LangGraph 官方文档 — 编排引擎文档
- LangChain 官方文档 — LLM 交互文档