fix(usage): report cache hits and real input tokens to clients

`message_start` 只能带本地估算的 input_tokens（此刻上游还没回话），而收尾的
`message_delta` 只发了 output_tokens —— 上游 finish 事件里的缓存命中明细与真实
输入量被整个丢掉。Anthropic 兼容客户端（实测 ZCode）因此记录的 input 是估算值、
cache_read 恒为 0，用量界面上完全看不到缓存命中，而代理自己其实拿到了准确值。

- Anthropic 路由：收尾 delta 补 input_tokens / cache_read_input_tokens /
  cache_creation_input_tokens；非流式 buildAnthropicResponse 同步补齐
- OpenAI 路由：非流式响应与 include_usage 收尾 chunk 补
  prompt_tokens_details.cached_tokens
- 缓存拆分收敛到 usage.splitInput 导出复用，去掉 adapter 内的重复实现
  （非流式路径此前压根没做拆分，正是该 bug 的成因）
- 集成 mock 带缓存明细 + 三条路径断言，全量 229 项通过

版本 4.11.0 -> 4.11.1

Author: wjf1

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 所有主要版本更新都记录在此文件。
 
+## [4.11.1] - 2026-09-14
+
+### 修复
+- **客户端看不到缓存命中，输入量还是估算值** — Anthropic 路由的流式响应里，`message_start` 在拿到上游 usage 之前就已发出（`input_tokens` 只能是本地估算），而真正的收尾 `message_delta` 只带了 `output_tokens`：上游在 `finish` 事件里给出的**缓存命中明细**（`usageAcc.cacheReadTokens`）与**真实输入量**被整个丢掉。后果是 Anthropic 兼容客户端（实测 ZCode）记录的 `input_tokens` 是估算值、`cache_read_input_tokens` 恒为 0，用量界面上完全看不到缓存命中——而代理自己其实拿到了准确值（缓存读占输入 99%）。现在收尾 delta 一并补报 `input_tokens` / `cache_read_input_tokens` / `cache_creation_input_tokens`；非流式 `buildAnthropicResponse` 同样补齐。
+- 同源的 OpenAI 路由缺字段：非流式响应与流式 `include_usage` 收尾 chunk 都没有缓存明细，现补 `prompt_tokens_details.cached_tokens`。
+
+### 兼容性
+- **`usage` 新增字段，纯增量，既有字段语义不变** — Anthropic 路由新增 `cache_read_input_tokens` / `cache_creation_input_tokens`（流式在收尾 `message_delta`，非流式在 `message.usage`）；OpenAI 路由新增 `prompt_tokens_details.cached_tokens`。`input_tokens` / `prompt_tokens` 仍是**含缓存读的输入总量**，缓存字段是其中的子集，客户端不要重复相加。
+
+### 清理（行为不变）
+- 缓存拆分逻辑收敛到 `usage.ts` 的 `splitInput` 并导出复用，删掉 adapter 内的重复实现（此前非流式路径压根没做这一步，正是上面那个 bug 的成因）；`StreamEncoderState` 补 `cacheWriteTokens`，与既有 `cacheReadTokens` / `noCacheTokens` 对齐。
+
+### 测试
+- 集成 mock 上游的 `__THINK__` 场景带上缓存明细，新增断言锁定：流式收尾 `message_delta` 必须报出真实 `input_tokens`（=10，而非估算）与 `cache_read_input_tokens`（=8）；两条非流式路由同样锁定。全量 **229 项通过**。
+
 ## [4.11.0] - 2026-09-12
 
 ### 修复

README.md

@@ -90,6 +90,7 @@
 - **打包与 CI** — TypeScript + esbuild + `pkg` 单文件 exe；GitHub Actions 全量回归（typecheck → build → vitest）
 - **离线可用的仪表盘** — Tailwind / Font Awesome / Chart.js 全部本地化，不依赖公共 CDN
 - **Anthropic SDK 兼容** — `POST /v1/messages/count_tokens` 本地估算（CJK 感知，不发起上游请求）；OpenAI `stream_options.include_usage` 在收尾 chunk 附带 usage
+- **用量明细透传给客户端** — Anthropic 路由在收尾 `message_delta`（非流式为 `message.usage`）报出 `input_tokens` / `cache_read_input_tokens` / `cache_creation_input_tokens`，OpenAI 路由报出 `prompt_tokens_details.cached_tokens`。客户端因此能看到**缓存命中量**与**上游真实输入量**，而不是只有本地估算的输入总量；`input_tokens` / `prompt_tokens` 为含缓存读的总量，缓存字段是其子集（勿重复相加）
 - **每日预算告警 + 更新检查** — `DAILY_BUDGET_USD` 当日花费超阈值弹 toast；启动时查询 GitHub Releases，仪表盘头部显示"新版本"徽章
 - **明细导出** — 用量页一键导出 CSV（含 BOM，Excel 直开）
 
