dsh-router-core 0.4.5 → 0.4.7

package/src/protocol/wiring.test.ts

@@ -0,0 +1,225 @@
+/**
+ * 协议接线的**接线事实**判据 —— 守「四种协议真的挂上去了」这件事。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么需要这一组（而不是只测编解码器）
+ * ════════════════════════════════════════════════════════════════════
+ * 编解码器全绿、端点却是 404/405 —— 这是 2026-10-21 真实发生的状态：
+ *   - `/v1beta/models/` 的 prefix 带了尾斜杠，宿主匹配规则是
+ *     `pathname.startsWith(prefix + '/')`，于是永远比不上 → GET 404 / POST 405；
+ *   - `chatCompletions` 里造了 `out`（sink 包装）却没用它，所有写入仍走 `res`
+ *     → 非 chat 协议拿到的仍是 OpenAI 形态。
+ * 两条都在**单元测试全绿**的前提下发生。所以这里测的是接线本身：
+ * 路径前缀、以及「写入方到底写到谁」。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { geminiModelFromPath, geminiStreamFromPath } from './entry.ts'
+import { StreamState, translateStream } from './stream.ts'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(HERE, '..', '..')
+
+function source(rel: string): string {
+  return readFileSync(join(ROOT, rel), 'utf8')
+}
+
+/* ------------------------------------------------------------------ */
+/* 1. Gemini 的 prefix 不能带尾斜杠                                    */
+/* ------------------------------------------------------------------ */
+
+test('★ Gemini 路由注册的 prefix 不带尾斜杠（否则宿主永不匹配 → 404/405）', () => {
+  // 判据直接读源码：这是**接线**的正确性，不是某个函数的正确性。
+  // 为什么要钉这一条：宿主 `Table.match()` 的规则是
+  //   `pathname === prefix || pathname.startsWith(prefix + '/')`
+  // 带尾斜杠时它去比 `'/v1beta/models//'`，实际请求永远比不过。404/405 的
+  // 症状离根因太远（看起来像「端点没实现」），必须在这里拦住。
+  const src = source('src/index.ts')
+  const m = /kind:\s*'prefix',\s*\n\s*path:\s*'([^']+)'/.exec(src)
+  assert.ok(m !== null, '没找到 prefix 路由注册 —— 路由被删了？')
+  const path = m[1]!
+  assert.ok(
+    !path.endsWith('/'),
+    `prefix 尾斜杠会让宿主匹配成 '${path}/'，实际请求永不命中（2026-10-21 实测 404/405）`,
+  )
+  assert.equal(path, '/v1beta/models')
+})
+
+test('Gemini 路径解析：模型名从 URL 取，streamGenerateContent 也能认', () => {
+  assert.equal(geminiModelFromPath('/v1beta/models/gemini-2.5-pro:generateContent'), 'gemini-2.5-pro')
+  assert.equal(geminiModelFromPath('/v1beta/models/x:streamGenerateContent'), 'x')
+  // 带 query（Gemini 的 ?key= 形态）也能取
+  assert.equal(geminiModelFromPath('/v1beta/models/m:generateContent?key=abc'), 'm')
+  // 命名空间带斜杠的模型 id
+  assert.equal(geminiModelFromPath('/v1beta/models/publishers/google/models/gemini:generateContent'), 'publishers/google/models/gemini')
+  // 不认识的路径返回 undefined（不能瞎猜一个模型名）
+  assert.equal(geminiModelFromPath('/v1/models'), undefined)
+})
+
+/* ------------------------------------------------------------------ */
+/* 2. 非 chat 协议的响应必须真的经过 sink                              */
+/* ------------------------------------------------------------------ */
+
+test('★ chatCompletions 内部一律写 out（sink 包装），不许再写 res', () => {
+  // 这条守的是「协议翻译是否真的接上」：造了 `out` 却仍写 `res` = 翻译层
+  // 形同虚设，非 chat 客户端会收到 OpenAI 形态（2026-10-21 实测状态）。
+  const src = source('src/router/index.ts')
+  const start = src.indexOf('async chatCompletions(')
+  assert.ok(start > 0, '找不到 chatCompletions')
+  const end = src.indexOf('/** 调指定供应商。', start)
+  assert.ok(end > start, '找不到 chatCompletions 的结尾')
+  const body = src.slice(start, end)
+
+  // 允许出现 res 的地方：签名行 + out 的定义行
+  const allowed = [
+    'async chatCompletions(req: ChatRequest, res: ServerResponse, sink?: ResponseSink): Promise<void> {',
+    'const out = sink === undefined ? res : sinkRes(sink)',
+  ]
+  let scanned = body
+  for (const a of allowed) scanned = scanned.replace(a, '')
+
+  const hits = [...scanned.matchAll(/\bres\b/g)]
+  assert.equal(
+    hits.length,
+    0,
+    `chatCompletions 方法体内还有 ${hits.length} 处直接使用 res —— `
+    + '响应绕过了 sink，非 chat 协议会收到 OpenAI 形态',
+  )
+})
+
+test('非 chat 入口确实把 sink 传给 chatCompletions（不是只 parse 不接出站）', () => {
+  const src = source('src/index.ts')
+  // enterProtocol 里必须：造 sink 并作为第三个参数传进去
+  const m = /const sink = outboundSink\(protocol, parsed\.model, res\)/.exec(src)
+  assert.ok(m !== null, '没造 outboundSink')
+  const call = /await router\.chatCompletions\(\s*\{[\s\S]{0,400}?\},\s*res,\s*sink,\s*\)/.exec(src)
+  assert.ok(call !== null, 'sink 没传给 chatCompletions —— 出站翻译不会生效')
+})
+
+/* ------------------------------------------------------------------ */
+/* 3. 四条入站路由都注册了                                            */
+/* ------------------------------------------------------------------ */
+
+test('★ 四种协议的入站端点全部注册（少一条就是那种协议不可用）', () => {
+  const src = source('src/index.ts')
+  // 只认「route(...) 调用」与 prefix register，避免注释里提到也算命中
+  const routes = [
+    { name: 'chat', pattern: /route\('\/v1\/chat\/completions'/ },
+    { name: 'anthropic', pattern: /route\('\/v1\/messages'/ },
+    { name: 'responses', pattern: /route\('\/v1\/responses'/ },
+    { name: 'gemini', pattern: /path: '\/v1beta\/models'/ },
+  ]
+  for (const r of routes) {
+    assert.ok(r.pattern.test(src), `${r.name} 的入站路由没注册`)
+  }
+})
+
+test('count_tokens 明确 501（不编 token 数）', () => {
+  const src = source('src/index.ts')
+  assert.ok(src.includes("route('/v1/messages/count_tokens'"), 'count_tokens 路由没注册')
+  assert.ok(/writeJson\(res,\s*501/.test(src), 'count_tokens 应当 501，不该假装能数')
+})
+
+/* ------------------------------------------------------------------ */
+/* 4. 供应商 wire 的读取点存在                                        */
+/* ------------------------------------------------------------------ */
+
+test('★ 供应商声明非 chat wire 时，chatOnce 调用被包翻译', () => {
+  const src = source('src/router/index.ts')
+  const start = src.indexOf('private async chatWithSupplier(')
+  // 下一个方法（testModel）的文档注释起点作结束标记
+  const end = src.indexOf('测试某供应商的某模型是否可用。', start)
+  assert.ok(start > 0 && end > start, '找不到 chatWithSupplier')
+  const body = src.slice(start, end)
+  // chatWithSupplier 必须用包过的 chatOnce，而不是裸 s.chatOnce
+  assert.ok(body.includes('const chatOnce = this.wireOf(s)'), 'chatWithSupplier 没取 wire 包装')
+  assert.ok(!/await s\.chatOnce\(/.test(body), 'chatWithSupplier 里还在裸调 s.chatOnce，翻译被绕过')
+
+  // wireChatOnce 本体：读 s.wire、非 chat 时包 translateStream
+  const ws = src.indexOf('function wireChatOnce(')
+  const we = src.indexOf('/** 从上游响应体提取错误信息', ws)
+  assert.ok(ws > 0 && we > ws, '找不到 wireChatOnce')
+  const impl = src.slice(ws, we)
+  assert.ok(/s\.wire \?\? 'chat'/.test(impl), 'wireChatOnce 没读供应商的 wire 声明')
+  assert.ok(impl.includes('translateStream(r.stream'), 'wireChatOnce 没给上游流套协议翻译')
+  assert.ok(impl.includes('codec.fromChat('), 'wireChatOnce 没翻请求体')
+})
+
+test('★ Gemini 的流式意图来自 URL 路径（body 里没有 stream 字段）', () => {
+  // 事故（2026-10-21 在 3080 实测）：`:streamGenerateContent` 请求被当成
+  // 非流式，客户端拿到一整个 JSON 却按 SSE 解析 ⇒ 空响应。
+  assert.equal(geminiStreamFromPath('/v1beta/models/m:streamGenerateContent'), true)
+  assert.equal(geminiStreamFromPath('/v1beta/models/m:streamGenerateContent?alt=sse'), true)
+  assert.equal(geminiStreamFromPath('/v1beta/models/m:generateContent'), false)
+  // 路径没表态 → undefined（交给 body 的 stream 决定）
+  assert.equal(geminiStreamFromPath('/v1/messages'), undefined)
+})
+
+test('★ 入口确实把 streamFromPath 传进 parseInbound（否则上面那条解析等于没接）', () => {
+  const src = source('src/index.ts')
+  assert.ok(
+    /streamFromPath: protocol === 'gemini' \? geminiStreamFromPath\(req\.url \?\? ''\)/.test(src),
+    'Gemini 的路径流式意图没接进 parseInbound',
+  )
+})
+
+/* ------------------------------------------------------------------ */
+/* 4. 流式收尾：用量必须进收尾帧，且不许重复 message_delta             */
+/* ------------------------------------------------------------------ */
+
+test('★ Anthropic 流式收尾：message_delta 只发一次，且带真实 output_tokens', async () => {
+  // 事故（2026-10-21 在 3080 实测）：finish 与 usage 各发一帧 message_delta，
+  // 第一帧是 stop_reason + output_tokens:0（占位）、第二帧才是真数。
+  // Anthropic 客户端取第一个 ⇒ 用量永远读成 0。
+  const upstream = new ReadableStream<Uint8Array>({
+    start(ctrl) {
+      ctrl.enqueue(new TextEncoder().encode(
+        'data: {"choices":[{"delta":{"content":"hi"}}]}\n\n'
+        + 'data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":9,"completion_tokens":7}}\n\n'
+        + 'data: [DONE]\n\n',
+      ))
+      ctrl.close()
+    },
+  })
+  // 直接驱动 StreamState：translateStream 会自己建 state，这里要拿到它的收尾帧
+  const state = new StreamState('chat', 'anthropic', 'm')
+  const text = await new Response(translateStream(upstream, state)).text()
+
+  const deltas = text.split('\n\n').filter((f) => f.includes('event: message_delta'))
+  assert.equal(deltas.length, 1, `message_delta 应当只发一次，实际 ${deltas.length} 次`)
+
+  const payload = JSON.parse(deltas[0]!.split('\ndata: ')[1]!) as {
+    delta: { stop_reason?: string }
+    usage: { output_tokens?: number }
+  }
+  assert.equal(payload.delta.stop_reason, 'end_turn')
+  assert.equal(payload.usage.output_tokens, 7, '收尾帧的 output_tokens 必须是真数，不是占位 0')
+})
+
+test('★ Gemini 流式：functionCall 必须排在 finishReason 之前', async () => {
+  // 事故（2026-10-22 在 3080 实测）：Gemini 的 functionCall 攒到流末才发，
+  // 而 finishReason 由 encodeFrame(finish) 提前发出 —— 客户端看到 finishReason
+  // 就收尾这一轮，随后到达的工具调用被丢掉。
+  const state = new StreamState('chat', 'gemini', 'm')
+  const upstream = new ReadableStream<Uint8Array>({
+    start(ctrl) {
+      ctrl.enqueue(new TextEncoder().encode(
+        'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"c1","function":{"name":"get_weather","arguments":""}}]}}]}\n\n'
+        + 'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\\"city\\":\\"Beijing\\"}"}}]}}]}\n\n'
+        + 'data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}\n\n'
+        + 'data: [DONE]\n\n',
+      ))
+      ctrl.close()
+    },
+  })
+  const text = await new Response(translateStream(upstream, state)).text()
+  const callAt = text.indexOf('functionCall')
+  const finishAt = text.indexOf('finishReason')
+  assert.ok(callAt >= 0, 'functionCall 丢了')
+  assert.ok(finishAt >= 0, 'finishReason 丢了')
+  assert.ok(callAt < finishAt, `functionCall(idx ${callAt}) 必须排在 finishReason(idx ${finishAt}) 之前`)
+  assert.ok(text.includes('Beijing'), '工具参数没攒完整')
+})

package/src/router/account-pool.test.ts

@@ -660,3 +660,38 @@ test('【隔离】不同供应商的同名模型，各自独立冷却', () => {
   // B 供应商同名模型不受影响
   assert.equal(pb.pick(list, [], 'deepseek-v4-flash'), 'acc', 'B 池同名模型照常可用')
 })
+
+// ============ 限流冷却对齐上游声明的重置时刻（resetAt） ============
+
+/**
+ * 2026-10-15 事故：6004 文案自带「将在 … 重置」（小时级），但退避上限 5min →
+ * 到点回来再撞，11 个号轮流被打冷。锁住：带 resetAt 就冷到那个点；
+ * 过期/未带的 resetAt 退回指数退避（行为与改动前一致）。
+ */
+test('【resetAt】限流冷却到上游声明的重置时刻，而不是 5min 退避上限', () => {
+  const p = pool()
+  const list = accs(['a'])
+  const resetAt = Date.now() + 3 * 3600_000 // 3 小时后重置
+  p.noteFailure('a', 'm1', 'rate_limit', 'codebuddy 6004: 您的使用量已超出频率限制，将在 … 重置', resetAt)
+  const row = p.decorate(list, 'm1')[0]
+  assert.equal(row?.cooling, true)
+  assert.equal(row?.until === undefined ? 0 : new Date(row.until).getTime(), resetAt, '冷到上游重置点')
+  assert.equal(p.pick(list, [], 'm1'), undefined, '重置前不该再被选中')
+})
+
+test('【resetAt】过期的重置时刻退回指数退避；不带 resetAt 行为不变', () => {
+  const p = pool()
+  const list = accs(['a'])
+  // 上游报的重置时刻已过 → 退避（首档 2s 量级），不是「不冷」也不是冷很久
+  p.noteFailure('a', 'm1', 'rate_limit', '429', Date.now() - 1000)
+  const row = p.decorate(list, 'm1')[0]
+  const until = row?.until === undefined ? 0 : new Date(row.until).getTime()
+  assert.ok(until > Date.now(), '仍要冷')
+  assert.ok(until - Date.now() <= 60_000, '退回短退避，而不是按过期时刻冷')
+  // 不带 resetAt（其它供应商/文案没解析出）：同样短退避
+  const p2 = pool()
+  p2.noteFailure('b', 'm1', 'rate_limit', '429')
+  const row2 = p2.decorate(accs(['b']), 'm1')[0]
+  const until2 = row2?.until === undefined ? 0 : new Date(row2.until).getTime()
+  assert.ok(until2 > Date.now() && until2 - Date.now() <= 60_000)
+})

package/src/router/account-pool.ts

@@ -54,7 +54,9 @@ const SESSION_DEAD_COOLDOWN_MS = 30 * MINUTE
  *
  * 冷却策略对齐 9router 的 accountFallback / errorConfig：
  *  - `rate_limit` 用**指数退避**（9router 的 `backoff: true`）：偶发限流只
- *    短冷，持续限流越退越久，比固定 1 分钟两头不讨好要准。
+ *    短冷，持续限流越退越久，比固定 1 分钟两头不讨好要准。上游自己声明了
+ *    **重置时刻**（resetAt，如 6004「将在 … 重置」）时冷到该点——频率配额是
+ *    小时级的，退避上限（5min）只会到点回来再撞。
  *  - 未知/瞬时错误用**瞬时短冷却**（9router 默认分支 TRANSIENT_COOLDOWN_MS）：
  *    每次失败都冻结，坏号不会留在池里被下一个请求再选中。
  *
@@ -495,8 +497,13 @@ export class AccountPool {
     return `${this.supplierId}${SEP}${modelId}`
   }
 
-  /** 记录一次失败：按状态处置（冷却/退避），落在「(模型, 连接)」这个冷却单元上。 */
-  noteFailure(uid: string, modelId: string, state: AccountState, message: string): void {
+  /**
+   * 记录一次失败：按状态处置（冷却/退避），落在「(模型, 连接)」这个冷却单元上。
+   * `resetAt` = 上游声明的重置时刻（epoch ms）：限流退避优先冷到该点——
+   * 频率配额是小时级的，5min 上限的指数退避只会到点回来再撞 6004，
+   * 把号轮流打冷（2026-10-15 的 11 号全灭事故）。
+   */
+  noteFailure(uid: string, modelId: string, state: AccountState, message: string, resetAt?: number): void {
     const rule = RULES[state]
     if (rule.cooldown === 0) return // no_such_model 等：不冷不记
     // session_dead 是连接级冷却（登录态问题，跨该号所有模型），到期自愈——
@@ -514,7 +521,11 @@ export class AccountPool {
     if (rule.cooldown === 'backoff') {
       // 连续被限流 → 等级递进冷却；成功（noteSuccess）会清零等级
       e.backoffLevel = Math.min(e.backoffLevel + 1, BACKOFF_MAX_LEVEL)
-      e.until = Math.max(e.until, Date.now() + backoffMs(e.backoffLevel))
+      const backoffUntil = Date.now() + backoffMs(e.backoffLevel)
+      // 上游自己报了重置时刻就冷到那个点（且不低于已有的更长冷却）；过期/
+      // 未报的 resetAt 退回指数退避。
+      const until = resetAt !== undefined && resetAt > Date.now() ? resetAt : backoffUntil
+      e.until = Math.max(e.until, until)
       return
     }
     if (rule.cooldown === 'transient') {

package/src/router/index.ts

@@ -13,6 +13,9 @@ import { AccountPool } from './account-pool.ts'
 import { SupplierConfigStore } from '../supplier-config.ts'
 import { UsageStore } from './usage-store.ts'
 import { tapStreamUsage, usageFromJsonBody, withEstimates, type UsageTokens } from './usage-tokens.ts'
+import { codecOf } from '../protocol/index.ts'
+import { StreamState, translateStream } from '../protocol/stream.ts'
+import type { JsonObject } from '../protocol/types.ts'
 
 /** 一次 chat 的追踪信息（记日志用，回答「到底用的哪个模型哪个号」）。 */
 interface ChatTrace {
@@ -191,29 +194,62 @@ function reqMessages(rawBody: string): unknown {
 }
 
 /** 丢弃响应的假 ServerResponse（测试模型用：记录状态+内容，用于判定成败）。 */
-function sinkRes(): ServerResponse & { status(): number; body(): string } {
-  let status = 200
-  let text = ''
+/**
+ * 响应收集器：把 Router 本来要写给 `res` 的东西收进来，让调用方翻译后自己写。
+ *
+ * 只给**非 chat 协议**用（`/v1/messages`、`/v1/responses`、Gemini）：Router 只会
+ * 写 OpenAI 形态，而客户端要的是别的协议，中间必须插一层翻译。插入点在
+ * `chatCompletions` 的入口 —— 那里是唯一能同时看到「响应还没开始写」与
+ * 「协议是什么」的地方。
+ *
+ * 三条路径都要接住，漏一条就是那个协议下的一种故障：
+ *   - `head(status, headers)` —— 非流式的状态行（503 也走这里）
+ *   - `write(bytes)` —— 流式的 SSE 字节（可能是多段）
+ *   - `end()` —— 流结束
+ *
+ * 流式的 `writeHead` 是**延迟到第一个字节**才发生的（见 writeChatResult），
+ * 所以 `head` 在流式下可能一次都不来；调用方不能假设它来过。
+ */
+export interface ResponseSink {
+  /** 状态行 + 响应头（流式下可能不来；来了就一次）。 */
+  head?: (status: number, headers: Record<string, string>) => void
+  /** 一段响应体字节。 */
+  write: (bytes: Uint8Array) => void
+  /** 响应体结束。 */
+  end: () => void
+}
+
+/** 把 ResponseSink 包成一个 Router 能写的 ServerResponse。 */
+function sinkRes(sink: ResponseSink): ServerResponse {
   const self = {
     headersSent: false,
     writableEnded: false,
-    writeHead: (code: number): unknown => {
-      status = code
+    destroyed: false,
+    writeHead: (code: number, headers?: Record<string, string>): unknown => {
+      sink.head?.(code, headers ?? {})
       return self
     },
     write: (chunk?: unknown): boolean => {
-      if (chunk !== undefined) text += String(chunk)
+      if (chunk !== undefined) {
+        sink.write(typeof chunk === 'string' ? new TextEncoder().encode(chunk) : (chunk as Uint8Array))
+      }
       return true
     },
     end: (chunk?: unknown): unknown => {
-      if (chunk !== undefined) text += String(chunk)
+      if (chunk !== undefined) self.write(chunk)
+      sink.end()
       return self
     },
     flushHeaders: (): void => {},
-    status: (): number => status,
-    body: (): string => text,
+    once: (): unknown => self,
+    on: (): unknown => self,
+    removeListener: (): unknown => self,
+    destroy: (): void => { self.destroyed = true },
+    setHeader: (): unknown => self,
+    removeHeader: (): unknown => self,
+    writeableEnded: false,
   }
-  return self as unknown as ServerResponse & { status(): number; body(): string }
+  return self as unknown as ServerResponse
 }
 
 /**
@@ -594,6 +630,56 @@ async function writeChatResult(
 /** SSE 终止帧（断流兜底补发用）。 */
 const DONE_FRAME = new TextEncoder().encode('data: [DONE]\n\n')
 
+/**
+ * 取该供应商的 `chatOnce`，按它声明的 wire 包一层协议翻译。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么翻译放在核心、而不是让插件自己做
+ * ════════════════════════════════════════════════════════════════════
+ * 插件自己翻译意味着「每个只会说 Anthropic 的供应商各写一份 Anthropic→OpenAI
+ * 转换」，与账号池/冷却表/积分落盘是同一个错误：N 份互相不一致的实现，核心
+ * 也就无从判断该不该换号。放在核心，插件契约不变（仍只吐 OpenAI SSE），
+ * 换号/冷却/用量全部照旧生效。
+ *
+ * 翻译**只碰请求体与响应流**，不碰 `chatOnce` 的返回值语义：失败仍然返回
+ * `{ok:false, state, message}`，核心的冷却/回退逻辑一行不改。
+ *
+ * 非流式同理：上游给 JSON 时，先把它翻成规范 JSON 再交给核心（`writeChatResult`
+ * 的 `!('stream' in r)` 分支），客户端要流式而上游只给 JSON 时由现有的
+ * `aggregateSSE` 兜底（那条路径本来就要把 JSON 折成流）。
+ */
+function wireChatOnce(s: Supplier): (uid: string, lv: string, req: ChatRequest) => Promise<ChatOnceResult> {
+  const wire = s.wire ?? 'chat'
+  // 恒等快通道：今天所有供应商都是 chat，别为一个 no-op 造闭包 + 包流
+  if (wire === 'chat') return (uid, lv, req) => s.chatOnce(uid, lv, req)
+  const codec = codecOf(wire)
+  return async (uid, lv, req) => {
+    // 请求体：规范 → 上游协议。解析失败（坏 JSON）时原样交给插件 ——
+    // 插件的报错比在这里猜一个形状更接近真相。
+    let outReq = req
+    let body: JsonObject | undefined
+    try {
+      body = JSON.parse(req.rawBody) as JsonObject
+    } catch {
+      body = undefined
+    }
+    if (body !== undefined) {
+      outReq = {
+        ...req,
+        rawBody: JSON.stringify(codec.fromChat(body, { model: req.model, stream: req.stream })),
+      }
+    }
+    const r = await s.chatOnce(uid, lv, outReq)
+    if (!r.ok || !('stream' in r)) return r
+    // 响应流：上游协议 → OpenAI SSE。
+    //
+    // 首字节预算**不在这里套**：`writeChatResult` 已经给上游流套了
+    // `withFirstByteDeadline`，而那时流还是 OpenAI 形态（本函数返回的已经是
+    // 翻好的）。在翻好的流上再套一次会把两个预算叠起来，且翻译本身不该有超时。
+    return { ok: true, stream: translateStream(r.stream, new StreamState(wire, 'chat')) }
+  }
+}
+
 /** 从上游响应体提取错误信息（OpenAI {error:{message}} 或 {code,msg}/{message}）。 */
 function extractUpstreamError(body: string): string {
   try {
@@ -854,6 +940,16 @@ export class Router {
     return out
   }
 
+  /**
+   * 该供应商的 `chatOnce`，已按它声明的 wire 包好协议翻译。
+   *
+   * 每次调用都现取（而不是构造时缓存）：供应商会被开关/热重载替换，
+   * 缓存会把旧实例的翻译绑在新实例上。
+   */
+  private wireOf(s: Supplier): (uid: string, lv: string, req: ChatRequest) => Promise<ChatOnceResult> {
+    return wireChatOnce(s)
+  }
+
   /** 组合列表（面板用）：用户自定义组合。 */
   async combos(): Promise<Combo[]> {
     return [...this.customCombos]
@@ -1078,7 +1174,17 @@ export class Router {
    * - model 命中组合名 → 在组合模型里按策略选一个，交给供应商；失败按回退顺序尝试剩余模型。
    * - 否则 → 依次尝试供应商，直到某个返回 true（已写响应）或全部返回 false。
    */
-  async chatCompletions(req: ChatRequest, res: ServerResponse): Promise<void> {
+  /**
+   * 规范请求入口。
+   *
+   * @param res 真实的客户端响应。协议非 chat 时**不直接用它**，而是经
+   *   `sink` 先收集再翻译（见 `protocol/entry.ts`）—— 因为 Router 只知道
+   *   怎么写 OpenAI 形态，而客户端说的可能是 Anthropic/Gemini。
+   * @param sink 可选的响应收集器：给了就把「写给 res 的东西」改成写给 sink，
+   *   由调用方翻译后自己写真正的 res。只给非 chat 协议用。
+   */
+  async chatCompletions(req: ChatRequest, res: ServerResponse, sink?: ResponseSink): Promise<void> {
+    const out = sink === undefined ? res : sinkRes(sink)
     // 每个客户端请求一条用量记录（组合回退会试多个供应商，但只落一次账）
     const probe: UsageProbe = {
       requested: req.model,
@@ -1122,7 +1228,7 @@ export class Router {
         // 只剩 0ms（否则组合越多越没法用），但同一条腿内的多个号共享一份
         // （停滞是上游级的，按号各等一份会 11×60s）。
         const served = await this.chatWithModel(
-          req, res, model, probe, trace, Date.now() + this.firstByteBudgetMs,
+          req, out, model, probe, trace, Date.now() + this.firstByteBudgetMs,
         )
         if (served) {
           settle(true)
@@ -1135,7 +1241,7 @@ export class Router {
         }
       }
       settle(false, 'combo: all models unavailable')
-      writeJson(res, 503, openAIError('no_healthy_supplier', `combo ${JSON.stringify(req.model)}: all models unavailable`))
+      writeJson(out, 503, openAIError('no_healthy_supplier', `combo ${JSON.stringify(req.model)}: all models unavailable`))
       return
     }
     // 直接调用：模型全名 = alias/model。用别名反查供应商，精准调用。
@@ -1146,22 +1252,22 @@ export class Router {
     const alias = slash > 0 ? req.model.slice(0, slash) : ''
     const target = alias === '' ? undefined : this.supplierByAlias(alias)
     if (target !== undefined) {
-      const served = await this.chatWithTarget(target, req, res, probe)
+      const served = await this.chatWithTarget(target, req, out, probe)
       if (served) {
         settle(true)
         return
       }
       settle(false, `supplier ${target.id}: all accounts unavailable`)
-      writeJson(res, 503, openAIError('no_healthy_supplier', `supplier ${JSON.stringify(target.id)}: all accounts unavailable`))
+      writeJson(out, 503, openAIError('no_healthy_supplier', `supplier ${JSON.stringify(target.id)}: all accounts unavailable`))
       return
     }
-    const served = await this.chatWithModel(req, res, req.model, probe)
+    const served = await this.chatWithModel(req, out, req.model, probe)
     if (served) {
       settle(true)
       return
     }
     settle(false, 'all suppliers unavailable')
-    writeJson(res, 503, openAIError('no_healthy_supplier', 'all suppliers unavailable'))
+    writeJson(out, 503, openAIError('no_healthy_supplier', 'all suppliers unavailable'))
   }
 
   /** 调指定供应商。
@@ -1274,9 +1380,13 @@ export class Router {
   ): Promise<boolean> {
     const pool = s.pool
     const cfg = this.store.get(s.id)
-    // 无账号供应商：直接调一次（uid 传空，插件忽略）
+    // 上游协议适配：供应商声明了非 chat 的 wire 时，在这里包一层翻译 ——
+    // 请求体翻成它的协议、它的响应流翻回 OpenAI SSE。契约不变（插件仍只
+    // 看见 OpenAI 形态），翻译只此一处，四个入口（组合腿/直调/测试/探测）
+    // 全部受益。wire = 'chat'（缺省，今天所有供应商）时零成本返回原函数。
+    const chatOnce = this.wireOf(s)
     if (s.accounts !== undefined && s.accounts().length === 0) {
-      const r = await s.chatOnce('', req.lv ?? 'auto', req)
+      const r = await chatOnce('', req.lv ?? 'auto', req)
       if (!r.ok) {
         // 模型不属于本供应商、或请求本身被上游拒收：换供应商，不记账
         if (r.state === 'no_such_model' || r.state === 'bad_request') return false
@@ -1342,7 +1452,7 @@ export class Router {
       }
       pickWhy = pool.lastWhy
       tried.add(uid)
-      const r = await s.chatOnce(uid, req.lv ?? 'auto', req)
+      const r = await chatOnce(uid, req.lv ?? 'auto', req)
       if (!r.ok) {
         // 模型不属于本供应商、或请求本身被上游拒收：整个供应商都跳过，
         // 换号重试没有意义，也不能记在账号头上（否则无关账号会被冷掉）。
@@ -1355,7 +1465,7 @@ export class Router {
           }
           return false
         }
-        pool.noteFailure(uid, req.model, r.state, r.message)
+        pool.noteFailure(uid, req.model, r.state, r.message, r.resetAt)
         // 故障切走：下次选号会换号，旧块的驻留计数不再适用（前缀归属变了）
         pool.dropBlock(req.model)
         if (trace !== undefined) {
@@ -1406,7 +1516,16 @@ export class Router {
   async testModel(supplierId: string, model: string, onlyUid?: string): Promise<{ ok: boolean; error?: string }> {
     const s = this.active.find((x) => x.id === supplierId)
     if (s === undefined) return { ok: false, error: `unknown supplier ${JSON.stringify(supplierId)}` }
-    const sink = sinkRes()
+    // 测试 sink：只收集状态与 body，不写给任何真实 res（testModel 的响应丢弃）
+    let sinkStatus = 200
+    let sinkBody = ''
+    const sink = sinkRes({
+      head: (code) => { sinkStatus = code },
+      write: (bytes) => { sinkBody += new TextDecoder().decode(bytes) },
+      end: () => {},
+    })
+    const statusOf = (): number => sinkStatus
+    const bodyOf = (): string => sinkBody
     const req: ChatRequest = {
       model,
       stream: false,
@@ -1420,8 +1539,8 @@ export class Router {
       return { ok: false, error: (err as Error).message }
     }
     // 供应商可能「服务了但写出错误响应」（如 opencode：唯一能处理该模型的供应商，错误自己上报）
-    if (served && sink.status() < 400) return { ok: true }
-    const fromSink = served && sink.status() >= 400 ? extractUpstreamError(sink.body()) : ''
+    if (served && statusOf() < 400) return { ok: true }
+    const fromSink = served && statusOf() >= 400 ? extractUpstreamError(bodyOf()) : ''
     // 失败原因优先从上游响应体取，其次用 chatOnce 返回的 message（trace.lastError）。
     // 以前这里问插件的 lastError()——那是「最后一次失败」的可变全局，既可能串到
     // 别的账号/别的请求，也有插件压根没实现（codebuddy 就漏了，于是永远拿不到兜底）。

package/src/router/types.ts

@@ -5,6 +5,7 @@
  */
 import type { AccountState, ChatOnceResult, SupplierAccountNow } from '../suppliers/contract.ts'
 import type { AccountPool } from './account-pool.ts'
+import type { ProtocolId } from '../protocol/types.ts'
 
 /** 面板展示的账号状态（脱敏）。 */
 export interface SupplierAccount {
@@ -61,11 +62,24 @@ export interface ChatRequest {
   /** 推理等级（reasoning effort），供应商各自决定怎么映射到上游。缺省 = 'auto'。 */
   lv?: string
   /**
-   * 宿主盖的会话身份（dsh-llm `GenerateOptions.sessionId`），由 adapter 转成
-   * 内部头带进来。用于把用量记录**按会话归因**（「最近命中」徽章要按当前会话
-   * 显示，而不是显示别的会话的命中）。缺省 = 非宿主调用（外部 OpenAI 客户端）。
+   * 调用方身份（归因键）。来源两种：
+   *   1. 宿主会话身份（dsh-llm `GenerateOptions.sessionId`，adapter 转成内部头
+   *      `x-dsh-router-session`）——形式 `session-<uuid>`；
+   *   2. 外部 OpenAI 兼容客户端的 `user` 字段（Zed/IDE 等多客户端场景）——形式
+   *      `ext:<user>`，前缀标明「这不是宿主会话」。
+   * 用途：把用量记录**按调用方归因**（「最近命中」徽章按当前会话显示；出事时
+   * 能反查是哪个客户端在打）。缺省 = 匿名外部客户端。
    */
   session?: string
+  /**
+   * 客户端说的协议（入站）。
+   *
+   * 缺省 `'chat'`（今天所有入口的现状）。四种协议（chat / anthropic /
+   * responses / gemini）在入站路由上就被翻成规范形态，所以**核心与供应商
+   * 只认 chat**；这个字段存在的理由是让用量记录与日志能说出「客户端原本
+   * 说的哪种协议」，排查「Claude Code 打过来为什么不通」时省一次猜。
+   */
+  protocol?: ProtocolId
 }
 
 /**
@@ -93,6 +107,15 @@ export interface Supplier {
   accounts(): SupplierAccountNow[]
   /** 对单个账号调一次上游。不遍历账号、不管冷却、不写 res。 */
   chatOnce(uid: string, lv: string, req: ChatRequest): Promise<ChatOnceResult>
+  /**
+   * 上游说哪种协议（缺省 `'chat'`）。
+   *
+   * 声明成别种时，核心在 `chatOnce` 前后各做一次翻译：请求体翻成该协议、
+   * 响应流翻回 OpenAI SSE。于是**插件实现里永远只看见 OpenAI 形态**，
+   * 契约不变 —— 一个只会说 Anthropic 的上游可以接一个只写了几行 fetch 的
+   * 插件，路由/选号/冷却/用量全都照旧。
+   */
+  readonly wire?: ProtocolId
   /** 删除链接（清理凭证；内部能力，js 契约不要求实现）。 */
   removeLink?(uid: string): Promise<boolean>
   dispose(): void

package/src/router/usage-store.ts

@@ -55,8 +55,10 @@ export interface UsageRecord {
   /** 失败原因（ok=false 时）。 */
   error?: string
   /**
-   * 宿主会话身份（有则记）。用于「最近命中」按当前会话归因 —— 徽章要显示
-   * 当前会话的命中，而不是全局最近（team 多会话下后者会张冠李戴）。
+   * 调用方身份（有则记）：宿主会话 id（`session-<uuid>`）或外部 OpenAI 客户端
+   * 标签（`ext/…`，见 shared.ts 的 clientIdentityOf）。用于「最近命中」按当前
+   * 会话归因（徽章要显示当前会话的命中，而不是全局最近），出事时也能反查
+   * 是哪个客户端在打。
    */
   session?: string
 }