dsh-router-core 0.3.3 → 0.3.4

package/README.md

@@ -45,7 +45,7 @@ dsh plugin --profile web add dsh-router-core
 | 零额外进程 | 就是 DSH 插件,随 `dsh web` 启停,天然同源(`/router/api/*` 无 CORS、面板嵌在设置里)。 |
 | 供应商即插即拔 | 内置供应商随插件分发;更多供应商 = 装一个 DSH 插件(`dsh-router-*`)或放一个 js 文件到 `~/.dsh/profiles/web/suppliers/`。 |
 | 模型不内置 | 供应商只实现差异化能力,模型拉取与缓存由核心统一管,不写死、不过时。 |
-| 策略只写一次 | 组合回退、账号池(选号/冷却/禁用/连续错误累计)、响应写入、凭证存储、模型管理都由核心提供。供应商 js 只对**单个账号**调一次上游并报告成败,不自己遍历账号、不维护冷却表——否则每个插件都会长出一份互相不一致的实现,而核心也就无从判断「该不该换号」。 |
+| 策略只写一次 | 组合回退、账号池(选号/冷却/禁用)、响应写入、凭证存储、积分持久化、模型管理都由核心提供。供应商 js 只对**单个账号**调一次上游并报告成败,不自己遍历账号、不维护冷却表、不落盘积分——否则每个插件都会长出一份互相不一致的实现,而核心也就无从判断「该不该换号」。 |
 | 凭证单库 | `auths/credentials.sqlite`,供应商凭证不透明 blob,核心统一生命周期,干净可备份。 |
 | 组合即模型 | 建好的组合自动带出为 DSH 模型目录里的 `router` provider 选项,设置 → 模型直接选组合名即可。 |
 | 用量可观测 | 面板概览看板:周期切换、汇总卡、趋势折线、Top 榜、最近请求。 |

package/docs/suppliers.md

@@ -10,16 +10,18 @@
 | | 谁负责 |
 |---|---|
 | 组合回退、按策略选中模型 | 核心 |
-| **账号池**:选号、冷却、禁用、连续错误累计、遍历回退 | 核心 |
+| **账号池**:选号、冷却、禁用、遍历回退 | 核心 |
 | 响应写入(状态行、SSE 头、JSON body) | 核心 |
 | 模型启用/禁用、自定义模型、别名 | 核心 |
 | 凭证存储(`env.credentials`) | 核心 |
+| 积分**持久化**(`supplier-config.json` 的 `credits`) | 核心 |
 | **对单个账号调通上游**(协议、鉴权、SSE 解析/生成) | **js** |
-| 列模型、登录、加 key、删链接、签到、拉积分 | **js** |
+| 列模型、登录、加 key、删链接、签到、拉积分(只报值,不落盘) | **js** |
 
-关键推论:**js 不遍历账号、不维护冷却表、不写 `res`**。
+关键推论:**js 不遍历账号、不维护冷却表、不写 `res`、不落盘积分**。
 `chatOnce(uid, req)` 一次只服务一个账号,成败告诉核心,换不换号由核心决定。
 这样「哪个账号坏了」「为什么坏」是核心的一等信息,组合回退才做得了判断。
+积分同理:js 报值,核心存。
 
 ## 契约
 
@@ -58,6 +60,7 @@ export const priority = 10        // 数字越小越优先(免费优先)
 js 报告**此刻**观察到的账户状况,而不是把上游原始响应丢给核心解读:
 
 ```ts
+// credits: 剩余额度。拿不到(含不支持积分)报 -1——0 是真值「用完了」,别拿它当未知
 { uid, nickname?, credits: number, state: AccountState, message? }
 ```
 
@@ -74,10 +77,10 @@ js 报告**此刻**观察到的账户状况,而不是把上游原始响应丢给
 | `unknown` | 说不清是什么错 |
 | `no_such_model` | **这个模型不属于本供应商**(不是账号的失败) |
 
