DeerFlow 2.0 架构：14层中间件源码解读，洋葱责任链的工程化落地

在构建大型语言模型（LLM）驱动的智能体时，如何优雅地处理日志、安全、状态管理等非功能性需求？问题的答案常常指向一种经典的架构思维——“洋葱责任链模式”。从 LangChain 的轻量级中间件，到字节跳动基于 源码 开源框架深度定制的 DeerFlow 2.0，这种模式已被工程化到了极致。本文将深入 DeerFlow 的 14 层中间件 架构，逐层拆解其设计哲学与实现细节，带你领略生产级 Agent 框架的严谨之美。

一、LangChain Middleware架构与源码解析

LangChain Middleware架构的核心是一种“Runnable包装器”模式。你可以把它理解为：所有中间件本质上都是接受一个旧 Runnable 并返回一个新 Runnable 的函数或类。它们通过 before 和 after 钩子，在目标 Runnable 执行的前后巧妙地插入自定义逻辑。

这种架构完美契合了“纯洋葱模型”。它和 MyBatis 中广为人知的洋葱式责任链高度同源，二者都追求通过“层层嵌套包装”来实现请求的双向穿透，这和你可能见过的传统的、依靠 next 指针顺序传递的链表式责任链完全不同。

LangChain Middleware 的洋葱模型意味着：一个请求会从最外层的中间件开始，一层层穿透进去，触达核心的 Runnable；随后，响应会从核心一层层回溯出来。每一层中间件都有机会独立处理进入的请求和返回的响应，并且它们可以被灵活地组合、插拔。

这里需要明确一个核心概念：LangChain Middleware 的“洋葱模式责任链”架构。它与 MyBatis 一致，都采用了“代理嵌套 + 反射传递”的设计。其精髓在于，通过层层包装，实现了请求与响应的双向处理能力，而不仅仅是单向的线性传递。

1.1 LangChain Middleware核心定位

LangChain 1.0 版本正式将 Middleware（中间件）概念提升为“一等公民”。它被明确定义为 Runnable 执行流程中的横切逻辑载体。与早期依赖 RunnableLambda 或回调函数的实现方式不同，1.0 版本的 Middleware 通过一套标准化的 API，优雅地解决了代码复用问题。

这些中间件旨在解决 Agent 执行过程中的三大核心难题：不可控性、安全风险和资源浪费。通过这种标准化的 API，日志、重试、限流、安全拦截等通用功能得以被独立封装，并在不同的 Agent 和链中复用。

值得一提的是，早期的 AgentMiddleware 接口已成为兼容层，当下 LangChain 的核心中间件体系已全面迁移至 langchain_core.runnables.middleware 模块。它形成了一套“装饰器 + 类继承”的实现模式，为所有可执行组件提供流程拦截与增强的能力。

1.2 LangChain Middleware “洋葱模式责任链” 架构核心设计

洋葱模型的精髓在于“请求正向穿透、响应反向回溯”。这并不是简单地用 next 指针将处理器串成一条线，而是通过嵌套包装的方式构建层级结构。这正是它与传统顺序责任链最本质的区别——它形成了一个有深度、有反向处理能力的结构。

LangChain Middleware 的设计完美体现了这个定义。它的每个中间件都是一个 before/after 钩子包，核心的 Runnable 是最终的“处理节点”。各种各样的中间件像洋葱皮一样层层包裹住核心，将业务逻辑之外的处理织入执行流程中。

1.3. 洋葱模式 责任链模式核心要素 与LangChain Middleware的对应关系

责任链模式有 4 大核心要素，LangChain Middleware 通过模块化的设计，将它们一一落地到了具体的源码组件中。这种清晰的映射关系是整个架构可扩展、可组合的基石。我们将结合 MyBatis 的洋葱责任链进行对照，方便你触类旁通。

(1) 抽象处理器（Abstract Handler）：对应 langchain_core.runnables.middleware.Middleware 抽象类。它定义了所有中间件必须遵守的统一接口——__call__(self, request, call_next) 方法。这个方法规定了每个中间件都必须接收“请求”和“调用下一层的方法 (call_next)”，确保了请求能在层级间传递，同时也支持响应的回溯处理。

(2) 具体处理器（Concrete Handler）：对应所有具体的中间件实现，例如装饰器式的日志中间件、类继承式的 LoggingMiddleware，以及内置的重试、限流中间件等。每个具体中间件都实现了 __call__ 方法，负责处理自己分内的横切逻辑，同时通过 call_next(request) 将请求传递给内层。当响应返回时，它们再依次处理响应，形成完整的“请求进、响应出”双向链路。

