IronClaw 渐进式工具披露：tool_search 命名空间目录头的设计与实现

IronClaw 渐进式工具披露tool_search 命名空间目录头的设计与实现【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw导读本文围绕 IronClaw Agent OS 中tool_search桥接工具的命名空间目录头namespace catalog header展开深入剖析这条被注入到系统提示词system prompt中的一行模板如何被源码渲染为「工具总数 授权命名空间 代表性工具名」的结构化索引。你将理解 IronClaw 渐进式工具披露progressive tool disclosure为何需要它、它如何受字节预算与安全描述safe-description约束以及tool_search → tool_describe → tool_call完整发现链路在 crates/loop/ironclaw_loop_host 中的真实实现与测试验证。目录头模板一行文本承载的发现协议IronClaw 将tool_search桥接工具的描述文本同时用作「常驻目录索引」——模型每次看到的可见工具列表只是实际能力的精选子集更多工具按需加载而tool_search的描述必须告诉模型当前到底还有多少工具、分布在哪几个授权命名空间、以及搜索结果以何种形式返回。该模板位于 crates/loop/ironclaw_loop_host/prompts/tool_search_namespace_header.md全文如下These {{total_tools}} tools are available on demand across {{namespace_count}} authorized namespaces. Search results include complete schemas when schema_completetrue; otherwise use tool_describe. Never report a capability unavailable before searching. Namespaces:这行模板定义了四条关键语义全部被下游实现逐一落实模板要素语义对应实现{{total_tools}}按需可发现的工具总数渲染时被替换为各命名空间工具数之和{{namespace_count}}授权命名空间数量渲染时被替换为BTreeMap去重后的命名空间数schema_completetrue搜索结果已含完整 schema可直接调用否则须先tool_describe见 tool_disclosure.rs 的CatalogSearchResultNever report a capability unavailable before searching模型在搜索之前不得断言能力不可用见 tool_disclosure_protocol.md 的强制步骤 1模板末尾的Namespaces:是命名空间列表的锚点随后的每一行以- namespace (count)形式列出语义命名空间及其工具数再由Representative tools (fair namespace rounds):引出代表性工具名。源码注入与占位符渲染模板通过include_str!在编译期嵌入二进制与空目录描述一并成为两个常量tool_disclosure.rs 第 20-21 行const EMPTY_CATALOG_DESCRIPTION: str include_str!(../prompts/tool_search_empty_catalog.md); const NAMESPACE_CATALOG_HEADER: str include_str!(../prompts/tool_search_namespace_header.md);渲染入口是catalog_index_tool_search_description_for_modetool_disclosure.rs 第 696-756 行核心流程如下若当前披露模式不含命名空间摘要includes_namespace_summaries()为假则退化为纯字母序索引通过catalog.discoverable_namespaces(policy)获取经过授权策略过滤的命名空间分组若没有任何可发现工具直接返回 tool_search_empty_catalog.md 的内容No additional tools are available on demand. Tools already listed are available and do not need to be searched.否则执行占位符替换let mut description NAMESPACE_CATALOG_HEADER .trim_end() .replace({{total_tools}}, total.to_string()) .replace({{namespace_count}}, namespaces.len().to_string());依次追加每个命名空间条目\n- {namespace} ({count})当累计长度超出预算时以\n- additional authorized namespaces exist; use tool_search截断收尾再以「公平轮次」fair rounds逐命名空间轮流取一个代表性工具名写入Representative tools (fair namespace rounds):之后直到预算耗尽或全部列出若仍有剩余追加\n…and N more — use tool_search(queryservice or action)引导模型继续搜索。字节预算为什么索引只写名字不写描述源码注释tool_disclosure.rs 第 672-687 行明确解释了这一设计约束tool_search的描述会被校验为能力安全描述safe-description存在4096 字节硬上限和敏感内容黑名单超出即导致整轮对话在提示词阶段直接失败因此索引只携带工具名字——若写入工具描述既会撑爆字节预算也可能携带被黑名单拦截的子串代码层设置了更保守的内部预算BUDGET_BYTES 3800另预留TAIL_NOTE_RESERVE 96字节给「…and N more」尾部提示确保永不触顶。测试 index_description_stays_under_the_model_safe_cap_for_a_large_catalog 用 300 个长名工具构造超大目录断言最终描述长度 4096且包含more — use tool_search尾部提示防止回归。命名空间如何划分从 capability id 到语义分组命名空间分组定义在 tool_disclosure.rs 第 319-422 行。DiscoveryNamespace枚举包含 12 个第一方意图分组加一个扩展组agents、coding、data、extensions、memory、messaging、observability、scheduling、settings、skills、system、web以及按扩展 id 命名的Extension(String)。discovery_namespace的映射规则capability id 以builtin.开头 → 走builtin_discovery_namespace二次映射以ironclaw.memory.开头 →Memory以ironclaw.开头 →System其余视为扩展工具取点号前一段作为扩展 id 命名空间。内置工具的语义映射builtin_discovery_namespace示例read_file/write_file/list_dir/glob/grep/apply_patch/shell→codinghttp→webextension_*/ironhub_*→extensionsskill_*→skillstrigger_*→schedulingoutbound_*/notification_*→messagingtrace_commons.*→observabilityadmin_*/operator_config_*→settingsspawn_subagent→agentsjson→data其余落入system。分组结果经BTreeMap按命名空间名与工具名双重排序保证索引文本确定性与缓存稳定性——同一 surface 版本与同一授权策略下每次生成的描述字节完全一致。谁被索引、谁被排除核心工具与桥接工具并非所有工具都会进入命名空间索引。CapabilityCatalog::new构建目录时tool_disclosure.rs 第 146-176 行桥接工具tool_search/tool_describe/tool_call即is_bridge_name与桥接 capability id 被排除出目录剩余条目按is_core_tool_definition或配置档位固定profile pins判定为Core层否则为Discoverable层仅Discoverable层的工具会进入命名空间摘要——因为Core工具如read_file、shell、memory_search、extension_install、trigger_create、outbound_deliver等见 CORE_TOOL_NAMES 第 29-77 行的完整 schema 已在可见列表里直接给出无需重复索引。测试 tool_search_description_summarizes_namespace_and_representative_tool 验证索引必须包含可发现工具google-calendar__list_events、必须出现授权命名空间计数fixture (1)、且不得重复列出已直出 schema 的核心工具read_file。授权策略索引与结果同口径收窄命名空间索引与tool_search结果、tool_describe一样都受CapabilitySurfacePolicy过滤。discoverable_namespaces(policy)只统计policy.permits_capability_id允许的条目测试 tool_search_description_is_narrowed_by_policy 用allow_only策略验证允许列表内的github__list_issues仍会出现在索引中而未被允许的google-calendar__list_events名字绝不泄漏进索引——否则收窄后的 profile 会通过tool_search自己的描述旁路绕过结果过滤直接读到全部工具名。模式开关REBORN_TOOL_DISCLOSURE 环境变量命名空间摘要是否启用由披露模式决定定义在 crates/loop/ironclaw_loop_host/src/tool_disclosure_mode.rs通过环境变量REBORN_TOOL_DISCLOSURE配置取值模式命名空间摘要完整签名配置档位固定offOff否否否compactCompact否否否signaturesSignatures否是否namespaces默认Namespaces是是否bridgedBridged是是是默认值为Namespaces生产臂未设置或空值沿用默认识别不了的值与显式off都失败关闭到Off回滚路径非 UTF-8 取值同样回退到Off并在 debug 级记录日志。测试 tool_disclosure_mode_defaults_namespaces_with_off_kill_switch 覆盖了全部取值的大小写、非法值与开关语义。完整发现协议从「看不见」到「调起来」目录头只是发现链路的入口。配套的 tool_disclosure_protocol.md 定义了模型侧完整行为协议当可见工具列表中出现tool_search说明列表只是精选子集需要某项能力但没看到匹配工具时先调用tool_search(queryservice or action)它返回带schema_complete标记的排序匹配结果结果schema_completetrue时按返回的parametersschema 直接调用为false、标记缺失或结果有歧义时先调用tool_describe(nametool)取完整 schema通过tool_call(nametool, arguments{\field\:\value\})执行arguments为字符串编码的 JSON 对象已知精确名字后也可直接以该名字调用审批、策略、钩子与安全机制走完全相同的路径只有当tool_search返回无相关结果后才能向用户声明能力不可用。tool_search与tool_describe、tool_call三个桥接工具的 schema 定义位于 tool_disclosure.rs 第 558-625 行tool_search接受query必填与limit默认 10、最小 1tool_describe接受nametool_call接受name与arguments。此外tool_disclosure.rs还实现了宽容名称解析——模型无论传点号形式的 capability idgoogle-calendar.list_events、__编码的线缆名google-calendar__list_events还是裸名都能解析到同一目录条目测试见 provider_name_matcher_resolves_non_builtin_dotted_and_encoded_forms。容量控制何时触发按需披露最后目录头的存在与否取决于DisclosureCaps与阈值判定tool_disclosure.rs 第 540-556 行。默认上限为max_tokens 12_000、max_tools 32defer_threshold_tokens在配置了上下文上限时取min(max_tokens, ctx_limit / 10)。select_active_set_for_mode在有效工具 schema 总 token 数不超阈值且工具数不超上限时直出全部定义deferred: false否则只直出核心工具与桥接工具其余全部按需延迟tool_search的描述随之变成命名空间目录头deferred: true。小结tool_search_namespace_header.md这行模板是 IronClaw 渐进式工具披露在提示词面的「门面」它把{{total_tools}}与{{namespace_count}}两个占位符渲染成受字节预算约束的命名空间索引用「公平轮次」给出代表性工具名再用schema_complete与「先搜索再下结论」两条纪律约束模型行为。它的每一次替换、截断与过滤都能在 tool_disclosure.rs、tool_disclosure_mode.rs 及对应测试中找到精确的源码依据——理解这条链路也就理解了 IronClaw 如何在上下文预算内让模型「看得见但不背全量 schema」地调用成百上千个工具。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考