从 Harness Engineering 看 DeerFlow 2.0：AI 智能体的生产级解决方案系统性地剖析 De

一、背景

1.1 Harness Engineering：AI Agent 工程的新范式

2025-2026年，AI Agent 领域正在经历一场深刻的范式转移——从”如何构建Agent”到“如何让Agent稳定运行”。这一转变催生了Harness Engineering（驾驭工程），一个专注于构建让 Agent 稳定运行的完整基础设施的技术理念和工程范式。在 AI 技术栈中，Harness指的是除大模型本身之外，所有让 Agent 能够执行任务的基础设施——包括状态管理、工具执行、反馈循环、强制约束、sub-agents 协同等。如果把 AI 体系与计算机硬件做类比：

LLM是 CPU，提供原始算力
上下文窗口是 RAM，决定信息边界
Agent Harness是操作系统，负责上下文治理、工具驱动、流程调度
AI Agent是应用程序，在 Harness 提供的标准化环境中运行

1.2 DeerFlow 2.0：Super Agent Harness 的开源实践

字节开源的 DeerFlow 2.0 提供了一个完整的 Harness Engineering 实践方案。DeerFlow 最初作为 Deep Research 框架诞生，但很快被推向更广阔的领域——数据管道、幻灯片生成、仪表盘、内容工作流自动化。这些应用场景揭示了一个事实：DeerFlow 2.0 的真正价值在于它是一个 Super Agent Harness（超级智能体驾驭层） ——它把 sub-agents（子智能体）、memory（记忆系统）和 sandbox（沙箱环境）组织在一起，再配合可扩展的 skills（技能系统），让 Agent 可以完成复杂多样的任务。

本文在 AI Coding Agent 协助下系统性地剖析 DeerFlow 2.0 的 Harness 架构与实现细节，辅助理解 DeerFlow 的工程实践与技术精髓。

二、DeerFlow 2.0 总体架构

DeerFlow 2.0 采用微服务架构设计，以 Nginx 作为统一入口，将请求路由到三个核心服务：

2.1 核心服务组件

1. LangGraph Server (智能体运行时)

基于 LangGraph 构建的 Agent 运行时环境
负责任务编排、线程状态管理、工具执行协调
支持 SSE 流式响应，实现实时交互
入口点：packages/harness/deerflow/agents/lead_agent/agent.py:make_lead_agent``

2. Gateway API (REST 接口层)

FastAPI 构建的 RESTful API 服务
提供模型管理、MCP 配置、技能管理、文件上传等非 Agent 操作
入口点：app/gateway/app.py``

3. Frontend (用户界面)

Next.js + React 构建的现代化 Web 界面
提供对话界面、模型选择、技能管理等功能

2.2 配置体系

DeerFlow 采用分层配置设计：

config.yaml：核心配置文件，包含模型、工具、沙箱、技能等配置
extensions_config.json：扩展配置，包含 MCP 服务器、技能状态等动态配置

配置支持环境变量替换（$VAR_NAME），确保敏感信息不会硬编码。

三、核心系统详解

3.1 智能体运行时架构

DeerFlow 的智能体运行时是整个系统的核心大脑，采用中间件链式架构设计：

# 源码：packages/harness/deerflow/agents/lead_agent/agent.py
def make_lead_agent(config: RunnableConfig):
    # 1. 模型创建
    model = create_chat_model(name=model_name, thinking_enabled=thinking_enabled)
    
    # 2. 工具加载
    tools = get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled)
    
    # 3. 中间件链构建
    middleware = _build_middlewares(config, model_name=model_name, agent_name=agent_name)
    
    # 4. 系统提示词组装
    system_prompt = apply_prompt_template(...)
    
    # 5. 创建 Agent
    return create_agent(
        model=model,
        tools=tools,
        middleware=middleware,
        system_prompt=system_prompt,
        state_schema=ThreadState,
    )

3.1.1 中间件链

中间件链是 DeerFlow 的核心设计之一，采用责任链模式处理请求：

关键中间件详解：

