pi-cache-optimizer 2.4.7 → 2.4.9

package/README.md

@@ -304,11 +304,13 @@ The extension registers a Pi command `/cache-optimizer` for interactive diagnosi
 ```
 /cache-optimizer              — interactive menu (or text help when no UI)
 /cache-optimizer doctor        — show provider, model, API, base URL, compat status
+                                    and low-hit cause diagnosis
+/cache-optimizer stats         — show active model stats bucket and recent trend
 /cache-optimizer compat        — show compat suggestion with edit instructions
 ```
 
 When run without arguments, `/cache-optimizer` shows an interactive selection menu
-(Doctor / Compat / Cancel) when the Pi UI supports it (`ctx.ui.select`). In
+(Doctor / Stats / Compat / Cancel) when the Pi UI supports it (`ctx.ui.select`). In
 non-interactive terminals, it falls back to text help with current model compat
 status.
 
@@ -339,10 +341,85 @@ Edit ~/.pi/agent/models.json -> providers["otokapi"] -> compat (same level as ba
 
 ### `/cache-optimizer compat`
 
-Shows only the compat suggestion for the active model, including file path,
-provider path, and copyable JSON snippet. When no flags are missing, it shows
-`✅ Compat fully configured.` if the model is an applicable third-party proxy,
-or `ℹ️ Compat check not applicable for this model.` otherwise.
+Shows the compat suggestion for the active model, including file path,
+provider path, and copyable JSON snippet. When no compat flags are missing,
+it shows `✅ Compat fully configured.` if the model is an applicable
+third-party proxy, or `ℹ️ Compat check not applicable for this model.`
+otherwise.
+
+### `/cache-optimizer stats`
+
+Displays the active model's stats bucket (`provider/modelId`), today's request
+count (hit/total), cached input tokens vs total input tokens, and the hit rate
+percentage. Also shows recent trend summaries (last 10 and last 30 samples):
+
+```text
+Model key: otokapi/gpt-5.5
+Adapter:   OpenAI cache
+
+── Today ──
+Requests:      3 hit / 10 total · 30%
+Cached tokens: 0.0015M / 0.005M input · 30%
+
+── Recent trend ──
+Recent 10/10: 3/10 hits · 30% tok cached
+Recent 10/10: 3/10 hits · 30% tok cached
+```
+
+If the active model has no adapter match, a friendly message is shown. If
+no samples have been recorded yet in this session, trend shows "no samples".
+
+### Low-hit cause diagnosis
+
+The `/cache-optimizer doctor` output includes a "Cache diagnosis" section
+with prioritized low-hit cause analysis:
+
+1. **Missing compat flags** — flags that enable prompt caching and session-affinity
+   routing are absent.
+2. **Router/channel risk** — multi-backend routing may split the cache across
+   different upstream instances.
+3. **Missing usage fields** — the proxy may not return prompt-level usage
+   fields, causing the footer to under-report hits.
+4. **Recent low trend** — when today's cache hit rate is below 30%,
+   the diagnosis suggests proxy route instability or prompt prefix churn.
+
+For fully configured models that still have low cache hit rates, the diagnosis
+emphasizes sticky routing and upstream cache usage verification rather than
+pointing to compat flags.
+
+### Router/channel diagnostics
+
+For models using OpenAI-compatible APIs (`openai-completions` or
+`openai-responses`) through a non-official base URL, the extension detects
+common router/channel proxy patterns from `provider`, `baseUrl`, and `compat`
+metadata:
+Vercel AI Gateway, LiteLLM, OneAPI/NewAPI/VoAPI, or a generic third-party
+OpenAI-compatible proxy), both `doctor` and `compat` subcommands append
+router/channel diagnostics with targeted recommendations.
+
+### Router/channel diagnostics
+
+For models using OpenAI-compatible APIs (`openai-completions` or
+`openai-responses`) through a non-official base URL, the extension detects
+common router/channel proxy patterns from `provider`, `baseUrl`, and `compat`
+metadata:
+
+| Profile | Detection | Recommendation |
+|---------|-----------|----------------|
+| **OpenRouter** | baseUrl or provider contains `openrouter`/`openrouter.ai` | Fix the upstream provider with `openRouterRouting.only` or `.order` in compat |
+| **Vercel AI Gateway** | baseUrl contains `ai-gateway.vercel.sh` or provider contains `vercel` | Fix the upstream with `vercelGatewayRouting.only` or `.order` in compat |
+| **LiteLLM / OneAPI / NewAPI / VoAPI** | baseUrl or provider contains `litellm`, `oneapi`/`one-api`, `newapi`/`new-api`, `voapi`/`vo-api` | Ensure sticky session routing, forward `prompt_cache_key` + session-affinity headers, return cache usage fields |
+| **Generic third-party proxy** | Any `openai-completions` model with non-official base URL not matching above | General guidance: verify single-upstream routing, forward `prompt_cache_key` + session-affinity headers, return cache usage |
+
+These diagnostics are **advisory only**. They do not participate in adapter
+selection (still id/name-only), prompt_cache_key injection, footer stats, or
+any automated configuration changes. Detection uses only metadata exposed by
+Pi (`provider`, `api`, `baseUrl`, `compat`) — no API keys, prompts, payloads,
+headers, or model outputs are read or exposed.
+
+Official OpenAI (`api.openai.com`) and custom transports (`kiro-api`,
+`anthropic-messages`, `bedrock-converse-stream`) are excluded from router/
+channel diagnostics.
 
 ### Security
 

