深入解析OpenClaw上下文窗口压缩方案 ：一切都是为了效果与省钱

┌────────────────────────┐  ┌─────────────────────┐  ┌──────────────────────────┐
│   LLM 调用前（预防）     │  │  LLM 调用中（自动）   │  │   LLM 调用后（溢出恢复）   │
│                        │  │                     │  │                          │
│ 1. History Turn Limit  │  │ 3. SDK 自动          │  │ 5. Overflow 错误检测      │
│ 2. Context Pruning     │  │    Compaction        │  │ 6. 显式 Compaction       │
│    (Tool Result 裁剪)  │  │                     │  │ 7. 超大 Tool Result 截断  │
│                        │  │                     │  │ 8. 重试 / 放弃           │
└────────────────────────┘  └─────────────────────┘  └──────────────────────────┘

export function limitHistoryTurns(
  messages: AgentMessage[],
  limit: number | undefined,
): AgentMessage[] {
  if (!limit || limit <= 0 || messages.length === 0) {
    return messages;
  }
  let userCount = 0;
  let lastUserIndex = messages.length;
  for (let i = messages.length - 1; i >= 0; i--) {
    if (messages[i].role === "user") {
      userCount++;
      if (userCount > limit) {
        return messages.slice(lastUserIndex);
      }
      lastUserIndex = i;
    }
  }
  return messages;
}

per-DM 用户级别覆盖
  → channels.*.dms[userId].historyLimit
provider 级别 DM 默认
  → channels.*.dmHistoryLimit
provider 级别群组/频道默认
  → channels.*.historyLimit

// extension.ts
if (runtime.settings.mode === "cache-ttl") {
  const ttlMs = runtime.settings.ttlMs;
  const lastTouch = runtime.lastCacheTouchAt ?? null;
  if (!lastTouch || ttlMs <= 0) return undefined;
  if (ttlMs > 0 && Date.now() - lastTouch < ttlMs) return undefined;
}

function softTrimToolResultMessage(params) {
  const parts = collectTextSegments(msg.content);
  const rawLen = estimateJoinedTextLength(parts);
  if (rawLen <= settings.softTrim.maxChars) return null;
  
  const head = takeHeadFromJoinedText(parts, headChars);
  const tail = takeTailFromJoinedText(parts, tailChars);
  const trimmed = `${head}\n...\n${tail}`;
  const note = `\n\n[Tool result trimmed: kept first ${headChars} chars and last ${tailChars} chars of ${rawLen} chars.]`;
  return { ...msg, content: [asText(trimmed + note)] };
}

// settings.ts
{
  mode: "cache-ttl",
  ttlMs: 5 * 60 * 1000,          // 5 分钟缓存 TTL
  keepLastAssistants: 3,          // 保护最近 3 条 assistant 消息的 tool results
  softTrimRatio: 0.3,             // 总字符占比 > 30% 时触发 soft trim
  hardClearRatio: 0.5,            // 总字符占比 > 50% 时触发 hard clear
  minPrunableToolChars: 50_000,   // hard clear 前需要可裁剪 tool result ≥ 50K 字符
  softTrim: {
    maxChars: 4_000,              // tool result 超过 4K 字符才触发 soft trim
    headChars: 1_500,             // 保留首 1500 字符
    tailChars: 1_500,             // 保留尾 1500 字符
  },
  hardClear: {
    enabled: true,
    placeholder: "[Old tool result content cleared]",
  },
}

MAX_TOOL_RESULT_CONTEXT_SHARE = 0.3   // 单条 tool result 最多占上下文窗口的 30%
HARD_MAX_TOOL_RESULT_CHARS = 400_000  // 绝对上限 400K 字符（约 100K tokens）
MIN_KEEP_CHARS = 2_000                // 截断时至少保留前 2000 字符

export function calculateMaxToolResultChars(contextWindowTokens: number): number {
  const maxTokens = Math.floor(contextWindowTokens * MAX_TOOL_RESULT_CONTEXT_SHARE);
  const maxChars = maxTokens * 4;  // 1 token ≈ 4 chars 估算
  return Math.min(maxChars, HARD_MAX_TOOL_RESULT_CHARS);
}

export function truncateToolResultText(text, maxChars, options) {
  const keepChars = Math.max(minKeepChars, maxChars - suffix.length);
  let cutPoint = keepChars;
  // 尝试在 80% 范围内找到最近的换行符
  const lastNewline = text.lastIndexOf("\n", keepChars);
  if (lastNewline > keepChars * 0.8) {
    cutPoint = lastNewline;
  }
  return text.slice(0, cutPoint) + suffix;
}

