pi-cache-optimizer 2.4.8 → 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.
 
@@ -345,7 +347,52 @@ it shows `✅ Compat fully configured.` if the model is an applicable
 third-party proxy, or `ℹ️ Compat check not applicable for this model.`
 otherwise.
 
-When the model is routed through a known router/channel proxy (OpenRouter,
+### `/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.

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

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)
@@ -2842,6 +2976,115 @@ 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);
   const routerNotes = describeRouterChannelDiagnostics(model);
@@ -3042,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) {
@@ -3053,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 };
@@ -3162,6 +3442,7 @@ export default function (pi: ExtensionAPI) {
       // Reset integrity diagnostics on reload
       lastPromptIntegrityWarningAt = 0;
       integrityNotificationShown = false;
+      clearRecentSamples();
       await flushPersistCacheStats(ctx);
       return;
     }
@@ -3345,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);
@@ -3366,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",
@@ -3380,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");
@@ -3402,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",
           ];
@@ -3410,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 {
@@ -3436,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.8",
+  "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",