6 · 上下文治理 ★

这是全系统工程密度最高的一块。它要解决的问题只有一句话：智能体的上下文会自己长大，而上下文窗口有硬上限。

6.1 五级流水线

每一次调用模型之前，消息历史都要穿过这条流水线。顺序按成本从低到高排列：

// query.ts 主循环内，每次迭代开头
let messagesForQuery = [...getMessagesAfterCompactBoundary(messages)]
//   先取"上次压缩分界点之后"的消息，之前的已被摘要替代

// ① 工具结果预算：单条 / 每条消息聚合超限 → 落盘换引用
messagesForQuery = await applyToolResultBudget(
  messagesForQuery,
  toolUseContext.contentReplacementState,
  persistReplacements ? records => void recordContentReplacement(...) : undefined,
  new Set(toolUseContext.options.tools
    .filter(t => !Number.isFinite(t.maxResultSizeChars))    // 排除声明为无穷大的工具
    .map(t => t.name)),
)

// ② 裁剪：删除僵尸消息与失效标记
let snipTokensFreed = 0
if (feature('HISTORY_SNIP')) {
  const snipResult = snipModule!.snipCompactIfNeeded(messagesForQuery)
  messagesForQuery = snipResult.messages
  snipTokensFreed = snipResult.tokensFreed
  if (snipResult.boundaryMessage) yield snipResult.boundaryMessage
}

// ③ 微压缩：按工具调用 id 精确删除旧结果
const microcompactResult = await deps.microcompact(messagesForQuery, toolUseContext, querySource)
messagesForQuery = microcompactResult.messages
const pendingCacheEdits = feature('CACHED_MICROCOMPACT')
  ? microcompactResult.compactionInfo?.pendingCacheEdits : undefined

// ④ 上下文折叠：投影式，可重放
if (feature('CONTEXT_COLLAPSE') && contextCollapse) {
  const collapseResult = await contextCollapse.applyCollapsesIfNeeded(
    messagesForQuery, toolUseContext, querySource)
  messagesForQuery = collapseResult.messages
}

// ⑤ 自动摘要压缩：一次完整的模型调用
const { compactionResult, consecutiveFailures } = await deps.autocompact(
  messagesForQuery, toolUseContext, { systemPrompt, userContext, systemContext,
  toolUseContext, forkContextMessages: messagesForQuery }, querySource, tracking, snipTokensFreed)

// ⑥ 硬阻断检查（只在自动压缩被关闭时生效）
if (!compactionResult && querySource !== 'compact' && ... ) {
  const { isAtBlockingLimit } = calculateTokenWarningState(
    tokenCountWithEstimation(messagesForQuery) - snipTokensFreed,
    toolUseContext.options.mainLoopModel)
  if (isAtBlockingLimit) {
    yield createAssistantAPIErrorMessage({ content: PROMPT_TOO_LONG_ERROR_MESSAGE, ... })
    return { reason: 'blocking_limit' }
  }
}

顺序的理由

关于第 ④ 级为什么必须排在第 ⑤ 级之前，源码里有一句精确的说明：

第 ⑥ 级的反直觉设计

注意硬阻断的触发条件：只在自动压缩被关闭时才生效。注释解释了：

6.2 第 ① 级：工具结果预算

单条结果的落盘

export const PREVIEW_SIZE_BYTES = 2000                     // 预览多少字节
export const PERSISTED_OUTPUT_TAG = '<persisted-output>'    // 包裹标签
export const TOOL_RESULTS_SUBDIR = 'tool-results'          // 落盘子目录
export const TOOL_RESULT_CLEARED_MESSAGE = '[Old tool result content cleared]'

claude-code/src/utils/toolResultStorage.ts

流程：结果超过工具声明的 maxResultSizeChars → 完整内容写到 tool-results/ 目录 → 模型收到「前 2000 字节预览 + 文件路径」→ 需要全文时模型自己去 Read 那个文件。

那个 Infinity 的例外

每条消息的聚合预算

除了单条限制，还有一个 ContentReplacementState（内容替换状态）：

export type ContentReplacementState = {
  seenIds: ...        // 已经通过预算检查的结果 id
  ...
}
export function createContentReplacementState(): ContentReplacementState
export function cloneContentReplacementState(...): ContentReplacementState

它防的是：模型一次并行发出 20 个搜索调用，每个结果都在单条上限之内，但加起来爆掉。

而且它的生命周期很讲究，注释说明了三种情况：

6.3 第 ③ 级：微压缩与缓存编辑

困境

目标很朴素：把没用了的旧工具结果删掉。但直接删有致命副作用：

解法：让服务端在缓存里删

/**
 * Cached microcompact path - uses cache editing API to remove tool results
 * without invalidating the cached prefix.
 *
 * - Does NOT modify local message content
 *   (cache_reference and cache_edits are added at API layer)
 * - Uses count-based trigger/keep thresholds from GrowthBook config
 * - Takes precedence over regular microcompact (no disk persistence)
 */
