博客 | xw

DeerFlow 子Agent委派实现说明

May 22, 2026

概述

DeerFlow的子Agent系统是基于LangGraph构建的任务委派机制，允许主Agent将复杂任务委托给专门的子Agent执行，实现上下文隔离、并行处理和专业化分工。

核心组件

组件	位置	职责
执行引擎	`packages/harness/deerflow/subagents/executor.py`	子Agent同步/异步执行、线程池管理、任务状态跟踪、超时控制
注册中心	`packages/harness/deerflow/subagents/registry.py`	管理可用子Agent配置，支持config.yaml配置覆盖
工具入口	`packages/harness/deerflow/tools/builtins/task_tool.py`	对外暴露`task`工具，是父Agent调用子Agent的统一入口
内置子Agent	`packages/harness/deerflow/subagents/builtins/`	提供两种开箱即用的子Agent类型：`general-purpose`（通用型）、`bash`（命令行专家）
限流中间件	`packages/harness/deerflow/agents/middlewares/subagent_limit_middleware.py`	强制限制最大并发子Agent数为3，避免资源耗尽

完整委派流程

1. 触发阶段：父Agent调用`task`工具

当父Agent需要委派任务时，调用task工具，传入参数：

description: 3-5字的任务简短描述（用于日志和前端展示）
prompt: 给子Agent的详细任务指令，需要具体明确
subagent_type: 子Agent类型（general-purpose或bash）
可选max_turns: 子Agent最大交互轮次，覆盖默认配置

2. 配置加载阶段

从注册中心获取对应类型的子Agent默认配置
应用config.yaml中的自定义配置（如超时时间覆盖）
注入当前已启用的技能提示到子Agent的系统提示词
若指定了max_turns，覆盖默认配置值

3. 上下文继承阶段

子Agent自动继承父Agent的运行上下文，保持环境一致性：

沙箱状态（sandbox_state）：保持文件系统访问权限和路径映射一致
线程数据（thread_data）：共享线程级别的配置和状态
线程ID（thread_id）：关联到同一个会话线程
模型配置（parent_model）：可配置继承父Agent使用的LLM模型
追踪ID（trace_id）：统一分布式追踪ID，关联父子Agent的日志

4. 工具集过滤阶段

子Agent的工具集通过get_available_tools()获取，但强制关闭子Agent功能（subagent_enabled=False），防止递归嵌套调用
根据子Agent配置的工具白名单/黑名单进一步过滤可用工具
- general-purpose：拥有除task外的所有工具权限
- bash：仅拥有命令执行相关工具权限

5. 执行阶段

创建SubagentExecutor执行器实例
任务提交到双层线程池异步执行：
- _scheduler_pool（3 worker）：负责任务调度、状态管理、超时控制
- _execution_pool（3 worker）：负责实际的子Agent逻辑执行
子Agent创建独立的LangChain Agent实例，使用对应类型的专用系统提示词，运行在隔离上下文
以stream模式执行，实时收集AI生成的所有中间消息，用于后续调试和审计
父Agent调用task工具后会通过5秒间隔轮询等待子Agent执行完成（对当前会话是同步阻塞的），但子Agent运行在独立线程池，不会阻塞其他会话的Agent执行

6. 状态反馈阶段

执行过程中通过SSE流实时推送事件到前端：

task_started：任务开始执行
task_running：执行中，包含子Agent的中间输出消息（1-based索引）
task_completed：任务成功完成，返回最终结果
task_failed：任务执行失败，返回错误信息
task_timed_out：任务执行超时

7. 结果返回阶段

子Agent执行完成后，将最终结果返回给父Agent，父Agent可以基于这个结果继续后续处理，完成后自动清理后台任务记录，避免内存泄漏。

关键特性与保护机制

1. 强隔离设计

子Agent运行在独立的线程和执行上下文，不会污染父Agent的状态
工具集独立配置，权限按需分配

2. 防止递归

子Agent默认没有task工具权限，无法嵌套调用其他子Agent，避免无限递归

3. 双层超时保护

线程池层面的执行超时：可配置，默认15分钟
轮询层面的超时保护：超时时间+60s缓冲，作为兜底机制防止任务卡死

