第44篇：工具搜索——按需加载工具

这篇讲的是：当你的 AI 智能体挂了太多“工具插件”导致反应变慢时，Hermes 如何用“按需加载”的方式帮你省下宝贵的上下文空间。

先打个比方

想象你的厨房抽屉里塞满了 3000 件厨具。每次做饭时，你都得把所有工具摊在台面上——找一把菜刀要拨开 2999 件杂物。这就是 AI 智能体同时挂载大量 MCP 服务器（比如 GitHub、Linear、Cloudflare）时的窘境：每个工具的说明书（JSON Schema）都会占用上下文窗口，哪怕这次根本用不上它。

Hermes 的“工具搜索”功能，就像给厨房装了一个智能抽屉系统：台面上只放三样东西——搜索框、说明书查询卡、调用按钮。 需要哪件，再单独抽出来用。

第1步：开启工具搜索

默认是 auto 模式——只要检测到有可延迟的工具（MCP、非核心插件，或者被显式点名的内置工具），就自动启用。核心工具（终端、文件读写等）默认永远直接加载；不过那些“冷门、事件触发型”的内置工具（比如 computer_use、session_search 和部分桌面助手）可以被 defer 列表点名延迟加载。MCP 和非核心插件工具则自动进入延迟范围。

tools:
  tool_search:
    enabled: auto       # auto（默认）/ on / off
    threshold_pct: 5    # 目录清单占上下文的比例
    search_default_limit: 5
    max_search_limit: 25
    defer:              # 替换默认的精选列表；写 [] 则所有工具都直接加载
      - computer_use
      - session_search
      - image_generate
      - todo_list
      - process_manage
      - cronjob_manage

默认的 defer 列表还包含 hermes_cli/config_defaults.py 里列出的部分桌面 GUI 助手。想彻底关掉，改成 enabled: off 即可。

第2步：理解三级“渐进展示”

系统会根据工具数量自动切换档位：

Tier 0：没有可延迟的工具，一切照旧，直通。
Tier 1：工具不多时，AI 能看到一个“目录清单”——每个工具的名字 + 一句话简介。这就像餐厅菜单，菜名和简介都有，但完整做法（参数 Schema）要单独查。
Tier 2：工具爆炸多（比如 Cloudflare 一个服务器就有 3300 个工具），连菜单都放不下，就只显示“每台服务器一行摘要”（服务器名 + 工具数量）。这时只能靠搜索发现具体工具。

第3步：AI 的实际操作流程

开启后，AI 会看到三个“桥接工具”，典型流程是：

AI: tool_search("创建 GitHub issue")     → 找到 mcp_github_create_issue
AI: tool_describe("mcp_github_create_issue") → 查看完整参数
AI: tool_call({ calls: [{ name: "mcp_github_create_issue", arguments: {...} }] }) → 真正执行

关键点：AI 调用 tool_call 时，Hermes 会“拆开桥接”，直接调用底层真实工具——安全检查、审批提示、活动记录全部显示真实工具名，而不是 tool_call。

tool_call 的 calls 是一个数组，每次调用一个条目（单次本地调用就是只含一个元素的数组）。只有 connectors__ 开头的名字可以放在同一批里；混合批次和多个本地工具的批次会被拒绝。如果 calls 被写成 JSON 字符串，Hermes 也会按数组形式解析；多条目批次里混进本地工具会被打回，并附上一条用你自己第一个条目示范正确写法的提示。审批按条目逐个结算，条目之间来一个 /stop，还没开始的条目就不会发出（对应位置报 INTERRUPTED）。

第4步：为什么要有“目录清单”？

实测发现，如果没有清单，AI 会“看不见”延迟工具，转而用终端硬跑 gh 命令，或者直接说“这功能不存在”。有了清单，AI 看到工具名就能跳过搜索，直接 tool_describe，省一次往返。

第5步：连接器（远程工具）

当你登录 Nous Portal 后，桥接层还能触达 connectors——由托管工具网关提供的远程工具。它们从不在本地注册：tool_search 会把每个查询发给网关，把网关命中的结果作为文档加入本地目录（标记 source: "connectors"，命名为 connectors__<connector>__<tool>），再用同一套 BM25 排序和同样的“最稀有词元”规则统一排名，所以 limit 是对整组生效的，一个能回答查询的连接器工具不会被只共享一个词的本地工具挤掉。网关调用限时 30 秒；网关慢或无响应时只降级为本地结果。tool_describe 从网关获取连接器 schema，tool_call 会把批次里每个连接器条目按输入顺序作为独立的网关请求发送（网关不认识常规 slug 下的工具名时，会用字面 slug 重试一次，所以一个条目可能花两次请求）。如果某个连接器同时提供了 GMAIL_X 和字面的 X，两者都会组合成 connectors__gmail__X，实际运行的是 GMAIL_X；搜索保留这个孪生项、丢弃另一个，并记录一条警告。结果会按批次原始顺序拼回，并重新计算计数。

tools:
  connectors:
    enabled: true   # false — 完全不碰连接器路由；桥接层的行为
                    # 就和这个功能不存在一样

未登录（或网关不为你的账号提供连接器）时，以上一切都不可见：本地搜索的行为和本页其余部分描述完全一致，模型不会看到任何错误。

一个需要你尚未关联账号的连接器调用会返回 CONNECTION_REQUIRED 错误。manage_connections 工具会列出连接器及其连接状态并发起授权：在桌面应用里会弹出一张卡片，阻塞到每个应用被连接或跳过，然后汇报结果；其他地方则返回每个应用的连接链接，让用户自己打开。断开账号由用户在 Portal 中操作。这个工具还能从目录里安装、启用并授权本地 MCP 服务器（目标带 mcp: true），所以无论你是否登录它都在；只有托管连接器相关的操作才需要登录。

什么时候别用？

你的工具集很小（比如就两三个 MCP），直接 enabled: off 保持全量加载更简单。
小模型写不好搜索词，可能找不到工具（Anthropic 实测：Opus 4 开启后准确率从 49% 提到 74%，但仍有 26% 检索失败）。
每次冷启动新工具，会多花 1-2 次模型调用去加载 Schema。
延迟工具的 schema 没有 provider 原生校验：tool_describe 让模型读到 schema，但 provider 只看到通用的 tool_call.arguments 对象，Hermes 会在派发前本地做强制转换和校验。

小结

工具搜索是 Hermes 的“智能抽屉系统”——用少量固定开销（三个桥接工具 + 目录）换回大量上下文空间。核心工具永远直连，MCP/插件按需加载，目录清单保证“看得见、找得到”。

下篇预告：工具搜索解决了“工具太多”的问题，那“任务太多”怎么办？下一篇我们聊聊 任务委派与子智能体——如何让多个 AI 分工协作。