BUG 报告：compaction 反复压缩不可压缩 checkpoint 导致死循环

[myvivoyyx]

BUG 报告：compaction 反复压缩不可压缩 checkpoint 导致死循环

概要

项	值
严重程度	高
影响范围	所有触发自动 compaction 的长时间运行 session
触发条件	surface 头部存在 compaction checkpoint 节点，且整体 surface 超过 pressure 阈值
表现	单个 turn 内反复触发 compaction 几十次，全部失败，日志刷屏，session 最终在压缩过程中中断
根因	selectCompactableRange 不排除 checkpoint 节点 + pressure 路径无 summary 失败退避

问题现象

长时间运行的 agent session 在后期出现以下症状：

1. 日志中出现大量重复的 summary is not smaller than the shadowed content (1981 estimated framed tokens >= 1981) 错误
2. 单个 turn 内反复触发 compaction（20-28 次/turn），绝大多数失败
3. 偶尔成功一次（摘要恰好短了 1-3 个 token），但下一个 step 又触发，又失败
4. 最终 session 在 compaction/start 事件后中断，无对应 compaction/end（未闭合的压缩锁）

实际数据（来自真实 session 日志）

Session 概况

• session id: session-af3b7d70-f2e9-471a-86fc-a8dbe8ace5c1
• 工作目录: E:\code\xxxxx
• 模型路由: vcode-gateway / Ali-DeepSeek-V4-Flash-1m
• contextWindow: 262,144（256K，非名字暗示的 1M）
• 总事件: 33112 行，seq 到 240311
• turn 数: 119
• 文件结尾: 未闭合的 compaction/start（seq 240311），session 在压缩过程中中断

Compaction 事件统计

事件	次数
compaction/start	221
compaction/end	220
compaction/summary（成功落地）	19
失败（summary is not smaller）	198
失败（Request was aborted）	3

失败率 89.6%（221 次尝试仅 19 次成功）。

失败原因分布

失败原因	次数
summary is not smaller than the shadowed content	198
其中 framed == shadowed（完全相等）	180
其中 framed 仅比 shadowed 大 1-3 token	18
Request was aborted	3

180/198 次失败的 framed token 与 shadowed token 完全相等——摘要正文长度与原文几乎一致，framing 开销恰好抵消了仅有的缩短。

失败的 token 规模

198 次失败的 shadowedTokenCount 全部集中在 1981-2158 的极窄区间：

shadowed tokens	失败次数
2089	84
2084	17
1981	16
2073	16
2128	13
2019	12
2145	12
2137	11
1983	9
2158	3

被压缩区只有约 2000 token（按 4 字符/token 约 8000 字符），是一段小而密的结构化内容。

触发频率：turn 105 后飙升

turn	compaction/start 次数
19/52/79/99	各 1 次（正常）
105	15
109	26
113	27
116	28
119	22（未结束）

turn 105 之后，单个 turn 内反复触发压缩几十次。

无退避的连续失败

turn 119 尾部的事件序列（seq 几乎连续）：

238173  compaction/start
238174  compaction/end    FAIL
238930  compaction/start
238931  compaction/end    FAIL
239038  compaction/start
239039  compaction/end    FAIL
...
240311  compaction/start         ← session 在这里中断，无 end

start 和 end 的 seq 几乎连续，中间没有任何 step/tool 事件——同一个 region 被反复选中、反复尝试、反复失败，无任何退避。

关联错误：pi-ai detected context overflow

由于 compaction 失败导致 surface 无法缩减，input token 持续超过 contextWindow，触发 6 次 "pi-ai detected context overflow" 错误（turn 113-118）。

turn	input + cacheRead	contextWindow	超出
113	269,446	262,144	+7,302
114	273,041	262,144	+10,897
115	279,779	262,144	+17,635
116	291,217	262,144	+29,073
117	291,541	262,144	+29,397
118	295,610	262,144	+33,466