4. 并发控制

最大并发子Agent数为3，由SubagentLimitMiddleware中间件自动拦截超过限制的工具调用

5. 可扩展性

支持通过配置文件自定义子Agent超时时间
注册中心设计支持扩展更多内置子Agent类型

内置子Agent说明

类型	适用场景	工具权限
`general-purpose`	复杂多步骤任务、探索性研究、需要多种工具配合的工作	除`task`外的所有工具
`bash`	Git操作、构建流程、批量命令执行、大量命令输出的场景	仅命令行相关工具

配置说明

在config.yaml中可以配置子Agent的超时时间：

subagents:
  enabled: true
  timeouts:
    general-purpose: 900  # 15分钟
    bash: 300  # 5分钟

Plan Mode 与 TodoList 实现说明

May 16, 2026

xiwang

全栈开发者

概述

Plan Mode是DeerFlow提供的任务规划与进度跟踪功能，通过TodoList中间件实现，允许Agent将复杂任务拆分为多步执行，并实时跟踪进度，为用户提供透明的工作流程可见性。

核心组件

组件	位置	职责
Todo中间件	`packages/harness/deerflow/agents/middlewares/todo_middleware.py`	扩展LangChain内置`TodoListMiddleware`，添加上下文丢失检测和提醒注入功能
ThreadState定义	`packages/harness/deerflow/agents/thread_state.py`	定义`todos`字段存储任务列表状态
中间件注册	`packages/harness/deerflow/agents/lead_agent/agent.py`	动态根据Plan Mode开关决定是否加载Todo中间件
`write_todos`工具	LangChain内置，由TodoListMiddleware自动提供	任务列表管理工具，支持创建、更新、完成任务

实现原理

1. 开关控制

Plan Mode通过runtime配置参数动态控制，无需修改静态配置：

在调用Agent时，通过config.configurable.is_plan_mode = True开启Plan Mode
开启后，_build_middlewares函数会自动创建并加载TodoMiddleware
关闭时，Todo中间件不会被加载，Agent也不会拥有write_todos工具权限

2. 中间件工作流程

TodoMiddleware继承自LangChain的TodoListMiddleware，扩展了上下文丢失保护机制：

前置钩子（`before_model`/`abefore_model`）

在每次调用LLM之前执行：

检查当前状态中是否存在todos任务列表
检查最近的消息历史中是否包含write_todos工具调用（即任务列表是否还在上下文窗口中）
检查是否已经注入过todo提醒消息，避免重复
如果任务列表存在但已经不在上下文窗口中，自动注入系统提醒消息，包含当前所有任务的状态

提醒消息格式

<system_reminder>
Your todo list from earlier is no longer visible in the current context window,
but it is still active. Here is the current state:

- [pending] 任务1
- [in_progress] 任务2
- [completed] 任务3

Continue tracking and updating this todo list as you work.
Call `write_todos` whenever the status of any item changes.
</system_reminder>

3. 状态管理

任务列表存储在ThreadState的todos字段中，类型为list[Todo]
每个Todo对象包含：
- content: 任务描述
- status: 任务状态（pending/in_progress/completed）
- activeForm: 任务进行时的描述（可选）

4. 自定义规则与提示

DeerFlow对内置的TodoListMiddleware进行了定制，添加了严格的使用规则和最佳实践提示：

系统提示规则

必须立即标记完成：完成任务后立即更新状态，不要批量更新
单任务进行中：同一时间只能有一个任务处于in_progress状态（可并行任务除外）
实时更新：工作过程中实时更新任务列表，给用户提供可见性
避免滥用：少于3步的简单任务不要使用Todo功能，直接完成即可

适用场景

复杂多步骤任务（≥3步）
需要仔细规划的非平凡任务
用户明确要求使用任务列表
用户提供多个任务（编号或逗号分隔列表）
需要根据中间结果动态调整计划的任务

关键特性

1. 上下文丢失自动恢复

当对话历史被截断（例如被SummarizationMiddleware summarization）导致原始write_todos调用被移出上下文窗口时，中间件会自动注入提醒消息，确保Agent不会忘记当前的任务列表。

