$ cat ~/map/pi-cache-lens.md

pi-cache-lens

在状态栏显示单次与会话级 KV 缓存命中率，后台取证归因每一次缓存丢失。

extensions✓ 10月31日

pi install git:github.com/w31r4/pi-cache-lens，之后随时可用 pi update 更新。状态栏芯片在内置 pi 页脚中自动渲染；pi-powerline-footer 与 pi-cc-extensions 的集成片段在 README 里有文档。

## 速览

一个零开销的 pi 扩展：在状态栏显示最近一次请求与整个会话的前缀 KV 缓存命中率，并在后台取证归因每一次缓存丢失——冷启动、工具变动、历史改写、TTL 过期、模型切换或网关漂移——只落盘哈希与偏移量，从不写入原始提示文本。

## 要点

• $双命中率芯片：同时显示最近一次请求与整个会话的累计命中率，70% 及以上用 accent 色，30% 到 69% 之间警告，低于 30% 报错，会话头三次调用以弱化的预热样式显示。
• $构造上零开销：不注册任何工具 schema，也从不改写外发请求；扩展在 before_provider_request 钩子里只观察流量。
• $根因标签给每一次缓存丢失分型：冷启动、低于最小可缓存 token 数、工具变动、供应商 strict 工具回退、系统提示被改写、历史被改写或压缩、TTL 过期、模型切换、网关路由漂移，以及缺乏可比证据的骤然部分丢失。
• $凭据安全的归因：对归一化的系统提示、工具（含内联 additional_tools）、供应商档位标记与对话条目做指纹，落盘的只有哈希、字节长度与 char@/byte@ 偏移——从不保存提示片段。
• $斜杠命令：/cache 显示会话摘要与最近八次调用的短哈希，/cache anomalies 显示跨会话最近十次缓存丢失，/cache path 打印取证文件路径。
• $取证文件位于 ~/.pi/agent/cache-lens/ 下：按模型分组的 latest-report.md、10 MB 自动轮转的 events.jsonl，以及只收录实锤丢失的 anomalies.jsonl。
• $TTL 阈值跟随供应商：cache_control 或 prompt_cache_key 生效时默认 290 秒，30 分钟 prompt cache TTL 为 1800 秒，24 小时档最高 86400 秒；所有阈值都可在 ~/.pi/agent/cache-lens.json 里配置。
• $界面语言自动探测 rpiv-i18n 或 LANG（zh 或 en），也可在配置文件里强制指定。

## 常见问题

## 参考链接

• README（根因标签、安装、集成、配置） ↗

最后更新: 2026年10月30日