中间件	职责	触发条件
ThreadDataMiddleware	初始化线程数据目录	每次请求
UploadsMiddleware	注入上传文件列表到上下文	有上传文件时
SandboxMiddleware	获取/创建沙箱环境	每次请求
SummarizationMiddleware	上下文窗口压缩	接近 token 限制时
TitleMiddleware	自动生成对话标题	首次对话后
TodoListMiddleware	任务列表管理	计划模式启用时
MemoryMiddleware	长期记忆更新	对话结束后
SubagentLimitMiddleware	限制并行子智能体数量	子智能体启用时
LoopDetectionMiddleware	检测并打破工具调用循环	每次请求

3.1.2 线程状态管理

DeerFlow 扩展了 LangGraph 的 AgentState，定义了了 ThreadState：

class ThreadState(AgentState):
    # 核心状态（继承自 AgentState）
    messages: list[BaseMessage]
    
    # DeerFlow 扩展
    sandbox: dict             # 沙箱环境信息
    artifacts: list[str]      # 生成的文件路径
    thread_data: dict         # {workspace, uploads, outputs} 路径
    title: str | None         # 自动生成的对话标题
    todos: list[dict]         # 任务追踪（计划模式）
    viewed_images: dict       # 视觉模型图像数据

3.1.3 自定义 Agent

DeerFlow 提供了完整的自定义 Agent 创建流程，用户可通过前端界面直观创建，系统会自动生成必要的配置文件。

创建流程：

前端发起：用户在 Agents 页面点击”New Agent”按钮，进入创建流程
智能引导：通过对话模式引导用户定义 Agent 的个性、能力和行为准则
配置生成：系统自动生成以下文件：

-config.yaml：存储 Agent 配置（名称、描述、模型选择、工具组等）
-SOUL.md：定义 Agent 个性、价值观和行为边界
-memory.json：运行时生成的记忆数据

存储结构：

backend/.deer-flow/agents/
└── my-custom-agent/           # Agent 名称目录
    ├── config.yaml            # 配置文件
    ├── SOUL.md                # 个性定义文件
    └── memory.json            # 记忆数据（运行时生成）

核心配置项：
-name：Agent 唯一标识符（小写，仅包含字母、数字和连字符）
-description：Agent 功能描述
-model：可选的模型覆盖（默认使用全局配置）
-tool_groups：工具组白名单（如 web、file:read 等）
-SOUL.md：包含 Agent 个性、价值观和行为准则的详细定义

API 接口：
-POST /api/agents：创建自定义 Agent
-GET /api/agents：列出自定义 Agent
-GET /api/agents/{name}：获取 Agent 详情
-PUT /api/agents/{name}：更新 Agent 配置
-DELETE /api/agents/{name}：删除 Agent

技术实现：

-后端通过 agents.py 路由处理 Agent CRUD 操作-配置文件使用 YAML 格式存储-SOUL.md 内容会注入到 Lead Agent 的系统提示中-支持模型和工具组的精细控制

3.2 沙箱系统 (Sandbox)

沙箱系统为 Agent 提供隔离的执行环境，支持三种运行模式：

3.2.1 架构抽象

3.2.2 虚拟路径映射

沙箱内部使用统一的虚拟路径，与宿主机路径解耦：

虚拟路径	物理路径（宿主机）
`/mnt/user-data/workspace`	`backend/.deer-flow/threads/{thread_id}/user-data/workspace`
`/mnt/user-data/uploads`	`backend/.deer-flow/threads/{thread_id}/user-data/uploads`
`/mnt/user-data/outputs`	`backend/.deer-flow/threads/{thread_id}/user-data/outputs`
`/mnt/skills`	`deer-flow/skills/`

3.2.3 执行模式对比

模式	隔离级别	适用场景	启动速度
Local	进程级	开发调试	即时
Docker	容器级	生产环境	秒级
K8s	Pod级	大规模部署	秒级

3.3 技能系统 (Skills)

技能系统是 DeerFlow 的模块化能力扩展机制，通过 Markdown 文件定义工作流和最佳实践，使系统能够快速适应各种专业领域的任务需求。

3.3.1 系统架构

技能目录结构：

