今天在 GitHub Trending 上看到一个登顶的项目：DeerFlow 2.0，这是字节跳动开源的一款超级 Agent Harness，它把 Deep Research 的能力扩展成了一个可编排子 Agent、具备长期记忆、能在沙箱里执行任务的通用智能体运行时。

一、项目概述

DeerFlow（Deep Exploration and Efficient Research Flow）最早是一个 Deep Research 框架，2.0 版本是完全重写的超级 Agent Harness。它的核心定位不是又一个聊天机器人，而是给 Agent 提供“真正能干活的底层基础设施”：文件系统、记忆、技能、沙箱执行、子 Agent 编排，全部内置。

项目主要特点：

• 子 Agent 编排：主 Agent 可以动态创建多个子 Agent，分别处理不同任务，再聚合结果。
• 长期记忆：跨会话记住用户偏好、技术栈和常见工作流。
• 沙箱执行：支持本地、Docker 和 Kubernetes 三种沙箱模式，Agent 能真正读写文件、执行命令。
• 可扩展技能：通过 Markdown 形式的 SKILL.md 和 MCP 服务器扩展能力，按需加载。
• 多 IM 通道：原生支持 Telegram、Slack、飞书、企业微信、钉钉、微信等即时通讯接入。
• 模型无关：兼容 OpenAI、DeepSeek、Kimi、Doubao、Claude、Gemini 等任意 OpenAI-compatible API。

二、技术原理

2.1 架构设计

DeerFlow 2.0 基于 LangGraph + LangChain 构建，整体架构分为四层：

1. Gateway 层：提供 HTTP API 和 LangGraph 兼容接口，承载运行状态、SSE 流、IM 通道接入。
2. Agent 运行时：以 lead_agent 为入口，负责任务规划、子 Agent 调度、工具调用。
3. 技能与工具层：技能是 Markdown 描述的工作流，工具包含 web 搜索、文件操作、bash 执行、MCP 自定义工具。
4. 沙箱与文件层：每个任务拥有独立的文件系统视图，执行环境可按安全级别隔离。

2.2 核心技术栈与选型理由

2.3 关键设计模式

子 Agent 上下文隔离：每个子 Agent 运行在独立上下文中，无法看到主 Agent 或其他子 Agent 的内部状态。这保证了任务聚焦，也方便并行执行。

渐进式技能加载：技能不是一次性全部加载，而是根据当前任务按需读取 SKILL.md，从而控制上下文窗口大小。

严格工具调用恢复：当模型或中间件中断工具调用循环时，DeerFlow 会清理未完成的工具调用元数据，并注入占位结果，避免 OpenAI 兼容模型因历史记录格式错误而崩溃。

2.4 数据流分析

一个典型任务的数据流如下：

1. 用户通过 Web UI 或 IM 发送请求。
2. Gateway 创建 thread 和 run，调用 lead_agent。
3. lead_agent 规划任务，必要时拆分为子 Agent。
4. 子 Agent 在沙箱中执行文件读写、网络搜索、代码运行等操作。
5. 结果回流到主 Agent，进行汇总、生成报告或输出文件。
6. 最终响应通过 SSE 或 IM 通道返回给用户。

三、安装与快速开始

3.1 环境要求

• Python 3.12+
• Node.js 22+
• pnpm、uv、nginx
• 推荐 Linux + Docker 作为长期部署环境；macOS/Windows 适合本地开发评估

3.2 安装步骤

克隆仓库并运行交互式配置向导：

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup

make setup 会引导你选择 LLM 提供商、配置搜索、沙箱模式、bash 权限等，并生成 config.yaml 和 .env。

如果你偏好手动配置，可以运行：

3.3 最简运行示例

开发模式启动：

make check       # 检查依赖
make install     # 安装前后端依赖
make dev         # 启动开发服务

然后访问 http://localhost:2026 即可使用。

Docker 生产部署：

make up    # 构建镜像并启动
make down  # 停止并移除容器

四、使用方法与实战

4.1 基础用法

DeerFlow 支持通过 Web UI、IM 通道或嵌入式 Python 客户端调用。以下是用 Python 客户端聊天的示例：

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

for event in client.stream("帮我分析这篇论文"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

4.2 进阶用法

自定义模型配置：在 config.yaml 中添加任意 OpenAI-compatible 模型，例如 OpenRouter 或 vLLM：

models:
  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

接入 IM 通道：以 Telegram 为例，只需在 .env 中设置 TELEGRAM_BOT_TOKEN，并在 config.yaml 中启用即可：

channels:
  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []

4.3 实际项目示例

DeerFlow 内置了多种技能，可以完成：

• 深度研究并生成报告
• 自动生成幻灯片
• 构建网页和数据看板
• 生成图片和视频
• 通过 /claude-to-deerflow 技能与 Claude Code 联动

这些技能都以 Markdown 形式定义，放在 /mnt/skills/public/ 目录下，用户可以在 /mnt/skills/custom/ 中添加自己的技能。

五、常见问题与解决方案

5.1 安装失败

问题：make dev 提示找不到 config.yaml。

解决：先运行 make setup 或 make config 生成配置文件，再启动服务。

5.2 运行时错误

问题：Linux 上 Docker 命令报 permission denied。

解决：将当前用户加入 docker 组并重新登录，参考 CONTRIBUTING.md 中的完整修复步骤。

5.3 性能问题

问题：本地运行卡顿，CPU/内存占满。

解决：DeerFlow 官方给出的起步配置是 4 vCPU/8 GB RAM，推荐 8 vCPU/16 GB RAM。如果资源不足，可减少并发任务或升级到更高配置。

5.4 兼容性与安全

问题：想部署到公网服务器。

解决：DeerFlow 默认设计为本地可信环境（127.0.0.1）运行。若需跨网络部署，必须配置 IP 白名单、强认证反向代理、网络隔离等安全措施，避免被未授权访问后执行高危操作。

六、总结

DeerFlow 2.0 代表了开源 Agent 基础设施的一个重要方向：不再把 Agent 当作“会聊天的模型”，而是给它配齐文件系统、记忆、沙箱和子 Agent 团队，让它真正完成复杂工作。对于希望构建私有、可扩展、可落地的 AI Agent 平台的开发者来说，DeerFlow 是一个值得深入研究的标杆项目。