【DeerFlow 2.0】代码详解（一）：架构总览与核心骨架

系列导读：DeerFlow 2.0 是字节跳动开源的 SuperAgent 框架，基于 LangGraph + LangChain 构建，2026 年 2 月 27 日发布后 24 小时登顶 GitHub Trending。本系列共 5 篇，从架构总览到逐模块深入，带你彻底读懂 DeerFlow 2.0 的每一行代码。

• 第一篇：架构总览与核心骨架（本文）
• 第二篇：Lead Agent 与 Prompt 工程
• 第三篇：SubAgent 并发执行引擎
• 第四篇：Sandbox 安全隔离与 Skills 技能系统
• 第五篇：Memory 记忆系统与 MCP/ACP 扩展

---

一、DeerFlow 2.0 是什么？

1.1 一句话定义

DeerFlow 2.0 = LangGraph Agent + 9 层 Middleware + SubAgent 并发 + Sandbox 隔离 + Skills 技能 + Memory 记忆 + MCP/ACP 扩展

它不是一个简单的 ChatBot，而是一个完整的 Agent 运行时框架——你可以把它理解为"Agent 版的 Spring Boot"：提供了 Agent 开发所需的一切基础设施，你只需要写业务逻辑。

1.2 V1 vs V2：完全重写

维度	V1 (1.x)	V2 (2.0)
定位	Deep Research 工具	SuperAgent 框架
架构	简单链式调用	LangGraph + Middleware Pipeline
子Agent	无	并发执行引擎
沙盒	无	Local + Docker 双模式
技能	无	SKILL.md + 动态加载
记忆	无	异步记忆 + 纠偏/强化检测
中间件	无	9 层中间件管线
代码共享	-	0%（完全重写）

关键：V2 和 V1 没有任何共享代码。如果你在用 V1，迁移到 V2 需要完全重新理解。

---

二、项目结构总览

2.1 顶层目录

deer-flow/
├── backend/                    # 后端（Python）
│   └── packages/harness/
│       └── deerflow/           # 核心框架代码
├── frontend/                   # 前端（Next.js）
│   └── src/
│       ├── app/                # 页面路由
│       └── core/               # 核心模块
├── docker/                     # Docker 配置
├── scripts/                    # 工具脚本
├── config.example.yaml         # 配置模板
└── Makefile                    # 构建命令

2.2 后端核心目录

deerflow/
├── agents/                     # Agent 定义
│   ├── lead_agent/             # 主 Agent
│   │   ├── agent.py            # ★ Agent 创建入口
│   │   └── prompt.py           # ★ Prompt 模板构建
│   ├── middlewares/            # ★ 9 层中间件
│   │   ├── memory_middleware.py
│   │   ├── loop_detection_middleware.py
│   │   ├── clarification_middleware.py
│   │   ├── subagent_limit_middleware.py
│   │   ├── todo_middleware.py
│   │   ├── title_middleware.py
│   │   ├── summarization_middleware.py
│   │   ├── token_usage_middleware.py
│   │   └── view_image_middleware.py
│   ├── memory/                 # 记忆子系统
│   └── thread_state.py         # ★ 全局状态定义
├── subagents/                  # ★ SubAgent 执行引擎
│   ├── executor.py             # 并发执行器
│   └── config.py               # SubAgent 配置
├── sandbox/                    # ★ 沙盒系统
│   ├── sandbox.py              # 抽象基类
│   ├── local/                  # 本地沙盒
│   └── docker/                 # Docker 沙盒
├── skills/                     # ★ 技能系统
│   ├── types.py                # Skill 数据类型
│   └── storage/                # Skill 存储
├── tools/                      # ★ 工具系统
│   ├── tools.py                # 工具加载器
│   ├── builtins/               # 内置工具
│   └── skill_manage_tool.py    # 技能管理工具
├── mcp/                        # MCP 连接器
├── config/                     # ★ 配置系统
│   └── app_config.py           # AppConfig 主文件
├── persistence/                # 持久化层
├── community/                  # 社区集成
└── utils/                      # 工具函数

2.3 前端核心目录

