---
title: "上下文压缩"
description: "对话历史不断增长，token 窗口有限。理解 Claude Code 的三层压缩策略、边界标记机制和紧急降级路径。"
keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩"]
---

## 核心问题

AI 没有真正的长期记忆——它只能看到当前 API 请求中的内容。随着对话增长，token 消耗持续上升，最终会触及模型的上下文窗口限制。

压缩就是在"保留足够的语义信息"和"减少 token 占用"之间找平衡。

## 三层递进策略

系统不是用一种方法解决所有压缩需求，而是根据严重程度递进使用三种策略：

| 层级 | 触发条件 | 是否需要 API 调用 | 成本 |
|------|----------|:---:|------|
| **微压缩** | 单个工具输出过长 | 否 | 几乎为零 |
| **Session Memory 压缩** | 自动压缩触发时优先尝试 | 否 | 低（使用已提取的记忆） |
| **AI 摘要压缩** | 上述方法不可用或用户手动触发 | 是 | 高（需要额外 API 调用） |

### 设计哲学：从廉价到昂贵

为什么不直接用 AI 摘要？因为 AI 摘要需要额外的 API 调用——既花钱又花时间。系统的策略是**先用确定性操作（廉价），不行再用 AI 生成（昂贵）**。

这种分层设计意味着大部分情况下，系统可以在用户无感知的情况下释放足够的 token。

## 第一层：微压缩（Micro-Compact）

微压缩不生成摘要，只是清除旧的工具调用结果。

### 工作原理

AI 在工作过程中会产生大量工具输出：文件内容、命令结果、搜索匹配等。这些信息在产生时很重要，但随着对话推进，它们的价值迅速降低。

微压缩识别这些"过期"的工具输出，将其替换为简短的占位符文本。原始内容仍保留在磁盘上的 transcript 文件中，只是不再发送给 API。

### 时间衰减

越旧的工具输出越容易被清除，最近操作的优先保留。这个策略基于一个经验观察：AI 通常只需要最近几步操作的上下文，更早的工具结果很少被再次引用。

### 图片和文档的特殊处理

图片和 PDF 文档的 token 占用远高于文本。微压缩会将大型图片和文档替换为文本标记（如 `[image]`），在保留"这里曾有一张图片"的语义的同时释放大量 token。

## 第二层：Session Memory 压缩

当微压缩释放的 token 不够时，系统优先尝试 Session Memory 压缩。

### 设计思路

系统在对话过程中会持续提取关键信息形成"Session Memory"。压缩时，直接使用这些已提取的记忆作为对话摘要，而不需要额外调用 AI 生成摘要。

### 保留窗口

压缩后保留的消息需要满足三个约束：

- **最小深度**：至少保留 10K token 的最近对话（确保 AI 有足够的上下文）
- **最小连续性**：至少保留 5 条包含文本的消息（确保对话连贯）
- **最大上限**：不超过 40K token（避免保留太多又很快触发下一次压缩）

这三个约束形成了"不要压缩太少（AI 会迷失），也不要保留太多（很快又需要压缩）"的平衡。

### 工具对完整性

这是一个关键的**正确性保证**：API 要求每个工具调用都有对应的工具结果，反之亦然。如果压缩恰好切在一个工具调用和它的结果之间，API 会报错。

系统在计算压缩边界时，会自动向前或向后调整切分点，确保所有工具调用-结果对要么完整保留，要么一起被压缩。

## 第三层：AI 摘要压缩

当上述方法都不可用时（或用户手动触发 `/compact` 时），系统调用 AI 生成对话摘要。

### 压缩前处理

发送给摘要 AI 的消息会经过预处理：
- 图片被替换为文本标记（防止摘要请求本身也超出 token 限制）
- 会被重新注入的附件被剥离（避免重复）

### 压缩后的重新注入

压缩不是"砍掉旧对话就完了"。AI 在压缩后立即需要知道"现在正在做什么"。系统会在摘要后重新注入关键上下文：

| 重新注入内容 | 预算 | 设计理由 |
|-------------|------|----------|
| 最近读取的文件（最多 5 个） | 每文件 5K token | AI 最可能需要的就是刚操作过的文件 |
| 已激活的技能指令 | 每技能 5K，总计 25K | 保持 AI 的能力集不变 |
| CLAUDE.md 内容 | 不限 | 用户的项目指令必须始终存在 |
| MCP 工具发现结果 | 不限 | 保持工具可用性 |

**设计洞察**：总共 50K token 的重新注入预算看起来是浪费——刚压缩释放的 token 立刻又被用掉了一部分。但这是必要的：没有这些重新注入，AI 在压缩后会"忘记"当前任务状态，导致糟糕的用户体验。

## 边界标记：压缩的"墓碑"

每次压缩后，系统在消息流中插入一条边界标记消息。这条消息不展示给用户，但记录了：
- 压缩类型（自动/手动/微压缩）
- 压缩前的 token 数
- 哪些消息被保留

后续所有操作只处理最后一条边界标记之后的消息。这防止了"重复压缩已经压缩过的内容"——每次压缩都是相对于上一次边界的新压缩。

### 微压缩 vs 全量压缩的边界区别

微压缩的边界标记更轻量——它只记录哪些工具结果被清除了，不生成摘要。原始消息仍然存在（只是内容被替换为占位符），而非被摘要替代。

## 紧急降级：Prompt Too Long

当压缩后仍然超出 token 限制时，系统进入紧急路径：

1. **更激进的压缩**：尝试比正常压缩更激进的策略
2. **直接截断**：从最早的对话开始删除，直到能塞进上下文窗口
3. **放弃并报错**：如果以上都失败，向用户报告错误

**设计哲学**：系统宁可丢失部分对话历史，也不让整个会话卡死。用户可以通过文件快照和 transcript 记录恢复丢失的信息。

## Hook 机制

压缩前后支持自定义 Hook：

- **Pre-compact Hook**：压缩前执行，可以标记"必须保留"的内容
- **Post-compact Hook**：压缩后执行，可以验证关键信息是否被保留
- **Session Start Hook**：压缩后恢复 CLAUDE.md 等上下文

这确保了用户的自定义逻辑在压缩过程中被尊重——例如，用户可以通过 Hook 确保某个关键文件的内容永远不会被压缩掉。

## 接下来

- **项目记忆** — 理解跨会话的记忆持久化设计
- **令牌预算** — 了解 token 窗口的动态计算和阈值管理
- **系统提示词** — 理解上下文组装的缓存优化策略
