DeerFlow 调研笔记
本文为字节跳动开源的 DeerFlow（Deep Exploration and Efficient Research Flow）调研笔记。DeerFlow 是一个社区驱动的 Super Agent Harness，通过编排子智能体、记忆系统和沙箱来完成几乎任何任务。
开源地址：https://github.com/bytedance/deer-flow
当前版本：2.0（2026 年全面重写，与 v1 不共享代码）
这篇文章说了什么
DeerFlow 是字节跳动开源的"超级智能体套件（Super Agent Harness）"。v1 定位是 Deep Research 框架（做深度研究、生成报告），v2 推倒重来后定位升级为通用 Agent 编排平台——Skill 化、插件化，号称"通过可扩展的 Skills 编排 sub-agents、记忆和沙箱来完成几乎任何任务"。
核心卖点：
- 完整的 Web UI：比纯 Python SDK 的框架多了开箱即用的前端，支持对话管理、文件预览、MCP 工具集成、播客生成
- Skills 系统：把能力封装为可复用的 Skill，用户可以创建、分享、组合
- 多种部署模式：本地 dev、Docker、K8s 沙箱、火山引擎一键部署
- 16.6k Stars：社区活跃度很高
它和 DeepAgents 最大的区别：DeerFlow 更像一个产品（有 UI、有 Skills 商店的概念、有火山引擎的商业化路径），而 DeepAgents 更像一个开发框架（SDK + CLI + LangSmith 部署）。
观后感
- DeerFlow v2 从"Deep Research"到"Super Agent Harness"的定位升级很聪明——Deep Research 赛道太卷了，通用 Agent 编排才是更大的市场
- Skills 系统的设计思路值得学习：把 Agent 能力封装为可复用、可分享的技能单元
- Web UI 是重要的差异化——很多 Agent 框架只有 SDK，非技术人员根本用不了
- 火山引擎的 Coding Plan 和一键部署说明字节是把它当云产品的获客工具在推
- 作为开源项目 16.6k Stars 说明社区认可度很高，但 v2 全面重写也意味着生态需要重建
一、项目概述与演进
1.1 从 v1 到 v2
| 维度 | v1 | v2 |
|---|---|---|
| 定位 | Deep Research 框架 | Super Agent Harness（通用 Agent 编排） |
| 代码 | 基于 LangGraph 的研究工作流 | 全面重写，不共享代码 |
| 核心能力 | 搜索 + 爬虫 + Python 执行 → 研究报告 | Skills 驱动的多 Agent 编排 + 沙箱 + 记忆 |
| UI | 控制台 + Web UI | 完整 Web UI（对话管理、文件预览、MCP） |
| 部署 | pip install + 配置文件 | Docker / 本地 / K8s / 火山引擎一键部署 |
v1 仍然在 main-1.x 分支维护，但活跃开发已转向 v2。
1.2 技术栈
DeerFlow 2.0
├── 后端：Python 3.12+ / LangGraph / uv
├── 前端：Node.js 22+ / Next.js / pnpm
├── 沙箱：Docker / K8s（provisioner 模式）
├── 部署：Docker Compose / 火山引擎 FaaS / Nginx
└── 追踪：LangSmith / Langfuse
二、核心能力
2.1 Skills 系统
DeerFlow 最核心的设计：把 Agent 能力封装为可复用的 Skills。
一个 Skill 包含：
- Instructions：告诉 Agent 这个技能是干什么的、怎么用
- Tools：技能需要的工具集（搜索、爬虫、代码执行等）
- Context：技能相关的领域知识
# Skill 示例（概念示意）
name: research-report
description: 深度研究并生成结构化报告
instructions: |
1. 先搜索收集信息
2. 生成大纲
3. 逐节撰写
4. 生成最终报告
tools: [web_search, web_crawl, python_execute]
Skills 可以：
- 用户自己创建
- 从社区分享中获取
- 在对话中动态切换（不同的 Skill 对应不同的工作模式）
2.2 Sub-Agents（子智能体）
DeerFlow 的核心编排单位是 Sub-Agent。一个复杂任务会被拆解为多个子 Agent 并行或串行执行。
与 DeepAgents 的 task 工具类似，但 DeerFlow 更强调 Skills 驱动的子 Agent：每个子 Agent 可以加载不同的 Skill，相当于"给不同的工人分配不同的工具箱"。
2.3 沙箱与文件系统
三种执行模式：
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Local Execution | 直接在宿主机执行代码 | 开发测试 |
| Docker Execution | 在隔离容器中执行 | 生产安全 |
| K8s Execution | 通过 provisioner 在 K8s Pod 中执行 | 大规模多租户 |
沙箱提供了 Agent 操作文件系统和执行 Python 代码的安全环境。结合文件上传功能，Agent 可以分析 PDF、处理 CSV 数据、生成图表。
2.4 上下文工程
DeerFlow 的上下文管理策略：
- 对话摘要：长对话自动压缩早期消息
- 文件系统卸载：大内容写入文件系统，不在对话中堆积
- 子 Agent 隔离：每个子 Agent 独立上下文，只回传结果
2.5 长期记忆
支持跨对话的持久化记忆。Agent 可以记住用户偏好、之前的讨论内容、学到的经验。存储支持本地文件和数据库两种模式。
三、MCP 协议与工具集成
3.1 MCP Server 支持
DeerFlow 深度集成了 MCP（Model Context Protocol），支持：
- HTTP/SSE MCP Servers：连接外部工具服务
- OAuth Token Flow：
client_credentials和refresh_token授权 - 动态工具发现：Agent 自动获取 MCP Server 提供的工具列表
3.2 搜索引擎
支持多种搜索后端：
| 搜索引擎 | 类型 | 需要 API Key |
|---|---|---|
| Tavily | AI 专用搜索 API | 需要 |
| InfoQuest | BytePlus 自研（推荐） | 需要 |
| DuckDuckGo | 隐私搜索引擎 | 不需要 |
| Brave Search | 隐私搜索引擎 | 需要 |
| Arxiv | 学术论文搜索 | 不需要 |
| Searx/SearxNG | 自托管元搜索引擎 | 需要自建 |
3.3 Claude Code / Codex 集成
v2 支持 CLI 驱动的模型提供者（Claude Code OAuth、Codex CLI），可以在 DeerFlow 中使用这些 CLI 工具背后的模型：
models:
- name: claude-sonnet-4.6
use: deerflow.models.claude_provider:ClaudeChatModel
model: claude-sonnet-4-6
- name: gpt-5.4
use: deerflow.models.openai_codex_provider:CodexChatModel
model: gpt-5.4
四、架构设计
4.1 启动模式
DeerFlow 支持多种启动模式组合：
| 模式 | 进程数 | 特点 |
|---|---|---|
| Standard（Dev） | 4 进程 | 前端 + Gateway + LangGraph + Nginx，支持热重载 |
| Standard（Prod） | 4 进程 | 同上但使用预构建前端 |
| Gateway（Dev） | 3 进程 | Gateway 内嵌 Agent 运行时，不需要独立 LangGraph Server |
| Gateway（Prod） | 3 进程 | 生产环境的 Gateway 模式 |
4.2 Standard vs Gateway 模式
Gateway 模式是 v2 的一个重要创新——把 Agent 运行时嵌入到 Gateway API 中：
| 维度 | Standard Mode | Gateway Mode |
|---|---|---|
| 架构 | Gateway (REST) + LangGraph (Agent Runtime) 分离 | Gateway 内嵌 Agent Runtime |
| 进程数 | 4 | 3 |
| 并发控制 | --n-jobs-per-worker（需要 license） | --workers × async tasks（无限制） |
| LangGraph 许可证 | 生产需要 | 不需要 |
| 资源占用 | 更高（两个 Python 运行时） | 更低 |
4.3 部署模式
| 部署方式 | 命令 | 适用场景 |
|---|---|---|
| 本地开发 | make dev | 开发调试 |
| Docker 开发 | make docker-start | 热重载 + 沙箱隔离 |
| Docker 生产 | make up | 生产环境 |
| 火山引擎 FaaS | 一键部署链接 | 免运维 |
五、Web UI 体验
DeerFlow 的 Web UI 是相比纯 SDK 框架最重要的差异化优势：
5.1 对话管理
- 多对话支持，会话历史持久化
- 对话模式切换：Default / Plan Mode / Skill Mode
- 模型动态切换（对话中可以换模型）
5.2 文件系统
- 可视化文件浏览器（Agent 创建的文件直接预览）
- 文件上传（PDF、CSV、代码等）
- Agent 生成的文件直接下载
5.3 MCP 工具管理
- Settings 页面可视化配置 MCP Server
- 工具状态实时显示
- 连接测试
5.4 Skills 管理
- 创建、编辑、删除 Skills
- Skills 市场/社区（规划中）
- 对话中动态加载 Skill
5.5 其他功能
- 播客生成：基于研究报告自动生成播客音频（TTS 集成）
- IM 集成：支持飞书等 IM 渠道
- 播客回放：历史对话可回放
- 通知：浏览器通知
六、企业级部署
6.1 部署规模建议
| 场景 | 最低配置 | 推荐配置 |
|---|---|---|
| 本地开发 | 4 vCPU, 8 GB RAM, 20 GB SSD | 8 vCPU, 16 GB RAM |
| Docker 开发 | 4 vCPU, 8 GB RAM, 25 GB SSD | 8 vCPU, 16 GB RAM |
| 生产服务器 | 8 vCPU, 16 GB RAM, 40 GB SSD | 16 vCPU, 32 GB RAM |
6.2 Docker 部署
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup # 交互式配置向导
make docker-init # 拉取沙箱镜像
make docker-start # 启动服务
# 访问 http://localhost:2026
6.3 火山引擎一键部署
DeerFlow 已入驻火山引擎 FaaS 应用中心，支持一键部署。这是字节跳动把开源项目转化为云产品获客的标准路径。
6.4 安全注意
官方明确警告：不当部署可能引入安全风险（Agent 有 shell 执行和文件系统访问能力）。建议：
- 使用沙箱模式（Docker/K8s）隔离执行环境
- 不要暴露到公网而不做鉴权
- 生产环境使用 Gateway 模式并配置认证
七、推荐模型
字节官方推荐用于 DeerFlow 的模型：
| 模型 | 推荐理由 |
|---|---|
| Doubao-Seed-2.0-Code | 字节自家的代码模型，深度优化 |
| DeepSeek v3.2 | 性价比最高的开源推理模型 |
| Kimi 2.5 | 中文能力优秀 |
| Claude Sonnet 4.6 | 闭源天花板，tool calling 最稳定 |
八、与 DeepAgents 的对比
| 维度 | DeerFlow | DeepAgents |
|---|---|---|
| 开发者 | 字节跳动 | LangChain |
| 定位 | Super Agent Harness（产品化） | Agent Harness（开发框架） |
| Web UI | ✅ 完整前端 | ❌ 仅 CLI |
| Skills 系统 | ✅ 封装为可复用 Skill | ✅ Skills Middleware |
| 子 Agent | Sub-agents + Skills 驱动 | task 工具 spawn |
| 沙箱 | Docker / K8s / 本地 | StateBackend / Sandbox / 本地 |
| MCP | ✅ 深度支持 | ✅ langchain-mcp-adapters |
| 记忆系统 | 持久化记忆 | LangGraph Store |
| 部署 | Docker / 火山引擎 | LangSmith Deploy |
| 社区 | 16.6k Stars | 15k+ Stars |
| 许可证 | MIT | MIT |
| 适合谁 | 需要开箱即用产品 + Web UI 的团队 | 需要编程式 Agent SDK 深度定制的开发者 |
九、生态与商业模式
DeerFlow 的开源-商业路径：
- 开源引流：MIT 许可证 + 16.6k Stars 建立社区认知
- 火山引擎集成：InfoQuest（搜索 API）、FaaS 一键部署、Coding Plan
- Skills 生态：社区 Skills 创造网络效应
- 企业版：推测未来会有付费的增强功能（更大规模的多租户、更强大的审计等）
十、核心经验总结
- v2 全面重写的勇气值得学习：不破不立，v1 的 Deep Research 定位太窄，v2 的 Super Agent Harness 定位打开了更大市场
- Skills 系统是 Agent 平台的"App Store"：让非编程用户也能创建和分享 Agent 能力，降低使用门槛
- Web UI 是框架到产品的关键一步：再好的 SDK 也只能服务开发者，Web UI 能服务所有知识工作者
- Gateway 模式解决了 LangGraph 的 license 问题：不用 LangGraph Platform Server 也能做到生产可用的并发和稳定性
- MCP 协议正在成为 Agent 工具的通用连接标准：两个框架都深度支持 MCP，这个趋势不可忽视
- 字节做开源的风格是"用开源养云"：DeerFlow 免费好用，但火山引擎的 InfoQuest、FaaS 部署都在同一个生态里