tako 文档 GitHub

19v6-06 · 工具分级与 deferred tools(机制篇)

本篇是 doc/19-v6 文档集的 deferred tools 机制篇:工具分级为什么存在、前缀缓存的失效力学、 client mode 与 hosted mode 的完整链路、各厂商支持矩阵(2026-10-08 实证)、provider 原生通道的接法。 分级的 v6 落点(启用工具全注册 + BeforeModelRewriteState 声明过滤、两档定义)见 19v6-05 §5——本篇不重复裁定, 只给机制背景与 provider 原生通道的对照。本篇不做契约承诺,所有 provider 原生内容均为「背景素材」。 2026-10-20 校正:§1 的 hidden 原文「代码内部/子代理用」先校正为 pi 的操作定义(注册但不可达), 随后裁定 tako 不设 hidden 档——只留 direct / deferred,禁用工具 = 装配时不 append。见 19v6-90 十九修。 2026-10-21 裁定(终态):用户裁 client mode 即终态底座,hosted mode(provider 原生 deferred)不接—— 理由三条见 §6。本篇降为纯背景篇:§4–5 的链路与矩阵保留作将来复用的参考,不作施工面、不进待办。

0. 一句话

工具分级解决「工具一多,声明成本(token / 注意力 / 缓存)爆炸」;deferred tools 是各厂商对同一问题的 协议级回答——目前无标准名、无标准协议,形态碎片化,这正是 v6 把客户端过滤定为默认底座的原因。

1. 为什么需要分级

2. 缓存力学(一切的根源)

3. client mode = v6 现在(手写声明过滤)

4. hosted mode = provider 原生 deferred tools

4.1 名字(无标准)

出处 叫法
Anthropic deferred tool loading + Tool Search(tool_search_tool_bm25_20251119 / regex 变体)
OpenAI tool search(Responses API,{"type":"tool_search"} + defer_loading)
eino 抽象 WithDeferredTools / WithToolSearchTool
pi ToolExposure 的 deferred 档 + tool_search 扩展

4.2 完整链路(请求携带式 hosted,OpenAI 文档 + eino-ext 源码实证)

# 步骤 执行者 输入 输出 作用
0 目录组装 客户端(eino wrapper 每轮附加 WithDeferredTools) 应用的工具注册表 请求 tools 数组:全量 schema + defer_loading 标记 + {type:"tool_search"} provider 本轮知道库存
1 扣留暂存 provider 网关 tools 数组 暂存区(deferred schema 隔离,不进 KV key) 目录保管在上下文外
2 前缀预填充 provider 摘要层 + 常声明工具 + system + messages 前缀 KV;模型开局视野 建立恒定可缓存前缀
3 检索词生成 模型 任务上下文 + 摘要层 query / paths(hosted 下为内部信号) 模型唯一发言点:搜什么
4 索引检索 provider 检索索引 query + 暂存区 命中的工具 schema BM25/regex 机械匹配(无任何智能成分)
5 末尾注入 provider 基础设施 命中 schema 追加在上下文末尾(只增区) 模型看见 schema 且前缀不动
6 工具调用生成 模型 注入的 schema 普通 function_call / tool_use 与常声明工具同构
7 工具执行 客户端 function_call tool result(下轮 messages 追加) 客户端常规职责,零特殊逻辑
8 事件记录 provider → 客户端 步骤 3–5 过程 响应里的 tool_search_call / tool_search_output item 可观测;多轮回放保持状态

循环规则:同轮可 3→6 多遍(需要第二个工具就再搜);跨轮重复 0–2 时前缀字节相同 → 缓存命中,注入区累积在尾部。

4.3 关键机制点

4.4 缓存友好的三条路线(同一原则的实现谱系)

原则:变更只能落在「只增不改」的尾部,或干脆不落在模型上下文里。

路线 工具变更落在哪 前缀旧段 代表
前缀外通道 provider 暂存区(不进 KV key) 原样 defer_loading(Anthropic / OpenAI / DeepSeek)
尾部追加 messages 尾部 原样 Anthropic tool_addition(inline-tools beta);OpenAI additional_tools;Kimi messages[].tools
认损 tools 段中段 被破坏(发现期) client 过滤 = v6 现在

5. 厂商支持矩阵(2026-10-08 实证)

厂商 支持 形态 eino-ext 组件
Anthropic ✅ defer_loading + 内置 BM25/Regex tool search + inline-tools beta ✅ 已接(claude.go 翻译 defer_loading 与 tool search 工具)
OpenAI ✅(Responses API,gpt-5.4+) hosted + client-executed 两式 + namespaces + additional_tools ❌ 组件未翻译(API 有、组件没有)
DeepSeek ✅ Messages API 认 defer_loading(服务端 400 校验:"at least one tool must have defer_loading=false") —
Kimi ✅(私有变体) 消息级工具声明 messages[].tools:已加载工具从顶层 tools[] 剥离、schema 走消息通道 —
Gemini ❌ 仅标准 function calling(feature request 仍开) —
Qwen / 豆包 / GLM ❌ 未见 仅标准 function calling(托管 web_search 是厂商自带工具,与用户工具 deferred 无关) —

要点:

6. v6 的裁定与升级路

附 · 证据清单(全部 2026-10-08 实读)