Claude Code源码解构：压缩提示工程（三）：三层压缩策略与实战指南

接上篇（二），我们总结三层压缩策略和实战排障指南。

五、三层压缩策略：苍蝇腿也是肉

源码里其实藏着三种深度的压缩手段，根据 Token 的危急程度自动切换：

5.1 裁剪压缩 (Snip Compact)

在 snipCompact.ts 中定义。这是一种轻量级的”预压缩”，在主压缩逻辑之前运行。它不涉及调用大模型和 Prompt，只是在本地对超长的工具输出结果进行简单的文本头尾裁剪。

• • 触发机制：每次模型调用工具并产生输出时，系统会默认进行检查。当单个工具返回的文本行数或 Token 数超过系统硬编码的”危险阈值”时，自动触发。
• • 适用场景：执行了会产生大量刷屏输出的命令，例如 find / -name "*.ts"、大范围的 grep，或者读取了一个几万行的巨型日志文件。
• • 实际案例：你让大模型跑了一个 find 命令，输出了 5 万行结果。
• • 压缩前：完整的 5 万行字符串
• • 压缩后：只保留前 100 行和最后 100 行，中间用 \n...[49800 lines snipped]...\n 替换

这能瞬间腾出大量空间，且保留了报错或搜索结果中最关键的首尾信息。

5.2 微压缩 (Micro Compact)

在 microCompact.ts 中实现。它的核心思想是”遗忘无用的中间态”。比如你连续运行了 5 次 ls 或 cat，只有最后一次的结果对当前任务最重要，前面的完全可以丢弃。它没有调用大模型生成新的 Prompt 摘要，而是使用了一个硬编码的占位符文本来替换。

• • 触发机制：
1. 1. 基于时间 (Time-based)：系统后台有定时器监控，如果距离上一次助手回复超过了设定时间（如静置超过 5 分钟），且当前 Token 压力较大时触发。
2. 2. 缓存空间不足 (Space-based)：当剩余 Token 空间不足以支撑一次完整的”深度压缩”（约 15k Token）时，系统会优先执行 Micro Compact 来腾出最小可用空间。
• • 适用场景：用户与 Claude Code 的对话中存在大量”试错型”的中间步骤。
• • 实际案例：你在排查一个 bug，连续让 Claude 执行了以下操作：

  1. ls -la ./src/components/
  2. cat ./src/components/Login.tsx
  3. ls -la ./src/store/
  4. cat ./src/store/authStore.ts
  5. grep -r "useAuth" ./src/

  压缩前：5 条完整的工具调用及输出记录。

  压缩后：

  [
    {
      "role": "assistant",
      "content": "[Micro-Compacted: 4 intermediate tool calls removed to save space.]"
    },
    {
      "role": "user",
      "content": "[grep -r \"useAuth\" ./src/ 的输出结果...]"
    }
  ]

5.3 深度压缩 (Deep Compact)

这就是我们在前面详细讨论的、调用大模型生成结构化摘要的完整压缩流程。

六、实战排障与避坑指南

6.1 常见错误与解决方案

6.2 性能优化建议

1. 合理设置令牌预算

// 推荐配置（根据模型上下文窗口调整）
const AUTOCOMPACT_BUFFER_TOKENS = 13000;  // 安全缓冲
const POST_COMPACT_TOKEN_BUDGET = 50000;  // 压缩后预算
const POST_COMPACT_MAX_TOKENS_PER_FILE = 5000;  // 单文件上限

2. 避免”压缩 – 膨胀”循环

• • 压缩后不要立即重新加载所有文件
• • 只重新注入当前任务必需的文件
• • 使用 POST_COMPACT_MAX_FILES_TO_RESTORE 限制恢复数量

3. 监控压缩触发频率

// 添加压缩元数据追踪
{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",  // 或 "manual"
    "preTokens": 190000,
    "postTokens": 45000,
    "compressionRatio": 0.76
  }
}

七、完整场景复现

7.1 场景设定

你正在重构一个认证模块，涉及 5 个文件：

• • auth.ts – 核心认证逻辑
• • session.ts – 会话管理
• • jwt.ts – JWT 工具函数
• • middleware.ts – 认证中间件
• • config.ts – 认证配置

7.2 对话流程

第 1-20 轮：读取 auth.ts，分析代码结构，制定重构计划
第 21-40 轮：修改 auth.ts，修复类型错误，运行测试
第 41-60 轮：读取 session.ts 和 jwt.ts，开始重构
第 61-80 轮：修复连锁错误，更新 middleware.ts
第 81-100 轮：完成 config.ts 更新，运行集成测试

此时 Token 用量达到 195k，触发自动压缩。

7.3 压缩后状态

[
  {
    "type": "system",
    "subtype": "compact_boundary",
    "content": "Conversation compacted",
    "compactMetadata": {
      "trigger": "auto",
      "preTokens": 195000,
      "postTokens": 48000
    }
  },
  {
    "role": "user",
    "content": "Session continued. Summary: 已完成 auth.ts、jwt.ts 重构，middleware.ts 部分完成。待完成：config.ts 更新和集成测试。"
  },
  {
    "role": "user",
    "content": "[File: auth.ts - 最新内容]",
    "isAttachment":true
  },
  {
    "role": "user",
    "content": "[File: jwt.ts - 最新内容]",
    "isAttachment":true
  },
  {
    "role": "user",
    "content": "[Plan: 重构进度 80%，剩余 config.ts 和测试]",
    "isAttachment":true
  }
]

7.4 压缩后续对话

模型现在可以基于这个”精简版上下文”继续工作：

• • 知道已完成的工作（auth.ts、jwt.ts）
• • 手中有最新文件内容（无需重新读取）
• • 清楚剩余任务（config.ts 和测试）
• • Token 预算充足（48k/200k）

八、总结与核心要点

8.1 上下文经济学的三大原则

1. 1. 预算意识：将 Token 视为昂贵的运行时资源，主动管理而非被动消耗
2. 2. 分层压缩：根据危急程度选择裁剪、微压缩或深度压缩
3. 3. 状态保留：压缩不是删除，而是有选择的遗忘和关键信息重注入

8.2 核心参数速查表

8.3 实战检查清单

在实现类似压缩机制前，问自己：

• •是否设置了合理的令牌预算和缓冲？
• •是否有分层压缩策略应对不同场景？
• •压缩后是否正确重注入关键状态？
• •摘要 Prompt 是否足够结构化？
• •是否有压缩元数据用于调试和监控？
• •是否避免了”压缩 – 膨胀”循环？

8.4 最终思考

Claude Code 的压缩机制揭示了一个深刻的工程哲学：无限上下文不是靠堆硬件实现的，而是靠聪明的资源管理。

这套机制的核心价值不在于技术本身，而在于它提供了一种思维模式：将上下文视为一种需要精心管理的经济资源，通过预算、压缩、重注入三个环节，实现”有限资源下的无限可能”。

对于 AI 工程师来说，理解这套机制不仅有助于更好地使用 Claude Code，更重要的是能够将这些原则应用到自己的 Agent 系统设计中。

参考文献：

1. 1. Claude Code源码：compact.ts, snipCompact.ts, microCompact.ts
2. 2. Anthropic Claude API Documentation