skills/
├── public/          # 内置技能（随仓库发布，只读）
│   ├── skill-creator/       # 技能创建器
│   ├── deep-research/       # 深度研究技能
│   ├── ppt-generation/      # PPT生成技能
│   ├── image-generation/    # 图像生成技能
│   ├── video-generation/    # 视频生成技能
│   ├── frontend-design/     # 前端设计技能
│   └── ...
└── custom/          # 自定义技能（用户安装，gitignored）
    ├── my-skill/            # 示例自定义技能
    │   ├── SKILL.md         # 技能定义文件
    │   ├── scripts/         # 辅助脚本
    │   ├── references/      # 参考资料
    │   └── assets/          # 资源文件
    └── ...

核心组件：
-SKILL.md：技能定义文件，包含元数据和执行指令
-技能加载器：扫描目录并加载技能
-技能安装器：处理自定义技能的打包和安装

3.3.2 SKILL.md 格式

技能定义文件采用 YAML 前置元数据 + Markdown 内容的格式：

---
name: deep-research               # 技能唯一标识符
description: Use this skill for questions requiring web research...  # 触发条件和功能描述
license: MIT                      # 许可证信息
allowed-tools:                    # 允许使用的工具列表
  - web_search
  - web_fetch
  - bash
---

# Skill Instructions

## When to Use This Skill
详细说明何时应该使用该技能

## Core Principles
技能的核心原则和设计理念

## Implementation Steps
具体的执行步骤和最佳实践

## Output Requirements
期望的输出格式和质量标准

3.3.3 技能加载机制

加载流程：

目录扫描：递归扫描 public 和 custom 目录
文件解析：解析每个 SKILL.md 文件的元数据和内容
状态更新：根据 extensions_config.json 更新技能启用状态
技能注册：将技能添加到可用技能列表

核心代码：

def load_skills(skills_path: Path | None = None) -> list[Skill]:
    """加载所有技能"""
    skills = []
    
    # 扫描 public 和 custom 目录
    for category in ["public", "custom"]:
        category_path = skills_path / category
        for root, dirs, files in os.walk(category_path):
            if "SKILL.md" in files:
                skill_file = Path(root) / "SKILL.md"
                skill = parse_skill_file(skill_file, category=category)
                skills.append(skill)
    
    # 根据配置更新启用状态
    extensions_config = ExtensionsConfig.from_file()
    for skill in skills:
        skill.enabled = extensions_config.is_skill_enabled(skill.name, skill.category)
    
    return skills

3.3.4 内置技能

核心内置技能：

技能名称	功能描述	应用场景
skill-creator	引导用户创建自定义技能	技能开发
deep-research	提供系统化的多维度研究方法	深度调研
ppt-generation	生成专业演示文稿	报告制作
image-generation	创建和编辑图像	视觉设计
video-generation	生成和处理视频	多媒体内容
frontend-design	设计前端界面和组件	网页开发

Deep Research 技能：

Phase 1: Broad Exploration - 广泛收集相关信息
Phase 2: Deep Dive - 深入分析核心问题
Phase 3: Diversity & Validation - 多角度验证信息
Phase 4: Synthesis Check - 综合总结研究结果

3.3.5 自定义技能创建

创建流程：

前端发起：用户在设置页面点击”创建技能”按钮，进入 mode=skill 对话模式
智能引导：skill-creator 技能通过对话引导用户：
- 捕获用户意图（技能用途、触发条件、输出格式）
- 编写 SKILL.md 文件和相关资源
- 创建测试用例验证技能效果
- 迭代改进直到用户满意
打包安装：
- 使用 package_skill.py 脚本将技能目录打包成 .skill 文件（ZIP 格式）
- 通过 POST /api/skills/install API 提交安装请求
- 后端 install_skill_from_archive 函数处理解压、验证和安装

3.4 工具系统 (Tools)

3.4.1 工具分类

DeerFlow 的工具系统根据其来源和加载方式可分为以下几类：

内置工具 (Built-in Tools)

内置工具是系统默认提供的基础工具，无需额外配置即可使用：

工具	功能	来源
`present_file`	向用户展示文件	`deerflow/tools/builtins/`
`ask_clarification`	请求用户澄清	`deerflow/tools/builtins/`
`view_image`	查看图像（视觉模型支持）	`deerflow/tools/builtins/`
`task`	创建和管理子任务（子智能体启用时）	`deerflow/tools/builtins/`
`tool_search`	搜索可用工具（工具搜索启用时）	`deerflow/tools/builtins/`

