From b01cd1371f123e31978a4c4ba5d4d91a1cc7f61b Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Mon, 20 Apr 2026 09:11:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E4=B8=8A=E4=B8=8B?= =?UTF-8?q?=E6=96=87=E5=8E=8B=E7=BC=A9=EF=BC=8C=E4=BB=8E=E6=BA=90=E7=A0=81?= =?UTF-8?q?=E8=B5=B0=E8=AF=BB=E6=94=B9=E4=B8=BA=E5=8E=8B=E7=BC=A9=E7=AD=96?= =?UTF-8?q?=E7=95=A5=E8=AE=BE=E8=AE=A1=E5=88=86=E6=9E=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移除全部 TypeScript 类型定义、源码路径和实现常量， 聚焦三层递进策略的设计哲学、保留窗口的三约束平衡、 工具对完整性保证和压缩后重新注入的设计洞察。 Co-Authored-By: Claude Opus 4.6 --- docs/context/compaction.mdx | 282 ++++++++++-------------------------- 1 file changed, 74 insertions(+), 208 deletions(-) diff --git a/docs/context/compaction.mdx b/docs/context/compaction.mdx index 7ca01d01d..79bf7743e 100644 --- a/docs/context/compaction.mdx +++ b/docs/context/compaction.mdx @@ -1,265 +1,131 @@ --- -title: "上下文压缩 - Compaction 三层策略与边界机制" -description: "深度解析 Claude Code 上下文压缩的完整实现：Session Memory 压缩、传统 API 摘要压缩、MicroCompact 局部压缩三层策略，以及 CompactBoundary 消息、工具对保持、PTL 紧急降级等关键机制。" -keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩", "上下文窗口", "MicroCompact"] +title: "上下文压缩" +description: "对话历史不断增长，token 窗口有限。理解 Claude Code 的三层压缩策略、边界标记机制和紧急降级路径。" +keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩"] --- -{/* 本章目标：从源码层面剖析压缩的三层策略、边界机制和关键常量 */} +## 核心问题 -## 压缩的触发时机 +AI 没有真正的长期记忆——它只能看到当前 API 请求中的内容。随着对话增长，token 消耗持续上升，最终会触及模型的上下文窗口限制。 -上下文压缩不是单一操作，而是**三层递进**的策略系统，对应不同的触发条件和严重程度： +压缩就是在"保留足够的语义信息"和"减少 token 占用"之间找平衡。 -| 层级 | 触发条件 | 实现位置 | 是否需要 API 调用 | -|------|---------|---------|:---:| -| **MicroCompact** | 单个工具输出过长 | `microCompact.ts` | 否 | -| **Session Memory Compact** | 自动压缩触发（需 feature flag） | `sessionMemoryCompact.ts` | 否 | -| **传统 API 摘要** | 手动 `/compact` 或 SM 不可用时的自动回退 | `compact.ts` | 是 | +## 三层递进策略 -### 压缩入口的优先级链 +系统不是用一种方法解决所有压缩需求，而是根据严重程度递进使用三种策略： -源码路径：`src/commands/compact/compact.ts` +| 层级 | 触发条件 | 是否需要 API 调用 | 成本 | +|------|----------|:---:|------| +| **微压缩** | 单个工具输出过长 | 否 | 几乎为零 | +| **Session Memory 压缩** | 自动压缩触发时优先尝试 | 否 | 低（使用已提取的记忆） | +| **AI 摘要压缩** | 上述方法不可用或用户手动触发 | 是 | 高（需要额外 API 调用） | -当用户执行 `/compact` 或系统触发自动压缩时，压缩命令按以下优先级尝试： +### 设计哲学：从廉价到昂贵 -```typescript -// compact.ts:55-99 — 简化后的优先级链 -if (!customInstructions) { - const sessionMemoryResult = await trySessionMemoryCompaction(messages, ...) - if (sessionMemoryResult) return sessionMemoryResult // 优先：SM 压缩 -} +为什么不直接用 AI 摘要？因为 AI 摘要需要额外的 API 调用——既花钱又花时间。系统的策略是**先用确定性操作（廉价），不行再用 AI 生成（昂贵）**。 -if (reactiveCompact?.isReactiveOnlyMode()) { - return await compactViaReactive(messages, ...) // 次选：Reactive 压缩 -} +这种分层设计意味着大部分情况下，系统可以在用户无感知的情况下释放足够的 token。 -// 兜底：传统 API 摘要 -const microcompactResult = await microcompactMessages(messages, context) -const messagesForCompact = microcompactResult.messages -// → 调用 AI 模型生成摘要 -``` +## 第一层：微压缩（Micro-Compact） -注意：SM 压缩不支持自定义指令（`/compact 聚焦在认证模块`），有自定义指令时直接走传统路径。 +微压缩不生成摘要，只是清除旧的工具调用结果。 -## 第一层：MicroCompact — 局部压缩 +### 工作原理 -源码路径：`src/services/compact/microCompact.ts` +AI 在工作过程中会产生大量工具输出：文件内容、命令结果、搜索匹配等。这些信息在产生时很重要，但随着对话推进，它们的价值迅速降低。 -MicroCompact 不压缩整个对话，而是**清除旧工具输出的内容**。它维护一个白名单： +微压缩识别这些"过期"的工具输出，将其替换为简短的占位符文本。原始内容仍保留在磁盘上的 transcript 文件中，只是不再发送给 API。 -```typescript -// src/services/compact/microCompact.ts:41-50 -const COMPACTABLE_TOOLS = new Set([ - FILE_READ_TOOL_NAME, // 'Read' - 文件读取 - ...SHELL_TOOL_NAMES, // 'Bash' - 命令输出 - GREP_TOOL_NAME, // 'Grep' - 搜索结果 - GLOB_TOOL_NAME, // 'Glob' - 文件列表 - WEB_SEARCH_TOOL_NAME, // 'WebSearch' - 搜索结果 - WEB_FETCH_TOOL_NAME, // 'WebFetch' - 网页内容 - FILE_EDIT_TOOL_NAME, // 'Edit' - 编辑输出 - FILE_WRITE_TOOL_NAME, // 'Write' - 写入输出 -]) -``` +### 时间衰减 -替换策略：将超过时间窗口的工具输出内容替换为 `[Old tool result content cleared]`。这不是简单的截断——原始内容仍保留在 JSONL transcript 中，只是不再发送给 API。 - -MicroCompact 还有一个**时间衰减配置**（`timeBasedMCConfig.ts`）：越旧的工具输出越容易被清除，最近的优先保留。 +越旧的工具输出越容易被清除，最近操作的优先保留。这个策略基于一个经验观察：AI 通常只需要最近几步操作的上下文，更早的工具结果很少被再次引用。 ### 图片和文档的特殊处理 -```typescript -const IMAGE_MAX_TOKEN_SIZE = 2000 -``` +图片和 PDF 文档的 token 占用远高于文本。微压缩会将大型图片和文档替换为文本标记（如 `[image]`），在保留"这里曾有一张图片"的语义的同时释放大量 token。 -图片 block 如果超过 2000 token 估算值，也会被 MicroCompact 清除。PDF document block 同理。 +## 第二层：Session Memory 压缩 -## 第二层：Session Memory Compact — 无 API 调用的压缩 +当微压缩释放的 token 不够时，系统优先尝试 Session Memory 压缩。 -源码路径：`src/services/compact/sessionMemoryCompact.ts` +### 设计思路 -当 `tengu_session_memory` + `tengu_sm_compact` 两个 feature flag 启用时，系统优先使用 Session Memory 进行压缩——**不需要调用摘要模型**，直接使用已经提取好的 Session Memory 作为对话摘要。 +系统在对话过程中会持续提取关键信息形成"Session Memory"。压缩时，直接使用这些已提取的记忆作为对话摘要，而不需要额外调用 AI 生成摘要。 -### 保留窗口的计算 +### 保留窗口 -```typescript -// sessionMemoryCompact.ts:324-397 -export function calculateMessagesToKeepIndex(messages, lastSummarizedIndex) { - const config = getSessionMemoryCompactConfig() - // 默认: minTokens=10K, minTextBlockMessages=5, maxTokens=40K +压缩后保留的消息需要满足三个约束： - let startIndex = lastSummarizedIndex + 1 - // 从 lastSummarizedIndex 向前扩展，直到满足两个下限或命中上限 - for (let i = startIndex - 1; i >= floor; i--) { - totalTokens += estimateMessageTokens([msg]) - if (hasTextBlocks(msg)) textBlockMessageCount++ - startIndex = i - if (totalTokens >= config.maxTokens) break - if (totalTokens >= config.minTokens && textBlockMessageCount >= config.minTextBlockMessages) break - } - return adjustIndexToPreserveAPIInvariants(messages, startIndex) -} -``` +- **最小深度**：至少保留 10K token 的最近对话（确保 AI 有足够的上下文） +- **最小连续性**：至少保留 5 条包含文本的消息（确保对话连贯） +- **最大上限**：不超过 40K token（避免保留太多又很快触发下一次压缩） -这个算法确保压缩后保留的消息窗口满足： -- 至少 10,000 token（有上下文深度） -- 至少 5 条包含文本的消息（有对话连续性） -- 最多 40,000 token（不会太大又触发下一次压缩） +这三个约束形成了"不要压缩太少（AI 会迷失），也不要保留太多（很快又需要压缩）"的平衡。 -### 工具对完整性保护 +### 工具对完整性 -`adjustIndexToPreserveAPIInvariants()` 是压缩中一个**关键的正确性保证**： +这是一个关键的**正确性保证**：API 要求每个工具调用都有对应的工具结果，反之亦然。如果压缩恰好切在一个工具调用和它的结果之间，API 会报错。 -API 要求每个 `tool_result` 都有对应的 `tool_use`，反之亦然。如果压缩恰好切在一条 `tool_result` 消息处，会导致 API 报错。 +系统在计算压缩边界时，会自动向前或向后调整切分点，确保所有工具调用-结果对要么完整保留，要么一起被压缩。 -```typescript -// sessionMemoryCompact.ts:232-314 -// Step 1: 向前扫描，找到所有被保留消息中 tool_result 引用的 tool_use -// Step 2: 向前扫描，找到与被保留 assistant 消息共享 message.id 的 thinking block -// 两种情况都需要将 startIndex 向前移动 -``` +## 第三层：AI 摘要压缩 -流式传输会将一个 assistant 消息拆分为多条存储记录（thinking、tool_use 等各有独立 uuid 但共享 `message.id`），这增加了边界情况的复杂度。 - -## 第三层：传统 API 摘要压缩 - -源码路径：`src/services/compact/compact.ts` - -当 SM 压缩不可用时，系统回退到传统方式：调用 AI 模型生成对话摘要。 +当上述方法都不可用时（或用户手动触发 `/compact` 时），系统调用 AI 生成对话摘要。 ### 压缩前处理 -发送给摘要模型之前，消息会经过多层预处理： - -```typescript -// compact.ts:147-202 -const stripped = stripImagesFromMessages(messages) // 图片→[image] 文字标记 -const stripped2 = stripReinjectedAttachments(stripped) // 移除会被重新注入的附件 -``` - -图片被替换为 `[image]` 标记，防止摘要 API 调用本身也触发 prompt-too-long 错误。 +发送给摘要 AI 的消息会经过预处理： +- 图片被替换为文本标记（防止摘要请求本身也超出 token 限制） +- 会被重新注入的附件被剥离（避免重复） ### 压缩后的重新注入 -压缩后，系统会从摘要中**重新注入关键上下文**： +压缩不是"砍掉旧对话就完了"。AI 在压缩后立即需要知道"现在正在做什么"。系统会在摘要后重新注入关键上下文： -```typescript -// compact.ts:126-134 -export const POST_COMPACT_TOKEN_BUDGET = 50_000 // 总预算 -export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5 // 最多恢复 5 个文件 -export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000 // 每文件 5K token -export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000 // 每技能 5K token -export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000 // 技能总预算 25K -``` +| 重新注入内容 | 预算 | 设计理由 | +|-------------|------|----------| +| 最近读取的文件（最多 5 个） | 每文件 5K token | AI 最可能需要的就是刚操作过的文件 | +| 已激活的技能指令 | 每技能 5K，总计 25K | 保持 AI 的能力集不变 | +| CLAUDE.md 内容 | 不限 | 用户的项目指令必须始终存在 | +| MCP 工具发现结果 | 不限 | 保持工具可用性 | -这 50K token 的重新注入预算用于： -1. 恢复最近读取的文件内容（最多 5 个文件，每个截断到 5K token） -2. 恢复已激活的技能指令（每个技能截断到 5K token，总计 25K） -3. 重新注入 CLAUDE.md 内容 -4. 恢复 MCP 工具发现结果 +**设计洞察**：总共 50K token 的重新注入预算看起来是浪费——刚压缩释放的 token 立刻又被用掉了一部分。但这是必要的：没有这些重新注入，AI 在压缩后会"忘记"当前任务状态，导致糟糕的用户体验。 -## CompactBoundary：压缩的边界标记 +## 边界标记：压缩的"墓碑" -源码路径：`src/utils/messages.ts`（`createCompactBoundaryMessage`） +每次压缩后，系统在消息流中插入一条边界标记消息。这条消息不展示给用户，但记录了： +- 压缩类型（自动/手动/微压缩） +- 压缩前的 token 数 +- 哪些消息被保留 -每次压缩后，系统在消息流中插入一条 `SystemCompactBoundaryMessage`： +后续所有操作只处理最后一条边界标记之后的消息。这防止了"重复压缩已经压缩过的内容"——每次压缩都是相对于上一次边界的新压缩。 -```typescript -type SystemCompactBoundaryMessage = { - type: 'system' - message: { - type: 'compact_boundary' - compactMetadata: { - compactType: 'auto' | 'manual' | 'micro' - preCompactTokenCount: number - lastUserMessageUuid: string - preCompactDiscoveredTools?: string[] - } - } -} -``` +### 微压缩 vs 全量压缩的边界区别 -后续所有操作只处理**最后一条 boundary 之后**的消息： +微压缩的边界标记更轻量——它只记录哪些工具结果被清除了，不生成摘要。原始消息仍然存在（只是内容被替换为占位符），而非被摘要替代。 -```typescript -// messages.ts -export function getMessagesAfterCompactBoundary(messages: Message[]): Message[] { - const lastBoundary = messages.findLastIndex(m => isCompactBoundaryMessage(m)) - return lastBoundary >= 0 ? messages.slice(lastBoundary + 1) : messages -} -``` +## 紧急降级：Prompt Too Long -### Preserved Segment 注解 +当压缩后仍然超出 token 限制时，系统进入紧急路径： -boundary 消息上还附加了 `preservedSegment` 注解，记录哪些消息被保留而非压缩： +1. **更激进的压缩**：尝试比正常压缩更激进的策略 +2. **直接截断**：从最早的对话开始删除，直到能塞进上下文窗口 +3. **放弃并报错**：如果以上都失败，向用户报告错误 -```typescript -// compact.ts — annotateBoundaryWithPreservedSegment -boundaryMarker.compactMetadata.preservedSegment = { - summaryMessageUuid: string - preservedMessageUuids: string[] -} -``` +**设计哲学**：系统宁可丢失部分对话历史，也不让整个会话卡死。用户可以通过文件快照和 transcript 记录恢复丢失的信息。 -这在会话恢复时帮助加载器正确重建消息链，避免重复压缩已保留的消息。 +## Hook 机制 -### Microcompact Boundary +压缩前后支持自定义 Hook： -Microcompact 操作使用单独的 boundary 类型，与全量压缩的 `compact_boundary` 不同： +- **Pre-compact Hook**：压缩前执行，可以标记"必须保留"的内容 +- **Post-compact Hook**：压缩后执行，可以验证关键信息是否被保留 +- **Session Start Hook**：压缩后恢复 CLAUDE.md 等上下文 -```typescript -// src/utils/messages.ts:4599-4614 -type SystemMicrocompactBoundaryMessage = { - type: 'system' - subtype: 'microcompact_boundary' - content: 'Context microcompacted' - compactMetadata: { - trigger: 'auto' // Microcompact 只有自动触发 - preTokens: number // 压缩前 token 数 - tokensSaved: number // 节省的 token 数 - compactedToolIds: string[] // 被压缩的工具 ID 列表 - clearedAttachmentUUIDs: string[] // 被清除的附件 UUID - } -} -``` +这确保了用户的自定义逻辑在压缩过程中被尊重——例如，用户可以通过 Hook 确保某个关键文件的内容永远不会被压缩掉。 -与 `compact_boundary` 的区别： -- **保留原始消息**：Microcompact 仅清除工具输出内容，不删除消息本身 -- **可追溯性**：`compactedToolIds` 记录了哪些工具结果被清除 -- **轻量级**：不生成摘要，不调用 API +## 接下来 -## PTL 紧急降级：Prompt Too Long - -当压缩后仍然超出 token 限制（`PROMPT_TOO_LONG` 错误），系统会进入紧急降级路径： - -1. **Reactive Compact**：`reactiveCompactOnPromptTooLong()` 尝试更激进的压缩 -2. **截断重试**：如果 reactive 也失败，`truncateHeadForPTLRetry()` 直接截断最早的消息 -3. 放弃并报错 - -Reactive Compact 目前在反编译版本中是 stub（`isReactiveOnlyMode() → false`），表明这是 Anthropic 内部的实验性功能。 - -## 压缩的 Hook 机制 - -压缩前后可以执行自定义 Hook： - -- **Pre-compact Hook**（`executePreCompactHooks`）：在压缩前执行，可以注入"必须保留"的标记 -- **Post-compact Hook**（`executePostCompactHooks`）：在压缩后执行，可以验证关键信息是否保留 -- **Session Start Hook**（`processSessionStartHooks('compact')`）：SM 压缩使用此 Hook 恢复 CLAUDE.md 等上下文 - -Hook 结果以 `HookResultMessage` 的形式附加到压缩结果中，确保用户的自定义逻辑在压缩过程中被尊重。 - -## Snip Compact（实验性） - -源码路径：`src/services/compact/snipCompact.ts`（stub） - -Snip Compact 是另一种实验性压缩策略，在反编译版本中为空壳实现。从 stub 的类型签名推断： - -```typescript -snipCompactIfNeeded(messages, options?: { force?: boolean }) → { - messages: Message[] - executed: boolean - tokensFreed: number - boundaryMessage?: Message -} -``` - -它似乎是一种**更细粒度的消息级裁剪**（snip = 剪切），可能是对单条消息的进一步压缩，而非整个对话。`shouldNudgeForSnips()` 和 `SNIP_NUDGE_TEXT` 暗示它可能会提示用户触发。 +- **项目记忆** — 理解跨会话的记忆持久化设计 +- **令牌预算** — 了解 token 窗口的动态计算和阈值管理 +- **系统提示词** — 理解上下文组装的缓存优化策略