DeerFlow 工具系统详解

概述

DeerFlow 的工具系统采用三层加载 + 策略过滤架构。LLM 看到的所有工具都是通过统一入口 get_available_tools() 加载的，内建工具、配置工具、MCP 工具、社区工具各自注册后合并去重。工具通过 Command(update={}) 机制与 ThreadState 交互。

一、工具分类全景

                    get_available_tools()
                           │
        ┌──────────────────┼──────────────────┬──────────────────┐
        ▼                  ▼                   ▼                  ▼
   配置工具             内置工具             MCP工具            ACP工具
 config.tools[]       BUILTIN_TOOLS       extensions_config   acp_config
        │                  │                   │                  │
 ┌──────┼──────┐    ┌──────┼──────┐           │                  │
 ▼      ▼      ▼    ▼      ▼      ▼           ▼                  ▼
bash  read_file  │ present  task   │   MCP Server 1~N    invoke_acp_agent
                 │ _files  _tool   │
            web_search  view_image  │
            web_fetch  ask_clari... │
            ...       skill_manage  │
                      setup/update  │

二、工具加载流程

get_available_tools() 在 tools/tools.py:44 中定义，是唯一的工具加载入口。

函数签名

defget_available_tools(
    groups: list[str] | None = None,      # 按工具组过滤
    include_mcp: bool = True,              # 是否包含 MCP 工具
    model_name: str | None = None,         # 用于判断是否加载视觉工具
    subagent_enabled: bool = False,        # 是否包含子 agent 工具
    *,
    app_config: AppConfig | None = None,
) -> list[BaseTool]:

四层加载

第 1 层：从 config.tools 加载配置工具

# 过滤 + 解析
tool_configs = [t for t in config.tools if groups isNoneor t.group in groups]
loaded_tools = [(cfg, resolve_variable(cfg.use, BaseTool)) for cfg in tool_configs]

config.tools 由 config.yaml 中的 tools: 段定义。每个工具标注了 group（所属分组）和 use（Python 导入路径）：

tools:
-name:bash
group:bash
use:deerflow.sandbox.tools:bash_tool
-name:read_file
group:sandbox
use:deerflow.sandbox.tools:read_file_tool
-name:web_search
group:web
use:deerflow.community.serper.tools:web_search_tool
api_key:$SERPER_API_KEY

groups 过滤机制：

# groups=None → 不过滤，加载所有配置工具
# groups=["web"] → 只加载 group="web" 的工具
# groups=["web", "bash"] → 加载两个组的工具
tool_configs = [t for t in config.tools if groups isNoneor t.group in groups]

host bash 安全过滤：当使用 LocalSandboxProvider 且未显式 allow_host_bash: true 时，bash 工具会被自动排除。

第 2 层：添加内置工具

内置工具是硬编码在 tools/tools.py 中的常量列表，总是加载：

BUILTIN_TOOLS = [
    present_file_tool,          # 向用户展示文件
    ask_clarification_tool,     # 请求用户澄清
]

条件追加：

if config.skill_evolution.enabled:
    builtin_tools.append(skill_manage_tool)   # Skill 创建/演化

if subagent_enabled:
    builtin_tools.extend(SUBAGENT_TOOLS)      # [task_tool]

if model_config.supports_vision:
    builtin_tools.append(view_image_tool)      # 查看图片

第 3 层：加载 MCP 工具

if include_mcp:
    extensions_config = ExtensionsConfig.from_file()  # 实时读盘
if extensions_config.get_enabled_mcp_servers():
        mcp_tools = get_cached_mcp_tools()            # 从缓存取
for t in mcp_tools:
        tag_mcp_tool(t)  # 标记为 MCP 工具用于 deferred 识别

MCP 工具在应用启动时通过 initialize_mcp_tools() 初始化并缓存。每次请求只读缓存，不重建连接。tag_mcp_tool() 打上标记便于 DeferredToolFilterMiddleware 识别。

第 4 层：加载 ACP 工具

如果配置了 ACP agents，构建 invoke_acp_agent 工具。

去重合并

