pi-cache-optimizer 2.4.6 → 2.4.8

package/README.md

@@ -56,6 +56,36 @@ This release keeps the original DeepSeek behavior and adds read-only stats adapt
 | Microsoft Phi | Model id/name contains `phi-` prefix, or pattern `phi` with safe boundaries | `Phi cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
 | AI21 Jamba | Model id/name contains `jamba` or `ai21` | `Jamba cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
 | Upstage Solar | Model id/name contains `solar` or `upstage` | `Solar cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Perplexity / Sonar | Model id/name contains `sonar`, `perplexity`, or pattern `pplx` with safe boundaries | `Sonar cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Amazon Nova | Model id/name contains `amazon-nova`, or pattern `nova` with safe boundaries | `Nova cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Reka | Model id/name contains `reka` | `Reka cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Falcon / TII | Model id/name contains `falcon` or `tiiuae` (not bare `tii`) | `Falcon cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Databricks DBRX | Model id/name contains `dbrx` or `databricks` | `DBRX cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| MosaicML MPT | Model id/name contains `mosaicml`, `mpt-` prefix, or pattern `mpt` with safe boundaries | `MPT cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| StableLM / Stability AI | Model id/name contains `stablelm`, `stable-lm`, or `stability-ai` | `StableLM cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| BAAI / Aquila | Model id/name contains `aquila` or `baai` | `Aquila cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| LG EXAONE | Model id/name contains `exaone` | `EXAONE cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Naver HyperCLOVA X | Model id/name contains `hyperclova` or `clova-x` (conservative, not bare `clova`/`naver`) | `HyperCLOVA cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Aleph Alpha Luminous | Model id/name contains `luminous`, `aleph-alpha`, or pattern `aleph` with safe boundaries | `Luminous cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Nous / Hermes / OpenHermes | Model id/name contains `nous`, `hermes`, or `openhermes` | `Hermes cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| IBM Granite | Model id/name contains `granite` or `ibm-granite` | `Granite cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Snowflake Arctic | Model id/name contains `snowflake-arctic`, or safe-boundary pattern `arctic` | `Arctic cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Huawei Pangu / 盘古 | Model id/name contains `pangu`, `pan-gu`, `盘古`, or `huawei-pangu` | `Pangu cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| SenseTime SenseNova / 商汤 | Model id/name contains `sensenova`, `sense-nova`, `sensechat`, or `商汤` | `SenseNova cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| 360 Zhinao / 智脑 | Model id/name contains `360gpt`, `360-gpt`, `zhinao`, or `智脑` (no bare `360`) | `Zhinao cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| OpenBMB MiniCPM | Model id/name contains `minicpm`, `mini-cpm`, or `openbmb` | `MiniCPM cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| XVERSE | Model id/name contains `xverse` | `XVERSE cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| OrionStar Orion | Model id/name contains `orionstar`, `orion-star`, or safe-boundary pattern `orion` | `Orion cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| OpenChat | Model id/name contains `openchat` | `OpenChat cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Vicuna | Model id/name contains `vicuna` | `Vicuna cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| WizardLM / WizardCoder | Model id/name contains `wizardlm`, `wizard-lm`, `wizardcoder`, or `wizard-coder` | `Wizard cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Zephyr | Model id/name contains `zephyr` | `Zephyr cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Dolphin | Model id/name contains `dolphin` | `Dolphin cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| OpenOrca | Model id/name contains `openorca` or `open-orca` | `OpenOrca cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Starling | Model id/name contains `starling` | `Starling cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| BLOOM / BigScience | Model id/name contains `bloom` or `bigscience` | `BLOOM cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| RWKV | Model id/name contains `rwkv` | `RWKV cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
+| Cohere Aya | Model id/name contains `aya-expanse`, or safe-boundary pattern `aya` (avoid `maya`/`payara`) | `Aya cache` | Pi-normalized usage, or raw OpenAI-shaped fields when visible |
 | Anthropic / Claude | Model id/name contains `anthropic` or `claude` | `Claude cache` | Pi-normalized usage, or raw `cache_read_input_tokens`, `cache_creation_input_tokens`, `input_tokens` |
 | Gemini / Vertex | Model id/name contains `gemini` or `vertex` | `Gemini cache` | Pi-normalized usage, or raw Gemini/Vertex cached-content token metadata when visible |
 