每次 overflow 后触发 context-overflow 恢复压缩，6 次全部失败（同样是 summary is not smaller），形成 overflow → 恢复压缩失败 → surface 不变 → 下一个 turn 又 overflow 的死循环。

根因分析

根因一：selectCompactableRange 不排除 checkpoint 节点

packages/compaction/compaction-basic/src/region.ts 的 selectCompactableRange 函数（第 98-134 行）从 surfaceNodes[0] 开始选可压缩区：

// 当前逻辑（有缺陷）
const first = surfaceNodes[0]!           // ← 总是从第一个节点开始
const cutoff = surfaceNodes[keepFromIdx - 1]!
return { start: first, end: cutoff }

它不检查 surfaceNodes[0] 是否是 compaction checkpoint。checkpoint 是 compactCheckpointSource 来源的 user/message，内容是 CHECKPOINT_PREAMBLE + <compacted-summary>...</compacted-summary>，是一段高度结构化的摘要，几乎不可再压缩。

isCompactCheckpointSource（packages/compaction/compaction/src/checkpoint.ts:49）已经存在，可以检测 checkpoint：

export function isCompactCheckpointSource(source: MessageSource): boolean {
  return source.kind === 'plugin' && source.plugin === 'compact'
}

但 selectCompactableRange 没有使用它。

死循环机制

从成功压缩的数据发现真相——每次压缩的都是前一次压缩产生的 checkpoint 消息本身：

成功压缩 seq	shadowedSeqs	shadowedTokens
228965	225123	2084
232539	228966	2073
232877	232540	2045
234738	232878	2019
237714	234739	1983

shadowedSeqs 是单个 seq，就是上一次 summary 的落地 user/message。token 值递减是因为偶尔压缩成功（摘要短了几个 token），产生一个新的稍小的 checkpoint，下一个 step 又尝试压缩这个新 checkpoint。

完整循环：

surface 超过 thresholdTokens
  → selectCompactableRange 从 surfaceNodes[0] 开始选可压缩区
  → surfaceNodes[0] 是上一次压缩产生的 checkpoint（~1981 token）
  → surface 只剩 checkpoint + 尾部 retainTokens 保留区
  → 可压缩区 = checkpoint 自己
  → compactRegion 对 checkpoint 做摘要
  → 摘要 framing 后的 token (1981) >= 原始 checkpoint token (1981)
    （checkpoint 本身就是结构化摘要，无法再压缩，
     framing 的 preamble + 标签开销抵消了仅有的缩短）
  → 断言失败，surface 不变
  → 下一个 step 又超阈值又选同一个 checkpoint 又失败
  → 无退避，循环往复

根因二：pressure 路径无 summary 失败退避

packages/compaction/compaction-basic/src/index.ts 的 agent/pre-step 监听器（第 147-165 行）每个 step 都跑一次 pressure 检查：

ctx.on('agent/pre-step', async ({ agent, signal }, next): Promise<PreStepDecision> => {
  if (!signal.aborted) {
    try {
      const result = await this.compactIfNeeded(agent, 'pressure', signal)
    } catch (error: unknown) {
      const message = error instanceof Error ? error.message : String(error)
      ctx.logger.warn(`step compaction failed: ${message}; continuing the turn`)
      // ← 只 warn 不阻断，不记录失败 region，不退避
    }
  }
  return next()
})

失败只 warn 不阻断，不记录哪个 region 失败过，不跳过失败的 region。下一个 step 又触发 agent/pre-step，又跑 pressure 检查，totalTokens 仍超阈值（surface 没变），selectCompactableRange 选出同一个 checkpoint，又失败。

对比 context-overflow 路径有 overflowRetries 计数器（WeakMap<Agent, number>），pressure 路径没有任何类似的退避机制。warnedPressureConfigTargets 只对 TargetPressureConfigError（配置错误）去重，对 summary is not smaller 这种普通 Error 不生效。

根因三：被压缩区过小

