Claude_code上下文压缩（Compaction）机制

本文深度解析 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 自动压缩决策树入口shouldAutoCompact(messages, model, querySource)—src/services/compact/autoCompact.tsEntry: shouldAutoCompact(messages, model, querySource)↓递归保护检查├─ querySource ‘session_memory’ → FALSE防止循环├─ querySource ‘compact’ → FALSE防止循环└─ 否则 → 继续↓启用标志检查├─ DISABLE_COMPACTtrue → FALSE├─ DISABLE_AUTO_COMPACTtrue → FALSE├─ config.autoCompactEnabled false → FALSE└─ 否则 → 继续↓竞争性上下文管理检查├─ feature(‘REACTIVE_COMPACT’) → FALSE仅反应式├─ feature(‘CONTEXT_COLLAPSE’) → FALSEcollapse 优先└─ 否则 → 继续↓Token 阈值检查├─ 计算: threshold effectiveWindow - 13K buffer├─ tokens threshold → TRUE需要压缩└─ tokens threshold → FALSE不需要1.2 Token 预算层级5 级层级说明Sonnet 3.5Haiku 3TIER 1模型原始上下文窗口200,000128,000TIER 2有效窗口预留 20K 输出180,000108,000TIER 3自动压缩阈值-13K 缓冲167,00095,000TIER 4警告阈值黄灯147,00075,000TIER 5错误阈值/阻塞限制红区127,00055,000四层压缩策略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。内置 PTLPrompt Too Long重试循环for (attempt 1; attempt 3; attempt) {summary await streamCompactSummary({messages})if (PROMPT_TOO_LONG) {// 按 API-round 组删除最旧的消息组 // 重试} else {break}}四层策略性能对比指标基于时间 MC缓存 MC会话记忆完整压缩Token 节省10-30% tools5-15% tools40-60% 上下文60-80% 上下文延迟1ms10-50ms100-500ms3-10s缓存影响冷无收益热100-200 tokens5-10K 创建30-50K 创建失败率0%~1%5-15%0.1%API 调用0001工程亮点会话稳定锁存器缓存键 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仍然作为附件保留确保模型压缩后仍能看到完整指令。错误恢复路径3 级Stage 1: Context-Collapse 排空└─ 排出暂存队列用更小的上下文重试↓ 失败Stage 2: 反应式压缩Anthropic 内部└─ 413/媒体错误时触发异步压缩后重试↓ 失败Stage 3: 显示错误└─ 提示用户手动 /compact关键文件索引文件职责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%免费】