mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 21:05:51 +00:00
b01cd1371f
移除全部 TypeScript 类型定义、源码路径和实现常量， 聚焦三层递进策略的设计哲学、保留窗口的三约束平衡、 工具对完整性保证和压缩后重新注入的设计洞察。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
132 lines
6.5 KiB
Plaintext
132 lines
6.5 KiB
Plaintext
---
|
||
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 窗口的动态计算和阈值管理
|
||
- **系统提示词** — 理解上下文组装的缓存优化策略
|