Deerflow Book AI Agent

《DeerFlow 二次开发：理论、架构与源码剖析》

面向硬核开发者的技术深度解析

本书围绕 DeerFlow 2.0，从理论到源码，系统讲解如何进行二次开发。

所有代码示例均基于真实源码，确保与 DeerFlow 实现保持一致。

---

🚀 开始阅读

📖 在线阅读（推荐）	搜索、目录导航、代码高亮、响应式布局
📄 GitHub 阅读	适合直接浏览 Markdown 源码

---

📚 书籍特色

• 源码级解析 - 每一章都深入 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：

1. 内容修正 - 发现与源码不符的地方
2. 章节补充 - 增加新的源码解析
3. 示例代码 - 提供更清晰的代码示例
4. 翻译 - 翻译成其他语言

详见 附录 B · 贡献指南

---

📌 版本信息

• DeerFlow 版本: 2.0
• 书籍版本: 2026.06
• 最后更新: 2026-06-21

---

📄 许可证

本书采用 MIT 许可证 开源。

DeerFlow 是 ByteDance 的开源项目，本书为社区贡献的二次开发指南。