2. 严格的任务管理约束

内置规则确保任务管理的规范性：

只有完全完成的任务才能标记为completed
遇到阻塞时保持任务为in_progress，并新增解决阻塞的任务
自动提醒实时更新状态，避免进度跟踪滞后

3. 无额外配置开销

Plan Mode完全通过runtime参数控制，无需修改静态配置文件，可按需为每个会话独立开启或关闭。

4. 同步/异步双支持

同时实现了同步before_model和异步abefore_model钩子，兼容同步和异步两种Agent运行模式。

5. 与LangGraph生态无缝集成

基于LangChain官方TodoListMiddleware扩展，保持了与LangGraph生态的兼容性，同时添加了适合生产环境的增强功能。

使用流程

1. 开启Plan Mode

在创建Agent运行时传入配置：

config = {
    "configurable": {
        "is_plan_mode": True,
        # 其他配置...
    }
}

2. 使用`write_todos`工具

Agent会根据任务复杂度自动决定是否调用write_todos工具，示例调用：

{
    "name": "write_todos",
    "parameters": {
        "todos": [
            {
                "content": "分析子Agent委派实现",
                "status": "in_progress",
                "activeForm": "分析子Agent委派实现中"
            },
            {
                "content": "撰写实现文档",
                "status": "pending",
                "activeForm": "撰写实现文档中"
            },
            {
                "content": "复核文档正确性",
                "status": "pending",
                "activeForm": "复核文档正确性中"
            }
        ]
    }
}

3. 更新任务状态

Agent在完成任务或切换任务时自动调用write_todos更新状态：

{
    "name": "write_todos",
    "parameters": {
        "todos": [
            {
                "content": "分析子Agent委派实现",
                "status": "completed",
                "activeForm": "分析子Agent委派实现中"
            },
            {
                "content": "撰写实现文档",
                "status": "in_progress",
                "activeForm": "撰写实现文档中"
            },
            {
                "content": "复核文档正确性",
                "status": "pending",
                "activeForm": "复核文档正确性中"
            }
        ]
    }
}

与其他组件的交互

组件	交互方式
SummarizationMiddleware	Todo中间件在summarization之后执行，检测summarization是否导致任务列表被移出上下文窗口
ClarificationMiddleware	Todo中间件在ClarificationMiddleware之前执行，确保Agent可以在需要澄清问题时仍然能够管理任务列表
前端UI	任务状态变化会通过SSE事件推送到前端，实时展示进度
子Agent系统	Plan Mode下的任务可以委派给子Agent执行，状态更新会同步回主任务列表

注意事项

Plan Mode默认是关闭的，需要显式开启
任务列表存储在会话状态中，会话结束后不会持久化
中间件自动处理上下文丢失问题，无需人工干预
严格遵守内置规则可以有效提升任务执行的透明度和可追溯性

Skill 系统实现对比分析文档

May 16, 2026

xiwang

全栈开发者

本文档深入分析DeerFlow系统中Skill功能的实现机制，并与官方Claude Code的Skill系统实现进行对比，总结两者的异同点及背后的设计考量。

一、DeerFlow 系统 Skill 实现分析

1.1 系统定位

DeerFlow的Skill系统是一套可扩展的技能机制，允许用户安装、管理和使用预定义的工作流模板，每个Skill包含最佳实践、操作框架和相关资源，为AI Agent提供特定任务的标准化执行流程。

1.2 定义格式

每个Skill以独立目录形式存在，核心文件为SKILL.md，采用Markdown + YAML Frontmatter格式：

必填字段: name（技能名称，短横线命名法）、description（技能描述）
可选字段: license、allowed-tools、metadata、compatibility、version、author
正文内容: 技能的具体执行流程、使用说明、参考资源等

1.3 存储结构

skills/
├── public/          # 公共技能，随代码库提交
│   └── [skill-name]/
│       ├── SKILL.md
│       └── 其他资源文件
└── custom/          # 用户自定义安装的技能，git忽略
    └── [skill-name]/
        └── SKILL.md

1.4 加载流程

