observability: 从累计 cache 命中率升级到逐 turn 的 prompt-cache 失效诊断

[tt-a1i]

一句话结论

OpenPI Footer 当前显示整条 branch 的累计 cache 百分比；这个数字能看效率，却很难回答“哪一次模型/工具/system/context 变化打断了已经工作的 prefix cache”。

OMP 已实现一个很窄的 warm → cold detector。建议先在 OpenPI 做 provider-aware 的逐 turn 诊断研究，验证误报率后再决定是否提供 opt-in marker；不要把所有 cacheRead=0 都叫 cache miss。

固定证据

对比固定在：

• OpenPI main@2a69d3f32994da4123f1312b7fa84ef3d6119be1
• OMP main@7623b960540518bb1291808bbae28332065e9dba

OMP 当前：

• 只有上一轮实际读回至少 2048 cache tokens、当前轮 cacheRead=0、并且显式 prefix cache 发生 rewrite 时才判定 invalidation：detector contract
• 它刻意排除首轮、tiny context、连续冷轮，以及 OpenAI/Google 等 implicit best-effort cache 的传播噪声，避免制造假结论：provider boundary
• marker 默认关闭：setting

OpenPI 当前：

• model-info 遍历 active branch，把 cacheRead / (input + cacheRead + cacheWrite) 聚合成一个百分比：aggregate metric
• Footer 只渲染 cache N%，没有 turn boundary 或突变信息：footer projection

为什么值得讨论

OpenPI 的核心优势之一是 ordinary turn 的静态面小、工具渐进披露。要持续证明这个优势，需要能定位真实 cache 回退发生在哪个 turn，而不是只看 Session 结束后的平均数。

这可以帮助验证：

• capability group 加载是否导致 prefix 重写；
• tool schema / prompt 文案变动是否破坏 cache；
• compaction、branch move、model/thinking change 的成本；
• 某次 cache 降低是可控 invalidation，还是 provider 的正常 best-effort 波动；
• OpenPI 与 Bare Pi / OMP benchmark 的静态税和动态税分别来自哪里。

OpenPI 应保留的优势

• 这是 operator-facing 诊断，不向模型注入纠偏策略；
• 默认关闭，不增加普通 transcript 噪声；
• 只解释 Pi 已提供的 authoritative usage，不发明 provider 账单事实；
• provider 语义不清楚时显示 unknown，而不是推断“用户导致 miss”；
• 不把 cache 优化变成硬编码 workflow。

建议研究形态

先实现纯函数 + trace report，不急着做 UI：

1. 定义上一轮 warm、当前轮 cold、reprocessed tokens 的最小条件；
2. 按 provider/cache 类型区分 explicit prefix cache 与 implicit best-effort cache；
3. 对 model、thinking、active tools、compaction/branch change 记录可选的本地原因标签，但只能标作 correlation，不能冒充 provider 因果；
4. 用真实 Session usage 回放测试误报/漏报；
5. 只有结果可信，再加 opt-in transcript marker 或 /model-info 明细。

非目标

• 不保证 provider cache 一定命中；
• 不把 cacheRead=0 一律当异常；
• 不自动切模型、改 thinking 或阻止工具加载；
• 不把 OpenPI 变成 provider adapter；
• 不默认显示每轮 token 详情。

完成条件

• 列出 Pi usage 字段在各 provider 上可支持的结论和 unknown 边界
• detector 覆盖 first turn、warm→cold、cold→cold、partial hit、TTL expiry、compaction、model/tool change
• implicit cache provider 不因普通传播噪声产生高频假 marker
• 输出明确区分 observation、correlation 与 verified cause
• 用至少一组 OpenPI/Bare Pi/OMP trace 验证 detector
• 若加 UI，默认关闭且不改变 Session/model context
• 保留现有累计 cache% 作为趋势指标，不用单次 marker 取代它

与现有 Issue 的关系

• 研究 OMP：模型能力 × Harness 脚手架强度的收益曲线 #45：要求区分 OMP 静态税、动态税与机制触发
• 工具 Schema 不是越短越好：Codex、Maka、OMP 的角色披露、缓存稳定与有界设计 #84：关注 tool schema 的角色披露、缓存稳定和有界设计
• 本 Issue：建立可定位到 turn 的 cache observability，给 研究 OMP：模型能力 × Harness 脚手架强度的收益曲线 #45/工具 Schema 不是越短越好：Codex、Maka、OMP 的角色披露、缓存稳定与有界设计 #84 提供证据层

[627150795]

I am taking this issue for a focused first pass: document the provider-aware per-turn cache diagnostic contract and evidence boundaries, without changing runtime behavior or treating every cacheRead=0 as an invalidation. I will report the scope and validation in a follow-up.

[627150795]

Update: the focused design pass is available in PR #256: https://github.com/tt-a1i/openpi/pull/256\n\nIt defines provider-aware per-turn observations, conservative warm-to-cold evidence rules, unknown handling, replay coverage, and the boundary for a future opt-in detector. Validation passed: git diff --check, bun run lint, bun run typecheck. This PR is intentionally docs-only and does not claim runtime observability is implemented.

[tt-a1i]

相关设计讨论已展开：Tool lifecycle across compaction #311。#311 定义动态工具跨越 compaction/recovery 的状态边界；本 Issue 继续负责逐 turn 记录 compaction boundary、tool-surface fingerprint、重新物化与 cache read/write 证据。

[testikun]

我来认领 #156 尚未落地的运行时代码阶段，不重复此前的 provider-aware 设计文档。

技术方案：实现无副作用的逐 turn cache observation/detector，并从 Pi authoritative usage 构建有界 trace report；first turn、warm→cold、cold→cold、partial hit、TTL/implicit-cache unknown、compaction/model/thinking/tool-surface correlation 会有独立判定。输出严格区分 observation、correlation 与 verified cause，不把 cacheRead=0 自动称为失效，也不改变现有累计 cache% 或模型上下文。

实现已提交：PR #372。

验证：bun run check 通过；完整 bun run test 为 Node 1248 passed / 1 skipped、Vitest 30 passed；Node 22.19 定向测试 11/11 通过。实现不修改 UI，因此不适用真实 UI 截图要求。