[Feature Request] Prompt Cache 稳定性 / 批量 rollover 压缩（主杠杆）

[ranxianglei]

背景

#80 提出、#240 讨论确认：压缩的真实成本里，"写摘要的 output tokens" 只是小头，大头是 Prompt Cache 失效——selective compression 在历史中间就地改写，把压缩点之后的整个后缀踢出缓存前缀，后续每轮按全价重算这段 input。

#240 的独立压缩模型（/acp compact，含 session 共享前缀模式，见 PR #241）只解决了"隔离 + 摘要 output"，没动缓存失效。本 issue 做主杠杆：保护 Prompt Cache。

目标

把"频繁就地压缩"变成"偶发批量 rollover"，让 model-visible history 在阶段内尽量 append-only，缓存失效次数大幅下降。

方案要点（待细化）

1. 阶段内 append-only：一个阶段（任务 / 到上下文阈值）内，model-visible history 只追加、不改中间。
2. pending drop 标记：可删的 tool output 先标记 pending drop（对模型隐藏但不立即从 prompt 移除），避免每次删除都改前缀。
3. 批量 rollover：到上下文压力高 / 阶段结束时，一次性批量压缩 + 删除（一次缓存失效，摊薄到整个阶段）。
4. 检索结果追加到尾部：decompress / search 结果追加到上下文尾部，不插回原位置。

关键设计问题（需先对齐）

• pending drop 与缓存前缀的矛盾：如果"隐藏"= 立即从 prompt 移除，那本身就会改前缀、触发缓存失效，与目标矛盾。所以 pending drop 更可能是"延迟到 rollover 才真正移除"（阶段内先留着、占一点 context，换缓存稳定）。这个 trade-off 需要定量化：缓存省的钱 vs 临时多占的 context。
• rollover 触发条件：上下文压力阈值？阶段边界如何判定？
• 与 # [Feature Request] 新增 /acp compact 命令，复用 models.json 实现协同压缩 #240 独立压缩模型的关系：两者正交、可组合（批量 rollover 发生时，摘要生成可以甩给独立模型 /acp compact）。

验收标准

• 阶段内 model-visible history append-only（不就地改中间）。
• pending drop 机制：可删内容标记 + 延迟到 rollover 移除。
• 批量 rollover：压力高 / 阶段结束时一次性压缩 + 删除。
• decompress / search 结果追加到尾部。
• 单元测试：验证缓存前缀稳定性（rollover 前后前缀一致）。
• 文档更新（README + CONFIGURATION）。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 设计对齐 + 实现计划

一、pending drop 的矛盾：按你的猜测收敛

"隐藏" ≠ "从 prompt 移除"。pending drop = 标记 + 延迟到 rollover 才真正移除：阶段内内容留在 prompt 里（占一点 context），换缓存稳定。量化 trade-off：

• 缓存失效成本 ≈ 全价 × 压缩点之后的后缀长度（下一轮整个后缀按全价重算）。注意：与后缀长度成正比，不是与被删内容长度成正比。
• 保留 pending 内容的成本 ≈ cache-read 价 × 自身长度 × 到 rollover 的轮数（它在稳定前缀内，按 cache-read 计费）。
• 例（Claude 价：input $3/M、cache read $0.30/M）：一个 20K 的 tool output，其后有 60K 后缀，距 rollover 还有 10 轮——现在删 = 60K × $3/M ≈ $0.18；留到 rollover = 10 × 20K × $0.30/M ≈ $0.06。后缀越大、轮数越多，延迟越划算——正是"历史中间的 tool output"这个场景。

二、现状（master 实测）

出站视图每轮 context 事件从 (session log + ACP state) 重建，是确定性的：state 不变则视图跨轮字节稳定（tests/prefix-stab.test.ts 已 pin 住）。缓存失效只发生在 state 以"改写中间"的方式变化时：

1. applyCompression（建 block）→ summary 锚点替换历史中间的原消息 ← 主成本，模型一个阶段内可触发多次
2. applyAbsorb（kernel 已有该原语，pi adapter 未接线）→ tool-call+result 对从中间消失
3. emergency truncation（≥95%）→ 就地改写 body，防 overflow 的最后防线，保持不变

尾部追加（nudge、tool result）不动前缀。所以验收项"decompress/search 结果追加到尾部"现状已成立（decompress 默认写文件、tool result 天然在尾部），补测试 pin 住即可。