扫描: loader.py的load_skills()函数递归扫描public和custom目录，查找所有SKILL.md文件
解析: parser.py的parse_skill_file()提取YAML Frontmatter，解析为Skill数据对象
状态同步: 从extensions_config.json读取技能启用状态，更新Skill.enabled属性
返回: 按名称排序的Skill列表

1.5 调用与执行逻辑

注入: 已启用的技能会在Agent启动时以XML格式注入到系统提示词中，包含技能名称、描述和文件路径
触发: 当用户请求匹配技能使用场景时，Agent自动调用read_file读取技能内容
执行: Agent按照技能定义的步骤执行任务，按需加载技能目录下的其他参考资源

1.6 安全机制

安装安全：压缩包路径校验，防止目录穿越攻击，自动跳过符号链接，总大小限制512MB
内容校验：严格验证SKILL.md Frontmatter格式和字段合法性
权限控制：自定义技能与公共技能隔离，技能在容器内以只读方式挂载

1.7 核心模块与文件

模块	文件路径	功能说明
类型定义	`/backend/packages/harness/deerflow/skills/types.py`	Skill数据类定义
加载逻辑	`/backend/packages/harness/deerflow/skills/loader.py`	技能扫描、加载逻辑
解析逻辑	`/backend/packages/harness/deerflow/skills/parser.py`	SKILL.md文件解析
安装逻辑	`/backend/packages/harness/deerflow/skills/installer.py`	技能安装、安全校验
API路由	`/backend/app/gateway/routers/skills.py`	技能管理API接口
运行时注入	`/backend/packages/harness/deerflow/agents/lead_agent/prompt.py`	技能注入Agent系统提示词

二、官方 Claude Code Skill 实现分析

2.1 系统定位

Skills是Claude Code的模块化扩展组件，用于为Claude提供特定领域的专业知识、标准化工作流、工具集成能力和业务逻辑，将通用AI代理转变为面向特定任务的专业化代理。

2.2 定义格式

每个Skill完全自包含，核心文件为SKILL.md：

YAML Frontmatter必填字段: name（技能名称）、description（触发条件/使用场景描述）
可选字段: version、author、license、allowed-tools
正文内容: 技能的系统提示、执行规则、工作流步骤、工具使用规范等
面向Agent类型的Skill还支持JSON格式定义，包含identifier、whenToUse、systemPrompt字段

2.3 存储结构

skill-name/
├── SKILL.md          # 核心技能定义文件（必选）
├── references/       # 参考文档资源（可选）
├── examples/         # 示例代码/配置（可选）
└── scripts/          # 配套执行脚本（可选）

所有Skill统一存放在插件的skills/目录下的独立子目录中。

2.4 加载流程

采用三级渐进式加载机制：

启动扫描阶段: Claude Code启动时自动扫描所有插件的skills/目录，仅加载元数据（name/description/version）到常驻内存
触发加载阶段: 当用户查询或任务上下文匹配到技能的description描述时，加载对应技能的SKILL.md正文内容到当前会话上下文
按需加载阶段: 技能执行过程中需要参考文档、示例、脚本等资源时，动态加载对应目录下的资源文件

2.5 调用与执行逻辑

触发方式:
- 隐式触发：任务上下文和技能description中的触发描述匹配时自动激活
- 显式触发：用户执行/skill <skill-name> [args]命令主动调用
执行流程:
- 技能激活后，系统将技能定义的规则、工作流、系统提示词注入当前会话上下文
- Claude按照技能定义的逻辑和约束执行任务，可调用技能配套的脚本、工具和资源
结果处理: 技能执行结果直接返回会话上下文，可作为后续任务的输入

2.6 架构设计

插件化架构: Skill是Claude Code插件系统的核心组件之一，与commands、agents、hooks、MCP工具等组件并行
分层披露设计: 三级加载机制避免不必要的上下文占用，平衡性能和功能完整性
完全自包含设计: 每个Skill独立打包、分发、安装，无外部依赖
无侵入集成: 技能不需要编译或打包，直接以纯文本格式分发

三、异同点对比

3.1 相同点

