不过，

上个月写了一篇关于 Claude Code 上下文管理的文章。评论区有人问：“压缩具体是怎么压的？压完之后它怎么还记得我刚才让它干什么？”这问题直击使用者痛点：

• 上下文过长导致模型忘记早期指令。
• Token 消耗剧增，导致费用暴涨。
• API 返回 “prompt_too_long” 错误，流程被打断。不过，

为了解决这些痛点。我花了两天彻底阅读 Claude Code 的 compact 目录源码，并把每个关键细节拆解出来。下面把源码里扒出的每一步都摊开来讲，帮助你在实际编码中避免上述痛点。

为什么需要压缩

Claude Code 默认为 200K token。按理说已足够，但在真实编码场景里上下文增长速度远超预期。老实说，举例这方面，

• 读 Spring Boot 项目文件占用约 X token。
• @Secured 注解搜索占 Y token。
• 测试日志占 Z token。
• 程序提示词、CLAUDE.md、Memory 文件等固定开销累计到 %。

当上下文接近窗口极限时会出现 Context Rot：模型注意力分散，早期指令被遗忘或混淆。比如一次改接口返回格式后跑测试失败，却又把之前改好的格式恢复成原样——因为早期指令被覆盖。

压缩不是可选，而是保证长会话持续可用的主要机制。通过在合适时机将历史浓缩成精华，让模型轻装上阵。

四阶段管线总览

Claude Code 的压缩机制是一个四阶段管线，每一阶段触发条件和处理方式不同。从最温和到最激进依次排列：

1. MicroCompaction: 静默预处理，无 LLM 调用，仅裁剪工具返回结果。
2. AutoCompaction: 自动触发 LLM 摘要，将整段对话替换为结构化摘要。
3. Blocking Limit: 上下文接近极限时直接拒绝请求，防止 API 超时错误。
4. Reactive Fallback: 当收到 prompt_too_long 错误后执行最激进的压缩——逐条删除最老消息。

MicroCompaction——最轻量第一刀

MicroCompaction 在每次 API 调用前运行。不调用 LLM，只裁剪工具返回结果，例如文件读取、grep 搜索等长输出。 它通过白名单识别可压缩工具，并将旧 tool_result 内容替换为占位文本 “”。这样既保留最近使用的数据，又清理不再需要的信息。减少上下文空间而不会影响语义完整性。

此步骤零成本、零 API 调用。仅规则处理，速度极快，对话体验几乎不可感知，但长期累积能显著节省 token 空间。

AutoCompaction——LLM 驱动的结构化摘要

触发阈值计算：

const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000;const AUTOCOMPACT_BUFFER_TOKENS = 13_000;function getEffectiveContextWindowSize {
const reservedTokensForSummary = Math.min,MAX_OUTPUT_TOKENS_FOR_SUMMARY);return getContextWindowForModel - reservedTokensForSummary - AUTOCOMPACT_BUFFER_TOKENS;按理说，}

当对话消耗超过 ~167K token 时自动触发。阈值可通过环境变量覆盖，例如 CLEAUD_CODE_AUTO_COMPACT_WINDOW.

压缩流程：

1. Circuit Breaker 检查连续失败次数；若超过阈值则停止尝试，
2. Circuit Breaker 成功后执行 Pre-Compact Hooks。
3. 调用独立 forked agent生成结构化摘要。
4. `formatCompactSummary` 去除 `` 草稿块，只保留 `
   ` 输出。
5. 用摘要替换原始历史；执行 Post-Compact Cleanup 重置状态并同步缓存；
6. `Post-Compact Hooks` 和文件自动重读完成恢复工作上下文。

两条压缩方法示例：

Session Memory Compact : 若开启 Session Memory。可直接使用增量笔记作为摘要，无需完整通读全对话，加速高效处理；Full Conversation Summarization : 将整段对话交给 LLM 通读一次生成完整结构化摘要。占用更多 token 与时间，但兼容所有场景。

Compaction Prompt——压缩灵魂之光

The Prompt is heart of compression logic. It begins with a stern prohibition on tool calls:

const NOTOOLSPREAMBLE = CRITICAL: Respond with TEXT ONLY...
You already have all context you need...;怎么说呢，const NOTOOLSTRAILER = 
REMINDER: Do NOT call any tools...;按理说，

This ensures forked agent cannot waste its single turn on a tool call,which would orwise lead to failure—especially on Sonnet variants where self‑thinking can trigger unnecessary calls.

The Prompt demands two XML blocks:

– internal reasoning that will be stripped later..
– final structured summary containing nine fixed sections: Primary Request and Intent,Key Technical Concepts,Files and Code Sections,Errors and Fixes,Problem Solving,All User Messages,Pending Tasks,Current Work。Optional Next Step.
.

*The “All User Messages” section preserves every raw user instruction,ensuring that shifts in intent are never lost during compression.. *“Optional Next Step” keeps verbatim quotes so task explanations do not drift after compression.. *Partial Compact compresses only new messages after an existing summary,reducing input size and speeding up processing.

断路器与阻塞限制

阻塞限制 – 提前拒绝请求以防超时错误 export const MANUAL_COMPACT_BUFFER_TOKENS = 3000 当上下文使用量达到 `有效窗口 - buffer`时直接拒绝发送 API 请求，而不是等待 `prompt_too_long` 错误回传，从而避免一次无效调用。