本文深度解析 Claude Code 的上下文压缩机制，旨在解决超长对话中的连贯性问题。文章揭示了其多层压缩系统，包含 4 层压缩策略（基于时间、缓存编辑、会话记忆、完整压缩），以及 5 级 token 预算层级。此外，还详细阐述了会话稳定状态管理、工具配对不变量保持和多级错误恢复路径等关键设计，为开发基于大模型的 agent 系统提供了宝贵的参考。

---

本文基于 Claude Code 源码深度分析，揭秘其上下文压缩（Compaction）的完整实现原理。如果你曾好奇"为什么 Claude Code 能在超长对话中依然保持上下文连贯"，这篇文章会给你答案。

---

上下文压缩（Compaction）机制 — 完整解析

概述

Claude Code 实现了一个多层上下文压缩系统，用于在模型上下文窗口限制内优雅地处理无限长度的对话。系统核心包括：

• 4 层压缩策略，各有不同的成本/效果权衡

• 会话稳定的状态管理，防止缓存键在会话中间失效

• 工具配对不变量保持，确保 API 合约在截断时不被破坏

• 多级错误恢复路径，含回退链

• 5 级 token 预算层级，协调不同优化阶段

关键数字：

• 4 层压缩策略（基于时间、缓存编辑、会话记忆、完整压缩）

• 5 个 token 阈值

• 最多 3 次连续失败后熔断

• 60 分钟空隙触发（服务器缓存 TTL）

• 13,000 token 安全缓冲

• 压缩后清理 40+ 种缓存

• 完整压缩失败率约 0.1%

---

系统架构（6 层）

┌──────────────────────────────────────────────────────────────┐

│ Layer 1: 触发检测 │

│ • 评估当前 token 使用量 vs 阈值 │

│ • 选择压缩策略（基于时间、缓存、会话记忆、完整） │

│ • 与特性门控协调（collapse、reactive） │

└──────────────────────────────────────────────────────────────┘

                        ↓

┌──────────────────────────────────────────────────────────────┐

│ Layer 2: 策略实现 │

│ • 基于时间 MC：字符串替换旧 tool results │

│ • 缓存 MC：排队 cache_edits 到 API 层 │

│ • 会话记忆：使用已提取的摘要替代 API 调用 │

│ • 完整压缩：调用 Claude 生成摘要 │

└──────────────────────────────────────────────────────────────┘

                        ↓

┌──────────────────────────────────────────────────────────────┐

│ Layer 3: 状态管理 │

│ • 会话稳定锁存器（缓存头、thinking 清除） │

│ • 微压缩状态（工具追踪、缓存编辑） │

│ • 会话记忆提取状态（边界、时间戳） │

│ • 压缩后清理（主线程 vs 子 agent 作用域） │

└──────────────────────────────────────────────────────────────┘

                        ↓

┌──────────────────────────────────────────────────────────────┐

│ Layer 4: 缓存一致性 │

│ • 通知缓存中断检测器预期的变化 │

│ • 跨请求维持稳定的缓存键 │

│ • 追踪上次缓存读取 token 数作为基线 │

└──────────────────────────────────────────────────────────────┘

                        ↓

┌──────────────────────────────────────────────────────────────┐

│ Layer 5: API 集成 │

│ • 注入 context_management 头（缓存编辑） │

│ • 在原始位置包含 cache_edits │

│ • 追踪响应中的 cache_deleted_input_tokens │

└──────────────────────────────────────────────────────────────┘

                        ↓

┌──────────────────────────────────────────────────────────────┐

│ Layer 6: 压缩后清理 │

│ • 清除会话状态（微压缩状态、系统提示） │

│ • 仅主线程：清除 context collapse、memory cache │

│ • 有意不清理：skill 名称（避免 cache_creation 开销） │

└──────────────────────────────────────────────────────────────┘

---

1. 触发条件：何时触发压缩

---

1.1 自动压缩决策树

入口：shouldAutoCompact(messages, model, querySource) — src/services/compact/autoCompact.ts

Entry: shouldAutoCompact(messages, model, querySource)

↓

1. 递归保护检查

   ├─ querySource === ‘session_memory’ → FALSE（防止循环）

   ├─ querySource === ‘compact’ → FALSE（防止循环）

   └─ 否则 → 继续

↓

2. 启用标志检查

   ├─ DISABLE_COMPACT=true → FALSE

   ├─ DISABLE_AUTO_COMPACT=true → FALSE

   ├─ config.autoCompactEnabled === false → FALSE

   └─ 否则 → 继续

↓

3. 竞争性上下文管理检查

   ├─ feature(‘REACTIVE_COMPACT’) → FALSE（仅反应式）

   ├─ feature(‘CONTEXT_COLLAPSE’) → FALSE（collapse 优先）

   └─ 否则 → 继续

↓

4. Token 阈值检查

   ├─ 计算: threshold = effectiveWindow - 13K buffer

   ├─ tokens >= threshold → TRUE（需要压缩）

   └─ tokens < threshold → FALSE（不需要）

