claude-code/docs/context/compaction.mdx

---
title: "上下文压缩"
description: "对话太长怎么办——优雅地'遗忘'不重要的信息"
---

{/* 本章目标：解释 Compaction 机制的设计和策略 */}

## 为什么需要压缩

每次 API 调用的 token 有上限（通常 200K）。一场长时间的编程对话可能产生：

- 大量的文件内容（AI 读了几十个文件）
- 长篇的命令输出（构建日志、测试结果）
- 往返的对话历史

不压缩的话，很快就会撞到 token 上限，对话被迫终止。

<Frame caption="上下文压缩前后对比">
  <img src="/docs/images/compaction.png" alt="上下文压缩示意图" />
</Frame>

## 压缩的策略

Claude Code 提供了多层压缩机制：

<AccordionGroup>
  <Accordion title="自动压缩">
    当 token 接近上限时，系统自动触发压缩。AI 生成一份当前对话的**摘要**，替换掉早期的详细消息。效果就像人类的"记忆"——记住要点，忘记细节。
  </Accordion>
  <Accordion title="手动压缩">
    用户可以随时通过 `/compact` 命令主动触发压缩。可以附带提示语（如 `/compact 聚焦在认证模块的修改上`），引导 AI 保留特定信息。
  </Accordion>
  <Accordion title="Micro Compact">
    更细粒度的局部压缩——不是压缩整个对话，而是压缩某些特别长的工具输出（比如一个 5000 行的测试日志）。
  </Accordion>
</AccordionGroup>

## 压缩边界

压缩后，系统在消息历史中插入一个"边界标记"。后续的 API 调用只发送边界之后的消息：

```
[早期的 50 条消息] ← 被压缩
[压缩摘要边界] ← 一段浓缩的摘要
[后续的 10 条消息] ← 正常发送
```

这个设计保证了：
- 压缩后的摘要为 AI 提供了历史上下文
- 新的对话不受旧消息的 token 负担
- 用户无感知——对话继续自然进行

## 压缩前后的 Hooks

压缩是一个可能丢失信息的操作，因此系统允许用户在压缩前后执行自定义脚本：

- **Pre-compact Hook**：压缩前执行，可以标记"这些信息不能丢"
- **Post-compact Hook**：压缩后执行，可以验证关键信息是否保留

## 什么信息会被保留

压缩不是简单的截断，AI 会智能地决定保留什么：

- 用户的核心需求和目标
- 重要的决策和原因
- 当前工作的状态（改了哪些文件、做到哪一步）
- 之前犯过的错误（避免重蹈覆辙）