触发与位置

每次模型请求前，query.ts 的治理顺序是：

Tool Result Budget → History Snip → Microcompact → Context Collapse → AutoCompact → 主模型 API 调用

见 query.ts:L396-L468。

queryCheckpoint
const { compactionResult,consecutiveFailures } = await deps.autocompact(
messagesForQuery,toolUseContext,{
systemPrompt,userContext,systemContext。toolUseContext,forkContextMessages: messagesForQuery,},querySource,tracking,snipTokensFreed,)
queryCheckpoint

这代表着 AutoCompact 看到的 messagesForQuery 已经是前面几种治理机制处理后的模型视图。老实说，若你在调试时发现上下文被过度压缩，先检查这一步骤是否已执行。

从设计意图来看，优先信息保留

优先使用信息损失更小的手段：

工具结果替换 / Snip / Microcompact / Context Collapse
| | 如果已经降到阈值以下
v v
AutoCompact 不再执行 | 如果仍然超过阈值
v v
AutoCompact 生成摘要

Context Collapse 特别被安排在 AutoCompact 之前。因为源码希望尽量保留粒度更细的上下文，而不是过早把全部历史压成一条摘要。话说回来，若你发现上下文被过度聚合。请确认 Context Collapse 是否已启用。

阈值设计

再看先看代码，

// Reserve this many tokens for output during compaction
// Based on p99. of compact summary output being,tokens.
const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000
// Returns context window size minus max output tokens for model
export function getEffectiveContextWindowSize: number {
const reservedTokensForSummary = Math.min(
getMaxOutputTokensForModel,MAX_OUTPUT_TOKENS_FOR_SUMMARY。)
let contextWindow = getContextWindowForModel)
const autoCompactWindow = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW
if {
const parsed = parseInt
if && parsed> ) {
contextWindow = Math.min
}
}
return contextWindow - reservedTokensForSummary
}
export type AutoCompactTrackingState = {
compacted: boolean
turnCounter: number // Unique ID per turn
说到turnId，string // Consecutive autocompact failures. Reset on success.
// Used as a circuit breaker to stop retrying when context is irrecoverably over limit .
consecutiveFailures?: number}
export const AUTOCOMPACT_BUFFER_TOKENS = 13_000
export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000
export const ERROR_THRESHOLD_BUFFER_TOKENS = 20_000
export const MANUAL_COMPACT_BUFFER_TOKENS = 3_000
// Stop trying autocompact after this many consecutive failures.
// BQ --:,sessions had + consecutive failures
// in a single session。wasting ~250K API calls/day globally.
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES =
export function getAutoCompactThreshold: number {
const effectiveContextWindow = getEffectiveContextWindowSize
const autocompactThreshold =
effectiveContextWindow - AUTOCOMPACT_BUFFER_TOKENS // Override for easier testing of autocompact
const envPercent = process.env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
if {
const parsed = parseFloat
if && parsed> && parsed <= ) {
      const percentageThreshold =
        Math.floor)
         return Math.min
    }
  }
  return autocompactThreshold}

autoCompact 的阈值为 “有效 - 13 K buffer”。

有效窗口还预留了最多 20 K token 给“生成摘要的模型输出”，避免摘要请求自己溢出。见 autoCompact.ts:L28-L90。

shouldAutoCompact 判断逻辑

export async function shouldAutoCompact(
messages: Message。model: string,querySource?: QuerySource,snipTokensFreed =
): Promise {
// Recursion guards. session_memory and compact are forked agents that would deadlock.
if { return false }
// marble_origami is ctx-agent — if ITS context blows up and autocompact fires。
// runPostCompactCleanup calls resetContextCollapse which destroys MAIN thread's committed log.
if ) {
if { return false }
}
if ) { return false }
// Reactive-only mode:
if ) {
if (
getFeatureValue_CACHED_MAY_BE_STALE
) { return false }
}
// Context-collapse mode suppression logic…if ) {
/* eslint-disable @typescript-eslint/no-require-imports */
const { isContextCollapseEnabled } =
require as typeof import
/* eslint-enable @typescript-eslint/no-require-imports */
if ) { return false }
}
const tokenCount =
tokenCountWithEstimation - snipTokensFreed
const threshold = getAutoCompactThreshold
const effectiveWindow =
getEffectiveContextWindowSize
logForDebugging(
`autocompact: tokens=${tokenCount} threshold=${threshold} effectiveWindow=${effectiveWindow}${snipTokensFreed>?` snipFreed=${snipTokensFreed}` : ''}`,)
const { isAboveAutoCompactThreshold } =
calculateTokenWarningState
return isAboveAutoCompac…}

This function will skip auto‑compact in several situations:

• User‑configured off: If you set CLOUDE_CODE_AUTO_COMPACT_ENABLED=false。auto‑compact never runs.
• Syntic agents: If you are inside a sub‑agent or a marbled ctx‑agent it returns false.
• Noisy contexts: If Context Collapse or Reactive Compact modes are active it defers to those mechanisms.
• Circuit breaker: If re have been too many consecutive failures it stops trying.
• Error threshold reached: If your message count already exceeds pre‑computed threshold it won’t attempt anor compaction round.

痛点提炼的观点是，为什么你会关心这些细节？

• 上下文丢失风险： 如果 AutoCompact 被误触发，可能会把关键细节删掉。了解它何时被调用能帮助你定位丢失原因。
• 性能瓶颈： 频繁的自动压缩会导致额外 API 调用和计算开销。掌握阈值与配置可让你在性能与完整性之间做平衡。
• 调试难题： 当查询失败或提示“prompt_too_long”时你需要知道到底是哪一步触发了压缩，以便调整输入或 策略。
• 自定义策略冲突： 不同治理机制互斥。明白它们的优先级可以避免无谓的覆盖或重叠，例如手动/自动压缩同时开启导致两次不必要的。
• 可配置性不清晰： 环境变量和功能开关决定了行为，但其命名略显混乱。通过阅读上述代码，你可以快速定位并修改对应变量。如 CLOUDE_CODE_AUTO_COMPACT_ENABLED、CLOUDE_CONTEXT_COLLAPSE 等等。