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

【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：完全重写

关键：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：

defcreate_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_configorget_app_config()agent_config=load_agent_config(agent_name,resolved_app_config)# 自定义 Agent 可以更新自己的 SOUL.mdextra_tools=[update_agent]ifagent_nameelse[]returncreate_agent(model=create_chat_model(...),# 1. 创建 LLMtools=get_available_tools(...)+extra_tools,# 2. 加载工具middleware=_build_middlewares(...),# 3. 构建中间件system_prompt=apply_prompt_template(...),# 4. 构建 Promptstate_schema=ThreadState,# 5. 绑定状态)

5 个核心组件：

3.2 工具加载机制

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

defget_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)ifsubagent_enabled:builtin_tools.extend(SUBAGENT_TOOLS)# 4. MCP 工具 (外部服务)mcp_tools=_load_mcp_tools(config)ifinclude_mcpelse[]# 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# ... 去重逻辑 ...returnunique_tools

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

四、9 层 Middleware Pipeline

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

4.1 中间件列表

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())returnmiddlewares

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 生命周期的全局状态：

classThreadState(AgentState):sandbox:NotRequired[SandboxState|None]# 沙盒 IDthread_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 的关键：

defmerge_artifacts(existing:list[str]|None,new:list[str]|None)->list[str]:"""去重合并 artifacts"""ifexistingisNone:returnnewor[]ifnewisNone:returnexistingreturnlist(dict.fromkeys(existing+new))# 保序去重defmerge_viewed_images(existing,new):"""合并图片字典，空字典=清空"""iflen(new)==0:return{}# 特殊：空字典清空所有return{**existing,**new}# 新值覆盖旧值

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

六、Config System：配置体系

6.1 AppConfig 主文件

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

classAppConfig(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 APIacp_agents:dict[str,ACPAgentConfig]# ACP Agentsubagents:SubagentsAppConfig# SubAgent 配置guardrails:GuardrailsConfig# 护栏circuit_breaker:CircuitBreakerConfig# 熔断器database:DatabaseConfig# 数据库run_events:RunEventsConfig# 事件存储checkpointer:CheckpointerConfig# 检查点stream_bridge:StreamBridgeConfig# 流桥接

6.2 配置加载流程

@classmethoddeffrom_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 验证returncls.model_validate(config_data)

6.3 单例 + 热重载

defget_app_config()->AppConfig:"""获取配置单例，自动检测文件变化并重载"""# 1. 运行时覆盖优先runtime_override=_current_app_config.get()ifruntime_overrideisnotNone:returnruntime_override# 2. 检查文件修改时间current_mtime=_get_config_mtime(resolved_path)should_reload=(_app_configisNoneor_app_config_path!=resolved_pathor_app_config_mtime!=current_mtime# 文件被修改了!)ifshould_reload:_load_and_cache_app_config()# 热重载return_app_config

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

七、五篇系列规划

八、总结

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开发、深度学习等领域的深度内容。

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