@@ -309,10 +339,40 @@ 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.
+
+When the model is routed through a known router/channel proxy (OpenRouter,
+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

@@ -59,6 +59,36 @@
 | Microsoft Phi | model id/name 包含 `phi-` 前缀，或安全边界内 `phi` 模式 | `Phi cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
 | AI21 Jamba | model id/name 包含 `jamba` 或 `ai21` | `Jamba cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
 | Upstage Solar | model id/name 包含 `solar` 或 `upstage` | `Solar cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Perplexity / Sonar | model id/name 包含 `sonar`、`perplexity`，或安全边界内 `pplx` 模式 | `Sonar cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Amazon Nova | model id/name 包含 `amazon-nova`，或安全边界内 `nova` 模式 | `Nova cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Reka | model id/name 包含 `reka` | `Reka cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Falcon / TII | model id/name 包含 `falcon` 或 `tiiuae`（不含裸 `tii`） | `Falcon cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Databricks DBRX | model id/name 包含 `dbrx` 或 `databricks` | `DBRX cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| MosaicML MPT | model id/name 包含 `mosaicml`、`mpt-` 前缀，或安全边界内 `mpt` 模式 | `MPT cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| StableLM / Stability AI | model id/name 包含 `stablelm`、`stable-lm` 或 `stability-ai` | `StableLM cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| BAAI / Aquila | model id/name 包含 `aquila` 或 `baai` | `Aquila cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| LG EXAONE | model id/name 包含 `exaone` | `EXAONE cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Naver HyperCLOVA X | model id/name 包含 `hyperclova` 或 `clova-x`（保守检测，不含裸 `clova`/`naver`） | `HyperCLOVA cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Aleph Alpha Luminous | model id/name 包含 `luminous`、`aleph-alpha`，或安全边界内 `aleph` 模式 | `Luminous cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Nous / Hermes / OpenHermes | model id/name 包含 `nous`、`hermes` 或 `openhermes` | `Hermes cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| IBM Granite | model id/name 包含 `granite` 或 `ibm-granite` | `Granite cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Snowflake Arctic | model id/name 包含 `snowflake-arctic`，或安全边界内 `arctic` 模式 | `Arctic cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Huawei Pangu / 盘古 | model id/name 包含 `pangu`、`pan-gu`、`盘古` 或 `huawei-pangu` | `Pangu cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| SenseTime SenseNova / 商汤 | model id/name 包含 `sensenova`、`sense-nova`、`sensechat` 或 `商汤` | `SenseNova cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| 360 Zhinao / 智脑 | model id/name 包含 `360gpt`、`360-gpt`、`zhinao` 或 `智脑`（不含裸 `360`） | `Zhinao cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| OpenBMB MiniCPM | model id/name 包含 `minicpm`、`mini-cpm` 或 `openbmb` | `MiniCPM cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| XVERSE | model id/name 包含 `xverse` | `XVERSE cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| OrionStar Orion | model id/name 包含 `orionstar`、`orion-star`，或安全边界内 `orion` 模式 | `Orion cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| OpenChat | model id/name 包含 `openchat` | `OpenChat cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Vicuna | model id/name 包含 `vicuna` | `Vicuna cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| WizardLM / WizardCoder | model id/name 包含 `wizardlm`、`wizard-lm`、`wizardcoder` 或 `wizard-coder` | `Wizard cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Zephyr | model id/name 包含 `zephyr` | `Zephyr cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Dolphin | model id/name 包含 `dolphin` | `Dolphin cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| OpenOrca | model id/name 包含 `openorca` 或 `open-orca` | `OpenOrca cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Starling | model id/name 包含 `starling` | `Starling cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| BLOOM / BigScience | model id/name 包含 `bloom` 或 `bigscience` | `BLOOM cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| RWKV | model id/name 包含 `rwkv` | `RWKV cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
+| Cohere Aya | model id/name 包含 `aya-expanse`，或安全边界内 `aya` 模式（避免 `maya`/`payara`） | `Aya cache` | Pi 归一化 usage，或可见 OpenAI 形状字段 |
 | Anthropic / Claude | model id/name 包含 `anthropic` 或 `claude` | `Claude cache` | Pi 归一化 usage，或可见 raw 字段 `cache_read_input_tokens`、`cache_creation_input_tokens`、`input_tokens` |
 | Gemini / Vertex | model id/name 包含 `gemini` 或 `vertex` | `Gemini cache` | Pi 归一化 usage，或可见 Gemini/Vertex cached-content token metadata |
 
@@ -295,7 +325,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`）不会触发路由/通道诊断。
 
 ### 安全说明