Skip to main content

​
压缩的触发时机

上下文压缩不是单一操作，而是三层递进的策略系统，对应不同的触发条件和严重程度：
层级触发条件实现位置是否需要 API 调用
MicroCompact单个工具输出过长microCompact.ts否
Session Memory Compact自动压缩触发（需 feature flag）sessionMemoryCompact.ts否
传统 API 摘要手动 /compact 或 SM 不可用时的自动回退compact.ts是

​
压缩入口的优先级链

源码路径：src/commands/compact/compact.ts 当用户执行 /compact 或系统触发自动压缩时，压缩命令按以下优先级尝试： 
// 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 模型生成摘要
注意：SM 压缩不支持自定义指令（/compact 聚焦在认证模块），有自定义指令时直接走传统路径。

​
第一层：MicroCompact — 局部压缩

源码路径：src/services/compact/microCompact.ts MicroCompact 不压缩整个对话，而是清除旧工具输出的内容。它维护一个白名单： 
const COMPACTABLE_TOOLS = new Set([
  'Read',      // 文件读取
  'Bash',      // 命令输出
  'Grep',      // 搜索结果
  'Glob',      // 文件列表
  'WebSearch', // 搜索结果
  'WebFetch',  // 网页内容
  'Edit',      // 编辑输出
  'Write',     // 写入输出
])
替换策略：将超过时间窗口的工具输出内容替换为 [Old tool result content cleared]。这不是简单的截断——原始内容仍保留在 JSONL transcript 中，只是不再发送给 API。 MicroCompact 还有一个时间衰减配置（timeBasedMCConfig.ts）：越旧的工具输出越容易被清除，最近的优先保留。

​
图片和文档的特殊处理

const IMAGE_MAX_TOKEN_SIZE = 2000
图片 block 如果超过 2000 token 估算值，也会被 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 作为对话摘要。

​
保留窗口的计算

// 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 报错。 
// sessionMemoryCompact.ts:232-314
// Step 1: 向前扫描，找到所有被保留消息中 tool_result 引用的 tool_use
// Step 2: 向前扫描，找到与被保留 assistant 消息共享 message.id 的 thinking block
// 两种情况都需要将 startIndex 向前移动
流式传输会将一个 assistant 消息拆分为多条存储记录（thinking、tool_use 等各有独立 uuid 但共享 message.id），这增加了边界情况的复杂度。

​
第三层：传统 API 摘要压缩

源码路径：src/services/compact/compact.ts 当 SM 压缩不可用时，系统回退到传统方式：调用 AI 模型生成对话摘要。

​
压缩前处理

发送给摘要模型之前，消息会经过多层预处理： 
// compact.ts:147-202
const stripped = stripImagesFromMessages(messages)   // 图片→[image] 文字标记
const stripped2 = stripReinjectedAttachments(stripped) // 移除会被重新注入的附件
图片被替换为 [image] 标记，防止摘要 API 调用本身也触发 prompt-too-long 错误。

​
压缩后的重新注入

压缩后，系统会从摘要中重新注入关键上下文： 
// compact.ts:124-132
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： 
type SystemCompactBoundaryMessage = {
  type: 'system'
  message: {
    type: 'compact_boundary'
    compactMetadata: {
      compactType: 'auto' | 'manual' | 'micro'
      preCompactTokenCount: number
      lastUserMessageUuid: string
      preCompactDiscoveredTools?: string[]
    }
  }
}
后续所有操作只处理最后一条 boundary 之后的消息： 
// messages.ts
export function getMessagesAfterCompactBoundary(messages: Message[]): Message[] {
  const lastBoundary = messages.findLastIndex(m => isCompactBoundaryMessage(m))
  return lastBoundary >= 0 ? messages.slice(lastBoundary + 1) : messages
}

​
Preserved Segment 注解

boundary 消息上还附加了 preservedSegment 注解，记录哪些消息被保留而非压缩： 
// compact.ts — annotateBoundaryWithPreservedSegment
boundaryMarker.compactMetadata.preservedSegment = {
  summaryMessageUuid: string
  preservedMessageUuids: string[]
}
这在会话恢复时帮助加载器正确重建消息链，避免重复压缩已保留的消息。

​
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 的类型签名推断： 
snipCompactIfNeeded(messages, options?: { force?: boolean }) → {
  messages: Message[]
  executed: boolean
  tokensFreed: number
  boundaryMessage?: Message
}
它似乎是一种更细粒度的消息级裁剪（snip = 剪切），可能是对单条消息的进一步压缩，而非整个对话。shouldNudgeForSnips() 和 SNIP_NUDGE_TEXT 暗示它可能会提示用户触发。