IronClaw 工具发现评测契约：渐进式工具披露的检索基线、端到端基准与上线门禁

• 人工智能
• AI 应用
• 交互助手
• AI Agent

导读：本文基于 IronClaw 仓库 docs/internal/tool-discovery-evaluation.md 展开，系统讲解 IronClaw 在改变「渐进式工具发现（progressive tool discovery）」交互之前必须满足的评测契约：检索质量基线（Retrieval baseline）、端到端基准（End-to-end benchmark）与上线门禁（Rollout gates）。读完本文，你将掌握REBORN_TOOL_DISCLOSURE五个披露模式臂的语义与选择方法、如何运行仓库内已固化的 50 工具/72 意图评测语料，以及如何产出可复现、可审计的端到端评测报告。

一、评测契约要解决的问题

IronClaw 是一个以隐私、安全与可扩展性为核心的 Agent OS。当工具目录不断增长时，把全部工具的完整 JSON Schema 一次性灌入模型上下文，会带来 token 开销与上下文污染问题。为此，IronClaw 引入了渐进式工具披露（progressive tool disclosure）：不再全量披露授权工具，而是通过tool_search→tool_describe→tool_call的紧凑协议，按需检索、按需描述、再发起调用。

改变这种交互方式之前，仓库要求先满足 issue #7405 定义的证据要求，核心原则是：检索质量（retrieval quality）与端到端模型行为（end-to-end model behavior）是两套相互独立的测量，任何一方都不能替代另一方。也就是说，仅凭检索指标好看不能证明模型在实际任务中会用对工具；仅凭端到端任务通过也不能证明检索排序本身没有退化。评测契约因此由「检索基线 + 端到端基准 + 上线门禁」三段组成。

二、检索基线：crate 级质量门禁与规模基线

2.1 评测语料：50 个工具、72 条人工判定意图

检索质量门禁由ironclaw_loop_hostcrate 拥有，入口是测试函数tool_search::tests::committed_corpus_quality_gate_and_benchmark_report，定义在 crates/loop/ironclaw_loop_host/src/tool_search.rs。它从tests/fixtures/tool_search_relevance.json加载语料，并断言语料本身合法：

• 至少 50 个工具，且必须覆盖builtin、mcp、wasm、extension_lifecycle、provider五种工具类型（源码中逐一校验，缺失即失败）；
• 60～100 条判定意图（当前语料为 72 条），每条意图带有类别与相关性标注（1～3 级），且所有被判定工具必须真实存在于语料中；
• 意图必须覆盖九大检索类别：精确名称（exact_name）、别名（alias）、规范能力 ID（canonical_id）、参数（parameter）、嵌套 schema（nested）、歧义查询（ambiguous）、provider 名称（provider）、硬负例（hard_negative）与无匹配（no_match）。

这保证了门禁既测「找得到」，也测「不该找时别乱找」。

2.2 质量门禁阈值与基准对比

测试同时构建两套排序器并对比：

• 候选排序器（candidate）：AuthorizedToolSearchIndex授权工具搜索索引；
• 基线排序器（baseline）：legacy_rank传统排序（对应旧披露模式的检索方式）。

质量门禁不仅要求候选达到绝对阈值，还要求候选必须实质性优于基线：

此外，除no_match之外的每个意图类别还要分别通过类别级门禁：类别 Recall@5 ≥ 0.80、类别 NDCG@10 ≥ 0.75，防止某一大类拖后腿时被总体均分掩盖。

2.3 规模基线：100 / 500 / 1000 工具的确定性扩展

第二个测试committed_scale_baseline_covers_100_500_and_1000_tools（同样位于 crates/loop/ironclaw_loop_host/src/tool_search.rs）验证目录规模扩大时的排名稳定性：

• 保留全部已判定工具与意图，然后在20 个合成命名空间（asset_hub、billing_ops、document_vault、device_fleet等，见源码常量SCALE_NAMESPACES）上添加确定性干扰项（distractors）；
• 生成器使用固定种子（SCALE_NAMESPACES/SCALE_ACTIONS/SCALE_NOUNS的长度取模偏移），命名空间分布均匀（最大与最小命名空间工具数之差 ≤ 1），并且同一 catalog 构建两次必须字节级一致，以证明定义确定性；
• 只提交确定性质量指标到基线文件tests/fixtures/tool_search_scale_baseline.json；索引构建与查询耗时仅打印用于诊断，不作为门禁——因为耗时随宿主机器与构建 profile 波动。

仓库当前提交的规模基线数值如下：

值得注意的是：合成新增项是刻意不判定（unjudged）的干扰项。它们只验证排名稳定性、暴露索引成本随目录增长的变化，不代表 950 条人工判定的新用户意图。引入新的语义域时，必须在基础语料中补充新判定的工具与意图，而不是依赖合成干扰项。

运行两条检索证据的命令（--nocapture用于查看打印的诊断信息与最差查询）：