frontend/src/
├── app/workspace/
│   ├── chats/[thread_id]/      # 对话页面
│   └── agents/                 # Agent 管理页面
└── core/
    ├── api/                    # API 调用层
    ├── threads/                # 线程管理
    ├── todos/                  # 待办事项
    ├── mcp/                    # MCP 前端
    ├── tasks/                  # 任务管理
    └── models/                 # 模型管理

---

三、核心骨架：Lead Agent

3.1 Agent 创建入口

agents/lead_agent/agent.py 是整个框架的核心入口，负责创建 Lead Agent：

def create_lead_agent(
    model_name: str | None = None,
    subagent_enabled: bool = True,
    max_concurrent_subagents: int = 3,
    agent_name: str | None = None,
    thinking_enabled: bool = False,
    reasoning_effort: str | None = None,
    app_config: AppConfig | None = None,
):
    """创建 Lead Agent 实例"""
    resolved_app_config = app_config or get_app_config()
    agent_config = load_agent_config(agent_name, resolved_app_config)
    
    # 自定义 Agent 可以更新自己的 SOUL.md
    extra_tools = [update_agent] if agent_name else []
    
    return create_agent(
        model=create_chat_model(...),           # 1. 创建 LLM
        tools=get_available_tools(...) + extra_tools,  # 2. 加载工具
        middleware=_build_middlewares(...),      # 3. 构建中间件
        system_prompt=apply_prompt_template(...),# 4. 构建 Prompt
        state_schema=ThreadState,               # 5. 绑定状态
    )

5 个核心组件：

组件	作用	来源
create_chat_model	创建 LLM 实例	deerflow.models
get_available_tools	加载所有工具	deerflow.tools.tools
_build_middlewares	构建 9 层中间件	deerflow.agents.middlewares
apply_prompt_template	构建系统 Prompt	deerflow.agents.lead_agent.prompt
ThreadState	全局状态 Schema	deerflow.agents.thread_state

3.2 工具加载机制

tools/tools.py 中的 get_available_tools() 是工具加载的核心：

def get_available_tools(
    groups: list[str] | None = None,
    include_mcp: bool = True,
    model_name: str | None = None,
    subagent_enabled: bool = True,
    app_config: AppConfig | None = None,
) -> list[BaseTool]:
    """加载所有可用工具"""
    
    # 1. 内置工具 (present_file, ask_clarification)
    builtin_tools = list(BUILTIN_TOOLS)
    
    # 2. 配置文件加载的工具 (bash, edit, search...)
    loaded_tools = _load_tools_from_config(config, groups)
    
    # 3. SubAgent 工具 (task)
    if subagent_enabled:
        builtin_tools.extend(SUBAGENT_TOOLS)
    
    # 4. MCP 工具 (外部服务)
    mcp_tools = _load_mcp_tools(config) if include_mcp else []
    
    # 5. ACP Agent 工具 (其他 Agent)
    acp_tools = _load_acp_tools(config)
    
    # 6. 去重 (同名工具优先级: config > builtin > mcp > acp)
    all_tools = loaded_tools + builtin_tools + mcp_tools + acp_tools
    # ... 去重逻辑 ...
    return unique_tools

工具加载优先级：config.yaml 配置 > 内置工具 > MCP 工具 > ACP 工具

---

四、9 层 Middleware Pipeline

DeerFlow 2.0 最精妙的设计之一是 Middleware Pipeline——9 层中间件按顺序执行 before_agent，逆序执行 after_agent，所有中间件共享 ThreadState。

4.1 中间件列表

#	中间件	before_agent	after_agent	核心功能
1	TokenUsage	-	统计 Token 用量	每次 Agent 执行后记录 input/output tokens
2	LoopDetection	检测循环	-	检测重复工具调用，防止无限循环
3	SubagentLimit	检查并发数	-	限制并发 SubAgent 数量（默认 3）
4	Clarification	-	检测模糊指令	主动追问用户澄清需求
5	Memory	-	异步更新记忆	对话后异步更新长期记忆，支持纠偏/强化检测
6	Todo	-	解析待办	从 AI 回复中提取任务列表
7	Title	-	生成标题	首条消息自动生成对话标题
8	Summarization	-	长对话摘要	超过阈值自动摘要，BeforeSummarization Hook
9	ViewImage	-	注入图片	检测图片引用，注入 base64 数据

