DeerFlow 源码剖析-极简笔记

DeerFlow (Deep Exploration and Efficient Research Flow) — 字节跳动开源的 AI 超级智能体框架

仓库地址: https://github.com/bytedance/deer-flow

官方文档: https://deerflow.tech

许可证: MIT

Stars: ⭐ 69,600+

Forks: 9,300+

主要语言: Python / TypeScript

创建时间: 2025-05-07

最新版本: 2.0（完全重写，与 v1 无代码共享）

1. 项目概述

DeerFlow 是一个开源的超级智能体框架 (Super Agent Harness)，能够编排子 Agent、记忆和沙箱来完成几乎任何任务，由可扩展的技能 (Skills) 驱动。

核心特性

特性	说明
子 Agent 系统	支持任务分解和并行执行，内置 general-purpose 和 bash 子 Agent
沙箱执行	本地执行、Docker 容器、Kubernetes Pod 三种沙箱模式
持久记忆	长期记忆系统，跨会话保留上下文
技能系统	20+ 预置技能，支持动态安装和管理自定义技能
MCP 协议	原生支持 Model Context Protocol（stdio/SSE/HTTP）
多模型支持	OpenAI、Claude、DeepSeek、Gemini、vLLM、Mindie 等
多渠道集成	飞书、Slack、Telegram、Discord、钉钉、微信、企业微信
链路追踪	LangSmith / Langfuse 双链路追踪
Claude Code 集成	支持 Claude Code 作为编码子 Agent

2.0 版本说明

DeerFlow 2.0 是完全重写的版本，与 v1 无代码共享。v1 的原始 Deep Research 框架在 1.x 分支维护。

2. 整体架构

