工具暴露策略：直接列表、延迟发现与代码模式
工具是否注册、模型能否发现、某次操作是否获准，是三个不同的判断。
学完你能做到
- 能推演六种暴露方式
- 能区分规格字节预算与历史 预算
- 能定位配置过滤与工具身份冲突
本课目录 · 4 节
1. 注册不等于初始可见
目录中的工具先经过资格筛选，再构造 与规格，分配 。初始请求只包含选定规格；Deferred 工具由后续搜索发现。执行时仍要处理参数、授权和环境。
Hidden 主要收敛暴露表面，不能单独当成权限防火墙。的 tool 查找按身份返回已注册 ，没有用初始可见列表作为这一查找的权限条件。拒绝还要看注册 policy、入口与工具授权。
运行时按身份查找 ↗codex-rs/core/src/tools/registry.rs:576–585
注册时策略过滤 ↗codex-rs/core/src/tools/registry.rs:422–436
2. 六种方式对应三个表面
| 状态 / 条件 | 结果 | 边界 |
|---|---|---|
| Direct | 初始列表有； 可用 | 不走延迟发现。 |
| DirectModelOnly | 初始列表有 | 不提供嵌套代码调用。 |
| Deferred | 初始列表省略；可搜索； 可用 | 已注册但省略初始完整规格。 |
| DeferredModelOnly | 省略初始列表；可搜索 | 不提供嵌套代码调用。 |
| CodeModeOnly | 只提供嵌套调用 | 不在初始列表或搜索表面。 |
| Hidden | 不在这些可见/可发现表面 | 不应据此推断完成了授权隔离。 |
枚举与能力判断 ↗codex-rs/tools/src/tool_executor.rs:51–96
Direct 与 Deferred 在最终策略里互斥。支持搜索且策略允许延迟时，去掉 Direct；否则去掉 Deferred。CodeModeOnly 模式还要求对应的代码调用入口可保留。
3. 资格、缓存和字节预算先于表面选择
普通 工具检查可见性；Apps 工具还检查连接器和 policy。 缓存保存不可变元数据及规格预算，不是连接或授权快照。等价目录可以复用 身份，不能据此复用某次批准。
资格和缓存 ↗codex-rs/core/src/mcp_tool_exposure.rs:77–130
agent-plugin 来源的 规格受单项 8,000 字节、合计 64,000 字节限制；超限会使用 Hidden， 仍可能被注册。这是规格序列化字节额度，和后保留原文的 64k 额度无关。
规格常量 ↗codex-rs/core/src/mcp_tool_exposure.rs:18–19
预算处理 ↗codex-rs/core/src/mcp_tool_exposure.rs:131–158
4. 配置覆盖和名称冲突
策略合并服务及连接器的 omit_tools_from，处理 direct-only namespace，再按能力与工具模式转换表面。strict third-party CodeModeOnly 是特殊分支：冲突的 omit 配置被忽略，使符合资格的外部工具保留延迟入口；原先不合资格或超预算的 Hidden 不会因此重新放开。
表面配置合并 ↗codex-rs/core/src/tools/spec_plan.rs:197–285
严格外部工具分支 ↗codex-rs/core/src/tools/spec_plan.rs:602–623
最终计划记录身份冲突。开启 error_on_tool_collisions 时，重复工具身份或 namespace 所属源冲突返回 ToolCollision。 固定本次请求的 binding 和 ，晚执行的调用仍对应曾展示给的那一版。
冲突失败策略 ↗codex-rs/core/src/tools/spec_plan.rs:475–518
本步计划快照 ↗codex-rs/core/src/session/step_context.rs:24–48
沿着源码读
以下定位均锁定本课程版本。先读注释与分支，再深入类型定义。
实现推演
推演一个合格 工具：支持/不支持搜索，省略 direct，省略 code mode，或超单项规格预算。逐项列出最终表面，并标出仍依赖具体模式的组合。
阅读练习无需模型账号。示例命令请先确认目录与环境。
自测与边界检查
Deferred 代表工具尚未注册吗？
展开自测答案
不代表。它省略初始规格并保留发现能力，注册和初始可见是两层。
规格的 64,000 字节与历史保留的 64k 相同吗？
展开自测答案
不相同。对象、单位和发生阶段不同；不能拿一项额度解释另一项容量。