dsh-router-core 0.3.2 → 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 榜、最近请求。 |
@@ -71,7 +71,11 @@ dsh plugin --profile web add dsh-router-core
   - Top 榜:按供应商 / 按模型(请求数带失败计数);
   - 最近请求:时间 / 模型 / 供应商 / in↑ out↓ / 耗时,显示最近 10 条;
   - **清空** — 清掉全部用量统计(不影响供应商、账号、组合配置);
-  - 数据落盘 `data/usage.json`(按天聚合 + 最近 500 条明细 + 累计计数)。
+  - 数据落盘 `data/usage.json`(按天聚合 + 每天 24 个小时桶 + 最近 500 条明细 +
+    累计计数)。今日/7 天/30 天读天桶、24 小时读小时桶,都不受明细环容量限制;
+    明细环只服务「最近请求」列表。
+    小时桶从新数据开始累积,升级前那几天的天内分布查不到(明细环只剩 500 条
+    回溯不回去),那段历史的小时柱状图留空、24 小时口径按整桶计入 —— 不编数据。
     token 口径:上游返回 `usage` 就用真值(分散在多帧时按字段取最大值合并);
     上游不发时按 ~4 字符/token 估算,面板上标 `~`。**失败请求不估算**——
     它没到上游,编造输入 token 只会把总量灌水;

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 次把它冷却 10 分钟,表现为「组合越用越没号可用」。所以「这个模型不属于我」
-一定要报 `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 次冷却 10 分钟 |
+| `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 文件即可,接口不用变。
 
 ### 流式一旦写出第一个字节才绑死
@@ -128,6 +147,22 @@ type ChatOnceResult =
 - 要让「上游吐到一半才断」也能回退,必须在写响应头前缓冲判定,代价是
   首字节延迟,目前没做
 
+### 终止帧 `[DONE]` 由核心兜底
+
+客户端(dsh-llm adapter)严格等 `data: [DONE]` 才认为流正常结束;缺了就抛
+`SSE payload stream ended without [DONE]`,整轮判失败——已经流式吐出去的内容
+**全部作废**。
+
+核心是 SSE 的唯一写入方,所以这个兜底由核心做,不要求 js 合成:
+
+- 上游流结束时**没发过** `[DONE]` → 核心补发一个(降级为「拿到截断内容并
+  正常收尾」,而不是整轮白干)
+- 上游**已经发了** → 不再重复发(重复 `[DONE]` 同样坑客户端)
+- **一个字节都没写出就断** → **不补**,留给换号/换模型回退(补了就把这次
+  失败坐实成一个空响应,组合回退就没了)
+
+js 因此不必自己合成终止帧(合成也不算错,核心会认)。
+
 所以 js 的流转换要**尽早产出第一个字节**,别攒着。攒着不仅延迟高,还会把
 自己的失败伪装成「可回退」,让组合以为没成功而反复重试别的模型。
 
@@ -160,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 状态,否则幂等情况会被误报成失败。
@@ -206,8 +253,8 @@ RPC 失败,表现为「历史加载失败」。
 
 面板链接池的「刷新」按钮是核心的活,js 不用做任何事:
 
-1. **积分**:核心连着调 `status()` 等它落地;`status().accounts[].credits`
-   该缓存就缓存,不该缓存就现拉,核心只认这个字段
+1. **积分**:核心连着调 `status()` 等它落地(最多 3s),只认
+   `status().accounts[].credits` 这一个字段,并统一持久化
 2. **健康**:核心拿一个启用模型跑一次最简会话(复用「测试模型」的 `chatOnce`
    路径),回答「这个供应商还有没有活着的链接」——**不按链接细分**
 
@@ -223,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' }] }
@@ -262,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 侧)保持实时。
@@ -294,9 +350,10 @@ export function dispose() {}
 
 ### 为什么组合要存供应商 id 而不是裸模型 id
 