1.2 Token 预算层级（5 级）

层级	说明	Sonnet 3.5	Haiku 3
TIER 1	模型原始上下文窗口	200,000	128,000
TIER 2	有效窗口（预留 20K 输出）	180,000	108,000
TIER 3	自动压缩阈值（-13K 缓冲）	167,000	95,000
TIER 4	警告阈值（黄灯）	147,000	75,000
TIER 5	错误阈值/阻塞限制（红区）	127,000	55,000

---

2. 四层压缩策略

---

Layer 1：基于时间的微压缩（缓存冷）

触发条件：距上次助手消息 > 60 分钟（服务器缓存 TTL 过期）

策略很简单粗暴——把旧的 tool results 替换为占位符 "[Old tool result content cleared]"，只保留最近的 5 个。整个过程无需任何 API 请求，延迟 < 1ms。

Layer 2：缓存微压缩（缓存热）

触发条件：Tool result 数量超过阈值，且缓存仍然有效

这一层更精妙：不直接修改本地消息，而是通过 cache_edits 告诉 API"请删掉这几个 tool results"，从而在 不使缓存前缀失效 的情况下完成压缩。延迟仅 10-50ms。

{

“context_management”: {

"type": "auto",

"cache\_control": { "type": "ephemeral" },

"cache\_edits": [

  { "type": "delete", "index": 5 },

  { "type": "delete", "index": 8 }

]

}

}

Layer 3：会话记忆压缩（实验性）

触发条件：会话记忆中存在已提取的对话摘要

无需调用模型 API——直接读取磁盘上已有的会话摘要替换历史消息。压缩效果 40-60%，延迟 100-500ms。

关键步骤包括：

• 轮询等待会话记忆提取完成（最多 15s）

• 计算保留消息的起始索引

• 调整工具配对不变量，确保 tool_use/tool_result 对完整

Layer 4：完整压缩（兜底）

触发条件：Token 超过阈值且前三层都无法处理

这是最重量级的方案：直接调用 Claude API，让模型对整个对话历史生成一份摘要，然后用 摘要 + 关键附件 + 最近消息 重建对话。压缩效果高达 60-80%，但需要 3-10s。

内置 PTL（Prompt Too Long）重试循环：

for (attempt = 1; attempt <= 3; attempt++) {

summary = await streamCompactSummary({messages})

if (PROMPT_TOO_LONG) {

// 按 API-round 组删除最旧的消息组

// 重试

} else {

break

}

}

---

3. 四层策略性能对比

---

指标	基于时间 MC	缓存 MC	会话记忆	完整压缩
Token 节省	10-30% tools	5-15% tools	40-60% 上下文	60-80% 上下文
延迟	<1ms	10-50ms	100-500ms	3-10s
缓存影响	冷（无收益）	热（100-200 tokens）	5-10K 创建	30-50K 创建
失败率	0%	~1%	5-15%	0.1%
API 调用	0	0	0	1

---

4. 工程亮点

---

会话稳定锁存器

缓存键 = hash(系统提示 + 消息 + 请求参数)。如果中途改变 context_management 头的存在与否，缓存键会翻转，之前的缓存全部失效。

解决方案：首次请求时决定配置并锁存，后续请求无条件复用锁存值，直到会话结束。

cacheEditingHeaderLatched: null | boolean

// null → 首次请求，计算并写入锁存

// true/false → 复用，忽略运行时配置变化

工具配对不变量

API 要求每个 tool_use 必须在 tool_result 之前存在。截断消息时若不注意，很容易把 tool_use 切掉但留下孤立的 tool_result，导致 API 报错。

Claude Code 用 adjustIndexToPreserveAPIInvariants() 专门处理这个问题：向前扩展 startIndex 直到所有 tool 配对完整。

有意不清理 skill 名称

压缩后清理代码中有一行显眼的注释：

// sentSkillNames 不清理 — 原因: 重新注入 skill_listing (~4K tokens) 纯属 cache_creation 浪费

这是个精心的权衡：已发送的 skill 列表不重新注入，但具体调用过的 skill 内容（invoked_skills）仍然作为附件保留，确保模型压缩后仍能看到完整指令。

---

5. 错误恢复路径（3 级）

---

Stage 1: Context-Collapse 排空

└─ 排出暂存队列，用更小的上下文重试

  ↓ 失败

Stage 2: 反应式压缩（Anthropic 内部）

└─ 413/媒体错误时触发，异步压缩后重试

  ↓ 失败

Stage 3: 显示错误

└─ 提示用户手动 /compact

---

6. 关键文件索引

---

文件	职责
src/services/compact/autoCompact.ts	自动压缩触发逻辑、阈值计算
src/services/compact/compact.ts	完整压缩实现、PTL 重试
src/services/compact/sessionMemoryCompact.ts	会话记忆压缩
src/services/compact/microCompact.ts	基于时间/缓存微压缩
src/services/compact/postCompactCleanup.ts	压缩后清理策略
src/services/query.ts	查询状态机、错误恢复路径

