bytedance / deer-flow

bytedance/deer-flow

open_in_new前往仓库

开源长周期超级代理框架，支持研究、编码与创作。集成沙箱、记忆、工具、技能、子代理及消息网关，可处理耗时数分钟至数小时的多层级任务。

项目概览

项目概述

DeerFlow（Deep Exploration and Efficient Research Flow）是字节跳动开源的一个超级智能体框架（SuperAgent Harness），旨在编排子智能体、记忆和沙箱环境，以完成从研究、编码到内容创作等多种复杂任务。它基于 LangGraph 和 LangChain 构建，提供开箱即用的文件系统、记忆、技能、沙箱感知执行以及规划与生成子智能体的能力。DeerFlow 2.0 是一次从零开始的重写，与 1.x 版本不共享代码，1.x 分支仍在维护。项目采用 MIT 许可证，主要使用 Python 和 TypeScript 开发。

核心功能

  • 技能与工具（Skills & Tools）：通过 Markdown 文件定义的结构化能力模块，支持渐进式加载，可扩展自定义技能，并支持 MCP 服务器和 Python 函数自定义工具。
  • 子智能体（Sub-Agents）：主智能体可动态生成子智能体，每个子智能体拥有独立上下文、工具和终止条件，支持并行执行和结果综合。
  • 沙箱与文件系统（Sandbox & File System）：每个任务拥有独立的执行环境，包含完整的文件系统视图（技能、工作区、上传、输出），支持安全地执行 shell 命令。
  • 上下文工程（Context Engineering）：通过子智能体上下文隔离、摘要压缩和严格工具调用恢复，管理长任务中的上下文窗口。
  • 长期记忆（Long-Term Memory）：跨会话持久化用户画像、偏好和知识，支持 DeerMem 默认后端及可选的 mem0、OpenViking 后端。
  • 会话目标（Session Goals）：通过 /goal 命令设置完成条件，智能体自动评估并持续工作直至目标达成。
  • 手动上下文压缩（Manual Context Compaction）：通过 /compact 命令总结旧上下文，保持对话清晰。
  • IM 渠道集成（IM Channels）：支持 Telegram、Slack、飞书、微信、企业微信、钉钉等消息应用，无需公网 IP。
  • 可观测性（Observability）：内置 LangSmith、Langfuse、Monocle 追踪集成。
  • 嵌入式 Python 客户端（Embedded Python Client）：可作为库直接使用，无需运行完整 HTTP 服务。
  • 定时任务（Scheduled Tasks）：支持一次性或 cron 调度。
  • 终端工作台（TUI）：提供终端原生界面，无需 Gateway 或前端。

适用与不适用场景

适用场景：

  • 深度研究：需要多步骤、长时程的信息收集与综合分析。
  • 复杂编码任务：需要规划、编写、测试和迭代代码。
  • 内容创作：生成报告、幻灯片、网页、图像、视频、播客等。
  • 自动化工作流：构建数据管道、生成仪表盘、自动化内容流程。
  • 需要持久记忆和个性化交互的智能体应用。
  • 需要沙箱隔离执行环境的安全敏感任务。

不适用场景：

  • 简单、单步操作：DeerFlow 的复杂编排可能过度设计。
  • 对实时性要求极高的场景：长时程任务可能耗时较长。
  • 资源受限环境：官方建议至少 4 vCPU、8 GB RAM，2 vCPU/4 GB 通常不足。
  • 需要严格实时交互的聊天机器人：虽然支持 IM，但主要面向任务型。
  • 对数据隐私要求极高且无法接受沙箱内代码执行的场景。