(3) 链的组装（Chain Assembly）：对应 MiddlewareChain 类。它负责将多个具体的中间件按指定顺序组装成一个洋葱式的层级结构，并将最内层指向核心 Runnable。组装的关键是从后往前逆序包装，即最靠近核心的中间件最先被包装。这与 MyBatis 通过 InterceptorChain.pluginAll() 逐层包装目标对象的方式如出一辙。

(4) 请求传递（Request Delivery）：这恰恰是“洋葱模型”执行流程的体现。请求从最外层开始，逐层通过 call_next(request) 向内穿透，直达核心 Runnable。核心执行完毕后，响应再从核心逐层向外回溯，每层都可以对响应进行加工或记录，最终返回给调用方。这种“正向请求、反向响应”正是它与 MyBatis 等架构的共同特色。

二. LangChain Middleware 洋葱责任链模式的具体实现（结合源码）

现在，我们从“抽象处理器定义 → 具体处理器实现 → 链的组装 → 请求传递”这四个环节，结合核心源码，细致地拆解这个过程。

2.1 抽象处理器（Middleware抽象类）：定义责任链统一接口

Middleware 抽象类是整个层级王国的基石，它定义了处理器们必须遵守的共同契约。其核心源码（简化版）如下，请重点关注 __call__ 方法。

from abc import ABC, abstractmethod
from langchain_core.runnables.middleware import Request

class Middleware(ABC):
    @abstractmethod
    async def __call__(self, request: Request, call_next):
        """
        洋葱责任链处理器的核心接口，每个具体中间件必须实现
        :param request: 请求对象，包含输入、配置等信息
        :param call_next: 调用下一层中间件/核心Runnable的方法
        :return: 处理后的响应（支持响应反向回溯处理）
        """
        pass

这个抽象方法 __call__ 规定了中间件的“天职”：接收请求和调用下一层的回调，并最终返回一个响应。就是这样一个看似简单的契约，撑起了整个洋葱责任链的双向传递能力。

2.2 具体处理器（具体中间件）：实现责任链的具体处理逻辑

所有具体的中间件，无论是类还是函数形式，都是Middleware的具体实现者。它们负责执行自身的横切逻辑，并保证链路的畅通。

（1）类继承式中间件（有状态的具体处理器）

这种方式适合需要维护状态（如重试次数）的复杂场景。它通过继承 Middleware 类并实现 __call__ 方法来工作。

from langchain_core.runnables.middleware import Middleware

class LoggingMiddleware(Middleware):
    async def __call__(self, request, call_next):
        # 1. 正向穿透：请求执行前记录日志
        print(f"请求开始：{request}")
        # 2. 核心穿透：不中断链路，将请求传给下一层
        response = await call_next(request)
        # 3. 反向回溯：响应返回后记录日志
        print(f"请求结束：响应为{response}")
        return response

这段代码生动地展示了洋葱模型的双向性：在调用 call_next 之前，是“正向穿透”的前置处理；调用之后，是“反向回溯”的后置处理。整个过程一气呵成。

（2）装饰器式中间件（无状态的具体处理器）

对于简单的、无状态的场景，使用 @middleware 装饰器会非常轻便和直观。

from langchain_core.runnables.middleware import middleware

@middleware
async def log_middleware(request, call_next):
    # 前置处理
    print(f"收到请求: {request}")
    # 传递请求
    response = await call_next(request)
    # 后置处理
    print(f"返回响应: {response}")
    return response

@middleware 装饰器的本质，是帮你把普通函数自动“升级”为一个 Middleware 抽象类的实现，它遵循的依然是那套洋葱责任链的逻辑。

2.3 洋葱链的组装（MiddlewareChain）：构建洋葱责任链的完整结构

MiddlewareChain 类扮演着“组装器”的角色。它的核心逻辑是“从后往前逆序包装”：先把最里层的中间件与核心 Runnable 包装，然后把次外层的中间件再包装上去，以此类推，最终形成一个层层嵌套的洋葱结构。这与传统责任链需要手动设置 next 引用的做法相比，既优雅又不易出错。

2.4 洋葱模型 责任链 如何 请求传递 ：责任链的执行流程

执行链路完美诠释了“正向穿透”与“反向回溯”。一个请求会依次经历最外层、中层、最内层中间件的前置处理，然后抵达核心 Runnable 并执行；接着，生成的响应会沿着来时的路返回，由内向外依次经过每一层中间件的后置处理，最终返回给请求发起者。