4.2 中间件构建

_build_middlewares() 函数按顺序组装所有中间件：

def _build_middlewares(config, model_name, agent_name, app_config):
    middlewares = [
        # 1. Token 用量统计
        TokenUsageMiddleware(token_usage_config=app_config.token_usage),
        # 2. 循环检测
        LoopDetectionMiddleware(),
        # 3. SubAgent 并发限制
        SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents),
        # 4. 澄清中间件
        ClarificationMiddleware(),
        # 5. 记忆中间件
        MemoryMiddleware(agent_name=agent_name, memory_config=app_config.memory),
        # 6. 待办中间件
        TodoMiddleware(),
        # 7. 标题中间件
        TitleMiddleware(title_config=app_config.title),
        # 8. 摘要中间件
        DeerFlowSummarizationMiddleware(
            summarization_config=app_config.summarization,
            before_hooks=[BeforeSummarizationHook()],
        ),
        # 9. 图片查看
        ViewImageMiddleware(),
    ]
    # 加上运行时错误处理中间件
    middlewares.extend(build_lead_runtime_middlewares())
    return middlewares

4.3 执行流程

用户消息 → [LoopDetection.before] → [SubagentLimit.before] →
           [Agent 执行] →
           [ViewImage.after] → [Summarization.after] → [Title.after] →
           [Todo.after] → [Memory.after] → [Clarification.after] →
           [TokenUsage.after] → 返回结果

关键设计：before_agent 正序执行（1→9），after_agent 逆序执行（9→1）。这保证了"先检查后执行"和"先处理后记录"的逻辑。

---

五、ThreadState：全局状态

5.1 状态定义

thread_state.py 定义了贯穿整个 Agent 生命周期的全局状态：

class ThreadState(AgentState):
    sandbox: NotRequired[SandboxState | None]           # 沙盒 ID
    thread_data: NotRequired[ThreadDataState | None]    # 工作区路径
    title: NotRequired[str | None]                      # 对话标题
    artifacts: Annotated[list[str], merge_artifacts]    # 产出物 (去重合并)
    todos: NotRequired[list | None]                     # 待办事项
    uploaded_files: NotRequired[list[dict] | None]      # 上传文件
    viewed_images: Annotated[dict, merge_viewed_images] # 已查看图片 (合并)

5.2 Reducer 机制

LangGraph 的 Reducer 机制是理解 ThreadState 的关键：

字段	合并策略	说明
artifacts	merge_artifacts()	去重合并，保留顺序
viewed_images	merge_viewed_images()	字典合并，空字典=清空
其他字段	直接覆盖	last-write-wins

def merge_artifacts(existing: list[str] | None, new: list[str] | None) -> list[str]:
    """去重合并 artifacts"""
    if existing is None: return new or []
    if new is None: return existing
    return list(dict.fromkeys(existing + new))  # 保序去重

def merge_viewed_images(existing, new):
    """合并图片字典，空字典=清空"""
    if len(new) == 0: return {}  # 特殊：空字典清空所有
    return {**existing, **new}   # 新值覆盖旧值

为什么需要 Reducer？ 因为 SubAgent 并发执行时，多个 SubAgent 可能同时更新 artifacts，Reducer 保证了合并的正确性和一致性。

---

六、Config System：配置体系

6.1 AppConfig 主文件

config/app_config.py 是配置系统的核心，包含 17 个子配置模块：

class AppConfig(BaseModel):
    log_level: str                    # 日志级别
    token_usage: TokenUsageConfig     # Token 用量
    models: list[ModelConfig]         # 模型列表
    sandbox: SandboxConfig            # 沙盒配置
    tools: list[ToolConfig]           # 工具列表
    tool_groups: list[ToolGroupConfig]# 工具分组
    skills: SkillsConfig              # 技能配置
    skill_evolution: SkillEvolutionConfig  # 技能进化
    extensions: ExtensionsConfig      # 扩展 (MCP/Skills)
    tool_search: ToolSearchConfig     # 工具搜索
    title: TitleConfig                # 标题生成
    summarization: SummarizationConfig# 对话摘要
    memory: MemoryConfig              # 记忆系统
    agents_api: AgentsApiConfig       # Agent API
    acp_agents: dict[str, ACPAgentConfig]  # ACP Agent
    subagents: SubagentsAppConfig     # SubAgent 配置
    guardrails: GuardrailsConfig      # 护栏
    circuit_breaker: CircuitBreakerConfig  # 熔断器
    database: DatabaseConfig          # 数据库
    run_events: RunEventsConfig       # 事件存储
    checkpointer: CheckpointerConfig  # 检查点
    stream_bridge: StreamBridgeConfig # 流桥接