维度	共性描述
定义格式	都采用`SKILL.md`作为核心定义文件，使用YAML Frontmatter + Markdown正文格式，必填字段都包含`name`和`description`
存储结构	都采用独立目录存储每个Skill，支持配套资源文件（参考文档、示例、脚本等）
核心目标	都是为了提供标准化的工作流模板，扩展Agent的专业能力，处理特定领域的复杂任务
执行逻辑	都是将技能内容注入到Agent的上下文，让Agent按照技能定义的规则执行任务
扩展性	都支持用户自定义技能，无需修改核心代码即可扩展功能
安全性	都有严格的安全校验机制，防止恶意技能注入和攻击

3.2 不同点

维度	DeerFlow Skill系统	官方Claude Code Skill系统
加载机制	一次性加载所有已启用技能的元数据和路径信息到Agent系统提示	采用三级渐进式加载，仅在匹配到触发条件时才加载技能正文，按需加载资源
触发方式	仅支持隐式触发，依赖Agent自动识别匹配场景	支持隐式自动触发和显式命令触发（`/skill`命令）
架构定位	是DeerFlow系统的内置核心功能，与Agent系统深度集成	是Claude Code插件系统的一部分，与其他插件组件（commands、agents等）并行
技能分类	明确分为`public`（内置公共技能）和`custom`（用户自定义技能）两类	无明确分类，由插件目录结构自然区分
状态管理	有完整的启用/禁用状态管理，通过`extensions_config.json`配置，支持动态修改	依赖插件的启用/禁用机制，无单独的技能状态管理
资源加载	Agent需要主动调用`read_file`读取技能内容	系统自动加载匹配的技能内容到上下文，无需Agent主动读取
参数支持	无显式参数传递机制，参数从会话上下文提取	支持通过`Skill`工具的`args`参数显式传递参数

四、设计考量分析

4.1 DeerFlow 设计考量

深度集成优先: DeerFlow作为专门的Agent协作平台，需要技能系统与核心Agent流程深度耦合，因此采用一次性注入所有技能信息的方式，确保Agent可以随时访问所有可用技能
集中管理优先: 明确的技能分类和状态管理机制，方便平台管理员统一管控可用技能，适合企业级部署场景
安全性优先: 严格的容器隔离和只读挂载机制，保障多租户环境下的技能使用安全

4.2 官方 Claude Code 设计考量

性能优先: 三级渐进式加载机制最大限度减少不必要的上下文占用，提升会话响应速度，适合轻量级客户端场景
灵活性优先: 支持显式命令调用和参数传递，用户可以更灵活地控制技能的使用时机和方式
扩展性优先: 作为插件系统的一部分，技能可以与其他插件组件无缝协作，方便第三方开发者扩展功能

4.3 借鉴与优化方向

DeerFlow的Skill系统可以从官方实现中借鉴以下优化点：

引入渐进式加载机制，减少系统提示词长度，提升Agent响应效率
增加显式/skill命令调用支持，让用户可以主动触发特定技能
支持技能参数显式传递，提升技能使用的灵活性
优化技能匹配算法，提升隐式触发的准确率

DeerFlow 沙箱执行环境实现分析

May 15, 2026

xiwang

全栈开发者

整体架构

DeerFlow的沙箱系统采用抽象接口+多实现的设计模式，提供两种执行模式：本地文件系统模式和Docker容器隔离模式，通过统一的接口对外提供服务。

核心抽象层

Sandbox (接口) → 定义沙箱基本操作：execute_command、read_file、write_file、list_dir、update_file
SandboxProvider (接口) → 定义沙箱生命周期管理：acquire(获取)、get(查询)、release(释放)

两种实现模式

1. 本地模式 (LocalSandbox)

适用场景：开发环境、低安全要求场景
实现原理：
- 单例模式，所有线程共享同一个沙箱实例
- 通过路径映射机制实现逻辑隔离：
  - 虚拟路径：Agent 看到的统一路径 /mnt/user-data/{workspace,uploads,outputs}、/mnt/skills
  - 实际路径：物理上存储在 backend/.deer-flow/threads/{thread_id}/user-data/... 和项目根目录的 skills/
