pi-cache-optimizer 2.6.25 → 2.7.0

package/README.md

@@ -16,6 +16,7 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - [Install](#install)
 - [Commands](#commands)
 - [Persistent opt-out](#persistent-opt-out)
+- [Footer cache stats mode](#footer-cache-stats-mode)
 - [OpenAI-compatible proxy setup](#openai-compatible-proxy-setup)
 - [Adaptive thinking models](#adaptive-thinking-models)
 - [Auto-repair with `/cache-optimizer fix`](#auto-repair-with-cache-optimizer-fix)
@@ -30,10 +31,10 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - Reorders uniquely identifiable stable system-prompt content before dynamic context. If the same candidate appears more than once (for example, quoted inside dynamic context), it is left unchanged to avoid removing the wrong occurrence.
 - Compresses Pi skill listings and strips session-overview churn.
 - Requests long cache retention when Pi/provider compat supports it.
-- Adds a session-id `prompt_cache_key` fallback for `openai-completions` / `openai-responses` payloads when no effective key exists, including Pi's built-in `llama.cpp` provider as Pi 0.82 core does.
+- Adds a session-id `prompt_cache_key` fallback for `openai-completions` / `openai-responses` payloads when no effective key exists, including Pi's built-in `llama.cpp` provider as Pi 0.82+ core does.
 - Warns once for third-party OpenAI-compatible proxies missing cache/session-affinity compat flags.
-- Detects adaptive-thinking compat for Claude (opus-4.6+, sonnet-4.6+ including Sonnet 5, fable-5+) and Kimi Coding K3 / `kimi-for-coding` custom channels.
-- Shows restart-persistent provider/model footer stats for supported model families.
+- Detects adaptive-thinking compat for Claude (opus-4.6+ including Opus 5, sonnet-4.6+ including Sonnet 5, fable-5+) and Kimi Coding K3 / `kimi-for-coding` custom channels.
+- Shows daily cumulative provider/model footer stats by default, with an opt-in current-session display mode.
 - 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 and router extensions can still hide cache usage, reject unsupported parameters, or route requests across multiple upstreams.
@@ -54,6 +55,8 @@ Run `/reload` in Pi after install/update/remove so extension hooks refresh.
 
 On Pi 0.79.7 and newer, `pi update` updates Pi itself only. To update installed Pi packages such as this extension, run `pi update --extensions` (packages only) or `pi update --all` (Pi + packages).
 
+This extension is validated against Pi 0.83.0 and remains designed for Pi 0.82+. It uses the existing extension hooks, `getAgentDir()`, and prompt options shared by those versions; it does not depend on Pi 0.83-only APIs such as `ctx.scopedModels` or the bundled TypeBox 1.3 aliases.
+
 ## Commands
 
 | Command | Effect |
@@ -65,6 +68,7 @@ On Pi 0.79.7 and newer, `pi update` updates Pi itself only. To update installed
 | `/cache-optimizer compat` | Shows copyable compat advice for the active model, if applicable. |
 | `/cache-optimizer stats` | Shows today's local provider/model counters and recent trend for the active model. |
 | `/cache-optimizer reset` | Resets local footer stats for the active provider/model; upstream provider cache is not modified. |
+| `/cache-optimizer config footer-mode session\|total` | Persist the footer stats mode. Persistent command configuration overrides the environment variable. |
 | `/cache-optimizer fix` | Auto-repairs safe compat issues for the active model (adaptive thinking, DeepSeek reasoning, OpenAI proxy session affinity). Shows preview + risk warning, requires confirmation. **Only modifies `models.json` after explicit user approval.** |
 
 `enable` / `disable` are current-process switches. For a persistent opt-out, use environment variables below.
@@ -78,11 +82,29 @@ On Pi 0.79.7 and newer, `pi update` updates Pi itself only. To update installed
 | `PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY=1` | Disable the OpenAI-compatible `prompt_cache_key` fallback. Preferred explicit opt-out. |
 | `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=0` | Disable the same fallback via the legacy inverse switch. Values `0`, `false`, `no`, or `off` disable it. |
 
+## Footer cache stats mode
+
+**v2.7.0+** supports both daily cumulative and current-session footer scopes. The footer defaults to `total`, which shows the provider/model's local counters for the current day across Pi sessions and process restarts. Use either the command or environment variable to select the scope:
+
+| Value | Effect |
+|---|---|
+| `total` (default) | Show today's restart-persistent provider/model totals across sessions. Local day rollover resets the counters. |
+| `session` | Show only the current hashed Pi session's counters. A fresh session starts at `0/0`; `/reload` in the same session restores that session bucket. |
+
+Persistent command configuration takes precedence over the environment variable:
+
+```text
+/cache-optimizer config footer-mode session
+/cache-optimizer config footer-mode total
+```
+
+The explicit setting is stored in `pi-cache-optimizer-config.json` under Pi's agent directory. If no command override exists, `PI_CACHE_OPTIMIZER_FOOTER_MODE=session|total` is used; values are case-insensitive, and missing or invalid values fall back to `total`. To return an existing installation to environment-controlled behavior, manually delete `pi-cache-optimizer-config.json` and run `/reload`.
+
 ## OpenAI-compatible proxy setup
 
 Third-party `openai-completions` proxies (LiteLLM / OneAPI / NewAPI / OpenRouter-like channels) often route one session across multiple upstream backends. That splits provider-side prompt caches.
 
-Pi 0.81+ also has a built-in `llama.cpp` provider using an OpenAI-shaped transport. Pi 0.82 core generates a session `prompt_cache_key` for it when cache retention is enabled, so this extension preserves that key and may add the same conservative fallback when missing. The built-in provider's explicit compat fingerprint is excluded from generic proxy routing/session-affinity advice, but a custom or overridden provider that merely reuses the id `llama.cpp` is treated like any other OpenAI-compatible channel. `prompt_cache_retention` remains subject to the normal safety rule: keep it only for official OpenAI or an explicit effective `supportsLongCacheRetention: true` opt-in in `models.json`; otherwise strip it before sending. Effective values follow Pi's precedence: `modelOverrides[modelId].compat` first, then the matching `models[].compat`, then provider-level `compat`. An explicit `false` at a higher layer overrides `true` below it.
+Pi 0.81+ also has a built-in `llama.cpp` provider using an OpenAI-shaped transport. Pi 0.82+ core generates a session `prompt_cache_key` for it when cache retention is enabled, so this extension preserves that key and may add the same conservative fallback when missing. The built-in provider's explicit compat fingerprint is excluded from generic proxy routing/session-affinity advice, but a custom or overridden provider that merely reuses the id `llama.cpp` is treated like any other OpenAI-compatible channel. `prompt_cache_retention` remains subject to the normal safety rule: keep it only for official OpenAI or an explicit effective `supportsLongCacheRetention: true` opt-in in `models.json`; otherwise strip it before sending. Effective values follow Pi's precedence: `modelOverrides[modelId].compat` first, then the matching `models[].compat`, then provider-level `compat`. An explicit `false` at a higher layer overrides `true` below it.
 
 For real proxies, start with session affinity:
 
@@ -123,7 +145,7 @@ Some proxies rewrite or insert hidden 5-minute breakpoints after Pi's request ho
 
 ## Adaptive thinking models
 
-Claude models from opus-4.6 / sonnet-4.6 (including Sonnet 5) / fable-5 onwards require `forceAdaptiveThinking: true` in compat. Kimi Coding K3 (`k3`) and `kimi-for-coding` also use adaptive thinking and need `allowEmptySignature: true` so replayed empty-signature thinking blocks remain valid. Without the required compat, Pi may send a legacy thinking payload or replay thinking incorrectly.
+Claude models from opus-4.6 / sonnet-4.6 (including Opus 5 and Sonnet 5) / fable-5 onwards require `forceAdaptiveThinking: true` in compat. Kimi Coding K3 (`k3`) and `kimi-for-coding` also use adaptive thinking and need `allowEmptySignature: true` so replayed empty-signature thinking blocks remain valid. Without the required compat, Pi may send a legacy thinking payload or replay thinking incorrectly. Pi 0.83.0's native Opus 5 catalog is covered by the same adaptive-thinking detection; custom `anthropic-messages` channels still need the compat flag when Pi does not provide it.
 
 Pi's built-in catalog already sets this flag for official models. Custom channels in `models.json` that override these models must include the flag:
 
@@ -249,7 +271,7 @@ If only one model should change, use `modelOverrides`:
 
 ## Footer stats
 
-Stats are read-only local counters stored in Pi's agent directory (default: `~/.pi/agent/pi-cache-optimizer-stats.json`; custom agent dirs use `PI_CODING_AGENT_DIR`) and keyed by provider/model, so the same channel/model keeps today's footer counters after a Pi process or terminal restart. The file also keeps hashed session buckets for migration/reload bookkeeping. It contains only dates and numeric counters — no API keys, prompts, payloads, headers, responses, or model output.
+Stats are read-only local counters stored in Pi's agent directory (default: `~/.pi/agent/pi-cache-optimizer-stats.json`; custom agent dirs use `PI_CODING_AGENT_DIR`). Both today's provider/model totals and hashed session buckets are maintained. The footer shows daily totals by default, or the current session bucket when `session` mode is selected. The stats file contains only dates and numeric counters — no API keys, prompts, payloads, headers, responses, or model output. Footer mode configuration is stored separately in `pi-cache-optimizer-config.json`.
 
 Pi 0.79+ also includes a built-in footer `CH` marker for the latest prompt cache hit rate. This extension complements that marker with persisted provider/model counters plus proxy compat diagnostics.
 
@@ -378,13 +400,13 @@ When the query matches the current session/route, `hints` may contain `systemPro
 pi remove npm:pi-cache-optimizer
 ```
 
-Then run `/reload` or restart Pi. Optional local stats cleanup (if you use `PI_CODING_AGENT_DIR`, delete the same files from that directory instead):
+Then run `/reload` or restart Pi. Optional local state cleanup (if you use `PI_CODING_AGENT_DIR`, delete the same files from that directory instead):
 
-| Platform | Delete local stats files |
+| Platform | Delete local state files |
 |---|---|
-| Linux / macOS / WSL | `rm -f ~/.pi/agent/pi-cache-optimizer-stats.json ~/.pi/agent/deepseek-cache-optimizer-stats.json` |
-| Windows PowerShell | `Remove-Item -Force "$env:USERPROFILE\.pi\agent\pi-cache-optimizer-stats.json", "$env:USERPROFILE\.pi\agent\deepseek-cache-optimizer-stats.json" -ErrorAction SilentlyContinue` |
-| Windows Command Prompt | `del /f /q "%USERPROFILE%\.pi\agent\pi-cache-optimizer-stats.json" "%USERPROFILE%\.pi\agent\deepseek-cache-optimizer-stats.json" 2>nul` |
+| Linux / macOS / WSL | `rm -f ~/.pi/agent/pi-cache-optimizer-stats.json ~/.pi/agent/pi-cache-optimizer-config.json ~/.pi/agent/deepseek-cache-optimizer-stats.json` |
+| Windows PowerShell | `Remove-Item -Force "$env:USERPROFILE\.pi\agent\pi-cache-optimizer-stats.json", "$env:USERPROFILE\.pi\agent\pi-cache-optimizer-config.json", "$env:USERPROFILE\.pi\agent\deepseek-cache-optimizer-stats.json" -ErrorAction SilentlyContinue` |
+| Windows Command Prompt | `del /f /q "%USERPROFILE%\.pi\agent\pi-cache-optimizer-stats.json" "%USERPROFILE%\.pi\agent\pi-cache-optimizer-config.json" "%USERPROFILE%\.pi\agent\deepseek-cache-optimizer-stats.json" 2>nul` |
 
 Do not delete `models.json` during cleanup; it contains your Pi model/provider configuration and is not owned by this package.
 

package/README.zh-CN.md

@@ -16,6 +16,7 @@
 - [安装](#安装)
 - [命令](#命令)
 - [持久 Opt-out](#持久-opt-out)
+- [Footer 缓存统计模式](#footer-缓存统计模式)
 - [OpenAI-compatible 代理配置](#openai-compatible-代理配置)
 - [Adaptive thinking 模型](#adaptive-thinking-模型)
 - [使用 `/cache-optimizer fix` 自动修复](#使用-cache-optimizer-fix-自动修复)
@@ -30,10 +31,10 @@
 - 将能唯一定位的稳定 system prompt 内容移动到动态上下文之前。如果同一候选出现多次（例如动态上下文引用了它），则保持原样，避免删除错误的那一处。
 - 压缩 Pi skill 列表，并移除 session-overview 中的易变字段。
 - 在 Pi / provider compat 支持时请求长缓存保留。
-- 对 `openai-completions` / `openai-responses` 请求，在没有有效 key 时使用 Pi session id 补 `prompt_cache_key`；Pi 0.82 core 对内置 `llama.cpp` 也使用这一语义。
+- 对 `openai-completions` / `openai-responses` 请求，在没有有效 key 时使用 Pi session id 补 `prompt_cache_key`；Pi 0.82+ core 对内置 `llama.cpp` 也使用这一语义。
 - 对缺少缓存 / session-affinity compat 的第三方 OpenAI-compatible 代理给出一次性提醒。
-- 检测 Claude（opus-4.6+、sonnet-4.6+ 含 Sonnet 5、fable-5+）以及 Kimi Coding K3 / `kimi-for-coding` 自定义渠道的 adaptive-thinking compat。
-- 为支持的模型家族显示可跨 Pi 进程 / 终端重启延续的 provider/model footer 缓存统计。
+- 检测 Claude（opus-4.6+ 含 Opus 5、sonnet-4.6+ 含 Sonnet 5、fable-5+）以及 Kimi Coding K3 / `kimi-for-coding` 自定义渠道的 adaptive-thinking compat。
+- 默认显示按本地日期累计的 provider/model footer 缓存统计，也可切换为仅显示当前 session。
 - 通过版本化全局协议（`Symbol.for("pi.routing.registry.v1")` 与 `Symbol.for("pi.cache.hints.v1")`）支持可选的 router extension 集成，而不导入任何 router 包。
 
 缓存是 provider 侧的 best-effort 行为。第三方代理和 router extension 仍可能隐藏缓存 usage、拒绝不支持的参数，或把请求路由到多个上游。
@@ -54,6 +55,8 @@ pi remove npm:pi-deepseek-cache-optimizer && pi install npm:pi-cache-optimizer
 
 Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安装的 Pi package（包括本扩展），请运行 `pi update --extensions`（只更新 packages）或 `pi update --all`（Pi 与 packages 一起更新）。
 
+本扩展已使用 Pi 0.83.0 验证，并继续面向 Pi 0.82+ 设计。它使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options，不依赖 Pi 0.83 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。
+
 ## 命令
 
 | 命令 | 作用 |
@@ -65,6 +68,7 @@ Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安
 | `/cache-optimizer compat` | 对当前模型显示可复制的 compat 建议（如适用）。 |
 | `/cache-optimizer stats` | 显示当前模型今天的本地 provider/model 统计和近期趋势。 |
 | `/cache-optimizer reset` | 重置当前 provider/model 的本地 footer 统计；不会修改上游 provider 缓存。 |
+| `/cache-optimizer config footer-mode session\|total` | 持久设置 footer 统计模式；持久命令配置优先于环境变量。 |
 | `/cache-optimizer fix` | 为当前模型自动修复安全的 compat 问题（adaptive thinking、DeepSeek reasoning、OpenAI proxy session affinity）。展示预览 + 风险提示，需要用户确认。**仅在用户明确批准后才修改 `models.json`。** |
 
 `enable` / `disable` 是当前进程内开关。若要持久关闭某些能力，请使用下面的环境变量。
@@ -78,11 +82,29 @@ Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安
 | `PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY=1` | 关闭 OpenAI-compatible `prompt_cache_key` fallback。推荐使用这个显式 opt-out。 |
 | `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=0` | 通过旧的反向开关关闭同一个 fallback。取值 `0`、`false`、`no`、`off` 时关闭。 |
 
+## Footer 缓存统计模式
+
+**v2.7.0+** 同时支持每日累计与当前 session 两种 footer 统计范围。Footer 默认使用 `total`，显示当前本地日期内、跨 Pi session 和进程重启延续的 provider/model 统计。可以通过命令或环境变量切换显示范围：
+
+| 值 | 作用 |
+|---|---|
+| `total`（默认） | 显示今天跨 session 持久延续的 provider/model 累计统计；本地日期切换时重置。 |
+| `session` | 仅显示当前 hashed Pi session 的统计。新 session 从 `0/0` 开始；同一 session 内 `/reload` 会恢复该 session 桶。 |
+
+持久命令配置优先于环境变量：
+
+```text
+/cache-optimizer config footer-mode session
+/cache-optimizer config footer-mode total
+```
+
+显式设置保存在 Pi agent 目录下的 `pi-cache-optimizer-config.json`。没有命令覆盖时，读取 `PI_CACHE_OPTIMIZER_FOOTER_MODE=session|total`；值不区分大小写，缺失或非法值均回退到 `total`。如需让已有安装重新由环境变量控制，请手动删除 `pi-cache-optimizer-config.json`，然后运行 `/reload`。
+
 ## OpenAI-compatible 代理配置
 
 LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completions` 代理，常会把同一个 session 分散到多个上游后端，导致 provider 侧 prompt cache 被拆散。
 
-Pi 0.81+ 也内置了使用 OpenAI-shaped transport 的 `llama.cpp` provider。Pi 0.82 core 在启用 cache retention 时会为它生成 session `prompt_cache_key`，因此本扩展会保留该 key，并在缺失时使用同样的保守 fallback。只有符合 Pi 内置 provider 明确 compat 指纹的模型会跳过通用 proxy 路由 / session-affinity 建议；仅复用 `llama.cpp` id 的自定义或覆盖 provider 仍按普通 OpenAI-compatible 渠道处理。`prompt_cache_retention` 继续遵循统一安全规则：仅官方 OpenAI 或 `models.json` 中有效配置为 `supportsLongCacheRetention: true` 时保留，否则发送前移除。有效值遵循 Pi 的优先级：先看 `modelOverrides[modelId].compat`，再看匹配的 `models[].compat`，最后看 provider 级 `compat`；高层显式 `false` 会覆盖低层的 `true`。
+Pi 0.81+ 也内置了使用 OpenAI-shaped transport 的 `llama.cpp` provider。Pi 0.82+ core 在启用 cache retention 时会为它生成 session `prompt_cache_key`，因此本扩展会保留该 key，并在缺失时使用同样的保守 fallback。只有符合 Pi 内置 provider 明确 compat 指纹的模型会跳过通用 proxy 路由 / session-affinity 建议；仅复用 `llama.cpp` id 的自定义或覆盖 provider 仍按普通 OpenAI-compatible 渠道处理。`prompt_cache_retention` 继续遵循统一安全规则：仅官方 OpenAI 或 `models.json` 中有效配置为 `supportsLongCacheRetention: true` 时保留，否则发送前移除。有效值遵循 Pi 的优先级：先看 `modelOverrides[modelId].compat`，再看匹配的 `models[].compat`，最后看 provider 级 `compat`；高层显式 `false` 会覆盖低层的 `true`。
 
 对真正的代理，建议先启用 session affinity：
 
@@ -123,7 +145,7 @@ Anthropic 按 `tools → system → messages` 顺序处理 cache breakpoint，
 
 ## Adaptive thinking 模型
 
-Claude 从 opus-4.6 / sonnet-4.6（含 Sonnet 5）/ fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。Kimi Coding K3（`k3`）和 `kimi-for-coding` 也使用 adaptive thinking，并需要 `allowEmptySignature: true`，以正确重放空 signature 的 thinking block。缺少这些 compat 时，Pi 可能发送旧版 thinking payload 或错误重放 thinking。
+Claude 从 opus-4.6 / sonnet-4.6（含 Opus 5、Sonnet 5）/ fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。Kimi Coding K3（`k3`）和 `kimi-for-coding` 也使用 adaptive thinking，并需要 `allowEmptySignature: true`，以正确重放空 signature 的 thinking block。缺少这些 compat 时，Pi 可能发送旧版 thinking payload 或错误重放 thinking。Pi 0.83.0 的原生 Opus 5 catalog 已覆盖在同一 adaptive-thinking 检测中；如果自定义 `anthropic-messages` 渠道没有继承该 compat，仍需手动设置。
 
 Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这些模型的自定义渠道必须包含该 flag：
 
@@ -249,7 +271,7 @@ Provider 级最小 override：
 
 ## Footer 统计
 
-统计是只读本地计数，保存在 Pi agent 目录（默认 `~/.pi/agent/pi-cache-optimizer-stats.json`；自定义 agent 目录使用 `PI_CODING_AGENT_DIR`），按 provider/model 作为 footer 展示维度，因此同一个渠道/模型在 Pi 进程或终端重启后会延续今天的统计。文件也保留 hashed session buckets，用于迁移和 reload 记录。文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。
+统计是只读本地计数，保存在 Pi agent 目录（默认 `~/.pi/agent/pi-cache-optimizer-stats.json`；自定义 agent 目录使用 `PI_CODING_AGENT_DIR`）。扩展同时维护当天的 provider/model totals 和 hashed session buckets。Footer 默认显示每日 totals；选择 `session` 模式后显示当前 session 桶。统计文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。Footer 模式配置单独保存在 `pi-cache-optimizer-config.json`。
 
 Pi 0.79+ 已内置 footer `CH` 标记，用于显示最近一次 prompt cache hit rate。本扩展在此基础上补充持久化的 provider/model 计数，以及代理 compat 诊断。
 
@@ -378,13 +400,13 @@ const hints = (globalThis as Record<symbol, any>)[CACHE_HINTS]?.getHints?.({
 pi remove npm:pi-cache-optimizer
 ```
 
-然后运行 `/reload` 或重启 Pi。可选：删除本地统计文件（如果使用 `PI_CODING_AGENT_DIR`，请删除该目录中的同名文件）：
+然后运行 `/reload` 或重启 Pi。可选：删除本地状态文件（如果使用 `PI_CODING_AGENT_DIR`，请删除该目录中的同名文件）：
 
-| 平台 | 删除本地统计文件 |
+| 平台 | 删除本地状态文件 |
 |---|---|
-| Linux / macOS / WSL | `rm -f ~/.pi/agent/pi-cache-optimizer-stats.json ~/.pi/agent/deepseek-cache-optimizer-stats.json` |
-| Windows PowerShell | `Remove-Item -Force "$env:USERPROFILE\.pi\agent\pi-cache-optimizer-stats.json", "$env:USERPROFILE\.pi\agent\deepseek-cache-optimizer-stats.json" -ErrorAction SilentlyContinue` |
-| Windows 命令提示符 | `del /f /q "%USERPROFILE%\.pi\agent\pi-cache-optimizer-stats.json" "%USERPROFILE%\.pi\agent\deepseek-cache-optimizer-stats.json" 2>nul` |
+| Linux / macOS / WSL | `rm -f ~/.pi/agent/pi-cache-optimizer-stats.json ~/.pi/agent/pi-cache-optimizer-config.json ~/.pi/agent/deepseek-cache-optimizer-stats.json` |
+| Windows PowerShell | `Remove-Item -Force "$env:USERPROFILE\.pi\agent\pi-cache-optimizer-stats.json", "$env:USERPROFILE\.pi\agent\pi-cache-optimizer-config.json", "$env:USERPROFILE\.pi\agent\deepseek-cache-optimizer-stats.json" -ErrorAction SilentlyContinue` |
+| Windows 命令提示符 | `del /f /q "%USERPROFILE%\.pi\agent\pi-cache-optimizer-stats.json" "%USERPROFILE%\.pi\agent\pi-cache-optimizer-config.json" "%USERPROFILE%\.pi\agent\deepseek-cache-optimizer-stats.json" 2>nul` |
 
 清理时不要删除 `models.json`；它保存你的 Pi 模型 / provider 配置，不属于本包。
 

package/index.ts

@@ -95,12 +95,20 @@ const STATUS_KEY = "pi-cache-stats";
 const STATE_DIR = getAgentDir();
 const STATE_FILE_PATH = join(STATE_DIR, "pi-cache-optimizer-stats.json");
 const LEGACY_STATE_FILE_PATH = join(STATE_DIR, "deepseek-cache-optimizer-stats.json");
+const CONFIG_FILE_PATH = join(STATE_DIR, "pi-cache-optimizer-config.json");
 const CACHE_PROVIDER_IDS: CacheProviderId[] = ["deepseek", "openai", "claude", "gemini"];
 const OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY";
 const NO_OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY";
 const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
 const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
 const NO_PROMPT_REWRITE_ENV = "PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE";
+const FOOTER_MODE_ENV = "PI_CACHE_OPTIMIZER_FOOTER_MODE";
+type FooterStatsMode = "session" | "total";
+type FooterStatsModeSource = "config" | "env" | "default";
+type PersistedCacheOptimizerConfigV1 = {
+  version: 1;
+  footerMode?: FooterStatsMode;
+};
 const PI_ROUTING_REGISTRY_SYMBOL = Symbol.for("pi.routing.registry.v1");
 const PI_CACHE_HINTS_SYMBOL = Symbol.for("pi.cache.hints.v1");
 const PI_CACHE_HINTS_OWNER_SYMBOL = Symbol.for("pi.cache.optimizer.hints-owner.v1");
@@ -1132,6 +1140,62 @@ function isEnabledEnv(value: string | undefined): boolean {
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
 
+function parseFooterStatsMode(value: unknown): FooterStatsMode | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "session" || normalized === "total" ? normalized : undefined;
+}
+
+function parsePersistedCacheOptimizerConfig(value: unknown): PersistedCacheOptimizerConfigV1 | undefined {
+  const record = asRecord(value);
+  if (!record || record.version !== 1) return undefined;
+  const footerMode = parseFooterStatsMode(record.footerMode);
+  if (record.footerMode !== undefined && !footerMode) return undefined;
+  return { version: 1, ...(footerMode ? { footerMode } : {}) };
+}
+
+function readPersistedFooterMode(configPath: string = CONFIG_FILE_PATH): FooterStatsMode | undefined {
+  try {
+    const parsed = parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8")));
+    if (!parsed) throw new Error("invalid footer config schema");
+    return parsed.footerMode;
+  } catch (error) {
+    if (getErrorCode(error) !== "ENOENT") {
+      console.warn(`${LOG_PREFIX}: failed to read footer config; using environment/default mode`, error);
+    }
+    return undefined;
+  }
+}
+
+async function writePersistedFooterMode(
+  mode: FooterStatsMode,
+  configPath: string = CONFIG_FILE_PATH,
+): Promise<void> {
+  await mkdir(dirname(configPath), { recursive: true });
+  const payload: PersistedCacheOptimizerConfigV1 = { version: 1, footerMode: mode };
+  const tempPath = `${configPath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  await rename(tempPath, configPath);
+}
+
+function resolveFooterStatsMode(
+  configuredMode: FooterStatsMode | undefined,
+  env: MutableEnv = process.env,
+): { mode: FooterStatsMode; source: FooterStatsModeSource } {
+  if (configuredMode) return { mode: configuredMode, source: "config" };
+  const envMode = parseFooterStatsMode(env[FOOTER_MODE_ENV]);
+  return envMode ? { mode: envMode, source: "env" } : { mode: "total", source: "default" };
+}
+
+function footerStatsMode(
+  env: MutableEnv = process.env,
+  configuredMode: FooterStatsMode | undefined = persistedFooterStatsMode,
+): FooterStatsMode {
+  return resolveFooterStatsMode(configuredMode, env).mode;
+}
+
+let persistedFooterStatsMode = readPersistedFooterMode();
+
 function isDisabledEnv(value: string | undefined): boolean {
   if (!value) return false;
   const normalized = value.trim().toLowerCase();
@@ -3827,11 +3891,24 @@ function routedModelRefToPiModel(ref: PersistedRoutedModelRef): PiModel {
   } as PiModel;
 }
 
+function selectFooterStatsForModel(
+  mode: FooterStatsMode,
+  sessionHash: string | undefined,
+  statsByModel: Record<string, CacheStats>,
+  totalsByModel: Record<string, CacheStats>,
+  model: { provider: string; id: string },
+): CacheStats | undefined {
+  if (mode === "total") return totalsByModel[modelKey(model)];
+  if (!sessionHash) return undefined;
+  return statsByModel[makeSessionModelKey(sessionHash, model.provider, model.id)];
+}
+
 function buildExactRouterStatusEntry(
   sessionHash: string | undefined,
   statsByModel: Record<string, CacheStats>,
   lastRoutedModel: PersistedRoutedModelRef | undefined,
   totalsByModel: Record<string, CacheStats> = {},
+  mode: FooterStatsMode = "total",
 ): { model: PiModel; adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
   if (!sessionHash || !lastRoutedModel) return undefined;
 
@@ -3839,8 +3916,43 @@ function buildExactRouterStatusEntry(
   const adapter = selectAdapterForModel(model);
   if (!adapter) return undefined;
 
-  const key = makeSessionModelKey(sessionHash, lastRoutedModel.provider, lastRoutedModel.id);
-  return { model, adapter, stats: totalsByModel[modelKey(model)] ?? statsByModel[key] ?? emptyCacheStats() };
+  return {
+    model,
+    adapter,
+    stats: selectFooterStatsForModel(mode, sessionHash, statsByModel, totalsByModel, model) ?? emptyCacheStats(),
+  };
+}
+
+function findBestRouterModelStats(
+  mode: FooterStatsMode,
+  sessionHash: string | undefined,
+  statsByModel: Record<string, CacheStats>,
+  totalsByModel: Record<string, CacheStats>,
+): { model: PiModel; adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
+  const entries = mode === "total"
+    ? Object.entries(totalsByModel)
+    : sessionHash
+      ? Object.entries(statsByModel)
+        .filter(([key]) => key.startsWith(`${sessionHash}:`))
+        .map(([key, stats]) => [key.slice(sessionHash.length + 1), stats] as const)
+      : [];
+  let best: { model: PiModel; adapter: CacheProviderAdapter; stats: CacheStats; total: number } | undefined;
+
+  for (const [modelKeyPart, stats] of entries) {
+    const slashIdx = modelKeyPart.indexOf("/");
+    if (slashIdx < 1 || slashIdx >= modelKeyPart.length - 1) continue;
+    const model = routedModelRefToPiModel({
+      provider: modelKeyPart.slice(0, slashIdx),
+      id: modelKeyPart.slice(slashIdx + 1),
+    });
+    const adapter = selectAdapterForModel(model);
+    if (!adapter) continue;
+    if (!best || stats.totalRequests > best.total) {
+      best = { model, adapter, stats, total: stats.totalRequests };
+    }
+  }
+
+  return best ? { model: best.model, adapter: best.adapter, stats: best.stats } : undefined;
 }
 
 function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
@@ -6558,6 +6670,16 @@ export const __internals_for_tests = {
   parsePersistedRoutedModelRef,
   routedModelRefToPiModel,
   buildExactRouterStatusEntry,
+  findBestRouterModelStats,
+  selectFooterStatsForModel,
+  parseFooterStatsMode,
+  parsePersistedCacheOptimizerConfig,
+  readPersistedFooterMode,
+  writePersistedFooterMode,
+  resolveFooterStatsMode,
+  footerStatsMode,
+  CONFIG_FILE_PATH,
+  FOOTER_MODE_ENV,
   // Routing-provider protocol helpers
   PI_ROUTING_REGISTRY_SYMBOL,
   PI_CACHE_HINTS_SYMBOL,
@@ -6996,50 +7118,6 @@ export default function (pi: ExtensionAPI) {
     await rollOverStatsIfNeeded(ctx);
   }
 
-  /**
-   * Fallback for older persisted files that do not yet carry exact
-   * last-routed-model metadata. When the current model is a router channel
-   * (e.g. router/auto), restorable stats are stored under the real upstream
-   * model's provider/id key, not under router/auto. Find the best valid entry
-   * (highest totalRequests among adapter-detectable model keys) so we can show
-   * meaningful footer content on session_start after reload.
-   */
-  function findBestRouterModelStats(): { adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
-    let best: { adapter: CacheProviderAdapter; stats: CacheStats; total: number } | undefined;
-
-    for (const [modelKeyPart, stats] of Object.entries(cacheStatsTotalsByModel)) {
-      const slashIdx = modelKeyPart.indexOf("/");
-      if (slashIdx < 0 || slashIdx >= modelKeyPart.length - 1) continue;
-      const modelId = modelKeyPart.slice(slashIdx + 1);
-      const providerName = modelKeyPart.slice(0, slashIdx);
-
-      // Construct a minimal model for adapter detection.
-      // Every is*LikeModel function only accesses model.id and model.name
-      // via getModelIdNameTokenValues, so { id, name } is sufficient.
-      const mockModel = {
-        id: modelId,
-        name: modelId,
-        provider: providerName,
-        api: "",
-        baseUrl: "",
-        reasoning: false,
-        input: ["text"],
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: 0,
-        maxTokens: 0,
-      } as PiModel;
-
-      const adapter = selectAdapterForModel(mockModel);
-      if (!adapter) continue;
-
-      if (!best || stats.totalRequests > best.total) {
-        best = { adapter, stats, total: stats.totalRequests };
-      }
-    }
-
-    return best ? { adapter: best.adapter, stats: best.stats } : undefined;
-  }
-
   async function publishStatus(ctx: ExtensionContext, model: PiModel | undefined = ctx.model): Promise<void> {
     syncSessionHash(ctx);
     await rollOverStatsIfNeeded(ctx);
@@ -7049,6 +7127,8 @@ export default function (pi: ExtensionAPI) {
     const adapter = selectAdapterForModel(displayModel);
     const activeIsVirtualRoute = !!routedModel || isVirtualRoutingModel(model, ctx);
     let statusText: string | undefined;
+    const mode = footerStatsMode();
+    const sessionHash = currentSessionHashSet ? currentSessionHash : undefined;
 
     if (!adapter && !routedModel && activeIsVirtualRoute) {
       // On model_select (existing footer), keep the existing cache footer
@@ -7058,11 +7138,17 @@ export default function (pi: ExtensionAPI) {
       // heuristics only when no exact metadata exists.
       if (lastStatusText !== undefined) return;
       const realEntry = buildExactRouterStatusEntry(
-        currentSessionHashSet ? currentSessionHash : undefined,
+        sessionHash,
         cacheStatsByModel,
         lastActualRoutedModel,
         cacheStatsTotalsByModel,
-      ) ?? findBestRouterModelStats();
+        mode,
+      ) ?? findBestRouterModelStats(
+        mode,
+        sessionHash,
+        cacheStatsByModel,
+        cacheStatsTotalsByModel,
+      );
       if (realEntry) {
         const statsText = formatCacheStats(realEntry.adapter, realEntry.stats);
         statusText = runtimeOptimizerEnabled
@@ -7072,10 +7158,11 @@ export default function (pi: ExtensionAPI) {
     }
 
     if (adapter) {
-      // Display provider/model cumulative stats. A model that has never
-      // been used locally shows 0/0. The message_end hook updates both the
-      // current session bucket and this restart-persistent totals bucket.
-      const stats = displayModel ? cacheStatsTotalsByModel[modelKey(displayModel)] : undefined;
+      // Footer mode defaults to daily provider/model totals. Users may select
+      // current-session counters through persistent command config or the env var.
+      const stats = displayModel
+        ? selectFooterStatsForModel(mode, sessionHash, cacheStatsByModel, cacheStatsTotalsByModel, displayModel)
+        : undefined;
       const statsText = formatCacheStats(adapter, stats ?? emptyCacheStats());
       statusText = runtimeOptimizerEnabled ? statsText : `Cache Optimizer disabled · ${statsText}`;
     }
@@ -7520,17 +7607,19 @@ export default function (pi: ExtensionAPI) {
   //             with low-hit diagnosis
   //   stats   — show active model stats bucket, recent trend, usage
   //   compat  — show compat suggestion with file path
+  //   config footer-mode session|total — persist footer mode override
   //   fix     — auto-fix compat issues (writes models.json, requires UI)
   //   reset   — reset current provider/model footer stats bucket (local only)
   //   (no args) — interactive menu (with UI) or help summary
   // ────────────────────────────────────────────────────────────────
   pi.registerCommand("cache-optimizer", {
-    description: "Diagnose Pi cache configuration",
+    description: "Configure and diagnose Pi cache behavior",
     handler: async (args: string, cmdCtx) => {
       syncSessionHash(cmdCtx);
       const selectedModel = cmdCtx.model;
       const model = resolveRouteModel(selectedModel, cmdCtx as unknown as ExtensionContext) ?? selectedModel;
-      const subcommand = args.trim().toLowerCase().split(/\s+/)[0] || "help";
+      const commandParts = args.trim().toLowerCase().split(/\s+/).filter(Boolean);
+      const subcommand = commandParts[0] || "help";
 
       if (subcommand === "enable") {
         setRuntimeOptimizerEnabled(true);
@@ -7570,6 +7659,36 @@ export default function (pi: ExtensionAPI) {
         const samples = sk ? getRecentSamples(sk) : [];
         const output = buildStatsOutput(model, adapter, statsState, samples);
         cmdCtx.ui.notify(output, "info");
+      } else if (subcommand === "config") {
+        const configKey = commandParts[1];
+        const requestedMode = commandParts[2];
+        if (configKey !== "footer-mode" || !requestedMode || !["session", "total"].includes(requestedMode)) {
+          const resolved = resolveFooterStatsMode(persistedFooterStatsMode);
+          cmdCtx.ui.notify(
+            `Usage: /cache-optimizer config footer-mode session|total\n` +
+            `Current footer mode: ${resolved.mode} (${resolved.source})`,
+            "info",
+          );
+          return;
+        }
+
+        const nextMode = requestedMode as FooterStatsMode;
+        try {
+          await writePersistedFooterMode(nextMode);
+          persistedFooterStatsMode = nextMode;
+          lastStatusText = undefined;
+          await publishStatus(cmdCtx as unknown as ExtensionContext, model);
+          const resolved = resolveFooterStatsMode(persistedFooterStatsMode);
+          cmdCtx.ui.notify(
+            `✅ Footer mode set to ${resolved.mode}. Persistent config overrides ${FOOTER_MODE_ENV}.`,
+            "info",
+          );
+        } catch (error) {
+          cmdCtx.ui.notify(
+            `❌ Could not update footer mode config: ${error instanceof Error ? error.message : String(error)}`,
+            "error",
+          );
+        }
       } else if (subcommand === "compat") {
         if (!model) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
@@ -8168,10 +8287,13 @@ export default function (pi: ExtensionAPI) {
         diagnosis.push("  doctor  — Show current model/provider/api/baseUrl/compat and low-hit diagnosis");
         diagnosis.push("  stats   — Show active model stats bucket and recent trend");
         diagnosis.push("  compat  — Show compat suggestion with edit location");
+        diagnosis.push("  config footer-mode session|total — Persist the footer stats mode");
         diagnosis.push("  fix     — Auto-fix compat issues (writes models.json, requires UI)");
         diagnosis.push("  reset   — Reset local provider/model stats for current model (does not affect upstream)");
         diagnosis.push("");
         diagnosis.push(formatOptimizerRuntimeMode());
+        const resolvedFooterMode = resolveFooterStatsMode(persistedFooterStatsMode);
+        diagnosis.push(`Footer stats mode: ${resolvedFooterMode.mode} (${resolvedFooterMode.source})`);
         diagnosis.push("");
         if (model) {
           const displayKey = modelKey(model);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.6.25",
+  "version": "2.7.0",
   "description": "Improve Pi prompt/KV cache hit rates with stable prompts, OpenAI-compatible cache keys, proxy compat warnings, and footer cache stats.",
   "keywords": [
     "pi-package",