dsh-router-core 0.3.16 → 0.3.19

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 {
@@ -1228,29 +1235,43 @@ function tapStreamUsage(source, startedAt) {
 			outputChars += frameText(obj).length;
 		}
 	};
+	/** 源 reader：cancel 时要靠它把取消传下去（见下方 cancel 分支）。 */
+	let reader;
 	return {
-		stream: new ReadableStream({ start: async (ctrl) => {
-			const reader = source.getReader();
-			try {
-				for (;;) {
-					const { done, value } = await reader.read();
-					if (done) break;
-					if (firstAt === 0) firstAt = Date.now();
-					buf += dec.decode(value, { stream: true });
-					let sep;
-					while ((sep = buf.indexOf("\n\n")) >= 0) {
-						const frame = buf.slice(0, sep + 2);
-						buf = buf.slice(sep + 2);
-						parseFrame(frame);
+		stream: new ReadableStream({
+			start: async (ctrl) => {
+				reader = source.getReader();
+				try {
+					for (;;) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						if (firstAt === 0) firstAt = Date.now();
+						buf += dec.decode(value, { stream: true });
+						let sep;
+						while ((sep = buf.indexOf("\n\n")) >= 0) {
+							const frame = buf.slice(0, sep + 2);
+							buf = buf.slice(sep + 2);
+							parseFrame(frame);
+						}
+						ctrl.enqueue(value);
 					}
-					ctrl.enqueue(value);
+					if (buf !== "") parseFrame(buf);
+				} catch {} finally {
+					try {
+						reader.releaseLock();
+					} catch {}
 				}
-				if (buf !== "") parseFrame(buf);
-			} finally {
-				reader.releaseLock();
-			}
-			ctrl.close();
-		} }),
+				try {
+					ctrl.close();
+				} catch {}
+			},
+			/**
+			* 取消要往下传（同 normalizeSSEStream 的理由）：不传 → 客户端断开时
+			* 上游 fetch body 永不 cancel，连接与 in-flight 请求一直挂着。
+			* 必须用 reader.cancel()：流已被 getReader() 锁住，stream.cancel() 会抛。
+			*/
+			cancel: (reason) => reader?.cancel(reason)
+		}),
 		done: async () => ({
 			usage: merged,
 			outputChars,
@@ -1392,59 +1413,65 @@ async function aggregateSSE(stream) {
 	const calls = /* @__PURE__ */ new Map();
 	const reader = stream.getReader();
 	let buf = "";
-	for (;;) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		buf += dec.decode(value, { stream: true });
-		let sep;
-		while ((sep = buf.indexOf("\n\n")) >= 0) {
-			const frame = buf.slice(0, sep);
-			buf = buf.slice(sep + 2);
-			for (const line of frame.split("\n")) {
-				if (!line.startsWith("data:")) continue;
-				const payload = line.slice(5).trim();
-				if (payload === "" || payload === "[DONE]") continue;
-				let obj;
-				try {
-					obj = JSON.parse(payload);
-				} catch {
-					continue;
-				}
-				if (typeof obj.id === "string" && obj.id !== "") id = obj.id;
-				if (typeof obj.model === "string" && obj.model !== "") model = obj.model;
-				if (typeof obj.created === "number") created = obj.created;
-				if (obj.usage !== void 0) usage = obj.usage;
-				const ch = obj.choices?.[0];
-				if (ch === void 0) continue;
-				if (typeof ch.finish_reason === "string") finish = ch.finish_reason;
-				const delta = ch.delta;
-				if (delta === void 0) {
-					const msg = ch.message;
-					if (msg !== void 0) {
-						if (typeof msg.content === "string") content += msg.content;
-						if (typeof msg.reasoning_content === "string") reasoning += msg.reasoning_content;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buf += dec.decode(value, { stream: true });
+			let sep;
+			while ((sep = buf.indexOf("\n\n")) >= 0) {
+				const frame = buf.slice(0, sep);
+				buf = buf.slice(sep + 2);
+				for (const line of frame.split("\n")) {
+					if (!line.startsWith("data:")) continue;
+					const payload = line.slice(5).trim();
+					if (payload === "" || payload === "[DONE]") continue;
+					let obj;
+					try {
+						obj = JSON.parse(payload);
+					} catch {
+						continue;
+					}
+					if (typeof obj.id === "string" && obj.id !== "") id = obj.id;
+					if (typeof obj.model === "string" && obj.model !== "") model = obj.model;
+					if (typeof obj.created === "number") created = obj.created;
+					if (obj.usage !== void 0) usage = obj.usage;
+					const ch = obj.choices?.[0];
+					if (ch === void 0) continue;
+					if (typeof ch.finish_reason === "string") finish = ch.finish_reason;
+					const delta = ch.delta;
+					if (delta === void 0) {
+						const msg = ch.message;
+						if (msg !== void 0) {
+							if (typeof msg.content === "string") content += msg.content;
+							if (typeof msg.reasoning_content === "string") reasoning += msg.reasoning_content;
+						}
+						continue;
+					}
+					if (typeof delta.content === "string") content += delta.content;
+					if (typeof delta.reasoning_content === "string") reasoning += delta.reasoning_content;
+					const tcs = delta.tool_calls;
+					if (!Array.isArray(tcs)) continue;
+					for (const tc of tcs) {
+						const idx = typeof tc.index === "number" ? tc.index : 0;
+						const fn = tc.function;
+						const prev = calls.get(idx) ?? {
+							name: "",
+							args: ""
+						};
+						if (typeof tc.id === "string" && tc.id !== "") prev.id = tc.id;
+						if (typeof tc.type === "string") prev.type = tc.type;
+						if (typeof fn?.name === "string" && fn.name !== "") prev.name = fn.name;
+						if (typeof fn?.arguments === "string") prev.args += fn.arguments;
+						calls.set(idx, prev);
 					}
-					continue;
-				}
-				if (typeof delta.content === "string") content += delta.content;
-				if (typeof delta.reasoning_content === "string") reasoning += delta.reasoning_content;
-				const tcs = delta.tool_calls;
-				if (!Array.isArray(tcs)) continue;
-				for (const tc of tcs) {
-					const idx = typeof tc.index === "number" ? tc.index : 0;
-					const fn = tc.function;
-					const prev = calls.get(idx) ?? {
-						name: "",
-						args: ""
-					};
-					if (typeof tc.id === "string" && tc.id !== "") prev.id = tc.id;
-					if (typeof tc.type === "string") prev.type = tc.type;
-					if (typeof fn?.name === "string" && fn.name !== "") prev.name = fn.name;
-					if (typeof fn?.arguments === "string") prev.args += fn.arguments;
-					calls.set(idx, prev);
 				}
 			}
 		}
+	} finally {
+		try {
+			reader.releaseLock();
+		} catch {}
 	}
 	const toolCalls = [...calls.entries()].sort((a, b) => a[0] - b[0]).filter(([, c]) => c.name !== "").map(([, c]) => ({
 		id: c.id ?? `call_${c.name}`,
@@ -1498,31 +1525,47 @@ function normalizeSSEStream(stream) {
 	const dec = new TextDecoder();
 	let buf = "";
 	let sawDone = false;
+	/** 上游 reader：cancel 时要靠它把取消传下去（见下方 cancel 分支）。 */
+	let reader;
 	return {
-		stream: new ReadableStream({ start: async (ctrl) => {
-			const reader = stream.getReader();
-			try {
-				for (;;) {
-					const { done, value } = await reader.read();
-					if (done) break;
-					buf += dec.decode(value, { stream: true });
-					let sep;
-					while ((sep = buf.indexOf("\n\n")) >= 0) {
-						const frame = buf.slice(0, sep + 2);
-						buf = buf.slice(sep + 2);
-						if (isDoneFrame(frame)) sawDone = true;
-						ctrl.enqueue(enc.encode(fixFrame(frame)));
+		stream: new ReadableStream({
+			start: async (ctrl) => {
+				reader = stream.getReader();
+				try {
+					for (;;) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						buf += dec.decode(value, { stream: true });
+						let sep;
+						while ((sep = buf.indexOf("\n\n")) >= 0) {
+							const frame = buf.slice(0, sep + 2);
+							buf = buf.slice(sep + 2);
+							if (isDoneFrame(frame)) sawDone = true;
+							ctrl.enqueue(enc.encode(fixFrame(frame)));
+						}
 					}
+					if (buf !== "") {
+						if (isDoneFrame(buf)) sawDone = true;
+						ctrl.enqueue(enc.encode(fixFrame(buf)));
+					}
+				} catch {} finally {
+					try {
+						reader.releaseLock();
+					} catch {}
 				}
-				if (buf !== "") {
-					if (isDoneFrame(buf)) sawDone = true;
-					ctrl.enqueue(enc.encode(fixFrame(buf)));
-				}
-			} finally {
-				reader.releaseLock();
-			}
-			ctrl.close();
-		} }),
+				try {
+					ctrl.close();
+				} catch {}
+			},
+			/**
+			* **取消必须往下传**：ReadableStream 的取消不会自动穿过 wrapper。
+			* 不实现这个分支，客户端断开的取消就停在这里，上游 fetch body 永不 cancel
+			* ——那条 TCP 连接和 in-flight 请求原样挂着（长跑一天就会累积到耗尽）。
+			* 用 reader.cancel() 而不是 stream.cancel()：流已被 getReader() 锁住，
+			* 直接 cancel 会抛 `Invalid state: ReadableStream is locked`。
+			*/
+			cancel: (reason) => reader?.cancel(reason)
+		}),
 		sawDone: () => sawDone
 	};
 }
@@ -1592,6 +1635,7 @@ async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
 		try {
 			body = await aggregateSSE(r.stream);
 		} catch {
+			await r.stream.cancel().catch(() => {});
 			return false;
 		}
 		if (probe !== void 0) probe.tokens = usageFromJsonBody(body);
@@ -1606,6 +1650,18 @@ async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
 	let wroteAny = false;
 	/** 响应已死（客户端断开/res 已销毁）：等 drain 的写入要立刻放弃，别吊死。 */
 	let dead = false;
+	/**
+	* 唤醒「等 drain 的挂起 write」。客户端断开时必须调它：那时 'drain' 永不到来，
+	* 不唤醒就永远卡在 write 里，pipeTo 不 settle，finally 不执行，
+	* **上游流也就永不 cancel**（= 每次客户端放弃漏一条连接）。
+	*/
+	let releaseWait;
+	/**
+	* 中止 pipeTo 的信号源（客户端断开时 abort）。
+	* 单靠 `dead` 标志只能让**下一次** write 立刻返回，唤醒不了**已经挂起**的那次；
+	* abort 才能让 pipeTo 立刻收尾并走它的取消路径（进而 cancel 上游）。
+	*/
+	const abort = new AbortController();
 	const writeChunk = (chunk) => new Promise((resolve) => {
 		if (dead) {
 			resolve();
@@ -1628,6 +1684,11 @@ async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
 				resolve();
 			};
 			res.once("drain", onDrain);
+			/** 让这个挂起的 write 立刻收尾（客户端断开时调用）。 */
+			releaseWait = () => {
+				res.removeListener("drain", onDrain);
+				resolve();
+			};
 		}
 	});
 	const onError = () => {
@@ -1635,13 +1696,28 @@ async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
 		res.destroy();
 	};
 	res.once("error", onError);
+	/**
+	* **客户端断开必须被当成取消信号**：只监听 'error' 是不够的 —— 对端关闭
+	* （pi-ai 的流空闲超时、用户取消、消费方提前退出）触发的是 'close'，
+	* 不是 'error'。此时若不收手，pipeTo 会一直等着 drain（永不到来），
+	* finally 永不执行，上游 fetch body **永不 cancel** → 那条 TCP 连接和
+	* in-flight 请求原样挂着，长跑累积到耗尽（"用久了就报 connection error"）。
+	*/
+	const onClose = () => {
+		if (res.writableEnded) return;
+		dead = true;
+		releaseWait?.();
+		abort.abort();
+	};
+	res.once("close", onClose);
 	const norm = normalizeSSEStream(tapped?.stream ?? r.stream);
 	try {
-		await norm.stream.pipeTo(new WritableStream({ write: writeChunk }));
+		await norm.stream.pipeTo(new WritableStream({ write: writeChunk }), { signal: abort.signal });
 	} catch {} finally {
 		res.removeListener("error", onError);
+		res.removeListener("close", onClose);
 		if (wroteAny && !norm.sawDone() && !dead && !res.writableEnded && !res.destroyed) await writeChunk(DONE_FRAME);
-		if (wroteAny) res.end();
+		if (wroteAny && !dead) res.end();
 		if (probe !== void 0 && tapped !== void 0) {
 			const got = await tapped.done();
 			probe.tokens = got.usage;
@@ -2308,6 +2384,16 @@ var Router = class {
 */
 /** tool-result 里图片挂到 user 消息时用的说明文字（与官方适配器一致）。 */
 const TOOL_RESULT_IMAGE_TEXT = "Tool result images";
+/**
+* 流空闲超时：上游连上后这么久没吐**任何**字节就判失败（抛 TIMEOUT，可重试）。
+*
+* 对齐 `dsh-llm-pi-ai` 的 `DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000`：同一个
+* dsh-router `/v1`，走自定义供应商（pi-ai）时有这个兜底、走内置 adapter 时没有
+* —— 差异导致「上游停摆」在内置路径上永久挂住。
+*
+* 只守空闲、不封总时长：长生成只要持续吐块就不该被打断。
+*/
+const STREAM_IDLE_TIMEOUT_MS = 3e5;
 async function wireMessages(options, system, attachments) {
 	const out = [];
 	/**
@@ -2749,11 +2835,18 @@ var RouterAdapter = class RouterAdapter extends LlmAdapter {
 	baseURL;
 	source;
 	resolveAttachments;
-	constructor(baseURL, source, resolveAttachments) {
+	/** 流空闲超时（ms）：上游这么久不吐字节就判 TIMEOUT。 */
+	idleTimeoutMs;
+	/**
+	* @param idleTimeoutMs 流空闲超时；缺省用生产值（300s，对齐 pi-ai）。
+	*   可注入只为测试能压到几百毫秒，生产不传。
+	*/
+	constructor(baseURL, source, resolveAttachments, idleTimeoutMs = STREAM_IDLE_TIMEOUT_MS) {
 		super();
 		this.baseURL = baseURL;
 		this.source = source;
 		this.resolveAttachments = resolveAttachments ?? (() => void 0);
+		this.idleTimeoutMs = idleTimeoutMs;
 	}
 	providerInfo(provider) {
 		return {
@@ -2817,16 +2910,19 @@ var RouterAdapter = class RouterAdapter extends LlmAdapter {
 				signal: controller.signal
 			});
 		} catch (error) {
+			options.signal?.removeEventListener("abort", onAbort);
 			throw new LlmError(`dsh-router upstream call failed: ${error.message}`, "TRANSPORT", { cause: error });
+		}
+		try {
+			if (!resp.ok) {
+				const detail = await resp.text().catch(() => "");
+				throw new LlmError(`dsh-router /v1 returned ${resp.status}: ${detail.slice(0, 200)}`, "TRANSPORT");
+			}
+			if (resp.body === null) return;
+			yield* translateSse(ssePayloads(resp.body, this.idleTimeoutMs));
 		} finally {
 			options.signal?.removeEventListener("abort", onAbort);
 		}
-		if (!resp.ok) {
-			const detail = await resp.text().catch(() => "");
-			throw new LlmError(`dsh-router /v1 returned ${resp.status}: ${detail.slice(0, 200)}`, "TRANSPORT");
-		}
-		if (resp.body === null) return;
-		yield* translateSse(ssePayloads(resp.body));
 	}
 };
 /**
@@ -2854,16 +2950,41 @@ function looksComplete(payload) {
 * 跨块边界：一个 `data:` 行可能横跨两次 read()，所以留 `buffer` 接住
 * 最后一段未完整的行（9router 的 pipeTransformedSSE 同样处理）。
 */
-async function* ssePayloads(body) {
+async function* ssePayloads(body, idleTimeoutMs) {
 	const reader = body.getReader();
 	const decoder = new TextDecoder("utf-8", { fatal: false });
 	let buffer = "";
 	/** 攒一帧内的多行 data（SSE 规范：多行用 \n 连起来）。**必须**是局部
 	*  状态 —— 放模块级会让并发请求互相串数据。 */
 	let payload = "";
+	/**
+	* 带**空闲超时**的读：上游连上后若长时间一个字节都不吐，就读穿不了 ——
+	* 没有超时的话这里会永久挂着，连接和 in-flight 请求都收不回。
+	*
+	* 为什么必须有（issue #6 的另一半）：`dsh-llm-pi-ai`（自定义供应商走的那条
+	* openai-completions adapter）有 `idleWatchdog`，默认 **300s** 空闲即
+	* `LLM_STREAM_IDLE_TIMEOUT` 中止；而本 adapter 此前**没有任何超时**，只靠
+	* 调用方的 `options.signal`。于是同一个组合，走内置 Router 时上游一停摆就
+	* 永久挂住（占用连接、且该请求永不收尾），走自定义供应商时 300s 后被放弃
+	* —— 放弃又会触发服务端那条「客户端断开不回收」的泄漏路径，两边叠加就是
+	* 「用久了报 connection error」。
+	*
+	* 只守**空闲**、不设总时长：长生成可以跑很久，只要还在吐块就不该被打断
+	* （总时长封顶会让长回答写到一半被砍）。
+	*/
+	const readWithIdleTimeout = () => new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new LlmError(`dsh-router upstream stream idle for ${idleTimeoutMs}ms`, "TIMEOUT")), idleTimeoutMs);
+		reader.read().then((r) => {
+			clearTimeout(timer);
+			resolve(r);
+		}, (e) => {
+			clearTimeout(timer);
+			reject(e);
+		});
+	});
 	try {
 		for (;;) {
-			const { done, value } = await reader.read();
+			const { done, value } = await readWithIdleTimeout();
 			if (done) break;
 			buffer += decoder.decode(value, { stream: true });
 			const lines = buffer.split("\n");

package/lib/types/llm/adapter.d.ts

@@ -58,7 +58,13 @@ export declare class RouterAdapter extends LlmAdapter {
     private readonly baseURL;
     private readonly source;
     private readonly resolveAttachments;
-    constructor(baseURL: string, source: RouterAdapterSource, resolveAttachments?: () => RouterAttachmentStore | undefined);
+    /** 流空闲超时（ms）：上游这么久不吐字节就判 TIMEOUT。 */
+    private readonly idleTimeoutMs;
+    /**
+     * @param idleTimeoutMs 流空闲超时；缺省用生产值（300s，对齐 pi-ai）。
+     *   可注入只为测试能压到几百毫秒，生产不传。
+     */
+    constructor(baseURL: string, source: RouterAdapterSource, resolveAttachments?: () => RouterAttachmentStore | undefined, idleTimeoutMs?: number);
     providerInfo(provider: string): {
         id: string;
         name: string;

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.19",
   "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/llm/adapter.test.ts

@@ -15,6 +15,13 @@ import { EMPTY_RESPONSE_CODE } from '@deepseek-ai/dsh-llm'
 import { toTokenUsage } from '../router/usage-tokens.ts'
 import { RouterAdapter, translateSse } from './adapter.ts'
 
+/**
+ * 本文件大量用例把 `globalThis.fetch` 打桩成假上游，且**从不还原**（沿既有惯例：
+ * 每个用例自己设桩）。所以「要打真实网络」的用例必须自己把真 fetch 放回去 ——
+ * 否则会静默拿到上一个用例残留的桩（曾导致「停摆测试 0ms 就 ended」的假结果）。
+ */
+const realFetch: typeof fetch = globalThis.fetch
+
 /**
  * dsh-llm 默认可重试的错误码白名单（DEFAULT_RETRYABLE_CODES）。
  *
@@ -727,3 +734,78 @@ test('wire：纯文本 tool-result 不因图片逻辑改变顺序（tool 紧跟
   assertToolPairingIntact(messages)
   assert.deepEqual(messages.map((m) => m.role), ['user', 'assistant', 'tool'], '纯文本 tool 结果仍紧跟 assistant')
 })
+
+/* ---------------- 流空闲超时：上游停摆不能永久挂住（issue #6） ---------------- */
+
+/**
+ * 为什么要有这一组：同一个 dsh-router `/v1`，走**自定义供应商**（llm-pi-ai 的
+ * openai-completions adapter）时有 `idleWatchdog`（默认 300s）兜底，走**内置
+ * Router adapter** 时此前没有任何超时 —— 上游连上后一停摆就永久挂着，连接和
+ * in-flight 请求都收不回。这是 issue #6「内置 vs 自定义」差异的一半。
+ *
+ * **必须用真实 http server**：合成 `ReadableStream` 上 `AbortSignal` 是无效的
+ * （实测合成流 + AbortSignal.timeout 永不收尾），拿它测只能得到假结论。
+ */
+test('流空闲超时：上游停摆 → adapter 自己中止（不依赖调用方给 signal）', async () => {
+  const http = await import('node:http')
+  const server = http.createServer((_req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' })
+    res.flushHeaders()          // 一个字节都不吐，也不结束
+  })
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()))
+  const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`
+  globalThis.fetch = realFetch   // 本文件前面的用例会留桩，必须装回真 fetch
+  try {
+    // 用可注入的短超时（默认 300s，测起来太慢）；不注入就退回生产值。
+    const adapter = new RouterAdapter(base, { comboModels: async () => [] }, undefined, 400)
+    const started = Date.now()
+    const consume = (async () => {
+      for await (const _c of adapter.stream({ model: 'm', messages: [] } as never)) void _c
+    })()
+    const outcome = await Promise.race([
+      consume.then(() => 'ended', (e: Error) => `threw:${(e as Error & { code?: string }).code ?? e.message}`),
+      new Promise<string>((r) => setTimeout(() => r('HANG'), 4000)),
+    ])
+    const ms = Date.now() - started
+    console.log(`[gate] 无调用方 signal，停摆 → ${outcome} @${ms}ms`)
+    assert.notEqual(outcome, 'HANG', 'adapter 必须自带空闲超时，不能永久挂住')
+    assert.ok(String(outcome).includes('TIMEOUT'), `应抛 TIMEOUT（可重试码），实际 ${outcome}`)
+  } finally {
+    server.closeAllConnections?.()
+    server.close()
+  }
+})
+
+test('调用方取消必须能贯穿整条流（响应头到手后仍可中断，不永久挂住）', async () => {
+  // 用**真实 http server**：合成 ReadableStream 会给出假象（abort 对非 undici 流
+  // 无效）。这里上游发出响应头 + 一块数据后停摆，调用方给 1s 超时。
+  // 修复前：adapter 在 fetch 返回时就 removeEventListener，body 读无人打断 →
+  // 请求永久挂住（实测 6s 仍未收尾）。修复后：1s 左右被中止。
+  const http = await import('node:http')
+  const server = http.createServer((_req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' })
+    res.write('data: {"choices":[{"delta":{"content":"a"}}]}\n\n')
+    res.flushHeaders()          // 之后停摆：不吐数据也不结束
+  })
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()))
+  const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`
+  globalThis.fetch = realFetch   // 同上：必须先装回真 fetch
+  try {
+    const adapter = new RouterAdapter(base, { comboModels: async () => [] })
+    const t0 = Date.now()
+    const consume = (async () => {
+      for await (const _c of adapter.stream({ model: 'm', messages: [], signal: AbortSignal.timeout(1000) } as never)) void _c
+    })()
+    const outcome = await Promise.race([
+      consume.then(() => 'ended', (e: Error) => `threw:${e.message}`),
+      new Promise((r) => setTimeout(() => r('HANG'), 5000)),
+    ])
+    const ms = Date.now() - t0
+    console.log(`[gate] 停摆 + 1s 超时 → ${outcome} @${ms}ms`)
+    assert.notEqual(outcome, 'HANG', '调用方取消后必须收尾，不能永久挂住')
+    assert.ok(ms < 4000, `应在调用方超时附近收尾（实际 ${ms}ms）`)
+  } finally {
+    server.closeAllConnections?.()
+    server.close()
+  }
+})

package/src/llm/adapter.ts

@@ -81,6 +81,17 @@ export interface RouterAdapterSource {
 /** tool-result 里图片挂到 user 消息时用的说明文字（与官方适配器一致）。 */
 const TOOL_RESULT_IMAGE_TEXT = 'Tool result images'
 
+/**
+ * 流空闲超时：上游连上后这么久没吐**任何**字节就判失败（抛 TIMEOUT，可重试）。
+ *
+ * 对齐 `dsh-llm-pi-ai` 的 `DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000`：同一个
+ * dsh-router `/v1`，走自定义供应商（pi-ai）时有这个兜底、走内置 adapter 时没有
+ * —— 差异导致「上游停摆」在内置路径上永久挂住。
+ *
+ * 只守空闲、不封总时长：长生成只要持续吐块就不该被打断。
+ */
+const STREAM_IDLE_TIMEOUT_MS = 300_000
+
 async function wireMessages(options: GenerateOptions, system: string | undefined, attachments: RouterAttachmentStore | undefined): Promise<Array<Record<string, unknown>>> {
   const out: Array<Record<string, unknown>> = []
   /**
@@ -530,12 +541,24 @@ export class RouterAdapter extends LlmAdapter {
   private readonly baseURL: string
   private readonly source: RouterAdapterSource
   private readonly resolveAttachments: () => RouterAttachmentStore | undefined
+  /** 流空闲超时（ms）：上游这么久不吐字节就判 TIMEOUT。 */
+  private readonly idleTimeoutMs: number
 
-  constructor(baseURL: string, source: RouterAdapterSource, resolveAttachments?: () => RouterAttachmentStore | undefined) {
+  /**
+   * @param idleTimeoutMs 流空闲超时；缺省用生产值（300s，对齐 pi-ai）。
+   *   可注入只为测试能压到几百毫秒，生产不传。
+   */
+  constructor(
+    baseURL: string,
+    source: RouterAdapterSource,
+    resolveAttachments?: () => RouterAttachmentStore | undefined,
+    idleTimeoutMs: number = STREAM_IDLE_TIMEOUT_MS,
+  ) {
     super()
     this.baseURL = baseURL
     this.source = source
     this.resolveAttachments = resolveAttachments ?? (() => undefined)
+    this.idleTimeoutMs = idleTimeoutMs
   }
 
   providerInfo(provider: string): { id: string; name: string } {
@@ -602,16 +625,24 @@ export class RouterAdapter extends LlmAdapter {
         signal: controller.signal,
       })
     } catch (error) {
+      options.signal?.removeEventListener('abort', onAbort)
       throw new LlmError(`dsh-router upstream call failed: ${(error as Error).message}`, 'TRANSPORT', { cause: error })
+    }
+    // **监听必须活到整条流结束**，不能在 fetch 返回时就摘：`controller.signal`
+    // 已经把传入的 signal 与这次 fetch 绑在一起（含 body 流），响应头到手后
+    // body 还在读，此时调用方取消（用户中断 / agent-loop 收敛 / 上游停摆被
+    // 上层超时放弃）必须还能 abort 掉这次请求 —— 摘早了，body 读就无人打断，
+    // 请求永久挂住、连接也收不回（issue #6「内置供应商才挂死」的另一半）。
+    try {
+      if (!resp.ok) {
+        const detail = await resp.text().catch(() => '')
+        throw new LlmError(`dsh-router /v1 returned ${resp.status}: ${detail.slice(0, 200)}`, 'TRANSPORT')
+      }
+      if (resp.body === null) return
+      yield* translateSse(ssePayloads(resp.body, this.idleTimeoutMs))
     } finally {
       options.signal?.removeEventListener('abort', onAbort)
     }
-    if (!resp.ok) {
-      const detail = await resp.text().catch(() => '')
-      throw new LlmError(`dsh-router /v1 returned ${resp.status}: ${detail.slice(0, 200)}`, 'TRANSPORT')
-    }
-    if (resp.body === null) return
-    yield* translateSse(ssePayloads(resp.body))
   }
 }
 
@@ -641,16 +672,42 @@ function looksComplete(payload: string): boolean {
  * 跨块边界：一个 `data:` 行可能横跨两次 read()，所以留 `buffer` 接住
  * 最后一段未完整的行（9router 的 pipeTransformedSSE 同样处理）。
  */
-async function* ssePayloads(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+async function* ssePayloads(body: ReadableStream<Uint8Array>, idleTimeoutMs: number): AsyncGenerator<string> {
   const reader = body.getReader()
   const decoder = new TextDecoder('utf-8', { fatal: false })
   let buffer = ''
   /** 攒一帧内的多行 data（SSE 规范：多行用 \n 连起来）。**必须**是局部
    *  状态 —— 放模块级会让并发请求互相串数据。 */
   let payload = ''
+  /**
+   * 带**空闲超时**的读：上游连上后若长时间一个字节都不吐，就读穿不了 ——
+   * 没有超时的话这里会永久挂着，连接和 in-flight 请求都收不回。
+   *
+   * 为什么必须有（issue #6 的另一半）：`dsh-llm-pi-ai`（自定义供应商走的那条
+   * openai-completions adapter）有 `idleWatchdog`，默认 **300s** 空闲即
+   * `LLM_STREAM_IDLE_TIMEOUT` 中止；而本 adapter 此前**没有任何超时**，只靠
+   * 调用方的 `options.signal`。于是同一个组合，走内置 Router 时上游一停摆就
+   * 永久挂住（占用连接、且该请求永不收尾），走自定义供应商时 300s 后被放弃
+   * —— 放弃又会触发服务端那条「客户端断开不回收」的泄漏路径，两边叠加就是
+   * 「用久了报 connection error」。
+   *
+   * 只守**空闲**、不设总时长：长生成可以跑很久，只要还在吐块就不该被打断
+   * （总时长封顶会让长回答写到一半被砍）。
+   */
+  const readWithIdleTimeout = (): Promise<ReadableStreamReadResult<Uint8Array>> =>
+    new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new LlmError(`dsh-router upstream stream idle for ${idleTimeoutMs}ms`, 'TIMEOUT')),
+        idleTimeoutMs,
+      )
+      reader.read().then(
+        (r) => { clearTimeout(timer); resolve(r) },
+        (e) => { clearTimeout(timer); reject(e) },
+      )
+    })
   try {
     for (;;) {
-      const { done, value } = await reader.read()
+      const { done, value } = await readWithIdleTimeout()
       if (done) break
       buffer += decoder.decode(value, { stream: true })
       const lines = buffer.split('\n')

package/src/router/disconnect-leak.test.ts

@@ -0,0 +1,200 @@
+/**
+ * 客户端断开的连接回收测试 —— issue #6「组合模型用久了报 connection error」的真根因。
+ *
+ * 现象：把 `http://127.0.0.1:3080/v1` 加为**自定义供应商**（llm-pi-ai 的
+ * openai-completions）后，连续用半天到一天就全面 connection error；内置 Router
+ * 供应商同一个组合却正常。
+ *
+ * 真根因（**不是**「undici 每 origin 限 10 socket」——那条实测不成立，见下）：
+ * 客户端主动断开时，服务端 `writeChatResult` 只监听 `res` 的 `'error'`，**不监听
+ * `'close'`**。对端关闭触发的是 `'close'`，于是：
+ *   - 上游流还在推 → `writeChunk` 里 `res.write` 返回 false → 挂起等 `'drain'`
+ *   - 连接已死 → `'drain'` 永不到来 → `pipeTo` 永不 settle
+ *   - → `finally` 不执行 → 上游 fetch body **永不 cancel**
+ *   → 每次「客户端放弃」漏一条上游 TCP 连接 + 挂一个请求；长跑累积到 fd/端口耗尽。
+ *
+ * 为什么只有自定义供应商路径中招：pi-ai 有**流空闲超时**（idleWatchdog，默认
+ * 300s）和消费方提前退出时的 `consumer.abort()`，会**主动放弃**请求；而 dsh-router
+ * 自己的 adapter 不设任何超时、从不主动放弃 → 内置路径几乎不触发这条泄漏。
+ *
+ * 为什么「每 origin 10 socket」的解释不成立：实测（探针 I）连续泄漏 200 次
+ * **全部成功、无排队**（单次 ≤10ms），undici 会自行关闭多余连接 —— 默认 fetch
+ * 没有这个硬上限，所以「池满 → 全部 connection error」推不出来。
+ *
+ * 用 node --test 跑（Node 原生 TS 剥离，零新依赖）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import http from 'node:http'
+import { Router } from './index.ts'
+import { AccountPool } from './account-pool.ts'
+import type { ChatOnceResult, SupplierAccountNow, SupplierStatusNow } from '../suppliers/contract.ts'
+import type { ModelInfo } from './types.ts'
+
+/**
+ * 造一个**永不结束**的上游流（模拟长生成），并记录它有没有被 cancel。
+ * `enqueued` 用来证明「断开后服务端是否还在继续消费」。
+ */
+function infiniteStream(): { stream: ReadableStream<Uint8Array>; cancelled: () => boolean; enqueued: () => number } {
+  const enc = new TextEncoder()
+  let cancelled = false
+  let enqueued = 0
+  let timer: ReturnType<typeof setInterval> | undefined
+  const stream = new ReadableStream<Uint8Array>({
+    start(ctrl) {
+      timer = setInterval(() => {
+        try { ctrl.enqueue(enc.encode('data: {"choices":[{"delta":{"content":"x"}}]}\n\n')); enqueued += 1 } catch { /* closed */ }
+      }, 20)
+    },
+    cancel() { cancelled = true; if (timer !== undefined) clearInterval(timer) },
+  })
+  return { stream, cancelled: () => cancelled, enqueued: () => enqueued }
+}
+
+function supplierWith(stream: ReadableStream<Uint8Array>) {
+  return {
+    id: 'sup', name: 'sup', priority: 0, pool: new AccountPool('sup'),
+    status: (): SupplierStatusNow => ({ id: 'sup', name: 'sup', accounts: [] }),
+    listModels: async (): Promise<ModelInfo[]> => [{ id: 'm1' }],
+    accounts: (): SupplierAccountNow[] => [{ uid: 'u1', credits: 0, state: 'ok' }],
+    getAlias: () => 'sup',
+    chatOnce: async (): Promise<ChatOnceResult> => ({ ok: true, stream }),
+    dispose: () => {},
+  }
+}
+
+/** 建 server + 发起「拿一块就断」的请求，返回服务端是否收尾。 */
+async function abandonedRequest(
+  router: Router,
+  leak: { cancelled: () => boolean; enqueued: () => number },
+): Promise<{ settled: boolean; closeSeen: boolean; enqueuedAfterSettle: number }> {
+  let settled = false
+  let closeSeen = false
+  const server = http.createServer((req, res) => {
+    let body = ''
+    req.on('data', (c) => { body += c })
+    req.on('end', () => {
+      res.on('close', () => { closeSeen = true })
+      void router.chatCompletions(
+        { model: 'sup,m1', stream: true, rawBody: body } as never,
+        res as never,
+      ).then(() => { settled = true }, () => { settled = true })
+    })
+  })
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()))
+  const port = (server.address() as { port: number }).port
+
+  await new Promise<void>((resolve) => {
+    const creq = http.request({
+      host: '127.0.0.1', port, path: '/x', method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }, (cres) => {
+      cres.once('data', () => { creq.destroy(); resolve() })
+    })
+    creq.on('error', () => resolve())
+    creq.end(JSON.stringify({ model: 'sup,m1', messages: [{ role: 'user', content: 'hi' }], stream: true }))
+  })
+
+  await new Promise((r) => setTimeout(r, 1200))
+  const enqueuedAfterSettle = leak.enqueued()
+  server.closeAllConnections?.()
+  server.close()
+  return { settled, closeSeen, enqueuedAfterSettle }
+}
+
+test('客户端中途断开：服务端必须停手并 cancel 上游流（否则每放弃一次漏一条连接）', async () => {
+  const leak = infiniteStream()
+  const router = new Router('')
+  router.add(supplierWith(leak.stream) as never)
+
+  const { settled, closeSeen } = await abandonedRequest(router, leak)
+
+  assert.equal(closeSeen, true, 'server 应看到客户端 close')
+  assert.equal(settled, true, '客户端断开后请求处理必须收尾（不能永远挂着）')
+  assert.equal(leak.cancelled(), true, '上游流必须被 cancel（否则 fetch body 泄漏，累积到 connection error）')
+
+  // 断开后不能再继续消费上游
+  const a = leak.enqueued()
+  await new Promise((r) => setTimeout(r, 400))
+  assert.equal(leak.enqueued(), a, '断开后不该继续从上游拉数据')
+})
+
+test('客户端断开：上游流 cancel 链要穿过 tapStreamUsage / normalizeSSEStream 两层 wrapper', async () => {
+  // 带 probe（= 真实请求路径）时会多包一层 tapStreamUsage；两层 wrapper 都必须
+  // 实现 cancel→reader.cancel()，取消才到得了上游（缺一层就静默断链）。
+  const leak = infiniteStream()
+  const router = new Router('')
+  router.add(supplierWith(leak.stream) as never)
+
+  let settled = false
+  let closeSeen = false
+  const server = http.createServer((req, res) => {
+    let body = ''
+    req.on('data', (c) => { body += c })
+    req.on('end', () => {
+      res.on('close', () => { closeSeen = true })
+      void router.chatCompletions(
+        { model: 'sup,m1', stream: true, rawBody: body } as never,
+        res as never,
+      ).then(() => { settled = true }, () => { settled = true })
+    })
+  })
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()))
+  const port = (server.address() as { port: number }).port
+  await new Promise<void>((resolve) => {
+    const creq = http.request({
+      host: '127.0.0.1', port, path: '/x', method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }, (cres) => { cres.once('data', () => { creq.destroy(); resolve() }) })
+    creq.on('error', () => resolve())
+    creq.end(JSON.stringify({ model: 'sup,m1', messages: [{ role: 'user', content: 'hi' }], stream: true }))
+  })
+  await new Promise((r) => setTimeout(r, 1200))
+  server.closeAllConnections?.()
+  server.close()
+
+  assert.equal(closeSeen, true)
+  assert.equal(settled, true, '带探针的路径也必须收尾')
+  assert.equal(leak.cancelled(), true, '取消必须穿过两层 wrapper 到达上游')
+})
+
+test('聚合失败：reader 必须被解绑（否则连接还活着时上层无法 cancel）', async () => {
+  // 这一条测的**不是**「cancel 回调有没有触发」——那测不出东西：
+  // 实测结论（两个都验过）：
+  //   - 流 error 后调 cancel()，只会以同一错误 reject，**不触发** cancel 回调
+  //     （`pull()` 抛错会把流置为 errored；上游拆连接则流直接 error）
+  //   - 这两种情况下 undici **已经自己关了连接**，不需要我们 cancel
+  // 所以聚合失败路径真正要保证的是 **reader 被解绑**：流锁着的话，上层
+  // （writeChatResult 的失败路径 / 未来的取消逻辑）想 cancel 都会抛
+  // `Invalid state: ReadableStream is locked`，连接就永久漏了。
+  let releaseLocked = false
+  const enc = new TextEncoder()
+  const failing = new ReadableStream<Uint8Array>({
+    start(c) { c.enqueue(enc.encode('data: {"choices":[{"delta":{"content":"a"}}]}\n\n')) },
+    pull() { throw new Error('aggregate read failed') },
+  })
+  const origGetReader = failing.getReader.bind(failing)
+  ;(failing as unknown as { getReader: () => unknown }).getReader = () => {
+    const r = origGetReader()
+    const origRelease = r.releaseLock.bind(r)
+    r.releaseLock = () => { releaseLocked = true; origRelease() }
+    return r
+  }
+
+  const router = new Router('')
+  router.add(supplierWith(failing) as never)
+  const sink = {
+    writeHead: () => undefined, end: () => undefined, write: () => true,
+    once: () => undefined, removeListener: () => undefined, destroy: () => undefined,
+    writableEnded: false, destroyed: false,
+  } as never
+
+  await router.chatCompletions(
+    { model: 'sup,m1', stream: false, rawBody: JSON.stringify({ model: 'sup,m1', messages: [] }) } as never,
+    sink,
+  )
+  await new Promise((r) => setTimeout(r, 150))
+
+  assert.equal(releaseLocked, true, '聚合失败后必须 releaseLock，否则流锁死、上层无法回收')
+  assert.equal(failing.locked, false, '流必须处于未锁定状态（可被 cancel / 已被回收）')
+})

package/src/router/index.ts

@@ -140,6 +140,7 @@ async function aggregateSSE(stream: ReadableStream<Uint8Array>): Promise<string>
 
   const reader = stream.getReader()
   let buf = ''
+  try {
   for (;;) {
     const { done, value } = await reader.read()
     if (done) break
@@ -189,6 +190,12 @@ async function aggregateSSE(stream: ReadableStream<Uint8Array>): Promise<string>
       }
     }
   }
+  } finally {
+    // 无论正常读完还是中途抛错，都要**解绑** reader：调用方（writeChatResult）
+    // 在失败路径里要对同一流 cancel()，而流被锁住时 cancel 会抛
+    // `Invalid state: ReadableStream is locked` —— 那样这次的连接就漏了。
+    try { reader.releaseLock() } catch { /* 有待定 read 时会抛，忽略 */ }
+  }
 
   const toolCalls = [...calls.entries()]
     .sort((a, b) => a[0] - b[0])
@@ -242,9 +249,11 @@ function normalizeSSEStream(stream: ReadableStream<Uint8Array>): {
   const dec = new TextDecoder()
   let buf = ''
   let sawDone = false
+  /** 上游 reader：cancel 时要靠它把取消传下去（见下方 cancel 分支）。 */
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
   const out = new ReadableStream<Uint8Array>({
     start: async (ctrl) => {
-      const reader = stream.getReader()
+      reader = stream.getReader()
       try {
         for (;;) {
           const { done, value } = await reader.read()
@@ -263,11 +272,21 @@ function normalizeSSEStream(stream: ReadableStream<Uint8Array>): {
           if (isDoneFrame(buf)) sawDone = true
           ctrl.enqueue(enc.encode(fixFrame(buf)))
         }
+      } catch {
+        // 消费方取消（客户端断开）会让挂起的 read 抛错/返回 done —— 静默收尾
       } finally {
-        reader.releaseLock()
+        try { reader.releaseLock() } catch { /* 有待定 read 时会抛，忽略 */ }
       }
-      ctrl.close()
+      try { ctrl.close() } catch { /* 已取消 */ }
     },
+    /**
+     * **取消必须往下传**：ReadableStream 的取消不会自动穿过 wrapper。
+     * 不实现这个分支，客户端断开的取消就停在这里，上游 fetch body 永不 cancel
+     * ——那条 TCP 连接和 in-flight 请求原样挂着（长跑一天就会累积到耗尽）。
+     * 用 reader.cancel() 而不是 stream.cancel()：流已被 getReader() 锁住，
+     * 直接 cancel 会抛 `Invalid state: ReadableStream is locked`。
+     */
+    cancel: (reason) => reader?.cancel(reason),
   })
   return { stream: out, sawDone: () => sawDone }
 }
@@ -338,7 +357,12 @@ async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStre
     try {
       body = await aggregateSSE(r.stream)
     } catch {
-      return false // 聚合失败 = 一个字节都没写，调用方可以换号重试
+      // 聚合失败 = 一个字节都没写，调用方可以换号重试。
+      // **但底层流必须 cancel**：aggregateSSE 内部 getReader() 消费到一半抛错时，
+      // reader 只是 releaseLock()，传输层毫无察觉 —— 那条上游连接会一直挂着。
+      // 不 cancel 就退化成「每次聚合失败漏一条连接」（issue #6 的路径 1）。
+      await r.stream.cancel().catch(() => {})
+      return false
     }
     if (probe !== undefined) probe.tokens = usageFromJsonBody(body)
     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
@@ -351,6 +375,18 @@ async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStre
   let wroteAny = false
   /** 响应已死（客户端断开/res 已销毁）：等 drain 的写入要立刻放弃，别吊死。 */
   let dead = false
+  /**
+   * 唤醒「等 drain 的挂起 write」。客户端断开时必须调它：那时 'drain' 永不到来，
+   * 不唤醒就永远卡在 write 里，pipeTo 不 settle，finally 不执行，
+   * **上游流也就永不 cancel**（= 每次客户端放弃漏一条连接）。
+   */
+  let releaseWait: (() => void) | undefined
+  /**
+   * 中止 pipeTo 的信号源（客户端断开时 abort）。
+   * 单靠 `dead` 标志只能让**下一次** write 立刻返回，唤醒不了**已经挂起**的那次；
+   * abort 才能让 pipeTo 立刻收尾并走它的取消路径（进而 cancel 上游）。
+   */
+  const abort = new AbortController()
   const writeChunk = (chunk: Uint8Array): Promise<void> =>
     new Promise<void>((resolve) => {
       if (dead) { resolve(); return }
@@ -370,25 +406,44 @@ async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStre
       if (res.write(chunk)) resolve()
       else {
         // 背压：等 drain。但连接可能在这期间断掉 —— 那时 'drain' 永不到来，
-        // 得靠 dead 标志（onError 里置位）兜住，否则这次请求会永远挂着。
+        // 得靠 release() 兜住（客户端断开时唤醒），否则这次请求会永远挂着。
         const onDrain = (): void => { res.removeListener('error', onDrain); resolve() }
         res.once('drain', onDrain)
+        /** 让这个挂起的 write 立刻收尾（客户端断开时调用）。 */
+        releaseWait = () => { res.removeListener('drain', onDrain); resolve() }
       }
     })
 
-  // 流中途出错（客户端断开/上游断流）也要结束响应，否则连接悬挂
+  // 客户端断开 / 流中途出错都要停手，否则连接悬挂
   const onError = (): void => {
     dead = true
     res.destroy()
   }
   res.once('error', onError)
+  /**
+   * **客户端断开必须被当成取消信号**：只监听 'error' 是不够的 —— 对端关闭
+   * （pi-ai 的流空闲超时、用户取消、消费方提前退出）触发的是 'close'，
+   * 不是 'error'。此时若不收手，pipeTo 会一直等着 drain（永不到来），
+   * finally 永不执行，上游 fetch body **永不 cancel** → 那条 TCP 连接和
+   * in-flight 请求原样挂着，长跑累积到耗尽（"用久了就报 connection error"）。
+   */
+  const onClose = (): void => {
+    if (res.writableEnded) return // 正常写完的 close，不是取消
+    dead = true
+    releaseWait?.()
+    abort.abort()
+  }
+  res.once('close', onClose)
   const norm = normalizeSSEStream(tapped?.stream ?? r.stream)
   try {
-    await norm.stream.pipeTo(new WritableStream<Uint8Array>({ write: writeChunk }))
+    // signal 让 abort 时 pipeTo 立刻收尾（而不是等 drain）；其收尾路径会
+    // cancel 源流，顺着 wrapper 的 cancel 一路传到上游 fetch body。
+    await norm.stream.pipeTo(new WritableStream<Uint8Array>({ write: writeChunk }), { signal: abort.signal })
   } catch {
-    // 流断了：一个字节都没写的话，调用方还能换号重试——交给上层决定
+    // 断流/取消：一个字节都没写的话，调用方还能换号重试——交给上层决定
   } finally {
     res.removeListener('error', onError)
+    res.removeListener('close', onClose)
     // 断流也要给客户端一个终止帧。客户端（dsh-llm adapter）严格等
     // `[DONE]`，缺了就整轮判失败（`SSE payload stream ended without
     // [DONE]`），已经流式吐出去的内容全部作废。上游自己发了就不重复发
@@ -396,10 +451,11 @@ async function writeChatResult(res: ServerResponse, r: ChatOnceResult, wantsStre
     //
     // 只在**已提交响应**时补：一个字节都没写 = 还能换号重试，补了就等于
     // 把这次失败坐实成一个空响应，组合回退就没了。
+    // dead（客户端已走）时也不补：对端没了，写了也没人收。
     if (wroteAny && !norm.sawDone() && !dead && !res.writableEnded && !res.destroyed) {
       await writeChunk(DONE_FRAME)
     }
-    if (wroteAny) res.end()
+    if (wroteAny && !dead) res.end()
     // 流走完才出得了 usage（上游多在最后一帧才发 usage）
     if (probe !== undefined && tapped !== undefined) {
       const got = await tapped.done()

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)
 
@@ -269,9 +280,11 @@ export function tapStreamUsage(
     }
   }
 
+  /** 源 reader：cancel 时要靠它把取消传下去（见下方 cancel 分支）。 */
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
   const stream = new ReadableStream<Uint8Array>({
     start: async (ctrl) => {
-      const reader = source.getReader()
+      reader = source.getReader()
       try {
         for (;;) {
           const { done, value } = await reader.read()
@@ -289,11 +302,19 @@ export function tapStreamUsage(
           ctrl.enqueue(value as Uint8Array)
         }
         if (buf !== '') parseFrame(buf)
+      } catch {
+        // 消费方取消会让挂起的 read 收尾 —— 静默退出
       } finally {
-        reader.releaseLock()
+        try { reader.releaseLock() } catch { /* 有待定 read 时会抛，忽略 */ }
       }
-      ctrl.close()
+      try { ctrl.close() } catch { /* 已取消 */ }
     },
+    /**
+     * 取消要往下传（同 normalizeSSEStream 的理由）：不传 → 客户端断开时
+     * 上游 fetch body 永不 cancel，连接与 in-flight 请求一直挂着。
+     * 必须用 reader.cancel()：流已被 getReader() 锁住，stream.cancel() 会抛。
+     */
+    cancel: (reason) => reader?.cancel(reason),
   })
 
   return {

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 })