1.1 如果不注册呢？#

不把工具放进 tools 数组，只在聊天消息里写一句「你可以调用 get_weather，参数是 {…}」，模型也能输出一段看起来很规整的 JSON——但它只是普通文本：Provider 不会标记 finish_reason，不会校验参数，不会给 call_id。本地程序必须自己解析、自己判断、自己校验。

这条「文本协议」路线在过去很流行：2023–2025 年的 ReAct、Claude Dev/Cline、Roo Code 和 Kilo Code 早期版本都是这么干的——在 System Prompt 里用 XML/Markdown 描述所有工具，模型按约定输出调用指令，客户端捕获符合格式的文本块后解析执行。它的历史价值是快速兼容不支持原生 Tool Calling 的模型渠道；代价是没有 Provider 层的语法约束，模型偶尔写跑偏（参数名拼错、少一个括号、自由发挥一段解释），可靠性全靠框架兜底。随着 Strict Tool Use、结构化输出等能力普及，这条路线慢慢退出了主流。

1.2 算一笔账#

结论先摆出来：要做原生 Tool Calling，工具就必须出现在请求的 tools 参数里。Provider 在推理开始前就要拿到所有工具的完整契约，否则无法建立语法约束，也就无法产出合法的原生 tool call。听起来像「人被杀就会死」一样自然——直到我们期望一个 Agent 在会话中灵活调度上百个工具。

按原文的保守估算：一个工具定义（名称 + 描述 + 参数 Schema）平均 400 token，200 个工具就是 80k token。主流旗舰模型的实际可用上下文窗口虽然几个月内从 150k 涨到了 400–500k，但注意力机制在大量低相关性工具描述上仍会产生信息稀释与「上下文腐烂」——窗口变大，不等于可以当败家子。

1.3 Skills 容易，Tools 难#

Skills 之所以能优雅地渐进披露，是因为它的本质是纯文本内容：用户提问 → 模型判断需要某 Skill → 客户端把对应 markdown 追加到消息末尾。关键点在于：所有信息增量都发生在消息末尾，不碰请求最前方的任何结构。

这对 Prompt Cache 机制极其友好：主流 Provider（Anthropic、OpenAI）的缓存逻辑是「两次连续请求的前缀在 token 层面完全一致，就直接复用上一次的 KV 计算结果」——哪怕只修改或插入一个 token，后续缓存全部作废。Skills 的加载方式恰好不动前缀，庞大的基础上下文稳定命中缓存。

但 Tools 不同。原生 Tool Calling 要求工具定义出现在 tools 参数里，而 tools 数组永远驻扎在请求的最前端。设想：Agent 有 200 个工具，第一轮只注册 5 个高频的；第三轮模型需要「创建 PDF」工具，客户端只剩两条路：

• 改 tools 数组 → 请求最前方的结构变了 → 整个 Prompt Cache 报废 → 几万甚至几十万 token 的历史全部重算，又慢又贵；
• 不改 → 让模型在普通对话里按格式纯文本输出参数 → 失去原生调用的一切保障，参数幻觉和格式错误由客户端兜底。

于是核心死结出现了：

原生工具调用的可信度建立在「Provider 在推理前就知道所有工具的完整契约」这一前提上；而渐进式披露的本质是「推理前坚决不让 Provider 知道所有工具」。这两个需求在系统结构上是天然互斥的。

理解了这一点，才能看懂下面四种方案各自在跟什么较劲。

2.1 方案一（Provider 原生）：Anthropic Tool Search Tool#

Anthropic 在 2025 年 11 月发布 Tool Search Tool。原理上，客户端仍然把全部工具契约发给 Anthropic，但把不那么必要的工具标上 defer_loading——被标注的工具不会进入模型初始上下文，Anthropic 在服务端维护一个隐藏的工具目录：

1
{
2
  "tools": [
3
    { "type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25" },
4
    {
5
      "name": "learning_create_cards",
6
      "description": "Create learning cards...",
7
      "input_schema": { "...": "完整严格 schema" },
8
      "defer_loading": true
9
    }
10
  ]
11
}

