很多人做 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?pwd6fkr
Claude Code Token预算策略全解析：AI Agent上下文工程、工具结果持久化、Prompt Cache、Token计数与成本优化
发布时间：2026/5/16 5:12:38
很多人做 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?pwd6fkr
