面向硬核开发者的技术深度解析
本书围绕 DeerFlow 2.0,从理论到源码,系统讲解如何进行二次开发。
所有代码示例均基于真实源码,确保与 DeerFlow 实现保持一致。
| 📖 在线阅读(推荐) | 搜索、目录导航、代码高亮、响应式布局 |
|---|---|
| 📄 GitHub 阅读 | 适合直接浏览 Markdown 源码 |
- 源码级解析 - 每一章都深入 DeerFlow 源码,不是简单的概念介绍
- 实战导向 - 提供完整的二次开发示例,可直接用于项目
- 架构思维 - 不仅讲 "怎么用",更讲 "为什么这样设计"
- 持续更新 - 跟随 DeerFlow 版本迭代,保持内容最新
# 克隆 DeerFlow 官方仓库 git clone https://github.com/bytedance/deerflow.git cd deerflow # 使用 Docker Compose 启动全套服务 docker-compose up -d # 检查服务状态 docker-compose ps
启动后,打开浏览器访问 http://localhost:2026,在对话窗口中输入:
@web-researcher 请研究 "LangGraph 的 checkpoint 机制",深度:技术细节级别,输出格式:Markdown 报告
DeerFlow 会自动加载 web-researcher Skill,执行网络搜索、信息整合,并返回结构化的研究报告。
复制配置文件模板并根据需要调整:
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 系统 | Working Memory、Long-term Memory、Consolidation | agents/memory/ |
| 第十章 · 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 章节)
基于 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 节) |
基于 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.05
- 最后更新: 2026年05月02日
本书采用 MIT 许可证 开源。
DeerFlow 是 ByteDance 的开源项目,本书为社区贡献的二次开发指南。