@@ -294,6 +295,7 @@ Point any OpenAI-style client (Cursor, Continue, Aider, OpenWebUI, Hermes, your
 
 - **OpenAI `/v1/chat/completions`** — streaming SSE + non-streaming; tool calling (parallel tools, streamed `tool_calls` deltas); vision (`image_url` base64/data-URL); `reasoning_effort` snapped down to per-model tiers; `max_completion_tokens`; usage passthrough from upstream `totalUsage`
 - **Anthropic `/v1/messages`** — full streaming block lifecycle (`message_start` → `content_block_start/delta/stop` → `signature_delta` → `message_delta` → `message_stop`); `tool_use` / `tool_result` round-trip; thinking blocks with signature compatibility; system block arrays
+- **Usage detail reaches the client** — the Anthropic route reports `input_tokens` / `cache_read_input_tokens` / `cache_creation_input_tokens` in the closing `message_delta` (non-streaming: `message.usage`), and the OpenAI route reports `prompt_tokens_details.cached_tokens`. Clients can therefore see **cache hits** and the **upstream's real input count** instead of a locally estimated total. `input_tokens` / `prompt_tokens` already include cache reads, with the cache fields as a subset — do not add them together
 - **Faithful wire translation**, verified line-by-line against the original CLI: raw-base64 image parts with `mediaType`, `tool_search→search_tools` aliasing, terminal-error no-retry list
 - **Full tool passthrough** — no truncation to 15; the 30+ tools issued by multi-tool agent hosts are all forwarded
 - **Fuzzy model resolution + per-plan filtering** — unknown models pass through as-is (upstream returns an accurate error instead of a silently substituted default); `GET /v1/models?plan=…&available=1` (fail-open)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "commandcode-proxy-v4",
-  "version": "4.11.0",
+  "version": "4.11.1",
   "description": "Local OpenAI Chat Completions & Anthropic Messages compatible proxy for Command Code AI. Chinese dashboard, hardened translation, retries, idle timeouts.",
   "main": "dist/index.js",
   "type": "module",

package.json

@@ -26,7 +26,7 @@ import {
   StreamEncoderState,
 } from '../../types/index.js';
 import { resolveModelName } from '../../utils/models.js';
-import { parseUsd } from './usage.js';
+import { parseUsd, splitInput } from './usage.js';
 import { estimateTextTokens } from './upstream.js';
 
 // ─── 推理强度（reasoning effort）映射表（按 CLI wire 契约）───────────────────────
@@ -554,6 +554,7 @@ export class CommandCodeAdapter {
       inputTokens: 0,
       outputTokens: 0,
       cacheReadTokens: 0,
+      cacheWriteTokens: 0,
       noCacheTokens: 0,
     };
   }
@@ -710,11 +711,10 @@ export class CommandCodeAdapter {
         if (usage.inputTokens != null) {
           state.inputTokens = usage.inputTokens;
           // 缓存命中量必须拆出来：单价仅为输入价的 1/50，混在 inputTokens 里会虚高成本。
-          const details = usage.inputTokenDetails || {};
-          const cacheRead = details.cacheReadTokens ?? usage.cachedInputTokens ?? 0;
-          const cacheWrite = details.cacheWriteTokens ?? 0;
+          const { cacheRead, cacheWrite, noCache } = splitInput(usage);
           state.cacheReadTokens = cacheRead;
-          state.noCacheTokens = details.noCacheTokens ?? Math.max(0, usage.inputTokens - cacheRead - cacheWrite);
+          state.cacheWriteTokens = cacheWrite;
+          state.noCacheTokens = noCache;
         }
         if (usage.outputTokens != null) state.outputTokens = usage.outputTokens;
       }
