当前位置：首页 > news >正文

Claude Code 源码分析（四）：上下文窗口管理 —— 长对话场景下的 Token 预算与自动压缩

news 2026/5/25 23:56:43

本系列文章基于 Claude Code 2.1.88 版本的 TypeScript 源码进行分析。源码版权归 Anthropic 所有，本文仅用于技术研究。

引言

上下文窗口管理是 AI 应用工程中最核心的挑战之一。Claude Code 作为一个长时间运行的终端助手，单次会话可能持续数小时、涉及数百次工具调用，上下文 token 消耗极易超出模型限制。src/services/compact/目录下的 11 个文件实现了一套完整的上下文预算管理方案，涵盖自动压缩触发、多策略压缩、熔断保护、token 估算等环节。

涉及的核心源码文件：

src/services/compact/autoCompact.ts—— 自动压缩触发与熔断
src/services/compact/compact.ts—— 压缩策略实现
src/services/compact/microCompact.ts—— 缓存级微压缩
src/services/compact/sessionMemoryCompact.ts—— 会话记忆压缩
src/services/compact/prompt.ts—— 压缩 prompt 模板
src/services/tokenEstimation.ts—— 多策略 token 估算
src/cost-tracker.ts—— 成本追踪

一、自动压缩触发机制

1.1 阈值计算

系统根据模型的上下文窗口大小动态计算压缩阈值。计算过程分为两步：

第一步，计算有效上下文窗口大小（扣除输出预留）：