模型需要某工具时，调用搜索工具（BM25 变体接受自然语言查询，上限 500 字符；regex 变体让模型自己写 re.search() 正则，上限 200 字符；两者都搜索工具名、描述、参数名和参数描述），Provider 在服务端检索后返回特殊的引用：

1
{ "type": "tool_reference", "tool_name": "learning_create_cards" }

随后 Provider 在当前对话位置把这个引用展开成完整工具定义——搜索结果和最终的工具调用甚至可以出现在同一次 assistant response 里，客户端只需要执行最终的具体工具。

缓存为什么没坏？关键在于 defer_loading 的特殊语义：完整定义是在发现位置追加的，没有回头修改最前面的工具前缀。历史消息里出现过的 tool_reference 会被 API 全程展开，模型后续轮次可以直接复用已发现的工具，无需重新搜索。

短板：强绑定 Anthropic。OpenAI 自家的 Responses API 提供了同构的 tool_search + defer_loading（支持按需加载 Function、Namespace 和 MCP 工具），但广大 OpenAI 兼容生态——vLLM、OpenRouter、各家自建兼容层——通常只能二选一：发送 tools 就全部进模型上下文，不发送 Provider 就不承认对应的原生调用。它们缺少 defer_loading / tool_reference 这种 Provider 级协议，于是才有了下面两条客户端自救路线。

2.2 方案二（客户端折中）：Stub 注册 + load_tool_schemas#

既然 tools 数组一个字都不能动，那就「注册全部工具、但把未被需要的契约压缩到极限」。这是原文作者自己实现过的方案：

• 每个真实工具注册成一个 stub：保留真实工具名，描述压到一句话，参数契约换成宽松的万能外壳；
• 工具列表常驻一个客户端实现的 load_tool_schemas 工具。

1
{
2
  "name": "learning_create_cards",
3
  "description": "从学习笔记创建记忆卡片。调用前必须先调用 load_tool_schemas 获取完整参数契约。",
4
  "parameters": {
5
    "type": "object",
6
    "properties": { "arguments": { "type": "object", "additionalProperties": true } }
7
  }
8
}

调用流程：

1
模型认为自己需要制卡能力
2
  → 调 load_tool_schemas({ "tools": ["learning_create_cards"] })
3
  → 客户端把完整 JSON Schema 作为普通 tool_result 消息返回
4
    （追加在对话尾部，不碰任何前缀，缓存安全）
5
  → 模型按刚拿到的 schema 调用对应的 stub

账很好算：200 个工具从约 80k token 压到约 15k（每个 stub 约 60–80 token），降低约 80%。

短板：这是「半原生」方案——stub 数量依然是 O(N)，没有实现真正的按需加载，每个 stub 都常驻上下文、真实占用注意力；Provider 的语法约束约束的是那个宽松外壳，真实参数的合法性完全靠客户端自己保证。

2.3 方案三（客户端激进）：search_tools + invoke_tool#

再进一步。注册工具有两个基本前提——「工具在 Provider 注册」和「模型能遵守契约」。第一条可以收窄到极限：注册一个全能力工具；第二条随着旗舰模型指令遵循能力的提升，「把契约以文本形式交给模型、它照着填参数」已相当可靠：

1
{
2
  "name": "invoke_tool",
3
  "description": "执行工具目录中的工具。请先用 search_tools 找到目标工具，再按返回的契约填写 arguments。",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "tool_name": { "type": "string" },
8
      "arguments": { "type": "object", "additionalProperties": true }
9
    },
10
    "required": ["tool_name", "arguments"]
11
  }
12
}

tools 数组从此恒定，只有 search_tools 和 invoke_tool 两个：

1
1. 模型 → search_tools({ "query": "create flashcards from study notes" })
2
2. 客户端 → 返回目录条目（工具名 + 一行描述，不含完整 schema）
3
3. 模型 → invoke_tool({ "tool_name": "learning_create_cards", "arguments": { "notes": "..." } })
4
4. 客户端 → 按 tool_name 取出真实 schema 校验 → 执行 → 回传结果
5
   （校验失败 → 返回结构化错误 → agent 修正重试）

