cs-note/claude-code-best/docs/context/compaction.md

---
tags: [上下文压缩, compaction, token管理, MicroCompact, Session-Memory]
create time: 2026-06-09 22:15
---

# 上下文压缩 - Compaction 三层策略与边界机制

## 概述

Claude Code 的上下文压缩是一个三层递进的策略系统: MicroCompact 局部压缩、Session Memory 无 API 压缩、传统 API 摘要压缩。配合 CompactBoundary 边界标记、工具对完整性保护和 PTL 紧急降级，确保对话在 token 限制内持续运行。

## 正文

### 压缩的触发时机

上下文压缩不是单一操作，而是**三层递进**的策略系统，对应不同的触发条件和严重程度:

| 层级 | 触发条件 | 实现位置 | 是否需要 API 调用 |
|------|---------|---------|:---:|
| **MicroCompact** | 单个工具输出过长 | `microCompact.ts` | 否 |
| **Session Memory Compact** | 自动压缩触发（需 feature flag） | `sessionMemoryCompact.ts` | 否 |
| **传统 API 摘要** | 手动 `/compact` 或 SM 不可用时的自动回退 | `compact.ts` | 是 |

#### 压缩入口的优先级链

源码路径: `src/commands/compact/compact.ts`

当用户执行 `/compact` 或系统触发自动压缩时，压缩命令按以下优先级尝试:

```typescript
// compact.ts:55-99 -- 简化后的优先级链
if (!customInstructions) {
  const sessionMemoryResult = await trySessionMemoryCompaction(messages, ...)
  if (sessionMemoryResult) return sessionMemoryResult      // 优先: SM 压缩
}

if (reactiveCompact?.isReactiveOnlyMode()) {
  return await compactViaReactive(messages, ...)            // 次选: Reactive 压缩
}

// 兜底: 传统 API 摘要
const microcompactResult = await microcompactMessages(messages, context)
const messagesForCompact = microcompactResult.messages
// -> 调用 AI 模型生成摘要
```

> [!warning] SM 压缩限制
> SM 压缩不支持自定义指令（如 `/compact 聚焦在认证模块`），有自定义指令时直接走传统路径。

### 第一层: MicroCompact -- 局部压缩

源码路径: `src/services/compact/microCompact.ts`

MicroCompact 不压缩整个对话，而是**清除旧工具输出的内容**。它维护一个白名单:

```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`）: 越旧的工具输出越容易被清除，最近的优先保留。

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

图片 block 如果超过 2000 token 估算值（`IMAGE_MAX_TOKEN_SIZE = 2000`），也会被 MicroCompact 清除。PDF document block 同理。

### 第二层: Session Memory Compact -- 无 API 调用的压缩

源码路径: `src/services/compact/sessionMemoryCompact.ts`

当 `tengu_session_memory` + `tengu_sm_compact` 两个 feature flag 启用时，系统优先使用 Session Memory 进行压缩——**不需要调用摘要模型**，直接使用已经提取好的 Session Memory 作为对话摘要。

#### 保留窗口的计算

```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)
}
```

这个算法确保压缩后保留的消息窗口满足:
- 至少 10,000 token（有上下文深度）
- 至少 5 条包含文本的消息（有对话连续性）
- 最多 40,000 token（不会太大又触发下一次压缩）

#### 工具对完整性保护

`adjustIndexToPreserveAPIInvariants()` 是压缩中一个**关键的正确性保证**:

API 要求每个 `tool_result` 都有对应的 `tool_use`，反之亦然。如果压缩恰好切在一条 `tool_result` 消息处，会导致 API 报错。

流式传输会将一个 assistant 消息拆分为多条存储记录（thinking、tool_use 等各有独立 uuid 但共享 `message.id`），这增加了边界情况的复杂度。

> [!question] 思考题
> 为什么流式传输会导致一个 assistant 消息被拆分为多条存储记录? 这对压缩的边界处理带来了什么挑战?

### 第三层: 传统 API 摘要压缩

源码路径: `src/services/compact/compact.ts`

当 SM 压缩不可用时，系统回退到传统方式: 调用 AI 模型生成对话摘要。

#### 压缩前处理

发送给摘要模型之前，消息会经过多层预处理: 图片被替换为 `[image]` 标记，防止摘要 API 调用本身也触发 prompt-too-long 错误。

#### 压缩后的重新注入

压缩后，系统会从摘要中**重新注入关键上下文**:

```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
```

这 50K token 的重新注入预算用于:
1. 恢复最近读取的文件内容（最多 5 个文件，每个截断到 5K token）
2. 恢复已激活的技能指令（每个技能截断到 5K token，总计 25K）
3. 重新注入 CLAUDE.md 内容
4. 恢复 MCP 工具发现结果

### CompactBoundary: 压缩的边界标记

源码路径: `src/utils/messages.ts`（`createCompactBoundaryMessage`）

每次压缩后，系统在消息流中插入一条 `SystemCompactBoundaryMessage`:

```typescript
type SystemCompactBoundaryMessage = {
  type: 'system'
  message: {
    type: 'compact_boundary'
    compactMetadata: {
      compactType: 'auto' | 'manual' | 'micro'
      preCompactTokenCount: number
      lastUserMessageUuid: string
      preCompactDiscoveredTools?: string[]
    }
  }
}
```

后续所有操作只处理**最后一条 boundary 之后**的消息。

#### Preserved Segment 注解

boundary 消息上还附加了 `preservedSegment` 注解，记录哪些消息被保留而非压缩。这在会话恢复时帮助加载器正确重建消息链，避免重复压缩已保留的消息。

#### Microcompact Boundary

Microcompact 操作使用单独的 boundary 类型，与全量压缩的 `compact_boundary` 不同:

```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
  }
}
```

与 `compact_boundary` 的区别:
- **保留原始消息**: Microcompact 仅清除工具输出内容，不删除消息本身
- **可追溯性**: `compactedToolIds` 记录了哪些工具结果被清除
- **轻量级**: 不生成摘要，不调用 API

### PTL 紧急降级: Prompt Too Long

当压缩后仍然超出 token 限制（`PROMPT_TOO_LONG` 错误），系统会进入紧急降级路径:

1. **Reactive Compact**: `reactiveCompactOnPromptTooLong()` 尝试更激进的压缩
2. **截断重试**: 如果 reactive 也失败，`truncateHeadForPTLRetry()` 直接截断最早的消息
3. 放弃并报错

> [!warning] 实验性功能
> 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 的类型签名推断，它似乎是一种**更细粒度的消息级裁剪**（snip = 剪切），可能是对单条消息的进一步压缩，而非整个对话。`shouldNudgeForSnips()` 和 `SNIP_NUDGE_TEXT` 暗示它可能会提示用户触发。

## 关联笔记

- [[token-budget]] - Token 预算与自动压缩触发阈值
- [[system-prompt]] - System Prompt 缓存策略
- [[project-memory]] - Session Memory 与记忆系统
- [[../conversation/the-loop]] - Agentic Loop 中的压缩触发