async function cachedMicrocompactPath(messages, querySource) {
  const mod    = await getCachedMCModule()
  const state  = ensureCachedMCState()
  const config = mod.getCachedMCConfig()

  // 1. 扫出所有"可压缩工具"的调用 id
  const compactableToolIds = new Set(collectCompactableToolIds(messages))

  // 2. 按"用户消息"分组，注册这些工具结果
  for (const message of messages) {
    if (message.type === 'user' && Array.isArray(message.message.content)) {
      const groupIds: string[] = []
      for (const block of message.message.content) {
        if (block.type === 'tool_result' &&
            compactableToolIds.has(block.tool_use_id) &&
            !state.registeredTools.has(block.tool_use_id)) {
          mod.registerToolResult(state, block.tool_use_id)
          groupIds.push(block.tool_use_id)
        }
      }
      mod.registerToolMessage(state, groupIds)
    }
  }

  // 3. 问状态机：该删哪些？（保留最近 N 个）
  const toolsToDelete = mod.getToolResultsToDelete(state)

  if (toolsToDelete.length > 0) {
    // 4. 生成 cache_edits 指令块，排队交给接口层
    const cacheEdits = mod.createCacheEditsBlock(state, toolsToDelete)
    if (cacheEdits) pendingCacheEdits = cacheEdits
    ...
    // 5. ★ 消息原样返回 —— 本地一个字都没改
    return { messages, compactionInfo: { pendingCacheEdits: {...} } }
  }
  return { messages }
}

claude-code/src/services/compact/microCompact.ts

只有 8 种工具的结果允许被删

const COMPACTABLE_TOOLS = new Set<string>([
  FILE_READ_TOOL_NAME,      // 读文件
  ...SHELL_TOOL_NAMES,      // Bash / PowerShell
  GREP_TOOL_NAME,           // 内容搜索
  GLOB_TOOL_NAME,           // 文件名搜索
  WEB_SEARCH_TOOL_NAME,     // 网络搜索
  WEB_FETCH_TOOL_NAME,      // 抓网页
  FILE_EDIT_TOOL_NAME,      // 编辑文件
  FILE_WRITE_TOOL_NAME,     // 写文件
])

这 8 种的共同特征是：结果是一次性的观察数据 —— 读了个文件、搜了个词、跑了个命令，模型消化完就不需要原文了。

而其他工具（比如 TodoWrite 维护待办清单）的结果代表持续有效的状态，删掉会造成失忆。

删了多少 token，要等服务端告诉你

// query.ts，流式响应结束后
if (feature('CACHED_MICROCOMPACT') && pendingCacheEdits) {
  const lastAssistant = assistantMessages.at(-1)
  const usage = lastAssistant?.message.usage
  // ★ 这个字段是"累积/粘性"的（从会话开始的总量），不是本次增量
  const cumulativeDeleted = usage
    ? ((usage as unknown as Record<string, number>).cache_deleted_input_tokens ?? 0) : 0
  const deletedTokens = Math.max(0,
    cumulativeDeleted - pendingCacheEdits.baselineCacheDeletedTokens)   // 减去请求前的基线
  if (deletedTokens > 0) {
    yield createMicrocompactBoundaryMessage(
      pendingCacheEdits.trigger, 0, deletedTokens, pendingCacheEdits.deletedToolIds, [])
  }
}

因为本地什么都没改，客户端不知道实际省了多少，所以「已压缩」的通知消息被推迟到接口响应之后才发。

副作用：存在一个短暂的「认知偏差窗口」 —— 从「决定删除」到「响应回来」这几秒内，客户端对上下文大小的估算是偏高的。这也是为什么后面自动压缩的阈值检查里到处是手工补偿项（比如 - snipTokensFreed）。

三处防止状态串味的保护

// 保护 1：只对主线程跑缓存编辑
if (mod.isCachedMicrocompactEnabled() &&
    mod.isModelSupportedForCacheEditing(model) &&
    isMainThreadSource(querySource)) {
  return await cachedMicrocompactPath(messages, querySource)
}

注释：「Only run cached MC for the main thread to prevent forked agents (session_memory, prompt_suggestion, etc.) from registering their tool_results in the global cachedMCState, which would cause the main thread to try deleting tools that don't exist in its own conversation.」

译：只对主线程运行缓存微压缩，防止分叉出的智能体（会话记忆、提示建议等）把它们的工具结果注册进全局状态，从而导致主线程试图删除自己对话里根本不存在的工具。

问题的根源是：cachedMCState 是一个模块级的全局单例，和消息数组各存一份真相。这是这套机制最大的复杂度来源。

反过来的那条路径：时间触发

export function evaluateTimeBasedTrigger(messages, querySource) {
  const config = getTimeBasedMCConfig()
  if (!config.enabled || !querySource || !isMainThreadSource(querySource)) return null
  const lastAssistant = messages.findLast(m => m.type === 'assistant')
  if (!lastAssistant) return null
  const gapMinutes = (Date.now() - new Date(lastAssistant.timestamp).getTime()) / 60_000
  if (!Number.isFinite(gapMinutes) || gapMinutes < config.gapThresholdMinutes) return null
  return { gapMinutes, config }
}