配置工具 (Configured Tools)

配置工具是通过配置文件定义的工具，需要在 config.yaml 中配置：

工具	功能	来源
`bash`	执行 shell 命令	`deerflow/sandbox/tools.py`
`read_file`	读取文件内容	`deerflow/sandbox/tools.py`
`write_file`	写入文件内容	`deerflow/sandbox/tools.py`
`str_replace`	字符串替换	`deerflow/sandbox/tools.py`
`ls`	列出目录内容	`deerflow/sandbox/tools.py`
`web_search`	网络搜索（支持 Tavily、DuckDuckGo 等）	`deerflow/community/`
`web_fetch`	网页内容获取（支持 Jina AI、Firecrawl 等）	`deerflow/community/`

MCP 工具 (MCP Tools)

MCP 工具是通过 Model Context Protocol 集成的外部工具，需要在 extensions_config.json 中配置：

工具类型	功能	配置方式
第三方服务工具	提供各种专业功能	通过 MCP 服务器配置
自定义脚本工具	执行用户自定义逻辑	通过本地 MCP 服务器配置
云服务工具	访问云服务 API	通过远程 MCP 服务器配置

3.4.2 MCP 集成

DeerFlow 支持通过 Model Context Protocol (MCP) 集成外部工具：

def build_servers_config(extensions_config: ExtensionsConfig) -> dict:
    """构建 MCP 服务器配置"""
    enabled_servers = extensions_config.get_enabled_mcp_servers()
    
    servers_config = {}
    for server_name, server_config in enabled_servers.items():
        servers_config[server_name] = build_server_params(server_name, server_config)
    
    return servers_config

支持三种传输协议：
-stdio：本地命令行工具
-sse：Server-Sent Events 远程服务
-http：HTTP 远程服务（支持 OAuth 认证）

3.4.3 MCP 服务器扩展

在 extensions_config.json 中添加 MCP 服务器：

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
    }
  }
}

3.5 子智能体系统 (Sub-Agents)

子智能体是 DeerFlow 处理复杂任务的核心机制，通过动态生成专业化的子智能体来分解和并行处理复杂任务，提高系统的整体能力和效率。

3.5.1 动态生成机制

DeerFlow 的子智能体动态生成机制基于以下核心流程：

1. 主智能体初始化

主智能体在创建时通过配置参数 subagent_enabled 决定是否启用子智能体功能
当启用时，会加载 task_tool 工具到可用工具列表中

# 源码：packages/harness/deerflow/agents/lead_agent/agent.py
# 主智能体创建过程
def make_lead_agent(config: RunnableConfig):
    # ...
    subagent_enabled = cfg.get("subagent_enabled", False)
    max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
    # ...
    # 加载工具，包括子智能体工具
    tools=get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled),
    # ...
    # 添加子智能体限制中间件
    if subagent_enabled:
        middlewares.append(SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents))
    # ...

2. 子智能体工具注册

当 subagent_enabled 为 True 时，get_available_tools 函数会加载 task_tool
task_tool是创建和管理子智能体的核心工具

# 源码：packages/harness/deerflow/tools/tools.py
# 工具加载过程
def get_available_tools(
    groups: list[str] | None = None,
    include_mcp: bool = True,
    model_name: str | None = None,
    subagent_enabled: bool = False,
) -> list[BaseTool]:
    # ...
    # 仅当启用时添加子智能体工具
    if subagent_enabled:
        builtin_tools.extend(SUBAGENT_TOOLS)  # SUBAGENT_TOOLS 包含 task_tool
        logger.info("Including subagent tools (task)")
    # ...

3. 子智能体创建与执行

主智能体通过调用 task_tool 来创建子智能体
task_tool 接收任务描述、提示词和子智能体类型等参数
根据参数动态创建对应的子智能体配置和执行环境