三、方案（v1）：batch rollover 模式，默认开，rollover: false 回退现状

1. compress 延迟：compress 工具先用 kernel 在 scratch state 上完整校验（protected range / minCompressRange / tier 规则 / T3-only 守卫），通过后把 {range, summary, callId} 记入 adapter 状态（持久化进 .acp.json，跨重启存活），视图不变。与已有 pending 范围重叠的重复范围当场拒绝（避免 rollover 时才发现）。
2. pending drop = 接线 kernel 的 absorb：注册 absorb 工具，模型对大 tool output 蒸馏 absorb({ref, summary})。rollover 模式下 AbsorbRecord 存 adapter pending（不写 state.absorbed），原 pair 在 rollover 前保持可见（模型 rollover 前还需要就能直接读）。v1 不开 kernel 的强制 absorb prompt（config.absorb.enabled=false，避免阈值穿越瞬间改写视图），模型自愿标记；想用强制模式可经 coreOverrides.absorb 打开。
3. rollover 触发：
   • 自动：calibrated sent-view usage ≥ 阈值（默认 70%，可配；低于 75% forced-nudge 带，保证先回收再强推）且有 pending work → 一次性批量应用全部 pending compressions（一次 applyCompression）+ 合并全部 pending absorbs 进 state.absorbed → 保存 → 同一轮重算视图并返回（回收立即生效）+ 尾部追加一次性报告（应用了几个、回收多少 token、失败明细）。一个 rollover 一次缓存失效。
   • 手动：/acp rollover。
   • 阶段边界判定：v1 不做（启发式；且阈值触发已覆盖——pending work 最迟在 usage 到 70% 时必然被应用）。
4. 必须填的一个坑：kernel 的 hideConsumedCompressCalls 会隐藏超过最近 2 个的 orphan compress 调用（KEEP_LAST_ORPHANED=2）。deferred compress 调用恰好都是 orphan（block 还没建），第 3 个 pending 调用会把第 1 个从历史中间隐藏 → 缓存失效。修复：adapter 对 processTurn 输出做 diff，把被隐藏的 pending compress 调用（+result）按原位置插回视图。
5. nudge / emergency 不变：nudge 仍提示模型写摘要（现在被延迟应用）；≥95% emergency truncation 仍是最后防线。模型完全不压缩时行为退化为现状（不会更差）。
6. 与 # [Feature Request] 新增 /acp compact 命令，复用 models.json 实现协同压缩 #240 的关系：正交。v1 摘要仍由主模型写（只延迟应用）；将来 rollover 时可把摘要生成甩给 /acp compact 独立模型，接口不冲突。

四、验收标准映射

验收项	方案
阶段内 append-only	compress/absorb 均延迟；阶段内唯一 state 变化是 ref 分配（对已有消息稳定，不改视图）
pending drop	absorb 标记 + 延迟到 rollover 移除
批量 rollover	70% 阈值（可配）+ /acp rollover 手动
decompress/search 追加尾部	现状已成立，补 pin 测试
单测：前缀稳定性	阶段内字节稳定（含 ≥3 个 pending compress 调用不被隐藏）→ rollover 恰好改写一次 → 重新锚定稳定；legacy 模式（rollover:false）保留现有 prefix-stab 断言
文档	README + CONFIGURATION（含 zh-CN）：trade-off 量化、配置项、absorb 工具、回退开关

开始实现，完成后在此汇报（分支 + PR，合并留给你）。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 设计对齐 + 实现计划

一、pending drop 的矛盾：按你的猜测收敛

"隐藏" ≠ "从 prompt 移除"。pending drop = 标记 + 延迟到 rollover 才真正移除：阶段内内容留在 prompt 里（占一点 context），换缓存稳定。量化 trade-off：

• 缓存失效成本 ≈ 全价 × 压缩点之后的后缀长度（下一轮整个后缀按全价重算）。注意：与后缀长度成正比，不是与被删内容长度成正比。
• 保留 pending 内容的成本 ≈ cache-read 价 × 自身长度 × 到 rollover 的轮数（它在稳定前缀内，按 cache-read 计费）。
• 例（Claude 价：input $3/M、cache read $0.30/M）：一个 20K 的 tool output，其后有 60K 后缀，距 rollover 还有 10 轮——现在删 = 60K × $3/M ≈ $0.18；留到 rollover = 10 × 20K × $0.30/M ≈ $0.06。后缀越大、轮数越多，延迟越划算——正是"历史中间的 tool output"这个场景。

