Claude Code上下文窗口管理：动态压缩与熔断机制解析

1. 项目概述

在构建长时间运行的AI助手应用时，上下文窗口管理是一个极具挑战性的工程问题。Claude Code作为一个终端助手，其单次会话可能持续数小时，涉及数百次工具调用，这使得上下文token消耗很容易超出模型限制。本文基于Claude Code 2.1.88版本的TypeScript源码，深入分析其上下文窗口管理系统的设计与实现。

这套系统位于src/services/compact/目录下，由11个文件组成，实现了从自动压缩触发、多策略压缩到熔断保护的完整解决方案。它不仅解决了基础的技术问题，还展示了如何在大规模生产环境中处理边缘情况和系统间协同的工程智慧。

2. 核心设计思路

2.1 动态阈值计算

系统首先根据模型类型动态计算压缩触发阈值。这个过程分为两个关键步骤：

1. 计算有效上下文窗口大小（扣除输出预留）：

typescript复制const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000

export function getEffectiveContextWindowSize(model: string): number {
  const reservedTokensForSummary = Math.min(
    getMaxOutputTokensForModel(model),
    MAX_OUTPUT_TOKENS_FOR_SUMMARY
  )
  let contextWindow = getContextWindowForModel(model, getSdkBetas())
  
  // 支持环境变量覆盖（用于测试）
  const autoCompactWindow = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW
  if (autoCompactWindow) {
    contextWindow = Math.min(contextWindow, parseInt(autoCompactWindow, 10))
  }
  
  return contextWindow - reservedTokensForSummary
}

这个20,000 token的输出预留不是随意设定的，而是基于生产环境数据——源码注释明确指出"p99.99 of compact summary output being 17,387 tokens"。

2. 在有效窗口基础上扣除缓冲区：

typescript复制export const AUTOCOMPACT_BUFFER_TOKENS = 13_000

export function getAutoCompactThreshold(model: string): number {
  return getEffectiveContextWindowSize(model) - AUTOCOMPACT_BUFFER_TOKENS
}

这种分层计算方式确保了系统在不同模型和场景下都能保持合理的压缩触发点。

2.2 多级警告系统

为了给用户提供渐进式的体验，系统设置了四个递进的警告级别：

typescript复制export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000
export const ERROR_THRESHOLD_BUFFER_TOKENS = 20_000
export const MANUAL_COMPACT_BUFFER_TOKENS = 3_000

export function calculateTokenWarningState(tokenUsage, model) {
  return {
    percentLeft,                    // 剩余百分比