# 源码：packages/harness/deerflow/tools/builtins/task_tool.py
@tool("task", parse_docstring=True)
async def task_tool(
    runtime: ToolRuntime[ContextT, ThreadState],
    description: str,
    prompt: str,
    subagent_type: Literal["general-purpose", "bash"],
    tool_call_id: Annotated[str, InjectedToolCallId],
    max_turns: int | None = None,
) -> str:
    """Delegate a task to a specialized subagent that runs in its own context."""
    # 获取子智能体配置
    config = get_subagent_config(subagent_type)
    if config is None:
        return f"Error: Unknown subagent type '{subagent_type}'. Available: general-purpose, bash"
    
    # 构建配置覆盖
    overrides: dict = {}
    # ...
    
    # 获取可用工具（排除 task_tool 以防止嵌套）
    tools = get_available_tools(model_name=parent_model, subagent_enabled=False)
    
    # 创建执行器
    executor = SubagentExecutor(
        config=config,
        tools=tools,
        parent_model=parent_model,
        sandbox_state=sandbox_state,
        thread_data=thread_data,
        thread_id=thread_id,
        trace_id=trace_id,
    )
    
    # 启动后台执行
    task_id = executor.execute_async(prompt, task_id=tool_call_id)
    # ...

4. 子智能体执行引擎

SubagentExecutor 负责实际创建和执行子智能体
为每个子智能体创建独立的 Agent 实例和执行环境
支持同步和异步执行模式

# 源码：packages/harness/deerflow/subagents/executor.py
class SubagentExecutor:
    """子智能体执行引擎"""

    def __init__(
        self, config, tools, parent_model, sandbox_state, thread_data, thread_id, trace_id
    ):
        # 初始化执行器
        # ...
        # 过滤工具
        self.tools = _filter_tools(tools, config.tools, config.disallowed_tools)

    def _create_agent(self):
        """创建智能体实例"""
        model_name = _get_model_name(self.config, self.parent_model)
        model = create_chat_model(name=model_name, thinking_enabled=False)
        
        middlewares = build_subagent_runtime_middlewares(lazy_init=True)
        
        return create_agent(
            model=model,
            tools=self.tools,
            middleware=middlewares,
            system_prompt=self.config.system_prompt,
            state_schema=ThreadState,
        )

    def execute_async(self, task: str, task_id: str | None = None) -> str:
        """在后台启动任务执行"""
        # 创建初始待处理结果
        result = SubagentResult(
            task_id=task_id,
            trace_id=self.trace_id,
            status=SubagentStatus.PENDING,
        )
        
        # 提交到调度池
        def run_task():
            # 执行子智能体任务
            # ...
        
        _scheduler_pool.submit(run_task)
        return task_id

3.5.2 执行状态管理

子智能体的执行状态通过 SubagentResult 类进行管理，包含完整的执行生命周期信息：

@dataclass
class SubagentResult:
    task_id: str              # 任务唯一标识
    trace_id: str             # 分布式追踪ID
    status: SubagentStatus    # PENDING/RUNNING/COMPLETED/FAILED/TIMED_OUT
    result: str | None        # 执行结果
    error: str | None         # 错误信息
    started_at: datetime      # 开始时间
    completed_at: datetime    # 完成时间
    ai_messages: list[dict]   # 完整的AI消息记录

状态流转：
PENDING → RUNNING → COMPLETED (成功)
PENDING → RUNNING → FAILED (执行失败)
PENDING → RUNNING → TIMED_OUT (执行超时)

3.5.3 并发控制与资源管理

DeerFlow 采用双线程池设计管理子智能体执行：

# 调度线程池 - 负责任务调度和编排
_scheduler_pool = ThreadPoolExecutor(max_workers=3, thread_name_prefix="subagent-scheduler-")

# 执行线程池 - 负责实际子智能体执行
_execution_pool = ThreadPoolExecutor(max_workers=3, thread_name_prefix="subagent-exec-")

并发控制机制：
1.线程池隔离：调度和执行分离，提高系统稳定性
2.并行限制：通过 SubagentLimitMiddleware 限制最大并行子智能体数量（默认为3）
3.超时控制：每个子智能体执行有超时设置，防止任务无限执行
4.资源清理：任务完成后自动清理背景任务，防止内存泄漏

3.5.4 子智能体类型与应用场景

DeerFlow 支持多种类型的子智能体，每种类型针对特定场景优化：

子智能体类型	描述	应用场景
general-purpose	通用型子智能体，具备完整的工具集和推理能力	复杂多步骤任务、深度研究、综合分析
bash	命令执行专家，专注于执行 shell 命令	Git 操作、构建过程、文件系统操作

