dsh-router-core 0.3.1 → 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CARVIN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,18 @@
-# dsh-router
+<h1 align="center">dsh-router</h1>
+
+<p align="center">DeepSeek Harness 的 OpenAI 兼容路由插件</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-router-core"><img src="https://img.shields.io/npm/v/dsh-router-core?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10b981?style=flat-square" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#快速安装">快速安装</a> ·
+  <a href="#面板设置--路由">面板</a> ·
+  <a href="#api-端点openai-兼容3080v1">API 端点</a> ·
+  <a href="docs/suppliers.md">供应商开发</a>
+</p>
 
 **插件版的 9router** —— 不是另开一个网关服务,而是直接作为 DSH 插件嵌进 DSH web,
 在 `http://localhost:3080/v1` 上原生暴露 OpenAI 兼容端点,把请求路由到内部供应商。
@@ -7,30 +21,44 @@
 
 ![设置 → 路由 面板：概览（用量看板）、供应商、组合、端点与密钥](docs/screenshot.png)
 
-## 为什么更优雅
-
-- **零额外进程**:dsh-router 就是 DSH 插件,随 `dsh web` 启停,天然同源
-  (`/router/api/*` 无 CORS、面板嵌在设置里),不像 9router 要独立跑一个
-  Next.js 服务再对接;
-- **供应商即插即拔**:内置供应商(如 opencode / openrouter / nvidia)随插件分发;
-  更多供应商 = 装一个 DSH 插件(`dsh-router-*`)经 cordis service
-  `router.suppliers` 注册,面板自动出现、热加载/卸载;也可以放一个自定义
-  js 文件到 `~/.dsh/profiles/web/suppliers/` 就注册一个新供应商——
-  无需改核心代码、无需重编译;
-- **模型不内置**:供应商只实现差异化能力(列模型/调上游/登录),模型拉取与
-  缓存由核心统一管,不写死、不过时;
-- **策略只写一次**:组合回退、账号池(选号/冷却/禁用/连续错误累计)、响应写入、
-  凭证存储、模型管理都由核心提供。供应商 js 只对**单个账号**调一次上游并报告
-  成败,不自己遍历账号、不维护冷却表——否则每个插件都会长出一份互相不一致的
-  实现,而核心也就无从判断「该不该换号」;
-- **凭证 SQLite 单库**:`auths/credentials.sqlite`,供应商凭证不透明 blob,
-  核心统一生命周期,干净可备份;
-- **复用 9router 思路**:面板布局、组合 fallback、连接池/账号池、API key
-  管理都贴近 9router,但按 DSH「一切皆插件」的方式重组得更轻。
+## 快速安装
+
+需要支持 `dsh plugin` profile 插件机制的 DeepSeek Harness、Node.js `>= 20`,以及 `web` profile。
+
+```bash
+dsh plugin --profile web add dsh-router-core
+```
+
+然后**重启 `dsh web`**。打开设置面板,左侧导航「模型」下面会出现 **路由**。
+
+> 更多供应商:DSH 插件形态的供应商各自发 npm 包,同样
+> `dsh plugin --profile web add <包名>` 即可;供应商接入与开发见
+> [`docs/suppliers.md`](docs/suppliers.md)。
+>
+> 本地开发版:不用 npm,直接 `dependencies` 加
+> `"dsh-router-core": "link:/path/to/dsh-router"` 指向本地仓库。
 
