🦌 DeerFlow - 字节跳动开源的超级智能体框架

初步简介

GitHub: https://github.com/bytedance/deer-flow

📌 一句话介绍

DeerFlow 是一个开源的 SuperAgent Harness（超级智能体框架），能够研究、编码、创作——通过沙箱、记忆、工具、技能和子代理，处理从几分钟到几小时的复杂任务。

🎯 核心定位

DeerFlow 不是一个简单的聊天机器人框架，而是一个完整的智能体运行环境：

传统 Agent	DeerFlow
只有工具调用	有自己的沙箱计算机
无状态对话	长期记忆，越用越懂你
单一任务	子代理并行，复杂任务分解
需要手动组装	开箱即用，技能可扩展

🚀 主要功能

1. 技能系统 (Skills)

内置技能:
├── research/          # 深度研究
├── report-generation/ # 报告生成
├── slide-creation/    # PPT 制作
├── web-page/          # 网页生成
├── image-generation/  # 图片生成
└── video-generation/  # 视频生成

2. 沙箱执行环境

每个任务在隔离的 Docker 容器中运行
完整文件系统：上传文件、工作目录、输出目录
可执行 bash 命令、编写代码、查看图片

3. 子代理编排

主代理可动态创建子代理
子代理并行运行，互不干扰
结果汇聚，合成最终输出

4. 长期记忆

跨会话记住你的偏好和风格
本地存储，隐私可控
用得越多，越懂你

5. 上下文工程

自动压缩已完成任务
中间结果存文件系统
长任务不爆上下文

🛠️ 技术栈

组件	技术
框架基础	LangGraph + LangChain
沙箱	Docker / Kubernetes
模型支持	任意 OpenAI 兼容 API
MCP 支持	可扩展工具服务器

📦 快速开始

# 克隆仓库
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 生成配置
make config

# Docker 启动（推荐）
make docker-init
make docker-start

# 访问
# http://localhost:2026

🌟 亮点

开箱即用 - 内置丰富技能，无需手动组装
沙箱隔离 - 真正的执行环境，不只是对话
模型无关 - 支持任意 LLM（推荐长上下文模型）
高度可扩展 - 可添加自定义技能和 MCP 工具
MIT 开源 - 完全免费，可商用

📊 项目热度

2026年2月28日，DeerFlow 2.0 发布后登顶 GitHub Trending #1
字节跳动开源，社区活跃

简单说：DeerFlow 是一个"有自己电脑"的 AI 智能体框架，能真正干活，而不只是聊天。

DeerFlow Backend 源码分析报告

https://zhuanlan.zhihu.com/p/2011727923938346873

项目概述

DeerFlow 是一个基于 LangGraph 的 AI 超级代理系统，具有沙箱执行、持久化内存和可扩展工具集成功能。Backend 部分采用 Python 开发，使用 FastAPI 作为 API 网关，LangGraph 作为智能体运行时框架。

技术栈分析

核心依赖

LangGraph (1.0.6+) - 智能体框架和多智能体工作流编排
LangChain (1.2.3+) - LLM 抽象和工具系统
FastAPI (0.115.0+) - Gateway REST API
langchain-mcp-adapters - 模型上下文协议支持
agent-sandbox - 沙箱化代码执行
markitdown - 多格式文档转换

开发工具

uv - Python 包管理器
ruff - 代码格式化和检查
pytest - 测试框架

架构设计

三层架构

┌─────────────────┐
│    Nginx (2026)  │ ← 统一反向代理
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌─────────┐ ┌─────────┐
│LangGraph│ │ Gateway │
│ (2024)  │ │ (8001)  │
└─────────┘ └─────────┘

核心组件

1. LangGraph Server (端口 2024)

智能体运行时入口
线程状态管理
中间件链执行
SSE 流式响应

2. Gateway API (端口 8001)

FastAPI 应用
提供 RESTful 接口
管理模型、MCP、技能、内存等

3. 智能体系统

Lead Agent: 主智能体，通过 make_lead_agent() 创建
Middleware Chain: 9个中间件按顺序执行
Thread State: 扩展 LangGraph 的 AgentState

中间件链执行顺序

ThreadDataMiddleware - 创建线程隔离目录
UploadsMiddleware - 注入上传文件到上下文
SandboxMiddleware - 获取沙箱环境
SummarizationMiddleware - 上下文摘要（可选）
TodoListMiddleware - 任务跟踪（计划模式）
TitleMiddleware - 自动生成对话标题
MemoryMiddleware - 异步内存提取队列
ViewImageMiddleware - 视觉模型图像支持
ClarificationMiddleware - 处理澄清请求

