Context Window Auto-Compaction

Clawdbot Contributors· validated-in-production

问题

上下文（Context）溢出是侵蚀Agent可靠性的隐形杀手。当累积的对话历史超出模型的上下文窗口（context window）时，会引发以下问题：

API错误：请求因context_length_exceeded或类似错误而失败
人工干预需求：运维人员必须截断对话记录，导致宝贵的Context丢失
重试复杂性：检测溢出并通过压缩方式重试的过程极易出错

Agent需具备自动压缩功能，在令牌（token）限额内保留核心信息，同时结合模型专属校验机制与预留令牌下限，以防止溢出问题立即再次发生。

方案

由上下文溢出错误触发的自动会话压缩机制，具备智能预留令牌和队列感知重试能力。系统会自动检测溢出、压缩会话记录、验证结果并重试请求——所有操作对用户完全透明。

核心概念：

溢出检测：捕获表明上下文长度超出的API错误（如context_length_exceeded、prompt过长等）。
带压缩的自动重试：发生溢出时，系统会自动压缩会话并重试请求。
预留令牌下限：压缩后确保剩余令牌不低于最小数量（默认20k），避免立即再次出现溢出。
队列感知压缩：采用分层队列（会话→全局）机制，防止压缩过程中出现死锁。
压缩后验证：估算压缩后的令牌数量，确认其小于压缩前的令牌数。
模型专属验证：Anthropic模型要求严格的轮次顺序；Gemini模型则有不同的会话记录格式要求。

实现草图：

async function compactEmbeddedPiSession(params: {
  sessionFile: string;
  config?: Config;
}): Promise<CompactResult> {
  // 1. 加载会话并配置预留令牌
  const sessionManager = SessionManager.open(params.sessionFile);
  const settingsManager = SettingsManager.create(workspaceDir, agentDir);

  // 确保满足最低预留令牌要求（默认20k）
  ensurePiCompactionReserveTokens({
    settingsManager,
    minReserveTokens: resolveCompactionReserveTokensFloor(params.config),
  });

  // 2. 针对模型API清理会话历史
  const prior = sanitizeSessionHistory({
    messages: session.messages,
    modelApi: model.api,
    modelId,
    provider,
    sessionManager,
  });

  // 3. 执行模型专属验证
  const validated = provider === "anthropic"
    ? validateAnthropicTurns(prior)
    : validateGeminiTurns(prior);

  // 4. 压缩会话
  const result = await session.compact(customInstructions);

  // 5. 估算压缩后的令牌数量
  let tokensAfter: number | undefined;
  try {
    tokensAfter = 0;
    for (const message of session.messages) {
      tokensAfter += estimateTokens(message);
    }
    // 合理性检查：压缩后令牌数必须小于压缩前
    if (tokensAfter > result.tokensBefore) {
      tokensAfter = undefined;  // 不采信该估算结果
    }
  } catch {
    tokensAfter = undefined;
  }

  return {
    ok: true,
    compacted: true,
    result: {
      summary: result.summary,
      tokensBefore: result.tokensBefore,
      tokensAfter,
    },
  };
}

预留令牌强制机制：

const DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR = 20_000;

function ensurePiCompactionReserveTokens(params: {
  settingsManager: SettingsManager;
  minReserveTokens?: number;
}): { didOverride: boolean; reserveTokens: number } {
  const minReserveTokens = params.minReserveTokens ?? DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR;
  const current = params.settingsManager.getCompactionReserveTokens();

  if (current >= minReserveTokens) {
    return { didOverride: false, reserveTokens: current };
  }

  // 覆盖配置以确保满足最低令牌下限
  params.settingsManager.applyOverrides({
    compaction: { reserveTokens: minReserveTokens },
  });

  return { didOverride: true, reserveTokens: minReserveTokens };
}

基于API的压缩（OpenAI Responses API）： 部分服务商提供了专用的压缩端点，效率优于手动摘要：

// OpenAI的/responses/compact端点
const compacted = await responsesAPI.compact({
  messages: currentMessages,
});

// 返回结果包含以下类型的条目：
// - 特殊type=compaction的条目，带有encrypted_content字段
//   用于保留模型对原始对话的潜在理解
// - 精简后的对话条目

currentMessages = compacted.items;

该方案具备以下优势：

保留潜在理解：encrypted_content字段会保存模型对原始对话的压缩表示
效率更高：服务端压缩速度快于客户端本地摘要
自动触发压缩：当超出auto_compact_limit阈值时可自动触发压缩

队列感知重试（防止死锁）：

// 压缩流程先经过会话队列，再进入全局队列
async function compactEmbeddedPiSession(params: CompactParams): Promise<CompactResult> {
  const sessionLane = resolveSessionLane(params.sessionKey);
  const globalLane = resolveGlobalLane(params.lane);

  return enqueueCommandInLane(sessionLane, () =>
    enqueueCommandInLane(globalLane, () =>
      compactEmbeddedPiSessionDirect(params)  // 核心压缩逻辑
    )
  );
}