二、现状（master 实测）

出站视图每轮 context 事件从 (session log + ACP state) 重建，是确定性的：state 不变则视图跨轮字节稳定（tests/prefix-stab.test.ts 已 pin 住）。缓存失效只发生在 state 以"改写中间"的方式变化时：

1. applyCompression（建 block）→ summary 锚点替换历史中间的原消息 ← 主成本，模型一个阶段内可触发多次
2. applyAbsorb（kernel 已有该原语，pi adapter 未接线）→ tool-call+result 对从中间消失
3. emergency truncation（≥95%）→ 就地改写 body，防 overflow 的最后防线，保持不变

尾部追加（nudge、tool result）不动前缀。所以验收项"decompress/search 结果追加到尾部"现状已成立（decompress 默认写文件、tool result 天然在尾部），补测试 pin 住即可。

三、方案（v1）：batch rollover 模式，默认开，rollover: false 回退现状

1. compress 延迟：compress 工具先用 kernel 在 scratch state 上完整校验（protected range / minCompressRange / tier 规则 / T3-only 守卫），通过后把 {range, summary, callId} 记入 adapter 状态（持久化进 .acp.json，跨重启存活），视图不变。与已有 pending 范围重叠的重复范围当场拒绝（避免 rollover 时才发现）。
2. pending drop = 接线 kernel 的 absorb：注册 absorb 工具，模型对大 tool output 蒸馏 absorb({ref, summary})。rollover 模式下 AbsorbRecord 存 adapter pending（不写 state.absorbed），原 pair 在 rollover 前保持可见（模型 rollover 前还需要就能直接读）。v1 不开 kernel 的强制 absorb prompt（config.absorb.enabled=false，避免阈值穿越瞬间改写视图），模型自愿标记；想用强制模式可经 coreOverrides.absorb 打开。
3. rollover 触发：
   • 自动：calibrated sent-view usage ≥ 阈值（默认 70%，可配；低于 75% forced-nudge 带，保证先回收再强推）且有 pending work → 一次性批量应用全部 pending compressions（一次 applyCompression）+ 合并全部 pending absorbs 进 state.absorbed → 保存 → 同一轮重算视图并返回（回收立即生效）+ 尾部追加一次性报告（应用了几个、回收多少 token、失败明细）。一个 rollover 一次缓存失效。
   • 手动：/acp rollover。
   • 阶段边界判定：v1 不做（启发式；且阈值触发已覆盖——pending work 最迟在 usage 到 70% 时必然被应用）。
4. 必须填的一个坑：kernel 的 hideConsumedCompressCalls 会隐藏超过最近 2 个的 orphan compress 调用（KEEP_LAST_ORPHANED=2）。deferred compress 调用恰好都是 orphan（block 还没建），第 3 个 pending 调用会把第 1 个从历史中间隐藏 → 缓存失效。修复：adapter 对 processTurn 输出做 diff，把被隐藏的 pending compress 调用（+result）按原位置插回视图。
5. nudge / emergency 不变：nudge 仍提示模型写摘要（现在被延迟应用）；≥95% emergency truncation 仍是最后防线。模型完全不压缩时行为退化为现状（不会更差）。
6. 与 # [Feature Request] 新增 /acp compact 命令，复用 models.json 实现协同压缩 #240 的关系：正交。v1 摘要仍由主模型写（只延迟应用）；将来 rollover 时可把摘要生成甩给 /acp compact 独立模型，接口不冲突。

四、验收标准映射

验收项	方案
阶段内 append-only	compress/absorb 均延迟；阶段内唯一 state 变化是 ref 分配（对已有消息稳定，不改视图）
pending drop	absorb 标记 + 延迟到 rollover 移除
批量 rollover	70% 阈值（可配）+ /acp rollover 手动
decompress/search 追加尾部	现状已成立，补 pin 测试
单测：前缀稳定性	阶段内字节稳定（含 ≥3 个 pending compress 调用不被隐藏）→ rollover 恰好改写一次 → 重新锚定稳定；legacy 模式（rollover:false）保留现有 prefix-stab 断言
文档	README + CONFIGURATION（含 zh-CN）：trade-off 量化、配置项、absorb 工具、回退开关

