企业官网建设流程全解析

• 人工智能
• AI Agent
• AI 应用
• 多智能体
• Agent 编排
• Agent 沙箱
• Agent 记忆
• AI 技能

DeerFlow 2.0 Enhanced 是一款基于 LangGraph 构建的开源超级智能体（Super Agent）框架，它通过编排子智能体、沙箱与记忆系统，借助可扩展的技能（Skills）完成几乎任何任务。本文带你从代码一路走到运行时，深度剖析 DeerFlow 的三层服务架构、Agent 构建入口make_lead_agent，以及那条决定 Agent 行为质量的10 层中间件链（Middleware Chain）——即使你是新手，也能看懂每一层在做什么、为什么要排在这个位置。

一、先认识 DeerFlow 的运行时全景

DeerFlow 的运行时由三个核心服务组成，全部由 Nginx 统一反向代理（端口 2026）：

Client (Browser) │ ▼ Nginx (2026) ┌──┴───────────────┐ ▼ ▼ LangGraph Server Gateway API Frontend (2024) (8001) (3000)

完整架构图见官方文档：backend/docs/ARCHITECTURE.md。

💡 理解这个拓扑是关键：所有"智能"发生在 LangGraph Server 里，中间件链就是它的灵魂；Gateway 只负责"杂务"。

二、从代码到运行时：Agent 的诞生路径

打开 backend/langgraph.json，你会发现整个 Agent 的入口只有一行声明：

{ "graphs": { "lead_agent": "deerflow.agents:make_lead_agent" }, "checkpointer": { "path": "./packages/harness/deerflow/agents/checkpointer/async_provider.py:make_checkpointer" } }

这就是 DeerFlow"代码即运行时"的精髓：

1. make_lead_agent(config)：每次运行（run）时动态构建 Agent，接收模型名、思考模式、计划模式、子智能体开关等参数。源码位于 agent.py#L262-L337；
2. 模型工厂create_chat_model()：根据 config.example.yaml 中的models配置，反射加载 LangChain 集成类（OpenAI / Anthropic / DeepSeek 等），无需改代码即可换模型；
3. 工具装配get_available_tools()：合并三类工具——内置工具（present_file、ask_clarification、view_image）、配置文件工具（bash、web_search）、MCP 工具；
4. 中间件链_build_middlewares()：本文的主角，见 agent.py#L207-L259；
5. 状态模式ThreadState：定义整条链共享的"黑匣子"。

最终调用 LangChain 的create_agent(model, tools, middleware, system_prompt, state_schema=ThreadState)，一个可运行的 LangGraph 图就出生了。

上图是 DeerFlow 在运行时中调用data-analysis技能、经沙箱执行 Python 脚本后落盘到outputs目录的真实产物——这正是中间件链为 Agent 铺设的"文件高速公路"。

三、10 层中间件链逐层剖析 🔍

DeerFlow 的中间件链由两段拼装而成：

• 基础运行时链（5 层）：由 tool_error_handling_middleware.py#L78-L103 中的build_lead_runtime_middlewares()构建；
• Lead Agent 专属链（5 层常驻 + 4 层条件挂载）：在_build_middlewares()中按序追加。

默认配置下（summarization.enabled: true，见 config.example.yaml#L356-L357），常驻激活的正好是 10 层，顺序如下：

还有 4 位"按需上场"的队员

DeerFlow 的设计哲学是能力可配置、默认最精简，以下中间件满足条件才加入链中：

• TodoMiddleware：开启 plan mode 时挂载，提供write_todos工具，为 3 步以上的复杂任务建立实时任务清单；
• ViewImageMiddleware：仅当所选模型supports_vision: true时挂载，在 LLM 调用前把view_image工具读入的图片（含 base64）以人类消息形式注入对话；
• DeferredToolFilterMiddleware：开启tool_search时挂载，从bind_tools中隐藏"延迟工具"的 schema，节省上下文 token，Agent 通过tool_search工具在运行时按需发现；
• SubagentLimitMiddleware：开启子智能体时挂载，用代码而非提示词硬性截断单次响应中超过上限（2~4 个）的并行task调用。