constMAX_OUTPUT_TOKENS_FOR_SUMMARY=20_000exportfunctiongetEffectiveContextWindowSize(model:string):number{constreservedTokensForSummary=Math.min(getMaxOutputTokensForModel(model),MAX_OUTPUT_TOKENS_FOR_SUMMARY)letcontextWindow=getContextWindowForModel(model,getSdkBetas())// 支持环境变量覆盖（用于测试）constautoCompactWindow=process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOWif(autoCompactWindow){contextWindow=Math.min(contextWindow,parseInt(autoCompactWindow,10))}returncontextWindow-reservedTokensForSummary}

20,000 token 的预留基于生产数据——源码注释指出"p99.99 of compact summary output being 17,387 tokens"。

第二步，在有效窗口基础上扣除缓冲区：

exportconstAUTOCOMPACT_BUFFER_TOKENS=13_000exportfunctiongetAutoCompactThreshold(model:string):number{returngetEffectiveContextWindowSize(model)-AUTOCOMPACT_BUFFER_TOKENS}

1.2 多级警告

系统设置了四个递进的警告级别：

exportconstWARNING_THRESHOLD_BUFFER_TOKENS=20_000exportconstERROR_THRESHOLD_BUFFER_TOKENS=20_000exportconstMANUAL_COMPACT_BUFFER_TOKENS=3_000exportfunctioncalculateTokenWarningState(tokenUsage,model){return{percentLeft,// 剩余百分比isAboveWarningThreshold,// 距上限 20K tokensisAboveErrorThreshold,// 距上限 20K tokensisAboveAutoCompactThreshold,// 触发自动压缩isAtBlockingLimit,// 距上限 3K tokens（阻止新请求）}}

当 token 用量达到阻塞阈值（距上限仅 3,000 tokens）时，系统会阻止新的请求，强制用户手动压缩。

1.3 递归保护

自动压缩本身也是一次 API 调用，因此需要防止递归触发：

exportasyncfunctionshouldAutoCompact(messages,model,querySource){// 会话记忆提取和压缩本身不触发自动压缩if(querySource==='session_memory'||querySource==='compact'){returnfalse}// 上下文折叠代理不触发自动压缩if(feature('CONTEXT_COLLAPSE')){if(querySource==='marble_origami')returnfalse}}

源码注释解释了marble_origami（上下文折叠代理）被排除的原因：如果它的上下文膨胀触发了自动压缩，runPostCompactCleanup会调用resetContextCollapse()，而这会销毁主线程的已提交日志（因为是模块级共享状态）。

二、熔断机制

这是整个压缩系统中最具工程价值的设计之一。

constMAX_CONSECUTIVE_AUTOCOMPACT_FAILURES=3exportasyncfunctionautoCompactIfNeeded(messages,toolUseContext,...){// 熔断器：连续失败 N 次后停止重试if(tracking?.consecutiveFailures>=MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES){return{wasCompacted:false}}try{constcompactionResult=awaitcompactConversation(...)return{wasCompacted:true,consecutiveFailures:0}// 成功则重置}catch(error){constnextFailures=(tracking?.consecutiveFailures??0)+1if(nextFailures>=MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES){logForDebugging(`autocompact: circuit breaker tripped after${nextFailures}consecutive failures — skipping future attempts this session`)}return{wasCompacted:false,consecutiveFailures:nextFailures}}}

源码注释中记录了这一设计的数据驱动背景：

// BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures // (up to 3,272) in a single session, wasting ~250K API calls/day globally.

在引入熔断器之前，当上下文不可恢复地超出限制时，系统会在每个 turn 都尝试压缩，最多一个会话内连续失败 3,272 次，全局每天浪费约 25 万次 API 调用。熔断器将最大重试次数限制为 3 次。

三、多策略压缩

3.1 压缩优先级

autoCompactIfNeeded中的压缩策略有明确的优先级：

// 优先尝试会话记忆压缩constsessionMemoryResult=awaittrySessionMemoryCompaction(messages,toolUseContext.agentId,threshold)if(sessionMemoryResult){// 会话记忆压缩成功，跳过传统压缩return{wasCompacted:true,compactionResult:sessionMemoryResult}}// 回退到传统对话压缩constcompactionResult=awaitcompactConversation(messages,...)

会话记忆压缩优先于传统压缩，因为它基于记忆提取而非简单截断，能保留更多有价值的上下文信息。

3.2 传统压缩的预处理

compact.ts中的传统压缩在调用 API 之前会进行多步预处理：

// 剥离消息中的图片内容functionstripImagesFromMessages(messages:Message[]):Message[]{...}// 清理重复注入的附件functionstripReinjectedAttachments(messages:Message[]):Message[]{...}// 针对 prompt-too-long 错误的紧急头部截断functiontruncateHeadForPTLRetry(messages:Message[]):Message[]{...}

3.3 微压缩

microCompact.ts实现了缓存级别的细粒度压缩，维护了 pending 和 pinned 两个编辑队列：

functionconsumePendingCacheEdits():CacheEdit[]{...}functiongetPinnedCacheEdits():PinnedCacheEdits[]{...}functionpinCacheEdits(edits:CacheEdit[]):void{...}

微压缩在 API 请求层面操作，通过编辑缓存中的内容来减少 token 消耗，粒度比对话级压缩更细。

3.4 按轮次分组

grouping.ts将消息按 API 轮次分组，确保压缩时不会在一个轮次的中间截断：

functiongroupMessagesByApiRound(messages:Message[]):Message[][]{...}

四、Token 估算

tokenEstimation.ts提供了多层次的 token 计数策略，在精度和性能之间做了梯度权衡。

4.1 API 精确计数

asyncfunctioncountTokensWithAPI(messages,model,systemPrompt):Promise<number>{...}

调用 Claude API 的 token counting 端点，精度最高但有网络延迟。

4.2 Haiku 回退

asyncfunctioncountTokensViaHaikuFallback(messages,systemPrompt):Promise<number>{...}

当主模型不可用时，使用 Haiku 模型估算。Haiku 的 tokenizer 与主模型相近，但调用成本更低。

4.3 粗略估算

functionroughTokenCountEstimation(text:string):number{// 默认 4 bytes per token}functionbytesPerTokenForFileType(fileExtension:string):number{// 不同文件类型的 bytes-per-token 比率不同// 代码文件通常比自然语言文本有更高的 bytes-per-token}

粗略估算按字节数计算，并根据文件类型调整比率。这是最快的估算方式，用于不需要精确计数的场景。

4.4 Bedrock 计数

asyncfunctioncountTokensWithBedrock({messages,model}):Promise<number>{...}

针对 AWS Bedrock 部署的专用计数端点。

五、成本追踪

cost-tracker.ts实现了按模型的 token 用量和费用追踪。

5.1 核心功能

functionaddToTotalModelUsage(model,inputTokens,outputTokens){...}functionaddToTotalSessionCost(cost){...}functionformatModelUsage():string{...}// 格式化各模型用量functionformatTotalCost():string{...}// 格式化总费用functionformatCost(cost,maxDecimalPlaces):string{...}

5.2 会话恢复

functiongetStoredSessionCosts(sessionId):StoredCosts|null{...}functionrestoreCostStateForSession(sessionId):boolean{...}functionsaveCurrentSessionCosts(fpsMetrics?):void{...}

成本状态支持跨会话持久化和恢复，确保用户在恢复会话时能看到累计的费用统计。

六、Prompt Cache 感知

压缩系统与 prompt cache 机制紧密集成。每次压缩后都会通知 cache 检测系统：

if(feature('PROMPT_CACHE_BREAK_DETECTION')){notifyCompaction(querySource??'compact',toolUseContext.agentId)}

源码注释解释了这一设计的必要性：

// Reset cache read baseline so the post-compact drop isn't flagged // as a break. BQ 2026-03-01: missing this made 20% of // tengu_prompt_cache_break events false positives

压缩会导致 prompt cache 命中率下降，如果不重置基线，cache 监控系统会将这种正常下降误报为 cache 中断。在引入这一修复之前，20% 的 cache 中断告警是误报。

七、与其他系统的协同

7.1 与上下文折叠的互斥

当上下文折叠（Context Collapse）功能启用时，自动压缩会被禁用：

if(feature('CONTEXT_COLLAPSE')){const{isContextCollapseEnabled}=require('../contextCollapse/index.js')if(isContextCollapseEnabled())returnfalse}

源码注释详细解释了原因：上下文折叠在 90% 时提交、95% 时阻塞，而自动压缩在约 93% 时触发。两者会竞争，自动压缩通常先触发，会销毁折叠系统正在保存的细粒度上下文。

7.2 与会话记忆的协同

压缩完成后会重置会话记忆的状态：

// Reset lastSummarizedMessageId since compaction replaces all messages// and the old message UUID will no longer existsetLastSummarizedMessageId(undefined)

压缩会替换消息列表，旧的消息 UUID 不再存在，因此记忆系统的"上次总结位置"标记需要重置。