dsh-router-core 0.1.0 → 0.3.0

package/src/index.ts

@@ -18,6 +18,9 @@
  *   PATCH /router/api/keys/:id                toggle key {isActive}
  *   GET  /router/api/settings                 { requireApiKey }
  *   PATCH /router/api/settings                { requireApiKey }
+ *   GET  /router/api/stats                    usage overview (period=today|24h|7d|30d)
+ *   GET  /router/api/stats/chart              usage bar chart buckets
+ *   POST /router/api/stats/clear              reset all usage stats
  *   POST /router/api/suppliers/:id/login                  generate login URL
  *   POST /router/api/suppliers/:id/login/callback         {callbackUrl} → add account
  *   GET  /router/api/suppliers/:id/models                 models with enabled state
@@ -28,7 +31,7 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { join, dirname } from 'node:path'
-import { ROUTER_API_BASE } from './shared.ts'
+import { ROUTER_API_BASE, type RouterPeriod } from './shared.ts'
 import { Router } from './router/index.ts'
 import { RouterAdapter } from './llm/adapter.ts'
 import { KeysStore } from './keys.ts'
@@ -128,7 +131,7 @@ export function apply(rawContext: unknown): void {
   const stateFile = process.env.TW2A_STATE_FILE ?? 'data/state.json'
   const store = new SupplierConfigStore(stateFile)
   const credentials = new CredentialStore(process.env.TW2A_AUTH_DIR ?? join(dirname(stateFile), 'auths'))
-  const router = new Router(stateFile)
+  const router = new Router(stateFile, store, log)
 
   const keys = new KeysStore(stateFile)
 
@@ -146,7 +149,7 @@ export function apply(rawContext: unknown): void {
   const supplierDisposers = new Map<string, Array<() => void>>()
   const registerSupplierRoutes = (loaded: LoadedSupplier): void => {
     const dis: Array<() => void> = []
-    for (const r of supplierRoutes(ROUTER_API_BASE, loaded, store)) {
+    for (const r of supplierRoutes(ROUTER_API_BASE, loaded, store, router)) {
       dis.push(ctx.webServer.register(r))
     }
     supplierDisposers.set(loaded.supplier.id, dis)
@@ -405,6 +408,51 @@ export function apply(rawContext: unknown): void {
     writeJson(res, 200, { ok: true, requireApiKey: keys.requireApiKey })
   })
 
+  // ---- 概览看板：用量统计 ----
+
+  /** 解析并校验周期参数（不接受任意字符串）。 */
+  const periodOf = (raw: string | null): RouterPeriod => {
+    return raw === '24h' || raw === '7d' || raw === '30d' ? raw : 'today'
+  }
+
+  route(`${ROUTER_API_BASE}/stats`, (req, res) => {
+    const period = periodOf(new URL(req.url ?? '/', 'http://localhost').searchParams.get('period'))
+    const s = router.usage.stats(period)
+    writeJson(res, 200, {
+      ok: true,
+      period,
+      requests: s.requests,
+      okCount: s.ok,
+      failed: s.failed,
+      promptTokens: s.promptTokens,
+      completionTokens: s.completionTokens,
+      cachedTokens: s.cachedTokens,
+      avgDurationMs: s.avgDurationMs,
+      avgTtfbMs: s.avgTtfbMs,
+      estimatedInputs: s.estimatedInputs,
+      estimatedOutputs: s.estimatedOutputs,
+      lifetime: s.lifetime,
+      bySupplier: s.bySupplier,
+      byModel: s.byModel,
+      byRequested: s.byRequested,
+      recent: router.usage.recentList(20),
+    })
+  })
+
+  route(`${ROUTER_API_BASE}/stats/chart`, (req, res) => {
+    const period = periodOf(new URL(req.url ?? '/', 'http://localhost').searchParams.get('period'))
+    writeJson(res, 200, { ok: true, chart: router.usage.chart(period) })
+  })
+
+  route(`${ROUTER_API_BASE}/stats/clear`, async (req, res) => {
+    if (req.method !== 'POST') {
+      writeJson(res, 405, { ok: false, error: 'method not allowed' })
+      return
+    }
+    router.usage.clear()
+    writeJson(res, 200, { ok: true })
+  })
+
   // ---- 设置-模型：Router 提供方（固定卡片，插件注册，不可删）+ 模型目录（= 组合） ----
 
   // llm 缺失时（如测试环境）跳过，不影响 /v1 核心。
@@ -461,7 +509,7 @@ export function apply(rawContext: unknown): void {
   ctx.effect(
     () => () => {
       for (const dispose of disposers.splice(0)) dispose()
-      router.dispose()
+      router.dispose() // 内部会 flush 用量统计（防抖中的计数不能丢）
     },
     'dsh-router: teardown',
   )

package/src/llm/adapter.test.ts

@@ -0,0 +1,108 @@
+/**
+ * RouterAdapter 的 usage 契约测试。
+ *
+ * 这些用例存在的原因：adapter 曾把上游 OpenAI 形态的 usage 原样透传给
+ * dsh-llm，导致会话日志里的 usage 全是 `prompt_tokens`（没有 `inputTokens`）。
+ * 下游 token-meter 读 `usage.inputTokens` 得 `undefined`，累加出 `NaN`，
+ * 投影 schema（`z.number().int().nonnegative()`）校验一抛，整条
+ * `session.history` RPC 失败 —— 用户看到的就是「历史加载失败」。
+ *
+ * 所以这里锁死两条：字段名对、口径对（DISJOINT）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { toTokenUsage } from '../router/usage-tokens.ts'
+import { translateSse } from './adapter.ts'
+
+/** 跑一遍 SSE 载荷序列，返回产出的 usage chunk（没有则 undefined）。 */
+async function usageOf(...payloads: string[]): Promise<Record<string, unknown> | undefined> {
+  for await (const chunk of translateSse(payloads)) {
+    if (chunk.type === 'usage') return chunk.usage as unknown as Record<string, unknown>
+  }
+  return undefined
+}
+
+/** 一帧 SSE 的 data 载荷（translateSse 吃的是已剥掉 `data:` 前缀的载荷）。 */
+const frame = (obj: unknown): string => JSON.stringify(obj)
+
+/* ---------------- 契约转换 ---------------- */
+
+test('转换：OpenAI 形态的 prompt_tokens → inputTokens，且扣掉缓存（DISJOINT）', () => {
+  // prompt_tokens 是含缓存的总量；DISJOINT 要求 inputTokens 只算未缓存部分
+  const u = toTokenUsage({ promptTokens: 1000, completionTokens: 50, cachedTokens: 300 })
+  assert.deepEqual(u, { inputTokens: 700, outputTokens: 50, cacheReadTokens: 300 })
+})
+
+test('转换：无缓存时不带 cacheReadTokens 字段（不写无意义的 0）', () => {
+  const u = toTokenUsage({ promptTokens: 100, completionTokens: 20, cachedTokens: 0 })
+  assert.deepEqual(u, { inputTokens: 100, outputTokens: 20 })
+})
+
+test('转换：全 0 返回 null（这一帧没真数据，整个省略 usage）', () => {
+  assert.equal(toTokenUsage({ promptTokens: 0, completionTokens: 0, cachedTokens: 0 }), null)
+  assert.equal(toTokenUsage(null), null)
+})
+
+test('转换：NaN / Infinity / 负数一律归零 —— 绝不把 NaN 写进会话日志', () => {
+  const u = toTokenUsage({
+    promptTokens: Number.NaN,
+    completionTokens: Number.POSITIVE_INFINITY,
+    cachedTokens: -5,
+  })
+  assert.equal(u, null) // 全归零 → 视为无数据
+  const partial = toTokenUsage({ promptTokens: Number.NaN, completionTokens: 42, cachedTokens: 0 })
+  assert.deepEqual(partial, { inputTokens: 0, outputTokens: 42 })
+  for (const v of Object.values(partial ?? {})) assert.ok(Number.isFinite(v), `出现非有限数: ${v}`)
+})
+
+test('转换：缓存比总输入还大时 inputTokens 不为负（上游口径打架也要自洽）', () => {
+  const u = toTokenUsage({ promptTokens: 100, completionTokens: 1, cachedTokens: 500 })
+  assert.equal(u?.inputTokens, 0)
+})
+
+/* ---------------- adapter 出口 ---------------- */
+
+test('出口：流式 SSE 的 usage 必须是 DSH 契约，不是上游原样', async () => {
+  const usage = await usageOf(
+    frame({ choices: [{ delta: { content: 'hi' } }] }),
+    frame({
+      choices: [{ delta: {}, finish_reason: 'stop' }],
+      usage: { prompt_tokens: 236655, completion_tokens: 548, prompt_tokens_details: { cached_tokens: 1024 } },
+    }),
+    '[DONE]',
+  )
+  assert.ok(usage !== undefined, '应当产出 usage chunk')
+  // 字段名对
+  assert.equal(usage.prompt_tokens, undefined, '不能把上游字段原样透传')
+  assert.equal(usage.inputTokens, 235631) // 236655 - 1024
+  assert.equal(usage.outputTokens, 548)
+  assert.equal(usage.cacheReadTokens, 1024)
+  // 每个字段都是有限非负整数（投影 schema 的硬要求）
+  for (const [k, v] of Object.entries(usage)) {
+    assert.ok(Number.isInteger(v) && (v as number) >= 0, `${k} 非法: ${v}`)
+  }
+})
+
+test('出口：上游把 usage 拆在多帧时字段级合并（不是被后一帧覆盖）', async () => {
+  // Claude 系：message_start 给输入，message_delta 只给输出
+  const usage = await usageOf(
+    frame({ choices: [{ delta: { content: 'x' } }], usage: { input_tokens: 100, cache_read_input_tokens: 40 } }),
+    frame({ choices: [{ delta: {}, finish_reason: 'stop' }], usage: { output_tokens: 55 } }),
+    '[DONE]',
+  )
+  assert.equal(usage?.inputTokens, 100, '后一帧没有输入，不能把前一帧的输入冲掉')
+  assert.equal(usage?.outputTokens, 55)
+  assert.equal(usage?.cacheReadTokens, 40)
+})
+
+test('出口：上游发全 0 或垃圾 usage 时省略整个 usage chunk', async () => {
+  const zero = frame({ choices: [{ delta: { content: 'x' } }], usage: { prompt_tokens: 0, completion_tokens: 0 } })
+  assert.equal(await usageOf(zero, '[DONE]'), undefined)
+  const junk = frame({ choices: [{ delta: { content: 'x' } }], usage: { prompt_tokens: 'abc', completion_tokens: null } })
+  assert.equal(await usageOf(junk, '[DONE]'), undefined)
+})
+
+test('出口：上游压根不发 usage 时不硬凑 usage chunk', async () => {
+  const sse = frame({ choices: [{ delta: { content: 'x' }, finish_reason: 'stop' }] })
+  assert.equal(await usageOf(sse, '[DONE]'), undefined)
+})

package/src/llm/adapter.ts

@@ -15,6 +15,7 @@ import {
   type LlmModelInfo,
   type StreamChunk,
 } from '@deepseek-ai/dsh-llm'
+import { mergeUsage, normalizeUsage, toTokenUsage, type UsageTokens } from '../router/usage-tokens.ts'
 
 /** 模型目录来源：组合。 */
 export interface RouterAdapterSource {
@@ -107,15 +108,16 @@ interface OpenBlock {
   name?: string
 }
 
-/** openai SSE payload → DSH StreamChunk 流。 */
-async function* translate(payloads: Iterable<string>): AsyncGenerator<StreamChunk> {
+/** openai SSE payload → DSH StreamChunk 流。导出以便单测锁死 usage 契约。 */
+export async function* translateSse(payloads: Iterable<string>): AsyncGenerator<StreamChunk> {
   let nextIndex = 0
   let textBlock: OpenBlock | undefined
   let reasoningBlock: OpenBlock | undefined
   const toolBlocks = new Map<number, OpenBlock>()
   const order: OpenBlock[] = []
   let pendingFinish: { kind: string; failure?: unknown } | undefined
-  let pendingUsage: unknown
+  /** 攒上游各帧的 usage（归一形态），[DONE] 时统一转成 DSH 契约。 */
+  let accumulated: UsageTokens | null = null
 
   const open = (kind: OpenBlock['kind']): OpenBlock => {
     const block: OpenBlock = { index: nextIndex++, kind, text: '' }
@@ -128,7 +130,15 @@ async function* translate(payloads: Iterable<string>): AsyncGenerator<StreamChun
       for (const block of order) {
         yield { type: 'block-end', index: block.index, block: closeBlock(block) }
       }
-      if (pendingUsage !== undefined) yield { type: 'usage', usage: pendingUsage as never }
+      if (accumulated !== null) {
+        // 转成 DSH 的 TokenUsage：**必须**转，不能把上游的 OpenAI 形态
+        // （prompt_tokens，且含缓存）原样透传。字段名和 DISJOINT 口径都
+        // 对不上，下游 token-meter 读到 undefined 会累加出 NaN，投影
+        // schema 校验一抛就是整条 session.history 失败（「历史加载失败」）。
+        // 转换结果为 null（三个数全 0）则整个省略 usage。见 toTokenUsage。
+        const usage = toTokenUsage(accumulated)
+        if (usage !== null) yield { type: 'usage', usage }
+      }
       const reason = pendingFinish ?? { kind: 'stop' }
       yield {
         type: 'finish',
@@ -188,7 +198,9 @@ async function* translate(payloads: Iterable<string>): AsyncGenerator<StreamChun
       }
       if (typeof choice.finish_reason === 'string') pendingFinish = mapFinishReason(choice.finish_reason)
     }
-    if (chunk.usage !== undefined) pendingUsage = chunk.usage
+    // 上游可能把 usage 拆在多个帧里（Claude 系：先给输入、后给输出），
+    // 所以是字段级 max 合并，不是覆盖。攒着，[DONE] 时统一转契约。
+    if (chunk.usage !== undefined) accumulated = mergeUsage(accumulated, normalizeUsage(chunk.usage))
   }
   throw new LlmError('SSE payload stream ended without [DONE]', 'STREAM_CLOSED')
 }
@@ -268,6 +280,6 @@ export class RouterAdapter extends LlmAdapter {
       throw new LlmError(`dsh-router /v1 returned ${resp.status}: ${detail.slice(0, 200)}`, 'TRANSPORT')
     }
     const text = resp.body === null ? '' : await resp.text()
-    yield* translate(parseSseText(text))
+    yield* translateSse(parseSseText(text))
   }
 }

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

@@ -0,0 +1,120 @@
+/**
+ * 账号池（核心策略）测试 —— 选号/冷却/禁用/错误累计/遍历回退。
+ * 用 node --test 跑（Node 原生 TS 剥离，零新依赖）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { AccountPool } from './account-pool.ts'
+import type { SupplierAccountNow } from '../suppliers/contract.ts'
+
+const accs = (uids: string[]): SupplierAccountNow[] => uids.map((uid) => ({ uid, credits: 0, state: 'ok' }))
+
+test('选号：无冷却时按 poolOrder 优先，未配置的追加在后', () => {
+  const p = new AccountPool()
+  const list = accs(['a', 'b', 'c'])
+  assert.equal(p.pick(list, ['c', 'a'], 'fallback'), 'c')
+  assert.equal(p.pick(list, ['b'], 'fallback'), 'b')
+  // 未配置顺序的按自然顺序补上
+  assert.equal(p.pick(list, [], 'fallback'), 'a')
+})
+
+test('选号：冷却中的号跳过，全冷却返回 undefined', () => {
+  const p = new AccountPool()
+  const list = accs(['a', 'b'])
+  p.noteFailure('a', 'rate_limit', '429')
+  assert.equal(p.pick(list, [], 'fallback'), 'b')
+  p.noteFailure('b', 'rate_limit', '429')
+  assert.equal(p.pick(list, [], 'fallback'), undefined)
+})
+
+test('选号：round-robin 在健康号间轮转', () => {
+  const p = new AccountPool()
+  const list = accs(['a', 'b'])
+  assert.equal(p.pick(list, [], 'round-robin'), 'a')
+  assert.equal(p.pick(list, [], 'round-robin'), 'b')
+  assert.equal(p.pick(list, [], 'round-robin'), 'a')
+})
+
+test('处置：session_dead 永久禁用（不再被选中）', () => {
+  const p = new AccountPool()
+  const list = accs(['a'])
+  p.noteFailure('a', 'session_dead', '凭证失效')
+  assert.equal(p.pick(list, [], 'fallback'), undefined)
+  assert.equal(p.decorate(list)[0]?.disabled, true)
+})
+
+test('处置：连续错误攒够阈值才冷却（前两次仍可服务）', () => {
+  const p = new AccountPool()
+  const list = accs(['a'])
+  p.noteFailure('a', 'unknown', 'e1')
+  assert.equal(p.pick(list, [], 'fallback'), 'a')
+  p.noteFailure('a', 'unknown', 'e2')
+  assert.equal(p.pick(list, [], 'fallback'), 'a')
+  // 第三次触发冷却
+  p.noteFailure('a', 'unknown', 'e3')
+  assert.equal(p.pick(list, [], 'fallback'), undefined)
+})
+
+test('处置：成功清零连续错误，避免之前累积的错误把好号冷却掉', () => {
+  const p = new AccountPool()
+  const list = accs(['a'])
+  p.noteFailure('a', 'unknown', 'e1')
+  p.noteFailure('a', 'unknown', 'e2')
+  p.noteSuccess('a')
+  p.noteFailure('a', 'unknown', 'e3')
+  assert.equal(p.pick(list, [], 'fallback'), 'a')
+})
+
+test('decorate：把冷却/禁用/错误累计叠加到插件报的「现在状态」上', () => {
+  const p = new AccountPool()
+  const list: SupplierAccountNow[] = [
+    { uid: 'ok', credits: 5, state: 'ok' },
+    { uid: 'cool', credits: 5, state: 'ok' },
+    { uid: 'dead', credits: 5, state: 'ok' },
+  ]
+  p.noteFailure('cool', 'rate_limit', '429')
+  p.noteFailure('dead', 'session_dead', '凭证失效')
+  const out = p.decorate(list)
+  const by = new Map(out.map((a) => [a.uid, a]))
+  assert.equal(by.get('ok')?.cooling, false)
+  assert.equal(by.get('ok')?.disabled, false)
+  assert.equal(by.get('cool')?.cooling, true)
+  assert.equal(by.get('cool')?.until !== undefined, true)
+  assert.equal(by.get('cool')?.reason, '429')
+  assert.equal(by.get('dead')?.disabled, true)
+  // 插件报的字段要原样透出（不能被 decorate 吃掉）
+  assert.equal(by.get('ok')?.credits, 5)
+})
+
+test('no_such_model 不惩罚账号：不冷却、不计数', () => {
+  const p = new AccountPool()
+  const list = accs(['a'])
+  // 攒够阈值次也不该冷却——模型不属于本供应商不是账号的错
+  for (let i = 0; i < 10; i++) p.noteFailure('a', 'no_such_model', 'unknown model "x"')
+  assert.equal(p.pick(list, [], 'fallback'), 'a')
+  const out = p.decorate(list)[0]
+  assert.equal(out?.cooling, false)
+  assert.equal(out?.disabled, false)
+  assert.equal(out?.err_count, 0)
+})
+
+test('状态表：各 AccountState 的处置符合预期', () => {
+  const p = new AccountPool()
+  const list = accs(['rate', 'quota', 'dead', 'unavail'])
+  p.noteFailure('rate', 'rate_limit', 'x')
+  p.noteFailure('quota', 'quota', 'x')
+  p.noteFailure('dead', 'session_dead', 'x')
+  p.noteFailure('unavail', 'unavailable', 'x')
+  // rate_limit/quota 立刻冷却；session_dead 禁用；unavailable 只计错误不冷却
+  assert.equal(p.pick(list, [], 'fallback'), 'unavail')
+  const by = new Map(p.decorate(list).map((a) => [a.uid, a]))
+  assert.equal(by.get('rate')?.cooling, true)
+  assert.equal(by.get('quota')?.cooling, true)
+  assert.equal(by.get('dead')?.disabled, true)
+  assert.equal(by.get('unavail')?.cooling, false)
+  assert.equal(by.get('unavail')?.err_count, 1)
+  // 攒够阈值后才冷却（与 unknown/transport 同一条路径）
+  p.noteFailure('unavail', 'unavailable', 'x')
+  p.noteFailure('unavail', 'unavailable', 'x')
+  assert.equal(p.pick(list, [], 'fallback'), undefined)
+})

package/src/router/account-pool.ts

@@ -0,0 +1,161 @@
+/**
+ * 账号池 —— dsh-router 核心策略：选号、冷却、禁用、错误累计、遍历回退。
+ *
+ * 供应商插件只管「对单个账号调通上游」，账号层面的策略全在这里：
+ *   - 按 poolOrder 排序（未配置的按插件报告顺序追加）
+ *   - 按 poolStrategy 选号：fallback = 取第一个健康；round-robin = 轮转健康号
+ *   - 失败按插件报的 AccountState 处置（冷却/禁用/错误累计），攒够阈值自动冷却
+ *
+ * 天花板：冷却/禁用/错误计数都是**内存态**，重启归零（与旧插件行为一致，
+ * 插件的持久化只存凭证与积分，不存健康）。要跨重启保留得落盘，届时加一个
+ * stateFile 即可，接口不用变。
+ */
+import type { AccountState, SupplierAccountNow } from '../suppliers/contract.ts'
+
+/** 各 AccountState 的处置：冷却时长 / 是否禁用 / 是否计入连续错误。 */
+interface Rule {
+  /** 冷却时长（ms）；0 = 不冷却。 */
+  cooldownMs: number
+  /** 是否永久禁用（需重新登录才能恢复）。 */
+  disable: boolean
+  /** 是否计入连续错误（攒够阈值自动冷却）。 */
+  counts: boolean
+}
+
+const MINUTE = 60_000
+
+/**
+ * 状态 → 处置表。**核心策略就在这一张表里**，插件只报状态不做决策。
+ * 时长参考 9router 的 errorConfig（限流类短冷却、额度类长冷却），
+ * 但 9router 按文本/状态匹配，这里按插件解读后的语义状态匹配，更准。
+ */
+const RULES: Record<AccountState, Rule> = {
+  ok: { cooldownMs: 0, disable: false, counts: false },
+  rate_limit: { cooldownMs: 1 * MINUTE, disable: false, counts: false },
+  quota: { cooldownMs: 10 * MINUTE, disable: false, counts: false },
+  session_dead: { cooldownMs: 0, disable: true, counts: false },
+  // 404/服务下线：只计错误不立刻冷却——偶发的自己恢复，真挂了攒够阈值再冷却
+  unavailable: { cooldownMs: 0, disable: false, counts: true },
+  transport: { cooldownMs: 0, disable: false, counts: true },
+  unknown: { cooldownMs: 0, disable: false, counts: true },
+  // 模型不属于本供应商：不是账号的错，不冷却也不计数（核心据此换下一个供应商）
+  no_such_model: { cooldownMs: 0, disable: false, counts: false },
+}
+
+/** 连续错误攒够这么多次就自动冷却（防止坏号被反复重试）。 */
+const ERR_THRESHOLD = 3
+/** 攒够后的冷却时长。 */
+const ERR_COOLDOWN_MS = 10 * MINUTE
+
+interface Entry {
+  until: number
+  disabled: boolean
+  errCount: number
+  reason: string
+}
+
+export class AccountPool {
+  private entries = new Map<string, Entry>()
+  private rrCursor = 0
+
+  private entry(uid: string): Entry {
+    let e = this.entries.get(uid)
+    if (!e) {
+      e = { until: 0, disabled: false, errCount: 0, reason: '' }
+      this.entries.set(uid, e)
+    }
+    return e
+  }
+
+  /** 是否可服务：未禁用且不在冷却中。 */
+  private healthy(uid: string, now: number): boolean {
+    const e = this.entries.get(uid)
+    if (!e) return true
+    if (e.disabled) return false
+    return e.until <= now
+  }
+
+  /**
+   * 按策略选一个健康账号。
+   * @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
+   * @param poolOrder 用户在面板拖出来的顺序（核心管）
+   * @returns 选中的 uid；无健康账号返回 undefined
+   */
+  pick(accounts: SupplierAccountNow[], poolOrder: string[], strategy: string): string | undefined {
+    const now = Date.now()
+    const byUid = new Map(accounts.map((a) => [a.uid, a]))
+    // 池顺序优先，未配置的按插件自然顺序追加
+    const ordered = [
+      ...poolOrder.filter((uid) => byUid.has(uid)),
+      ...accounts.map((a) => a.uid).filter((uid) => !poolOrder.includes(uid)),
+    ]
+    const healthy = ordered.filter((uid) => this.healthy(uid, now))
+    if (healthy.length === 0) return undefined
+    if (strategy !== 'round-robin') return healthy[0]
+    const uid = healthy[this.rrCursor % healthy.length]
+    this.rrCursor = (this.rrCursor + 1) % healthy.length
+    return uid
+  }
+
+  /** 记录一次失败：按状态处置（冷却/禁用/错误累计）。 */
+  noteFailure(uid: string, state: AccountState, message: string): void {
+    const rule = RULES[state]
+    const e = this.entry(uid)
+    if (rule.disable) {
+      e.disabled = true
+      e.reason = message
+      return
+    }
+    if (rule.cooldownMs > 0) {
+      e.until = Math.max(e.until, Date.now() + rule.cooldownMs)
+      e.reason = message
+      e.errCount = 0
+      return
+    }
+    if (rule.counts) {
+      e.errCount += 1
+      e.reason = message
+      if (e.errCount >= ERR_THRESHOLD) {
+        e.until = Date.now() + ERR_COOLDOWN_MS
+        e.errCount = 0
+      }
+    }
+  }
+
+  /** 记录一次成功：清零连续错误。 */
+  noteSuccess(uid: string): void {
+    const e = this.entries.get(uid)
+    if (e) e.errCount = 0
+  }
+
+  /** 手动冷却（面板/管理用途）。 */
+  cooldown(uid: string, ms: number, reason: string): void {
+    const e = this.entry(uid)
+    e.until = Date.now() + ms
+    e.reason = reason
+    e.errCount = 0
+  }
+
+  /** 把核心的冷却/禁用/错误累计叠加到插件报告的「现在状态」上，产出面板态。 */
+  decorate(accounts: SupplierAccountNow[]): Array<SupplierAccountNow & {
+    cooling: boolean
+    disabled: boolean
+    err_count: number
+    until?: string
+    reason?: string
+  }> {
+    const now = Date.now()
+    return accounts.map((a) => {
+      const e = this.entries.get(a.uid)
+      const cooling = e !== undefined && !e.disabled && e.until > now
+      return {
+        ...a,
+        cooling,
+        disabled: e?.disabled ?? false,
+        err_count: e?.errCount ?? 0,
+        until: cooling && e ? new Date(e.until).toISOString() : undefined,
+        reason: e?.reason !== '' ? e?.reason : undefined,
+      }
+    })
+  }
+}