《DeerFlow 二次开发：理论、架构与源码剖析》
面向硬核开发者的技术深度解析
本书围绕 DeerFlow 2.0，从理论到源码，系统讲解如何进行二次开发。
所有代码示例均基于真实源码，确保与 DeerFlow 实现保持一致。
🚀 开始阅读
📚 书籍特色
- 源码级解析 - 每一章都深入 DeerFlow 源码，不是简单的概念介绍
- 实战导向 - 提供完整的二次开发示例，可直接用于项目
- 架构思维 - 不仅讲 "怎么用"，更讲 "为什么这样设计"
- 持续更新 - 跟随 DeerFlow 版本迭代，保持内容最新
⚡ 5 分钟快速开始
1. Docker 一键启动
# 克隆 DeerFlow 官方仓库
git clone https://github.com/bytedance/deerflow.git
cd deerflow
# 使用 Docker Compose 启动全套服务
docker-compose up -d
# 检查服务状态
docker-compose ps
2. 第一条对话测试
启动后，打开浏览器访问 http://localhost:2026，在对话窗口中输入：
@web-researcher 请研究 "LangGraph 的 checkpoint 机制"，深度：技术细节级别，输出格式：Markdown 报告
DeerFlow 会自动加载 web-researcher Skill，执行网络搜索、信息整合，并返回结构化的研究报告。
3. 环境变量配置
复制配置文件模板并根据需要调整：
cp config.example.yaml config.yaml
cp extensions_config.example.json extensions_config.json
核心环境变量：
| 变量 | 说明 | 必填 |
|---|---|---|
OPENAI_API_KEY | LLM API Key | ✅ |
DEERFLOW_DATABASE_URL | PostgreSQL 连接串 | ✅ |
SANDBOX_MODE | local / docker / provisioner | 可选，默认 local |
MCP_SERVERS_CONFIG | MCP Server 配置文件路径 | 可选 |
详见 附录 A · 配置参考。
📖 目录结构
第一部分：理论基础
| 章节 | 内容亮点 |
|---|---|
| 第一章 · 引言 | DeerFlow 定位、核心特性、技术栈 |
| 第二章 · 核心概念 | Skill vs Tool、Sub-Agent、Sandbox、Memory、Context Engineering |
| 第三章 · 架构总览 | 系统架构图、LangGraph Server、Gateway API、中间件链 |
第二部分：源码剖析 ⭐️
| 章节 | 内容亮点 | 源码文件 |
|---|---|---|
| 第四章 · 项目结构 | 目录组织、模块职责、配置体系 | - |
| 第五章 · Agent 核心 ✅ | ThreadState 类型系统、14+ 中间件详解、DeerFlowClient SDK | agents/thread_state.py, agents/middlewares/ |
| 第六章 · Skills 与 Tools ✅ | Skill 安全扫描、历史管理、安装器实现 | skills/security_scanner.py, skills/manager.py, skills/installer.py |
| 第七章 · Sub-Agent 体系 ✅ | SubagentExecutor、任务状态机、背景任务管理 | subagents/executor.py, subagents/config.py |
| 第八章 · Sandbox 环境 ✅ | Provider 模式、中间件生命周期、安全审计 | sandbox/sandbox_provider.py, sandbox/middleware.py, sandbox/security.py |
| 第九章 · Memory 系统 ✅ | JSON Profile/Facts、LLM 更新、MemoryMiddleware、Prompt 注入 | agents/memory/storage.py, agents/memory/updater.py, agents/middlewares/memory_middleware.py |
| 第十章 · Context Engineering | 上下文压缩、RAG、Token 预算分配 | - |
第三部分：二次开发实战 ⭐️
| 章节 | 内容亮点 | 源码文件 |
|---|---|---|
| 第十一章 · MCP Server 集成 ✅ | OAuth 2.0 认证、工具缓存、多传输方式 (stdio/sse/http) | mcp/oauth.py, mcp/cache.py, mcp/client.py |
| 第十二章 · 自定义 Skill 开发 | 多模态输出 Skill（PPT/播客/图片/视频/看板） | - |
| 第十三章 · Human-in-the-Loop | 审批节点设计、审批中间件、审计日志 | - |
| 第十四章 · 企业级应用案例 | 多租户隔离、RBAC、审计系统、多模态内容平台、知识库集成 | - |
附录
- 附录 A · 配置参考 - 完整配置示例
- 附录 B · 贡献指南 - 开发规范、PR 流程
- 附录 C · 代码示例 - 多模态 Skill 完整代码
- 附录 D · 术语表 - 核心概念速查
✅ 标记表示本章已基于 DeerFlow 最新源码进行深度更新
🎯 阅读建议
不同读者的阅读路径
🆕 Agent 开发新手
第一章 → 第二章 → 第三章 → 第十二章 (快速上手 Skill 开发)
🔧 二次开发工程师
第四章 → 第五章 → 第六章 → 第七章 → 第十一章 (核心架构)
🏢 企业级应用开发者
第五章 → 第八章 → 第九章 → 第十三章 → 第十四章 (生产环境)
🔬 源码贡献者
通读全书 + 附录 B + 直接阅读 DeerFlow 源码
📋 阅读前置要求
- Python 3.12+ - 熟悉类型注解、异步编程
- LangChain / LangGraph - 了解基本概念（Graph、State、Node）
- Agent / LLM 应用开发 - 有实际项目经验更佳
- Docker - 理解容器基础（用于 Sandbox 章节）
🔄 最新更新
2026-06-21 重大更新
基于 DeerFlow 2.0 当前源码，对 Memory 相关内容进行了校正：
| 章节 | 更新内容 |
|---|---|
| Chapter 02 | 明确内置 Memory 不使用 embedding、向量数据库或相似度检索 |
| Chapter 09 | 重写 Memory 系统章节，改为 JSON profile/facts、LLM 更新、MemoryMiddleware、prompt 注入 |
| Chapter 10 | 将 Memory 检索示例改为 JSON facts 注入，并区分外部 RAG 扩展 |
| Appendix A/D | 更新 Memory 配置与术语解释 |
2026-05-02 重大更新
基于 DeerFlow 2.0 最新版本进展（2026 年 4 月），对以下章节进行了更新：
| 章节 | 更新内容 |
|---|---|
| Chapter 01 | 新增核心特性：Progressive Skill Loading、InfoQuest、多模态输出 |
| Chapter 03 | 新增渐进式 Skill 加载在架构中的位置（3.9 节） |
| Chapter 06 | 新增渐进式 Skill 加载机制、InfoQuest 集成 |
| Chapter 12 | 新增多模态输出 Skill 开发（PPT/播客/图片/视频/看板） |
| Chapter 14 | 新增企业级多模态内容生成平台（14.9 节） |
2026-04-09 重大更新
基于 DeerFlow 最新源码，对以下章节进行了深度更新：
| 章节 | 更新内容 |
|---|---|
| Chapter 05 | 新增 ThreadState 类型系统 (NotRequired/Annotated)、14+ 中间件完整列表、DeerFlowClient SDK |
| Chapter 06 | 新增 Skill 安全扫描、历史管理、安装器实现 |
| Chapter 07 | 新增 SubagentExecutor、任务状态机、背景任务管理 |
| Chapter 08 | 新增 Sandbox Provider 模式、中间件生命周期、安全审计 |
| Chapter 11 | 新增 OAuth 2.0 认证、MCP 工具缓存、多传输方式 |
🤝 参与贡献
本书是开源的，欢迎提交 PR：
- 内容修正 - 发现与源码不符的地方
- 章节补充 - 增加新的源码解析
- 示例代码 - 提供更清晰的代码示例
- 翻译 - 翻译成其他语言
详见 附录 B · 贡献指南
📌 版本信息
- DeerFlow 版本: 2.0
- 书籍版本: 2026.06
- 最后更新: 2026-06-21
📄 许可证
本书采用 MIT 许可证 开源。
DeerFlow 是 ByteDance 的开源项目，本书为社区贡献的二次开发指南。