02 注册表与按模型过滤

02 注册表与按模型过滤

本节摘要:工具定义好只是「存在」,要被模型用还得进入「可用集合」——这就是注册表(Registry)。本节讲注册表如何汇总三类工具来源(内置、自定义、插件),以及一个容易被忽视但很重要的机制:按模型过滤。不同模型对工具的偏好不同(比如某模型系列偏好补丁式工具而非读写工具),注册表会按当前模型动态决定哪些工具可用。理解了注册表,你才知道「模型实际看到的工具列表是怎么来的」。

一、注册表:工具的中央清单

注册表是「所有可用工具的中央清单」。它的职责是把三类来源的工具汇总到一起:

内置工具 ─┐
自定义工具 ─┼─► 注册表汇总 ──► 全部工具清单
插件工具 ─┘
​

注册表是这个汇总的「单一事实来源」——模型能用的工具,全从注册表来。

二、内置工具一览

内置工具覆盖了编码 Agent 的核心需求:

这些是「开箱即得」的,不用你配。

三、按模型过滤:动态决定可用工具

注册表不只「汇总」,还会按当前模型动态过滤——不同模型看到的工具集可能不同。这是本节最值得讲的机制。

一个典型例子:apply_patch vs edit/write

有些模型系列(如某厂商的较新模型)对「补丁式改文件」(apply_patch)更在行——它擅长生成「在某行改什么」的补丁。而传统模型用「读全文再写全文」(edit/write)更稳。

注册表会按模型 ID 判断:

如果模型是「某补丁偏好系列」:
   ├─ 启用 apply_patch
   └─ 禁用 edit / write(避免模型在两套之间混淆)
否则:
   ├─ 禁用 apply_patch
   └─ 启用 edit / write
​

判断逻辑大致是看模型 ID 是否包含某前缀(如 gpt-)且不包含某些排除标识(如 oss、旧版本标识)。

为什么要过滤

你可能会问:为什么不全开着,让模型自己选?三个理由:

1. 避免混淆:同时给 apply_patch 和 edit/write,模型可能在两套之间摇摆,改得不一致。
2. 扬长避短:补丁偏好模型用 apply_patch 效果更好,强行让它用 edit/write 是浪费它的能力。
3. 减少上下文:少几个工具,工具描述占的 token 就少,上下文更宽裕。

💡 过滤是「替模型做选择」:与其把所有工具丢给模型让它纠结,不如根据模型特性预先筛掉不适合的。这是「工具系统为模型服务」的体现。

四、过滤的其他维度

除了 apply_patch vs edit/write,注册表还有其他过滤维度:

• websearch 的开关:取决于 Provider 是否支持(某些 Provider 有原生搜索能力,或配置了搜索服务)。
• 条件性工具:某些工具只在特定条件下启用(如 plan 工具只在特定模式、lsp 是实验性)。
• 权限过滤:结合第 4 章权限,把当前 Agent 无权用的工具隐藏掉(可见性过滤)。

这些过滤叠加,最终给模型一个「当前最合适、最精简」的工具集。

五、插件工具的适配

插件工具用「模式校验」(zod)定义参数,和内置工具用的 Schema 不完全一样。注册表会做一个适配——把插件工具的 zod 定义转成统一的格式,这样它就能和内置工具一起被调度。

插件工具(zod 定义) ──适配──► 统一格式 ──► 进入注册表
​

这种适配让插件作者可以用更熟悉的 zod 写工具(降低门槛),同时不破坏注册表的统一性。第 11 章详讲插件。

六、模型看到的工具列表怎么来

把本节和第 4、5 章串起来,模型实际看到的工具列表是这样来的:

注册表汇总(内置 + 自定义 + 插件)
   │
   ▼ 按模型过滤(apply_patch vs edit/write 等)
   │
   ▼ 按权限过滤(隐藏当前 Agent 无权用的)
   │
   ▼ 附加子 Agent 描述(task 工具会列出可委派的子 Agent)
   │
   ▼ 触发插件钩子(让插件能改工具定义)
   │
   ▼ 最终工具列表(喂给模型)
​

这是一条「从全量到精简」的流水线。理解了它,你就知道模型每次看到的工具不是固定的,而是动态算出来的。

七、本节要点回顾

1. 注册表是工具中央清单:汇总内置 + 自定义 + 插件三类来源。
2. 内置工具:read/write/edit/grep/glob/bash/task/todo/webfetch/websearch/skill/apply_patch 等。
3. 按模型过滤:不同模型看到的工具集不同(如补丁偏好模型用 apply_patch,禁 edit/write)。
4. 过滤理由:避免混淆、扬长避短、减少上下文。
5. 其他过滤:websearch 开关、条件性工具、权限可见性过滤。
6. 模型看到的列表是动态算出来的:汇总 → 模型过滤 → 权限过滤 → 加子 Agent 描述 → 插件钩子 → 最终列表。

工具进注册表了,下一节讲执行时的「上下文」——工具怎么知道当前会话、怎么请求权限。