dsh-connect-trae 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2.0.5 (2026-09-22)
+
+### Fixes
+
+- **修复「缓存统计一直是 0」**（issue #10：用户反馈「我测试了一下一直0缓存」，并猜测是接口原因或 Trae 本身不缓存）：
+  - **根因在插件自己这一层**：Trae 上游**确实有前缀缓存、也确实在报**（实测逐字节相同的长 prompt 连发，第二次起 `cache_read_input_tokens` 从 0 升到 5248、9216），但插件解码 `token_usage` 事件时**只搬了 4 个计数器**（`prompt_tokens` / `completion_tokens` / `total_tokens` / `reasoning_tokens`），`cache_read_input_tokens` 与 `cache_creation_input_tokens` 被直接丢弃；`TraeStreamEvent.usage` 在**类型层就无法表达**这两个值，转发层自然也无从搬运。
+  - **不是「放行」就够，必须做字段名映射**：`dsh-llm-pi-ai` 只在 `usage.cacheRead > 0` 时写入 `cacheReadTokens`，而 pi-ai 的 `parseChunkUsage` 只识别 `prompt_tokens_details.cached_tokens` / `prompt_cache_hit_tokens` / `cached_tokens` 三种拼写——Trae 的原生字段名不在其中，原样透传依然读不到。现在映射为规范的 `prompt_tokens_details.cached_tokens` / `.cache_write_tokens`。
+  - **先确认了语义再动手**：pi-ai 会做 `input = prompt_tokens - cacheRead - cacheWrite`，该减法仅在「`prompt_tokens` 包含缓存量」（OpenAI 口径）时成立。实测同一份 prompt 的 `prompt_tokens` 恒为 9224 而 `cache_read` 从 5248 涨到 9216，若为 Anthropic 的排除口径则同一输入的实际规模会在 14472 → 18440 之间跳变，不可能——据此确认 Trae 用包含口径。端到端复核账目守恒：`8 + 9216 + 0 = 9224`，与 `prompt_tokens` 完全相等，无重复扣减。
+  - **`src/raw-chat.ts` 存在同一类缺口**（Raw Chat 通道将来启用时会踩同一个坑）：`RawChatDelta.usage` 补上缓存字段，并同时接受 OpenAI 嵌套拼写与 DeepSeek/Kimi 的顶层拼写。两个通道均保证「上游没报缓存时 wire 形状不变」，不产生空 `prompt_tokens_details`。
+  - 新增 4 个回归测试，其中 bridge 用例直接以真机捕获的 `token_usage` 事件原文作为输入。
+  - 取证与复现脚本：`docs/ISSUE10_DIAGNOSIS.md`、`scripts/probe-cache-convention.mjs`。
+  - **说明**：修复只保证「上游报了缓存就如实上报」。新会话/新前缀的第一轮必然 `cache_read=0`（冷启动），第二轮起才有值；实测 Trae 当前只报读不报写（`cache_creation_input_tokens` 恒为 0）。
+
+## 2.0.4 (2026-09-16)
+
+### Fixes
+
+- **修复「某个区域没有实时模型目录时，该区域的 provider 整个加载失败」**（issue #8：未安装国际版的用户看到 `Trae Global 加载失败：adapter returned invalid context metadata for provider "trae-global" model "gemini-3.1-pro"`）：
+  - **根因**：两个区域的内置兜底目录里，每个模型都缺少 `contextWindow`。DSH 要求它必须是正整数（`INVALID_MODEL_CONTEXT`），而 `dsh-llm-pi-ai` 的回退链是 `entry.contextWindow → 已安装 catalog → request.defaultContextWindow`——本插件既没传 `defaultContextWindow`，兜底模型也不在已安装 catalog 里，三条全空，于是校验失败。
+  - **失败粒度是 provider 级**：不是丢单个模型，而是**整个区域不可用**。触发场景包括未安装该区客户端、未登录、目录拉取失败（该端点有已知的间歇性 401）、以及首次安装尚未刷新过目录。因此这不是「没装国际版拖累国内版」，而是**两个区域各自独立地有这个缺陷**。
+  - **修复**：(1) 兜底目录补上实测 `contextWindow`——国际版依据 2026-09-15 实测目录（`gemini-3.1-pro`/`gemini-3-flash-solo`/`minimax-m3`/`minimax-m2.7`/`kimi-k2.5` = 200000，`gpt-5.4`/`gpt-5.2` = 272000），国内版依据 SOLO 通道实测（200000）；(2) adapter 传 `defaultContextWindow` 作为最终防线，将来任何来源的条目不慎缺字段时降级为「一个保守尺寸的模型」而非「整区不可用」。
+  - 新增不变量测试：**两个区域的兜底行都必须带正整数 `contextWindow`**。原先有一条测试断言「兜底条目没有 `contextWindow`」——它固化的正是这个 bug，已改正。
+
 ## 2.0.3 (2026-09-16)
 
 ### Fixes