6.2 配置加载流程

@classmethod
def from_file(cls, config_path=None):
    # 1. 解析配置文件路径
    resolved_path = cls.resolve_config_path(config_path)
    
    # 2. YAML 加载
    config_data = yaml.safe_load(f)
    
    # 3. 版本检查
    cls._check_config_version(config_data, resolved_path)
    
    # 4. 环境变量解析 ($OPENAI_API_KEY → 实际值)
    config_data = cls.resolve_env_variables(config_data)
    
    # 5. 数据库默认值
    cls._apply_database_defaults(config_data)
    
    # 6. 逐个子配置加载
    load_title_config_from_dict(config_data.get("title"))
    load_memory_config_from_dict(config_data.get("memory"))
    load_subagents_config_from_dict(config_data.get("subagents"))
    # ... 更多子配置 ...
    
    # 7. Pydantic 验证
    return cls.model_validate(config_data)

6.3 单例 + 热重载

def get_app_config() -> AppConfig:
    """获取配置单例，自动检测文件变化并重载"""
    # 1. 运行时覆盖优先
    runtime_override = _current_app_config.get()
    if runtime_override is not None:
        return runtime_override
    
    # 2. 检查文件修改时间
    current_mtime = _get_config_mtime(resolved_path)
    should_reload = (
        _app_config is None or
        _app_config_path != resolved_path or
        _app_config_mtime != current_mtime  # 文件被修改了!
    )
    
    if should_reload:
        _load_and_cache_app_config()  # 热重载
    
    return _app_config

热重载：修改 config.yaml 后无需重启服务，DeerFlow 会自动检测文件 mtime 变化并重新加载配置。这是生产环境非常实用的功能。

---

七、五篇系列规划

篇章	主题	核心内容
第一篇（本文）	架构总览与核心骨架	项目结构 / Lead Agent / Middleware / ThreadState / Config
第二篇	Lead Agent 与 Prompt 工程	System Prompt 模板 / SOUL.md / Skills 注入 / SubAgent 调度指令
第三篇	SubAgent 并发执行引擎	executor.py / ThreadPool / 异步任务 / 超时取消 / 状态管理
第四篇	Sandbox 安全隔离与 Skills	Sandbox ABC / Local vs Docker / SKILL.md / Skill Storage / 动态加载
第五篇	Memory 记忆系统与扩展	异步记忆队列 / 纠偏强化 / MCP 连接 / ACP Agent / 持久化

---

八、总结

8.1 核心设计理念

DeerFlow 2.0 的架构设计体现了三个核心理念：

1. 分层解耦：Agent / Middleware / Tool / Sandbox / Memory 各层独立，通过 ThreadState 串联
2. 中间件管线：9 层中间件提供横切关注点的统一处理，避免 Agent 代码膨胀
3. 配置驱动：17 个子配置模块 + 热重载，让框架行为完全可配置

8.2 一句话总结

DeerFlow 2.0 的核心骨架是 “Lead Agent + 9 层 Middleware + ThreadState”——Lead Agent 是大脑，Middleware 是神经，ThreadState 是血液。三者协同，构成了一个可扩展、可配置、可观测的 SuperAgent 运行时。

---

下一篇预告：《DeerFlow 2.0 代码详解（二）：Lead Agent 与 Prompt 工程》——深入拆解 System Prompt 的 800 行模板构建、SOUL.md 机制、Skills 动态注入、SubAgent 调度指令。

---

作者简介：小李同学_LSH，CSDN博主，专注AI前沿技术解读与开发实战，持续分享LLM应用、Agent开发、深度学习等领域的深度内容。

如果觉得有帮助，欢迎点赞、收藏、关注！你的支持是我持续创作的动力！ 🚀