dsh-router-core 0.1.0 → 0.3.0

package/README.md

@@ -17,6 +17,10 @@ OpenAI 兼容端点,把请求路由到内部供应商。装好即用,不用多
   无需改核心代码、无需重编译;
 - **模型不内置**:供应商只实现差异化能力(列模型/调上游/登录),模型拉取与
   缓存由核心统一管,不写死、不过时;
+- **策略只写一次**:组合回退、账号池(选号/冷却/禁用/连续错误累计)、响应写入、
+  凭证存储、模型管理都由核心提供。供应商 js 只对**单个账号**调一次上游并报告
+  成败,不自己遍历账号、不维护冷却表——否则每个插件都会长出一份互相不一致的
+  实现,而核心也就无从判断「该不该换号」;
 - **凭证 SQLite 单库**:`auths/credentials.sqlite`,供应商凭证不透明 blob,
   核心统一生命周期,干净可备份;
 - **复用 9router 思路**:面板布局、组合 fallback、连接池/账号池、API key
@@ -28,13 +32,37 @@ OpenAI 兼容端点,把请求路由到内部供应商。装好即用,不用多
 左侧边栏「记忆系统」上方有 **路由系统** 入口,点击打开中心栏面板:
 
 - **返回会话** — 左侧按钮,关闭面板回到聊天;
+- **概览** — 用量看板(默认页):
+  - 周期切换 **今日 / 24 小时 / 7 天 / 30 天**;
+  - 汇总卡:总请求(含成功率)、输入 Tokens、输出 Tokens、缓存 Tokens、平均耗时(含首字节);
+  - Token 趋势折线图:鼠标悬停 / 触摸点选 / 键盘 `←` `→`(`Home` `End` 到两端,`Esc` 取消)
+    看每个时段;读数和峰值用 K/M 缩写,精确值在悬停提示里;
+  - Top 榜:按供应商 / 按模型(请求数带失败计数);
+  - 最近请求:时间 / 模型 / 供应商 / in↑ out↓ / 耗时,显示最近 10 条;
+  - **清空** — 清掉全部用量统计(不影响供应商、账号、组合配置);
+  - 数据落盘 `data/usage.json`(按天聚合 + 最近 500 条明细 + 累计计数)。
+    token 口径:上游返回 `usage` 就用真值(分散在多帧时按字段取最大值合并);
+    上游不发时按 ~4 字符/token 估算,面板上标 `~`。**失败请求不估算**——
+    它没到上游,编造输入 token 只会把总量灌水;
+    缓存口径:OpenAI 系 `prompt_tokens` **含**缓存,Claude 系不含(单报
+    `cache_read_input_tokens`),归一时统一折成「prompt 含缓存」,
+    所以「缓存 Tokens」是「输入 Tokens」的**子集**,不是并列的第三种;
 - **供应商** — 供应商卡片(内置 / 插件分组),点击进入详情:
-  - **链接池** — 账号列表(冷却/禁用/健康数),支持删除;
+  - **链接池** — 账号列表(冷却/禁用/健康数/积分),支持删除;
   - **加链接** — 按供应商能力弹出不同流程:URL 登录(生成链接 → 浏览器登录 → 回调)、
     API key 弹窗(填名字 + key)、轮询登录(登录后自动取凭证);
+  - **签到** — 供应商实现了签到的才显示(如 codebuddy:每日 100 积分,连续第 7 天
+    1000)。核心遍历所有链接逐个签,汇总「N/M 成功 · X 今日已签」;上游「今日已
+    签到」按成功处理(幂等),账号额度或凭证失效会单独标出;
+  - **刷新** — 刷所有链接的积分,并跑一次最简会话探测该供应商是否还有活着的链接
+    (走真实对话路径 + 账号池回退,能分清是账号额度没了还是供应商真挂了);
   - **可用模型** — 模型列表,逐个启用/禁用 + 自定义模型(通用能力,持久化到
-    `data/supplier-config.json`,`/v1/models` 与 chat 只接受启用的模型);
-- **组合** — fallback 链(免费优先),可自定义;
+    `data/supplier-config.json`,`/v1/models` 与 chat 只接受启用的模型);单个模型可
+    「测试」,走真实对话路径并按账号池依次回退,所以能分清是这个账号额度没了还是
+    该模型真的不支持;
+- **组合** — fallback 链(免费优先),可自定义。**组合即模型**:建好的组合会**自动带出**
+  为 DSH 模型目录里的 `router` provider 选项(设置 → 模型直接选组合名即可用),请求
+  按组合策略命中其中一个供应商模型;
 - **端点与密钥** — 端点核心(无隧道/Tailscale):
   - API 端点 URL(`http://localhost:3080/v1`,可复制);
   - 鉴权设置 `requireApiKey` 开关;