关键点在于：链路的正常运转依赖不中断的穿透。每个中间件都必须在其核心逻辑中调用 call_next(request)，除非遇到需要立即拦截的场景（如鉴权失败）。这确保了整个洋葱结构能够被完整地遍历。

2.5. 洋葱责任链模式在LangChain Middleware中的优势体现

洋葱责任链模式为 LangChain Middleware 带来了三大核心优势：可组合性、强扩展性和高类型安全性。其架构核心依赖三个组件：

1. Middleware 装饰器：最简洁的中间件实现方式。
2. Middleware 类：适用于有状态、逻辑复杂的场景。
3. MiddlewareChain：负责任务繁重的多中间件有序组合与嵌套。

2.6 LangChain Middleware核心特性

1. 横切逻辑复用：将日志、重试、安全拦截等通用逻辑独立封装，告别重复实现。
2. 灵活组合：通过 MiddlewareChain 实现同步/异步中间件的有序编排。
3. 全局管控：可以作用于单个 Runnable，也可以全局配置，对整个 Agent 流程进行统一拦截。
4. 错误统一处理：可以在中间件层统一捕获异常，实现重试、降级等容错机制，让核心业务代码更干净。

三、DeerFlow最新源码解析：14层洋葱中间件层

如果说 LangChain 提供的是“通用范式”，那么 DeerFlow 2.0 则进行了一次严肃的“工程化落地”。它基于 LangChain Middleware 架构进行了深度定制与扩展，采用了严格有序的 14 层洋葱中间件设计。这 14 层中间件将“流程管控、安全拦截、状态管理、工具调用过滤”四大能力，拆解为一个个职责极其单一的中间件。

DeerFlow 的这种“僵硬”是深思熟虑的：与 LangChain 的“松散组合”不同，它的 14 层中间件执行顺序是硬编码在源码中的。为什么？因为部分外层中间件的工作依赖于内层中间件注入的状态。这种看似牺牲了灵活性的设计，实则避免了隐式约定带来的维护噩梦，体现了生产级系统设计的严谨性。

3.1 DeerFlow 14层洋葱中间件核心设计理念

DeerFlow 中间件层严格遵循三大设计原则：

1. 洋葱模型复用：完全继承 LangChain 中间件的“请求穿透、响应回溯”双向处理模式。
2. 严格顺序设计：14 层中间件的执行顺序由 _build_middlewares() 函数静态确定，不可更改。
3. 单一职责原则：每个中间件只专注于一件事，如“循环检测”、“工具过滤”、“安全拦截”，绝不多管闲事。
   它的核心价值在于：将所有非核心业务逻辑从主流程剥离，让核心的 Agent 逻辑极度简洁，同时通过“插件化”的中间件组合实现能力的无限扩展。

3.2 DeerFlow中间件层与LangChain中间件的关联与差异

DeerFlow 与 LangChain 共享“洋葱模型”和“Runnable 包装器”的设计基础，且其诸多能力（如摘要）都源于 LangChain 理念。两者的核心差异在于：

• 执行顺序：LangChain 是松散、可调的；DeerFlow 是严格固定、硬编码的。
• 职责与目标：LangChain 是通用化的，目标是为各类 Runnable 提供横切逻辑；DeerFlow 是业务化定制的，专注于解决 Super Agent 场景下的具体工程问题（如死循环、并发超限）。
• 状态管理：LangChain 是轻量的，主要依赖 RunnableConfig；DeerFlow 是重度的，需要维护线程级、对话级的复杂状态。

3.4 DeerFlow中间件层的核心价值

1. 流程可控性：通过 LoopDetectionMiddleware 等解决了 LangChain 原生未充分覆盖的死循环等问题。
2. 系统稳定性：通过沙盒隔离、工具过滤等构建了多维度防护，经受了字节跳动内部亿级流量的验证。
3. 可维护与可扩展性：单一职责让结构清晰，严格顺序避免了隐式依赖的 Bug，新增功能只需增加新插件。

四：DeerFlow 14层洋葱中间件详细解析 + 深度解析

接下来，我们将逐一解析这 14 层中间件，包括其源码核心逻辑，带你进行一场可落地的深度技术之旅。