- 命令执行时自动转换路径：
  - 输入：将命令中的虚拟路径替换为实际本地路径，优先匹配最长前缀避免歧义
  - 输出：将执行结果中的本地路径替换回虚拟路径，对Agent完全透明
- Shell自动检测：优先使用zsh，其次bash，最后sh，保证跨平台兼容性
特点：轻量、无额外依赖、启动快，但隔离性较弱

2. Docker隔离模式 (AioSandbox)

适用场景：生产环境、高安全要求场景
核心特性：
- 两种后端：
  - 本地Docker后端：直接管理本地Docker容器生命周期
  - 远程K8s后端：通过Provisioner服务动态创建K8s Pod作为沙箱
- 暖池机制：释放的沙箱容器不会立即销毁，放入暖池等待复用，避免冷启动开销
- 空闲超时管理：默认10分钟无活动自动销毁容器，节省资源
- 并发控制：默认最大3个并发沙箱容器，超过时采用LRU策略销毁最旧的暖池容器；并发限制为软限制，活跃沙箱不会被强制销毁
- 跨进程一致性：通过线程ID生成确定性沙箱ID，支持多进程/多Pod环境下的沙箱发现
- 跨进程锁机制：通过文件锁防止多个进程同时为同一个线程创建沙箱导致的冲突
安全特性：
- 每个线程独立容器，完全隔离，进程、文件系统、网络都互相隔离
- 工作目录、上传目录、输出目录独立挂载，每个线程只能访问自己的数据
- 技能目录只读挂载，防止Agent修改系统技能
- ACP工作区只读挂载，仅允许Agent读取ACP代理的执行结果
- 支持自定义环境变量和额外挂载配置

生命周期管理

沙箱的生命周期由SandboxMiddleware中间件统一管理：

会话开始时调用provider.acquire(thread_id)获取沙箱
会话过程中通过provider.get(sandbox_id)获取沙箱实例执行操作
会话结束时调用provider.release(sandbox_id)释放沙箱（Docker模式下放入暖池）

工具封装

沙箱功能被封装为统一的工具集提供给Agent使用：

bash：执行命令，自动处理路径转换和错误
ls：目录列表，返回tree格式
read_file：读取文件内容，支持行范围
write_file：写入/追加文件，自动创建目录
str_replace：字符串替换，支持批量替换

配置方式

在config.yaml中通过sandbox.use字段指定沙箱实现：

# 本地模式
sandbox:
  use: deerflow.sandbox.local.local_sandbox_provider:LocalSandboxProvider

# Docker模式
sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
  idle_timeout: 600
  replicas: 3

这种设计使得沙箱实现可插拔，未来可以轻松扩展支持其他隔离技术（如Kata Containers、WASM等）而不影响上层业务逻辑。

MCP (Model Context Protocol) 系统实现说明

May 15, 2026

xiwang

全栈开发者

概述

DeerFlow完整集成了MCP（Model Context Protocol）协议，支持无缝对接各类MCP服务器，实现工具能力的动态扩展。系统采用模块化设计，支持多种传输协议、OAuth 2.0认证、运行时热更新、自动缓存等企业级特性，无需修改代码即可通过配置扩展Agent的工具能力。

核心架构

1. 文件结构

所有MCP相关代码集中在packages/harness/deerflow/mcp/目录下：

文件	职责
`mcp/__init__.py`	模块导出接口，统一暴露核心函数
`mcp/cache.py`	MCP工具缓存机制，支持自动失效与懒加载
`mcp/client.py`	MCP客户端实现，支持多传输类型配置构建
`mcp/oauth.py`	OAuth令牌管理，支持自动刷新与请求头注入
`mcp/tools.py`	工具加载与同步适配，将MCP工具转换为LangChain兼容格式
`config/extensions_config.py`	配置解析系统，定义MCP配置结构与加载逻辑
`app/gateway/routers/mcp.py`	Gateway API层，提供MCP配置的REST管理接口

2. 整体架构

