pi-cache-optimizer 2.6.4 → 2.6.6

package/README.md

@@ -8,7 +8,7 @@
 
 Pi extension for improving provider-side KV / prompt cache hit rates. It keeps stable prompt content near the front, adds a conservative OpenAI-compatible `prompt_cache_key` fallback, warns about common proxy cache-routing gaps, and shows read-only footer cache stats.
 
-> Renamed from `pi-deepseek-cache-optimizer`. Existing footer counters migrate automatically. This package never creates, edits, backs up, or deletes your `~/.pi/agent/models.json`.
+> Renamed from `pi-deepseek-cache-optimizer`. Existing footer counters migrate automatically. The extension does **not** touch `~/.pi/agent/models.json` during normal operation; only `/cache-optimizer fix` can edit it, and only after an explicit interactive preview + confirmation with an automatic timestamped backup.
 
 ## Contents
 
@@ -17,6 +17,8 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - [Commands](#commands)
 - [Persistent opt-out](#persistent-opt-out)
 - [OpenAI-compatible proxy setup](#openai-compatible-proxy-setup)
+- [Anthropic adaptive thinking models](#anthropic-adaptive-thinking-models)
+- [Auto-repair with `/cache-optimizer fix`](#auto-repair-with-cache-optimizer-fix)
 - [Footer stats](#footer-stats)
 - [Uninstall](#uninstall)
 - [Verify effect](#verify-effect)
@@ -31,8 +33,9 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - Warns once for third-party OpenAI-compatible proxies missing cache/session-affinity compat flags.
 - Detects Anthropic adaptive thinking models (opus-4.6+, sonnet-4.6+, fable-5+) missing `forceAdaptiveThinking: true` compat.
 - Shows session-scoped footer stats for supported model families.
+- Supports optional router-extension integration through versioned global protocols (`Symbol.for("pi.routing.registry.v1")` and `Symbol.for("pi.cache.hints.v1")`) without importing router packages.
 
-Caching is provider-side and best-effort. Third-party proxies can still hide cache usage, reject unsupported parameters, or route requests across multiple upstreams.
+Caching is provider-side and best-effort. Third-party proxies and router extensions can still hide cache usage, reject unsupported parameters, or route requests across multiple upstreams.
 
 ## Install
 
@@ -161,7 +164,7 @@ Or use model-level override:
 
 1. Shows full preview of changes (file path, edit location, JSON to write, risks)
 2. Warns: ① changes affect all sessions using that channel, ② automatic backup created at `models.json.backup-cache-optimizer-<timestamp>`, ③ Pi reload required
-3. Uses comment-preserving surgical editor — existing comments, indentation, key order preserved
+3. Uses comment-preserving surgical editor — existing comments, indentation, and existing key order are preserved
 4. Requires explicit user confirmation (interactive prompt or `ui.select`)
 5. Writes atomically (temp + rename); self-validates after write
 6. Falls back to manual guidance if JSONC scanner cannot confidently locate the target
@@ -210,6 +213,8 @@ If only one model should change, use `modelOverrides`:
 
 Stats are read-only local counters stored at `~/.pi/agent/pi-cache-optimizer-stats.json` and scoped by Pi session + provider/model. They contain only dates and numeric counters — no API keys, prompts, payloads, headers, responses, or model output.
 
+For virtual routing providers, completed assistant message metadata is authoritative: if the message carries real upstream `provider`, `model` / `responseModel`, `api`, and usage, stats are attributed to that upstream provider/model instead of the virtual router shell. Router extensions may also publish a live route adapter under `Symbol.for("pi.routing.registry.v1")` so footer, doctor, compat, and reset flows can resolve the current upstream before the final assistant message exists. The cache optimizer also exposes query-scoped prompt/cache hints via `Symbol.for("pi.cache.hints.v1")` for routers that forward to inner `streamSimple` calls. Both protocols are optional and versioned; no router package import is required.
+
 Example footer:
 
 ```text

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 用于提升 Pi 中 provider 侧 KV Cache / Prompt Cache 命中率的扩展：把稳定 prompt 内容前置，给 OpenAI-compatible 请求补保守的 `prompt_cache_key`，提示代理渠道常见缓存路由兼容问题，并在底部显示只读缓存统计。
 
-> 本包已从 `pi-deepseek-cache-optimizer` 改名。已有底部统计会自动迁移。本扩展绝不会创建、修改、备份或删除你的 `~/.pi/agent/models.json`。
+> 本包已从 `pi-deepseek-cache-optimizer` 改名。已有底部统计会自动迁移。正常运行时扩展不会触碰你的 `~/.pi/agent/models.json`；只有 `/cache-optimizer fix` 会在展示交互式预览、风险提示并得到明确确认后写入，且会先创建带时间戳的自动备份。
 
 ## 目录
 
@@ -17,6 +17,8 @@
 - [命令](#命令)
 - [持久 Opt-out](#持久-opt-out)
 - [OpenAI-compatible 代理配置](#openai-compatible-代理配置)
+- [Anthropic adaptive thinking 模型](#anthropic-adaptive-thinking-模型)
+- [使用 `/cache-optimizer fix` 自动修复](#使用-cache-optimizer-fix-自动修复)
 - [Footer 统计](#footer-统计)
 - [卸载](#卸载)
 - [验证效果](#验证效果)
@@ -31,8 +33,9 @@
 - 对缺少缓存 / session-affinity compat 的第三方 OpenAI-compatible 代理给出一次性提醒。
 - 检测 Anthropic adaptive thinking 模型（opus-4.6+、sonnet-4.6+、fable-5+）是否缺少 `forceAdaptiveThinking: true` compat。
 - 为支持的模型家族显示按 session 隔离的底部缓存统计。
+- 通过版本化全局协议（`Symbol.for("pi.routing.registry.v1")` 与 `Symbol.for("pi.cache.hints.v1")`）支持可选的 router extension 集成，而不导入任何 router 包。
 
-缓存是 provider 侧的 best-effort 行为。第三方代理仍可能隐藏缓存 usage、拒绝不支持的参数，或把请求路由到多个上游。
+缓存是 provider 侧的 best-effort 行为。第三方代理和 router extension 仍可能隐藏缓存 usage、拒绝不支持的参数，或把请求路由到多个上游。
 
 ## 安装
 
@@ -161,7 +164,7 @@ Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这
 
 1. 显示完整变更预览（文件路径、编辑位置、要写入的 JSON、风险说明）
 2. 警告：① 修改影响使用该渠道的所有 session，② 自动备份到 `models.json.backup-cache-optimizer-<timestamp>`，③ 需重启 Pi 或 reload
-3. 使用保留注释的精确编辑器 —— 现有注释、缩进、key 顺序全部保留
+3. 使用保留注释的精确编辑器 —— 现有注释、缩进和已有 key 顺序都会保留
 4. 需要用户明确确认（交互式提示或 `ui.select`）
 5. 原子写入（temp + rename）；写入后自我验证
 6. 如果 JSONC 扫描器无法置信定位目标，回退到手动修改指引
@@ -210,6 +213,8 @@ Provider 级最小 override：
 
 统计是只读本地计数，保存在 `~/.pi/agent/pi-cache-optimizer-stats.json`，按 Pi session + provider/model 隔离。文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。
 
+对于虚拟 routing provider，最终 assistant message 的 metadata 是权威来源：如果 message 携带真实上游 `provider`、`model` / `responseModel`、`api` 和 usage，统计会归因到真实上游 provider/model，而不是虚拟 router 外壳。Router extension 也可以在 `Symbol.for("pi.routing.registry.v1")` 下发布 live route adapter，让 footer、doctor、compat 和 reset 在最终 assistant message 出现前解析当前上游。本扩展还通过 `Symbol.for("pi.cache.hints.v1")` 暴露按查询过滤的 prompt/cache hints，供转发到内部 `streamSimple` 的 router 使用。两个协议都是可选、版本化的；不需要导入任何 router 包。
+
 示例 footer：
 
 ```text