第十四章 ClaudeCode如何节省Token

在内容进入上下文窗口之前，如何通过三层防御体系精准控制其大小，以防止窗口溢出或不必要的压缩。

以下是该章节核心内容的总结：

1. 三级入口闸门体系

为了应对工具输出过大（如海量日志或并行搜索）带来的挑战，系统在三个维度实施预算控制：

• 单工具结果级别（50K 字符限制）：

  • 当单个工具输出超过 50,000 字符时，系统会触发持久化机制：完整内容写入磁盘，模型仅接收到一个包含文件路径和前 2,000 字节预览的替代消息。

  • 特殊例外：Read 工具被设定为“永不持久化”，因为它通过自身的 maxTokens 参数控制大小，且避免了“模型读取持久化文件”的死循环。

• 单消息聚合级别（200K 字符限制）：

  • 针对并行工具调用场景（例如同时发起 10 个 Grep），系统限制单轮对话中所有工具结果的总量不超过 200,000 字符。

  • 状态冻结机制：为保护提示词缓存（Prompt Cache），系统采用“三态分区”管理（必须应用、已冻结、新增）。一旦模型看到了某个结果，该状态就会被冻结，确保后续调用中字节级一致，防止缓存失效。

• Token 计数级别：

  • 系统结合“API 规范计数”与“运行时粗略估算”来实时追踪上下文占用情况。

2. 精细化的 Token 估算模型

在两次 API 调用之间，系统使用字符长度除以经验系数进行估算：

• 普通文本/代码：采用 4 字节/token 的保守系数。

• JSON 文件：由于包含大量单字符 token（如 {, ", :），其密度是普通代码的两倍，系数被设为 2 字节/token，以防止严重低估导致的溢出。

• 多媒体文件：图片和 PDF 文档统一按 2,000 token 固定值估算，避免将其 Base64 编码计入 JSON 序列化路径而导致的灾难性高估。

3. 处理并行调用的“计数陷阱”

并行工具调用会导致消息数组出现交错结构，多个 assistant 记录共享同一个 message.id 和 usage。

• 回溯修正（Backtracking）：tokenCountWithEstimation 函数在计算时会向前回溯到共享同一 ID 的第一个分片，确保所有交错的工具结果都被纳入统计。

• 原则：宁可高估触发提前压缩，也不要低估导致 API 报错。

4. 辅助计数与回退方案

• countTokens API：在需要极高精确度时（如评估工具定义的开销），系统会调用专用的计数端点，虽然会有额外的网络延迟。

• Haiku 回退：当专用计数 API 不可用时，系统会利用 Haiku（小模型）通过 max_tokens: 1 的请求来“白嫖”精确的输入 token 使用量，这是一种极具工程巧思的低成本替代方案。

5. 核心设计洞察

• 安全优于优化：Token 预算被视为一种安全机制。系统在所有环节都倾向于保守策略（如 JSON 密度的处理和并行回溯），因为低估的代价是 API 调用失败。

• 架构耦合：为了追求性能优化（Prompt Cache），系统被迫引入了复杂的**有状态状态机（ContentReplacementState）**来管理预算，展示了底层优化如何反向约束高层功能设计。

总结而言：第14章揭示了 Claude Code 如何通过持久化闸门、聚合预算、多系数估算和回溯修正，在 200K Token 的竞技场内建立了一套纵深防御体系，确保了系统的稳定性和成本的可预测性。