-**`no_such_model` 是必须的,不能拿 `unavailable` 顶替。** 后者在核心策略里
-会计一次连续错误——组合里每有一个别人家的模型,就会给无关账号攒一次错误,
-攒够 3 次把它冷却 5 分钟,表现为「组合越用越没号可用」。所以「这个模型不属于我」
-一定要报 `no_such_model`,核心才知道该换供应商而不是换账号。
+**`no_such_model` 是必须的,不能拿 `unavailable` 顶替。** 后者在核心策略里会
+把**这个号 × 这个模型**冷掉——组合里每有一个别人家的模型,js 就会对每个账号
+都报一次,于是一个都选不出来(表现为「组合越用越没号可用」)。所以「这个模型
+不属于我」一定要报 `no_such_model`,核心才知道该换供应商而不是换账号。
 
 **js 只说「现在怎么了」,不说「该怎么办」。** 冷却多久、是否禁用、要不要换号
 都是核心的策略(见下),js 不该自己记冷却表——那样每个插件都会长出一份
@@ -85,6 +88,16 @@ js 报告**此刻**观察到的账户状况,而不是把上游原始响应丢给
 
 核心在 `status()` 之上叠加 `cooling` / `disabled` / `err_count` / `until` / `reason`
 再给面板,所以 js 不用(也不该)填这些字段。`accounts` 为空数组 = 无账号供应商。
+注意 `err_count` 现在是**限流退避等级**(反复被限流的号等级递增),不是
+「连续失败次数」——面板按等级展示,等级在成功后清零。
+
+### 冷却颗粒度 = (供应商, 模型, 连接)
+
+js 只要知道这一条:**报 `rate_limit`/`transport`/`unknown` 只影响「这个号 × 这个
+模型」**,不会牵连该号上的其它模型。一个连接服务多个模型时,模型 A 被限流不该
+让模型 B 也不可用。
+
+例外是 `session_dead`:凭证失效是连接级问题,该号**所有模型**都停用。
 
 ## `chatOnce(uid, req)`:一次只服务一个账号
 
@@ -105,17 +118,23 @@ type ChatOnceResult =
 
 | state | 核心处置 |
 |---|---|
-| `rate_limit` | 冷却 1 分钟 |
+| `rate_limit` | **指数退避**:首次 2s,每次翻倍,上限 5 分钟;成功后等级清零 |
 | `quota` | 冷却 10 分钟 |
-| `session_dead` | **永久禁用**(需重新登录才能恢复) |
-| `unavailable` / `transport` / `unknown` | 计一次连续错误,攒够 3 次冷却 5 分钟 |
+| `session_dead` | **永久禁用该号**(所有模型都停用,需重新登录才能恢复) |
+| `unavailable` / `transport` / `unknown` | 瞬时短冷却 30s(**每次都冷**,不攒次数) |
 | `no_such_model` | **不惩罚账号**,核心直接跳过整个供应商换下一个 |
 
 - 非流式若聚合后发现**空响应**(无 content / reasoning / tool_calls),请返回
   `{ ok:false, state:'unknown' }` 而不是 `ok:true`——空响应交给核心换号/换模型回退,
   比当作成功更有用
 
-冷却/禁用/错误累计目前是**内存态**,重启归零(与凭证/积分的持久化不同)。
+所以 js 别报「保险」的状态:把瞬时抖动报成 `quota` 会让好号白躺 10 分钟,把
+限流报成 `unknown` 则只冷 30s、等下个请求再撞一次。网关自带业务码的(如
+「请求参数非法」「上游临时不可用」)建议归 `rate_limit`——瞬时/请求类的错,
+短冷换号比长冷划算。
+
+冷却/禁用/退避等级都是**内存态**,重启归零(与凭证、积分的持久化不同)。
+重启后所有号都会重新被选中一次,所以**上游确实挂了的号会各撞一次**,属预期。
 要跨重启保留,届时给账号池加一个落盘 state 文件即可,接口不用变。
 
 ### 流式一旦写出第一个字节才绑死
@@ -176,9 +195,21 @@ js 只需把失败原因记下来并通过 `lastError()` 暴露,核心就能给
 - `message` 直接透给用户看;某个 uid 抛错由核心兜住记成 `error`,不会带垮其它链接
 - 核心汇总后给面板:`{ ok, total, succeeded, already, results }`
 