技术架构与依赖

  • 编程语言：Python 3.12+（后端）、Node.js 22+（前端）
  • 核心框架：LangGraph、LangChain
  • 后端：FastAPI（Gateway API）、SQLAlchemy（持久化）
  • 前端：Next.js（React）
  • 沙箱：支持本地执行、Docker 容器、Kubernetes（通过 provisioner）
  • 数据库：SQLite（默认）、PostgreSQL（生产推荐）
  • 消息渠道：Telegram Bot API、Slack Socket Mode、飞书 WebSocket、微信 iLink、企业微信 WebSocket、钉钉 Stream Push、Buzz Nostr
  • 可观测性：LangSmith、Langfuse、Monocle（OpenTelemetry）
  • 其他：MCP（Model Context Protocol）、Playwright（浏览器控制）、Redis（可选缓存/流桥）

安装与快速开始

配置

  1. 克隆仓库： 
    git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
  2. 运行设置向导： 
    make setup
    该向导会引导选择 LLM 提供商、可选网络搜索、执行/安全偏好（沙箱模式、bash 访问、文件写入工具），并生成 config.yaml 和 .env。

运行（Docker 推荐）

开发模式（热重载）：

make docker-init    # 拉取沙箱镜像（仅首次或镜像更新时）
make docker-start   # 启动服务
make docker-logs    # 查看日志

生产模式：

make up     # 构建镜像并启动所有生产服务
make down   # 停止并移除容器

访问 http://localhost:2026

本地开发

make check    # 检查 Node.js 22+、pnpm、uv、nginx
make install  # 安装前后端依赖
make dev      # 启动开发服务

典型使用方法

通过 Web UI

启动后访问 http://localhost:2026，创建会话并输入任务描述。DeerFlow 会自动规划、调用工具、生成子智能体并输出结果。

通过嵌入式 Python 客户端

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# 聊天
response = client.chat("Analyze this paper for me", thread_id="my-thread")

# 流式响应
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

通过 IM 渠道

配置好渠道后，直接在 Telegram、Slack 等应用中与 DeerFlow 对话，支持 /new、/status、/models、/memory、/help 等命令。

通过终端工作台（TUI）

deerflow --print "summarize this repo"   # 无头一次性回答

配置与部署要点

  • 配置文件：config.yaml（由 make setup 生成或手动编辑），环境变量存储在 .env。
  • 模型配置：支持 OpenAI 兼容 API、OpenRouter、vLLM、Codex CLI、Claude Code OAuth 等。
  • 沙箱模式：本地执行、Docker 执行、Kubernetes 执行（通过 provisioner）。
  • 数据库：生产环境推荐 PostgreSQL，支持 LangGraph checkpointer、Store 和 DeerFlow 应用数据共享。
  • 多工作进程：生产环境默认单 Gateway worker；多 worker 需要 PostgreSQL、Redis 流桥、心跳和数据库事件存储。
  • 安全：默认仅监听 127.0.0.1，部署到不可信环境需配置 IP 白名单、认证网关、网络隔离等。
  • 追踪：通过环境变量启用 LangSmith、Langfuse、Monocle。
  • MCP 服务器：支持 HTTP/SSE 和 stdio 类型，可配置 OAuth 令牌流。

限制、风险与许可证

  • 许可证：MIT License。
  • 安全风险：DeerFlow 具有系统命令执行、资源操作等高风险能力，默认设计为本地可信环境部署。不当部署可能引入未授权调用、合规和法律风险。
  • 资源需求：官方建议至少 4 vCPU、8 GB RAM，2 vCPU/4 GB 通常不足。
  • 沙箱信任边界：沙箱内代码可读取挂载的凭据，需谨慎处理。
  • 已知限制：
    • 标准模式（非 Gateway 模式）下摘要可能导致消息丢失（见文档）。
    • 多 Gateway 部署需要额外配置。
    • 某些功能（如定时任务）仍为 MVP 状态。
  • 版本：最新发布版本为 v2.0.0（2026-06-25）。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、CHANGELOG、CONTRIBUTING、docs 目录下的设计文档和实施计划。
  • 分析时间：2026-07-30（基于仓库内容推断，实际分析时间以系统时间为准）。