package/README.zh-CN.md

@@ -298,15 +298,44 @@ Gemini cache 1/2 · 0.18M/0.50M tok (36%)
 ```
 /cache-optimizer              — 交互菜单（无 UI 时显示文字帮助）
 /cache-optimizer doctor        — 显示 provider、model、API、base URL、compat 状态
+                                   及低命中原因诊断
+/cache-optimizer stats         — 显示当前模型的 stats 桶和近期趋势
 /cache-optimizer compat        — 显示 compat 建议和编辑说明
 ```
 
-不带参数时，当 Pi UI 支持时（`ctx.ui.select` 可用），`/cache-optimizer` 会显示交互选择菜单（Doctor / Compat / Cancel）。在非交互终端中，会回退到文字帮助和当前模型 compat 状态。
+不带参数时，当 Pi UI 支持时（`ctx.ui.select` 可用），`/cache-optimizer` 会显示交互选择菜单（Doctor / Stats / Compat / Cancel）。在非交互终端中，会回退到文字帮助和当前模型 compat 状态。
 
 ### `/cache-optimizer doctor`
 
 显示当前模型的 provider、model id、名称、API 类型、base URL、当前 `compat` 标志以及缺少的缓存/session-affinity 标志。如果缺少标志，还会显示可复制的 JSON 片段和精确编辑位置。
 
