## 项目概述

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

### 运行（Docker 推荐）

**开发模式**（热重载）：
```bash
make docker-init    # 拉取沙箱镜像（仅首次或镜像更新时）
make docker-start   # 启动服务
make docker-logs    # 查看日志
```

**生产模式**：
```bash
make up     # 构建镜像并启动所有生产服务
make down   # 停止并移除容器
```

访问 http://localhost:2026

### 本地开发

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

## 典型使用方法

### 通过 Web UI

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

### 通过嵌入式 Python 客户端

```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）

```bash
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 仓库：https://github.com/bytedance/deer-flow
- 官方网站：https://deerflow.tech
- 发布页面：https://github.com/bytedance/deer-flow/releases
- 文档：仓库内 `backend/docs/`、`docs/` 目录

## 信息来源和分析时间

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