使用建议：

对于需要复杂推理和多工具协作的任务，选择 general-purpose
对于需要执行大量命令或产生冗长输出的任务，选择 bash
子智能体适用于复杂、独立、无需用户交互的任务
简单任务应直接使用工具，避免子智能体开销

3.5.5 子智能体与主智能体的协同

数据传递：

子智能体继承父智能体的沙箱状态和线程数据
子智能体的执行结果通过 task_tool 返回给主智能体
支持实时状态更新，主智能体可以监控子智能体执行进度

执行模式：

同步执行：主智能体等待子智能体完成后继续执行
异步执行：主智能体可以并行启动多个子智能体，然后收集结果

最佳实践：

将复杂任务分解为多个子任务，并行执行以提高效率
为每个子智能体分配明确的职责和目标
设置合理的超时时间，避免单个子任务阻塞整个流程
利用子智能体的隔离性，处理可能产生大量输出的任务

子智能体系统是 DeerFlow 实现复杂任务处理的关键机制，通过动态生成和管理专业化的子智能体，大大提高了系统的处理能力和效率。

3.6 模型工厂 (Model Factory)

DeerFlow 的模型系统采用工厂模式设计，支持多种 LLM 提供商：

def create_chat_model(
    name: str | None = None,
    thinking_enabled: bool = False,
    reasoning_effort: str | None = None
) -> BaseChatModel:
    """创建聊天模型实例"""
    # 1. 解析模型配置
    model_config = app_config.get_model_config(name)
    
    # 2. 动态加载模型类
    model_class = resolve_class(model_config.use)
    
    # 3. 构建初始化参数
    kwargs = build_model_kwargs(model_config, thinking_enabled, reasoning_effort)
    
    # 4. 实例化模型
    return model_class(**kwargs)

3.6.1 支持的模型提供商

提供商	类路径	特殊支持
OpenAI	`langchain_openai:ChatOpenAI`	Responses API
Anthropic	`langchain_anthropic:ChatAnthropic`	Thinking 模式
DeepSeek	`langchain_deepseek:ChatDeepSeek`	Thinking 模式
Claude Code	`deerflow.models.claude_provider:ClaudeChatModel`	OAuth 认证
Codex CLI	`deerflow.models.openai_codex_provider:CodexChatModel`	CLI 集成

3.6.2 Thinking 模式支持

对于支持推理的模型，DeerFlow 提供统一的 thinking_enabled 参数：

models:
  - name: deepseek-v3
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

3.7 记忆系统 (Memory)

DeerFlow 的记忆系统实现跨会话长期记忆，让 Agent 能够记住用户的偏好、习惯和上下文。

3.7.1 记忆更新流程

class MemoryMiddleware(AgentMiddleware):
    """记忆中间件 - 在对话结束后更新记忆"""
    
    async def on_chain_end(self, outputs, **kwargs):
        # 1. 提取对话中的关键信息
        facts = extract_facts(outputs["messages"])
        
        # 2. 去重处理
        new_facts = [f for f in facts if f not in existing_memory]
        
        # 3. 更新记忆存储
        await update_memory(new_facts)

3.7.2 记忆内容类型

-用户画像：身份、职业、技术栈
-偏好设置：输出格式、语言风格、详细程度
-事实知识：项目信息、历史上下文
-对话摘要：重要对话的总结

3.8 上下文管理

DeerFlow 实现了多层次的上下文管理机制，确保在长对话中保持高效和准确。

3.8.1 上下文压缩 (Summarization)

当对话接近上下文窗口限制时，自动触发压缩：

SummarizationMiddleware(
    model=summarization_model,      # 用于总结的轻量级模型
    trigger=[                       # 触发条件
        ("tokens", 120000),         # token 数量超过阈值
        ("messages", 50),           # 消息数量超过阈值
    ],
    keep=("messages", 10),          # 保留最近 N 条消息
    trim_tokens_to_summarize=80000, # 每次总结的 token 数
)

3.8.2 上下文剪枝 (Context Pruning)

配置化的上下文剪枝策略：