~2000 token 的 region 信息密集（结构化摘要），模型无法在保留必需事实的同时明显缩短。COMPACTION_INSTRUCTION 要求保留 "exact file paths, commands, error strings, identifiers, numeric values, function signatures"，对短而密的 checkpoint 而言，合规摘要几乎等于原文。

frameSummary() 的 framing 开销：

• CHECKPOINT_PREAMBLE：约 300 字符 ≈ 75 token
• <compacted-summary> 开闭合标签：约 40 字符 ≈ 10 token
• 两个 text block 的 BLOCK_OVERHEAD：4 + 4 = 8 token
• ROLE_OVERHEAD：4 token
• 合计约 97 token 的固定开销

摘要正文只要比原文短不到约 97 token 就会触发断言失败。对 1981 token 的 checkpoint，这是一个极窄的窗口。

根因四（配置层面）：contextWindow 配置缺失

settings.yaml 里 vcode-gateway 的模型只声明了 id 和 name，没有 contextWindow 字段，导致走 llm-pi-ai 的 DEFAULT_CONTEXT_WINDOW = 262_144（256K）默认值。模型名 Ali-DeepSeek-V4-Flash-1m 里的 "1m" 只是显示文本，DSH 不从名字解析容量。

这导致 thresholdTokens = floor(262144 × 0.8) = 209,715，session 后期 surface 容易超过这个阈值，频繁触发 pressure 压缩。

影响面

• 直接受影响：所有长时间运行、触发自动 compaction 且 surface 头部存在 checkpoint 的 session
• 间接受影响：compaction 失败导致 surface 无法缩减，进一步触发 context overflow，形成 overflow → 恢复压缩失败 → 又 overflow 的二级死循环
• 用户体验：日志刷屏、session 卡死、最终在压缩过程中中断
• 资源浪费：每次失败的 compaction 都调用一次 LLM summarization（真实模型请求），198 次失败 = 198 次无效 LLM 调用

建议修复方案

修复一：selectCompactableRange 跳过头部 checkpoint 节点（根因修复）

在 selectCompactableRange 确定保留尾部边界后、返回范围前，从头部向前跳过所有连续的 checkpoint 节点。使用已有的 isCompactCheckpointSource 检测 checkpoint。

// 修复后逻辑
let startIdx = 0
while (startIdx < keepFromIdx) {
  const seq = surfaceNodes[startIdx]
  const event = session.events[seq]
  const message = session.deriveEventMessage(event)
  if (message !== null && isCompactCheckpointSource(message.source)) {
    startIdx += 1
  } else {
    break
  }
}
if (startIdx >= keepFromIdx) return null  // 整个可压缩区都是 checkpoint
return { start: surfaceNodes[startIdx], end: surfaceNodes[keepFromIdx - 1] }

修复二：pressure 路径加 summary 失败退避（缓解）

在 compactIfNeeded 的 pressure 路径 for 循环里，compactRegion 抛出 summary is not smaller 错误时 break 而非继续重试。

修复三：给被压缩区设最小 token 门槛（缓解）

selectCompactableRange 加 minShadowedTokens 检查，选出的 region token 总量小于阈值（如 4000）时返回 null。

修复四：配置层面（用户侧）

在 settings.yaml 里给每个模型补上 contextWindow 字段，避免走 256K 默认值。1M 模型设为 1000000，其余按实际容量填写。

相关代码位置

文件	行	说明
packages/compaction/compaction-basic/src/region.ts	98-134	selectCompactableRange：不排除 checkpoint
packages/compaction/compaction-basic/src/region.ts	374-378	summary is not smaller 断言
packages/compaction/compaction-basic/src/region.ts	359-384	summarizeCompaction：framing 后比价
packages/compaction/compaction-basic/src/index.ts	147-165	agent/pre-step 监听器：每 step 触发，无退避
packages/compaction/compaction-basic/src/index.ts	315-326	pressure 路径重试循环
packages/compaction/compaction/src/checkpoint.ts	49-51	isCompactCheckpointSource：已存在但未被 region 使用
packages/compaction/compaction-basic/src/summarizer.ts	69-70	CHECKPOINT_PREAMBLE：约 300 字符固定开销
packages/compaction/compaction-basic/src/summarizer.ts	189-195	frameSummary：preamble + 标签 + summary
packages/llm/token-meter/src/estimate.ts	13-19	固定密度估算器：4 字符/token + block/role overhead
packages/llm/llm-pi-ai/src/config.ts	61	DEFAULT_CONTEXT_WINDOW = 262_144
packages/llm/llm-pi-ai/src/catalog.ts	851	contextWindow 三层 fallback