初始上下文占用从 O(N) 直接变成 O(1)——工具目录里躺 100 个还是 10,000 个工具，模型永远只看到两个（几百 token）。目录本身可以是本地索引、数据库表甚至 embedding 检索服务，检索自由度在自己手里。

代价：Provider 只认识 invoke_tool 的外层 schema，不认识内层 schema——外层有语法约束，arguments 内部却是不设防的黑盒，真实校验必须客户端全权承担，失败就返回结构化错误让 agent 修正；真实参数变成「JSON 里的 JSON」，多一层转义与嵌套；且对模型指令遵循能力有门槛，弱模型会在第 3 步频繁出错。

补偿：所有具体调用收敛到同一个入口后，校验、授权、审计、限流这些横切关注点只需要在 Gateway 一处实现——多用户/多 Agent 场景下是意外之喜。

2.4 方案四（Provider 原生 + 协议改造）：Kimi K3 动态加载工具#

Moonshot 在 Kimi K3 的 API 里提供「动态加载工具」机制，思路是：工具声明不一定要待在请求开头的 tools 字段里，它可以是一条消息。

1
{
2
  "messages": [
3
    { "role": "system", "content": "You are Kimi, an AI assistant..." },
4
    { "role": "user", "content": "Calculate fuel consumption." },
5
    {
6
      "role": "system",
7
      "tools": [
8
        {
9
          "type": "function",
10
          "function": {
11
            "name": "Calculator",
12
            "description": "计算器，只支持单个算术表达式的求值",
13
            "parameters": {
14
              "type": "object",
15
              "properties": { "expr": { "type": "string" } },
16
              "required": ["expr"]
17
            }
18
          }
19
        }
20
      ]
21
    }
22
  ]
23
}

关键语义：携带 tools 的 system 消息与普通消息地位相同——它出现在 messages 的哪个位置，工具就从哪个位置开始对模型可见；动态加载的工具与顶层声明的全局工具并存；声明必须是完整定义，不能只传工具名；这条消息不能再带 content 字段，否则请求报 400。

缓存规则官方给了四条：

总结成一句话：追加，不要插入；注入了就别删。 工具声明被当成普通对话内容的一部分往后追加，前缀纹丝不动——和 Skills 的加载路径一模一样。

官方参考实现也很朴素：顶层只注册客户端实现的 search_tools → system prompt 里告诉模型工具目录/领域关键词 → 模型需要时先 search → 应用把命中工具的完整声明追加到末尾 → 模型原生调用。

我的评价：这是协议层面的改造，不需要 defer_loading、tool_reference 这类新概念，声明格式与顶层 tools 完全一致；位置语义直觉且可控，天然缓存友好；同时保留 Provider 侧的原生约束，不会像 invoke_tool 那样把参数黑盒化。原文作者说它「十分优雅，令人眼馋」，我同意。

旁证：Anthropic 在 2026 年 7 月推出的 mid-conversation system messages 和 tool changes，也允许通过对话中途的 system message 添加或移除工具并保留前缀缓存——但没有人回头重新采用 Kimi 的方案。这个「为什么」很有意思，见 4.3 节。

3.1 社区补充思路#

原文评论区一百多楼里，有几条值得记下的补充：

• bash/CLI 收敛：只暴露一个 bash 工具（或「伪 bash」），把其他工具下沉成 CLI，靠 --help 完成逐层披露。Vercel 的 just-bash、Pi 的思路（五六个极简工具覆盖读写与 bash，每个描述只有一句话、三四十个单词）都是这个路线。本质上把披露从 Provider 协议层挪到了命令行环境。适用面仅限于能跑 OS 的 Agent——跑在业务系统内部的 Agent 用不了 bash（社区里 jelly15 的疑问）。
• 大小模型协同：bod 提出用便宜快的模型（如 DS V4 Flash）在会话/子 Agent 开始时先做一次工具编排预筛选，把可能用到的工具提前挑进新上下文，loop 里再让便宜模型做上下文整理、预压缩的杂活。
• 子代理专职校验：LLMeme 提出起一个子 Agent 专门负责输出/校验工具调用（本质是 invoke_tool 的加强版）。反对意见也很实在：子 Agent 转述损失信息、增加延迟、双上下文管理复杂度。
• 一条重要的实测反例：yuwkGoo 在 pi agent 上试过 invoke_tool + search_tools，结果是 grok 4.5 基本不再调用工具了（除了 GPT 系，其他模型普遍有这个倾向）；后来改用本地 BM25 做轻量 tool search，效果反而更好。这条反馈直接说明：方案三的成败不只在架构，更在检索质量——模型找不到、搜不准，就不会用。

