Tool Surface Economics：稳定全量前缀还是渐进式能力加载？

[tt-a1i]

这是 OpenPI 产品哲学总纲 #299 的第一个专题。

问题不是“工具越少越好”或“缓存后工具就免费”，而是：在不同模型、Provider、Session 长度和任务分布下，怎样让一项能力产生的价值覆盖它的完整成本？

先统一 Function Call / Tool 的含义

Runtime 把 Tool Definition 发给模型
  name + description + JSON Schema
        ↓
模型输出结构化 Tool Call
        ↓
Pi / OpenPI 校验并执行
        ↓
Tool Result 进入会话
        ↓
模型继续回答或调用下一个工具

模型输出的是调用意图，真正执行函数的是 Runtime。

一项 Tool 的成本至少包括：

1. Schema 成本：名称、描述和参数定义进入模型请求；
2. 选择成本：模型要从可见工具中判断调用哪个；
3. 往返成本：Tool Call 和 Tool Result 往往带来下一次模型采样；
4. Result 成本：工具结果进入历史并可能在后续请求中回放；
5. 轨迹成本：错误选择可能放大成更多 turn、tool call、reasoning 和 wall time。

Prompt Cache 主要降低稳定前缀的重复处理成本。它不等于免费，也不会自动消除上下文占用、工具选择干扰、额外往返或长 Tool Result。

还必须把三个指标分开：

• 有效模型上下文：cached definitions 仍可能占用模型可见上下文并参与选择；
• 计费 usage：uncached、cache read、cache write 的价格和 TTL 随精确模型/API 而变；
• 网络传输：Prompt Cache 通常不承诺缩小 wire payload。Provider server-state 或 Gemini explicit CachedContent 等引用机制是另一层能力。

Prompt Cache 也不是 OpenPI Session-owned 状态。新 Session 首请求可能复用相同隔离域、模型、TTL 和前缀下的已有 cache；同一长 Session 也可能因 TTL、路由、Compaction 或 prefix 变化而 miss。必须看 Provider-reported usage，不能用“第几轮”推断命中。

两条正交轴

发现与授权

策略	谁决定发现/启用	优点	主要风险
Explicit intent	用户明确意图触发 Runtime 加载	普通任务固定面最小；授权容易解释	文本分类误触发/漏触发；中途直载可能绕开 native load point
Adaptive discovery	模型通过小型 gateway/catalog 发现能力	用户不必记产品词；可能随模型增强	固定入口税；误加载；发现与昂贵执行授权容易耦合

Discovery 和 Authority 的完整讨论见 #312。

Provider 序列化

机制	定义怎样进入上下文	主要边界
稳定全量 top-level tools + allowed subset	工具全集保持稳定，只限制当轮可调用子集	初始 Schema 与选择面仍存在；支持面依模型/API
中途修改 top-level tools	第 K 轮重写顶层工具面	可能使此前 system/developer/history 前缀失配
Native append/reference	在 Tool Result/load point 后追加定义	可保留旧 prefix；仍有新增 Schema、发现、兼容和权限成本
Gateway/fallback	用稳定小入口包装不支持原生追加的 Provider	可能多一轮；不应退化成万能 Workflow

Pi 0.84.1 只有在 Tool 执行期间发生纯追加 setActiveTools() 时，才通过 addedToolNames 走 native path。before_agent_start 直载、tool removal/replacement 会使用普通 active-tool projection；激活同时改变 system prompt snippet/guidelines 时，即使 Schema 可 deferred，旧 prefix 也可能变化。

OpenPI 当前默认 explicit，adaptive 是用户显式 opt-in。能力组集合尽量单调；但 Background、Tasks、Goal 等生命周期工具仍可能出现或消失，不能把“能力组已加载”理解成顶层工具面永久不变。

摊销模型

下面的 first write / later read 指某个精确 Provider、API、模型、隔离域、TTL、路由和可匹配 prefix 下的 cache 生命周期，不对应 OpenPI Session 的首轮/后续轮次。

假设某能力组 Tool Definition 大小为 S，到第 K 个 turn 才第一次需要它：

• 稳定全量：此前每次请求都包含 S，是否按 read/write/fresh 处理取决于实际 cache；
• 顶层渐进变更：前 K-1 轮不含 S，但第 K 轮可能让截至 K 的失配历史 H(K) 重新处理或重新写 cache；
• Native deferred：前 K-1 轮不含完整定义，第 K 轮在历史 load point 追加定义，旧 prefix 通常可以保留。

顶层变更的激活成本更接近：