┌─────────────────────────────────────────────────────────────┐
│                      用户 / IM 渠道                          │
│   (Web UI / 飞书 / Slack / Telegram / Discord / 钉钉)       │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   Nginx 反向代理 (:2026)                      │
│   /api/langgraph/* → Gateway (LangGraph 兼容)               │
│   /api/*          → Gateway (原生路由)                        │
│   /*              → Frontend (Next.js)                       │
└──────┬──────────────────────────────────┬──────────────────┘
       │                                  │
       ▼                                  ▼
┌──────────────────────┐    ┌──────────────────────────────────┐
│   FastAPI Gateway   │    │      Next.js Frontend            │
│   (:8001)           │    │   (React 19 + TypeScript)         │
│                     │    │                                  │
│ ┌─────────────────┐  │    │  App Router / Shadcn UI           │
│ │ 认证/授权/CSRF │  │    │  React Query / CodeMirror         │
│ └────────┬────────┘  │    │  Nextra 文档站 / i18n             │
│          │           │    └──────────────────────────────────┘
│ ┌────────▼────────┐  │
│ │  API 路由层      │  │
│ │  threads/runs/  │  │
│ │  agents/skills/ │  │
│ │  memory/mcp/    │  │
│ │  uploads/auth/   │  │
│ └────────┬────────┘  │
│          │           │
│ ┌────────▼────────┐  │
│ │  服务编排层      │  │
│ │  (services.py)  │  │
│ └────────┬────────┘  │
└──────────┼───────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│              DeerFlow 核心引擎 (deerflow package)             │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ Agent 系统 │  │ 运行时引擎 │  │ 工具系统  │  │ 技能系统  │    │
│  │ LangGraph │  │ 执行/流式 │  │ 内置+MCP  │  │ 安装/管理 │    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
│       │              │              │              │          │
│  ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐    │
│  │ 子 Agent  │  │ 检查点/  │  │ 社区工具  │  │ 安全扫描  │    │
│  │ 委派系统  │  │ 持久化   │  │ 搜索/抓取 │  │ 验证策略  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ 沙箱系统  │  │ 模型工厂  │  │ 安全护栏  │  │ 链路追踪  │    │
│  │ 本地/Docker│  │ 多LLM支持│  │ 授权检查  │  │ Smith/   │    │
│  │ /K8s Pod  │  │ 动态加载  │  │ 白名单   │  │ Fuse     │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                    基础设施层                                  │
│  SQLite / PostgreSQL │ Docker │ Kubernetes │ LangSmith/Fuse  │
└─────────────────────────────────────────────────────────────┘

架构设计要点

统一入口: Nginx 在端口 2026 统一代理前端和后端，同源部署无 CORS 问题
网关内嵌运行时: Gateway API 内嵌 Agent 运行时，无需独立的 LangGraph Server
LangGraph 兼容: Gateway 同时提供 LangGraph 兼容 API (/api/langgraph/*)
模块化核心: deerflow 包通过 reflection 模块实现动态类加载，支持运行时扩展
DooD 模式: Docker 沙箱使用 Docker-outside-of-Docker 模式，Gateway 容器挂载宿主机 Docker Socket

3. 项目目录结构

deer-flow/                                    # 项目根目录
│
├── .agent/                                   # AI Agent 配置
│   └── skills/smoke-test/                    #   冒烟测试技能
│
├── .github/                                  # GitHub 配置
│   ├── ISSUE_TEMPLATE/                       #   Issue 模板
│   ├── workflows/                            #   CI/CD 工作流
│   │   ├── backend-unit-tests.yml           #     后端单元测试
│   │   ├── backend-blocking-io-tests.yml    #     后端阻塞 IO 测试
│   │   ├── frontend-unit-tests.yml          #     前端单元测试
│   │   ├── e2e-tests.yml                    #     端到端测试
│   │   ├── lint-check.yml                   #     代码检查
│   │   └── container.yaml                   #     容器发布
│   └── copilot-instructions.md              #   GitHub Copilot 指令
│
├── backend/                                  # ===== 后端 =====
│   ├── app/                                  #   应用入口层
│   │   ├── channels/                         #     IM 渠道桥接
│   │   │   ├── base.py                       #       渠道基类
│   │   │   ├── manager.py                    #       渠道管理器
│   │   │   ├── service.py                    #       渠道服务层
│   │   │   ├── message_bus.py                #       消息总线
│   │   │   ├── feishu.py                     #       飞书渠道
│   │   │   ├── slack.py                      #       Slack 渠道
│   │   │   ├── telegram.py                   #       Telegram 渠道
│   │   │   ├── discord.py                    #       Discord 渠道
│   │   │   ├── dingtalk.py                   #       钉钉渠道
│   │   │   ├── wechat.py                     #       微信渠道
│   │   │   └── wecom.py                      #       企业微信渠道
│   │   │
│   │   └── gateway/                          #     FastAPI 网关
│   │       ├── app.py                        #       应用初始化
│   │       ├── services.py                   #       服务编排
│   │       ├── deps.py                       #       依赖注入
│   │       ├── auth_middleware.py            #       认证中间件
│   │       ├── csrf_middleware.py            #       CSRF 防护
│   │       ├── authz.py                      #       授权逻辑
│   │       ├── auth/                         #       认证模块
│   │       │   ├── jwt.py                    #         JWT 令牌
│   │       │   ├── password.py               #         密码哈希
│   │       │   ├── local_provider.py         #         本地认证
│   │       │   └── providers.py              #         认证提供者接口
│   │       └── routers/                      #       API 路由
│   │           ├── threads.py                #         线程 CRUD
│   │           ├── thread_runs.py            #         线程运行管理
│   │           ├── agents.py                 #         Agent 管理
│   │           ├── auth.py                   #         认证端点
│   │           ├── skills.py                 #         技能管理
│   │           ├── memory.py                 #         记忆管理
│   │           ├── uploads.py                #         文件上传
│   │           ├── mcp.py                     #         MCP 管理
│   │           ├── artifacts.py              #         制品管理
│   │           ├── models.py                 #         模型管理
│   │           └── assistants_compat.py       #         OpenAI 兼容层
│   │
│   ├── packages/                             #   Python 包
│   │   └── harness/                           #     核心包 (deerflow-harness)
│   │       └── deerflow/                     #     ===== deerflow 核心包 =====
│   │           ├── client.py                 #       核心客户端 (55KB)
│   │           ├── agents/                   #       Agent 系统
│   │           │   ├── factory.py            #         Agent 工厂
│   │           │   ├── features.py           #         运行时特性
│   │           │   ├── thread_state.py       #         线程状态
│   │           │   ├── lead_agent/            #         主 Agent
│   │           │   ├── middlewares/           #         中间件 (9个)
│   │           │   └── memory/               #         记忆子系统
│   │           ├── community/                 #       社区工具集成
│   │           │   ├── tavily/                #         Tavily 搜索
│   │           │   ├── jina_ai/              #         Jina AI
│   │           │   ├── firecrawl/            #         Firecrawl 抓取
│   │           │   ├── ddg_search/          #         DuckDuckGo 搜索
│   │           │   ├── serper/              #         Google 搜索
│   │           │   ├── exa/                 #         Exa AI 搜索
│   │           │   ├── infoquest/           #         InfoQuest
│   │           │   ├── image_search/        #         图片搜索
│   │           │   └── aio_sandbox/        #         异步沙箱
│   │           ├── config/                  #       配置系统
│   │           │   ├── app_config.py        #         主配置 (20KB)
│   │           │   ├── paths.py             #         路径配置 (14KB)
│   │           │   ├── extensions_config.py #         扩展配置 (11KB)
│   │           │   ├── model_config.py      #         模型配置
│   │           │   ├── database_config.py   #         数据库配置
│   │           │   ├── memory_config.py     #         记忆配置
│   │           │   └── guardrails_config.py #         护栏配置
│   │           ├── guardrails/              #       安全护栏
│   │           ├── mcp/                      #       MCP 协议集成
│   │           ├── models/                  #       模型工厂
│   │           │   ├── factory.py           #         模型工厂
│   │           │   ├── claude_provider.py    #         Claude 支持
│   │           │   ├── openai_codex_provider.py #     Codex 支持
│   │           │   ├── vllm_provider.py      #         vLLM 支持
│   │           │   ├── mindie_provider.py    #         Mindie 支持
│   │           │   ├── patched_openai.py    #         OpenAI 补丁
│   │           │   ├── patched_deepseek.py  #         DeepSeek 补丁
│   │           │   └── credential_loader.py #         凭证加载
│   │           ├── persistence/             #       数据持久化
│   │           │   ├── engine.py             #         数据库引擎
│   │           │   ├── models/              #         ORM 模型
│   │           │   ├── run/                  #         运行记录
│   │           │   ├── thread_meta/         #         线程元数据
│   │           │   ├── user/                 #         用户数据
│   │           │   ├── feedback/             #         反馈数据
│   │           │   └── migrations/           #         数据库迁移
│   │           ├── reflection/              #       动态模块加载
│   │           ├── runtime/                  #       运行时环境
│   │           │   ├── runs/                 #         运行管理
│   │           │   ├── checkpointer/         #         检查点
│   │           │   ├── store/               #         BaseStore
│   │           │   ├── stream_bridge/        #         流式桥接
│   │           │   ├── journal.py            #         运行日志 (23KB)
│   │           │   └── events/               #         事件系统
│   │           ├── sandbox/                  #       沙箱系统
│   │           │   ├── sandbox.py             #         沙箱接口
│   │           │   ├── tools.py              #         沙箱工具 (69KB)
│   │           │   ├── middleware.py         #         沙箱中间件
│   │           │   ├── security.py           #         安全策略
│   │           │   └── local/               #         本地沙箱
│   │           ├── skills/                   #       技能系统
│   │           │   ├── installer.py          #         技能安装器
│   │           │   ├── parser.py             #         技能解析
│   │           │   ├── security_scanner.py    #         安全扫描
│   │           │   ├── validation.py         #         技能验证
│   │           │   └── storage/              #         技能存储
│   │           ├── subagents/                #       子 Agent 系统
│   │           │   ├── executor.py            #         执行引擎 (36KB)
│   │           │   ├── registry.py           #         注册表
│   │           │   ├── config.py             #         子 Agent 配置
│   │           │   └── builtins/             #         内置子 Agent
│   │           ├── tools/                    #       工具系统
│   │           │   ├── tools.py              #         工具注册
│   │           │   ├── skill_manage_tool.py  #         技能管理工具
│   │           │   └── builtins/             #         内置工具
│   │           ├── tracing/                   #       链路追踪
│   │           └── uploads/                   #       文件上传
│   │
│   ├── docs/                                  #   后端文档
│   ├── scripts/                               #   后端脚本
│   ├── tests/                                 #   测试套件
│   ├── pyproject.toml                         #   Python 依赖
│   ├── langgraph.json                         #   LangGraph 图注册
│   ├── Dockerfile                              #   后端容器
│   └── debug.py                               #   调试工具
│
├── frontend/                                  # ===== 前端 =====
│   ├── src/
│   │   ├── app/                               #   Next.js App Router
│   │   │   ├── (auth)/                        #     认证路由组
│   │   │   ├── [lang]/                        #     国际化路由
│   │   │   ├── workspace/                     #     工作区页面
│   │   │   ├── blog/                          #     博客页面
│   │   │   └── api/                           #     API 路由
│   │   ├── components/                         #   React 组件
│   │   │   ├── ui/                            #     通用 UI (Shadcn)
│   │   │   ├── workspace/                     #     工作区组件
│   │   │   ├── ai-elements/                   #     AI 交互组件
│   │   │   └── landing/                       #     落地页组件
│   │   ├── core/                              #   核心业务逻辑
│   │   │   ├── api/                           #     API 客户端
│   │   │   ├── agents/                        #     Agent 管理
│   │   │   ├── artifacts/                     #     产物管理
│   │   │   ├── auth/                          #     认证
│   │   │   ├── i18n/                          #     国际化
│   │   │   ├── mcp/                           #     MCP 集成
│   │   │   ├── memory/                        #     记忆管理
│   │   │   ├── messages/                      #     消息处理
│   │   │   ├── models/                        #     数据模型
│   │   │   ├── settings/                      #     设置管理
│   │   │   ├── skills/                         #     技能管理
│   │   │   ├── streamdown/                    #     流式 Markdown
│   │   │   └── tasks/                         #     任务管理
│   │   ├── hooks/                              #   自定义 Hooks
│   │   ├── lib/                               #   工具库
│   │   ├── styles/                            #   全局样式
│   │   ├── typings/                            #   TypeScript 类型
│   │   └── content/                            #   Nextra 文档 (MDX)
│   ├── tests/
│   │   ├── e2e/                               #   E2E 测试 (Playwright)
│   │   └── unit/                              #   单元测试 (Vitest)
│   ├── package.json                            #   Node.js 依赖
│   └── Dockerfile                              #   前端容器
│
├── docker/                                     # ===== Docker 部署 =====
│   ├── docker-compose.yaml                     #   生产环境编排
│   ├── docker-compose-dev.yaml                 #   开发环境编排
│   ├── dev-entrypoint.sh                       #   开发入口脚本
│   ├── nginx/                                  #   Nginx 反向代理配置
│   │   └── nginx.conf                          #     Nginx 配置模板
│   └── provisioner/                            #   K8s 沙箱供给器
│       └── Dockerfile
│
├── scripts/                                    # ===== 项目级脚本 =====
│   ├── setup_wizard.py                         #   交互式安装向导
│   ├── doctor.py                               #   环境诊断
│   ├── deploy.sh                               #   部署脚本
│   ├── serve.sh                                #   服务启动脚本
│   ├── docker.sh                               #   Docker 操作脚本
│   ├── configure.py                            #   配置引导
│   └── check.py                                #   依赖检查
│
├── skills/public/                              # ===== 公共技能库 =====
│   ├── deep-research/                          #   深度研究
│   ├── data-analysis/                          #   数据分析
│   ├── code-documentation/                     #   代码文档生成
│   ├── ppt-generation/                         #   PPT 生成
│   ├── podcast-generation/                     #   播客生成
│   ├── chart-visualization/                    #   图表可视化
│   ├── frontend-design/                        #   前端设计
│   ├── image-generation/                       #   图片生成
│   ├── newsletter-generation/                   #   新闻简报生成
│   ├── academic-paper-review/                  #   学术论文评审
│   ├── systematic-literature-review/            #   系统性文献综述
│   ├── consulting-analysis/                    #   咨询分析
│   ├── github-deep-research/                   #   GitHub 深度研究
│   ├── skill-creator/                          #   技能创建器（元技能）
│   ├── find-skills/                            #   技能发现
│   ├── bootstrap/                              #   项目引导
│   ├── claude-to-deerflow/                     #   Claude 迁移助手
│   ├── surprise-me/                            #   随机惊喜
│   └── vercel-deploy-claimable/                #   Vercel 部署
│
├── docs/                                       # ===== 项目文档 =====
├── config.example.yaml                         # 配置示例
├── extensions_config.example.json               # 扩展配置示例
├── .env.example                                # 环境变量示例
├── Makefile                                    # 项目级 Makefile
├── README.md                                   # 项目主文档
├── README_zh.md                                # 中文文档
├── Install.md                                  # 安装指南
├── CONTRIBUTING.md                             # 贡献指南
├── LICENSE                                     # MIT 许可证
└── SECURITY.md                                 # 安全策略

4. 主要模块职责

4.1 核心引擎 (deerflow)

路径: backend/packages/harness/deerflow/

核心引擎是 DeerFlow 的"大脑"，包含 Agent 编排、工具管理、沙箱执行、记忆系统等全部核心逻辑。采用 LangGraph 作为 Agent 编排框架。

子模块	职责
`agents/`	Agent 定义与工厂，LangGraph 图构建，中间件管道
`runtime/`	Agent 执行、流式传输、检查点、运行管理
`models/`	多 LLM 提供者支持（OpenAI、Claude、DeepSeek、vLLM 等）
`tools/`	工具注册、内置工具、技能管理工具
`sandbox/`	安全代码执行环境（本地/Docker/K8s）
`skills/`	技能安装、解析、验证、安全扫描
`subagents/`	子 Agent 委派与执行引擎
`community/`	第三方搜索和信息获取服务集成
`mcp/`	Model Context Protocol 协议集成
`config/`	统一配置管理（YAML + 环境变量）
`guardrails/`	工具调用安全检查与授权
`persistence/`	SQLAlchemy 2.0 异步 ORM 数据持久化
`tracing/`	LangSmith / Langfuse 链路追踪
`uploads/`	文件上传管理与路径安全校验
`reflection/`	运行时动态类/变量解析
`client.py`	核心客户端，封装 LangGraph SDK 交互

4.2 API 网关 (gateway)

路径: backend/app/gateway/

基于 FastAPI 的 API 网关，内嵌 Agent 运行时，提供 REST API 和 LangGraph 兼容 API。

子模块	职责
`app.py`	FastAPI 应用创建与生命周期管理
`services.py`	业务服务编排（模型/MCP/技能/记忆等）
`deps.py`	FastAPI 依赖注入
`auth/`	认证系统（JWT + bcrypt + 本地认证）
`auth_middleware.py`	认证中间件
`csrf_middleware.py`	CSRF 防护中间件
`authz.py`	授权逻辑
`routers/`	API 路由（threads/runs/agents/skills/memory 等）

4.3 IM 渠道层 (channels)

路径: backend/app/channels/

将外部 IM 平台桥接到 DeerFlow Agent，通过统一的消息总线和管理器协调。

渠道	文件	说明
飞书	`feishu.py` (32KB)	飞书/Lark 机器人集成
钉钉	`dingtalk.py` (30KB)	钉钉流式消息集成
微信	`wechat.py` (53KB)	微信公众号集成
企业微信	`wecom.py` (14KB)	企业微信 AI 机器人
Slack	`slack.py` (9KB)	Slack 集成
Telegram	`telegram.py` (13KB)	Telegram Bot 集成
Discord	`discord.py` (24KB)	Discord Bot 集成

4.4 前端应用 (frontend)

路径: frontend/

基于 Next.js 16 + React 19 的全栈前端应用，使用 App Router 架构。

子模块	职责
`app/`	Next.js App Router 路由（工作区、博客、API）
`components/`	React UI 组件（Shadcn UI + Radix UI）
`core/`	核心业务逻辑（API 客户端、Agent 管理、消息处理等）
`hooks/`	自定义 React Hooks
`lib/`	工具函数库
`content/`	Nextra 文档内容 (MDX)

4.5 部署层 (docker)

路径: docker/

Docker 容器化部署配置，包含 Nginx 反向代理和多服务编排。

文件	说明
`docker-compose.yaml`	生产环境编排（nginx + frontend + gateway + provisioner）
`docker-compose-dev.yaml`	开发环境编排（热重载、源码挂载）
`nginx/nginx.conf`	Nginx 反向代理配置
`provisioner/`	Kubernetes 沙箱容器供给器

4.6 技能系统 (skills)

路径: skills/public/

预置的 20 个公共技能，每个技能是一个独立的功能包，包含 SKILL.md 定义文件。

5. 关键类与函数说明

5.1 Agent 系统

路径: backend/packages/harness/deerflow/agents/

类/函数	文件	说明
`create_deerflow_agent()`	`factory.py` (15KB)	核心工厂函数，创建完整的 DeerFlow Agent，组装 LangGraph 图、中间件管道、工具集
`make_lead_agent()`	`lead_agent/`	构建主导 Agent，包含 prompt 模板和特性配置
`RuntimeFeatures`	`features.py`	运行时特性标志系统，控制 Agent 行为（如是否启用记忆、沙箱等）
`ThreadState`	`thread_state.py`	线程状态 TypedDict，定义 Agent 执行过程中的状态结构
`SandboxState`	`thread_state.py`	沙箱状态 TypedDict，跟踪沙箱执行状态
`Next` / `Prev`	—	Agent 图节点路由枚举，控制 LangGraph 图的流转方向

中间件 (middlewares/):

中间件	说明
`ThreadDataMiddleware`	线程数据管理
`UploadsMiddleware`	文件上传处理
`SandboxMiddleware`	沙箱生命周期管理
`SummarizationMiddleware`	对话摘要
`TodoListMiddleware`	任务列表跟踪
`TitleMiddleware`	对话标题生成
`MemoryMiddleware`	记忆提取与注入
`ViewImageMiddleware`	图片查看
`ClarificationMiddleware`	澄清请求处理

5.2 运行时引擎

路径: backend/packages/harness/deerflow/runtime/

类/函数	文件	说明
`run_agent()`	—	核心执行函数，启动 Agent 运行
`RunManager`	`runs/`	运行管理器，协调 Agent 生命周期
`RunContext`	`runs/`	运行上下文，封装单次执行的配置和状态
`RunRecord`	`runs/`	运行记录，持久化运行元数据
`RunStatus`	—	运行状态枚举
`StreamBridge`	`stream_bridge/`	流式传输桥接，将 LangGraph 事件转换为客户端可消费的流
`MemoryStreamBridge`	`stream_bridge/`	记忆流式桥接
`StreamEvent`	—	流式事件类型定义
`make_checkpointer()`	`checkpointer/`	创建 LangGraph 检查点（状态持久化）
`make_store()`	`store/`	创建 BaseStore 实例
`journal.py` (23KB)	—	运行日志/记录系统

5.3 模型提供者

路径: backend/packages/harness/deerflow/models/

类/函数	文件	说明
`create_chat_model()`	`factory.py` (8KB)	模型工厂函数，根据配置动态创建 LLM 实例
`ClaudeChatModel`	`claude_provider.py` (14KB)	Anthropic Claude 模型适配（支持 Claude Code OAuth）
`CodexChatModel`	`openai_codex_provider.py` (18KB)	OpenAI Codex CLI 模型适配
`VllmChatModel`	`vllm_provider.py` (10KB)	vLLM 自部署模型适配（支持 Qwen 推理模型）
`MindieChatModel`	`mindie_provider.py` (10KB)	华为 Mindie 模型适配
`PatchedOpenAI`	`patched_openai.py`	OpenAI 兼容 API 补丁封装
`PatchedDeepSeek`	`patched_deepseek.py`	DeepSeek 模型补丁封装
`PatchedMiniMax`	`patched_minimax.py`	MiniMax 模型补丁封装
`load_credentials()`	`credential_loader.py` (7KB)	模型凭证加载器，支持多种凭证来源

5.4 工具系统

路径: backend/packages/harness/deerflow/tools/

类/函数	文件	说明
`get_available_tools()`	`tools.py` (10KB)	获取所有可用工具列表（内置 + MCP + 技能）
`SkillManageTool`	`skill_manage_tool.py` (10KB)	技能管理工具（安装/卸载/列表/搜索）

内置工具 (builtins/):

工具	说明
`present_files`	展示文件内容
`ask_clarification`	向用户请求澄清
`skill_manage`	技能管理操作

5.5 沙箱系统

路径: backend/packages/harness/deerflow/sandbox/

类/函数	文件	说明
`Sandbox`	`sandbox.py`	沙箱抽象基类，定义安全代码执行接口
`SandboxProvider`	`sandbox_provider.py`	沙箱提供者抽象，支持多种后端
`get_sandbox_provider()`	`sandbox_provider.py`	工厂函数，根据配置返回沙箱提供者
`tools.py` (69KB)	—	最大文件，沙箱内所有可用工具：bash 执行、文件操作、代码搜索等

沙箱工具集:

bash — Shell 命令执行
ls — 目录列表
read_file — 文件读取
write_file — 文件写入
str_replace — 字符串替换
搜索功能 — 代码/文件搜索

沙箱模式:

模式	说明
本地执行	直接在宿主机运行（开发用）
Docker 容器	在隔离 Docker 容器中运行
Kubernetes Pod	通过 provisioner 服务在 K8s Pod 中运行

5.6 MCP 协议集成

路径: backend/packages/harness/deerflow/mcp/

类/函数	文件	说明
`build_server_params()`	`client.py`	构建 MCP 服务器连接参数
`build_servers_config()`	`client.py`	构建 MCP 服务器配置
`get_mcp_tools()`	`tools.py` (12KB)	获取 MCP 工具列表
`initialize_mcp_tools()`	`cache.py` (5KB)	初始化 MCP 工具（含缓存）
`get_cached_mcp_tools()`	`cache.py`	获取缓存的 MCP 工具
`reset_mcp_tools_cache()`	`cache.py`	重置 MCP 工具缓存
`SessionPool`	`session_pool.py` (7KB)	MCP 会话池管理
MCP OAuth	`oauth.py` (5KB)	OAuth 认证支持

5.7 配置管理

路径: backend/packages/harness/deerflow/config/

类/函数	文件	说明
`get_app_config()`	`app_config.py` (20KB)	获取全局应用配置
`get_paths()` / `Paths`	`paths.py` (14KB)	获取运行时路径配置
`get_memory_config()`	`memory_config.py`	获取记忆系统配置
`get_extensions_config()`	`extensions_config.py` (11KB)	获取扩展配置
`get_tracing_config()`	—	获取链路追踪配置
`is_tracing_enabled()`	—	检查追踪是否启用
`AppConfig`	`app_config.py`	主配置数据类
`MemoryConfig`	`memory_config.py`	记忆配置数据类
`ExtensionsConfig`	`extensions_config.py`	扩展配置数据类
`LoopDetectionConfig`	`loop_detection_config.py`	循环检测配置
`SkillsConfig`	—	技能配置

5.8 安全护栏

路径: backend/packages/harness/deerflow/guardrails/

类/函数	文件	说明
`GuardrailProvider`	`provider.py`	护栏提供者抽象基类
`GuardrailMiddleware`	`middleware.py` (4KB)	护栏中间件，在工具调用前执行安全检查
`GuardrailDecision`	—	护栏决策模型（允许/拒绝/修改）
`GuardrailReason`	—	护栏决策原因
`GuardrailRequest`	—	护栏请求数据
`AllowlistProvider`	`builtin.py`	内置白名单提供者

5.9 持久化层

路径: backend/packages/harness/deerflow/persistence/

基于 SQLAlchemy 2.0 异步 ORM，与 LangGraph 检查点系统完全独立。

类/函数	文件	说明
`init_engine()`	`engine.py` (7KB)	初始化数据库引擎
`get_engine()`	`engine.py`	获取数据库引擎实例
`get_session_factory()`	`engine.py`	获取会话工厂
`close_engine()`	`engine.py`	关闭数据库连接

ORM 模型:

子模块	说明
`models/`	ORM 基础模型定义
`run/`	运行记录持久化
`thread_meta/`	线程元数据持久化
`user/`	用户数据持久化
`feedback/`	反馈数据持久化
`migrations/`	数据库迁移脚本

5.10 链路追踪

路径: backend/packages/harness/deerflow/tracing/

类/函数	文件	说明
`build_tracing_callbacks()`	`factory.py`	构建追踪回调（LangSmith/Langfuse）
`build_langfuse_trace_metadata()`	`metadata.py`	构建 LangFuse 追踪元数据
`inject_langfuse_metadata()`	`metadata.py`	注入 LangFuse 元数据到配置

6. 依赖关系

6.1 后端依赖 (Python)

核心依赖

依赖包	版本要求	用途
`deerflow-harness`	workspace	内部核心包（`packages/harness`）
`fastapi`	>=0.115.0	Web 框架
`uvicorn[standard]`	>=0.34.0	ASGI 服务器
`httpx`	>=0.28.0	HTTP 客户端
`python-multipart`	>=0.0.27	文件上传支持
`sse-starlette`	>=2.1.0	Server-Sent Events
`langgraph-sdk`	>=0.1.51	LangGraph SDK（Agent 编排核心）
`lark-oapi`	>=1.4.0	飞书 SDK
`slack-sdk`	>=3.33.0	Slack SDK
`python-telegram-bot`	>=21.0	Telegram SDK
`dingtalk-stream`	>=0.24.3	钉钉 SDK
`wecom-aibot-python-sdk`	>=0.1.6	企业微信 SDK
`markdown-to-mrkdwn`	>=0.3.1	Markdown → Slack 格式转换
`bcrypt`	>=4.0.0	密码哈希
`pyjwt`	>=2.9.0	JWT 认证
`email-validator`	>=2.0.0	邮箱验证

可选依赖

可选组	依赖包	用途
`postgres`	`deerflow-harness[postgres]`	PostgreSQL 数据库
`discord`	`discord.py>=2.7.0`	Discord 集成

开发依赖

依赖包	用途
`pytest` + `pytest-asyncio`	单元测试
`ruff`	代码检查和格式化
`prompt-toolkit`	交互式命令行

6.2 前端依赖 (Node.js)

核心框架

依赖包	版本	用途
`next`	^16.2.6	Next.js 全栈框架 (App Router)
`react`	^19.0.0	React UI 库
`react-dom`	^19.0.0	React DOM

AI/LLM 集成

依赖包	版本	用途
`ai`	^6.0.33	Vercel AI SDK（流式交互）
`@langchain/core`	^1.1.15	LangChain 核心
`@langchain/langgraph-sdk`	^1.5.3	LangGraph SDK
`streamdown`	1.4.0	流式 Markdown 渲染
`tokenlens`	^1.3.1	Token 可视化

UI 组件

依赖包	用途
`@radix-ui/react-*` (18个)	Radix UI 原子组件
`lucide-react`	图标库
`cmdk`	命令面板
`sonner`	Toast 通知
`class-variance-authority`	组件变体管理
`tailwind-merge`	Tailwind 类名合并

代码编辑器 (CodeMirror 6)

依赖包	用途
`@uiw/react-codemirror`	CodeMirror React 封装
`@codemirror/lang-python`	Python 语法高亮
`@codemirror/lang-javascript`	JavaScript 语法高亮
`@codemirror/lang-html`	HTML 语法高亮
`@codemirror/lang-css`	CSS 语法高亮
`@codemirror/lang-json`	JSON 语法高亮
`@codemirror/lang-markdown`	Markdown 语法高亮

可视化与动画

依赖包	用途
`@xyflow/react`	工作流可视化 (React Flow)
`gsap`	高性能动画
`motion`	React 动画 (Framer Motion)
`ogl`	WebGL 3D 图形

文档系统

依赖包	用途
`nextra` + `nextra-theme-docs`	Next.js 文档框架
`shiki`	代码语法高亮
`rehype-katex` + `katex`	数学公式渲染
`remark-gfm`	GitHub Flavored Markdown

状态管理

依赖包	用途
`@tanstack/react-query`	服务端状态管理
`zod`	Schema 验证
`next-themes`	主题切换

开发工具

依赖包	用途
`typescript`	TypeScript 编译器
`tailwindcss`	CSS 框架
`eslint` + `prettier`	代码检查/格式化
`vitest`	单元测试
`@playwright/test`	E2E 测试

6.3 模块依赖关系图

frontend (Next.js)
    │
    ├── @langchain/langgraph-sdk ──→ Gateway API
    ├── @tanstack/react-query ──→ REST API
    └── ai (Vercel AI SDK) ──→ SSE 流式接口
         │
         ▼
Gateway (FastAPI :8001)
    │
    ├── auth/ ──→ JWT + bcrypt
    ├── routers/ ──→ services.py
    │                    │
    │                    ├── deerflow.client ──→ LangGraph SDK
    │                    ├── deerflow.agents ──→ deerflow.tools
    │                    │                        ├── deerflow.mcp
    │                    │                        ├── deerflow.community
    │                    │                        └── deerflow.sandbox
    │                    ├── deerflow.models ──→ LLM APIs
    │                    ├── deerflow.skills ──→ 技能存储
    │                    ├── deerflow.subagents ──→ deerflow.agents
    │                    ├── deerflow.memory ──→ deerflow.persistence
    │                    └── deerflow.tracing ──→ LangSmith/Langfuse
    │
    └── channels/ ──→ IM 平台 SDK

7. 项目运行方式

7.1 环境要求

组件	最低要求	推荐版本
Python	>= 3.12	3.12+
Node.js	>= 22	22+
pnpm	>= 10.26.2	最新版
uv	最新版	最新版
Docker	—	最新版（Docker 部署时）
Nginx	—	最新版（本地开发时）

部署规格建议

部署方式	最低配置	推荐配置
本地开发 (`make dev`)	4 vCPU, 8 GB RAM, 20 GB SSD	8 vCPU, 16 GB RAM
Docker 开发 (`make docker-start`)	4 vCPU, 8 GB RAM, 25 GB SSD	8 vCPU, 16 GB RAM
生产服务器 (`make up`)	8 vCPU, 16 GB RAM, 40 GB SSD	16 vCPU, 32 GB RAM

7.2 快速开始

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

# 2. 运行交互式安装向导（约 2 分钟）
make setup
# 向导会引导你选择 LLM 提供者、配置 API Key、设置沙箱模式等
# 自动生成 config.yaml 和 .env

# 3. 验证配置
make doctor

# 4. 启动服务（选择以下任一方式）

7.3 Docker 部署（推荐）

开发模式（热重载）

make docker-init     # 拉取沙箱镜像（仅需一次）
make docker-start    # 启动服务（自动检测沙箱模式）

生产模式

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

访问地址: http://localhost:2026

Docker 服务架构

用户 → nginx:2026 → frontend (Next.js)
                   → gateway:8001 (FastAPI + Agent 运行时)
                         ├── Docker Socket (DooD 模式)
                         └── provisioner (可选, K8s 沙箱)

7.4 本地开发

# 1. 检查系统依赖
make check           # 验证 Node.js 22+, pnpm, uv, nginx

# 2. 安装依赖
make install         # 安装后端 + 前端依赖 + pre-commit hooks

# 3. (可选) 拉取沙箱镜像
make setup-sandbox

# 4. (可选) 加载示例记忆数据
python scripts/load_memory_sample.py

# 5. 启动开发服务
make dev

# 访问: http://localhost:2026

Windows 用户注意: 需从 Git Bash 运行，不支持原生 cmd.exe/PowerShell。

7.5 启动模式

	本地前台	本地后台	Docker 开发	Docker 生产
开发	`make dev`	`make dev-daemon`	`make docker-start`	—
生产	`make start`	`make start-daemon`	—	`make up`
停止	`make stop`	`make stop`	`make docker-stop`	`make down`

7.6 配置说明

配置文件

文件	说明
`config.yaml`	主配置文件（由 `make setup` 生成）
`config.example.yaml`	完整配置模板
`.env`	环境变量（API Key 等，由向导生成）
`.env.example`	环境变量模板
`extensions_config.json`	MCP 扩展配置
`extensions_config.example.json`	扩展配置模板

模型配置示例

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY

  - name: claude-sonnet-4.6
    display_name: Claude Sonnet 4.6
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-6
    max_tokens: 4096
    supports_thinking: true

  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    supports_thinking: true

环境变量分类

类别	变量
LLM API	`OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `VLLM_API_KEY`, `VOLCENGINE_API_KEY`
搜索 API	`SERPER_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY`, `INFOQUEST_API_KEY`
IM 渠道	`FEISHU_APP_ID/SECRET`, `SLACK_BOT_TOKEN`, `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, `DINGTALK_CLIENT_ID/SECRET`
追踪	`LANGSMITH_TRACING`, `LANGSMITH_ENDPOINT`, `LANGSMITH_API_KEY`
数据库	`DATABASE_URL`
安全	`DEER_FLOW_INTERNAL_AUTH_TOKEN`, `GATEWAY_CORS_ORIGINS`

关键环境变量

变量	说明
`DEER_FLOW_PROJECT_ROOT`	项目根目录
`DEER_FLOW_CONFIG_PATH`	配置文件路径
`DEER_FLOW_HOME`	运行时状态目录（默认 `.deer-flow`）
`DEER_FLOW_SKILLS_PATH`	技能目录（默认 `skills/`）
`GATEWAY_CORS_ORIGINS`	CORS 允许的源（逗号分隔）

8. CI/CD 工作流

DeerFlow 使用 GitHub Actions 进行持续集成和持续部署。

工作流	触发条件	说明
`lint-check.yml`	push to main / PR	后端 ruff lint + 前端 format/lint/typecheck/build
`backend-unit-tests.yml`	push to main / PR	Python pytest 后端单元测试
`backend-blocking-io-tests.yml`	push to main / PR	后端阻塞 IO 场景测试
`frontend-unit-tests.yml`	push to main / PR (非 draft)	Vitest 前端单元测试（15 分钟超时）
`e2e-tests.yml`	push to main / PR (仅 frontend 变更)	Playwright E2E 测试（Chromium）
`container.yaml`	推送 `v*` 标签	构建 Docker 镜像并推送到 `ghcr.io`

容器发布标签策略: Git tag + 分支名 + SHA + latest（默认分支）

9. 技术栈总结

层级	技术选型
前端框架	Next.js 16 + React 19 + TypeScript 5.8
CSS 方案	Tailwind CSS 4 + Radix UI + class-variance-authority
状态管理	@tanstack/react-query 5
AI 集成	Vercel AI SDK 6 + LangGraph SDK + LangChain Core
代码编辑	CodeMirror 6 (Python/JS/HTML/CSS/JSON/Markdown)
可视化	@xyflow/react (React Flow) + GSAP + Motion + OGL (WebGL)
文档系统	Nextra 4
后端框架	FastAPI + Uvicorn
AI 编排	LangGraph SDK
消息渠道	飞书、Slack、Telegram、Discord、钉钉、微信、企业微信
认证	JWT + bcrypt + email-validator
容器化	Docker + Nginx 反向代理
CI/CD	GitHub Actions (lint + 单元测试 + E2E + 容器发布)
测试	pytest (后端) + vitest (前端单元) + Playwright (E2E)
代码质量	ruff (Python) + ESLint + Prettier (TypeScript)
包管理	uv (Python) + pnpm (Node.js)
数据库	SQLite (默认) / PostgreSQL (可选)
ORM	SQLAlchemy 2.0 (异步)
可观测性	LangSmith / Langfuse

本文档基于 DeerFlow 仓库 main 分支分析生成，最后更新时间：2026-05-30

DeerFlow 源码剖析

目录