all_tools = config_tools + builtin_tools + mcp_tools + acp_tools
# 按 name 去重，先出现的保留
seen: set[str] = set()
for t in all_tools:
if t.name notin seen:
        unique.append(t)

优先级：配置工具 > 内置工具 > MCP 工具 > ACP 工具。用户可以通过在 config.tools 中定义同名工具来覆盖内置行为。

三、工具分类详解

3.1 沙箱工具（配置工具 - sandbox/group）

沙箱工具是对文件系统和 shell 的封装，全部定义在 sandbox/tools.py。它们通过 config.yaml 加载，不属于内置工具。

安全约束：

• • SandboxAuditMiddleware 对 bash 命令做三级分类（block/warn/pass）
• • write_file 有 80KB 大小上限
• • read_file 支持行范围避免一次读取过大文件
• • 所有沙箱工具需要 sandbox_id（通过 lazy_init 按需创建）

3.2 内置工具（BUILTIN_TOOLS）

内置工具是 deerflow/tools/builtins/ 下的工具，不通过 config.tools 配置，始终或条件加载。

3.3 社区工具（community/）

14 个第三方服务集成，按功能分：

配置示例：

tools:
-name:web_search
group:web
use:deerflow.community.serper.tools:web_search_tool
max_results:5

3.4 MCP 工具

通过 extensions_config.json 配置的外部 MCP 服务器工具。默认处于 deferred 状态——LLM 只看到工具名不看到 schema，需通过 tool_search 激活后才能调用。

详见 延迟工具机制。

四、ToolConfig 与 ToolGroupConfig

定义在 config/tool_config.py。

ToolConfig

classToolConfig(BaseModel):
    name: str# 工具唯一名称，如 "bash"
    group: str# 所属分组，如 "bash"、"web"
    use: str# Python 导入路径，如 "deerflow.sandbox.tools:bash_tool"
# model_config = ConfigDict(extra="allow") — 允许额外字段（api_key 等）

group 是 get_available_tools(groups=[...]) 过滤的依据。use 通过 resolve_variable() 动态解析为 BaseTool 实例。

ToolGroupConfig

classToolGroupConfig(BaseModel):
    name: str# 分组名称

在 config.yaml 中定义，用于 agent 配置的 tool_groups 白名单。

tool_groups:
-name:web
-name:bash
-name:sandbox

五、Agent 层面的工具过滤

5.1 tool_groups 白名单

Agent 配置中通过 tool_groups 字段控制可见工具：

agents:
-name:search-only
tool_groups:
-web
skills: []

这会导致 get_available_tools(groups=["web"]) 只加载 group="web" 的配置工具。注意内置工具不受 groups 过滤影响（它们不在 config.tools 中）。

5.2 Skill allowed_tools 策略

filter_tools_by_skill_allowed_tools() 在 Skill 级别进一步裁剪工具。

渐进式白名单策略：

1. 1. 所有 skill 都没声明 allowed_tools（纯 legacy）→ 不限制，所有工具可用
2. 2. 至少一个 skill 声明了 allowed_tools → 切换到白名单模式：
• • 声明的 skills 取其 allowed_tools 的并集
• • 未声明的 legacy skills 不提供任何工具

# Skill A: allowed_tools = ["bash", "read_file", "write_file"]
# Skill B: allowed_tools = ["bash", "web_search", "web_fetch"]
# → 最终白名单：{"bash", "read_file", "write_file", "web_search", "web_fetch"}

调用位置：在 _make_lead_agent 中，get_available_tools() 之后、create_agent() 之前：

raw_tools = get_available_tools(...)
filtered = filter_tools_by_skill_allowed_tools(raw_tools, skills_for_tool_policy)

六、工具与 ThreadState 的交互

只有三个工具直接写入 ThreadState 的非 messages 字段：

这些工具都通过 Command(update={fields}) 返回更新，由 LangGraph 的 reducer 机制处理并发写入。

不写 ThreadState 的工具（只通过 ToolMessage 返回结果）：