+输出中还会包含 "Cache diagnosis"（缓存诊断）章节，按优先级分析低命中原因：
+1. **缺少 compat 标志** — 缺少启用 prompt 缓存和 session-affinity 路由的标志。
+2. **路由/渠道风险** — 多后端路由可能导致缓存分散到不同上游实例。
+3. **缺少 usage 字段** — 代理可能未返回 prompt 层级的使用情况字段，导致 footer 低估命中率。
+4. **近期趋势低** — 当今日缓存命中率低于 30% 时，诊断提示代理路由不稳定或 prompt 前缀变化。
+
+对于已完整配置但命中率仍低的模型，诊断会重点提示粘性路由和上游缓存使用验证，而非 compat 标志。
+
+### `/cache-optimizer stats`
+
+显示当前模型的 stats 桶（`provider/modelId`），今日请求计数（命中/总数）、缓存输入令牌 vs 总输入令牌及命中率百分比。同时显示近期趋势摘要（最近 10 条和最近 30 条样本）：
+
+```text
+Model key: otokapi/gpt-5.5
+Adapter:   OpenAI cache
+
+── Today ──
+Requests:      3 hit / 10 total · 30%
+Cached tokens: 0.0015M / 0.005M input · 30%
+
+── Recent trend ──
+Recent 10/10: 3/10 hits · 30% tok cached
+Recent 10/10: 3/10 hits · 30% tok cached
+```
+
+如果当前模型没有匹配的 adapter，显示友好提示。如果尚未记录样本，趋势显示 "no samples"。
+
 如果所有 compat 标志都已配置且适用（第三方 `openai-completions` 代理），输出显示 `✅ Compat fully configured.`。对于不适用 compat 检查的模型（官方 OpenAI、非 `openai-completions` API、custom transport），显示 `ℹ️ Compat check not applicable for this model.`：
 
 ```text
@@ -325,7 +354,24 @@ Edit ~/.pi/agent/models.json -> providers["otokapi"] -> compat (same level as ba
 
 ### `/cache-optimizer compat`
 
-仅显示当前模型的 compat 建议，包括文件路径、provider 路径和可复制 JSON 片段。当没有缺失标志时，如果模型是适用的第三方代理则显示 `✅ Compat fully configured.`，否则显示 `ℹ️ Compat check not applicable for this model.`。
+显示当前模型的 compat 建议，包括文件路径、provider 路径和可复制 JSON 片段。当没有缺失的 compat 标志时，如果模型是适用的第三方代理则显示 `✅ Compat fully configured.`，否则显示 `ℹ️ Compat check not applicable for this model.`。
+
+当模型通过已知的路由器/通道代理（OpenRouter、Vercel AI Gateway、LiteLLM、OneAPI/NewAPI/VoAPI 或通用第三方 OpenAI-compatible 代理）时，`doctor` 和 `compat` 子命令都会附加路由/通道诊断信息和建议。
+
+### 路由/通道诊断
+
+对于通过非官方 base URL 使用 OpenAI-compatible API（`openai-completions` 或 `openai-responses`）的模型，扩展会从 `provider`、`baseUrl` 和 `compat` 元数据中检测常见的路由/通道代理模式：
+
+| 类型 | 检测方式 | 建议 |
+|------|----------|------|
+| **OpenRouter** | baseUrl 或 provider 包含 `openrouter`/`openrouter.ai` | 在 compat 中用 `openRouterRouting.only` 或 `.order` 固定上游 provider |
+| **Vercel AI Gateway** | baseUrl 包含 `ai-gateway.vercel.sh` 或 provider 包含 `vercel` | 在 compat 中用 `vercelGatewayRouting.only` 或 `.order` 固定上游 |
+| **LiteLLM / OneAPI / NewAPI / VoAPI** | baseUrl 或 provider 包含 `litellm`、`oneapi`/`one-api`、`newapi`/`new-api`、`voapi`/`vo-api` | 确保每 session 固定路由，转发 `prompt_cache_key` + session-affinity headers，返回缓存用量字段 |
+| **通用第三方代理** | 任何非官方 base URL 的 `openai-completions` 模型，且不匹配以上类型 | 通用建议：验证单上游路由、转发 `prompt_cache_key` + session-affinity headers、返回缓存用量 |
+
+这些诊断**仅用于建议**。它们不参与 adapter selection（仍基于 id/name）、不参与 `prompt_cache_key` 注入、不参与 footer 统计、也不做任何自动化配置修改。检测仅使用 Pi 暴露的元数据（`provider`、`api`、`baseUrl`、`compat`），不会读取或暴露 API key、prompt、payload、headers 或模型输出。
+
+官方 OpenAI（`api.openai.com`）和 custom transport（`kiro-api`、`anthropic-messages`、`bedrock-converse-stream`）不会触发路由/通道诊断。
 
 ### 安全说明
 

package/index.ts

@@ -147,6 +147,23 @@ type OptimizedSystemPrompt = {
   changed: boolean;
 };
 
+/**
+ * Per-request sample stored for trend analysis and usage-field-missing detection.
+ * Contains only numeric counters and booleans — never message content, prompts,
+ * payloads, headers, API keys, or model outputs.
+ */
+type CacheUsageSample = {
+  timestamp: number;
+  hit: boolean;
+  cachedInputTokens: number;
+  cacheWriteInputTokens: number;
+  totalInputTokens: number;
+  missingUsageFields: boolean;
+};
+
+/** Maximum number of recent samples kept per model key (in-memory only, not persisted). */
+const MAX_RECENT_SAMPLES = 50;
+
 type CacheProviderAdapter = {
   id: CacheProviderId;
   label: string;
@@ -1141,6 +1158,10 @@ function modelKey(model: PiModel): string {
   return `${model.provider}/${model.id}`;
 }
 
+function keyForModelExt(model: { provider: string; id: string }): string {
+  return `${model.provider}/${model.id}`;
+}
+
 function usageRecordFromAssistant(message: unknown): UnknownRecord | undefined {
   return asRecord(getAssistantRecord(message)?.usage);
 }
@@ -2473,6 +2494,119 @@ function formatCacheStats(adapter: CacheProviderAdapter, stats: CacheStats): str
   return `${adapter.label} ${stats.hitRequests}/${stats.totalRequests} · ${formatTokenCount(stats.cachedInputTokens)}/${formatTokenCount(stats.totalInputTokens)} tok${percent}${writeText}`;
 }
 
+/**
+ * Compute a hit-ratio percentage string for a value between 0 and 1.
+ * Returns e.g. "75%", "0%", "100%", or "N/A" for zero total.
+ */
+function formatHitRatio(hits: number, total: number): string {
+  if (total <= 0) return "N/A";
+  return `${Math.round((hits / total) * 100)}%`;
+}
+
+/**
+ * Format a token-to-M abbreviation for stats output.
+ * Example: 1500000 → "1.50M"
+ */
+function formatTokenM(value: number): string {
+  const millions = Math.max(0, Math.round(value)) / 1_000_000;
+  if (millions === 0) return "0";
+  if (millions < 0.01) return millions.toFixed(4);
+  if (millions >= 10) return millions.toFixed(1);
+  return millions.toFixed(2);
+}
+
+/**
+ * Check if an assistant message's usage fields appear to be missing or empty.
+ * Returns true when Pi-normalized fields (input, cacheRead, cacheWrite) are all
+ * absent/zero AND raw usage fields (prompt_tokens, etc.) are also absent/zero
+ * for the given adapter.
+ */
+function hasMissingUsageFields(message: unknown, adapter: CacheProviderAdapter): boolean {
+  const usage = usageRecordFromAssistant(message);
+  if (!usage) return true;
+
+  // Check Pi-normalized fields
+  const input = getNonNegativeNumber(usage, "input");
+  const cacheRead = getNonNegativeNumber(usage, "cacheRead");
+  const cacheWrite = getNonNegativeNumber(usage, "cacheWrite");
+
+  // If Pi-normalized fields exist with non-zero values, usage is present
+  if (cacheRead !== undefined || cacheWrite !== undefined || (input !== undefined && input > 0)) {
+    return false;
+  }
+
+  // Check raw usage for the adapter's provider family
+  const rawUsage = adapter.normalizeUsage(message);
+  if (!rawUsage || (rawUsage.cacheRead === 0 && rawUsage.cacheWrite === 0 && rawUsage.totalInput === 0)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Build a summary string for the recent trend (last N samples).
+ * Example: "Recent 10: 7/10 hits · 65% tok cached · no missing usage"
+ */
+function formatRecentTrendSummary(samples: CacheUsageSample[], maxCount: number): string {
+  const recent = samples.slice(-maxCount);
+  if (recent.length === 0) return `Recent ${maxCount}: no samples yet`;
+
+  const hits = recent.filter((s) => s.hit).length;
+  const totalCached = recent.reduce((sum, s) => sum + s.cachedInputTokens, 0);
+  const totalInput = recent.reduce((sum, s) => sum + s.totalInputTokens, 0);
+  const missingCount = recent.filter((s) => s.missingUsageFields).length;
+
+  const hitRatio = formatHitRatio(hits, recent.length);
+  const tokenRatio = totalInput > 0 ? formatHitRatio(totalCached, totalInput) : "N/A";
+
+  let result = `Recent ${recent.length}/${maxCount}: ${hits}/${recent.length} hits · ${tokenRatio} tok cached`;
+  if (missingCount > 0) {
+    result += ` · ${missingCount} missing usage`;
+  }
+  return result;
+}
+
+/**
+ * Build the output for `/cache-optimizer stats`.
+ */
+function buildStatsOutput(model: PiModel | undefined, adapter: CacheProviderAdapter | undefined, stats: CacheStats | undefined, recentSamples: CacheUsageSample[]): string {
+  const lines: string[] = [];
+
+  if (!model || !adapter) {
+    lines.push("ℹ️ No cache-adapter-matched model active. Select a model with a recognized provider family.");
+    return lines.join("\n");
+  }
+
+  const key = modelKey(model);
+  const currentStats = stats ?? emptyCacheStats();
+
+  lines.push(`Model key: ${key}`);
+  lines.push(`Adapter:   ${adapter.label}`);
+  lines.push("");
+  lines.push("── Today ──");
+  lines.push(`Requests:      ${currentStats.hitRequests} hit / ${currentStats.totalRequests} total · ${formatHitRatio(currentStats.hitRequests, currentStats.totalRequests)}`);
+  lines.push(`Cached tokens: ${formatTokenM(currentStats.cachedInputTokens)}M / ${formatTokenM(currentStats.totalInputTokens)}M input · ${currentStats.totalInputTokens > 0 ? `${Math.round((currentStats.cachedInputTokens / currentStats.totalInputTokens) * 100)}%` : "N/A"}`);
+  if (currentStats.cacheWriteInputTokens > 0) {
+    lines.push(`Cache write:   ${formatTokenM(currentStats.cacheWriteInputTokens)}M tok`);
+  }
+
+  lines.push("");
+  lines.push("── Recent trend ──");
+  lines.push(formatRecentTrendSummary(recentSamples, 10));
+  lines.push(formatRecentTrendSummary(recentSamples, 30));
+
+  // Check if any sample has missingUsageFields flagged
+  const missingAny = recentSamples.some((s) => s.missingUsageFields);
+  if (missingAny) {
+    lines.push("");
+    lines.push("⚠️ Some recent responses had missing or empty cache usage fields. Footer may under-report hits.");
+    lines.push("   The proxy may not return prompt_cache_hit_tokens or usage.input/cacheRead in responses.");
+  }
+
+  return lines.join("\n");
+}
+
 function getErrorCode(error: unknown): string | undefined {
   return typeof error === "object" && error !== null && "code" in error
     ? String((error as { code?: unknown }).code)
@@ -2621,6 +2755,171 @@ function isCompatCheckApplicable(model: PiModel): boolean {
   return lower(model.api) === "openai-completions" && !isOfficialOpenAIBaseUrl(model);
 }
 
+/**
+ * Detect router / channel profiles from a PiModel and return diagnostic notes.
+ *
+ * This function is advisory only — it does NOT participate in adapter selection,
+ * prompt_cache_key injection, or footer stats. It inspects provider, api, baseUrl,
+ * and compat to identify common proxy/router patterns where cache performance may
+ * be degraded due to multi-backend routing.
+ *
+ * Known profiles (checked in order):
+ *   1. OpenRouter — baseUrl or provider id matching openrouter.ai / openrouter
+ *   2. Vercel AI Gateway — baseUrl matching ai-gateway.vercel.sh, or provider
+ *      matching vercel / vercel-ai-gateway
+ *   3. LiteLLM / OneAPI / NewAPI / VoAPI — baseUrl or provider matching litellm,
+ *      oneapi, one-api, newapi, new-api, voapi, vo-api (self-hosted aggregation)
+ *   4. Generic third-party OpenAI-compatible proxy — any openai-completions model
+ *      with a non-official base URL that does not match a higher-profile above.
+ *
+ * Official OpenAI (api.openai.com) and custom transports (kiro-api, anthropic-messages,
+ * bedrock-converse-stream) do NOT produce notes.
+ */
+function describeRouterChannelDiagnostics(model: PiModel): string[] {
+  const notes: string[] = [];
+  const api = lower(model.api);
+  const baseUrl = lower(model.baseUrl || "");
+  const provider = lower(model.provider);
+
+  // Only OpenAI-compatible APIs are applicable for router/channel diagnostics.
+  // Custom transports like kiro-api, anthropic-messages, bedrock-converse-stream
+  // or non-OpenAI APIs are excluded.
+  if (api !== "openai-completions" && api !== "openai-responses") {
+    return notes;
+  }
+
+  // Official OpenAI bypass — no notes needed.
+  if (isOfficialOpenAIBaseUrl(model)) {
+    return notes;
+  }
+
+  // ── 1. OpenRouter ────────────────────────────────────────────────
+  if (
+    baseUrl.includes("openrouter.ai") ||
+    baseUrl.includes("openrouter") ||
+    provider.includes("openrouter")
+  ) {
+    const compat = getCompat(model);
+    const hasOnly = !!(compat as Record<string, unknown>)["openRouterRouting"]?.only;
+    const hasOrder = !!(compat as Record<string, unknown>)["openRouterRouting"]?.order;
+
+    notes.push(
+      "🔀 Router/channel: OpenRouter detected. OpenRouter is a multi-provider router; " +
+      "low cache hit rates are common when each turn lands on a different upstream provider.",
+    );
+
+    if (!hasOnly && !hasOrder) {
+      notes.push(
+        "   Suggestion: Add an openRouterRouting config to fix the upstream provider. " +
+        "Example for models.json -> providers[\"<providerId>\"] -> compat:",
+      );
+      notes.push(
+        `   { "sendSessionAffinityHeaders": true, "supportsLongCacheRetention": true, ` +
+        `"openRouterRouting": { "only": ["<provider-slug>"] } }`,
+      );
+      notes.push(
+        '   Replace <provider-slug> with the actual OpenRouter provider slug (e.g. "openai", "anthropic").',
+      );
+      notes.push(
+        "   Alternatively, use openRouterRouting.order: [\"<provider-slug>\", \"...\"] for fallback order. " +
+        "Only set supportsLongCacheRetention if your upstream supports long cache retention.",
+      );
+    }
+
+    return notes;
+  }
+
+  // ── 2. Vercel AI Gateway ─────────────────────────────────────────
+  if (
+    baseUrl.includes("ai-gateway.vercel.sh") ||
+    provider.includes("vercel") ||
+    provider.includes("vercel-ai-gateway")
+  ) {
+    const compat = getCompat(model);
+    const hasOnly = !!(compat as Record<string, unknown>)["vercelGatewayRouting"]?.only;
+    const hasOrder = !!(compat as Record<string, unknown>)["vercelGatewayRouting"]?.order;
+
+    notes.push(
+      "🔀 Router/channel: Vercel AI Gateway detected. The gateway may route to different " +
+      "provider endpoints per request, reducing cache locality.",
+    );
+
+    if (!hasOnly && !hasOrder) {
+      notes.push(
+        "   Suggestion: Add a vercelGatewayRouting config to fix the upstream. " +
+        "Example for models.json -> providers[\"<providerId>\"] -> compat:",
+      );
+      notes.push(
+        `   { "sendSessionAffinityHeaders": true, "supportsLongCacheRetention": true, ` +
+        `"vercelGatewayRouting": { "only": ["<provider-id>"] } }`,
+      );
+      notes.push(
+        "   Replace <provider-id> with the actual Vercel provider ID (e.g. \"openai\").",
+      );
+      notes.push(
+        "   Only set supportsLongCacheRetention if your upstream supports it.",
+      );
+    }
+
+    return notes;
+  }
+
+  // ── 3. LiteLLM / OneAPI / NewAPI / VoAPI (self-hosted aggregation) ──
+  const aggregationPatterns = ["litellm", "oneapi", "one-api", "newapi", "new-api", "voapi", "vo-api"];
+  if (
+    aggregationPatterns.some((p) => baseUrl.includes(p)) ||
+    aggregationPatterns.some((p) => provider.includes(p))
+  ) {
+    notes.push(
+      "🔀 Router/channel: Self-hosted aggregation proxy detected (LiteLLM / OneAPI / NewAPI / VoAPI). " +
+      "These proxies route to multiple upstream accounts or instances, which can split the cache.",
+    );
+    notes.push(
+      "   Suggestions:",
+    );
+    notes.push(
+      "   • Ensure the proxy can fix to a single upstream per session (session_id affinity).",
+    );
+    notes.push(
+      "   • Forward prompt_cache_key and session-affinity headers to the upstream.",
+    );
+    notes.push(
+      "   • Return cache usage fields (prompt_cache_hit_tokens, etc.) in the response.",
+    );
+    notes.push(
+      `   Example compat: { "sendSessionAffinityHeaders": true, "supportsLongCacheRetention": true }`,
+    );
+
+    return notes;
+  }
+
+  // ── 4. Generic third-party OpenAI-compatible proxy ─────────────────
+  if (api === "openai-completions" && baseUrl) {
+    const missing = describeMissingOpenAICompatibleProxyCompat(model);
+    notes.push(
+      "🔀 Router/channel: Third-party OpenAI-compatible proxy. If cache hit rates are low:",
+    );
+    notes.push(
+      "   • Verify the proxy routes to the same upstream account/instance per session.",
+    );
+    notes.push(
+      "   • Ensure the proxy forwards prompt_cache_key and sends session-affinity headers.",
+    );
+    notes.push(
+      "   • Check that the proxy returns cache usage fields (prompt_cache_hit_tokens etc.).",
+    );
+    if (missing.length > 0) {
+      notes.push(
+        `   • The compat flags above (${missing.join(", ")}) are recommended for cache stability.`,
+      );
+    }
+
+    return notes;
+  }
+
+  return notes;
+}
+
 function buildDoctorDiagnosis(model: PiModel): string {
   const lines: string[] = [];
   lines.push(`Provider: ${model.provider}`);
@@ -2648,6 +2947,15 @@ function buildDoctorDiagnosis(model: PiModel): string {
     lines.push("ℹ️ Compat check not applicable for this model.");
   }
 
+  // ── Router/channel diagnostics ──
+  const routerNotes = describeRouterChannelDiagnostics(model);
+  if (routerNotes.length > 0) {
+    lines.push("");
+    for (const note of routerNotes) {
+      lines.push(note);
+    }
+  }
+
   // ── Integrity diagnostics ──
   if (lastPromptIntegrityWarningAt > 0) {
     const ago = Date.now() - lastPromptIntegrityWarningAt;
@@ -2668,23 +2976,157 @@ function buildDoctorDiagnosis(model: PiModel): string {
   return lines.join("\n");
 }
 
+/**
+ * Build a "Cache diagnosis" section for low-hit causes, appended to doctor output.
+ * This is a separate function because it depends on per-session state (recent samples,
+ * per-model stats) that is not available at the module level.
+ */
+function buildLowHitDiagnosis(
+  model: PiModel,
+  adapter: CacheProviderAdapter | undefined,
+  stats: CacheStats | undefined,
+  samples: CacheUsageSample[],
+): string[] {
+  const lines: string[] = [];
+
+  // 1. Missing compat flags (reuse existing check)
+  const missingCompat = describeMissingOpenAICompatibleProxyCompat(model);
+
+  // 2. Router/channel risk (reuse existing check)
+  const routerNotes = describeRouterChannelDiagnostics(model);
+
+  // 3. Recent samples missing usage fields
+  const missingUsageSamples = samples.filter((s) => s.missingUsageFields).length;
+
+  // 4. Recent trend analysis
+  const recent10 = samples.slice(-10);
+  const recent10Hits = recent10.filter((s) => s.hit).length;
+  const recent10Total = recent10.length;
+  const recent10Cached = recent10.reduce((sum, s) => sum + s.cachedInputTokens, 0);
+  const recent10Input = recent10.reduce((sum, s) => sum + s.totalInputTokens, 0);
+
+  // 5. Today's overall trend from persisted stats
+  const todayStats = stats ?? emptyCacheStats();
+
+  const hasMissingCompat = missingCompat.length > 0;
+  const hasRouterRisk = routerNotes.length > 0;
+  const hasUsageMissing = missingUsageSamples > 0;
+
+  // Determine if there are actual issues worth flagging
+  const hasActualIssues = hasMissingCompat || hasUsageMissing ||
+    // Low hit trend (today total > 3 and hit ratio < 30%)
+    (todayStats.totalRequests > 3 && todayStats.totalInputTokens > 0 &&
+     (todayStats.cachedInputTokens / todayStats.totalInputTokens) < 0.3) ||
+    // Low hit rate in recent samples (recent10Total >= 3 and all misses)
+    (recent10Total >= 3 && recent10Hits === 0);
+
+  // Skip section if no issues
+  if (!hasActualIssues && !(hasRouterRisk && (hasMissingCompat || hasUsageMissing))) {
+    return lines;
+  }
+
+  lines.push("");
+  lines.push("── Cache diagnosis ──");
+
+  // Priority 1: missing compat flags
+  if (hasMissingCompat) {
+    lines.push(`⚠️  Missing compat flags: ${missingCompat.join(", ")}`);
+    lines.push("   These flags enable prompt caching and session-affinity routing.");
+    lines.push("   Run /cache-optimizer compat for edit instructions.");
+  }
+
+  // Priority 2: router/channel risk (only flag when there are other issues)
+  // Router notes are already shown in the main doctor output, so we only
+  // mention them in the diagnosis section when they compound a problem.
+  if (hasRouterRisk && (hasMissingCompat || hasUsageMissing || hasActualIssues)) {
+    lines.push("🔀 Router/channel proxy detected — see routing notes above.");
+  }
+
+  // Priority 3: usage fields missing
+  if (hasUsageMissing) {
+    lines.push(`⚠️  ${missingUsageSamples}/${samples.length} recent responses had missing/empty usage fields.`);
+    lines.push("   Footer may under-report cache hit rate.");
+    lines.push("   Verify the proxy returns prompt-level usage (prompt_tokens, input_tokens_details).");
+  }
+
+  // Priority 4: recent trend low
+  if (recent10Total > 0) {
+    const hitRatio = recent10Input > 0 ? Math.round((recent10Cached / recent10Input) * 100) : 0;
+    const todayHitRatio = todayStats.totalInputTokens > 0
+      ? Math.round((todayStats.cachedInputTokens / todayStats.totalInputTokens) * 100)
+      : 0;
+
+    if (recent10Hits === 0 && todayStats.totalRequests > 3 && todayHitRatio < 30) {
+      lines.push(`📉 Cache hit rate is low: ${todayHitRatio}% today (${recent10Total} recent samples).`);
+      lines.push("   Likely causes: proxy routing to different backends per request,");
+      lines.push("   or prompt prefix changes across turns.");
+      lines.push("   Verify session affinity (sendSessionAffinityHeaders) and long cache retention.");
+    } else if (todayHitRatio < 30 && todayStats.totalRequests > 3) {
+      lines.push(`📉 Cache hit rate is low: ${todayHitRatio}% today (${todayStats.totalRequests} total requests).`);
+      lines.push("   Check compat flags and proxy upstream routing.");
+    }
+
+    // Show brief trend summary if there are enough samples
+    if (recent10Total >= 3) {
+      const trend = formatRecentTrendSummary(samples, 10);
+      lines.push(`📊 ${trend}`);
+    }
+  }
+
+  // For fully configured but low hit models, emphasize sticky routing
+  if (!hasMissingCompat && !hasRouterRisk && todayStats.totalRequests > 3 && todayHitRatio < 30) {
+    lines.push("💡 Compat is configured but cache hit rate remains low.");
+    lines.push("   Possible causes:");
+    lines.push("   • Proxy still routes to multiple backends — check session affinity on the proxy side.");
+    lines.push("   • Prompt prefix varies per turn — check dynamic context in system prompt.");
+    lines.push("   • Provider does not return cache usage fields — footer can't measure hits.");
+  }
+
+  return lines;
+}
+
 function buildCompatDiagnosis(model: PiModel): string | undefined {
   const missing = describeMissingOpenAICompatibleProxyCompat(model);
-  if (missing.length === 0) return undefined;
+  const routerNotes = describeRouterChannelDiagnostics(model);
+
+  if (missing.length === 0 && routerNotes.length === 0) return undefined;
 
   const key = modelKey(model);
-  const slashIdx = key.indexOf("/");
-  const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
-  const suggestion = Object.fromEntries(missing.map((f) => [f, true]));
-  const modelsJsonPath = getModelsJsonDisplayPath();
-  return (
-    `Active model: ${key}\n` +
-    `Missing: ${missing.join(", ")}\n\n` +
-    `Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat` +
-    ` (at the same level as baseUrl/api/apiKey/models) and add:\n` +
-    `${JSON.stringify(suggestion, null, 2)}\n\n` +
-    `Only enable if your endpoint supports them.`
-  );
+  const lines: string[] = [];
+
+  if (missing.length > 0) {
+    const slashIdx = key.indexOf("/");
+    const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+    const suggestion = Object.fromEntries(missing.map((f) => [f, true]));
+    const modelsJsonPath = getModelsJsonDisplayPath();
+    lines.push(`Active model: ${key}`);
+    lines.push(`Missing: ${missing.join(", ")}`);
+    lines.push("");
+    lines.push(`Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat`);
+    lines.push(`(at the same level as baseUrl/api/apiKey/models) and add:`);
+    lines.push(JSON.stringify(suggestion, null, 2));
+    lines.push("");
+    lines.push(`Only enable if your endpoint supports them.`);
+  }
+
+  // When compat is fully configured but router notes exist, prefix the status.
+  if (routerNotes.length > 0 && missing.length === 0) {
+    if (isCompatCheckApplicable(model)) {
+      lines.push("✅ Compat fully configured.");
+    } else {
+      lines.push("ℹ️ Compat check not applicable for this model.");
+    }
+    lines.push("");
+  }
+
+  if (routerNotes.length > 0) {
+    if (missing.length > 0) lines.push("");
+    for (const note of routerNotes) {
+      lines.push(note);
+    }
+  }
+
+  return lines.join("\n");
 }
 
 // Internal helpers exported only so the task verification script
@@ -2835,6 +3277,7 @@ export const __internals_for_tests = {
   isCompatCheckApplicable,
   buildDoctorDiagnosis,
   buildCompatDiagnosis,
+  describeRouterChannelDiagnostics,
   // Cache stats helpers (module-level, usable from verify script)
   addUsageToCacheStats,
   formatCacheStats,
@@ -2842,6 +3285,15 @@ export const __internals_for_tests = {
   emptyAllCacheStats,
   parseCacheStats,
   parsePersistedCacheStats,
+  // Recent sample / stats output / diagnosis helpers
+  MAX_RECENT_SAMPLES,
+  buildStatsOutput,
+  buildLowHitDiagnosis,
+  formatRecentTrendSummary,
+  formatHitRatio,
+  formatTokenM,
+  hasMissingUsageFields,
+  keyForModelExt,
 };
 
 export default function (pi: ExtensionAPI) {
@@ -2853,7 +3305,35 @@ export default function (pi: ExtensionAPI) {
   let persistTimer: ReturnType<typeof setTimeout> | null = null;
   let integrityNotificationShown = false;
   const PERSIST_DEBOUNCE_MS = 2000;
+  /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
+  const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
+
+  function recordRecentSample(modelKeyStr: string, usage: UsageSnapshot, missingUsageFields: boolean): void {
+    let samples = recentSamplesByModelKey.get(modelKeyStr);
+    if (!samples) {
+      samples = [];
+      recentSamplesByModelKey.set(modelKeyStr, samples);
+    }
+    samples.push({
+      timestamp: Date.now(),
+      hit: usage.cacheRead > 0,
+      cachedInputTokens: usage.cacheRead,
+      cacheWriteInputTokens: usage.cacheWrite,
+      totalInputTokens: usage.totalInput,
+      missingUsageFields,
+    });
+    if (samples.length > MAX_RECENT_SAMPLES) {
+      samples.splice(0, samples.length - MAX_RECENT_SAMPLES);
+    }
+  }
+
+  function getRecentSamples(modelKeyStr: string): CacheUsageSample[] {
+    return recentSamplesByModelKey.get(modelKeyStr) ?? [];
+  }
 
+  function clearRecentSamples(): void {
+    recentSamplesByModelKey.clear();
+  }
 
   function getCacheStatsState(): CacheStatsState {
     return { statsByModel: cacheStatsByModel, legacyFamily: cacheStatsLegacyFamily };
@@ -2962,6 +3442,7 @@ export default function (pi: ExtensionAPI) {
       // Reset integrity diagnostics on reload
       lastPromptIntegrityWarningAt = 0;
       integrityNotificationShown = false;
+      clearRecentSamples();
       await flushPersistCacheStats(ctx);
       return;
     }
@@ -3145,6 +3626,16 @@ export default function (pi: ExtensionAPI) {
     if (!adapter) return;
 
     const usage = adapter.normalizeUsage(event.message);
+
+    // Record recent sample (even when usage is missing, for trend diagnosis)
+    if (ctx.model) {
+      const key = modelKey(ctx.model);
+      const missingFields = usage === undefined || (usage.cacheRead === 0 && usage.cacheWrite === 0 && usage.totalInput === 0)
+        ? true
+        : hasMissingUsageFields(event.message, adapter);
+      recordRecentSample(key, usage ?? { cacheRead: 0, cacheWrite: 0, totalInput: 0 }, missingFields);
+    }
+
     if (!usage) return;
 
     await rollOverStatsIfNeeded(ctx);
@@ -3166,8 +3657,10 @@ export default function (pi: ExtensionAPI) {
   // Register /cache-optimizer command
   // Subcommands:
   //   doctor  — show current model/provider/api/baseUrl/compat status
+  //             with low-hit diagnosis
+  //   stats   — show active model stats bucket, recent trend, usage
   //   compat  — show compat suggestion with file path
-  //   (no args) — show help summary + current diagnosis
+  //   (no args) — interactive menu (with UI) or help summary
   // ────────────────────────────────────────────────────────────────
   pi.registerCommand("cache-optimizer", {
     description: "Diagnose Pi cache configuration",
@@ -3180,7 +3673,26 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
           return;
         }
-        cmdCtx.ui.notify(buildDoctorDiagnosis(model), "info");
+        const diagnosis = buildDoctorDiagnosis(model);
+        const adapter = selectAdapterForModel(model);
+        const statsState = model ? cacheStatsByModel[modelKey(model)] : undefined;
+        const samples = model ? getRecentSamples(modelKey(model)) : [];
+        const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
+        const fullDiagnosis = lowHitLines.length > 0
+          ? diagnosis + "\n" + lowHitLines.join("\n")
+          : diagnosis;
+        cmdCtx.ui.notify(fullDiagnosis, "info");
+      } else if (subcommand === "stats") {
+        if (!model) {
+          cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+          return;
+        }
+        const adapter = selectAdapterForModel(model);
+        const key = model ? modelKey(model) : undefined;
+        const statsState = key ? cacheStatsByModel[key] : undefined;
+        const samples = model ? getRecentSamples(modelKey(model)) : [];
+        const output = buildStatsOutput(model, adapter, statsState, samples);
+        cmdCtx.ui.notify(output, "info");
       } else if (subcommand === "compat") {
         if (!model) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
@@ -3202,6 +3714,7 @@ export default function (pi: ExtensionAPI) {
         if (cmdCtx.hasUI) {
           const menuOptions = [
             "🩺 Doctor — Show current model cache configuration",
+            "📊 Stats — Show active model stats bucket and trend",
             "⚙️  Compat — Show compat suggestion with edit instructions",
             "❌ Cancel",
           ];
@@ -3210,9 +3723,28 @@ export default function (pi: ExtensionAPI) {
             if (!model) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
             } else {
-              cmdCtx.ui.notify(buildDoctorDiagnosis(model), "info");
+              const diagnosis = buildDoctorDiagnosis(model);
+              const adapter = selectAdapterForModel(model);
+              const statsState = model ? cacheStatsByModel[modelKey(model)] : undefined;
+              const samples = model ? getRecentSamples(modelKey(model)) : [];
+              const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
+              const fullDiagnosis = lowHitLines.length > 0
+                ? diagnosis + "\n" + lowHitLines.join("\n")
+                : diagnosis;
+              cmdCtx.ui.notify(fullDiagnosis, "info");
             }
           } else if (choice === menuOptions[1]) {
+            if (!model) {
+              cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+            } else {
+              const adapter = selectAdapterForModel(model);
+              const key = model ? modelKey(model) : undefined;
+              const statsState = key ? cacheStatsByModel[key] : undefined;
+              const samples = model ? getRecentSamples(modelKey(model)) : [];
+              const output = buildStatsOutput(model, adapter, statsState, samples);
+              cmdCtx.ui.notify(output, "info");
+            }
+          } else if (choice === menuOptions[2]) {
             if (!model) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
             } else {
@@ -3236,7 +3768,8 @@ export default function (pi: ExtensionAPI) {
         // Fallback: text help when no interactive UI
         const diagnosis: string[] = [];
         diagnosis.push("📋 /cache-optimizer commands:");
-        diagnosis.push("  doctor  — Show current model/provider/api/baseUrl/compat status");
+        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("");
         if (model) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.4.7",
+  "version": "2.4.9",
   "description": "Pi extension that improves provider-side KV/prompt cache hit rates (DeepSeek, OpenAI, Claude, Gemini) by reordering the system prompt, requesting long retention, and showing footer cache stats. Renamed from pi-deepseek-cache-optimizer.",
   "keywords": [
     "pi-package",