4.1 如果让我选，我会怎么选#

第一步不是选方案，而是量化：工具总数、平均定义长度、单会话实际激活的工具数、当前缓存命中率。不量化就上方案，是拍脑袋。在此基础上我的排序是：

• 工具 < 20：全量注册。省心，且渐进披露的额外请求成本未必划算。
• 工具多 + 目标 Provider 有原生机制：优先 defer_loading（Anthropic）或动态加载（Moonshot）。协议层面兼容缓存，参数校验不黑盒，工程成本最低。
• 工具多 + 自建/多后端兼容：方案三为主，但必须把本地工具检索质量当一级指标来做（BM25 起步，目录规模大到语义检索有用再上 embedding），并接受「客户端校验代码会膨胀」的事实——校验逻辑写在哪，复杂度就在哪，这就是把黑盒从 Provider 挪到客户端的代价。
• 工具 schema 极复杂 + 团队短期不想写通用校验器：方案二（stub）是合理过渡。

关于社区里「通用工具 vs 特化工具」的争论（「四肢健全」论 vs 特化论），我的看法是两者不矛盾：通用外壳负责寻址与横切，特化 schema 负责参数语义。真正的分界在「谁维护索引」：内部系统 Agent 的工具集稳定，索引成本低，特化 schema 价值高；跨团队共用的工具网关，通用外壳 + 统一审计限流反而更值。

4.2 如果要落地，我会怎么验证#

方案之间的争议大多停留在观点层面，缺可复现的对照实验。如果我来做，会这样设计：

• 同一任务集（覆盖各工具的使用频率梯度），分别跑「全量注册」和候选方案；
• 观测指标：工具调用成功率、参数错误率、单任务总 token 消耗、TTFT、缓存命中率、任务完成率；
• 先埋点 2 周拿基线，再单场景灰度，最后全量。

指标口径必须先写清楚——「缓存命中率」按请求数还是按 token 数算，结论会完全不同。

4.3 三个问题#

1. 位置敏感性问题：大模型对首尾的 prompt 更敏感，工具契约出现在对话中间（Kimi 方案的形态），模型遵循契约的能力会不会下降？

   「不好说塞满 80k 契约的 agent 和渐进披露之后的 agent 哪个更差」。

   如果 Kimi 方案要广泛落地，这是最值得先做对照实验的点。

2. 净账问题：渐进披露增加请求次数，减少了单次成本，长任务下到底省不省？我猜存在一个阈值。但是具体的阈值在哪里，需要进一步测试。

3. 方案收敛悬念：Kimi 方案被证明可行（Anthropic 2026 年 7 月也做了 mid-conversation tool changes 且保留缓存），为什么主流 harness 没有跟进？一方面可以说是积重难返，还有一层是：工具声明一旦可以出现在消息序列里，prompt injection 的攻击面也随之增大——社区里也有人提到过「权威性」与注入风险的考虑。

4.4 这篇文章对我的修正#

读这篇文章之前，我对工具加载的理解停留在「全量注册 + 增大上下文窗口」的层面，顶多听说过「MCP 工具多了会挤占上下文」。最改变我看法的一点是：工具动态加载的瓶颈不是检索算法，而是请求结构——tools 数组在前缀里的位置决定了它与 Prompt Cache 的天然冲突，这个约束比「工具多不多」深刻得多。以后评估任何「工具按需加载」方案，我都会先问一句：它动了请求前缀吗？

Hook：该给的上下文自动给#

规范写得再好，要靠人每次记得去贴，迟早会漏。Trellis 的思路是别靠人。

在支持 hook 的平台上，有三个时机会自动注入：

