Claude Code 上下文压缩策略详解目录1. [整体架构](#1-整体架构)2. [四层压缩流水线](#2-四层压缩流水线)3. [阈值参数详解](#3-阈值参数详解)4. [压缩 Prompt 完整内容](#4-压缩-prompt-完整内容)5. [消息流向图](#5-消息流向图)6. [Hooks 系统](#6-hooks-系统)7. [电路断路器机制](#7-电路断路器机制)8. [GrowthBook 配置](#8-growthbook-配置)9. [缓存策略](#9-缓存策略)---1. 整体架构flowchart TB subgraph Input[用户输入层] UserMsg[用户消息] end subgraph PreQuery[查询前处理] Snip[SnipCompactbr/快速截断] Micro[MicroCompactbr/消息分组] Collapse[Context Collapsebr/上下文折叠] end subgraph Auto[自动压缩层] Auto[AutoCompactbr/自动摘要] end subgraph API[API 调用] APICall[Claude API] end UserMsg -- Snip Snip -- Micro Micro -- Collapse Collapse -- Auto Auto -- APICall style Snip fill:#22c55e,color:#000 style Micro fill:#3b82f6,color:#fff style Auto fill:#f59e0b,color:#000 style Collapse fill:#a855f7,color:#fff**执行顺序**: SnipCompact → MicroCompact → Context Collapse → AutoCompact---2. 四层压缩流水线2.1 SnipCompact (快速截断)flowchart LR subgraph Input M1[重复消息] M2[冗长输出] M3[空消息] M4[相似合并] end subgraph Output M1[去重] M2[截断] M3[删除] M4[合并] end Input -- Output style Input fill:#1a1a2e,color:#e4e4e7 style Output fill:#1a1a2e,color:#e4e4e7**文件**:snipCompact.ts(引用但未在 sourcemap 中)**特点**:无 API 调用即时本地执行在 HISTORY_SNIP feature 开启时启用与 MicroCompact 可同时运行不互斥**作用**:移除完全重复的用户/助手消息截断超长工具输出 (100 字符保留前 100)删除空消息合并连续相似的助手消息---2.2 MicroCompact (消息分组)flowchart TB subgraph Triggers[触发条件] Time[时间衰减触发] Cache[缓存编辑触发] end subgraph TimeBased[时间衰减清理] T1[检查最后 Assistant 消息时间] T2{gap 阈值?} T3[清除旧工具结果br/保留最近 N 条] T4[标记为已清除] T1 -- T2 T2 --|是| T3 -- T4 T2 --|否| Skip1[跳过] end subgraph CachedMC[缓存编辑 MicroCompact] C1[收集可压缩工具 ID] C2[注册工具结果] C3[计算待删除列表] C4[创建 cache_edits 块] C5[API 层添加编辑] C1 -- C2 -- C3 -- C4 -- C5 end style TimeBased fill:#3b82f6,color:#fff style CachedMC fill:#3b82f6,color:#fff**文件**:microCompact.ts,apiMicrocompact.ts,cachedMicrocompact.js**两种触发模式**:#### 2.2.1 时间衰减触发 (Time-Based)当距离上次 Assistant 消息的时间超过阈值时触发:// 默认配置 (GrowthBook: tengu_slate_heron) const TIME_BASED_MC_CONFIG_DEFAULTS { enabled: false, // 默认关闭 gapThresholdMinutes: 60, // 60 分钟阈值 keepRecent: 5 // 保留最近 5 条 }**逻辑**:1. 检查最后 Assistant 消息的时间戳2. 计算当前时间与该时间戳的差值 (分钟)3. 如果差值 gapThresholdMinutes:- 保留最近keepRecent条工具结果- 其余标记为[Old tool result content cleared]- 重置缓存编辑状态#### 2.2.2 缓存编辑触发 (Cached MicroCompact)使用 Claude API 的cache_edits功能:// 可压缩的工具类型 const COMPACTABLE_TOOLS new Set([ FILE_READ_TOOL_NAME, ...SHELL_TOOL_NAMES, // Bash, PowerShell 等 GREP_TOOL_NAME, GLOB_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME, FILE_EDIT_TOOL_NAME, FILE_WRITE_TOOL_NAME, ])**GrowthBook 配置** (tengu_plum_violet):triggerThreshold: 触发阈值 (默认 5)keepRecent: 保留最近数量deletionBatchSize: 每次删除数量---2.3 AutoCompact (自动摘要)flowchart TB subgraph Trigger[触发检测] T1[Token 计数] T2{超过阈值?} T3[PreCompact Hook] end subgraph Compact[压缩执行] C1[创建摘要请求] C2[调用 Claude API] C3{PTL 错误?} C4[截断头部重试] C5[生成摘要] end subgraph Output[输出] O1[边界标记] O2[摘要消息] O3[附件] O4[PostCompact Hook] end T1 -- T2 --|是| T3 -- C1 C1 -- C2 -- C3 C3 --|是| C4 -- C1 C3 --|否| C5 C5 -- O1 -- O2 -- O3 -- O4 style Trigger fill:#f59e0b,color:#000 style Compact fill:#f59e0b,color:#000 style Output fill:#f59e0b,color:#000**文件**:autoCompact.ts,compact.ts,prompt.ts**触发阈值**:// autoCompact.ts export const AUTOCOMPACT_BUFFER_TOKENS 13_000 export const WARNING_THRESHOLD_BUFFER_TOKENS 20_000 export const ERROR_THRESHOLD_BUFFER_TOKENS 20_000 export const MANUAL_COMPACT_BUFFER_TOKENS 3_000 // 计算公式 autoCompactThreshold effectiveContextWindow - 13,000 blockingLimit effectiveContextWindow - 3,000**上下文窗口大小** (按模型):| 模型 | 上下文窗口 ||-----|----------|| Sonnet 4.6 / Opus 4.6 | 1,000,000 (1M) || 其他默认 | 200,000 |---2.4 Context Collapse (上下文折叠)flowchart TB subgraph States[状态机] S1[正常] S2[90%: Commit 模式] S3[95%: 阻塞模式] S4[上下文折叠] end S1 --|使用量 90%| S2 S2 --|使用量 95%| S3 S3 --|触发| S4 S4 --|折叠完成| S1 style S1 fill:#22c55e,color:#000 style S2 fill:#f59e0b,color:#000 style S3 fill:#ef4444,color:#fff style S4 fill:#a855f7,color:#fff**文件**:contextCollapse/index.ts**机制**:90% 上下文使用量: 开始提交 (commit) 模式95% 上下文使用量: 阻塞新 API 调用保留 commit 历史用于持久化提供可折叠视图---3. 阈值参数详解3.1 Token 阈值层级┌────────────────────────────────────────────────────────────┐ │ 上下文窗口 (200K / 1M) │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ 阻塞区 (最后 3,000 tokens) │ │ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ AutoCompact 触发区 (最后 13,000 tokens) │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ │ │ │ │ 警告区 (最后 20,000 tokens) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌───────────────────────────────────┐ │ │ │ │ │ │ │ │ │ 安全区 │ │ │ │ │ │ │ │ │ └───────────────────────────────────┘ │ │ │ │ │ │ │ └─────────────────────────────────────────┘ │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────┘3.2 阈值计算公式// 获取有效上下文窗口 effectiveContextWindow getContextWindowForModel(model) // 自动压缩阈值 autoCompactThreshold effectiveContextWindow - AUTOCOMPACT_BUFFER_TOKENS effectiveContextWindow - 13_000 // 警告阈值 warningThreshold effectiveContextWindow - WARNING_THRESHOLD_BUFFER_TOKENS effectiveContextWindow - 20_000 // 错误阈值 errorThreshold effectiveContextWindow - ERROR_THRESHOLD_BUFFER_TOKENS effectiveContextWindow - 20_000 // 阻塞限制 blockingLimit effectiveContextWindow - MANUAL_COMPACT_BUFFER_TOKENS effectiveContextWindow - 3_0003.3 各阈值使用场景| 阈值 | 值 | 用途 ||-----|---|-----||AUTOCOMPACT_BUFFER_TOKENS| 13,000 | AutoCompact 自动触发 ||WARNING_THRESHOLD_BUFFER_TOKENS| 20,000 | 显示警告 ||ERROR_THRESHOLD_BUFFER_TOKENS| 20,000 | 显示错误 ||MANUAL_COMPACT_BUFFER_TOKENS| 3,000 | 手动压缩预留空间 |3.4 环境变量覆盖# 覆盖自动压缩窗口 CLAUDE_CODE_AUTO_COMPACT_WINDOW150000 # 覆盖自动压缩百分比 (测试用) CLAUDE_AUTOCOMPACT_PCT_OVERRIDE80 # 覆盖阻塞限制 CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE180000 # 禁用所有压缩 DISABLE_COMPACTtrue # 仅禁用自动压缩 DISABLE_AUTO_COMPACTtrue---4. 压缩 Prompt 完整内容4.1 基础压缩 Prompt// prompt.ts const NO_TOOLS_PREAMBLE CRITICAL: Respond with TEXT ONLY. Do NOT call any tools. - Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool. - You already have all the context you need in the conversation above. - Tool Calls will be REJECTED and will waste your only turn — you will fail the task. - Your entire response must be plain text: an analysis block followed by a summary block. const BASE_COMPACT_PROMPT Your task is to create a detailed summary of the conversation so far, paying close attention to the users explicit requests and your previous actions. This summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context. ${DETAILED_ANALYSIS_INSTRUCTION_BASE} Your summary should include the following sections: 1. Primary Request and Intent: Capture all of the users explicit requests and intents in detail 2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed. 3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Pay special attention to the most recent messages and include full code snippets where applicable and include a summary of why this file read or edit is important. 4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently. 5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts. 6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users feedback and changing intent. 7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on. 8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request, paying special attention to the most recent messages from both user and assistant. Include file names and code snippets where applicable. 9. Optional Next Step: List the next step that you will take that is related to the most recent work you were doing. IMPORTANT: ensure that this step is DIRECTLY in line with the users most recent explicit requests, and the task you were working on immediately before this summary request. If your last task was concluded, then only list next steps if they are explicitly in line with the users request. Do not start on tangential requests or really old requests that were already completed without confirming with the user first. If there is a next step, include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off. This should be verbatim to ensure theres no drift in task interpretation.4.2 分析指令 (注入到 Prompt)const DETAILED_ANALYSIS_INSTRUCTION_BASE Before providing your final summary, wrap your analysis in analysis tags to organize your thoughts and ensure youve covered all necessary points. In your analysis process: 1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify: - The users explicit requests and intents - Your approach to addressing the users requests - Key decisions, technical concepts and code patterns - Specific details like: - file names - full code snippets - function signatures - file edits - Errors that you ran into and how you fixed them - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently. 2. Double-check for technical accuracy and completeness, addressing each required element thoroughly.4.3 摘要输出格式example analysis [Your thought process, ensuring all points are covered thoroughly and accurately] /analysis summary 1. Primary Request and Intent: [Detailed description] 2. Key Technical Concepts: - [Concept 1] - [Concept 2] - [...] 3. Files and Code Sections: - [File Name 1] - [Summary of why this file is important] - [Summary of the changes made to this file, if any] - [Important Code Snippet] - [File Name 2] - [Important Code Snippet] - [...] 4. Errors and fixes: - [Detailed description of error 1]: - [How you fixed the error] - [User feedback on the error if any] - [...] 5. Problem Solving: [Description of solved problems and ongoing troubleshooting] 6. All user messages: - [Detailed non tool use user message] - [...] 7. Pending Tasks: - [Task 1] - [Task 2] - [...] 8. Current Work: [Precise description of current work] 9. Optional Next Step: [Optional Next step to take] /summary /example4.4 摘要格式化函数export function formatCompactSummary(summary: string): string { let formattedSummary summary // 剥离 analysis 标签 - 仅用于草稿不进入最终上下文 formattedSummary formattedSummary.replace( /analysis[\s\S]*?\/analysis/, , ) // 提取并格式化 summary 标签 const summaryMatch formattedSummary.match(/summary([\s\S]*?)\/summary/) if (summaryMatch) { const content summaryMatch[1] || formattedSummary formattedSummary.replace( /summary[\s\S]*?\/summary/, Summary:\n${content.trim()}, ) } // 清理多余空白 formattedSummary formattedSummary.replace(/\n\n/g, \n\n) return formattedSummary.trim() }---5. 消息流向图5.1 完整 Query 循环sequenceDiagram participant User as 用户 participant Snip as SnipCompact participant Micro as MicroCompact participant Collapse as Context Collapse participant Auto as AutoCompact participant API as Claude API participant Hooks as Hooks User-Snip: 用户消息 Snip-Snip: 去除重复/冗余 Snip--Micro: 消息列表 Note over Micro: 微压缩可能触发br/时间衰减清理br/或缓存编辑 Micro--Collapse: 消息列表 Note over Collapse: 投影折叠视图br/可能提交更多折叠 Collapse--Auto: 消息列表 Note over Auto: 检查阈值br/可能触发摘要 Auto-Hooks: PreCompact Hook Hooks--Auto: 自定义指令 Auto-API: 摘要请求 API--Auto: 摘要响应 Auto-Hooks: PostCompact Hook Auto--API: 压缩后的消息 API--User: 最终响应5.2 AutoCompact 重试流程flowchart TB Start[开始压缩] -- API[调用 API] API -- Response{响应类型} Response --|正常文本| Success[成功] Response --|PTL 错误| PTL{PTL 重试次数br/ 3?} Response --|API 错误| Error[记录错误] PTL --|是| Truncate[截断头部br/删除最老的 API round] Truncate -- API PTL --|否| Fail[抛出错误br/PROMPT_TOO_LONG] Success -- StripImages[剥离图片] Fail -- Error StripImages -- CreateBoundary[创建边界标记] CreateBoundary -- SummaryMsg[生成摘要消息] SummaryMsg -- Attachments[生成附件] Attachments -- SessionHooks[SessionStart Hooks] SessionHooks -- PostHooks[PostCompact Hooks] PostHooks -- Result[返回 CompactionResult]---6. Hooks 系统6.1 压缩相关 Hooksflowchart LR subgraph Hooks[Hook 生命周期] Pre[PreCompact Hook] Post[PostCompact Hook] end subgraph Capabilities[能力] Cancel[可取消压缩] Modify[可修改指令] Notify[可通知用户] end Pre --|触发| Cancel Pre --|触发| Modify Post --|触发| Notify style Pre fill:#f59e0b,color:#000 style Post fill:#f59e0b,color:#0006.2 Hook 接口// PreCompact Hook interface PreCompactHookParams { trigger: auto | manual customInstructions: string | null } interface PreCompactHookResult { newCustomInstructions?: string // 追加到压缩指令 userDisplayMessage?: string // 显示给用户的消息 // 返回 true 或抛出错误以取消压缩 } // PostCompact Hook interface PostCompactHookParams { trigger: auto | manual compactSummary: string } interface PostCompactHookResult { userDisplayMessage?: string }---7. 电路断路器机制flowchart TB subgraph Circuit[电路断路器] A{连续失败br/ 3?} A --|否| Continue[继续尝试] A --|是| Trip[断路器触发] Trip -- Disabled[禁用 AutoCompact] Disabled -- Stop[停止自动压缩] end subgraph Tracking[追踪状态] T1[记录失败次数] T2[重置成功时] end A -- T1 T1 -- A Continue -- T2 T2 -- Reset[重置计数器] style Trip fill:#ef4444,color:#fff style Disabled fill:#ef4444,color:#fff// autoCompact.ts const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES 3 // 断路器逻辑 if (tracking?.consecutiveFailures MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES) { return { wasCompacted: false } } // 失败时增量 const nextFailures prevFailures 1 // 成功时重置 consecutiveFailures: 0---8. GrowthBook 配置8.1 特性开关| Feature | 默认值 | 用途 ||---------|-------|-----||HISTORY_SNIP| false | 启用 SnipCompact ||CONTEXT_COLLAPSE| false | 启用 Context Collapse ||REACTIVE_COMPACT| false | 启用响应式压缩 ||CACHED_MICROCOMPACT| true | 启用缓存编辑 ||PROMPT_CACHE_BREAK_DETECTION| false | 检测缓存中断 |8.2 GrowthBook Keys| Key | 类型 | 默认值 | 说明 ||-----|------|-------|-----||tengu_slate_heron| TimeBasedMCConfig | 见下方 | 时间衰减配置 ||tengu_plum_violet| CachedMCConfig | - | 缓存编辑配置 ||tengu_compact_cache_prefix| boolean | true | 压缩时共享缓存 |// TimeBasedMCConfig 默认值 const TIME_BASED_MC_CONFIG_DEFAULTS { enabled: false, gapThresholdMinutes: 60, // 60 分钟后清理 keepRecent: 5 // 保留最近 5 条 }---9. 缓存策略9.1 缓存编辑 (cache_edits)sequenceDiagram participant MC as MicroCompact participant API as Claude API participant Cache as 缓存系统 MC-MC: 注册工具结果 MC-MC: 计算待删除列表 MC-API: 发送 cache_edits 块 API-Cache: 应用缓存编辑 Cache--API: 编辑确认 API--MC: 响应 (含 cache_deleted_input_tokens) MC--MC: 记录基准值9.2 缓存中断检测// PROMPT_CACHE_BREAK_DETECTION 特性 if (feature(PROMPT_CACHE_BREAK_DETECTION)) { // 压缩后重置基准 notifyCompaction(querySource, agentId) // 缓存删除后通知 notifyCacheDeletion(querySource) }---10. 关键文件索引| 文件 | 功能 ||-----|-----||services/compact/compact.ts| 核心压缩逻辑 ||services/compact/autoCompact.ts| 自动压缩触发 ||services/compact/microCompact.ts| 微压缩 ||services/compact/prompt.ts| 压缩 Prompt 模板 ||services/compact/timeBasedMCConfig.ts| 时间衰减配置 ||services/compact/cachedMicrocompact.js| 缓存编辑 ||utils/context.ts| 上下文窗口计算 ||query.ts| Query 循环集成 ||query/deps.ts| 依赖注入 |