-`credits`(`status().accounts[].credits`)用于面板显示积分/额度;上游接口不实时时
-建议缓存 + 签到后刷新。**填「剩余额度」而不是「已消耗」**——额度类接口两者常常
-都有,填反了面板数字会越用越多。
+`credits`(`status().accounts[].credits`)用于面板显示积分/额度。**填「剩余额度」
+而不是「已消耗」**——额度类接口两者常常都有,填反了面板数字会越用越多。
+
+### 积分归核心持久化,js 只报值
+
+积分的持久化由核心统一管(存 `supplier-config.json` 的 `credits` 字段),js **不要
+自己落盘**——一份数据两处存,两边都可能过期。js 只管两件事:内存 TTL、报真值。
+
+报值的规矩(见上「`status()`」一节):**拿不到就报 `-1`,不是 `0`**。核心靠这个
+区分「没拿到」和「拿到了 0」,报 0 会把缓存冲成 0(`0` 是真值「用完了」)。
+不支持积分的供应商也报 `-1`,面板显示「积分未知」。
+
+天花板:核心存的是「最后一次拿到的值」,不带时间戳。所以插件重启后短暂显示
+上次的值,真值等异步拉完自动覆盖(面板下一次刷新即可见)。要消掉这个窗口,
+得让核心存时间戳并在过期时标旧,目前没做。
 
 上游幂等要处理好:有的上游「今日已签到」返回 **HTTP 400 + 业务 code**,
 所以要先解析 body 的 code 再判 HTTP 状态,否则幂等情况会被误报成失败。
@@ -222,8 +253,8 @@ RPC 失败,表现为「历史加载失败」。
 
 面板链接池的「刷新」按钮是核心的活,js 不用做任何事:
 
-1. **积分**:核心连着调 `status()` 等它落地;`status().accounts[].credits`
-   该缓存就缓存,不该缓存就现拉,核心只认这个字段
+1. **积分**:核心连着调 `status()` 等它落地(最多 3s),只认
+   `status().accounts[].credits` 这一个字段,并统一持久化
 2. **健康**:核心拿一个启用模型跑一次最简会话(复用「测试模型」的 `chatOnce`
    路径),回答「这个供应商还有没有活着的链接」——**不按链接细分**
 
@@ -239,8 +270,9 @@ export const id = 'echo'
 export const name = 'Echo'
 export const priority = 10
 
-// 只报「现在状态」:冷却/禁用/错误累计由核心叠加
-const accounts = [{ uid: 'echo-1', nickname: 'Echo 1', credits: 100, state: 'ok' }]
+// 只报「现在状态」:冷却/禁用/退避等级由核心叠加,积分由核心持久化
+// credits: -1 = 不支持/没拉到(别写 0,0 会被当成「用完了」存下来)
+const accounts = [{ uid: 'echo-1', nickname: 'Echo 1', credits: -1, state: 'ok' }]
 
 export function status() { return { id, name, accounts } }
 export function listModels() { return [{ id: 'echo-model' }] }
@@ -278,17 +310,25 @@ export function dispose() {}
 
 单个供应商加载失败(缺 `id`/`name`、构造异常)不阻断其他供应商,错误记入 DSH 日志。
 
-**模型统一策略**:供应商的模型列表**优先从上游拉取、不自行缓存**——
-`listModels` 每次都从上游拉取(失败回退上次成功结果避免面板空模型),**缓存由
-核心统一管**(`Router.modelsOf`,TTL 60s)。
+**模型统一策略**:模型列表**优先从上游拉取**,缓存由核心统一管
+(`Router.modelsOf`,TTL 10 分钟),js **不要自己缓存**——自己缓存一份会和核心
+那份一起过期两次,「获取模型」按钮就成了摆设。
+
+核心缓存是 **stale-while-revalidate**:过期后**先返回旧值**让面板立刻有内容,
+后台再重新拉。所以 `listModels` 被调用的时机是:
+
+- **冷启动**(该供应商第一次被问,没有旧值)——**会同步等**,全程只有这一次
+- **TTL 过期后的第一次**——返回旧值,`listModels` 在**后台**被调用
+- **手动点「获取模型」**(`force=true`)——**会同步等**,用户要看到结果
 
-这意味着 **js 的 `listModels` 会被核心频繁调用**,所以:
+因此:
 
-- 只有这两种场景会真的打到上游:**首次打开供应商详情**(缓存还没建)和
-  **手动点「获取模型」**(`force=true`)。组合面板只**读缓存**,不触发拉取
-- 因此 `listModels` 要**快**:别在里面做全量探测之类的重活。重活放到
-  `force=true` 时做(如按模型探测可用性),别拖慢每次只读
-- 失败时回退上次成功的结果,避免面板空模型
+- `listModels` 要**快**:别在里面做全量探测之类的重活。重活放到 `force=true`
+  时做(如按模型探测可用性)
+- 冷启动那次会拖慢面板首屏(实测 0.3~1.0s/供应商,组合页取最慢那家),
+  **别在这条路上加重活**——这是唯一一次用户真会等到的调用
+- 拉到空列表时核心会保住旧值不当成新结果,所以别用「返回空」表达
+  「上游出错」;出错就抛,核心会退回旧值(首次则整个供应商剔除)
 
 `/suppliers/:id/models` 与 `/combos` 共用这份缓存(模型增删改后失效),
 `/v1/models`(LLM 侧)保持实时。
@@ -310,9 +350,10 @@ export function dispose() {}
 
 ### 为什么组合要存供应商 id 而不是裸模型 id
 
-存裸 id 时,核心只能遍历所有供应商逐个试。插件用 `unavailable` 回答
-「不是我的」,而这个状态在池策略里**计一次连续错误**——组合里每有一个别人家的
-模型就给无关账号攒一次,攒够 3 次冷却 5 分钟,表现为「组合越用越没号可用」。
+存裸 id 时,核心只能遍历所有供应商逐个试。插件用 `unavailable` 回答「不是我的」,
+而这个状态在池策略里会把**这个号 × 这个模型**冷掉——组合里每有一个别人家的
+模型,每个账号在那模型上就都被冷一次,表现为「组合越用越没号可用」。
+(`no_such_model` 是为此专门加的状态:它不冷任何东西。)
 
 存了供应商 id 就不需要问了:直接调那一个。查不到供应商(拼错/供应商没加载)
 直接失败,**不兜底遍历**——兜底会让拼错的 id 静默落到别的供应商上,更难查。

package/lib/client-registry.js

@@ -838,16 +838,20 @@ window.__ModuleLoader__.load({
 														className: "dshr-linkDot",
 														children: "·"
 													}),
-													/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														className: "dshr-mono dshr-linkCredits",
-														children: [Math.ceil(account.credits), " 积分"]
+														children: account.credits < 0 ? "积分未知" : `${Math.ceil(account.credits)} 积分`
 													}),
 													account.err_count !== void 0 && account.err_count > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														className: "dshr-linkDot",
 														children: "·"
 													}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 														className: "dshr-linkErr",
-														children: ["连续错误 ", account.err_count]
+														children: [
+															"退避 ",
+															account.err_count,
+															" 级"
+														]
 													})] }),
 													coolingText !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														className: "dshr-reason dshr-linkCooling",

package/lib/client.js

@@ -838,16 +838,20 @@ window.__ModuleLoader__.load({
 														className: "dshr-linkDot",
 														children: "·"
 													}),
-													/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														className: "dshr-mono dshr-linkCredits",
-														children: [Math.ceil(account.credits), " 积分"]
+														children: account.credits < 0 ? "积分未知" : `${Math.ceil(account.credits)} 积分`
 													}),
 													account.err_count !== void 0 && account.err_count > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														className: "dshr-linkDot",
 														children: "·"
 													}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 														className: "dshr-linkErr",
-														children: ["连续错误 ", account.err_count]
+														children: [
+															"退避 ",
+															account.err_count,
+															" 级"
+														]
 													})] }),
 													coolingText !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														className: "dshr-reason dshr-linkCooling",

package/lib/index.js

@@ -251,18 +251,13 @@ var AccountPool = class {
 		});
 	}
 };
-//#endregion
-//#region src/supplier-config.ts
-/**
-* 通用供应商配置 —— dsh-router 核心能力,按供应商 id 存储。
-*
-* 通用能力(所有供应商共享,供应商 js 不需要实现)：
-*   - 别名 alias(前缀,模型全名 = alias/id)
-*   - 模型管理:启用/禁用 disabled、自定义 custom
-*   - 连接池:poolOrder(拖动排序)、poolStrategy(回退/轮询)
-*
-* 持久化到 data/supplier-config.json。
-*/
+/** 读盘时的积分字段校验：只留有限非负数（负数一律当没缓存过）。 */
+function readCredits(raw) {
+	const out = {};
+	if (typeof raw !== "object" || raw === null) return out;
+	for (const [uid, v] of Object.entries(raw)) if (typeof v === "number" && Number.isFinite(v) && v >= 0) out[uid] = v;
+	return out;
+}
 /** 通用供应商配置存储。 */
 var SupplierConfigStore = class {
 	fp = "";
@@ -292,7 +287,8 @@ var SupplierConfigStore = class {
 				disabled: [],
 				custom: [],
 				poolOrder: [],
-				poolStrategy: "fallback"
+				poolStrategy: "fallback",
+				credits: {}
 			};
 			this.bySupplier.set(supplierId, cfg);
 		}
@@ -344,6 +340,32 @@ var SupplierConfigStore = class {
 		this.get(supplierId).poolStrategy = strategy;
 		this.saveLocked();
 	}
+	/**
+	* 读缓存的积分。没缓存过返回 `CREDITS_UNKNOWN`(-1),让调用方自己决定
+	* 显示什么——不要把 -1 当 0 展示。
+	*/
+	getCredits(supplierId, uid) {
+		const v = this.get(supplierId).credits[uid];
+		return typeof v === "number" && Number.isFinite(v) ? v : -1;
+	}
+	/**
+	* 合并插件报的积分:非 -1 就写入并返回它;-1(未知)则回落到上次缓存值。
+	* @returns 面板该显示的积分(仍可能是 -1 = 从来没拿到过)
+	*/
+	putCredits(supplierId, uid, reported) {
+		if (typeof reported !== "number" || !Number.isFinite(reported) || reported < 0) return this.getCredits(supplierId, uid);
+		if (this.getCredits(supplierId, uid) === reported) return reported;
+		this.get(supplierId).credits[uid] = reported;
+		this.saveLocked();
+		return reported;
+	}
+	/** 删除链接时清掉它的积分缓存(不写盘:下一行 removeLink 会带出保存)。 */
+	clearCredits(supplierId, uid) {
+		const credits = this.get(supplierId).credits;
+		if (credits[uid] === void 0) return;
+		delete credits[uid];
+		this.saveLocked();
+	}
 	load() {
 		if (this.fp === "") return;
 		let f;
@@ -357,7 +379,8 @@ var SupplierConfigStore = class {
 			disabled: Array.isArray(c.disabled) ? c.disabled.filter((m) => typeof m === "string") : [],
 			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"
+			poolStrategy: c.poolStrategy === "round-robin" ? "round-robin" : "fallback",
+			credits: readCredits(c.credits)
 		});
 	}
 	saveLocked() {
@@ -368,7 +391,8 @@ var SupplierConfigStore = class {
 			disabled: [...cfg.disabled],
 			custom: [...cfg.custom],
 			poolOrder: [...cfg.poolOrder],
-			poolStrategy: cfg.poolStrategy
+			poolStrategy: cfg.poolStrategy,
+			credits: { ...cfg.credits }
 		};
 		try {
 			const dir = dirname(this.fp);
@@ -1055,8 +1079,15 @@ function withEstimates(usage, requestChars, outputChars) {
 * 仿 9router：组合 = 一组模型，请求 model 命中组合名时，按策略
 * （fallback 顺序尝试 / round-robin 轮转）选中一个模型路由。
 */
-/** 模型列表缓存有效期。 */
-const MODELS_TTL_MS = 6e4;
+/**
+* 模型列表缓存有效期。
+*
+* 取 10 分钟而不是 60s：模型列表本来很少变（上游上新/下线才动），而每次
+* TTL 过期都会穿透到插件真打一次上游——实测冷路径 0.3~1.0s/供应商，组合页
+* 取最慢那家就是 1s+ 的白屏。拉长 TTL 直接把这个穿透频率降一个量级；真要
+* 立刻看新模型，点「获取模型」走 force 即可。
+*/
+const MODELS_TTL_MS = 6e5;
 function openAIError(code, msg) {
 	return { error: {
 		message: msg,
@@ -1426,6 +1457,11 @@ var Router = class {
 	store;
 	/** 模型列表缓存（supplierId → 模型 + 拉取时间）。插件只管拉，不缓存。 */
 	modelsCache = /* @__PURE__ */ new Map();
+	/**
+	* 正在拉模型的供应商 → in-flight promise。
+	* 组合页会同时从多个入口触发同一个供应商的刷新，不去重上游就被按 N 倍打。
+	*/
+	modelsInflight = /* @__PURE__ */ new Map();
 	/** 请求日志出口（面板/宿主 logger）。 */
 	log;
 	/** 用量统计（概览看板）。 */
@@ -1535,40 +1571,74 @@ var Router = class {
 	* 取某供应商的模型（核心统一缓存）。
 	*
 	* 模型列表只在这里缓存一次：`/suppliers/:id/models`（供应商详情）和
-	* `/combos`（组合加模型）共用。组合面板**不主动打上游**——它只是读缓存，
-	* 冷启动（缓存还没建）时才拉一次；真正刷新由详情页打开或「获取模型」
-	* 按钮（force）触发。
+	* `/combos`（组合加模型）共用。
 	*
-	* 天花板：TTL 60s 是拍的。若上游模型列表变更很频繁，可调小；要彻底实时
-	* 就得让供应商暴露 etag/版本号，目前没有这个需求。
+	* **过期后走 stale-while-revalidate**:先返回旧值让面板立刻有内容,后台
+	* 重新拉,拉完下次请求就是新的。为什么必须这样:插件的 `listModels` 大多
+	* 无条件打上游(实测冷路径 0.3~1.0s/供应商),而组合页要拉全部供应商、
+	* 取最慢那家——同步等就是 1s+ 的白屏。旧值只可能「少列了新模型」,
+	* 比白屏划算;想立刻看新模型点「获取模型」(force)即可。
+	*
+	* 只有两种情况会真的等:`force`(用户主动刷新)和**从来没有过缓存值**
+	* (冷启动,没有旧值可给)。后者只发生一次。
 	*/
 	async modelsOf(supplierId, force = false) {
 		const s = this.suppliers.find((x) => x.id === supplierId);
 		if (s === void 0) return [];
 		const hit = this.modelsCache.get(supplierId);
-		if (!force && hit !== void 0 && 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 models = (await Promise.resolve(s.listModels())).map((mm) => ({
-			...mm,
-			enabled: !disabled.has(mm.id),
-			custom: custom.has(mm.id) ? true : void 0
-		}));
-		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 !== void 0 && Date.now() - hit.fetchedAt < MODELS_TTL_MS;
+		if (!force && fresh) return hit.models;
+		if (!force && hit !== void 0) {
+			this.refreshModels(supplierId, s).catch(() => {});
+			return hit.models;
 		}
-		this.modelsCache.set(supplierId, {
-			models,
-			fetchedAt: Date.now()
+		return await this.refreshModels(supplierId, s);
+	}
+	/**
+	* 真拉一次上游并写缓存。并发调用共享同一个 in-flight promise——
+	* 组合页会同时触发多个入口,不去重会把上游按 N 倍打(各家插件自己没做这层)。
+	*
+	* 失败时:**有旧值就退回旧值**(宁可显示几分钟前的列表,也别让面板空掉),
+	* **没旧值就把错误抛回去**——调用方(`supplierModels`)据此把该供应商整个
+	* 剔除,而不是显示一个「有 0 个模型」的空壳。
+	*/
+	refreshModels(supplierId, s) {
+		const inflight = this.modelsInflight.get(supplierId);
+		if (inflight !== void 0) return inflight;
+		const p = (async () => {
+			const cfg = this.store.get(supplierId);
+			const custom = new Set(cfg.custom);
+			const disabled = new Set(cfg.disabled);
+			const models = (await Promise.resolve(s.listModels())).map((mm) => ({
+				...mm,
+				enabled: !disabled.has(mm.id),
+				custom: custom.has(mm.id) ? true : void 0
+			}));
+			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 !== void 0 && stale.models.length > 0) return stale.models;
+			this.modelsCache.set(supplierId, {
+				models,
+				fetchedAt: Date.now()
+			});
+			return models;
+		})().catch((err) => {
+			const stale = this.modelsCache.get(supplierId);
+			if (stale !== void 0) return stale.models;
+			throw err instanceof Error ? err : new Error(String(err));
+		}).finally(() => {
+			this.modelsInflight.delete(supplierId);
 		});
-		return models;
+		this.modelsInflight.set(supplierId, p);
+		return p;
 	}
 	/** 失效某供应商的模型缓存（增删改模型后调用）。 */
 	invalidateModels(supplierId) {
@@ -1925,8 +1995,9 @@ var Router = class {
 			})
 		};
 		let served = false;
+		const trace = { attempts: 0 };
 		try {
-			served = await this.chatWithSupplier(s, req, sink);
+			served = await this.chatWithSupplier(s, req, sink, trace);
 		} catch (err) {
 			return {
 				ok: false,
@@ -1935,7 +2006,7 @@ var Router = class {
 		}
 		if (served && sink.status() < 400) return { ok: true };
 		const fromSink = served && sink.status() >= 400 ? extractUpstreamError(sink.body()) : "";
-		const detail = fromSink !== "" ? fromSink : s.lastError?.();
+		const detail = fromSink !== "" ? fromSink : trace.lastError;
 		return {
 			ok: false,
 			error: detail !== void 0 && detail !== "" ? `${detail}（账号/额度/限流问题，非模型问题）` : "所有账号都失败或账号都在冷却中（稍后重试）"
@@ -2526,6 +2597,26 @@ var KeysStore = class {
 function isFn(v) {
 	return typeof v === "function";
 }
+/**
+* 积分回灌（核心统一持久化，插件不落盘）。
+*
+* 插件的积分是异步拉的：重启后第一次 status() 拿不到真值，报 `CREDITS_UNKNOWN`
+* (-1)。这里做两件事：
+*   - 报了真值 → 写入 supplier-config.json（下次重启还在）
+*   - 报了 -1 → 用上次存的顶上，面板不会闪 0
+*
+* 插件不该自己把 0 当「未知」报上来 —— 0 是真值（用完了），核心分不清，
+* 会把缓存冲成 0。这条是本层存在的理由（2026-09-03）。
+*/
+function hydrateCredits(supplierId, store, accounts) {
+	return accounts.map((a) => {
+		const merged = store.putCredits(supplierId, a.uid, a.credits);
+		return merged === a.credits ? a : {
+			...a,
+			credits: merged
+		};
+	});
+}
 /** 从模块导出解析出供应商模块对象（支持 export default / 命名导出 / factory）。 */
 function resolveModule(mod, file) {
 	const cand = mod.default ?? mod;
@@ -2579,7 +2670,7 @@ function wrapModule(instance, env, source, kind = "external") {
 			return {
 				id: now.id,
 				name: now.name,
-				accounts: pool.decorate(now.accounts)
+				accounts: pool.decorate(hydrateCredits(instance.id, env.store, now.accounts))
 			};
 		},
 		listModels: (force) => instance.listModels(force),
@@ -2597,7 +2688,6 @@ function wrapModule(instance, env, source, kind = "external") {
 		customModelIds: () => [...env.store.get(instance.id).custom],
 		accounts: () => instance.status().accounts,
 		chatOnce: (uid, req) => instance.chatOnce(uid, req),
-		lastError: isFn(instance.lastError) ? () => instance.lastError() : void 0,
 		removeLink: isFn(instance.removeLink) ? (uid) => instance.removeLink(uid) : void 0,
 		dispose: () => instance.dispose(),
 		pool
@@ -2970,8 +3060,9 @@ function supplierRoutes(base, loaded, store, router) {
 				});
 				return;
 			}
-			const body = JSON.parse(await readBody$1(req));
-			const ok = await s.removeLink(body.uid ?? "");
+			const uid = JSON.parse(await readBody$1(req)).uid ?? "";
+			const ok = await s.removeLink(uid);
+			if (ok) store.clearCredits(s.id, uid);
 			writeJson$1(res, ok ? 200 : 404, ok ? { ok: true } : {
 				ok: false,
 				error: "link not found"

package/lib/types/router/index.d.ts

@@ -13,6 +13,11 @@ export declare class Router {
     private store;
     /** 模型列表缓存（supplierId → 模型 + 拉取时间）。插件只管拉，不缓存。 */
     private modelsCache;
+    /**
+     * 正在拉模型的供应商 → in-flight promise。
+     * 组合页会同时从多个入口触发同一个供应商的刷新，不去重上游就被按 N 倍打。
+     */
+    private modelsInflight;
     /** 请求日志出口（面板/宿主 logger）。 */
     private log;
     /** 用量统计（概览看板）。 */
@@ -50,14 +55,27 @@ export declare class Router {
      * 取某供应商的模型（核心统一缓存）。
      *
      * 模型列表只在这里缓存一次：`/suppliers/:id/models`（供应商详情）和
-     * `/combos`（组合加模型）共用。组合面板**不主动打上游**——它只是读缓存，
-     * 冷启动（缓存还没建）时才拉一次；真正刷新由详情页打开或「获取模型」
-     * 按钮（force）触发。
+     * `/combos`（组合加模型）共用。
+     *
+     * **过期后走 stale-while-revalidate**:先返回旧值让面板立刻有内容,后台
+     * 重新拉,拉完下次请求就是新的。为什么必须这样:插件的 `listModels` 大多
+     * 无条件打上游(实测冷路径 0.3~1.0s/供应商),而组合页要拉全部供应商、
+     * 取最慢那家——同步等就是 1s+ 的白屏。旧值只可能「少列了新模型」,
+     * 比白屏划算;想立刻看新模型点「获取模型」(force)即可。
      *
-     * 天花板：TTL 60s 是拍的。若上游模型列表变更很频繁，可调小；要彻底实时
-     * 就得让供应商暴露 etag/版本号，目前没有这个需求。
+     * 只有两种情况会真的等:`force`(用户主动刷新)和**从来没有过缓存值**
+     * (冷启动,没有旧值可给)。后者只发生一次。
      */
     modelsOf(supplierId: string, force?: boolean): Promise<ModelWithEnabled[]>;
+    /**
+     * 真拉一次上游并写缓存。并发调用共享同一个 in-flight promise——
+     * 组合页会同时触发多个入口,不去重会把上游按 N 倍打(各家插件自己没做这层)。
+     *
+     * 失败时:**有旧值就退回旧值**(宁可显示几分钟前的列表,也别让面板空掉),
+     * **没旧值就把错误抛回去**——调用方(`supplierModels`)据此把该供应商整个
+     * 剔除,而不是显示一个「有 0 个模型」的空壳。
+     */
+    private refreshModels;
     /** 失效某供应商的模型缓存（增删改模型后调用）。 */
     invalidateModels(supplierId: string): void;
     /** 可用模型（按供应商分组，仅启用），面板加模型用。

package/lib/types/router/types.d.ts

@@ -72,8 +72,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/lib/types/supplier-config.d.ts

@@ -1,10 +1,21 @@
 export type PoolStrategy = 'fallback' | 'round-robin';
+/**
+ * 积分哨兵:插件还**没拿到过**真实额度(刚重启、积分拉取失败、或压根不支持
+ * 积分)时报 `-1`,核心据此保留上一次的缓存值,而不是把 0 写进去。
+ *
+ * 为什么不能用 0 表示未知:积分 0 是有意义的真值(用完了),核心无法区分
+ * 「拿到 0」和「没拿到」。用 0 当哨兵会把缓存冲成 0 —— 这正是 codebuddy
+ * 重启后面板永久显示 0 积分的原因(插件只在内存里缓存积分)。
+ */
+export declare const CREDITS_UNKNOWN = -1;
 export interface SupplierConfig {
     alias: string;
     disabled: string[];
     custom: string[];
     poolOrder: string[];
     poolStrategy: PoolStrategy;
+    /** 积分缓存:uid → 剩余额度(最后一次从插件拿到的非 -1 值)。 */
+    credits: Record<string, number>;
 }
 /** 通用供应商配置存储。 */
 export declare class SupplierConfigStore {
@@ -34,6 +45,18 @@ export declare class SupplierConfigStore {
     removeCustomModel(supplierId: string, modelId: string): void;
     setPoolOrder(supplierId: string, uids: string[]): void;
     setPoolStrategy(supplierId: string, strategy: string): void;
+    /**
+     * 读缓存的积分。没缓存过返回 `CREDITS_UNKNOWN`(-1),让调用方自己决定
+     * 显示什么——不要把 -1 当 0 展示。
+     */
+    getCredits(supplierId: string, uid: string): number;
+    /**
+     * 合并插件报的积分:非 -1 就写入并返回它;-1(未知)则回落到上次缓存值。
+     * @returns 面板该显示的积分(仍可能是 -1 = 从来没拿到过)
+     */
+    putCredits(supplierId: string, uid: string, reported: number): number;
+    /** 删除链接时清掉它的积分缓存(不写盘:下一行 removeLink 会带出保存)。 */
+    clearCredits(supplierId: string, uid: string): void;
     private load;
     private saveLocked;
 }