4.5 Compaction：上下文窗口管理

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2025-02-17

---

Compaction（上下文压缩）是 OpenCode 中解决 LLM 上下文窗口限制的关键机制。当对话历史过长时，Compaction 会自动清理旧内容，确保对话可以持续进行。

4.5.1 为什么需要 Compaction？

衍生概念：LLM 的上下文窗口（Context Window）

每个 LLM 都有一个上下文窗口限制——它在一次请求中能处理的最大 token 数。例如：

模型	上下文窗口
Claude Sonnet	200,000 tokens
GPT-4o	128,000 tokens
Gemini Pro	2,000,000 tokens

在 Agentic Coding 场景中，上下文很容易被填满：

• System Prompt：~2,000 tokens

• AGENTS.md 指令：~1,000-5,000 tokens

• 每轮对话的消息：~500-2,000 tokens

• 每次工具调用的输出：~500-50,000 tokens（读取大文件时可能很大）

一次 10 轮的 Agent 对话，可能就消耗 50,000+ tokens。当累计 token 超过上下文窗口时，LLM 会拒绝请求或产生错误。

Compaction 的目标就是：在不丢失关键信息的前提下，压缩对话历史以腾出上下文空间。

4.5.2 溢出检测算法：isOverflow()

SessionCompaction.isOverflow() 判断当前对话是否即将超出上下文窗口：

const COMPACTION_BUFFER = 20_000  // 预留 20K tokens 的缓冲区

export async function isOverflow(input: {
  tokens: MessageV2.Assistant["tokens"]
  model: Provider.Model
}) {
  const config = await Config.get()
  if (config.compaction?.auto === false) return false  // 用户关闭了自动压缩

  const context = input.model.limit.context
  if (context === 0) return false  // 模型没有上下文限制

  // 计算当前已用 token 数
  const count = input.tokens.total ||
    input.tokens.input + input.tokens.output +
    input.tokens.cache.read + input.tokens.cache.write

  // 计算可用空间 = 输入限制 - 预留缓冲
  const reserved = config.compaction?.reserved ??
    Math.min(COMPACTION_BUFFER, ProviderTransform.maxOutputTokens(input.model))
  const usable = input.model.limit.input
    ? input.model.limit.input - reserved
    : context - reserved

  return count >= usable
}

关键参数：

• COMPACTION_BUFFER = 20,000：在上下文窗口末尾预留 20K tokens 的缓冲区。这确保即使检测到溢出，也还有足够的空间让 LLM 生成最后的回复和压缩摘要。

• reserved：实际预留空间。取 COMPACTION_BUFFER 和模型最大输出 token 的较小值。

4.5.3 Prune 策略：工具输出的渐进式清理

在触发完整的 Compaction 之前，OpenCode 会先尝试 Prune（修剪）——一种更轻量的清理方式：

export const PRUNE_MINIMUM = 20_000   // 至少清理 20K tokens
export const PRUNE_PROTECT = 40_000   // 保护最近 40K tokens 的工具输出
const PRUNE_PROTECTED_TOOLS = ["skill"] // skill 工具的输出永不清理

export async function prune(input: { sessionID: string }) {
  const config = await Config.get()
  if (config.compaction?.prune === false) return

  const msgs = await Session.messages({ sessionID: input.sessionID })
  let total = 0
  let turns = 0

  // 从最新消息往前遍历
  loop: for (let msgIndex = msgs.length - 1; msgIndex >= 0; msgIndex--) {
    const msg = msgs[msgIndex]
    if (msg.info.role === "user") turns++
    if (turns < 2) continue          // 保护最近 2 轮对话
    if (msg.info.role === "assistant" && msg.info.summary) break  // 遇到摘要停止

    for (let partIndex = msg.parts.length - 1; partIndex >= 0; partIndex--) {
      const part = msg.parts[partIndex]
      if (part.type === "tool" && part.state.status === "completed") {
        if (PRUNE_PROTECTED_TOOLS.includes(part.tool)) continue

        const estimate = Token.estimate(part.state.output)
        total += estimate

        if (total > PRUNE_PROTECT) {
          // 超过保护区后的工具输出 → 标记为需要清理
          toPrune.push(part)
        }
      }
    }
  }

  // 执行清理：将旧工具输出替换为 "[truncated]"
  for (const part of toPrune) {
    await Session.updatePart({
      ...part,
      state: {
        ...part.state,
        output: "[output truncated by compaction]",
        time: { ...part.state.time, compacted: Date.now() },
      },
    })
  }
}

Prune 算法的核心思想：

1. 从后往前遍历消息历史

2. 保护最近 2 轮对话的所有内容

3. 保护最近 40K tokens 的工具输出

4. 超过保护区的旧工具输出 → 替换为 "[output truncated by compaction]"

5. skill 工具的输出永不清理（因为 Skill 内容对后续行为至关重要）

这种策略的直觉是：旧的工具输出（比如 10 轮前读取的文件内容）很可能已经不再相关，可以安全丢弃；而最近的工具输出仍然是当前推理的依据，必须保留。

4.5.4 Compaction 执行流程

如果 Prune 后空间仍不够，就会触发完整的 Compaction——用 LLM 生成一段摘要来替代旧的消息历史：

Compaction 前：
┌──────────────────────────────────────────┐
│ System Prompt                            │
│ User Msg 1                               │
│ Assistant Msg 1 (含工具调用)              │  ← 这些会被摘要替代
│ User Msg 2                               │
│ Assistant Msg 2 (含工具调用)              │
│ User Msg 3                               │
│ Assistant Msg 3 (当前)                    │  ← 保留
└──────────────────────────────────────────┘

Compaction 后：
┌──────────────────────────────────────────┐
│ System Prompt                            │
│ [Compaction Summary]                     │  ← 由 LLM 生成的摘要
│ "之前的对话摘要：用户要求实现排序函数，    │
│  我已完成 quicksort 实现并通过测试..."    │
│ User Msg 3                               │  ← 保留最近的对话
│ Assistant Msg 3 (当前)                    │
└──────────────────────────────────────────┘

Compaction 使用的 Prompt 模板在 agent/prompt/compaction.txt 中定义。

4.5.5 Token 估算工具

由于精确的 token 计数需要使用模型的 tokenizer（分词器），OpenCode 在某些场景下使用快速估算：

// util/token.ts
export function estimate(text: string): number {
  // 粗略估算：每 4 个字符约 1 个 token
  return Math.ceil(text.length / 4)
}

这个估算值不需要精确——它只用于 Prune 策略中判断"大约"清理了多少 token。而精确的 token 数来自 LLM Provider 的响应元数据（usage 字段）。