1. 项目概述
1.1 项目定位
DeerFlow (Deep Exploration and Efficient Research Flow) 是一个开源的 Super Agent Harness (超级智能体运行平台)，基于 LangGraph 和 LangChain 构建。它通过编排子智能体、记忆系统和沙箱执行环境，实现复杂的 AI 任务自动化。
1.2 核心功能
• 多模型支持: 支持任意 OpenAI-compatible API 的 LLM，包括 GPT、Claude、Gemini、DeepSeek 等 • 子智能体编排: 支持并行/串行子任务委托，lead agent 可动态生成子代理 • 沙箱执行: 支持 Local/Docker/Kubernetes 三种沙箱隔离模式 • 长期记忆: 基于 LLM 的用户画像和上下文记忆系统 • 技能系统: 可扩展的 Markdown 技能定义，支持公共/自定义技能 • MCP 集成: Model Context Protocol 支持，扩展工具生态 • IM 渠道: 支持 Telegram、Slack、飞书的消息通道接入
1.3 目标用户
• AI 研究者和开发者 • 需要自动化复杂任务的企业用户 • 希望构建定制化 AI Agent 的团队
2. 架构设计
2.1 整体架构模式
┌─────────────────────────────────────────────────────────────────┐
│ Nginx (Port 2026) │
│ ┌───────────────┬────────────────────┬───────────────────┐ │
│ │ /api/langgraph│ /api/* │ / │ │
│ │ → LangGraph │ → Gateway API │ → Frontend │ │
│ │ (2024) │ (8001) │ (3000) │ │
│ └───────────────┴────────────────────┴───────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌────▼────┐
│ LangGraph │ │ Gateway │ │ Frontend│
│ Server │ │ API │ │ (Next) │
│ (2024) │ │ (8001) │ │ (3000) │
└─────┬─────┘ └─────┬─────┘ └────┬────┘
│ │ │
│ ┌─────────────┘ │
│ │ │
▼ ▼ │
┌──────────────────┐ │
│ Harness Core │◄───────────────────────┘
│ (deerflow.*) │ (LangGraph SDK)
└──────────────────┘
│
┌─────┴─────┐
│ Sandbox │
│ Provider │
└───────────┘2.2 技术选型
| 前端 | |
| 后端 | |
| 沙箱 | |
| 数据存储 | |
| 消息队列 | |
| 基础设施 |
2.3 模块间通信方式
1. Frontend → LangGraph: 通过 @langchain/langgraph-sdk的 SSE 流式通信2. Frontend → Gateway: REST API (models, skills, memory, uploads, artifacts) 3. Gateway → LangGraph: 内部通信用于 IM 渠道消息分发 4. Nginx: 反向代理，统一入口 (2026)
2.4 核心设计模式
• Middleware Chain Pattern: 12 个中间件按序执行 (ThreadData → Uploads → Sandbox → DanglingToolCall → Guardrail → Summarization → TodoList → Title → Memory → ViewImage → SubagentLimit → Clarification) • Provider Pattern: Sandbox、Memory、Checkpointer 等核心组件使用 Provider 模式 • Factory Pattern: Model factory ( create_chat_model) 通过反射动态创建• Observer Pattern: MessageBus pub/sub 解耦 IM 渠道与核心处理
3. 技术栈详解
3.1 前端技术栈
框架与库:
• Next.js 16 (App Router) • React 19 • TypeScript 5.8 • Tailwind CSS 4 • TanStack Query 5 (服务端状态管理)
UI 组件:
• Radix UI (对话组件) • Shadcn/ui (基础组件) • Lucide React (图标) • Sonner (Toast)
核心功能:
• 流式处理: useThreadStreamhook 处理 SSE• 状态管理: TanStack Query + 本地 Storage • 国际化: i18n 支持 (en-US, zh-CN)
构建工具:
• Turbopack (开发) • pnpm 10.26.2
3.2 后端技术栈
运行时与框架:
• Python 3.12+ • FastAPI (Gateway API) • LangGraph (Agent 编排) • LangChain (LLM 集成)
核心依赖:
langgraph>=1.0.6,<1.0.10
langchain>=1.2.3
langchain-openai>=1.1.7
langchain-anthropic>=1.3.4
langchain-deepseek>=1.0.1
langchain-google-genai>=4.2.1
langchain-mcp-adapters>=0.1.0
pydantic>=2.12.5
fastapi>=0.115.0
httpx>=0.28.0工具生态:
• Tavily / DuckDuckGo (网页搜索) • Jina AI (网页抓取/ readability) • Firecrawl (网页爬取) • markitdown (文档转换 PDF/PPT/Excel/Word)
3.3 数据库和缓存方案
Memory Storage:
• JSON 文件存储 ( memory.json)• 支持 per-agent 隔离存储 • 原子性写入 (temp + rename)
Checkpointer:
• 支持 Memory/SQLite/PostgreSQL • 默认 SQLite 用于开发 • LangGraph 持久化状态
MCP Cache:
• 基于 mtime 的配置变更检测 • 工具缓存失效机制
3.4 其他基础设施
日志:
• Python logging (basicConfig) • Nginx access/error logs
监控集成:
• LangSmith tracing (可选) • Langfuse tracing (可选)
4. 功能模块分析
4.1 核心业务模块划分
backend/
├── app/
│ ├── gateway/ # FastAPI 网关 (8001)
│ │ ├── routers/ # API 路由 (models, mcp, skills, memory, etc.)
│ │ ├── services.py
│ │ ├── deps.py # 依赖注入
│ │ └── config.py
│ └── channels/ # IM 渠道集成
│ ├── manager.py # 消息分发中心
│ ├── message_bus.py # Pub/Sub 总线
│ ├── store.py # 渠道-线程映射持久化
│ ├── feishu.py # 飞书 WebSocket
│ ├── slack.py # Slack Socket Mode
│ └── telegram.py # Telegram Bot API
│
└── packages/harness/deerflow/
├── agents/
│ ├── lead_agent/ # 主 Agent 工厂 + 系统提示
│ ├── middlewares/ # 12 个中间件组件
│ ├── memory/ # 记忆提取/队列/存储
│ └── thread_state.py # ThreadState 定义
├── sandbox/ # 沙箱抽象与实现
│ ├── local/ # 本地文件系统执行
│ ├── tools.py # bash/ls/read_file/write_file/str_replace
│ └── middleware.py
├── subagents/ # 子代理执行引擎
│ ├── executor.py # 异步执行 + 双线程池
│ ├── registry.py # 内置代理注册
│ └── builtins/ # general-purpose / bash
├── tools/ # 工具系统
│ ├── builtins/ # present_files, ask_clarification, view_image
│ └── get_available_tools()
├── models/ # 模型工厂
│ ├── factory.py # create_chat_model()
│ ├── claude_provider.py
│ ├── openai_codex_provider.py
│ └── patched_*.py # 特定模型补丁
├── mcp/ # MCP 集成
│ ├── client.py
│ ├── tools.py # get_mcp_tools()
│ ├── cache.py
│ └── oauth.py
├── skills/ # 技能系统
│ ├── loader.py
│ └── parser.py
├── config/ # 配置解析
│ ├── app_config.py # 主配置 (config.yaml)
│ └── extensions_config.py # MCP/Skills 配置
├── community/ # 社区工具
│ ├── tavily/
│ ├── jina_ai/
│ ├── firecrawl/
│ ├── image_search/
│ ├── ddg_search/
│ └── aio_sandbox/ # Docker 沙箱提供者
└── client.py # 嵌入式 Python 客户端4.2 各模块职责和边界
Harness vs App 边界:
• Harness ( deerflow.*): 可发布的 Agent 框架包• App ( app.*): 应用层代码，依赖 Harness• 严格单向依赖: App → Harness，禁止反向
Lead Agent 职责:
• 动态模型选择 (thinking/vision support) • 工具聚合 (sandbox + built-in + MCP + community + subagent) • 系统提示构建 (skills + memory + subagent instructions)
沙箱职责:
• 虚拟路径映射 ( /mnt/user-data→backend/.deer-flow/threads/{id})• 命令执行与文件系统操作 • 安全路径验证 (禁止 path traversal)
子代理职责:
• 异步任务执行 (ThreadPoolExecutor) • 最大并发控制 (MAX_CONCURRENT_SUBAGENTS=3) • 超时管理 (默认 15 分钟)
4.3 模块间依赖关系
Gateway (app.gateway)
└── deps.py → langgraph_runtime (初始化 StreamBridge, RunManager, checkpointer)
└── channels.service → start_channel_service
└── MessageBus.publish_inbound()
└── ChannelManager._dispatch_loop()
└── LangGraph SDK (threads.create, runs.stream)
Frontend (Next.js)
└── core/threads/hooks.ts → useStream → LangGraph SDK
└── core/api/index.ts → getAPIClient → LangGraph Client
LangGraph Server
└── make_lead_agent() → create_chat_model() + get_available_tools()
└── _build_middlewares() → 12 middleware chain5. 部署方案
5.1 容器化方案
Services:
1. nginx: Alpine, reverse proxy (2026) 2. frontend: Node 22, Next.js production/dev 3. gateway: Python 3.12, FastAPI + Uvicorn (8001) 4. langgraph: Python 3.12, langgraph dev(2024)5. provisioner (可选): K8s sandbox provisioner
Docker 特性:
• DooD (Docker-out-of-Docker): 沙箱容器通过 host Docker socket 创建 • 热重载: 开发模式 mount 源码目录 • 依赖缓存: uv cache mount
5.2 环境配置管理
配置文件:
• config.yaml- 主配置 (models, tools, sandbox, skills, memory 等)• extensions_config.json- MCP servers 和 skills 状态• .env- API keys 和敏感配置
环境变量优先级:
1. 显式传入 config_path2. DEER_FLOW_CONFIG_PATH环境变量3. config.yaml(当前目录或父目录)
配置热重载:
• Gateway 自动检测 config.yaml mtime 变化 • 无需手动重启
5.3 部署流程和配置
开发环境:
make docker-init # Pull sandbox image
make docker-start # Start services (auto-detect sandbox mode)生产环境:
make up # Build + start
make down # Stop + remove关键环境变量:
DEER_FLOW_HOME=/app/backend/.deer-flow
DEER_FLOW_CONFIG_PATH=/app/backend/config.yaml
DEER_FLOW_CHANNELS_LANGGRAPH_URL=http://langgraph:2024
DEER_FLOW_CHANNELS_GATEWAY_URL=http://gateway:8001
LANGSMITH_TRACING=true# 可选6. 代码质量与工程化
6.1 测试策略
后端测试 (backend/tests/):
• 回归测试: Docker sandbox mode detection, provisioner kubeconfig • 边界测试: harness/app import firewall • 内存系统: memory updater 测试 • 客户端一致性: TestGatewayConformance验证 client output 与 Gateway schema 一致
前端测试:
• 无测试框架配置 (截至当前版本)
6.2 代码规范
Python:
• rufflinting + formatting• Line length: 240 • Python 3.12+ 类型提示 • 双引号字符串
TypeScript:
• ESLint + Prettier • 导入排序: builtin → external → internal → parent → sibling • 路径别名: @/*→src/*
6.3 构建优化
前端:
• Turbopack 开发加速 • 静态网站模式支持 ( NEXT_PUBLIC_STATIC_WEBSITE_ONLY)• 多阶段 Dockerfile (dev/builder/prod)
后端:
• uv 依赖管理 (快速同步) • Docker layer caching • 开发模式源码挂载 (无需 rebuild)
7. 安全特性
7.1 沙箱安全
• Local Sandbox: 非安全隔离边界， allow_host_bash: false默认• Docker Sandbox: 容器隔离，path traversal 防护 • 路径验证: 虚拟路径映射 ( /mnt/user-data)，禁止逃逸
7.2 Guardrails
• 可插拔 GuardrailProvider 协议 • 内置 AllowlistProvider (零外部依赖) • 工具调用前授权检查
7.3 部署安全建议
• 本地可信网络部署 • IP 白名单 • 反向代理 + 强认证 • 网络隔离 (VLAN)
8. 关键设计亮点
1. Harness/App 分离: 可发布的 agent 框架 vs 应用代码，边界清晰 2. Middleware Chain: 12 个正交中间件，职责单一，可组合 3. 虚拟路径系统: 统一的 /mnt/user-data抽象，跨沙箱类型透明4. 双重线程池: scheduler (3) + execution (3)，平衡并发与资源 5. 流式架构: LangGraph SSE + Frontend useStream 端到端流式 6. 配置驱动: YAML 配置 + 环境变量替换，热重载支持
9. 项目结构总览
deer-flow/
├── backend/
│ ├── app/ # 应用层
│ │ ├── gateway/ # FastAPI 网关
│ │ └── channels/ # IM 渠道集成
│ ├── packages/
│ │ └── harness/ # Agent 运行框架 (deerflow.*)
│ │ └── deerflow/
│ ├── tests/ # 后端测试
│ ├── config.yaml # 主配置
│ ├── pyproject.toml # Python 项目配置
│ └── Dockerfile
├── frontend/ # Next.js 前端
│ ├── src/
│ │ ├── app/ # Next.js App Router
│ │ ├── components/ # React 组件
│ │ └── core/ # 核心 hooks 和 API
│ ├── package.json
│ └── Dockerfile
├── provisioner/ # K8s 沙箱配置器 (可选)
├── docker-compose.yml # 容器编排
├── docker-compose.dev.yml # 开发环境
├── Makefile # 构建命令
└── README.md本报告基于 v2.0 版本源码分析，涵盖了 DeerFlow 的完整技术栈和架构设计。