关键模块分析

1. 沙箱系统 (Sandbox)

抽象接口: execute_command, read_file, write_file, list_dir
提供者: LocalSandboxProvider (文件系统) 和 AioSandboxProvider (Docker)
虚拟路径映射:
- /mnt/user-data/workspace → 线程工作空间
- /mnt/user-data/uploads → 上传文件目录
- /mnt/user-data/outputs → 输出文件目录
- /mnt/skills → 技能目录

2. 工具系统 (Tools)

内置工具: present_file, ask_clarification, view_image, task
沙箱工具: bash, ls, read_file, write_file, str_replace
社区工具: Tavily (网页搜索), Jina AI (网页抓取), Firecrawl (爬虫)
MCP 工具: 通过 Model Context Protocol 集成任意工具

3. MCP 集成 (Model Context Protocol)

支持 stdio、SSE、HTTP 三种传输方式
OAuth 认证支持
动态配置加载和缓存
多服务器并行管理

4. 技能系统 (Skills)

目录结构: skills/public/ 和 skills/custom/
技能格式: SKILL.md 文件包含元数据和指令
动态加载: 递归发现嵌套 SKILL.md 文件
状态管理: 通过 extensions_config.json 控制启用状态

5. 子代理系统 (Subagents)

内置代理: general-purpose (完整工具集) 和 bash (命令专家)
并发控制: 每轮最多 3 个子代理，15分钟超时
执行引擎: 后台线程池和状态跟踪
流程: 主代理调用 task() 工具 → 执行器在后台运行子代理 → 轮询完成状态 → 返回结果

6. 内存系统 (Memory)

自动提取: 分析对话获取用户上下文、事实和偏好
结构化存储: 用户上下文、历史记录和置信度评分的事实
去抖动更新: 批量更新以减少 LLM 调用
系统提示注入: 将重要事实和上下文注入智能体提示

7. 配置系统 (Configuration)

主配置: config.yaml - 模型、工具、沙箱等设置
扩展配置: extensions_config.json - MCP 服务器和技能状态
环境变量解析: 支持 $VARIABLE_NAME 格式
热重载: 配置更改无需重启应用

数据流分析

文件上传流程

客户端上传文件到 /api/threads/{id}/uploads
Gateway 接收并验证文件
存储到线程上传目录
如果是文档，通过 markitdown 转换为 Markdown
返回虚拟路径和访问 URL

请求处理流程

客户端发送消息到 /api/langgraph/threads/{id}/runs
Nginx 代理到 LangGraph Server
LangGraph 加载线程状态并执行中间件链
智能体处理消息并可能调用工具
工具通过沙箱执行
结果添加到消息中并通过 SSE 流式返回

安全设计

沙箱隔离

代理代码在沙箱边界内执行
本地沙箱：直接执行（仅开发）
Docker 沙箱：容器隔离（推荐生产环境）
文件操作中的路径遍历防护

API 安全

线程隔离：每个线程有独立的数据目录
文件验证：上传文件检查路径安全性
环境变量解析：密钥不存储在配置中

MCP 安全

每个 MCP 服务器在独立进程中运行
环境变量在运行时解析
服务器可独立启用/禁用

性能优化

缓存策略

MCP 工具缓存，基于文件修改时间失效
配置加载一次，文件更改时重新加载
技能在启动时解析一次，缓存在内存中

流式处理

SSE 用于实时响应流式传输
减少首次令牌时间
支持长操作的进度可见性

上下文管理

摘要中间件在接近限制时减少上下文
可配置触发器：令牌数、消息数或比例
保留最近消息同时摘要较旧消息

项目结构亮点

模块化设计

清晰的职责分离：agents、gateway、sandbox、tools 等
可插拔中间件系统
灵活的配置管理

扩展性

MCP 协议支持任意工具集成
技能系统支持领域特定工作流
子代理系统支持并行任务执行

开发友好

完整的文档和架构说明
详细的测试覆盖
开发工具链完善

总结

DeerFlow Backend 是一个设计精良的 AI 智能体平台，具有以下核心优势：

架构清晰：三层架构分离关注点，模块化设计
功能全面：沙箱执行、内存管理、工具集成、子代理等
扩展性强：MCP 协议、技能系统、可插拔中间件
安全可靠：沙箱隔离、线程隔离、安全配置
性能优化：缓存策略、流式处理、上下文管理

该项目适合需要构建复杂 AI 智能体系统的场景，特别是需要代码执行、文件操作和工具集成的应用。