开始实现，完成后在此汇报（分支 + PR，合并留给你）。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 已实现，PR: #243 （分支 feat/rollover-cache-stability，单 commit 9832e70，27 files +1222/−84）

方案落地（默认开启，"rollover": false 恢复旧行为）

1. 阶段内 append-only — compress 调用立即校验范围（坏范围仍当场报错、计入重试上限），但只把范围记录为 pending：原文保持可见，历史不改写。
2. pending drop（absorb 工具） — 新增 absorb({ref, summary})：把大型 tool output 蒸馏成模型自写的紧凑摘要；原文标记 pending drop、保持可见直到批量应用（复用 kernel 原生 applyAbsorb 纯函数校验，零 kernel 改动）。
3. 批量 rollover — 用量越过 rollover.threshold（默认 70%，刻意低于 75% 强制 nudge 带，保证 rollover 总在 nudge 升级前触发）时，一次性 applyCompression 全部 pending + 合并 absorb 记录：一次缓存失效摊薄整段，该轮追加一次性 ▣ ACP rollover | N compression(s) + M absorb(s) applied: X → Y tokens 报告（瞬态尾部，下轮消失）。
4. 检索结果追加到尾部 — decompress / search_context 结果本就是历史末尾的 tool result，前缀永不触碰（有测试锁定）。

关键设计决策

• trade-off 定量化：pending 内容在 rollover 触发前一直占 context——这是换稳定前缀的明码价格。默认 70% 阈值保证 pending 最多存活"从记录到 70%"的窗口；回收量通常是窗口的百分之几十，一步拉回 75% nudge 带内。想更激进可调低 rollover.threshold，想更保守调高（代价是携带更多 pending）。
• 一个隐藏坑（restore 修复）：kernel 的 hideConsumedCompressCalls 只保留最近 2 个 orphan compress 调用（KEEP_LAST_ORPHANED=2）——第 3 个 pending 调用会把第 1 个从历史中间隐藏，直接破坏前缀稳定。adapter 侧按原始位置重新插入（合成 tag 与 kernel 渲染字节级一致，patchRefTag 的 tokens= 重写保证幂等）。这是"延迟压缩 + 缓存稳定"能成立的关键补丁。
• 零 kernel 改动：pending 状态、延迟 apply、restore、config、工具、命令、系统提示词段落全在 adapter 侧；acp-kernel 保持 pin 不变，无跨仓库发布顺序问题。
• 持久化：pending 存 .acp.json 的 rolloverPending 字段（跨重启生效）；顺带修了 mergeInitialState 丢弃 absorbed 字段的 bug（rollover 应用后重启会丢 absorb 记录）。
• 可观测/逃生舱：acp_status 新增 Rollover: N pending ... (threshold 70%, current X%) 行；/acp-rollover 命令强制立即批量；"rollover": false 完整回到旧行为。

验收标准对照

• 阶段内 model-visible history append-only — 测试 1：3 个 pending compress 调用期间所有相邻视图对字节级一致（含 restore 修复）
• pending drop 机制 — 测试 3：absorb 原文可见直到批量，一次性移除
• 批量 rollover — 测试 2（阈值触发）+ 测试 5（手动 /acp-rollover）
• decompress / search 结果追加到尾部 — 测试 4：前缀字节一致、纯尾部追加
• 缓存前缀稳定性单测 — tests/rollover.test.ts 5 个用例；测试 2 断言"恰好一次改写后重新锚定"（rollover 轮 + 报告消失轮，之后全部 append-only）
• 文档 — README/README.zh-CN/CONFIGURATION/CONFIGURATION.zh-CN 新增 Rollover 章节（含 trade-off 量化、配置键、absorb、/acp-rollover、逃生舱）+ CHANGELOG

验证

• npm run typecheck ✅　npm test → 433/433 ✅（428 基线 + 5 新增；既有 60 处 createAcpExtension 调用显式 rollover: false 保留旧行为覆盖，prefix-stab 回归测试同处理）　npm run build ✅（dist 544 KB，acp-kernel 内联）

一个说明：测试调试中发现既有测试的 fake ctx 把 toolCall 条目映射成空文本，导致 live-message 身份匹配失败——这是测试侧问题（真实 host 传原始消息不受影响），已修正为 verbatim 传递。PR 等 CI + 人工合并（按仓库规范，Agent 不合并 PR）。