层级	中间件名称（源码类名）	核心职责	源码核心逻辑摘要
1	ThreadDataMiddleware	状态管理：架构基石，注入 thread_id 并创建线程隔离的工作目录。	为后续所有需要线程隔离的中间件（如沙盒、上传）提供根依赖。
2	SandboxMiddleware	安全拦截+状态管理：为当前线程获取或创建独立的代码执行沙盒。	必须依赖 ThreadDataMiddleware；通过 sandbox_provider 获取沙盒实例，实现 100% 执行隔离。
3	UploadsMiddleware	状态管理：扫描线程专属上传目录，将文件信息注入对话上下文。	让 LLM 能“看见”用户上传的文件，支撑文件相关的工具调用。
4	TokenUsageMiddleware	状态管理：全链路拦截并统计模型调用的 Token 消耗。	非阻塞设计，后置统计，不影响主流程性能，用于成本管控。
5	MemoryMiddleware	状态管理：将对话消息异步入队并持久化，支撑 Agent 长期记忆。	非阻塞式写入，存储失败不影响主流程；过滤掉系统等无效消息。
6	TitleMiddleware	状态管理：首次人机交互后，自动调用 LLM 生成对话标题。	通过标记位 self.title_generated 确保单次执行，节省 Token。
7	ViewImageMiddleware	状态管理：为视觉模型将图片数据（如本地路径）注入对话上下文。	条件性中间件，仅在 enable_vision 开启时工作，将图片转为 Base64。
8	DanglingToolCallMiddleware	流程管控：自动修复悬空的工具调用。	检查 AIMessage 中的 tool_calls 后是否无响应，有则注入占位 ToolMessage。
9	SummarizationMiddleware	流程管控：在上下文字数接近上限时，自动触发 LLM 摘要压缩。	实时监控，超阈值即压缩，并在 LLM 摘要失败等边界情况下保留原始上下文以容错。
10	TodoMiddleware	流程管控：在 Plan 模式下，自动为 Agent 注入 write_todos 工具。	跟踪多步骤任务的执行进度，仅在 Plan 模式生效，避免浪费。
11	DeferredToolFilterMiddleware	工具调用过滤：工具过多时延迟暴露，配合 tool_search 实现按需检索。	将 RAG 思路应用于工具层，减少 Token 浪费，提升工具选择准确率。
12	SubagentLimitMiddleware	流程管控+安全拦截：对子 Agent 的创建进行“熔断”和“截断”。	硬限制并发数，并阻止子 Agent 再创建孙 Agent，防止递归耗尽资源。
13	LoopDetectionMiddleware	流程管控：滑动窗口 Hash 驱动的死循环检测与强制退出机制。	对工具调用进行归一化 Hash 比对，连续 5 次重复则强制清空工具调用，逼 LLM 输出答案。
14	ClarificationMiddleware	流程管控：拦截 ask_clarification 工具调用，中断流程并引导用户。	必须作为最后一层中间件，避免拦截其他中间件的核心逻辑。

接下来，我们来解读几个关键中间件的源码级执行链路与分层架构。

4.0、DeerFlow 14个中间件总执行顺序与分层架构

这 14 个中间件的执行顺序严格遵循“基础依赖 → 状态增强 → 流程管控 → 安全兜底”的逻辑，其执行链路自上而下为：
ThreadDataMiddleware → SandboxMiddleware → UploadsMiddleware → TokenUsageMiddleware → MemoryMiddleware → TitleMiddleware → ViewImageMiddleware → DanglingToolCallMiddleware → SummarizationMiddleware → TodoMiddleware → DeferredToolFilterMiddleware → SubagentLimitMiddleware → LoopDetectionMiddleware → ClarificationMiddleware

可以将其分为三个功能层次：

• 基础层 (1-3)：ThreadData、Sandbox、Uploads，搭建起线程隔离、代码安全执行和文件操作的基石。
• 状态层 (4-7)：TokenUsage、Memory、Title、ViewImage，负责对话状态的增强与持久化。
• 管控层 (8-14)：DanglingToolCall、Summarization、Todo、DeferredToolFilter、SubagentLimit、LoopDetection、Clarification，全方位保障流程的稳定、有序和高效。

五、整体架构总结

这 14 层中间件构成了一个精密运转的洋葱式防护与增强体系。DeerFlow 没有止步于 LangChain 提供的通用能力，而是直面生产环境的复杂性，将流程图化、安全拦截和状态管理等难题，以“插件化”的组合方式优雅地解决。它证明了，一个好的架构，不仅在于提供灵活的扩展点，更在于能为这些扩展点的有序协作提供坚实的保障。