---

最后

对于正在迷茫择业、想转行提升，或是刚入门的程序员、编程小白来说，有一个问题几乎人人都在问：未来10年，什么领域的职业发展潜力最大？

答案只有一个：人工智能（尤其是大模型方向）

当下，人工智能行业正处于爆发式增长期，其中大模型相关岗位更是供不应求，薪资待遇直接拉满——字节跳动作为AI领域的头部玩家，给硕士毕业的优质AI人才（含大模型相关方向）开出的月基础工资高达5万—6万元；即便是非“人才计划”的普通应聘者，月基础工资也能稳定在4万元左右。

再看阿里、腾讯两大互联网大厂，非“人才计划”的AI相关岗位应聘者，月基础工资也约有3万元，远超其他行业同资历岗位的薪资水平，对于程序员、小白来说，无疑是绝佳的转型和提升赛道。

如果你还不知道从何开始，我自己整理一套全网最全最细的大模型零基础教程，我也是一路自学走过来的，很清楚小白前期学习的痛楚，你要是没有方向还没有好的资源，根本学不到东西！

下面是我整理的大模型学习资源，希望能帮到你。

👇👇扫码免费领取全部内容👇👇

最后

1、大模型学习路线

2、从0到进阶大模型学习视频教程

从入门到进阶这里都有，跟着老师学习事半功倍。

3、 入门必看大模型学习书籍&文档.pdf（书面上的技术书籍确实太多了，这些是我精选出来的，还有很多不在图里）

4、 AI大模型最新行业报告

2026最新行业报告，针对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

5、面试试题/经验

【大厂 AI 岗位面经分享（107 道）】

【AI 大模型面试真题（102 道）】

【LLMs 面试真题（97 道）】

6、大模型项目实战&配套源码

适用人群

四阶段学习规划（共90天，可落地执行）

第一阶段（10天）：初阶应用

该阶段让大家对大模型 AI有一个最前沿的认识，对大模型 AI 的理解超过 95% 的人，可以在相关讨论时发表高级、不跟风、又接地气的见解，别人只会和 AI 聊天，而你能调教 AI，并能用代码将大模型和业务衔接。

• 大模型 AI 能干什么？
• 大模型是怎样获得「智能」的？
• 用好 AI 的核心心法
• 大模型应用业务架构
• 大模型应用技术架构
• 代码示例：向 GPT-3.5 灌入新知识
• 提示工程的意义和核心思想
• Prompt 典型构成
• 指令调优方法论
• 思维链和思维树
• Prompt 攻击和防范
• …

第二阶段（30天）：高阶应用

该阶段我们正式进入大模型 AI 进阶实战学习，学会构造私有知识库，扩展 AI 的能力。快速开发一个完整的基于 agent 对话机器人。掌握功能最强的大模型开发框架，抓住最新的技术进展，适合 Python 和 JavaScript 程序员。

• 为什么要做 RAG
• 搭建一个简单的 ChatPDF
• 检索的基础概念
• 什么是向量表示（Embeddings）
• 向量数据库与向量检索
• 基于向量检索的 RAG
• 搭建 RAG 系统的扩展知识
• 混合检索与 RAG-Fusion 简介
• 向量模型本地部署
• …

第三阶段（30天）：模型训练

恭喜你，如果学到这里，你基本可以找到一份大模型 AI相关的工作，自己也能训练 GPT 了！通过微调，训练自己的垂直大模型，能独立训练开源多模态大模型，掌握更多技术方案。

到此为止，大概2个月的时间。你已经成为了一名“AI小子”。那么你还想往下探索吗？

• 为什么要做 RAG
• 什么是模型
• 什么是模型训练
• 求解器 & 损失函数简介
• 小实验2：手写一个简单的神经网络并训练它
• 什么是训练/预训练/微调/轻量化微调
• Transformer结构简介
• 轻量化微调
• 实验数据集的构建
• …

第四阶段（20天）：商业闭环

对全球大模型从性能、吞吐量、成本等方面有一定的认知，可以在云端和本地等多种环境下部署大模型，找到适合自己的项目/创业方向，做一名被 AI 武装的产品经理。

• 硬件选型

• 带你了解全球大模型

• 使用国产大模型服务

• 搭建 OpenAI 代理

• 热身：基于阿里云 PAI 部署 Stable Diffusion

• 在本地计算机运行大模型

• 大模型的私有化部署

• 基于 vLLM 部署大模型

• 案例：如何优雅地在阿里云私有部署开源大模型

• 部署一套开源 LLM 项目

• 内容安全

• 互联网信息服务算法备案

• …

  👇👇扫码免费领取全部内容👇👇

  

3、这些资料真的有用吗？

这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理，现任上海殷泊信息科技CEO，其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证，服务航天科工、国家电网等1000+企业，以第一作者在IEEE Transactions发表论文50+篇，获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的技术人员，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】