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[SnipCompact<br/>快速截断]
        Micro[MicroCompact<br/>消息分组]
        Collapse[Context Collapse<br/>上下文折叠]
    end

    subgraph Auto["自动压缩层"]
        Auto[AutoCompact<br/>自动摘要]
    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_000
    3.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_WINDOW=150000

# 覆盖自动压缩百分比 (测试用)
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80

# 覆盖阻塞限制
CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE=180000

# 禁用所有压缩
DISABLE_COMPACT=true

# 仅禁用自动压缩
DISABLE_AUTO_COMPACT=true

    ---

    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 user's 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 user's 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 user's 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 there's 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 you've covered all necessary points. In your analysis process:

1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:
   - The user's explicit requests and intents
   - Your approach to addressing the user's 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>
</example>
    4.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 压缩相关 Hooks
    flowchart 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:#000
    6.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 | 依赖注入 |

# AI # 开发工具
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

GPT-5.6突然发布！Fable5痛失最强基模王座

avatar DeepSeek技术社区
cover

打造自动生长的知识库：用 Obsidian + Claude Code 构建 AI 第二大脑

avatar DeepSeek技术社区

面试总说不出亮点？双非应届生秋招求职，请提前准备一个企业级AI应用案例

每年秋招季，AI 应用能力都是运营、产品、数据分析等岗位的常见考察维度。不少应届生会在简历中标注 “熟练使用 ChatGPT 等大模型工具”，但在面试中被问及具体应用场景时，往往只能描述润色文案、总结报告等浅层操作，难以形成差异化的竞争亮点。在企业数字化转型持续深化的背景下，单纯的工具操作能力正逐渐成为通用职业素养，真正具备竞争力的，是结合业务场景拆解问题、搭建 AI 工作流的系统化能力。本文将分

avatar DeepSeek技术社区