dsh-router-core 0.3.16 → 0.3.18

package/lib/client-registry.js

@@ -3201,6 +3201,7 @@ window.__ModuleLoader__.load({
 			}, [period, active]);
 			const s = stats;
 			const successRate = s !== null && s.requests !== void 0 && s.requests > 0 ? Math.round((s.okCount ?? 0) / s.requests * 100) : null;
+			const cacheRatio = s !== null && (s.promptTokens ?? 0) > 0 ? Math.round((s.cachedTokens ?? 0) / (s.promptTokens ?? 0) * 100) : null;
 			const estimated = s !== null && ((s.estimatedInputs ?? 0) > 0 || (s.estimatedOutputs ?? 0) > 0);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "dshr-tabBody",
@@ -3276,10 +3277,11 @@ window.__ModuleLoader__.load({
 									tone: "ok"
 								}),
 								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(StatCard, {
-									label: "缓存 Tokens",
-									value: fmtShort(s?.cachedTokens),
-									hint: "命中缓存的输入部分",
-									tone: "default"
+									label: "缓存命中率",
+									value: cacheRatio === null ? "—" : `${cacheRatio}%`,
+									hint: cacheRatio === null ? "命中缓存的输入占比" : `命中 ${fmtShort(s?.cachedTokens)} / 输入 ${fmtShort(s?.promptTokens)}`,
+									tone: cacheRatio !== null && cacheRatio >= 80 ? "ok" : "default",
+									title: "缓存命中率 = 命中缓存的输入 tokens ÷ 总输入 tokens"
 								}),
 								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(StatCard, {
 									label: "平均耗时",

package/lib/client.js

@@ -3201,6 +3201,7 @@ window.__ModuleLoader__.load({
 			}, [period, active]);
 			const s = stats;
 			const successRate = s !== null && s.requests !== void 0 && s.requests > 0 ? Math.round((s.okCount ?? 0) / s.requests * 100) : null;
+			const cacheRatio = s !== null && (s.promptTokens ?? 0) > 0 ? Math.round((s.cachedTokens ?? 0) / (s.promptTokens ?? 0) * 100) : null;
 			const estimated = s !== null && ((s.estimatedInputs ?? 0) > 0 || (s.estimatedOutputs ?? 0) > 0);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "dshr-tabBody",
@@ -3276,10 +3277,11 @@ window.__ModuleLoader__.load({
 									tone: "ok"
 								}),
 								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(StatCard, {
-									label: "缓存 Tokens",
-									value: fmtShort(s?.cachedTokens),
-									hint: "命中缓存的输入部分",
-									tone: "default"
+									label: "缓存命中率",
+									value: cacheRatio === null ? "—" : `${cacheRatio}%`,
+									hint: cacheRatio === null ? "命中缓存的输入占比" : `命中 ${fmtShort(s?.cachedTokens)} / 输入 ${fmtShort(s?.promptTokens)}`,
+									tone: cacheRatio !== null && cacheRatio >= 80 ? "ok" : "default",
+									title: "缓存命中率 = 命中缓存的输入 tokens ÷ 总输入 tokens"
 								}),
 								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(StatCard, {
 									label: "平均耗时",

package/lib/index.js

@@ -1052,7 +1052,14 @@ function num(v) {
 * `cached_tokens` 口径照 9router 的 `canonicalizeUsage`：OpenAI 系报的
 * prompt_tokens **已含**缓存，直接透传；Claude 系报的是**不含**缓存的
 * prompt + 单独的 cache_read，要折进来，否则总输入偏小。
-* 判别式就是「有没有 cache_read_input_tokens」。
+*
+* 判别式**不能只看有没有 `cache_read_input_tokens`**：TRAE(SOLO) 借用了这个
+* Claude 字段名，语义却是 OpenAI 的「prompt_tokens 已含缓存」——
+* 于是同时报了 `prompt_tokens=160019` 和 `cache_read_input_tokens=159744`，
+* 旧逻辑无条件相加 → 总量翻倍、命中率被腰斩成 50%。正确判别是**看 prompt
+* 车道**：有 `prompt_tokens` = OpenAI 总语义（已含缓存，**不**再折 cache_read）；
+* 只有 `input_tokens`/`promptTokenCount` = Claude/Gemini 不含缓存，才折。
+* 这与供应商无关、自描述，比把 supplierId 灌进 usage 管线更干净。
 *
 * @returns 归一用量；一个非零字段都没有时返回 null（= 没拿到 usage）
 */
@@ -1061,7 +1068,7 @@ function normalizeUsage(raw) {
 	const u = raw;
 	const cached = num(u.cached_tokens) + num(u.cache_read_input_tokens) + num(u.cachedContentTokenCount) + num(u.prompt_tokens_details?.cached_tokens);
 	let prompt = num(u.prompt_tokens) + num(u.input_tokens) + num(u.promptTokenCount);
-	if (u.cache_read_input_tokens !== void 0) prompt += num(u.cache_read_input_tokens);
+	if (u.cache_read_input_tokens !== void 0 && u.prompt_tokens === void 0) prompt += num(u.cache_read_input_tokens);
 	const completion = num(u.completion_tokens) + num(u.output_tokens) + num(u.candidatesTokenCount);
 	if (prompt === 0 && completion === 0 && cached === 0) return null;
 	return {

package/lib/types/router/usage-tokens.d.ts

@@ -38,7 +38,14 @@ export interface Usage extends UsageTokens {
  * `cached_tokens` 口径照 9router 的 `canonicalizeUsage`：OpenAI 系报的
  * prompt_tokens **已含**缓存，直接透传；Claude 系报的是**不含**缓存的
  * prompt + 单独的 cache_read，要折进来，否则总输入偏小。
- * 判别式就是「有没有 cache_read_input_tokens」。
+ *
+ * 判别式**不能只看有没有 `cache_read_input_tokens`**：TRAE(SOLO) 借用了这个
+ * Claude 字段名，语义却是 OpenAI 的「prompt_tokens 已含缓存」——
+ * 于是同时报了 `prompt_tokens=160019` 和 `cache_read_input_tokens=159744`，
+ * 旧逻辑无条件相加 → 总量翻倍、命中率被腰斩成 50%。正确判别是**看 prompt
+ * 车道**：有 `prompt_tokens` = OpenAI 总语义（已含缓存，**不**再折 cache_read）；
+ * 只有 `input_tokens`/`promptTokenCount` = Claude/Gemini 不含缓存，才折。
+ * 这与供应商无关、自描述，比把 supplierId 灌进 usage 管线更干净。
  *
  * @returns 归一用量；一个非零字段都没有时返回 null（= 没拿到 usage）
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-router-core",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "DSH plugin: a simplified 9router (AI routing gateway). Adds a 路由系统 (Routing System) sidebar entry beside 记忆系统; the panel shows suppliers, account pool, combos, and endpoint/API keys.",
   "type": "module",
   "repository": {

package/src/client/StatsTab.tsx

@@ -421,6 +421,12 @@ export function StatsTab({ onRefresh, refreshing, active, health }: StatsTabProp
   const successRate = s !== null && s.requests !== undefined && s.requests > 0
     ? Math.round(((s.okCount ?? 0) / s.requests) * 100)
     : null
+  // 缓存命中率 = cachedTokens / promptTokens（cachedTokens 是 promptTokens
+  // 的子集：命中缓存的输入部分）。分母 0 = 本周期没有带缓存语义的请求，
+  // 显示 — 而不是硬造 0%（那会把「没数据」和「全未命中」混为一谈）。
+  const cacheRatio = s !== null && (s.promptTokens ?? 0) > 0
+    ? Math.round(((s.cachedTokens ?? 0) / (s.promptTokens ?? 0)) * 100)
+    : null
   // 估算提示：只有真有估算时才显示，别没事吓唬人
   const estimated = s !== null && ((s.estimatedInputs ?? 0) > 0 || (s.estimatedOutputs ?? 0) > 0)
 
@@ -490,8 +496,16 @@ export function StatsTab({ onRefresh, refreshing, active, health }: StatsTabProp
                 hint={(s?.estimatedOutputs ?? 0) > 0 ? '~ 含估算' : undefined}
                 tone="ok"
               />
-              {/* 缓存排在输入/输出之后：它是输入的子集，不是并列的第三种 token */}
-              <StatCard label="缓存 Tokens" value={fmtShort(s?.cachedTokens)} hint="命中缓存的输入部分" tone="default" />
+              {/* 缓存排在输入/输出之后：它是输入的子集，不是并列的第三种 token。
+                  显示命中率而不是 token 数：50.2% 这种数一眼能读出「缓存工作是否正常」，
+                  绝对值要看的话输入 Tokens 卡里已含（title 给出原始数字）。 */}
+              <StatCard
+                label="缓存命中率"
+                value={cacheRatio === null ? '—' : `${cacheRatio}%`}
+                hint={cacheRatio === null ? '命中缓存的输入占比' : `命中 ${fmtShort(s?.cachedTokens)} / 输入 ${fmtShort(s?.promptTokens)}`}
+                tone={cacheRatio !== null && cacheRatio >= 80 ? 'ok' : 'default'}
+                title="缓存命中率 = 命中缓存的输入 tokens ÷ 总输入 tokens"
+              />
               <StatCard
                 label="平均耗时"
                 value={fmtDuration(s?.avgDurationMs)}

package/src/router/usage-tokens.ts

@@ -61,7 +61,14 @@ function num(v: unknown): number {
  * `cached_tokens` 口径照 9router 的 `canonicalizeUsage`：OpenAI 系报的
  * prompt_tokens **已含**缓存，直接透传；Claude 系报的是**不含**缓存的
  * prompt + 单独的 cache_read，要折进来，否则总输入偏小。
- * 判别式就是「有没有 cache_read_input_tokens」。
+ *
+ * 判别式**不能只看有没有 `cache_read_input_tokens`**：TRAE(SOLO) 借用了这个
+ * Claude 字段名，语义却是 OpenAI 的「prompt_tokens 已含缓存」——
+ * 于是同时报了 `prompt_tokens=160019` 和 `cache_read_input_tokens=159744`，
+ * 旧逻辑无条件相加 → 总量翻倍、命中率被腰斩成 50%。正确判别是**看 prompt
+ * 车道**：有 `prompt_tokens` = OpenAI 总语义（已含缓存，**不**再折 cache_read）；
+ * 只有 `input_tokens`/`promptTokenCount` = Claude/Gemini 不含缓存，才折。
+ * 这与供应商无关、自描述，比把 supplierId 灌进 usage 管线更干净。
  *
  * @returns 归一用量；一个非零字段都没有时返回 null（= 没拿到 usage）
  */
@@ -77,7 +84,11 @@ export function normalizeUsage(raw: unknown): UsageTokens | null {
 
   // promptTokenCount 是 Gemini 形态；input_tokens 是 Claude 形态
   let prompt = num(u.prompt_tokens) + num(u.input_tokens) + num(u.promptTokenCount)
-  if (u.cache_read_input_tokens !== undefined) prompt += num(u.cache_read_input_tokens)
+  // 有 prompt_tokens = OpenAI 总语义（含缓存）；没有 = Claude/Gemini 不含缓存，
+  // 这时才该把 cache_read 折进来，否则像 TRAE 会加两遍
+  if (u.cache_read_input_tokens !== undefined && u.prompt_tokens === undefined) {
+    prompt += num(u.cache_read_input_tokens)
+  }
 
   const completion = num(u.completion_tokens) + num(u.output_tokens) + num(u.candidatesTokenCount)
 

package/src/router/usage.test.ts

@@ -12,6 +12,7 @@ import {
   tapStreamUsage,
   withEstimates,
   estimateTokens,
+  toTokenUsage,
 } from './usage-tokens.ts'
 import { UsageStore, localDateKey } from './usage-store.ts'
 import { mkdirSync, writeFileSync } from 'node:fs'
@@ -35,6 +36,22 @@ test('归一化：Claude 形态的 prompt 不含缓存，cache_read 要折进输
   assert.deepEqual(u, { promptTokens: 130, completionTokens: 10, cachedTokens: 80 })
 })
 
+test('归一化：TRAE 借 Claude 字段名、语义却是 OpenAI —— 不得重复加 cache（命中率腰斩 bug）', () => {
+  // TRAE(SOLO) 同时报 prompt_tokens（OpenAI 总语义，**已含**缓存）和
+  // cache_read_input_tokens。语义与字段名分属两条车道，判别不能只看后者。
+  // 2026-09-16 实测同一次请求：160019 + 159744 被加两遍 → 319763，命中率腰斩
+  // 成 ~50%；真实命中率 159744/160019 = 99.8%。
+  const u = normalizeUsage({
+    prompt_tokens: 160019,
+    completion_tokens: 307,
+    cache_read_input_tokens: 159744,
+  })
+  assert.deepEqual(u, { promptTokens: 160019, completionTokens: 307, cachedTokens: 159744 }, 'prompt_tokens 已含缓存，不得再加 cache_read')
+  // DISJOINT 折算后必须还原上游真实值：160019 - 159744 = 275 未缓存输入
+  const t = toTokenUsage(u)
+  assert.deepEqual(t, { inputTokens: 275, outputTokens: 307, cacheReadTokens: 159744 })
+})
+
 test('归一化：Gemini 形态（promptTokenCount / usageMetadata）', () => {
   const u = normalizeUsage({ promptTokenCount: 7, candidatesTokenCount: 3, cachedContentTokenCount: 2 })
   assert.deepEqual(u, { promptTokens: 7, completionTokens: 3, cachedTokens: 2 })