新增 Schema S
+ 失配历史 H(K) 的重新处理或 cache write
- 原本可按 cache-read 价格读取的 H(K)

因此：

• 能力从未使用时，渐进加载明确避免该组的 Schema 与选择面；
• K≈1、能力几乎必用时，稳定核心可能通过省去发现/加载动作获益；
• K 很晚时并不必然更优：顶层 mutation 少带了前期 Schema，却可能重算更长历史；native append 才更接近只新增后缀；
• 频繁加载、卸载、重排会增加 surface churn，但实际代价仍须按精确模型/API 验证；
• 盈亏平衡还取决于 TTL、路由、cache read/write 价格、Schema 大小、采用率、任务收益和加载后复用次数。

“常用工具全量、低频工具渐进”是合理假设，但常用应由真实采用率和净收益定义，不能只根据功能听起来重要。

当前证据

• #20 记录了 OpenPI 从约 31 个常驻模型工具，经过紧凑入口、单一网关，收敛到当前低常驻表面的过程。
• 两份 explicit/adaptive 运行记录目前仍是 operator-local / 尚未进入目标分支的证据，不能作为外部可复核引用。已知观察包括 gateway 的小型固定税、机制采用很低和少数错误加载，但在 canonical report 绑定 revision、model、task、usage 与原始 receipt 前，不据此宣称普遍质量因果。
• #45 在冻结的 OMP 17.2.12 / DeepSeek 诊断中记录到约 16.1k vs Pi-native 约 1.7k 的首请求输入（约 9.4×）。这是单一版本/配置的静态输入观察，不代表所有 Session 总成本，也不能外推到 OMO。
• #46 的冻结 Terminal 任务切片记录了 OMP 与 OpenPI 的 provider-token/结果差异；它限定于该模型、任务和配置，不能推出普遍产品排名。
• #84 讨论 Tool Schema 的有界设计和完整 surface fingerprint。
• #156 跟踪逐 turn prompt-cache 失效诊断。
• #191 区分 OpenPI、Pi/provider adapter 和 Provider 的缓存所有权及证据边界。

仍然不知道什么

• OpenAI/Anthropic 对 top-level tool definitions 的理论失效顺序已有官方合同；当前未知的是 Pi/OpenPI 对每个精确 model/API/adapter path 实际采用 top-level mutation、stable allowed subset 还是 native append，以及真实丢失的 read/write tokens；
• Gemini implicit cache 等路径的工具渲染顺序、隔离与真实 breakpoint 仍缺少同等强度的公开合同；
• 多长的 Session、怎样的采用率会让全量常驻胜过渐进加载；
• 更多可见工具对不同强度模型的选择质量影响；
• Dynamic Tool Surface 与后续长轨迹之间是因果关系还是采样相关性；
• Background / Workflow 的状态型工具是否仍造成不必要的 surface 变化。

建议的决策标准

在改变默认策略前，至少需要同时测量：

• 每 turn active-tool count、完整 Schema bytes 和 fingerprint；
• provider-reported input、cache read、cache write；
• 能力组首次加载 turn 和后续 surface 变化；
• Tool Call 采用率、正确率和无理由加载率；
• task success、turns、tool calls、wall time 和 cost；
• 新 Session、短 Session、长 Session分别报告；
• ordinary coding 与真正需要 Delegate / Workflow 的任务分赛道。

本专题不预设必须保留当前默认。当前暂定方向是：

Pi 核心工具稳定常驻；高采用、高收益且接口足够小的工具，可以基于证据考虑进入稳定核心；昂贵、低频能力按组渐进加载；一旦加载，在 Session 内尽量保持稳定。

欢迎提供固定模型、固定任务、固定 Provider、可回放 usage 的反例或数据。请把 Observation、Correlation、Verified Cause 分开陈述。

[tt-a1i]

后续 lifecycle 专题已展开：Tool lifecycle across compaction：动态工具如何跨越上下文压缩与 Session 恢复？ #311。它把 Runtime 权威能力状态、Compaction Summary、Provider-native deferred load point 和新的 cache epoch 分开讨论，并给出同进程压缩、Session 恢复、Provider 切换与权限收缩的可证伪实验。

[tt-a1i]

2026-08-30 补充：把“发现/授权”与“工具定义如何进入上下文”拆成两条轴

前面的候选方案把两个问题混在了一起：

1. Discovery / Authority：模型怎样知道能力存在，谁决定启用，Runtime 怎样限制权限；
2. Serialization / Cache：工具定义是常驻顶层、动态修改顶层，还是通过 Provider 原生引用追加到历史位置。

这两个选择可以正交组合。Explicit Intent 不等于一定修改顶层 tools；Adaptive Discovery 也不等于一定绕开缓存。