package/lib/index.d.ts

@@ -126,6 +126,14 @@ interface TraeModelInfo {
  * `DeepSeek-V4-Pro-Official` carry the `-Official` suffix, and there is no
  * `auto` config_name — an `auto` row was previously served here and would have
  * failed on selection.
+ *
+ * Every row MUST also carry a positive-integer `contextWindow`. DSH rejects an
+ * adapter whose model has no usable context (`INVALID_MODEL_CONTEXT`), and that
+ * failure is per-provider — one bad row takes the whole region offline. These
+ * rows are exactly the ones served when no live directory is available (no
+ * install for that region, signed out, or a failed refresh), which is precisely
+ * when the fallback is doing its job, so a missing field here is fatal rather
+ * than cosmetic. See docs/ISSUE8_DIAGNOSIS.md.
  */
 declare const FALLBACK_TRAE_MODELS: readonly TraeModelInfo[];
 /**
@@ -135,6 +143,10 @@ declare const FALLBACK_TRAE_MODELS: readonly TraeModelInfo[];
  * has no Gemini/GPT/MiniMax entries), so an international account must never
  * be seeded with the CN list. Like the CN fallback it is replaced by the live
  * refresh; image input stays the user's explicit opt-in (`imageModelIds`).
+ *
+ * The `contextWindow` values are the measured ones from that same capture
+ * (`docs/INTL_SG_EVIDENCE.md` §3) and are required for the same reason as the
+ * CN fallback: without them the whole `trae-global` provider fails to load.
  */
 declare const FALLBACK_TRAE_MODELS_AI: readonly TraeModelInfo[];
 /**
@@ -748,6 +760,10 @@ type RawChatDelta = {
   inputTokens?: number;
   outputTokens?: number;
   totalTokens?: number;
+  /** Cache-read tokens (`prompt_tokens_details.cached_tokens` / `cached_tokens`). */
+  cacheReadTokens?: number;
+  /** Cache-write tokens (`prompt_tokens_details.cache_write_tokens`). */
+  cacheWriteTokens?: number;
 } | {
   type: 'done';
   finishReason: string;
@@ -1006,6 +1022,17 @@ type TraeStreamEvent = {
   outputTokens?: number;
   totalTokens?: number;
   reasoningTokens?: number;
+  /**
+   * Trae's prompt-cache accounting (`cache_read_input_tokens` /
+   * `cache_creation_input_tokens` on the `token_usage` event). Verified
+   * 2026-09-22 (docs/ISSUE10_DIAGNOSIS.md): a byte-identical 9224-token
+   * prompt reports `prompt_tokens: 9224` while `cache_read_input_tokens`
+   * rises to 9216, so these are a *subset* of `prompt_tokens` — the OpenAI
+   * convention, not Anthropic's exclusive one. Forwarding them as
+   * `cached_tokens` is therefore arithmetically correct.
+   */
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
 } | {
   type: 'done';
   finishReason: string;

package/lib/index.js

@@ -29,23 +29,35 @@ import { promisify } from "node:util";
 * `DeepSeek-V4-Pro-Official` carry the `-Official` suffix, and there is no
 * `auto` config_name — an `auto` row was previously served here and would have
 * failed on selection.
+*
+* Every row MUST also carry a positive-integer `contextWindow`. DSH rejects an
+* adapter whose model has no usable context (`INVALID_MODEL_CONTEXT`), and that
+* failure is per-provider — one bad row takes the whole region offline. These
+* rows are exactly the ones served when no live directory is available (no
+* install for that region, signed out, or a failed refresh), which is precisely
+* when the fallback is doing its job, so a missing field here is fatal rather
+* than cosmetic. See docs/ISSUE8_DIAGNOSIS.md.
 */
 const FALLBACK_TRAE_MODELS = [
 	{
 		id: "DeepSeek-V4-Flash-Official",
-		name: "DeepSeek-V4-Flash"
+		name: "DeepSeek-V4-Flash",
+		contextWindow: 2e5
 	},
 	{
 		id: "DeepSeek-V4-Pro-Official",
-		name: "DeepSeek-V4-Pro"
+		name: "DeepSeek-V4-Pro",
+		contextWindow: 2e5
 	},
 	{
 		id: "glm-5.2",
-		name: "GLM-5.2"
+		name: "GLM-5.2",
+		contextWindow: 2e5
 	},
 	{
 		id: "kimi-k2.6",
-		name: "Kimi-K2.6"
+		name: "Kimi-K2.6",
+		contextWindow: 2e5
 	}
 ];
 /**
@@ -55,35 +67,46 @@ const FALLBACK_TRAE_MODELS = [
 * has no Gemini/GPT/MiniMax entries), so an international account must never
 * be seeded with the CN list. Like the CN fallback it is replaced by the live
 * refresh; image input stays the user's explicit opt-in (`imageModelIds`).
+*
+* The `contextWindow` values are the measured ones from that same capture
+* (`docs/INTL_SG_EVIDENCE.md` §3) and are required for the same reason as the
+* CN fallback: without them the whole `trae-global` provider fails to load.
 */
 const FALLBACK_TRAE_MODELS_AI = [
 	{
 		id: "gemini-3.1-pro",
-		name: "Gemini-3.1-Pro-Preview"
+		name: "Gemini-3.1-Pro-Preview",
+		contextWindow: 2e5
 	},
 	{
 		id: "gemini-3-flash-solo",
-		name: "Gemini-3-Flash-Preview"
+		name: "Gemini-3-Flash-Preview",
+		contextWindow: 2e5
 	},
 	{
 		id: "minimax-m3",
-		name: "MiniMax-M3"
+		name: "MiniMax-M3",
+		contextWindow: 2e5
 	},
 	{
 		id: "minimax-m2.7",
-		name: "MiniMax-M2.7"
+		name: "MiniMax-M2.7",
+		contextWindow: 2e5
 	},
 	{
 		id: "kimi-k2.5",
-		name: "Kimi-K2.5"
+		name: "Kimi-K2.5",
+		contextWindow: 2e5
 	},
 	{
 		id: "gpt-5.4",
-		name: "GPT-5.4"
+		name: "GPT-5.4",
+		contextWindow: 272e3
 	},
 	{
 		id: "gpt-5.2",
-		name: "GPT-5.2"
+		name: "GPT-5.2",
+		contextWindow: 272e3
 	}
 ];
 /**
@@ -292,6 +315,13 @@ const REQUEST_IMAGE_BUDGETS = {
 	requestImagePixelBudget: 4194304,
 	requestImageMaxBytes: 1048576
 };
+/**
+* Conservative context capacity used only when a served model row carries no
+* window of its own. Every fallback row and every live Trae row is expected to
+* state its real window; this is the backstop that keeps one unsized row from
+* failing the entire provider route (`INVALID_MODEL_CONTEXT`).
+*/
+const FALLBACK_CONTEXT_WINDOW = 2e5;
 function toPiModel(info, baseUrl, providerId) {
 	return {
 		id: info.id,
@@ -351,6 +381,7 @@ function createTraeAdapter(options) {
 		retryPolicy: resolveRetryPolicy(void 0, "dsh-connect-trae retryPolicy"),
 		configuredMaxTokens: /* @__PURE__ */ new Map(),
 		modelErrors: /* @__PURE__ */ new Map(),
+		defaultContextWindow: FALLBACK_CONTEXT_WINDOW,
 		...REQUEST_IMAGE_BUDGETS,
 		piProvider: provider
 	};
@@ -2135,7 +2166,9 @@ function decodeTraeEvent(event) {
 		...typeof record["prompt_tokens"] === "number" ? { inputTokens: record["prompt_tokens"] } : {},
 		...typeof record["completion_tokens"] === "number" ? { outputTokens: record["completion_tokens"] } : {},
 		...typeof record["total_tokens"] === "number" ? { totalTokens: record["total_tokens"] } : {},
-		...typeof record["reasoning_tokens"] === "number" ? { reasoningTokens: record["reasoning_tokens"] } : {}
+		...typeof record["reasoning_tokens"] === "number" ? { reasoningTokens: record["reasoning_tokens"] } : {},
+		...typeof record["cache_read_input_tokens"] === "number" ? { cacheReadTokens: record["cache_read_input_tokens"] } : {},
+		...typeof record["cache_creation_input_tokens"] === "number" ? { cacheWriteTokens: record["cache_creation_input_tokens"] } : {}
 	};
 	if (event.event === "done" || typeof record["finish_reason"] === "string" && record["response"] === void 0) return {
 		type: "done",
@@ -2222,12 +2255,20 @@ function bridgeTraeSoloStream(response, model) {
 						delta["tool_calls"] = toolCalls;
 					}
 					if (Object.keys(delta).length > 0) controller.enqueue(chunk(delta));
-				} else if (decoded.type === "usage") usage = {
-					...decoded.inputTokens === void 0 ? {} : { prompt_tokens: decoded.inputTokens },
-					...decoded.outputTokens === void 0 ? {} : { completion_tokens: decoded.outputTokens },
-					...decoded.totalTokens === void 0 ? {} : { total_tokens: decoded.totalTokens }
-				};
-				else if (decoded.type === "done") {
+				} else if (decoded.type === "usage") {
+					const cacheRead = decoded.cacheReadTokens;
+					const cacheWrite = decoded.cacheWriteTokens;
+					const details = {
+						...cacheRead === void 0 ? {} : { cached_tokens: cacheRead },
+						...cacheWrite === void 0 ? {} : { cache_write_tokens: cacheWrite }
+					};
+					usage = {
+						...decoded.inputTokens === void 0 ? {} : { prompt_tokens: decoded.inputTokens },
+						...decoded.outputTokens === void 0 ? {} : { completion_tokens: decoded.outputTokens },
+						...decoded.totalTokens === void 0 ? {} : { total_tokens: decoded.totalTokens },
+						...Object.keys(details).length === 0 ? {} : { prompt_tokens_details: details }
+					};
+				} else if (decoded.type === "done") {
 					upstreamEnded = true;
 					if (!emittedFinishReason) {
 						emittedFinishReason = true;
@@ -2518,11 +2559,16 @@ function decodeRawChatChunk(value) {
 	}
 	if (typeof record["usage"] === "object" && record["usage"] !== null) {
 		const usage = record["usage"];
+		const details = typeof usage["prompt_tokens_details"] === "object" && usage["prompt_tokens_details"] !== null ? usage["prompt_tokens_details"] : {};
+		const cacheRead = details["cached_tokens"] ?? usage["prompt_cache_hit_tokens"] ?? usage["cached_tokens"];
+		const cacheWrite = details["cache_write_tokens"];
 		result.push({
 			type: "usage",
 			...typeof usage["prompt_tokens"] === "number" ? { inputTokens: usage["prompt_tokens"] } : {},
 			...typeof usage["completion_tokens"] === "number" ? { outputTokens: usage["completion_tokens"] } : {},
-			...typeof usage["total_tokens"] === "number" ? { totalTokens: usage["total_tokens"] } : {}
+			...typeof usage["total_tokens"] === "number" ? { totalTokens: usage["total_tokens"] } : {},
+			...typeof cacheRead === "number" ? { cacheReadTokens: cacheRead } : {},
+			...typeof cacheWrite === "number" ? { cacheWriteTokens: cacheWrite } : {}
 		});
 	}
 	return result.length === 0 ? [{

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-trae",
   "displayName": "DSH Connect Trae",
   "description": "Connect locally signed-in Trae models to DeepSeek Harness, plus a read-only usage/credits summary.",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "author": "dingminhua",
   "copyright": "Copyright (c) 2026 LaoDing",
   "license": "MIT",