• 会话启动时，注入开发者身份、当前 git 状态、进行中的任务、spec 索引和你最近的 journal。注入的是一份索引和状态报告，不会把所有文档整个塞进去。
• 每条消息发出时，注入一小段当前任务状态对应的提示，让 AI 清楚现在在哪个阶段、下一步该做什么。这段文字写在 workflow.md 里，想改流程就改这个文件，不用去改 hook 脚本。
• 子代理启动前，把这个任务需要的 spec 和需求文档注入给它。

所以你不用每次开场先说一遍”先读一下规范”。写一次，之后每次都在。

没有 hook 的平台也有办法：靠 AGENTS.md 之类每次必读的入口文件，让 AI 自己去读。效果会差一点，文档里也写明了各平台的能力差异。

按任务给 spec，不是一股脑全灌#

最常见的做法是写一个很大的 CLAUDE.md 或 .cursorrules，每次全塞进去。文件一长，容易被截断，模型也容易抓不住重点。

Trellis 把 spec 拆成多个文件，再用任务目录里的 implement.jsonl 和 check.jsonl 列出”这次实现要读哪几份、这次检查要读哪几份”。每行就是一个文件路径加一句理由：

1
{"file": ".trellis/spec/backend/error-handling.md", "reason": "接口错误格式"}

这样做前端任务的时候，不会把数据库规范也带进来。清单里只放 spec 和调研文档，不放要改的源码。

Spec 绑定代码路径（动态加载）#

这是官方文档里标成 beta 的一个功能，我觉得思路很好。你可以在 spec 的 frontmatter 里写 paths，声明它约束哪些文件：

1
---
2
name: commands-workflow
3
description: Workflow command and resolver contracts
4
paths:
5
  - packages/cli/src/commands/workflow.ts
6
  - packages/cli/test/commands/workflow*.test.ts
7
---

之后 AI 读或改到这些文件时，对应的规则会在那个时刻送过来。同一会话里已经送过、内容没变的，不会重复发，隔一段时间才用一个简短的提醒；spec 改了，或者会话被压缩过，就重新发完整内容。规则会出现在它要约束的那处修改旁边，而不是在会话开头说一句，聊了一百轮之后就被冲淡了。

经验沉淀回 spec#

任务做完之后，trellis-update-spec 会判断这次有没有值得长期遵守的做法。有的话写进 .trellis/spec/，只跟这个任务有关的事实留在任务目录里。

文档里有一个说法我挺认同：用得越多，AI 越懂你们。前提是有人把 review 里反复出现的意见变成 spec。今天 review 里说了一句”这里要校验入参”，明天它就应该成为规范里的一条，不再需要有人每次说。

跨会话记忆：记在文件里#

AI 本身没有跨会话的记忆，Trellis 的办法是让仓库来记。

每次 finish-work 会往 .trellis/workspace/你的名字/journal-N.md 追加一条，写这次做了什么。下一次会话启动时 hook 会读到近期的 journal 和进行中的任务。任务本身的需求、设计、调研也都留在 .trellis/tasks/ 里。

文档里有句话说得很清楚：下一次 AI 会话会重新读取仓库状态，不需要上一段聊天记录，也能知道任务是什么、哪些 spec 适用、下一步该做哪一步。聊天记录压缩了、换了台电脑、换了个 AI 工具，都不影响。

Agent 一定会去读对应的 docs 吗？#

坦白说，不能保证 100%。大模型是概率系统，强模型大多会遵守读取规则，但偶发忽略也是可能的。

降低遗漏概率的做法：

• 在路由表里写清楚触发条件，而不是只列文件名
• 对 plan / code / review 等不同阶段分别指定要加载的规则
• 更进一步：用 hooks 强制注入索引，在任务开始时把相关文档片段自动塞进上下文

常用规则要不要也放到 docs 里？#

没必要。渐进式披露的目标是把低频、任务相关的细节下沉，而不是把每天都用的规则藏起来。

比如 response style、文件搜索策略这类几乎每次都会用到的内容，继续放在入口文件更合适。过度拆分反而会增加路由成本和维护负担。

文件太大会有截断问题吗？#

会。有佬友反馈，当核心文件达到约 18KB 时，部分 agent 应用可能触发截断，导致文件中后段的规则 agent 根本看不到——这时候整理就不仅是优化，而是刚需了。