-存裸 id 时,核心只能遍历所有供应商逐个试。插件用 `unavailable` 回答
-「不是我的」,而这个状态在池策略里**计一次连续错误**——组合里每有一个别人家的
-模型就给无关账号攒一次,攒够 3 次冷却 10 分钟,表现为「组合越用越没号可用」。
+存裸 id 时,核心只能遍历所有供应商逐个试。插件用 `unavailable` 回答「不是我的」,
+而这个状态在池策略里会把**这个号 × 这个模型**冷掉——组合里每有一个别人家的
+模型,每个账号在那模型上就都被冷一次,表现为「组合越用越没号可用」。
+(`no_such_model` 是为此专门加的状态:它不冷任何东西。)
 
 存了供应商 id 就不需要问了:直接调那一个。查不到供应商(拼错/供应商没加载)
 直接失败,**不兜底遍历**——兜底会让拼错的 id 静默落到别的供应商上,更难查。

package/lib/client-registry.js

@@ -243,16 +243,21 @@ window.__ModuleLoader__.load({
 						cache: "no-store"
 					})).json();
 					if (data.ok && data.total > 0) {
-						const failed = (data.results ?? []).filter((r) => r.status !== "ok" && r.status !== "already");
 						let msg = `签到完成：${data.succeeded}/${data.total} 成功`;
 						const already = data.already ?? 0;
 						if (already > 0) msg += ` · ${already} 今日已签`;
-						if (failed.length > 0) {
-							const first = failed[0];
-							msg += ` · ${first?.message ?? "有失败"}`;
-						}
 						showToast(msg);
-					} else showToast(data.error ?? (data.total === 0 ? "没有可签到的链接" : "签到失败"));
+					} else {
+						const firstFail = (data.results ?? []).find((r) => r.status !== "ok" && r.status !== "already");
+						const reason = firstFail ? `${firstFail.message ?? "有链接签到失败"}` : "";
+						const already = data.already ?? 0;
+						const head = data.total > 0 ? `签到未完成：${data.succeeded}/${data.total} 成功` : "没有可签到的链接";
+						showToast(data.error ?? [
+							head,
+							already > 0 ? `${already} 今日已签` : "",
+							reason
+						].filter(Boolean).join(" · "));
+					}
 					onRefresh();
 				} catch (err) {
 					showToast(`签到失败：${err.message}`);
@@ -833,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",
@@ -3392,9 +3401,9 @@ window.__ModuleLoader__.load({
 									children: [supplierAccounts.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 										className: "dshr-muted",
 										children: [
-											supplierAccounts.length,
-											"/",
 											healthy,
+											"/",
+											supplierAccounts.length,
 											" 健康"
 										]
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {

package/lib/client.js

@@ -243,16 +243,21 @@ window.__ModuleLoader__.load({
 						cache: "no-store"
 					})).json();
 					if (data.ok && data.total > 0) {
-						const failed = (data.results ?? []).filter((r) => r.status !== "ok" && r.status !== "already");
 						let msg = `签到完成：${data.succeeded}/${data.total} 成功`;
 						const already = data.already ?? 0;
 						if (already > 0) msg += ` · ${already} 今日已签`;
-						if (failed.length > 0) {
-							const first = failed[0];
-							msg += ` · ${first?.message ?? "有失败"}`;
-						}
 						showToast(msg);
-					} else showToast(data.error ?? (data.total === 0 ? "没有可签到的链接" : "签到失败"));
+					} else {
+						const firstFail = (data.results ?? []).find((r) => r.status !== "ok" && r.status !== "already");
+						const reason = firstFail ? `${firstFail.message ?? "有链接签到失败"}` : "";
+						const already = data.already ?? 0;
+						const head = data.total > 0 ? `签到未完成：${data.succeeded}/${data.total} 成功` : "没有可签到的链接";
+						showToast(data.error ?? [
+							head,
+							already > 0 ? `${already} 今日已签` : "",
+							reason
+						].filter(Boolean).join(" · "));
+					}
 					onRefresh();
 				} catch (err) {
 					showToast(`签到失败：${err.message}`);
@@ -833,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",
@@ -3392,9 +3401,9 @@ window.__ModuleLoader__.load({
 									children: [supplierAccounts.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 										className: "dshr-muted",
 										children: [
-											supplierAccounts.length,
-											"/",
 											healthy,
+											"/",
+											supplierAccounts.length,
 											" 健康"
 										]
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {