dsh-router-core 0.3.3 → 0.3.4

package/lib/types/suppliers/contract.d.ts

@@ -46,6 +46,12 @@ export type AccountState = 'ok' | 'rate_limit' | 'quota' | 'session_dead' | 'una
 export interface SupplierAccountNow {
     uid: string;
     nickname?: string;
+    /**
+     * 剩余额度。**拿不到就报 `-1`**，不是 0：
+     * 插件刚重启（内存缓存空）、积分拉取失败、或压根不支持积分时都是 `-1`。
+     * 核心据此保留上一次持久化下来的值 —— 报 0 会把缓存冲成 0（0 是真值
+     * 「用完了」，核心分不清「拿到 0」和「没拿到」）。
+     */
     credits: number;
     /** 插件观察到的上游状态。 */
     state: AccountState;
@@ -91,19 +97,16 @@ export interface SupplierModule {
     status(): SupplierStatusNow;
     /** 模型来源。`force=true` 时强制刷新来源（核心「获取模型」按钮调用）。 */
     listModels(force?: boolean): Promise<ModelInfo[]> | ModelInfo[];
-    /** 默认前缀（可被通用层 alias 覆盖）。 */
-    getAlias(): string;
     /**
      * 对**单个账号**调一次上游。插件不遍历账号、不管冷却、不写 res——
      * 选号/回退/健康判定全是核心的活。
      * 无账号供应商（如 opencode）传空 uid，忽略即可。
+     *
+     * 失败原因通过返回值的 `message` 报（核心在测试模型时直接用它做诊断提示），
+     * 插件不必自己存一份「上次失败」的状态。
      */
     chatOnce(uid: string, req: ChatRequest): Promise<ChatOnceResult>;
     dispose(): void;
-    /** 上次 chatOnce 失败的原因（诊断用）。
-     *  测试模型由 dsh-router 核心统一走 chatOnce 路径（账号池回退/冷却自动生效），
-     *  插件只需把失败原因暴露出来供核心汇总；不实现则测试失败时只有通用提示。 */
-    lastError?(): string | undefined;
     /** 生成登录链接（加账号）。有它才显示连接池（账号池）。 */
     generateLoginUrl?(): string | {
         ok: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-router-core",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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/SupplierDetail.tsx

@@ -673,11 +673,16 @@ export function SupplierDetail({ supplier, accounts, statusLoading, onBack, onRe
                         <div className="dshr-linkSub">
                           <span className="dshr-mono dshr-linkUid">{account.uid}</span>
                           <span className="dshr-linkDot">·</span>
-                          <span className="dshr-mono dshr-linkCredits">{Math.ceil(account.credits)} 积分</span>
+                          {/* credits < 0 = 插件还没拉到过积分（缓存也没值），
+                              别显示成「-1 积分」或直接吃掉整段 */}
+                          <span className="dshr-mono dshr-linkCredits">
+                            {account.credits < 0 ? '积分未知' : `${Math.ceil(account.credits)} 积分`}
+                          </span>
+                          {/* err_count 是限流退避等级（反复被限流的号递增，成功后清零） */}
                           {account.err_count !== undefined && account.err_count > 0 && (
                             <>
                               <span className="dshr-linkDot">·</span>
-                              <span className="dshr-linkErr">连续错误 {account.err_count}</span>
+                              <span className="dshr-linkErr">退避 {account.err_count} 级</span>
                             </>
                           )}
                           {coolingText !== '' && <span className="dshr-reason dshr-linkCooling">{coolingText}</span>}

package/src/router/index.ts

@@ -26,8 +26,15 @@ interface ChatTrace {
   lastState?: AccountState
 }
 
-/** 模型列表缓存有效期。 */
-const MODELS_TTL_MS = 60 * 1000
+/**
+ * 模型列表缓存有效期。
+ *
+ * 取 10 分钟而不是 60s：模型列表本来很少变（上游上新/下线才动），而每次
+ * TTL 过期都会穿透到插件真打一次上游——实测冷路径 0.3~1.0s/供应商，组合页
+ * 取最慢那家就是 1s+ 的白屏。拉长 TTL 直接把这个穿透频率降一个量级；真要
+ * 立刻看新模型，点「获取模型」走 force 即可。
+ */
+const MODELS_TTL_MS = 10 * 60 * 1000
 
 function openAIError(code: string, msg: string): Record<string, unknown> {
   return { error: { message: msg, type: 'api_error', code } }
@@ -444,6 +451,11 @@ export class Router {
   private store: SupplierConfigStore
   /** 模型列表缓存（supplierId → 模型 + 拉取时间）。插件只管拉，不缓存。 */
   private modelsCache = new Map<string, { models: ModelWithEnabled[]; fetchedAt: number }>()
+  /**
+   * 正在拉模型的供应商 → in-flight promise。
+   * 组合页会同时从多个入口触发同一个供应商的刷新，不去重上游就被按 N 倍打。
+   */
+  private modelsInflight = new Map<string, Promise<ModelWithEnabled[]>>()
   /** 请求日志出口（面板/宿主 logger）。 */
   private log: (msg: string) => void
   /** 用量统计（概览看板）。 */
@@ -592,37 +604,80 @@ export class Router {
    * 取某供应商的模型（核心统一缓存）。
    *
    * 模型列表只在这里缓存一次：`/suppliers/:id/models`（供应商详情）和
-   * `/combos`（组合加模型）共用。组合面板**不主动打上游**——它只是读缓存，
-   * 冷启动（缓存还没建）时才拉一次；真正刷新由详情页打开或「获取模型」
-   * 按钮（force）触发。
+   * `/combos`（组合加模型）共用。
    *
-   * 天花板：TTL 60s 是拍的。若上游模型列表变更很频繁，可调小；要彻底实时
-   * 就得让供应商暴露 etag/版本号，目前没有这个需求。
+   * **过期后走 stale-while-revalidate**:先返回旧值让面板立刻有内容,后台
+   * 重新拉,拉完下次请求就是新的。为什么必须这样:插件的 `listModels` 大多
+   * 无条件打上游(实测冷路径 0.3~1.0s/供应商),而组合页要拉全部供应商、
+   * 取最慢那家——同步等就是 1s+ 的白屏。旧值只可能「少列了新模型」,
+   * 比白屏划算;想立刻看新模型点「获取模型」(force)即可。
+   *
+   * 只有两种情况会真的等:`force`(用户主动刷新)和**从来没有过缓存值**
+   * (冷启动,没有旧值可给)。后者只发生一次。
    */
   async modelsOf(supplierId: string, force = false): Promise<ModelWithEnabled[]> {
     const s = this.suppliers.find((x) => x.id === supplierId)
     if (s === undefined) return []
     const hit = this.modelsCache.get(supplierId)
-    if (!force && hit !== undefined && Date.now() - hit.fetchedAt < MODELS_TTL_MS) return hit.models
-    const cfg = this.store.get(supplierId)
-    const custom = new Set(cfg.custom)
-    const disabled = new Set(cfg.disabled)
-    const list = await Promise.resolve(s.listModels())
-    const models: ModelWithEnabled[] = list.map((mm) => ({
-      ...mm,
-      enabled: !disabled.has(mm.id),
-      custom: custom.has(mm.id) ? true : undefined,
-    }))
-    // 自定义模型（listModels 之外的）并入显示
-    const seen = new Set(models.map((mm) => mm.id))
-    for (const id of custom) {
-      if (!seen.has(id)) {
-        seen.add(id)
-        models.push({ id, enabled: !disabled.has(id), custom: true })
-      }
+    const fresh = hit !== undefined && Date.now() - hit.fetchedAt < MODELS_TTL_MS
+    if (!force && fresh) return hit!.models
+    // 有旧值(只是过期了):立刻返回旧值,后台刷新
+    if (!force && hit !== undefined) {
+      // 后台刷新的失败不能冒出来:这是 fire-and-forget,没人接
+      void this.refreshModels(supplierId, s).catch(() => {})
+      return hit.models
     }
-    this.modelsCache.set(supplierId, { models, fetchedAt: Date.now() })
-    return models
+    return await this.refreshModels(supplierId, s)
+  }
+
+  /**
+   * 真拉一次上游并写缓存。并发调用共享同一个 in-flight promise——
+   * 组合页会同时触发多个入口,不去重会把上游按 N 倍打(各家插件自己没做这层)。
+   *
+   * 失败时:**有旧值就退回旧值**(宁可显示几分钟前的列表,也别让面板空掉),
+   * **没旧值就把错误抛回去**——调用方(`supplierModels`)据此把该供应商整个
+   * 剔除,而不是显示一个「有 0 个模型」的空壳。
+   */
+  private refreshModels(supplierId: string, s: Supplier): Promise<ModelWithEnabled[]> {
+    const inflight = this.modelsInflight.get(supplierId)
+    if (inflight !== undefined) return inflight
+    const p = (async (): Promise<ModelWithEnabled[]> => {
+      const cfg = this.store.get(supplierId)
+      const custom = new Set(cfg.custom)
+      const disabled = new Set(cfg.disabled)
+      const list = await Promise.resolve(s.listModels())
+      const models: ModelWithEnabled[] = list.map((mm) => ({
+        ...mm,
+        enabled: !disabled.has(mm.id),
+        custom: custom.has(mm.id) ? true : undefined,
+      }))
+      // 自定义模型（listModels 之外的）并入显示
+      const seen = new Set(models.map((mm) => mm.id))
+      for (const id of custom) {
+        if (!seen.has(id)) {
+          seen.add(id)
+          models.push({ id, enabled: !disabled.has(id), custom: true })
+        }
+      }
+      const stale = this.modelsCache.get(supplierId)
+      // 拉到空列表当「上游抖了一下」:有旧值就保住旧值并返回它,别把面板清空。
+      // 真的一家模型都没有的供应商,第一次(无旧值)就该拿到空,不受影响。
+      if (models.length === 0 && stale !== undefined && stale.models.length > 0) {
+        return stale.models
+      }
+      this.modelsCache.set(supplierId, { models, fetchedAt: Date.now() })
+      return models
+    })()
+      .catch((err: unknown) => {
+        const stale = this.modelsCache.get(supplierId)
+        if (stale !== undefined) return stale.models
+        throw err instanceof Error ? err : new Error(String(err))
+      })
+      .finally(() => {
+        this.modelsInflight.delete(supplierId)
+      })
+    this.modelsInflight.set(supplierId, p)
+    return p
   }
 
   /** 失效某供应商的模型缓存（增删改模型后调用）。 */
@@ -973,15 +1028,20 @@ export class Router {
       rawBody: JSON.stringify({ model, messages: [{ role: 'user', content: 'ping' }], stream: false, max_tokens: 1 }),
     }
     let served = false
+    const trace: ChatTrace = { attempts: 0 }
     try {
-      served = await this.chatWithSupplier(s, req, sink)
+      served = await this.chatWithSupplier(s, req, sink, trace)
     } catch (err) {
       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()) : ''
-    const detail = fromSink !== '' ? fromSink : s.lastError?.()
+    // 失败原因优先从上游响应体取，其次用 chatOnce 返回的 message（trace.lastError）。
+    // 以前这里问插件的 lastError()——那是「最后一次失败」的可变全局，既可能串到
+    // 别的账号/别的请求，也有插件压根没实现（codebuddy 就漏了，于是永远拿不到兜底）。
+    // chatOnce 的返回值本身就带 message，用它更准，插件也不必再维护一份状态。
+    const detail = fromSink !== '' ? fromSink : trace.lastError
     return {
       ok: false,
       error: detail !== undefined && detail !== ''

package/src/router/models-cache.test.ts

@@ -66,6 +66,21 @@ function addSupplier(router: Router, s: unknown): void {
   ;(router as unknown as { suppliers: unknown[] }).suppliers.push(s)
 }
 
+/**
+ * 把某供应商的缓存标记成「已过期」（TTL 现在 10 分钟，测试不能真等）。
+ * 白盒改 fetchedAt，模拟插件重启/TTL 到期的冷路径。
+ */
+function expire(router: Router, id: string): void {
+  const cache = (router as unknown as { modelsCache: Map<string, { fetchedAt: number }> }).modelsCache
+  const hit = cache.get(id)
+  if (hit !== undefined) hit.fetchedAt = 0
+}
+
+/** 等一轮 microtask/定时器，让 fire-and-forget 的后台刷新跑完。 */
+function tick(ms = 20): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms))
+}
+
 test('组合面板连开两次只拉一次上游（缓存生效）', async () => {
   const router = new Router('')
   const a = supplier('a', [{ id: 'a-1' }])
@@ -137,9 +152,129 @@ test('单个供应商拉模型失败不影响其它供应商', async () => {
   assert.equal(groups[0]?.supplier.id, 'good')
 })
 
-test('未知供应商返回空，不抛错', async () => {
+/**
+ * 冷启动慢的回归（2026-09-03 实测）：插件的 listModels 大多无条件打上游
+ * （0.3~1.0s/供应商），TTL 一过就穿透到插件，组合页取最慢那家 = 1s+ 白屏。
+ * 现在核心走 stale-while-revalidate：过期先返回旧值，后台刷新。
+ */
+test('过期后不等上游：立刻返回旧值，后台刷新', async () => {
+  const router = new Router('')
+  // 慢供应商：真等它就是 300ms
+  const a = supplier('a', [{ id: 'a-1' }], 300)
+  addSupplier(router, a.s)
+
+  await router.modelsOf('a')
+  assert.equal(a.state.calls, 1)
+  expire(router, 'a')
+
+  const t0 = Date.now()
+  const models = await router.modelsOf('a')
+  const dt = Date.now() - t0
+
+  assert.ok(dt < 100, `过期后不该同步等上游（实测 ${dt}ms）`)
+  assert.deepEqual(models.map((m) => m.id), ['a-1'], '旧值要立刻返回，面板不空')
+  await tick(400)
+  assert.equal(a.state.calls, 2, '后台要真的刷新一次')
+})
+
+test('后台刷新后缓存变新：再取不再触发拉取', async () => {
   const router = new Router('')
-  assert.deepEqual(await router.modelsOf('nonexistent'), [])
+  const a = supplier('a', [{ id: 'a-1' }])
+  addSupplier(router, a.s)
+
+  await router.modelsOf('a')
+  expire(router, 'a')
+  await router.modelsOf('a') // 触发后台刷新
+  await tick()
+  assert.equal(a.state.calls, 2)
+
+  await router.modelsOf('a') // 已刷新过，不该再拉
+  await tick()
+  assert.equal(a.state.calls, 2)
+})
+
+test('并发刷新共享一次上游请求（不去重会把上游按 N 倍打）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }], 50)
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+  expire(router, 'a')
+
+  // 组合页的实际情况：多个入口同时触发同一个供应商
+  await Promise.all([router.modelsOf('a'), router.modelsOf('a'), router.modelsOf('a')])
+  await tick(200)
+  assert.equal(a.state.calls, 2, `并发只应多拉一次，实测 ${a.state.calls}`)
+})
+
+test('force 仍然同步等（用户主动点「获取模型」，要看到结果）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }], 150)
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+  expire(router, 'a')
+
+  const t0 = Date.now()
+  await router.modelsOf('a', true)
+  assert.ok(Date.now() - t0 >= 100, 'force 必须等上游拉完')
+  assert.equal(a.state.calls, 2)
+})
+
+test('拉到空列表不覆盖旧值（上游抖一下不该清空面板）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }])
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+
+  a.s.listModels = async (): Promise<ModelInfo[]> => []
+  expire(router, 'a')
+  const models = await router.modelsOf('a', true)
+
+  assert.deepEqual(models.map((m) => m.id), ['a-1'], '空结果不该冲掉旧列表')
+})
+
+test('后台刷新失败 → 保留旧值，不抛（fire-and-forget 没人接异常）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }])
+  addSupplier(router, a.s)
+  await router.modelsOf('a')
+
+  a.s.listModels = async (): Promise<ModelInfo[]> => {
+    throw new Error('upstream down')
+  }
+  expire(router, 'a')
+  const models = await router.modelsOf('a')
+  assert.deepEqual(models.map((m) => m.id), ['a-1'], '失败也要保住旧值')
+})
+
+test('首次就失败且无旧值 → 抛错（让 supplierModels 剔除该供应商，别显示空壳）', async () => {
+  const router = new Router('')
+  const a = supplier('a', [])
+  a.s.listModels = async (): Promise<ModelInfo[]> => {
+    throw new Error('upstream down')
+  }
+  addSupplier(router, a.s)
+
+  await assert.rejects(() => router.modelsOf('a'), /upstream down/)
+})
+
+/**
+ * 回归（2026-09-03 契约精简）：删了插件 lastError() 后，testModel 的失败原因
+ * 必须从 chatOnce 返回值的 message 取（经 trace.lastError 透传）。以前问插件
+ * 的 lastError() 是个「最后一次失败」的可变全局，可能串别的请求，也有插件
+ * 压根没实现照样能走到。锁住：chatOnce 报的 message 能作为诊断呈现。
+ */
+test('testModel 失败 → 用 chatOnce 返回的 message 作诊断，不依赖插件 lastError()', async () => {
+  const router = new Router('')
+  const a = supplier('a', [{ id: 'a-1' }])
+  // 明确不实现 lastError()——合约删了它
+  a.s.chatOnce = async (): Promise<ChatOnceResult> =>
+    ({ ok: false, state: 'quota', message: 'no quota for this plan' })
+  addSupplier(router, a.s)
+
+  const r = await router.testModel('a', 'a-1')
+  assert.equal(r.ok, false)
+  assert.match(r.error ?? '', /no quota for this plan/, '失败原因要来自 chatOnce 的 message')
+  assert.match(r.error ?? '', /账号\/额度\/限流问题/, '要带上可诊断的归类提示')
 })
 
 /**

package/src/router/types.ts

@@ -80,8 +80,6 @@ export interface Supplier {
   accounts(): SupplierAccountNow[]
   /** 对单个账号调一次上游。不遍历账号、不管冷却、不写 res。 */
   chatOnce(uid: string, req: ChatRequest): Promise<ChatOnceResult>
-  /** 上次 chatOnce 失败原因（诊断用，可选）。 */
-  lastError?(): string | undefined
   /** 删除链接（清理凭证；内部能力，js 契约不要求实现）。 */
   removeLink?(uid: string): Promise<boolean>
   dispose(): void

package/src/supplier-config.test.ts

@@ -0,0 +1,98 @@
+/**
+ * 积分缓存（核心统一持久化）测试 —— node --test 直接跑。
+ *
+ * 锁定的契约（2026-09-03 修的 bug：codebuddy 重启后面板永久显示 0 积分）：
+ *   - 插件报真值 → 落盘，重启后还在
+ *   - 插件报 -1（没拉到）→ 顶上次的缓存，不能显示 0
+ *   - 插件报 0（真用完了）→ 缓存被冲成 0，不能被当成「未知」保住旧值
+ *   - 删链接 → 缓存一起清
+ *   - 坏数据（负数/NaN/缺字段）读盘时不炸，当没缓存过
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { SupplierConfigStore } from './supplier-config.ts'
+
+/** 每个用例一个独立数据目录（stateFile 推导出 supplier-config.json 的位置）。 */
+function tempStore(preload?: unknown): { store: SupplierConfigStore; file: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'dshr-credits-'))
+  const stateFile = join(dir, 'state.json')
+  if (preload !== undefined) {
+    writeFileSync(join(dir, 'supplier-config.json'), JSON.stringify(preload))
+  }
+  return { store: new SupplierConfigStore(stateFile), file: join(dir, 'supplier-config.json') }
+}
+
+const UNKNOWN = -1
+
+test('报真值 → 落盘，重开还在', () => {
+  const { store, file } = tempStore()
+  assert.equal(store.putCredits('codebuddy', 'cb-1', 1234.5), 1234.5)
+  const raw = JSON.parse(readFileSync(file, 'utf8')) as {
+    suppliers: Record<string, { credits: Record<string, number> }>
+  }
+  assert.equal(raw.suppliers.codebuddy?.credits['cb-1'], 1234.5)
+  // 新实例 = 模拟重启
+  assert.equal(new SupplierConfigStore(join(file, '..', 'state.json')).getCredits('codebuddy', 'cb-1'), 1234.5)
+})
+
+test('报 -1（没拉到）→ 顶上次缓存，不是 0', () => {
+  const { store } = tempStore()
+  store.putCredits('codebuddy', 'cb-1', 900)
+  // 插件重启后内存缓存空 → 报 -1
+  assert.equal(store.putCredits('codebuddy', 'cb-1', UNKNOWN), 900)
+  assert.equal(store.getCredits('codebuddy', 'cb-1'), 900)
+})
+
+test('从来没拿到过 → 就是 -1（读不到就别编 0）', () => {
+  const { store } = tempStore()
+  assert.equal(store.getCredits('codebuddy', 'cb-1'), UNKNOWN)
+  assert.equal(store.putCredits('codebuddy', 'cb-1', UNKNOWN), UNKNOWN)
+})
+
+test('报 0（真用完了）→ 缓存被冲成 0', () => {
+  const { store } = tempStore()
+  store.putCredits('codebuddy', 'cb-1', 500)
+  assert.equal(store.putCredits('codebuddy', 'cb-1', 0), 0)
+  assert.equal(store.getCredits('codebuddy', 'cb-1'), 0)
+})
+
+test('删链接 → 积分缓存一起清', () => {
+  const { store } = tempStore()
+  store.putCredits('codebuddy', 'cb-1', 700)
+  store.clearCredits('codebuddy', 'cb-1')
+  assert.equal(store.getCredits('codebuddy', 'cb-1'), UNKNOWN)
+})
+
+test('同值重复写入不落盘（status() 是高频调用）', () => {
+  const { store, file } = tempStore()
+  store.putCredits('codebuddy', 'cb-1', 42)
+  const before = readFileSync(file, 'utf8')
+  store.putCredits('codebuddy', 'cb-1', 42)
+  assert.equal(readFileSync(file, 'utf8'), before)
+})
+
+test('坏数据读盘不炸：负数/NaN/非数字当没缓存过', () => {
+  const { store } = tempStore({
+    suppliers: { codebuddy: { credits: { 'cb-bad': -5, 'cb-nan': null, 'cb-ok': 300 } } },
+  })
+  assert.equal(store.getCredits('codebuddy', 'cb-bad'), UNKNOWN)
+  assert.equal(store.getCredits('codebuddy', 'cb-nan'), UNKNOWN)
+  assert.equal(store.getCredits('codebuddy', 'cb-ok'), 300)
+})
+
+test('旧配置文件（无 credits 字段）能读，不炸', () => {
+  const { store } = tempStore({ suppliers: { codebuddy: { alias: 'cb', poolOrder: ['cb-1'] } } })
+  assert.equal(store.getCredits('codebuddy', 'cb-1'), UNKNOWN)
+  assert.deepEqual(store.get('codebuddy').poolOrder, ['cb-1'])
+})
+
+test('按供应商隔离：同 uid 不同供应商互不干扰', () => {
+  const { store } = tempStore()
+  store.putCredits('codebuddy', 'key-1', 100)
+  store.putCredits('traework', 'key-1', 200)
+  assert.equal(store.getCredits('codebuddy', 'key-1'), 100)
+  assert.equal(store.getCredits('traework', 'key-1'), 200)
+})

package/src/supplier-config.ts

@@ -5,6 +5,7 @@
  *   - 别名 alias(前缀,模型全名 = alias/id)
  *   - 模型管理:启用/禁用 disabled、自定义 custom
  *   - 连接池:poolOrder(拖动排序)、poolStrategy(回退/轮询)
+ *   - 积分缓存 credits:按 supplier/uid 缓存最后一次拿到的剩余额度
  *
  * 持久化到 data/supplier-config.json。
  */
@@ -13,18 +14,40 @@ import { dirname, join } from 'node:path'
 
 export type PoolStrategy = 'fallback' | 'round-robin'
 
+/**
+ * 积分哨兵:插件还**没拿到过**真实额度(刚重启、积分拉取失败、或压根不支持
+ * 积分)时报 `-1`,核心据此保留上一次的缓存值,而不是把 0 写进去。
+ *
+ * 为什么不能用 0 表示未知:积分 0 是有意义的真值(用完了),核心无法区分
+ * 「拿到 0」和「没拿到」。用 0 当哨兵会把缓存冲成 0 —— 这正是 codebuddy
+ * 重启后面板永久显示 0 积分的原因(插件只在内存里缓存积分)。
+ */
+export const CREDITS_UNKNOWN = -1
+
 export interface SupplierConfig {
   alias: string
   disabled: string[]
   custom: string[]
   poolOrder: string[]
   poolStrategy: PoolStrategy
+  /** 积分缓存:uid → 剩余额度(最后一次从插件拿到的非 -1 值)。 */
+  credits: Record<string, number>
 }
 
 interface ConfigFile {
   suppliers: Record<string, Partial<SupplierConfig>>
 }
 
+/** 读盘时的积分字段校验：只留有限非负数（负数一律当没缓存过）。 */
+function readCredits(raw: unknown): Record<string, number> {
+  const out: Record<string, number> = {}
+  if (typeof raw !== 'object' || raw === null) return out
+  for (const [uid, v] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof v === 'number' && Number.isFinite(v) && v >= 0) out[uid] = v
+  }
+  return out
+}
+
 /** 通用供应商配置存储。 */
 export class SupplierConfigStore {
   private fp = ''
@@ -55,7 +78,7 @@ export class SupplierConfigStore {
   get(supplierId: string): SupplierConfig {
     let cfg = this.bySupplier.get(supplierId)
     if (!cfg) {
-      cfg = { alias: '', disabled: [], custom: [], poolOrder: [], poolStrategy: 'fallback' }
+      cfg = { alias: '', disabled: [], custom: [], poolOrder: [], poolStrategy: 'fallback', credits: {} }
       this.bySupplier.set(supplierId, cfg)
     }
     return cfg
@@ -116,6 +139,40 @@ export class SupplierConfigStore {
     this.saveLocked()
   }
 
+  // ---- 积分缓存（核心统一持久化，插件只管报） ----
+
+  /**
+   * 读缓存的积分。没缓存过返回 `CREDITS_UNKNOWN`(-1),让调用方自己决定
+   * 显示什么——不要把 -1 当 0 展示。
+   */
+  getCredits(supplierId: string, uid: string): number {
+    const v = this.get(supplierId).credits[uid]
+    return typeof v === 'number' && Number.isFinite(v) ? v : CREDITS_UNKNOWN
+  }
+
+  /**
+   * 合并插件报的积分:非 -1 就写入并返回它;-1(未知)则回落到上次缓存值。
+   * @returns 面板该显示的积分(仍可能是 -1 = 从来没拿到过)
+   */
+  putCredits(supplierId: string, uid: string, reported: number): number {
+    if (typeof reported !== 'number' || !Number.isFinite(reported) || reported < 0) {
+      return this.getCredits(supplierId, uid)
+    }
+    const prev = this.getCredits(supplierId, uid)
+    if (prev === reported) return reported // 值没变,不写盘(status() 是高频调用)
+    this.get(supplierId).credits[uid] = reported
+    this.saveLocked()
+    return reported
+  }
+
+  /** 删除链接时清掉它的积分缓存(不写盘:下一行 removeLink 会带出保存)。 */
+  clearCredits(supplierId: string, uid: string): void {
+    const credits = this.get(supplierId).credits
+    if (credits[uid] === undefined) return
+    delete credits[uid]
+    this.saveLocked()
+  }
+
   private load(): void {
     if (this.fp === '') return
     let f: ConfigFile
@@ -131,6 +188,7 @@ export class SupplierConfigStore {
         custom: Array.isArray(c.custom) ? c.custom.filter((m) => typeof m === 'string') : [],
         poolOrder: Array.isArray(c.poolOrder) ? c.poolOrder.filter((u) => typeof u === 'string') : [],
         poolStrategy: c.poolStrategy === 'round-robin' ? 'round-robin' : 'fallback',
+        credits: readCredits(c.credits),
       })
     }
   }
@@ -145,6 +203,7 @@ export class SupplierConfigStore {
         custom: [...cfg.custom],
         poolOrder: [...cfg.poolOrder],
         poolStrategy: cfg.poolStrategy,
+        credits: { ...cfg.credits },
       }
     }
     try {

package/src/suppliers/contract.ts

@@ -57,6 +57,12 @@ export type AccountState =
 export interface SupplierAccountNow {
   uid: string
   nickname?: string
+  /**
+   * 剩余额度。**拿不到就报 `-1`**，不是 0：
+   * 插件刚重启（内存缓存空）、积分拉取失败、或压根不支持积分时都是 `-1`。
+   * 核心据此保留上一次持久化下来的值 —— 报 0 会把缓存冲成 0（0 是真值
+   * 「用完了」，核心分不清「拿到 0」和「没拿到」）。
+   */
   credits: number
   /** 插件观察到的上游状态。 */
   state: AccountState
@@ -96,25 +102,19 @@ export interface SupplierModule {
   status(): SupplierStatusNow
   /** 模型来源。`force=true` 时强制刷新来源（核心「获取模型」按钮调用）。 */
   listModels(force?: boolean): Promise<ModelInfo[]> | ModelInfo[]
-  /** 默认前缀（可被通用层 alias 覆盖）。 */
-  getAlias(): string
   /**
    * 对**单个账号**调一次上游。插件不遍历账号、不管冷却、不写 res——
    * 选号/回退/健康判定全是核心的活。
    * 无账号供应商（如 opencode）传空 uid，忽略即可。
+   *
+   * 失败原因通过返回值的 `message` 报（核心在测试模型时直接用它做诊断提示），
+   * 插件不必自己存一份「上次失败」的状态。
    */
   chatOnce(uid: string, req: ChatRequest): Promise<ChatOnceResult>
   dispose(): void
 
   // ---- 差异化能力（可选，按存在性暴露端点/UI） ----
 
-  /** 上次 chatOnce 失败的原因（诊断用）。
-   *  测试模型由 dsh-router 核心统一走 chatOnce 路径（账号池回退/冷却自动生效），
-   *  插件只需把失败原因暴露出来供核心汇总；不实现则测试失败时只有通用提示。 */
-  lastError?(): string | undefined
-
-  // ---- 差异化能力（可选，按存在性暴露端点/UI） ----
-
   /** 生成登录链接（加账号）。有它才显示连接池（账号池）。 */
   generateLoginUrl?(): string | { ok: boolean; error?: string; loginUrl?: string } | Promise<string | { ok: boolean; error?: string; loginUrl?: string }>
   /** 回调完成登录。 */