• • bash、read_file、write_file、str_replace、ls、glob、grep — 沙箱工具，结果通过 ToolMessage 返回
• • task — 子 agent 分发，通过 SSE 事件通知前端
• • ask_clarification — 由 ClarificationMiddleware 拦截处理
• • web_search、web_fetch — 搜索结果通过 ToolMessage 返回

七、Command vs 普通返回值

工具可以通过两种方式返回结果：

# 方式1：不写 state，仅返回结果给 LLM
@tool("my_tool")
defmy_tool(...) -> str:
return"result"

# 方式2：写 state，同时返回结果给 LLM
@tool("my_tool")
defmy_tool(...) -> Command:
return Command(update={
"artifacts": ["file.pdf"],
"messages": [ToolMessage("done", tool_call_id=...)]
    })

用 Command 的必要条件：需要修改 ThreadState 中 messages 以外的字段。

为什么 present_files 必须用 Command：artifacts 字段需要累积写入，普通 str 返回值无法修改 state 中的 artifacts。

八、延迟工具（Deferred Tools）

问题

MCP 服务器可能暴露数十个工具。把所有工具的完整 JSON schema 放入 bind_tools 会导致上下文窗口爆炸和模型困惑。

解决方案

MCP 工具默认标记为 deferred：

1. 1. LLM 在 <available-deferred-tools> 中看到工具名称列表，看不到 schema
2. 2. LLM 需要某个工具时，先调用 tool_search("query") 查询
3. 3. tool_search 返回匹配工具的完整 schema + 写入 promoted state
4. 4. DeferredToolFilterMiddleware 在下一轮 LLM 调用时放行已激活的工具
5. 5. 再次调用 tool_search 的不同查询时，merge_promoted reducer 合并激活列表

两阶段流程

阶段 1：LLM 看到工具名称
  <available-deferred-tools>
    github_search_repositories
    github_create_issue
    slack_send_message
    ...

阶段 2：LLM 调用 tool_search("github")
  → 返回 github_search_repositories 和 github_create_issue 的完整 schema
  → 写入 promoted: {catalog_hash: "abc123", names: ["github_search_repos", "github_create_issue"]}

阶段 3：下一轮 LLM 调用
  → DeferredToolFilterMiddleware 放行这两个工具
  → LLM 直接调用 github_search_repositories("react")

安全：catalog_hash

防止 checkpointer 恢复时的"僵尸工具"问题——工具目录变化后，旧 promoted 的 catalog_hash 不匹配，被拒绝激活。

九、完整加载流程图

_make_lead_agent(config)
  │
  ├─ 解析 agent_config → model_name, tool_groups, skills, ...
  │
  ├─ get_available_tools(groups=agent_config.tool_groups, ...)
  │   │
  │   ├─ [Layer 1] 从 config.tools 加载，按 groups 过滤
  │   │   ├─ bash, read_file, write_file, ls, glob, grep
  │   │   ├─ web_search (serper/tavily/...)
  │   │   └─ web_fetch (firecrawl/jina/...)
  │   │
  │   ├─ [Layer 2] BUILTIN_TOOLS
  │   │   ├─ present_files, ask_clarification         (始终)
  │   │   ├─ skill_manage                             (skill_evolution.enabled)
  │   │   ├─ task                                     (subagent_enabled)
  │   │   └─ view_image                               (supports_vision)
  │   │
  │   ├─ [Layer 3] MCP tools (从缓存)
  │   │   └─ tag_mcp_tool(t) ← 标记为 deferred
  │   │
  │   └─ [Layer 4] ACP agents
  │       └─ invoke_acp_agent
  │
  │   → 去重 (按 name，先出现者保留)
  │   → 返回 all_tools
  │
  ├─ filter_tools_by_skill_allowed_tools(tools, skills)
  │   → 按 Skill 的 allowed_tools 白名单裁剪
  │
  ├─ assemble_deferred_tools(filtered_tools)
  │   → 分离为 active_tools + deferred_setup
  │   → deferred_setup 传给 DeferredToolFilterMiddleware
  │
  └─ create_agent(model, final_tools, middleware=[..., DeferredToolFilterMiddleware])

十、设计哲学