@@ -735,7 +735,13 @@ export class CommandCodeAdapter {
           created: state.created,
           model: state.model,
           choices: [{ index: 0, delta: {}, finish_reason: finishReason }],
-          usage: { prompt_tokens: pt, completion_tokens: state.outputTokens, total_tokens: pt + state.outputTokens },
+          usage: {
+            prompt_tokens: pt,
+            completion_tokens: state.outputTokens,
+            total_tokens: pt + state.outputTokens,
+            // 缓存命中明细按 OpenAI 语义放在 prompt_tokens_details，客户端据此算缓存折扣。
+            prompt_tokens_details: { cached_tokens: state.cacheReadTokens || 0 },
+          },
         })}\n\n`);
       } else {
         chunks.push(this.openAIDelta(state, {}, finishReason));
@@ -770,6 +776,8 @@ export class CommandCodeAdapter {
     let reasoningText = '';
     const toolCalls: Array<{ type: 'tool_use'; id: string; name: string; input: Record<string, unknown> }> = [];
     let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
     let stopReason: string | null = null;
 
     for (const event of events) {
@@ -804,7 +812,12 @@ export class CommandCodeAdapter {
         // Original CLI: totalUsage at top level; rawFinishReason ?? finishReason.
         const usage = event.totalUsage ?? event.data?.usage;
         if (usage) {
-          if (usage.inputTokens != null) inputTokens = usage.inputTokens;
+          if (usage.inputTokens != null) {
+            inputTokens = usage.inputTokens;
+            const { cacheRead, cacheWrite } = splitInput(usage);
+            cacheReadTokens = cacheRead;
+            cacheWriteTokens = cacheWrite;
+          }
           if (usage.outputTokens != null) outputTokens = usage.outputTokens;
         }
         const rawFR = event.rawFinishReason || event.finishReason || event.data?.finishReason;
@@ -848,7 +861,12 @@ export class CommandCodeAdapter {
       model: modelName,
       stop_reason: stopReason || (toolCalls.length > 0 ? 'tool_use' : 'end_turn'),
       stop_sequence: null,
-      usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+      usage: {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        cache_read_input_tokens: cacheReadTokens,
+        cache_creation_input_tokens: cacheWriteTokens,
+      },
     };
   }
 }

src/adapters/commandcode/adapter.ts

@@ -50,7 +50,7 @@ export function parseUsd(value: unknown): number | undefined {
 }
 
 /** 从 usage 明细中拆出缓存读/写与非缓存输入量。 */
-function splitInput(usage: CCEventUsage): { cacheRead: number; cacheWrite: number; noCache: number } {
+export function splitInput(usage: CCEventUsage): { cacheRead: number; cacheWrite: number; noCache: number } {
   const details = usage.inputTokenDetails || {};
   const total = usage.inputTokens ?? 0;
   const cacheRead = details.cacheReadTokens ?? usage.cachedInputTokens ?? 0;

src/adapters/commandcode/usage.ts

@@ -286,6 +286,8 @@ export async function chatRoutes(fastify: FastifyInstance) {
           prompt_tokens: inputTokens,
           completion_tokens: outputTokens,
           total_tokens: inputTokens + outputTokens,
+          // 缓存命中明细按 OpenAI 语义放在 prompt_tokens_details，客户端据此算缓存折扣。
+          prompt_tokens_details: { cached_tokens: usageAcc.cacheReadTokens || 0 },
         },
       });
     } catch (err: any) {

src/routes/chat.ts

@@ -258,7 +258,16 @@ export async function messagesRoutes(fastify: FastifyInstance) {
             sse('message_delta', {
               type: 'message_delta',
               delta: { stop_reason: stopReason, stop_sequence: null },
-              usage: { output_tokens: outputTokens },
+              // 输入侧用量也只有上游收尾的 finish 事件才给得准：message_start 里
+              // 发出去的 input_tokens 是本地估算（缓存明细此刻尚不存在）。这里在
+              // 收尾 delta 补报真实值，口径与 message_start 一致 —— 均为含缓存的
+              // 输入总量，cache_read_* 是其中的子集，客户端不要重复相加。
+              usage: {
+                input_tokens: usageAcc.inputTokens,
+                output_tokens: outputTokens,
+                cache_read_input_tokens: usageAcc.cacheReadTokens || 0,
+                cache_creation_input_tokens: usageAcc.cacheWriteTokens || 0,
+              },
             })
           );
           reply.raw.write(sse('message_stop', { type: 'message_stop' }));

src/routes/messages.ts

@@ -357,6 +357,8 @@ export interface StreamEncoderState {
   outputTokens: number;
   /** 输入中命中缓存的 token 数（计费按 cacheRead 单价）。 */
   cacheReadTokens: number;
+  /** 写入缓存的输入 token 数（多数模型为 0）。 */
+  cacheWriteTokens: number;
   /** 输入中未命中缓存的 token 数。 */
   noCacheTokens: number;
   /** 上游 provider-metadata 给出的权威账单金额（USD）；缺省为 undefined。 */

src/types/index.ts

@@ -289,11 +289,17 @@ describe('Stream encoding', () => {
       { type: 'reasoning-delta', text: 'thinking...' },
       { type: 'text-delta', text: 'Let me check.' },
       { type: 'tool-call', toolCallId: 'tu_1', toolName: 'search', input: { q: 'x' } },
-      { type: 'finish', finishReason: 'tool-calls', data: { usage: { inputTokens: 10, outputTokens: 20 } } },
+      { type: 'finish', finishReason: 'tool-calls', data: { usage: { inputTokens: 10, outputTokens: 20, inputTokenDetails: { cacheReadTokens: 7, noCacheTokens: 3 } } } },
     ];
     const msg = adapter.buildAnthropicResponse(events, 'msg_x', 'claude-sonnet-5', 5);
     expect(msg.stop_reason).toBe('tool_use');
-    expect(msg.usage).toEqual({ input_tokens: 10, output_tokens: 20 });
+    // 缓存命中明细必须随 usage 透出，否则客户端无法区分"输入总量"与"其中命中缓存的部分"。
+    expect(msg.usage).toEqual({
+      input_tokens: 10,
+      output_tokens: 20,
+      cache_read_input_tokens: 7,
+      cache_creation_input_tokens: 0,
+    });
     expect(msg.content.some((b: any) => b.type === 'thinking')).toBe(true);
     expect(msg.content.some((b: any) => b.type === 'text')).toBe(true);
     expect(msg.content.some((b: any) => b.type === 'tool_use' && b.name === 'search')).toBe(true);