DeerFlow 项目笔记
基本信息
| 属性 | 内容 |
|---|---|
| 全称 | Deep Exploration and Efficient Research Flow |
| 开发方 | 字节跳动 (ByteDance) |
| 开源协议 | MIT License |
| 当前版本 | 2.0（2026年2月28日发布，当日登顶 GitHub Trending #1） |
| 星标数 | 27.4k |
| 分支数 | 3.3k |
| 关注者 | 132 |
| 技术栈 | Python 49.7%, TypeScript 30.4%, HTML 9.7%, CSS 4.3%, JavaScript 3.6%, Shell 1.8% |
核心定位演进
从 v1 到 v2 的根本转变：
| 维度 | v1.x (旧版) | v2.0 (当前) |
|---|---|---|
| 本质 | Deep Research 框架 | Super Agent Harness（超级智能体运行时） |
| 架构 | 可组合框架 | 电池内置、完全可扩展的运行时 |
| 代码关系 | 原始代码基 | 完全重写，与 v1 无共享代码 |
| 维护状态 | 社区维护（main-1.x 分支） |
活跃开发主线 |
关键洞察：社区将 DeerFlow 用于数据管道、幻灯片生成、仪表盘、内容工作流等超出研究范畴的场景，促使团队重新定义为"Harness"------给智能体提供实际完成工作的基础设施。
核心架构组件
┌─────────────────────────────────────────┐
│ DeerFlow Super Agent │
│ (Lead Agent) │
├─────────────────────────────────────────┤
│ 技能系统 (Skills) │ 工具系统 (Tools) │
│ • 研究技能 │ • 网页搜索 │
│ • 报告生成 │ • 网页抓取 │
│ • 幻灯片创建 │ • 文件操作 │
│ • 网页构建 │ • Bash 执行 │
│ • 图像/视频生成 │ • MCP 服务器扩展 │
│ • 自定义技能 │ • Python 函数 │
├─────────────────────────────────────────┤
│ 子智能体系统 (Sub-Agents) │
│ • 动态生成、并行执行、独立上下文 │
│ • 结构化结果汇总至主智能体 │
├─────────────────────────────────────────┤
│ 沙箱执行环境 (Sandbox) │
│ • 隔离 Docker 容器 │
│ • 完整文件系统：/mnt/user-data/ │
│ - uploads/ ← 用户上传文件 │
│ - workspace/ ← 智能体工作目录 │
│ - outputs/ ← 最终交付物 │
├─────────────────────────────────────────┤
│ 记忆系统 (Memory) │
│ • 会话内：主动摘要、上下文压缩 │
│ • 跨会话：持久化用户画像、偏好、知识积累 │
└─────────────────────────────────────────┘三种沙箱执行模式
| 模式 | 适用场景 | 配置要点 |
|---|---|---|
| Local Execution | 开发测试、快速迭代 | 代码直接在宿主机运行 |
| Docker Execution | 生产环境、隔离需求 | 独立 Docker 容器 |
| Docker + Kubernetes | 大规模部署、云原生 | 通过 provisioner 服务在 K8s pods 中执行 |
Docker 开发时，
make docker-start会根据config.yaml自动检测是否启动 provisioner。
即时通讯通道 (IM Channels)
| 通道 | 传输方式 | 难度 | 特点 |
|---|---|---|---|
| Telegram | Bot API (长轮询) | 简单 | 无需公网 IP |
| Slack | Socket Mode | 中等 | 需配置 OAuth 权限 |
| Feishu/Lark | WebSocket | 中等 | 字节生态原生支持 |
核心命令：
/new- 开启新对话/status- 查看当前线程信息/models- 列出可用模型/memory- 查看记忆/help- 显示帮助
关键集成：Claude Code
claude-to-deerflow 技能 允许在 Claude Code 终端中直接操作 DeerFlow：
bash
npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow功能：
- 发送消息并获取流式响应
- 选择执行模式：flash（快速）/ standard / pro（规划）/ ultra（子智能体）
- 健康检查、模型/技能/智能体列表查询
- 线程管理与对话历史
- 文件上传分析
快速启动路径
推荐方式：Docker（3步）
bash
git clone https://github.com/bytedance/deer-flow.git && cd deer-flow
make config # 生成本地配置
make docker-init # 拉取沙箱镜像（首次）
make docker-start # 启动服务
# 访问 http://localhost:2026本地开发（5步）
bash
make check # 检查 Node.js 22+, pnpm, uv, nginx
make install # 安装前后端依赖
make setup-sandbox # 可选：预拉沙箱镜像
make dev # 启动服务模型配置示例
yaml
models:
- name: gpt-4
display_name: GPT-4
use: langchain_openai:ChatOpenAI
model: gpt-4
api_key: $OPENAI_API_KEY # 推荐环境变量
max_tokens: 4096
temperature: 0.7
reasoning_effort: medium # Doubao/GPT-5 支持推荐模型特性： 长上下文（100k+）、推理能力、多模态、强工具调用。
嵌入式 Python 客户端
无需启动完整 HTTP 服务，直接内嵌使用：
python
from src.client import DeerFlowClient
client = DeerFlowClient()
# 同步调用
response = client.chat("分析这篇论文", thread_id="my-thread")
# 流式响应（LangGraph SSE 协议）
for event in client.stream("hello"):
if event.type == "messages-tuple" and event.data.get("type") == "ai":
print(event.data["content"])
# 管理接口（返回与 Gateway API 一致的 Schema）
client.list_models()
client.list_skills()
client.update_skill("web-search", enabled=True)
client.upload_files("thread-1", ["./report.pdf"])关键文档索引
| 文档 | 内容 |
|---|---|
CONTRIBUTING.md |
开发环境、工作流、贡献指南 |
backend/docs/CONFIGURATION.md |
配置详解（含沙箱模式） |
backend/CLAUDE.md |
技术架构总览 |
backend/README.md |
后端架构与 API 参考 |
backend/docs/MCP_SERVER.md |
MCP 服务器配置（含 OAuth） |
skills/public/claude-to-deerflow/SKILL.md |
Claude Code 技能完整 API |
技术依赖与致谢
核心依赖：
- LangChain --- LLM 交互与链式调用
- LangGraph --- 多智能体编排与工作流
关键贡献者：
- Daniel Walnut (
hetaoBackend) - Henry Li (
magiccube)
版本 2.0 的关键设计决策
| 决策 | 说明 |
|---|---|
| 渐进式技能加载 | 按需加载，非全量注入，保护上下文窗口 |
| 子智能体上下文隔离 | 防止注意力分散，确保任务专注 |
| 文件系统卸载中间结果 | 长任务中主动将结果写入文件，压缩上下文 |
| 本地优先的记忆存储 | 数据可控，隐私安全 |
| 模型无关设计 | 任何 OpenAI 兼容 API 均可接入 |
项目状态（截至 2026-03-10）
- 最新提交 ：
0409f8c--- 修复子智能体后台任务清理问题 - 提交总数：1,575 commits
- 未解决问题：208 issues
- 待处理 PR：31 pull requests
- 活跃分支：17 branches