cargo test -p ironclaw_loop_host committed_corpus_quality_gate_and_benchmark_report -- --nocapture cargo test -p ironclaw_loop_host committed_scale_baseline_covers_100_500_and_1000_tools -- --nocapture

三、端到端基准：五个披露模式臂

3.1 五种披露形态

端到端基准要求对同一任务集、同一 catalog 种子，跑完全部五个「臂（arm）」：

1. 全量广告 schema（Full advertised schemas）：把所有授权工具的完整 schema 都广告给模型——对照组；
2. 当前紧凑协议：tool_search→tool_describe→ 调用的现状方案；
3. 有界完整签名（Bounded complete signatures）：tool_search直接返回有界完整签名；
4. 命名空间摘要 + 有界完整签名：先给命名空间概览，再按需取签名；
5. 命名空间摘要 + 有界完整签名 + 已评审 profile pins：在上一臂之上，把经人工评审的关键工具 pin 进提示。

五个臂都从同一个二进制选择，通过环境变量REBORN_TOOL_DISCLOSURE切换。其解析实现在 crates/loop/ironclaw_loop_host/src/tool_disclosure_mode.rs：

源码中ToolDisclosureMode::from_raw的匹配规则值得注意：

• 取值不区分大小写（COMPACT等价于compact）；
• 未设置或空字符串时落到默认值namespaces——即渐进式披露默认开启；
• 未知值 fail closed 到off：解析器会把garbage之类的非法值视为off并打 debug 日志，保证回滚路径永远可达；非 UTF-8 环境变量同样 fail closed 到off（对应测试tool_disclosure_mode_non_unicode_env_fails_closed）。

各模式由is_enabled()、includes_complete_signatures()、includes_namespace_summaries()、includes_profile_pins()精确门控：只有Signatures/Namespaces/Bridged含完整签名，只有Namespaces/Bridged含命名空间摘要，只有Bridged含 profile pins。

3.2 Profile pins：人工评审的「锚点工具」

bridged臂的可选 pins 通过环境变量REBORN_TOOL_DISCLOSURE_PROFILE_PINS提供，格式是以能力面 profile 为键、规范能力 ID 列表为值的 JSON 对象。契约给出的初始已评审基准映射为：

REBORN_TOOL_DISCLOSURE_PROFILE_PINS='{"interactive_tools":["gmail.list_messages","google-calendar.list_events","github.search_code"],"mission_tools":["github.search_issues_pull_requests","github.get_file_content"],"subagent_tools":["github.search_issues_pull_requests","github.get_file_content"]}'

底层解析在 crates/loop/ironclaw_turn_runner/src/runtime.rs 的parse_tool_disclosure_profile_pins中实现，其失败语义非常严格：

• 无效 JSON、任何非法 profile ID 或非法 capability ID，都会在运行时启动阶段整体拒绝（ProfilePinsNotUnicode、Profile、Capability错误，解析原因被保留而非吞掉）；
• 变量未设置时为空 pin 映射，正常运行；
• 某个 pin 不在当前生效的授权面（authorized surface）内时，该 pin无效果——即 pins 只收窄/突出，绝不放宽授权。

对应测试包括profile_pin_config_parses_typed_capability_ids、profile_pin_config_rejects_the_entire_map_when_any_id_is_invalid与profile_pin_environment_rejects_invalid_configuration_at_runtime_startup，分别覆盖正常解析、整体拒绝与启动期拒绝。

3.3 端到端基准的执行要求

• 100 / 500 / 1000 工具目录必须保留相同的判定任务；每个规模可以追加确定性干扰项，但报告必须记录生成器版本与种子；
• 基准运行器应该在每个臂之间重启服务，保持模型路由与 catalog 种子不变，并且把每次观测选用的REBORN_TOOL_DISCLOSURE值记录下来；
• 每个模型/provider 配置至少跑1 次冷启动 + 3 次热启动重复，报告给出中位数、最差情况、离散度（spread）与失败类别计数。

四、端到端报告 schema：逐任务观测、不藏失败

4.1 观测对象字段

每个观测对象记录一个 (臂, catalog 规模, 模型路由, 温度, 冷/热类别, 重复次数) 组合。契约给出了 schema_version 2 的完整示例：

{ "schema_version": 2, "catalog": { "generator_version": "tool-search-scale-v2", "seed": 7405, "tool_count": 500, "namespace_count": 20 }, "arm": "signatures", "model": { "provider": "provider-id", "model": "model-id", "temperature": 0.0 }, "run": { "thermal_class": "warm", "repetition": 1 }, "task": { "id": "email-to-calendar", "completed": true, "correct_tool_recalled": true, "unauthorized_tool_leaks": 0 }, "counts": { "model_turns": 3, "discovery_turns": 1, "tool_calls": 3, "tool_search_calls": 1, "tool_describe_calls": 0 }, "tokens": { "input": 12000, "cached_input": 8000, "output": 600 }, "latency_ms": { "time_to_first_correct_tool_call": 900, "end_to_end": 2400 }, "cache": { "tool_definition_signature_changes": null }, "failure": null }