复现方法

1. 配置一个 contextWindow 较小的模型（如 262K）
2. 运行一个长时间 agent session，持续累积 surface 直到超过 thresholdTokens（contextWindow × 0.8）
3. 让 compaction 成功压缩一次大 region，产生一个 ~2000 token 的 checkpoint
4. 继续运行，surface 再次超过阈值
5. 观察 selectCompactableRange 反复选中 checkpoint，summary is not smaller 错误循环出现

[Jstn-1g]

Current-release update (2026-08-27): the same fix is now ported and reverified against official dsh-v0.1.2-alpha.1 (cd5ef814). Current branch: https://github.com/Jstn-1g/deepseek-harness/tree/reference/discussion-4776-checkpoint-only-alpha1 — exact commit: Jstn-1g@ae6eeab. On this baseline: 130/130 compaction tests, 100% affected-source coverage, full type-check/lint, 32/32 documentation gates, pairing, duplication, and pre-push checks passed. The original rc.2 receipt remains below for reproducibility.

Verified reference implementation for the reported checkpoint re-compaction loop (not an upstream merge).

Source baseline: b150a55
Reference branch: https://github.com/Jstn-1g/deepseek-harness/tree/reference/discussion-4776-checkpoint-only
Exact commit: Jstn-1g@3ad5b66

Implementation

• A derived compaction range containing no model-useful input, or exactly one existing compaction checkpoint, now declines before calling the summarizer.
• Two or more checkpoints can still consolidate, and a checkpoint followed by new ordinary history remains compactable; this avoids freezing future history behind an old checkpoint.
• Manual and context-overflow requests still pass the durable compaction-lock admission check before the early return.
• The change is intentionally local: no heuristic token floor, failed-region cache, or model-capacity inference was added.

Causal regression coverage

• Repeated pressure checks against a lone checkpoint make zero summarizer calls and append zero compaction events.
• Removing the guard reproduces the original non-shrinking failure (106 >= 106).
• Two checkpoints consolidate in one call.
• Checkpoint plus ordinary history compacts normally.
• Checkpoint plus an empty assistant surface node declines.
• The existing manual lock case and a new context-overflow lock case verify that admission semantics are preserved.

Verification

• Complete compaction-basic suite: 127/127 tests passed.
• Affected implementation files (index.ts and region.ts): 100% statements, branches, functions, and lines.
• Full repository type-check and lint passed.
• Documentation gates: 28/28; translation pairing, agent-note format, and diff/precommit checks passed.

Scope

• This prevents the repeated summarization of one already-compacted checkpoint while retaining legitimate cumulative compaction.
• It does not repair previously damaged session history or synthesize a missing compaction/end, and it does not change model contextWindow configuration.

[fan56]

从「压缩手段反复失败→反复重压」这层看，有一个绕法：dsh-dcp 用确定性代码抽取替换「让模型总结」这一环（压缩零 LLM 调用），同样的输入永远得到同样的检查点，不存在「摘要无用→再来一轮」的失败模式，一次成活。触发/保留/事务锁继承官方，检查点格式兼容：

dsh plugin add @aiwayds/dsh-dcp

边界说明：你观察到的「不可压缩 checkpoint 被反复压缩」如果根因在 checkpoint 语义层（比如保留尾巴本身构成了环），那是另一层问题，dcp 解决的是「摘要这一环反复失败」；建议两个层面分开验证。