很多人做 AI 编码工具时，第一反应是换更强的模型、写更长的提示词、塞更多项目背景。真正到了工程落地阶段，最先把系统拖垮的，往往不是模型不够聪明，而是上下文被工具输出、日志、搜索结果、历史消息迅速挤爆。Token 预算策略解决的正是这个问题：内容进入模型之前，先经过一套入口闸门，把该保留的保留、该预览的预览、该压缩的压缩。
一、为什么 Token 预算是 AI Agent 的生命线
AI Agent 与普通聊天机器人最大的区别，是它会持续调用工具。一次搜索可能返回几十 KB，一次命令可能吐出几百 KB 日志，多路并行工具还会把结果堆到同一轮消息里。如果没有预算控制，模型的上下文窗口会被低价值内容快速吃光，真正需要推理的业务信息反而被挤出去。
Token 预算不是简单的“省钱”。它更像服务网关里的限流、缓存系统里的淘汰策略、数据库里的查询保护。目标有三个：第一，防止超大工具结果直接冲垮上下文；第二，让多工具并行时不会因为总量叠加而爆表；第三，让系统始终知道当前上下文大概用了多少，从而决定是否触发压缩。
单工具结果级：单个工具输出太大时，完整内容写入磁盘，只给模型一段预览。
单消息聚合级：一轮工具调用的所有结果加起来不能无限膨胀。
Token 追踪级：用 API 返回的精确 usage 加上增量估算，持续追踪上下文规模。
压缩治理级：当窗口接近上限时，交给自动压缩或微压缩做历史清理。
二、第一道闸门：单工具结果超过 50K 字符怎么办
在 Claude Code 的设计里，单个工具结果默认有一个关键阈值：50,000 个字符。超过这个规模的文本，不会完整塞进模型输入，而是写入磁盘文件，再给模型发送一段替代消息。替代消息里包含完整结果保存路径，以及开头约 2KB 的预览。
这套设计非常像“先把大包裹放到仓库，再给收件人一张提货单”。模型不需要立刻背下整份长日志，但它知道完整内容在哪里，也能从预览判断下一步是否需要继续读取。
2.1 为什么不是直接截断
直接截断最大的问题是信息丢失，而且模型不知道自己看到的是不完整内容。持久化方案更安全：它明确告诉模型“完整输出已保存”，同时给一小段可读预览。这样既省上下文，又保留了继续追查的入口。
2.2 为什么空结果也要处理
工程上还有一个容易被忽略的细节：工具没有输出时，也不能总是发空内容。某些模型或渲染链路可能把空工具结果误判为对话边界，导致后续生成提前结束。因此系统会注入类似“某工具已完成但没有输出”的占位信息。这个细节很小，但体现了 Agent 工程的真实复杂度：不是只要逻辑正确就行，还要照顾模型输入格式的边界行为。
2.3 图片为什么不能简单落盘替代
文本结果可以用路径加预览替代，但图片类内容通常需要直接给模型看。因为视觉输入本身就是模型判断的重要依据，如果只给路径，模型无法理解图像内容。所以图片类 block 会绕过普通文本持久化流程，进入专门的多模态估算和传输逻辑。
三、50K 阈值不是死规则：背后有一条优先级链
很多系统把阈值写死，后面所有工具一刀切。Claude Code 的设计更灵活：每个工具可以声明自己的最大结果规模，远程配置也能动态覆盖，特殊工具还能选择不走通用持久化。
优先级 | 触发条件 | 实际策略 | 工程意义 |
1 | 工具声明无限制 | 永不按通用规则持久化 | 适合自身已经有输出控制能力的工具 |
2 | 远程配置命中 | 使用远程下发阈值 | 线上可灰度调参，不必重新发布 |
3 | 工具声明自定义阈值 | 与默认 50K 取更保守值 | 避免工具自己把口子开太大 |
4 | 无特殊声明 | 使用默认 50K | 给绝大多数工具提供安全底线 |
这里最值得学习的是“保守优先”。工具可以有自由度，但不能随意突破系统安全线。对企业级 AI Agent 来说，工具越多，越不能把上下文预算交给单个工具自己决定。
四、第二道闸门：为什么还需要 200K 单消息聚合预算
单工具 50K 看起来已经够安全，但并行工具会制造新问题。假设模型同时发起 6 个搜索，每个搜索返回 40K 字符。单独看都没超过 50K，但合起来就是 240K。对 API 来说，这些结果可能最终被合并成一条用户消息，瞬间吃掉巨量上下文。
所以系统增加了第二道闸门：单消息内所有工具结果的聚合上限。默认思路是把一轮工具结果控制在约 200K 字符以内。它不是为了惩罚工具，而是为了防止一次并行调用把后续推理空间吃光。
4.1 分组难点：内部消息与 API 看到的不一样
内部执行时，多个工具结果可能分散在不同消息记录里，中间还可能插入进度消息、附件消息等。但最终发给 API 时，连续的工具结果可能会被合并。预算控制必须按照 API 实际看到的分组方式来算，而不能只看内部数组里临时分散的结构。
这就是很多 Agent 系统容易踩坑的地方：日志里看起来每条消息都不大，真正发送时却已经合并成一个巨大的输入包。预算系统必须理解“线路上的真实形态”。
五、三态分区：为什么预算控制会变成状态机
如果没有 Prompt Cache，系统每轮都可以重新判断：哪些工具结果太大，哪些应该替换成预览。但 Prompt Cache 要求前缀稳定，模型之前看过什么，后续最好保持一致，否则缓存命中会被破坏。于是预算执行不能是无状态函数，而必须变成状态机。
状态 | 含义 | 处理方式 | 为什么重要 |
mustReapply | 之前已经替换过 | 每轮重新应用同一份替代文本 | 保证缓存前缀字节级稳定 |
frozen | 之前看过但没替换 | 后续保持完整内容 | 不能突然改成预览，避免缓存失效 |
fresh | 本轮新增结果 | 可参与预算裁剪 | 只对新内容做决策，降低副作用 |
这套机制有一个非常重要的工程启示：性能优化会反向改变架构设计。为了让 Prompt Cache 稳定命中，预算系统必须记住过去的替换决策，并且在后续请求里原样重放。
六、第三道闸门：Token 计数为什么要“精确 + 估算”混合
上下文预算最终要落到 Token 上。问题是，Token 的精确数量并不总是随时可得。API 调用完成后，usage 字段能告诉你精确用量；但两次 API 调用之间新增了工具结果、附件、进度内容时，系统必须先用粗略估算填补空白。
6.1 API usage 包含哪些部分
一次模型调用的 usage 通常不只包含普通输入和输出，还可能包含缓存写入 token、缓存读取 token。对长会话 Agent 来说，缓存读取看起来可能很大，因为每轮都在复用之前的稳定前缀。预算系统需要把这些字段一起纳入上下文规模判断，而不是只看模型本轮输出了多少。
6.2 粗略估算为什么不能太乐观
常见经验是普通英文文本或代码大约 4 个字符对应 1 个 Token。但这只是粗略估算。JSON、JSONL、JSONC 这类内容更密集，很多符号本身就会消耗 Token，因此更接近 2 个字符对应 1 个 Token。如果仍然按普通文本估算，就会严重低估大型 JSON 对上下文的压力。
图片和 PDF 又是另一类特殊情况。它们不能按 base64 字符串长度粗暴估算，否则一个 1MB 文件会被误判为极其夸张的 Token 消耗。更合理的做法是用多模态输入的专门规则或固定估算值，避免灾难性高估。
七、并行工具调用的 Token 计数陷阱
并行工具调用带来的最大坑，是消息结构会交错。多个 assistant 片段可能来自同一次 API 响应，拥有同一个响应 ID，中间夹着多个工具结果。如果系统简单地从“最后一个带 usage 的 assistant 消息”之后开始估算，就会漏掉前面夹在同 ID assistant 之间的工具结果。
正确做法是：找到最后一次带 usage 的 assistant 片段后，继续向前回溯，直到找到同一个响应 ID 的最早片段，再从那里之后估算所有新增消息。这样才能把交错的工具结果全部算进去。
这个细节看似底层，却直接影响系统稳定性。如果低估上下文，系统会以为还有空间，继续塞内容，最终 API 调用可能因为超过窗口限制而失败。
八、什么时候需要额外调用 Token Count API
日常阈值判断可以用“精确基线 + 增量估算”。但在某些场景下，系统需要更准确的预检，比如评估工具定义本身会占多少 Token、判断一批消息是否能安全发送、或在不同模型之间做路由选择。此时可以调用专门的 Token Count API，在真正生成前获得输入 Token 数。
如果标准计数接口在某些平台不可用，还可以用小模型回退：发送一个极小输出上限的请求，不是为了让它回答，而是为了拿到 usage 信息。这是一种“用一次低成本调用换精确输入规模”的工程技巧。
九、四层防御：从工具输出到自动压缩的完整体系
把所有机制串起来，可以看到 Token 预算不是孤立功能，而是一套防御体系。第一层拦单个大结果，第二层拦一轮大消息，第三层追踪窗口使用量，第四层负责历史压缩和上下文修剪。
单工具持久化失败时，完整结果仍可原样返回，后续还有聚合预算和压缩兜底。
消息级 frozen 内容如果已经不能改命运，就接受短期超额，交给后续压缩清理。
粗略估算有偏差时，宁可稍早压缩，也尽量避免窗口溢出。
远程阈值可以动态调整，让线上系统在不同场景下快速收紧或放宽。
十、普通用户和工程团队应该怎么用好这套思想
这套机制不只是底层实现，也能指导我们日常使用 AI 编码工具。很多时候，Agent 表现变差并不是模型变笨，而是上下文被无效输出污染了。
10.1 搜索要精准，不要一次性撒网
让 Agent 搜索代码时，优先让它返回文件名、函数名、调用链，而不是直接把所有匹配行全文吐出来。先定位，再读取局部，通常比一次性全文搜索更稳定。
10.2 大日志先过滤，再交给模型
日志、构建输出、测试失败信息都可能很长。不要直接把整段输出扔进去，先保留错误堆栈、关键时间点、异常类型、失败文件路径，再让模型分析。
10.3 大 JSON 特别危险
很多人以为 100KB JSON 不算大，但 JSON 的 Token 密度往往高于普通代码。配置、接口响应、埋点数据、导出数据都要谨慎处理，最好先摘要结构，再读取关键字段。
10.4 需要完整文件时，优先走专门读取能力
命令行直接 cat 一个大文件，很容易触发持久化或预览截断。专门的读取能力通常有自己的范围控制和 Token 控制，更适合让模型稳定看到必要内容。
十一、最值得学习的架构思想
这套 Token 预算策略背后，有三条非常适合迁移到其他 AI Agent 系统的思想。
11.1 入口治理优先于事后补救
上下文爆了再压缩，只是最后补救。更好的系统会在内容进入前就做预算控制，把大输出、大消息、大附件提前分流。
11.2 缓存稳定性会重塑状态管理
Prompt Cache 让长会话更便宜、更快，但也要求前缀稳定。为了满足这个约束，系统不得不记录替换决策、冻结已看内容、复用旧预览。这说明性能优化不是外围能力，而会深入影响核心数据结构。
11.3 预算系统宁可保守，不要冒险低估
高估的代价通常是提前压缩、稍微增加一次处理；低估的代价可能是请求失败、上下文损坏、Agent 任务中断。对生产级系统来说，稳定性优先级高于极限压榨窗口。
十二、总结：真正成熟的 Agent，必须学会管理上下文
AI Agent 的能力不只来自模型本身，还来自它如何管理输入。Token 预算策略解决的是一个非常底层、也非常现实的问题：哪些内容值得进入上下文，哪些内容应该被预览，哪些内容要被持久化，什么时候该压缩，什么时候该冻结。
如果把模型比作大脑，那么上下文就是工作台。工作台再大，也不能无限堆满日志、搜索结果和历史消息。真正成熟的 AI 编码系统，一定会把上下文当成稀缺资源来经营。谁能把 Token 预算、工具结果治理、Prompt Cache 稳定性、压缩恢复机制做成一套完整工程体系，谁就更接近可长期运行、可持续交付、可控成本的 AI Agent。
资料参考：https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd=6fkr