⚠️ [Content truncated — original was too large for the model's context window.
The content above is a partial view. If you need more, request specific sections
or use offset/limit parameters to read smaller chunks.]

// truncateToolResultMessage() 中
const blockShare = textBlock.text.length / totalTextChars;
const blockBudget = Math.max(
  minKeepChars + suffix.length,
  Math.floor(maxChars * blockShare),
);

session_before_compact 事件触发
    │
    ├── 1. 前置检查
    │     ├── 解析 model（ctx.model → fallback runtime.model）
    │     └── 获取 API key → 任一缺失则 cancel，保留原始历史
    │
    ├── 2. 收集元数据
    │     ├── 文件操作记录：read/edited/written → readFiles + modifiedFiles
    │     └── 工具失败记录：最多 8 条，每条 ≤ 240 字符
    │
    ├── 3. 历史预裁剪（可选）
    │     └── 当新内容 > maxHistoryShare(50%) 的上下文窗口时
    │           ├── 丢弃最老的 chunk
    │           ├── 修复 tool_use/tool_result 配对
    │           └── 对被丢弃消息单独做摘要 → droppedSummary
    │
    ├── 4. 分段摘要（summarizeInStages）
    │     └── messagesToSummarize → chunks → per-chunk 摘要 → 合并
    │
    ├── 5. Split Turn 处理（可选）
    │     └── 如果是分裂轮次，额外摘要 turnPrefixMessages
    │
    └── 6. 组装最终 summary
          ├── 对话摘要文本
          ├── Tool Failures 列表
          ├── <read-files> / <modified-files> 文件操作
          └── <workspace-critical-rules> AGENTS.md 关键规则

消息列表
  → splitMessagesByTokenShare (按 token 均分为 N 个 chunk)
  → 逐 chunk 调用 summarizeWithFallback 生成摘要
  → 如果产生多个 partial summaries
      → 将各摘要作为 user 消息送入 LLM 做合并摘要
      → 使用 MERGE_SUMMARIES_INSTRUCTIONS 指导合并

const DEFAULT_PARTS = 2;                     // 默认分 2 段
const BASE_CHUNK_RATIO = 0.4;               // 每个 chunk 最多占上下文窗口的 40%
const MIN_CHUNK_RATIO = 0.15;               // 最小 15%
const SAFETY_MARGIN = 1.2;                  // 20% 安全裕量
const SUMMARIZATION_OVERHEAD_TOKENS = 4096;  // 预留 4096 tokens 给摘要 prompt 本身

export function computeAdaptiveChunkRatio(messages, contextWindow) {
  const avgTokens = totalTokens / messages.length;
  const safeAvgTokens = avgTokens * SAFETY_MARGIN;  // 乘以 1.2 安全系数
  const avgRatio = safeAvgTokens / contextWindow;

  // 当平均消息大小 > 上下文窗口的 10% 时，开始缩小
  if (avgRatio > 0.1) {
    const reduction = Math.min(avgRatio * 2, BASE_CHUNK_RATIO - MIN_CHUNK_RATIO);
    return Math.max(MIN_CHUNK_RATIO, BASE_CHUNK_RATIO - reduction);
  }
  return BASE_CHUNK_RATIO;  // 默认 0.4
}

Level 1: 尝试全量摘要
  ↓ 失败（超时/溢出/API 错误）
Level 2: 剔除超大消息（单条 > 50% 上下文窗口），只摘要剩余小消息
         + 追加 "[Large assistant (~150K tokens) omitted from summary]" 标注
  ↓ 仍然失败
Level 3: 返回兜底文本
         "Context contained N messages (M oversized). Summary unavailable due to size limits."

summary = await retryAsync(
  () => generateSummary(chunk, model, reserveTokens, apiKey, signal, customInstructions, summary),
  {
    attempts: 3,
    minDelayMs: 500,
    maxDelayMs: 5000,
    jitter: 0.2,
    label: "compaction/generateSummary",
    shouldRetry: (err) => !(err instanceof Error && err.name === "AbortError"),
  },
);

1. 计算 budgetTokens = contextWindowTokens × maxHistoryShare
2. while (消息总 token > budgetTokens):
     a. 将消息按 token 均分为 N 段（默认 2）
     b. 丢弃第一个（最老的）chunk
     c. 调用 repairToolUseResultPairing 修复孤立的 tool_result
     d. 统计丢弃量