┌─────────────────────────────────────────────────────────┐
│                     Agent Runtime                        │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│                   MCP Tool Cache                          │
│  (懒加载、自动失效、线程安全)                              │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│              MultiServerMCPClient                         │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐          │
│  │ Stdio 服务 │  │ SSE 服务   │  │ HTTP 服务  │          │
│  └────────────┘  └────────────┘  └────────────┘          │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│                  OAuth 管理器                             │
│  (令牌自动刷新、线程安全、请求头自动注入)                  │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│                MCP 服务器集群                              │
│  (本地进程、远程服务、第三方MCP服务)                       │
└───────────────────────────────────────────────────────────┘

配置系统

1. 配置格式

MCP服务器配置存储在extensions_config.json文件中，示例：

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@github/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      },
      "description": "GitHub API 工具集"
    },
    "internal-api": {
      "enabled": true,
      "type": "http",
      "url": "https://mcp.example.com/tools",
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth2/token",
        "grant_type": "client_credentials",
        "client_id": "$CLIENT_ID",
        "client_secret": "$CLIENT_SECRET",
        "scope": "read write"
      },
      "description": "内部系统API工具集"
    }
  }
}

2. 传输类型

支持三种传输协议：

类型	适用场景	配置参数
`stdio`	本地MCP服务器，通过子进程启动	`command`、`args`、`env`
`sse`	远程SSE协议的MCP服务器	`url`、`headers`
`http`	远程HTTP协议的MCP服务器	`url`、`headers`

3. 路径解析优先级

显式传入的config_path参数
DEER_FLOW_EXTENSIONS_CONFIG_PATH环境变量
当前工作目录下的extensions_config.json
当前工作目录父目录下的extensions_config.json（推荐位置）
兼容旧版：查找mcp_config.json作为备选

4. 环境变量注入

配置中所有以$开头的字符串会自动解析为环境变量
示例："GITHUB_TOKEN": "$GITHUB_TOKEN"会自动替换为对应环境变量的值
未找到的环境变量自动替换为空字符串，避免运行错误

核心功能实现

1. OAuth 2.0 认证系统

支持完整的OAuth 2.0客户端认证能力：

支持的授权模式

client_credentials：客户端凭证模式，适用于服务间通信
refresh_token：刷新令牌模式，适用于用户级授权场景

核心特性

自动刷新：提前60秒（可配置refresh_skew_seconds）自动刷新令牌，避免请求时令牌过期
线程安全：每个MCP服务器独立的令牌获取锁，避免并发刷新导致的重复请求
自动注入：工具调用拦截器自动将最新的Authorization头注入到所有MCP请求中
初始化认证：首次连接MCP服务器时自动注入OAuth头，确保工具发现阶段的认证通过

2. 工具加载与适配

自动发现：自动加载所有启用MCP服务器暴露的工具，无需手动定义
名称隔离：工具名称自动添加服务器前缀，避免不同服务器之间的命名冲突，格式为{server_name}_{tool_name}
同步适配：异步MCP工具自动封装为同步调用，适配DeerFlow的同步执行模型，使用全局线程池避免嵌套事件循环问题
类型转换：自动处理MCP工具参数与LangChain工具格式的转换，上层调用无感知

3. 缓存机制

缓存策略

全局单例缓存：MCP工具加载后全局缓存，避免重复初始化的性能开销
自动失效：通过监控配置文件的修改时间（mtime），配置变更后自动失效缓存，下次访问时重新加载
懒加载：支持首次使用时自动初始化，兼顾冷启动性能和资源占用
线程安全：初始化过程使用异步锁，避免并发场景下的重复初始化问题

管理接口

# 获取MCP工具（自动初始化、自动缓存）
from deerflow.mcp import get_cached_mcp_tools
tools = get_cached_mcp_tools()

# 手动重置缓存（配置更新后调用）
from deerflow.mcp import reset_mcp_tools_cache
reset_mcp_tools_cache()

4. 运行时热更新

配置文件修改后，系统自动检测到mtime变化，缓存自动失效
通过Gateway API更新配置后，自动触发缓存重置
新配置在下次工具调用时自动生效，无需重启LangGraph或Gateway服务
更新过程中不影响现有会话的运行

工作流程

完整执行流程