+## 它解决什么问题
+
+| 能力 | 说明 |
+|---|---|
+| 零额外进程 | 就是 DSH 插件,随 `dsh web` 启停,天然同源(`/router/api/*` 无 CORS、面板嵌在设置里)。 |
+| 供应商即插即拔 | 内置供应商随插件分发;更多供应商 = 装一个 DSH 插件(`dsh-router-*`)或放一个 js 文件到 `~/.dsh/profiles/web/suppliers/`。 |
+| 模型不内置 | 供应商只实现差异化能力,模型拉取与缓存由核心统一管,不写死、不过时。 |
+| 策略只写一次 | 组合回退、账号池(选号/冷却/禁用/连续错误累计)、响应写入、凭证存储、模型管理都由核心提供。供应商 js 只对**单个账号**调一次上游并报告成败,不自己遍历账号、不维护冷却表——否则每个插件都会长出一份互相不一致的实现,而核心也就无从判断「该不该换号」。 |
+| 凭证单库 | `auths/credentials.sqlite`,供应商凭证不透明 blob,核心统一生命周期,干净可备份。 |
+| 组合即模型 | 建好的组合自动带出为 DSH 模型目录里的 `router` provider 选项,设置 → 模型直接选组合名即可。 |
+| 用量可观测 | 面板概览看板:周期切换、汇总卡、趋势折线、Top 榜、最近请求。 |
+
+> 面板布局、组合 fallback、连接池/账号池、API key 管理都贴近
+> [9router](https://github.com/decolua/9router),但按 DSH「一切皆插件」的方式
+> 重组得更轻。
+>
 > 供应商开发与接入规范见 [`docs/suppliers.md`](docs/suppliers.md)
 > （契约 / 加载顺序 / 模型统一策略 / 内置供应商参考实现）。
 
+## 面板(设置 → 路由)
+
 面板挂在 **设置 → 路由**(官方 `settings.section` 座位,排在「模型」下面):
 
 - **概览** — 用量看板(默认页):
@@ -43,7 +71,11 @@
   - Top 榜:按供应商 / 按模型(请求数带失败计数);
   - 最近请求:时间 / 模型 / 供应商 / in↑ out↓ / 耗时,显示最近 10 条;
   - **清空** — 清掉全部用量统计(不影响供应商、账号、组合配置);
-  - 数据落盘 `data/usage.json`(按天聚合 + 最近 500 条明细 + 累计计数)。
+  - 数据落盘 `data/usage.json`(按天聚合 + 每天 24 个小时桶 + 最近 500 条明细 +
+    累计计数)。今日/7 天/30 天读天桶、24 小时读小时桶,都不受明细环容量限制;
+    明细环只服务「最近请求」列表。
+    小时桶从新数据开始累积,升级前那几天的天内分布查不到(明细环只剩 500 条
+    回溯不回去),那段历史的小时柱状图留空、24 小时口径按整桶计入 —— 不编数据。
     token 口径:上游返回 `usage` 就用真值(分散在多帧时按字段取最大值合并);
     上游不发时按 ~4 字符/token 估算,面板上标 `~`。**失败请求不估算**——
     它没到上游,编造输入 token 只会把总量灌水;
@@ -162,32 +194,14 @@ curl -X POST http://localhost:3080/v1/chat/completions \
 | `TW2A_STATE_FILE` | `data/state.json` | 状态持久化(同目录放 keys.json / combos.json / supplier-config.json) |
 | `TW2A_API_KEY` | 空 | /v1 Bearer 鉴权(与库内 key 等效) |
 
-## 构建
-
-```bash
-pnpm install
-pnpm build        # lib/index.js(host) + lib/client.js / lib/client-registry.js(browser)
-pnpm typecheck
-```
-
-## 安装(DSH)
-
-用 dsh CLI 装到 profile(web 是 DSH 插件宿主):
-
-```bash
-dsh plugin --profile web add dsh-router-core
-```
+## 与 DSH 的边界
 
-该命令会在 profile 里 `pnpm add`,并自动把 `dsh-router-core` 加入
-`dsh.profile.bundles`(包声明了 `dsh.bundle.patch`,即 `cordis.patch.yml`)。
-
-然后**重启 `dsh web`**。打开设置面板,左侧导航「模型」下面会出现 **路由**。
-
-> 更多供应商:DSH 插件形态的供应商各自发 npm 包,同样 `dsh plugin --profile web add <包名>`
-> 即可;供应商接入与开发见 [`docs/suppliers.md`](docs/suppliers.md)。
->
-> 本地开发版:不用 npm,直接 `dependencies` 加
-> `"dsh-router-core": "link:/path/to/dsh-router"` 指向本地仓库。
+- dsh-router 复用 DSH 的 Web Server 与设置面板座位,不启动第二个应用或代理系统。
+- 供应商 js 不改 DSH 的 prompt、工具 schema 或权限;它只负责「把上游协议翻译成
+  OpenAI 形态」,路由/回退/存储归核心。
+- 数据分两处:`data/` 下的状态与用量 JSON(删了只是没统计了),以及
+  `auths/credentials.sqlite`(删了要重新登录所有供应商)。
+- 内置 patch 仅支持 DSH 的 `web` profile。
 
 ## 前提
 
@@ -195,6 +209,18 @@ dsh plugin --profile web add dsh-router-core
 - 供应商接入与开发见 [`docs/suppliers.md`](docs/suppliers.md);
 - 重启 DSH 后 `/v1/*` 即生效;面板管理账号、模型与密钥。
 
+## 开发
+
+```bash
+pnpm install
+pnpm build        # lib/index.js(host) + lib/client.js / lib/client-registry.js(browser)
+pnpm typecheck
+pnpm test         # node --test "src/**/*.test.ts"
+```
+
+需要一个供应商最小实现作参考时,看 [`examples/suppliers/echo.js`](examples/suppliers/echo.js);
+完整契约、加载顺序与模型策略见 [`docs/suppliers.md`](docs/suppliers.md)。
+
 ## 致谢
 
 感谢以下项目给的灵感:
@@ -202,3 +228,7 @@ dsh plugin --profile web add dsh-router-core
 - [decolua/9router](https://github.com/decolua/9router) —— 本地 AI 路由网关,面板/组合/连接池/凭证等思路的来源;
 - [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) —— DSH「一切皆插件」的宿主框架;
 - [omdsh-dev/dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) —— DSH 插件形态与侧边栏入口的参考。
+
+## 许可证
+
+[MIT](LICENSE)

package/docs/suppliers.md

@@ -76,7 +76,7 @@ js 报告**此刻**观察到的账户状况,而不是把上游原始响应丢给
 
 **`no_such_model` 是必须的,不能拿 `unavailable` 顶替。** 后者在核心策略里
 会计一次连续错误——组合里每有一个别人家的模型,就会给无关账号攒一次错误,
-攒够 3 次把它冷却 10 分钟,表现为「组合越用越没号可用」。所以「这个模型不属于我」
+攒够 3 次把它冷却 5 分钟,表现为「组合越用越没号可用」。所以「这个模型不属于我」
 一定要报 `no_such_model`,核心才知道该换供应商而不是换账号。
 
 **js 只说「现在怎么了」,不说「该怎么办」。** 冷却多久、是否禁用、要不要换号
@@ -108,7 +108,7 @@ type ChatOnceResult =
 | `rate_limit` | 冷却 1 分钟 |
 | `quota` | 冷却 10 分钟 |
 | `session_dead` | **永久禁用**(需重新登录才能恢复) |
-| `unavailable` / `transport` / `unknown` | 计一次连续错误,攒够 3 次冷却 10 分钟 |
+| `unavailable` / `transport` / `unknown` | 计一次连续错误,攒够 3 次冷却 5 分钟 |
 | `no_such_model` | **不惩罚账号**,核心直接跳过整个供应商换下一个 |
 
 - 非流式若聚合后发现**空响应**(无 content / reasoning / tool_calls),请返回
@@ -128,6 +128,22 @@ type ChatOnceResult =
 - 要让「上游吐到一半才断」也能回退,必须在写响应头前缓冲判定,代价是
   首字节延迟,目前没做
 
+### 终止帧 `[DONE]` 由核心兜底
+
+客户端(dsh-llm adapter)严格等 `data: [DONE]` 才认为流正常结束;缺了就抛
+`SSE payload stream ended without [DONE]`,整轮判失败——已经流式吐出去的内容
+**全部作废**。
+
+核心是 SSE 的唯一写入方,所以这个兜底由核心做,不要求 js 合成:
+
+- 上游流结束时**没发过** `[DONE]` → 核心补发一个(降级为「拿到截断内容并
+  正常收尾」,而不是整轮白干)
+- 上游**已经发了** → 不再重复发(重复 `[DONE]` 同样坑客户端)
+- **一个字节都没写出就断** → **不补**,留给换号/换模型回退(补了就把这次
+  失败坐实成一个空响应,组合回退就没了)
+
+js 因此不必自己合成终止帧(合成也不算错,核心会认)。
+
 所以 js 的流转换要**尽早产出第一个字节**,别攒着。攒着不仅延迟高,还会把
 自己的失败伪装成「可回退」,让组合以为没成功而反复重试别的模型。
 
@@ -296,7 +312,7 @@ export function dispose() {}
 
 存裸 id 时,核心只能遍历所有供应商逐个试。插件用 `unavailable` 回答
 「不是我的」,而这个状态在池策略里**计一次连续错误**——组合里每有一个别人家的
-模型就给无关账号攒一次,攒够 3 次冷却 10 分钟,表现为「组合越用越没号可用」。
+模型就给无关账号攒一次,攒够 3 次冷却 5 分钟,表现为「组合越用越没号可用」。
 
 存了供应商 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}`);
@@ -607,7 +612,10 @@ window.__ModuleLoader__.load({
 									children: supplier.icon !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
 										className: "dshr-providerImg",
 										src: supplier.icon,
-										alt: ""
+										alt: "",
+										onError: (e) => {
+											e.currentTarget.style.display = "none";
+										}
 									}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Icon$4, {
 										d: I$4.link,
 										size: 22
@@ -3376,7 +3384,10 @@ window.__ModuleLoader__.load({
 									children: [supplier.icon !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
 										className: "dshr-supplierIcon",
 										src: supplier.icon,
-										alt: ""
+										alt: "",
+										onError: (e) => {
+											e.currentTarget.style.display = "none";
+										}
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 										className: "dshr-supplierName",
 										children: supplier.name
@@ -3386,9 +3397,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}`);
@@ -607,7 +612,10 @@ window.__ModuleLoader__.load({
 									children: supplier.icon !== void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
 										className: "dshr-providerImg",
 										src: supplier.icon,
-										alt: ""
+										alt: "",
+										onError: (e) => {
+											e.currentTarget.style.display = "none";
+										}
 									}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Icon$4, {
 										d: I$4.link,
 										size: 22
@@ -3376,7 +3384,10 @@ window.__ModuleLoader__.load({
 									children: [supplier.icon !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
 										className: "dshr-supplierIcon",
 										src: supplier.icon,
-										alt: ""
+										alt: "",
+										onError: (e) => {
+											e.currentTarget.style.display = "none";
+										}
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 										className: "dshr-supplierName",
 										children: supplier.name
@@ -3386,9 +3397,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", {