3. 对所有被丢弃的消息做单独摘要 → droppedSummary
4. droppedSummary 作为 previousSummary 传递给后续的主摘要流程

[对话摘要文本]

## Tool Failures                          ← 工具失败记录（最多 8 条）
- bash (exitCode=1): command not found...
- read_file (status=error): file too large

<read-files>                              ← 已读文件列表
src/foo.ts
src/bar.ts
</read-files>

<modified-files>                          ← 已修改文件列表
src/baz.ts
</modified-files>

<workspace-critical-rules>                ← AGENTS.md 中的关键规则
...Session Startup / Red Lines 内容...     （限制 ≤ 2000 字符）
</workspace-critical-rules>

永远不将 toolResult.details 送入 LLM 做摘要。details 可能包含不可信的 payload（如外部 API 返回的原始数据），防止 prompt injection

检测到 context overflow 错误
    │
    ├── 分支 A: 本次 attempt 内 SDK 已自动 compaction？
    │     └── 是 → 增加 overflowCompactionAttempts 计数
    │           └── 直接重试 prompt（不再额外 compact，避免重复压缩）
    │
    ├── 分支 B: 本次 attempt 内无 auto-compact？
    │     └── overflowCompactionAttempts < 3？
    │           ├── 是 → 执行显式 compaction（trigger: "overflow"）
    │           │     ├── 成功 → 重试 prompt
    │           │     └── 失败 → 进入 Fallback
    │           └── 否 → 进入 Fallback
    │
    ├── Fallback: 检测是否有超大 tool result
    │     └── sessionLikelyHasOversizedToolResults()
    │           ├── 有 → truncateOversizedToolResultsInSession()
    │           │     ├── 截断成功 → 重试 prompt
    │           │     └── 截断无效 → 放弃
    │           └── 无 → 放弃
    │
    └── 所有手段用尽 → 返回错误：
          "Context overflow: prompt too large for the model.
           Try /reset (or /new) to start a fresh session,
           or use a larger-context model."

const effectiveMax = Math.max(1, Math.floor(maxTokens / SAFETY_MARGIN));

const maxHistoryTokens = Math.floor(contextWindowTokens * maxHistoryShare * SAFETY_MARGIN);

                    ┌─────────────────────────────────┐
                    │   用户消息进入会话                 │
                    └────────────┬────────────────────┘
                                 │
                    ┌────────────▼────────────────────┐
                    │  History Turn Limit              │  ← 最简粗粒度截断
                    │  (只保留最近 N 轮用户对话)         │
                    └────────────┬────────────────────┘
                                 │
                    ┌────────────▼────────────────────┐
                    │  Context Pruning (soft/hard)     │  ← 渐进式裁剪旧 tool results
                    │  - Soft: 保留 head+tail          │     5 分钟 TTL 节流
                    │  - Hard: 替换为占位符             │     ratio 阈值 0.3/0.5
                    └────────────┬────────────────────┘
                                 │
                    ┌────────────▼────────────────────┐
                    │  单条 Tool Result 截断            │  ← 内存级预防守卫
                    │  (单条 ≤ 30% 上下文窗口)          │     ≤ 400K 字符硬顶
                    └────────────┬────────────────────┘
                                 │
                    ┌────────────▼────────────────────┐
                    │  发送给 LLM                      │
                    └────────────┬────────────────────┘
                                 │
                         成功 ◄──┤──► 溢出错误
                                 │
                    ┌────────────▼────────────────────┐
                    │  Compaction（LLM 生成摘要）       │
                    │  1. 自适应 chunk 大小             │
                    │  2. 分段摘要 + 摘要合并           │
                    │  3. 超大消息三级降级              │
                    │  4. 附加文件操作 + 工具失败信息    │
                    │  5. 附加工作区关键规则             │
                    │  6. 修复 tool_use/result 配对    │
                    └────────────┬────────────────────┘
                                 │
                         成功 ◄──┤──► 仍然溢出？
                                 │
                    ┌────────────▼────────────────────┐
                    │  截断超大 Tool Results            │  ← 最后手段
                    │  (持久级修改 session 文件)         │     通过 branching 重写
                    └────────────┬────────────────────┘
                                 │
                          成功 ◄─┤─► 放弃（提示用户 /reset）

// Context Pruning 默认 TTL
ttlMs: 5 * 60 * 1000  // 5 分钟

// Anthropic cache retention 默认
cacheRetention: "short"  // 5 分钟