context_pruning:
  mode: "cache-ttl"           # 基于 TTL 的缓存模式
  ttl: "5m"                   # 5分钟 TTL
  keep_last_assistants: 3     # 保护最近3条助手消息
  soft_trim_ratio: 0.3        # 上下文占用 >30% 触发软修剪
  hard_clear_ratio: 0.5       # 上下文占用 >50% 触发硬清除

3.9 即时通讯通道 (IM Channels)

DeerFlow 支持从多种即时通讯应用接收任务，无需公网 IP。配置完成后，对应渠道会自动启动，为用户提供便捷的聊天界面交互方式。

支持的通道

通道	传输方式	难度
Telegram	Bot API (长轮询)	简单
Slack	Socket Mode	中等
Feishu / Lark	WebSocket	中等

支持的命令

在已连接的即时通讯应用中，用户可以使用以下命令与 DeerFlow 交互：

命令	描述
`/new`	开始新对话
`/status`	显示当前线程信息
`/models`	列出可用模型
`/memory`	查看记忆
`/help`	显示帮助

注：没有命令前缀的消息会被当作普通聊天处理，DeerFlow 会自动创建 thread 并以对话方式回复。

四、执行模式

DeerFlow 2.0 提供四种执行模式，适应不同复杂度的任务：

模式	thinking_enabled	is_plan_mode	subagent_enabled	适用场景
Flash	false	false	false	快速问答、简单任务
Standard	true	false	false	标准对话、一般任务
Pro	true	true	false	复杂任务、需要规划
Ultra	true	true	true	深度研究、多步骤任务

4.1 计划模式 (Plan Mode)

启用计划模式时，DeerFlow 使用 TodoListMiddleware 追踪任务进度：

class TodoMiddleware(AgentMiddleware):
    """任务列表中间件"""
    
    def __init__(self):
        self.system_prompt = """
        <todo_list_system>
        You have access to the `write_todos` tool to help you manage and track complex multi-step objectives.
        
        **CRITICAL RULES:**
        - Mark todos as completed IMMEDIATELY after finishing each step
        - Keep EXACTLY ONE task as `in_progress` at any time
        - Update the todo list in REAL-TIME as you work
        - DO NOT use this tool for simple tasks (< 3 steps)
        </todo_list_system>
        """

4.2 子智能体模式 (Sub-Agent Mode)

在 Ultra 模式下，主智能体可以生成子智能体并行处理子任务：

# 主智能体生成子智能体
task_tool.invoke({
    "name": "research_subtask",
    "prompt": "研究主题A的相关信息",
    "async": True  # 异步执行
})

# 子智能体独立执行
subagent_executor.execute_async(task)

# 主智能体收集结果
results = poll_subagent_results(task_ids)

五、部署与运维

5.1 Docker 部署

开发环境（热重载、源码挂载）：

make docker-init    # 拉取沙箱镜像make docker-start   # 启动服务

生产环境（本地构建镜像）：

make up     # 构建并启动make down   # 停止并移除

5.2 配置热重载

DeerFlow 支持配置热重载，修改 config.yaml 后无需重启服务即可生效。

5.3 监控与追踪

集成 LangSmith 进行可观测性追踪：

LANGSMITH_TRACING=trueLANGSMITH_API_KEY=lsv2_pt_xxxxxxxxLANGSMITH_PROJECT=deerflow-prod

六、总结

DeerFlow 2.0 是一个生产级的超级智能体 Harness，其技术架构体现了以下核心设计理念：

模块化设计：中间件链、技能系统、工具系统均可独立扩展
隔离与安全：沙箱系统、线程隔离、路径防护确保安全性
可观测性：LangSmith 集成、详细日志、追踪ID支持
多模态支持：文本、图像、文件上传、网页浏览
灵活部署：本地开发、Docker、Kubernetes 多种部署模式

DeerFlow 2.0 不仅是一个 Deep Research 工具，更是一个完整的 Agent 运行时环境。对于希望构建复杂 AI 应用的开发者来说，DeerFlow 2.0 提供了一个坚实的起点——开箱即用，又足够灵活以满足定制需求。

相关链接：

本文首发于我的微信公众号「StackBreath Studio」，后续会持续同步同类技术/实战文章。感兴趣的朋友可以关注。

扫码_搜索联合传播样式-白色版.png