@@ -71,6 +99,9 @@ curl -X POST http://localhost:3080/v1/chat/completions \
 | `/keys/toggle` | POST | `{id, isActive}` |
 | `/keys/delete` | POST | `{id}` |
 | `/settings` | GET/PATCH | `{requireApiKey}` |
+| `/stats` | GET | 用量统计 `?period=today\|24h\|7d\|30d`(汇总 + Top 榜 + 最近请求 20 条) |
+| `/stats/chart` | GET | 趋势图数据 `?period=…`(today/24h = 24 小时桶,7d/30d = 天桶) |
+| `/stats/clear` | POST | 清空全部用量统计 |
 | `/suppliers/:id/login` | POST | 生成登录链接 |
 | `/suppliers/:id/login/callback` | POST | `{callbackUrl}` → 加账号 |
 | `/suppliers/:id/models` | GET | 模型 + 启用状态 |
@@ -81,12 +112,15 @@ curl -X POST http://localhost:3080/v1/chat/completions \
 ```
 浏览器(client 半)
   └─ 侧边栏「路由系统」+ 中心栏面板(RouterView, 含返回会话按钮)
-       ├─ RouterView        tab: 供应商 / 组合 / 端点与密钥
+       ├─ StatsTab          概览:用量看板(周期切换 + 汇总卡 + 折线趋势 + Top 榜 + 最近请求)
+       ├─ RouterView        tab: 概览 / 供应商 / 组合 / 端点与密钥
        ├─ SupplierDetail    供应商详情:链接池 + 加链接 + 可用模型
        ├─ EndpointTab       端点 URL + requireApiKey + 密钥管理
        └─ fetch /router/api/*            (同源,无 CORS)
             └─ host 半(src/index.ts)
                  ├─ /v1/models + /v1/chat/completions   (OpenAI 兼容, KeysStore 鉴权)
+                 │    └─ RouterAdapter(src/llm/adapter.ts)  OpenAI SSE → DSH StreamChunk
+                 │         (usage 经 toTokenUsage 转 DSH 契约,见 docs/suppliers.md)
                  ├─ KeysStore(src/keys.ts)              密钥库 + requireApiKey
                  └─ Router(路由器) → suppliers[]
                       ├─ OpenCodeSupplier(lib/suppliers/opencode.js) 无账号免费直连
@@ -95,9 +129,10 @@ curl -X POST http://localhost:3080/v1/chat/completions \
                       └─ 外部插件供应商(经 router.suppliers service 注册)
 ```
 
-- **供应商抽象**:可插拔 js 模块只提供**差异化能力**(`status/listModels/getAlias/chatCompletions`
-  + 可选登录/签到/测模型);**通用能力**(连接池排序/策略、模型启用/自定义、别名、凭证)
-  由核心统一管。
+- **供应商抽象**:可插拔 js 模块只提供**差异化能力**(`status/listModels/getAlias/chatOnce`
+  + 可选登录/签到/加 key);**策略与通用能力**(组合回退、账号池选号/冷却/禁用、
+  连接池排序、模型启用/自定义、别名、凭证、响应写入)由核心统一管。
+  `chatOnce(uid, req)` 一次只服务一个账号,返回成功/失败 + 语义状态,换号由核心决定。
 - **供应商加载**(三来源,见 [`docs/suppliers.md`](docs/suppliers.md)):
   1. 内置:`lib/suppliers/*.js`(随插件分发,如 opencode)
   2. 用户:`~/.dsh/profiles/web/suppliers/*.js`
@@ -127,14 +162,24 @@ pnpm build        # lib/index.js(host) + lib/client.js / lib/client-registry.js(
 pnpm typecheck
 ```
 
-## 挂载
+## 安装(DSH)
 
-1. `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 加 `"dsh-router"`,
-   `dependencies` 加 `"dsh-router-core": "link:/Users/carvin/Desktop/dsh-plugins/dsh-router"`;
-2. `cd ~/.dsh/profiles/web && pnpm install`;
-3. 重启 `dsh web`。
+用 dsh CLI 装到 profile(web 是 DSH 插件宿主):
 
-> 发布版:`npm i dsh-router-core`(见 [npm](https://www.npmjs.com/package/dsh-router-core))。
+```bash
+dsh plugin --profile web add dsh-router-core
+```
+
+该命令会在 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"` 指向本地仓库。
 
 ## 前提