结合当前 Pi 0.84.1、OpenPI 实现与 Provider 文档，补几条边界：

• Pi 的动态工具加载器有“纯追加”路径：返回 addedToolNames，由 Runtime 结合 Provider 能力决定使用 OpenAI tool_search 输出或 Anthropic tool_reference；不支持时才回退到顶层工具变化。
• OpenPI 目前 adaptive gateway 路径会走这套 addedToolNames 语义；直接 before_agent_start 加载路径并不天然等价。
• 因此，“一旦渐进加载就必然击穿整个前缀缓存”不是普遍结论；但原生 deferred 也不代表免费，仍有 cache read、发现调用、schema 展开、注意力和生命周期成本。
• “能力从未使用”时，渐进加载通常有明确优势；“很晚才使用”是否更优，取决于 Provider 行为、命中率、会话长度和加载后复用次数，不能只凭 K 很晚下结论。
• 已加载 capability 的集合可以在 Session 内单调增长，但具体 tool list 仍可能受 Goal、后台任务和生命周期状态影响，不能把“加载过”直接等同于“永远以同一顶层前缀存在”。
• 本帖原先列出的 benchmark 链接当前在 main 上不可访问，应先视为本地/未发布证据，不能当作公开可复核结论。

问题归档：

• 发现与授权策略：#312
• 跨 Compaction、恢复与 Provider 变化的生命周期：#311
• 成本模型、实验矩阵和证据门槛：#313

当前不据此改变默认策略。下一步应先补可复核实验，再讨论“常用前置、冷门渐进”或 adaptive 是否成为默认。

[tt-a1i]

开放问题：模型厂商已经优化 Function Call，工具选择成本还重要吗？

群聊中提出了一个很好的反问：LLM 厂商普遍针对 Function Call / Tool Use 做过训练，工具即使位于前缀，模型是否已经能很好处理，所谓“注意力干扰”会不会被夸大？

暂定答案只能是：优化会改变成本曲线，但不能推出成本为零。

需要分开验证：

• 选择质量：专门训练可能提高名称匹配、参数生成和多工具选择准确率；
• 请求成本：Tool name、description、Schema 仍进入请求，cache read 也仍有价格；
• Context 占用：缓存不会把工具定义从有效上下文中删除；
• 发现机制：OpenAI tool search、Anthropic deferred/tool reference 的存在，说明 Provider 也在主动减少大工具目录的常驻展开，而不是假设无限工具面天然无害；
• 模型差异：强模型可能更能驾驭大工具面，弱模型也可能从“能力始终可见”中获益，不能跨模型外推；
• 任务分布：工具很多但任务几乎必用，与工具很多且大部分从不使用，是两种不同实验。

最小对照应固定同一 Provider/model snapshot、任务与工具集合，改变：

1. 可见工具数量与 Schema bytes；
2. 无关但语义相近的 distractor 数量；
3. 全量顶层 tools、allowed subset、native tool search/deferred 三种呈现方式。

同时测 Tool Call 选择与参数正确率、task success、input/cache usage、turn、wall 和 cost。相关证据标准统一进入 #313。

在完成这组对照前，既不能说“工具多必然干扰模型”，也不能说“厂商优化过，所以几十个工具几乎没有代价”。

[tt-a1i]

Function Call 训练优化：官方合同能把问题再收紧一步

核对官方资料后，可以确认两层不同结论：

Source facts

• OpenAI Function Calling 说明函数定义会以模型训练过的 system-message 语法注入，仍计入 context limit 和 input billing；同一指南为了更高准确率，给出“每轮开始时少于 20 个函数”的软建议，并推荐对大或低频 surface 使用 tool search。
• Anthropic Tool Search 报告其典型多服务目录可达约 55k definition tokens，tool search 通常减少 85% 以上；还报告可见工具超过约 30–50 后选择准确度下降。

Evidence boundary

• “模型受过 Function Call 训练”不等于任意规模工具面没有选择或输入成本；
• OpenAI 的 <20 是软建议，Anthropic 的 30–50 与 85% 是该 Provider 自报经验，不能跨模型/API 当作硬阈值；
• OpenPI 仍要在精确 model snapshot、工具接口质量和任务分布下做自己的 distractor/selection 实验；
• 工具数量之外，还应测名称相似度、描述重叠、参数歧义、namespace 分组和 Tool Result 长度。

因此双方极端说法都不成立：不能只凭“厂商优化过”宣称几十个工具几乎无代价，也不能把某个 Provider 的经验阈值写成普遍模型定律。