注释说明了这条路径的逻辑：

那个 Math.max(1, ...) 的边界陷阱

// Floor at 1: slice(-0) returns the full array (paradoxically keeps everything),
// and clearing ALL results leaves the model with zero working context.
// Neither degenerate is sensible — always keep at least the last.
const keepRecent = Math.max(1, config.keepRecent)
const keepSet  = new Set(compactableIds.slice(-keepRecent))
const clearSet = new Set(compactableIds.filter(id => !keepSet.has(id)))

译：下限设为 1：因为 slice(-0) 会返回整个数组（矛盾地导致什么都不删），而清空所有结果又会让模型完全没有工作上下文。两种退化情形都不合理。

（slice(-N) 在 JavaScript 里是「取最后 N 个」。但 -0 在数值上等于 0，而 slice(0) 是「从头取全部」。所以配置成「保留最近 0 个」时，实际行为是「全部保留」—— 一个典型的边界值陷阱。）

清理完还要重置状态并通知监控

suppressCompactWarning()
// 缓存微压缩的全局状态里存着之前几轮注册的工具 id。我们刚刚清空了其中一些的内容，
// 并且通过改变提示词内容使服务端缓存失效了。如果下一轮缓存微压缩带着过期状态运行，
// 它会试图去 cache_edit 那些服务端已经不存在的条目。所以重置它。
resetMicrocompactState()

// 我们刚改了提示词内容 —— 下一次响应的缓存读取量会很低，但这是我们自己造成的，
// 不是缓存断裂。告诉检测器预期会有一次下跌。
if (feature('PROMPT_CACHE_BREAK_DETECTION') && querySource) {
  notifyCacheDeletion(querySource)
}

最后那个 notifyCacheDeletion 指向第 12 章会讲的缓存断裂检测系统 —— 它监控「缓存命中率突然下跌」并告警。而这里是一次「合法的下跌」，所以要主动通知它别误报。

6.4 第 ⑤ 级：自动摘要压缩

阈值

export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000   // 警告线缓冲
export const ERROR_THRESHOLD_BUFFER_TOKENS   = 20_000   // 错误线缓冲

const threshold        = getAutoCompactThreshold(model)
const warningThreshold = threshold - WARNING_THRESHOLD_BUFFER_TOKENS
const errorThreshold   = threshold - ERROR_THRESHOLD_BUFFER_TOKENS

压缩是一次「分叉子智能体」调用

压缩本身要调模型做摘要。Claude Code 用分叉子智能体跑它，并且让分叉继承父的完整工具集 —— 不是因为摘要需要工具，而是为了让缓存键匹配上、复用父已建立的缓存前缀。

这个决定带来了一个真实的生产问题，源码注释里连数字都留了：

const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.

`

claude-code/src/services/compact/prompt.ts

两段式输出：草稿纸模式

const DETAILED_ANALYSIS_INSTRUCTION_BASE = `Before providing your final summary,
wrap your analysis in <analysis> tags to organize your thoughts and ensure
you've covered all necessary points. In your analysis process:

1. Chronologically analyze each message and section of the conversation.
   For each section thoroughly identify:
   - The user's explicit requests and intents
   - Your approach to addressing the user's requests
   - Key decisions, technical concepts and code patterns
   - Specific details like:
     - file names
     - full code snippets
     - function signatures
...`

而处理函数 formatCompactSummary() 会把 analysis 块整个剥掉，只把 summary 块放进上下文。源码注释：「The <analysis> block is a drafting scratchpad that formatCompactSummary() strips before the summary reaches context.」

压缩成功后的埋点

logEvent('tengu_auto_compact_succeeded', {
  originalMessageCount:  messages.length,
  compactedMessageCount: compactionResult.summaryMessages.length +
                         compactionResult.attachments.length +
                         compactionResult.hookResults.length,
  preCompactTokenCount, postCompactTokenCount, truePostCompactTokenCount,
  compactionInputTokens:  compactionUsage?.input_tokens,
  compactionOutputTokens: compactionUsage?.output_tokens,
  compactionCacheReadTokens:     compactionUsage?.cache_read_input_tokens ?? 0,
  compactionCacheCreationTokens: compactionUsage?.cache_creation_input_tokens ?? 0,
  compactionTotalTokens: ...,
  queryChainId: ..., queryDepth: ...,
})

注意有三个「压缩后 token 数」：postCompactTokenCount 和 truePostCompactTokenCount。两者的区别正是前面讲的「认知偏差窗口」—— 一个是客户端估算，一个是服务端返回的真实值。把估算值和真实值都埋点上报，就能持续监控估算算法的偏差。

6.5 上下文真的超了：三级恢复瀑布

第 ③ 步为什么不能走结束钩子

体会一下这个循环的形状。「结束前质量检查」这个功能本身完全合理，但当失败原因是「上下文已经装不下了」时，它会：

1. 看到一个失败的回复
2. 判定不合格，生成一段「你的回答有以下问题……」的反馈
3. 把这段反馈注入上下文 —— 上下文变得更长了
4. 重试 → 更超了 → 又失败 → 回到第 1 步