初始化触发：应用启动或首次调用MCP工具时，get_cached_mcp_tools()被调用
配置加载：从extensions_config.json加载所有启用的MCP服务器配置，解析环境变量
OAuth初始化：为需要认证的服务器初始化OAuth令牌管理器，获取初始访问令牌
客户端创建：构建MultiServerMCPClient实例，连接所有MCP服务器
工具发现：自动从所有MCP服务器发现并加载工具定义
工具适配：将异步MCP工具封装为同步调用，添加服务器前缀，存入全局缓存
工具使用：Agent调用MCP工具时，OAuth拦截器自动注入最新令牌，同步包装器处理异步调用逻辑
缓存失效：当配置文件被修改时，缓存自动失效，下次访问时重新执行初始化流程

API管理接口

Gateway提供了REST接口用于管理MCP配置：

获取当前配置

GET /api/mcp/config

返回所有MCP服务器和技能的配置信息。

更新配置

PUT /api/mcp/config
Content-Type: application/json

请求体为新的MCP配置，保存到文件后自动重置缓存，新配置立即生效。

注意：更新MCP配置时不会覆盖已有的技能配置，实现MCP与技能配置的独立管理。

关键特性

零代码扩展：新增MCP服务器只需修改配置文件，无需修改业务代码
运行时热更新：配置修改后自动生效，无需重启服务
多场景适配：支持本地命令行、远程SSE/HTTP等多种MCP服务器部署方式
企业级安全：完整的OAuth 2.0支持，满足内部API和第三方API的安全访问需求
高性能设计：缓存机制与自动失效平衡了性能和配置实时性
兼容现有架构：同步包装器完美适配DeerFlow现有的同步执行模型，无需修改上层调用逻辑

最佳实践

敏感信息管理：所有API密钥、令牌都通过环境变量传递，不要硬编码在配置文件中
命名规范：MCP服务器名称使用小写字母和连字符，避免特殊字符
权限最小化：为MCP服务器配置最小必要的权限，避免过度授权
版本锁定：本地stdio类型的MCP服务器推荐锁定版本号，避免意外升级导致兼容性问题
监控告警：对重要的MCP服务器添加健康检查，及时发现服务不可用问题

博客

概述

核心组件

完整委派流程

1. 触发阶段：父Agent调用task工具

2. 配置加载阶段

3. 上下文继承阶段

4. 工具集过滤阶段

5. 执行阶段

6. 状态反馈阶段

7. 结果返回阶段

关键特性与保护机制

1. 强隔离设计

2. 防止递归

3. 双层超时保护

4. 并发控制

5. 可扩展性

内置子Agent说明

配置说明

概述

核心组件

实现原理

1. 开关控制

2. 中间件工作流程

前置钩子（before_model/abefore_model）

提醒消息格式

3. 状态管理

4. 自定义规则与提示

系统提示规则

适用场景

关键特性

1. 上下文丢失自动恢复

2. 严格的任务管理约束

3. 无额外配置开销

4. 同步/异步双支持

5. 与LangGraph生态无缝集成

使用流程

1. 开启Plan Mode

2. 使用write_todos工具

3. 更新任务状态

与其他组件的交互

注意事项

一、DeerFlow 系统 Skill 实现分析

1.1 系统定位

1.2 定义格式

1.3 存储结构

1.4 加载流程

1.5 调用与执行逻辑

1.6 安全机制

1.7 核心模块与文件

二、官方 Claude Code Skill 实现分析

2.1 系统定位

2.2 定义格式

2.3 存储结构

2.4 加载流程

2.5 调用与执行逻辑

2.6 架构设计

三、异同点对比

3.1 相同点

3.2 不同点

四、设计考量分析

4.1 DeerFlow 设计考量

4.2 官方 Claude Code 设计考量

4.3 借鉴与优化方向

整体架构

核心抽象层

两种实现模式

1. 本地模式 (LocalSandbox)

2. Docker隔离模式 (AioSandbox)

生命周期管理

工具封装

配置方式

概述

核心架构

1. 文件结构

2. 整体架构

配置系统

1. 配置格式

2. 传输类型

3. 路径解析优先级

1. 触发阶段：父Agent调用`task`工具

前置钩子（`before_model`/`abefore_model`）

2. 使用`write_todos`工具