字段语义要点：

• arm永远是REBORN_TOOL_DISCLOSURE的规范选择值（即off/compact/signatures/namespaces/bridged之一，与观测一一对应）；
• cache.tool_definition_signature_changes在 provider 链路无法给出可信的签名变更计数时为null，绝不估算；
• failure存在时使用稳定类别，如retrieval_miss、invalid_arguments、authorization_denied、approval_blocked、provider_error、task_incomplete；
• 聚合报告必须保留底层逐任务观测，防止「一个宽泛的总分掩盖某项失败能力」；
• 隐私边界：本地合成 fixture 校验任务拥有的参数字段，但原始提示词、用户内容、凭据与工具参数不保留在聚合基准观测中。

4.2 哪些指标由确定性 CI 提供，哪些只由部署运行器提供

契约明确划定了证据边界：确定性仓库测试负责门禁——目录构造、检索质量、协议形态（protocol shape）、授权拟合（authorization fitting）、命名空间公平性（namespace fairness）、稳定序列化。但provider token 用量与网络/模型延迟不会被 JSON 字节数或本地测试耗时估算，这两个字段只能由部署的冷/热运行器填充。

这一分离设计的目的很直白：防止「确定性 CI 代理」被包装成端到端模型证据。本地跑得快不能证明线上模型表现好，这两类数据必须严格区分来源。

五、必测场景与结果呈现

5.1 七个必测场景

• 精确工具名与规范能力 ID 查询；
• 别名与自然语言动作查询；
• 多个相关工具并存的歧义查询；
• 只出现在嵌套 schema 里的「仅参数词汇」查询；
• 相关但被拒绝的工具与允许的干扰项混在一起（测授权过滤与排序的交互）；
• 跨命名空间工作流，典型如「找到一封邮件并创建日历事件」（email-to-calendar即报告 schema 示例中的任务 id）；
• 无匹配任务——正确行为是报告「不存在已授权的能力」，而不是硬凑一个工具。

5.2 结果呈现要求

报告必须包含：中位数、最差情况、离散度、失败类别计数；启用了 provider 缓存的测量额外报告缓存输入 token 与工具定义签名变更次数；缺失的 provider 缓存测量显式保持null。

六、上线门禁（Rollout gates）：改动放行的硬条件

任何对渐进式披露交互的改动，只有在以下条件全部成立时才能上线：

1. 零泄露：不得有任何未授权的命名空间、签名、provider 引用、排序结果或可调用目标泄露；
2. 既有检索门禁不回退：召回率、MRR、NDCG、no-match 门禁必须继续满足；
3. 完整签名任务减少发现轮次：signatures类任务降低discovery_turns，同时不增加可归因于「缺 schema」的无效调用；
4. 任何 catalog 规模下任务完成率不得实质性回退；
5. 延迟加载稳定的 provider在整个发现与调用过程中保持字节一致的广告工具面（byte-identical advertised tool surface）。

另外，契约明确指出「有界编排（bounded orchestration）」尚不是一个臂——它要等到前面的交互改动上线、且本报告证明「模型往返仍是主导延迟来源」之后，才需要单独的设计与 issue。也就是说，这份契约本身是有版本节奏的：先证明检索与披露形态，再谈编排优化。

七、在仓库中如何落地与验证

• 阅读检索门禁实现：crates/loop/ironclaw_loop_host/src/tool_search.rs（语料校验、候选/基线对比、规模确定性、20 命名空间常量）；
• 阅读披露模式解析与 fail-closed 语义：crates/loop/ironclaw_loop_host/src/tool_disclosure_mode.rs；
• 阅读tool_search/tool_describe工具面与目录索引广告方式：crates/loop/ironclaw_loop_host/src/tool_disclosure.rs（含TOOL_SEARCH_NAME/TOOL_DESCRIBE_NAME常量与catalog_index_tool_search_description_for_mode的按模式广告逻辑）；
• 阅读 profile pins 的启动期解析与错误类型：crates/loop/ironclaw_turn_runner/src/runtime.rs；
• 语料与基线 fixture：crates/loop/ironclaw_loop_host/tests/fixtures/tool_search_relevance.json与tool_search_scale_baseline.json。

运行建议：先在本地跑第二章的两条检索测试确认门禁基线，再按第三章的五个臂配置REBORN_TOOL_DISCLOSURE与（可选）REBORN_TOOL_DISCLOSURE_PROFILE_PINS，最后按第四章 schema 逐任务记录观测并聚合成含失败类别统计的报告。务必遵守「臂间重启服务、模型路由与种子固定、记录每个观测的臂值」三条纪律，才能得到可对比、可审计的端到端证据。

• 人工智能
• AI 应用
• 交互助手
• AI Agent