当模型支持视觉时，ViewImageMiddleware会让 LLM 像上图这样的图片直接"入眼"——无需用户额外要求描述图片内容。

四、中间件顺序为什么这么排？

顺序不是随意的，源码注释（agent.py#L197-L206）写得很清楚，背后的依赖关系可以归纳为三条铁律：

1. 数据先于消费者：ThreadDataMiddleware必须最先运行，因为UploadsMiddleware和SandboxMiddleware都依赖它产出的thread_id路径；
2. 修复先于消费：DanglingToolCallMiddleware必须在模型看到历史之前打好补丁，否则 LLM 会因消息格式不完整直接报错；ToolErrorHandlingMiddleware也必须在ClarificationMiddleware之前，先把异常转成ToolMessage，再谈流程控制；
3. 拦截必须最后：ClarificationMiddleware永远排在链尾——它要在模型调用完成后拦截澄清请求并中断整个执行（通过 LangGraph 的Command跳转到END），若排得太前就失去了"最后把关"的意义。

此外还有一个性能细节：ThreadDataMiddleware和SandboxMiddleware都支持lazy_init（默认为True）——只在真正需要时才创建目录、才真正获取沙箱（见 sandbox/middleware.py#L21-L30），纯聊天请求不会白白启动 Docker 容器。

五、ThreadState：串联整条链的共享状态 🧵

10 层中间件之间不直接通信，而是通过ThreadState读写共享状态。它继承自 LangChain 的AgentState，扩展字段定义在 thread_state.py#L48-L55：

artifacts和viewed_images还实现了自定义Reducer（合并去重 / 空字典即清空），这是 LangGraph 状态管理中最实用的技巧之一：让并发写入变得安全。

由present_file工具登记进artifacts字段的视频产物参考图，会实时出现在前端的产物面板中——中间件链在幕后，用户在台前。

六、新手探索路线图：从哪开始读源码？

按"由浅入深"的顺序，建议这样走：

1. 架构总览→ backend/docs/ARCHITECTURE.md（含请求流、沙箱、工具、MCP 全图）
2. 入口函数→ make_lead_agent
3. 中间件工厂→ _build_middlewares
4. 状态定义→ thread_state.py
5. 沙箱层→ backend/packages/harness/deerflow/sandbox/（local/本地执行、community/aio_sandbox/Docker 容器隔离）
6. 配置层→ config.example.yaml（模型、沙箱、摘要、标题等全部可调）

🧭 每个中间件都是一个独立文件，放在 backend/packages/harness/deerflow/agents/middlewares/，平均百行左右，非常适合当作学习 LangGraph Agent 中间件模式的范本——关注它的before_agent/after_agent/wrap_model_call/wrap_tool_call四个钩子，你就能看懂一切。

七、总结：这套架构好在哪？

• 关注点分离：Nginx 只管路由，Gateway 只管杂务，LangGraph Server 只管智能，三者独立扩缩容；
• 中间件即插件：想加"记忆"、"防循环"、"限并发"？写一个AgentMiddleware塞进链里即可，核心 Agent 逻辑零改动；
• 顺序即契约：10 层链的每个位置都有明确的依赖理由，注释即文档；
• 默认精简、按需增强：视觉、计划模式、子智能体能力全部条件挂载，不用的能力零开销；
• 状态驱动协作：中间件之间零耦合，全靠ThreadState上的字段与 Reducer 协作，天然适配 LangGraph 的检查点（Checkpointer）持久化。

看懂这条 10 层中间件链，你就拿到了 DeerFlow 2.0 的"发动机图纸"——剩下的 Skills、MCP、Channels 都只是往这条装配线上加装的新零件。🦌

• 人工智能
• AI Agent
• AI 应用
• 多智能体
• Agent 编排
• Agent 沙箱
• Agent 记忆
• AI 技能