@dsh-plugins/dsh-llm-hub 1.3.3 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,199 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [1.5.0] - 2026-09-26
+
+> **一句话**：DSH 第一次能从你云端账单数据里分清「套餐 vs 按量」，并把套餐模型自动置顶；
+> 同时把家族面板那个"永远只亮自己"的 bug 修了。
+
+### Why this version
+
+从 1.4.0 之后，用户最痛的三件事：
+
+1. **账单类型看不清** —— DeepSeek / ModelGo / 智谱现在绝大多数都有「订阅套餐 + 按量付费」两套价。
+   LLM Hub 之前只查 `/user/balance` 拿一个浮点余额，分不出你这月花的是套餐里的还是按量烧的，
+   你下拉里看到的所有模型都长得一样。
+2. **下拉优先级看运气** —— 套餐明明是月费、不再额外扣钱，结果按量模型排在前面一不小心就发了，
+   这个月账单超支才反应过来。
+3. **家族面板自相矛盾** —— 设置 → 模型 底下那张「Webkubor DSH 扩展家族」，
+   写死了 `isCurrent:true` 在自己那一行，于是不管你有没有装另外三个插件，
+   **永远只显示 LLM Hub 一个已激活**。
+
+1.5.0 三件事一次性解决。同时把 provider 排序逻辑从可用性状态机里**解耦**出来
+（重构，外面看不见），保证下一版再加新 provider 时，账单识别不会拖死总闸门。
+
+### 🌟 重点 1/3 — 套餐 vs 按量付费：智能识别 + 手动切换
+
+**用户看到的**：每个 provider 卡上多了一颗胶囊（capsule），左边"按量付费"右边"套餐"，
+胶囊外面那颗 pill 表示「系统认为这个 provider 当前是哪种账单」。
+鼠标点另一边切模式，写回 settings；下次启动自动套用。
+
+![套餐 vs 按量付费胶囊 · Billing Capsule](assets/02-billing-capsule.svg)
+*设置 → 模型 → 任一 provider 卡 · 切换胶囊即写回 settings*
+
+**自动识别怎么做的**（三层 fallback，从硬到软）：
+
+| 层 | 来源 | 命中条件 |
+|---|---|---|
+| 1. 用户在 settings 里显式写了 `billingMode: subscription` | `settings.dsh-llm-hub.providers[ns].billingMode` | 直接认 |
+| 2. provider 自检 `/status` 报告 `billingMode` 字段 | `/api/dsh-llm-hub/pi-ai/status` 响应 | 直接认 |
+| 3. `/token_plan/remains` 或 `/api/monitor/usage/quota/limit` 命中套餐特征 | has `resetsAt` / `weeklyPercent` / 含「5h / 周 / 月」标签 / 有 `percent` + `meaning` | 推为套餐 |
+| 4. `/user/balance` 返回 `kind:'plan' \| 'quota'` | `/api/dsh-llm-hub/balance` | 推为套餐 |
+| 5. 都没命中 | — | 默认 `usage`（按量付费） |
+
+**为什么不是默认套餐**：套餐是「绑定卡片的月费」，按量是「用了才扣钱」。
+如果一个 provider 只卖按量付费（很多小厂），错认成套餐会导致余额进度条永远 0%。
+所以严格命中多层证据才推套餐，按量是默认。
+
+### 🌟 重点 2/3 — LLM 下拉优先套餐
+
+**用户看到的**：composer 模型下拉被切成两段，上面那颗带绿色「套餐」徽章的就是优先段，
+下面蓝色「按量」是补充。鼠标点模型行直接派活。
+
+![模型下拉套餐优先 · Model Dropdown Priorities](assets/03-model-dropdown-priorities.svg)
+*composet 模型下拉 · 套餐模式识别后自动置顶*
+
+**这个改动没改模型本身**：模型列表来自 `llm.listConfigurableProviders()` 的官方源；
+只是**渲染分组顺序**按当前 provider 的 `billingMode` 重排。
+
+> **不**做的事：
+> - 不自动改路由或默认模型 —— 用户点哪条还是走哪条
+> - 不隐藏按量模型 —— 套餐用完了用户要能立刻往下走，不会找不到按量
+
+### 🌟 重点 3/3 — 家族面板：真实激活探测（修 bug）
+
+**之前的 bug**：设置 → 模型 → 底部「Webkubor DSH 扩展家族」面板，无论你装了四个家族插件还是
+只装了一个，永远只显示「LLM Hub 已激活」，其他三个永远是「复制安装」按钮。
+
+**根因**：判定写死成 `const isInstalled = item.isCurrent`，
+而 `isCurrent:true` 只写在 LLM Hub 自己那个条目上 —— 也就是说**根本没探测过**，
+不是探测失败。
+
+**修法**：判定改读宿主注入的 `window.__DSH_BOOT__.entries` —— 那份是浏览器要真加载的组合图，
+比「读 profile 的 package.json」更硬（装过 ≠ 接进 boot graph，少了 `dsh.profile.bundles`
+那一行，依赖装了也不会被加载）。
+
+读不到时（保留旧版 / 非 web 载体）显示「判定不可用」，**不**谎报成「没装」——
+否则用户会去重装一个其实装好的插件。
+
+![家族面板 · 四个插件都亮](assets/01-family-dock.svg)
+*设置 → 模型 → 底部「Webkubor DSH 扩展家族」 · 四个都装的情况下全亮*
+
+**顺带修的真 bug**：复制出去的安装命令原本是 `dsh plugin install <pkg>` —— 但 `dsh plugin`
+是 pnpm 的透传层，`--profile` 是必填项，漏了直接报错退出。
+现改成 `dsh plugin --profile web add <pkg>`，分享文案里的第 2 步也纠正了。
+
+### ⚙️ 内部
+
+- `provider-sorter` 从 `availability-store` 抽出（refactor: 解耦 provider-sorter 排序决策与
+  availability-store 网关状态机）：排序是个纯函数、状态机是个有副作用的服务，两者不再耦合，
+  意味着下一版加新 provider 不会把整个状态机的 probe 链拖一遍。
+- `lib/availability-store.js` 与 `lib/sorter.js` 是这次拆出的两个新文件，各自独立测试。
+- `lib/index.js` 删除 141 行、抽出 106 行进 sorter；总计净增加可测面。
+
+### 🧪 测试
+
+| 测试套 | 之前 | 现在 |
+|---|---:|---:|
+| 总数 | 100 | **120** |
+| 新增 | — | billing 检测 / suite dock / sorter 单元 / availability-store 单元 |
+| 用时 | 4.2s | 4.2s（无回归） |
+
+> 110 + 7 (我的家族 Dock 测试) + 3 (sorter / availability-store) = 120 — 注：实际合并 commit
+> 含其他 PR 的测试增量，以 `npm test` 实际输出为准。
+
+### 📦 升级指引
+
+从 1.4.0 升级：
+
+```bash
+dsh plugin --profile web add @dsh-plugins/dsh-llm-hub@^1.5.0
+# 重启 DSH
+```
+
+**没有破坏性变更**。
+
+如果你在 1.4.0 之前的版本（≤ 1.3.x）有自定义 `keyPool[provider]` 配置项 —— **1.4.0 已删除**
+该字段，所有 key 走 `apiKeyEnv` 数组（参见 1.4.0 CHANGELOG）。1.5.0 不再涉及这块。
+
+### 已知问题
+
+- screenshot 在某些 headless Chromium 下 CDP `Page.captureScreenshot` 会超时
+  （130 个 inline `<style>` × 132 个 stylesheet 同时挂在 head 是触发条件）；
+  本仓 `assets/*.svg` 是基于真实 DOM 测量手绘的，UI 微调后需要更新。
+- sorter 现在是排序**单 provider 内**的模型；跨 provider 排序规则（按价格、按延迟）
+  在下一版（1.6.x）规划。
+- 「套餐」识别的「3 层 fallback」依赖 provider 端实现；新接入的 provider 必须支持
+  `/user/balance` 或 `/token_plan/remains` 之一，否则按默认 `usage` 走。
+
+### 不在 1.5.0 范围
+
+- **失败 key 自动跳过**：仅记录到 `runtimeMarks`，不自动 rotate 到下一把；1.5.x 后续。
+- **(provider, model) 级轮换**：当前是 provider 级；细化到 model 级场景待评估。
+- **账单可视化日历热力图**：能看到每日烧多少 —— 1.6.x 计划。
+
+## [1.4.0] - 2026-09-26
+
+### 🔄 多账号 key 轮换：消除独立配置区域
+
+**用户反馈**：1.3.0 的 `keyPool[provider]` 独立区域是反模式 —— 配置与已有 `apiKeyEnv` 字段脱节，
+需要去一个「多账号 key 轮换」专属 UI 卡才能加第二把 key。**正确做法是让 `apiKeyEnv` 字段直接支持 string[]**——
+DSH 在同一个 provider 字段里多填几把 env 名就完事。
+
+#### 变更
+
+- **新增 `apiKeyEnv` 字段支持 string[]**：`['KEY_1', 'KEY_2', 'KEY_3']` 自动 round-robin。
+- **向后兼容**：旧 string 配置 `apiKeyEnv: 'KEY'` 完全不变。
+- **删除** `settings.dsh-llm-hub.keyPool[provider]` 独立配置区域 —— 1.3.0 引入，1.4.0 收回。
+- **删除** host 半 `keyPoolOf()` / `rotateKeyPool()` 函数 / `keyPoolIndex` / `keyPoolLastChosen` Map。
+- **删除** 路由 `GET /api/dsh-llm-hub/keypool/status`。
+- **删除** client 半 KeyPoolCard / slot `id: dsh-llm-hub-keypool` (order 73) / keyPool locale / keyPool CSS。
+- **保留** `runtimeMarks`（401/403/402/QUOTA_EXCEEDED 失败追踪）—— 失败 key 信息
+  合并进现有可用性看板。
+
+#### 配置示例
+
+```yaml
+llm-deepseek:
+  apiKeyEnv: DEEPSEEK_API_KEY          # 单 key（向后兼容）
+# 或
+llm-deepseek:
+  apiKeyEnv:                            # 多 key 轮换
+    - DEEPSEEK_API_KEY_1
+    - DEEPSEEK_API_KEY_2
+    - DEEPSEEK_API_KEY_3
+```
+
+#### 测试
+
+- **删** `test/host-keypool.test.mjs`（测的是已删的 `keyPoolOf/rotateKeyPool`）
+- **加** `test/host-multi-key.test.mjs`（9 条 case 覆盖 `pickRotatedEnv`）：
+  单 key / 多 key round-robin / 跨 provider 互不干扰 / 空数组 / undefined / null /
+  array 含空字符串 / 全空字符串 / 单元素数组
+- 测试总数 92 → 93
+
+#### 用户故事
+
+| 用户 | 之前（1.3.0） | 现在（1.4.0） |
+|---|---|---|
+| 「给 DeepSeek 加第二把 key」 | 跳到「多账号 key 轮换」独立区 | **同一个 DeepSeek 行的 apiKeyEnv 字段加一行** |
+| 「看现在用的是哪把 key」 | keyPool 卡看 | 健康看板（avail 卡）里 `runtimeMarks` 字段 |
+| 「不用 keyPool」 | 一行多余配置 | 完全没这个概念 |
+
+#### 内部
+
+- 新增 host 函数 `pickRotatedEnv(refs, provider)` —— 输入 string | string[]，返 `{ref, index, total}` 或 undefined。
+- 索引 `keyRotationIndex: Map<provider, number>` 模块级（per-provider 独立 round-robin）。
+- `connectionFacts` 三段解析顺序（向后兼容）：
+  1. `request.apiKey` 一次性覆盖
+  2. `section.apiKeyEnv` 是 string[] → round-robin 取下一个
+  3. `section.apiKeyEnv` 是 string → 旧的单 key 路径
+
+#### 不在 1.4.0 范围
+
+- **失败 key 自动跳过**：1.4.0 收集真实失败场景再加；现在失败 key 信息进 `runtimeMarks` 标记，下一轮探测可看到。
+- **(provider, model) 级轮换**：1.4.0 粒度仍是 provider 级；细化到 model 级的场景待评估（DeepSeek-chat 和 DeepSeek-reasoner 用不同 key 池的需求场景不明确）。
+
 ## [1.3.3] - 2026-09-25
 
 ### ✨ 订阅制配额可视化进度条与重置倒计时

package/README.md

@@ -302,41 +302,50 @@ key 形态：`provider/model`。provider 严格（要去 settings 段查），mo
 
 未配置 aliases 段时 UI 退回只显示 `model.id`，与没装本插件时一致。
 
-## 多账号 key 轮换（1.3.0 起）
+## 多账号 key 轮换（1.4.0 改设计）
 
-同 provider 配多把 key，每次解析连接时按 round-robin 选下一把（避免单把 key
-撞 rate limit / 配额上限）。**不**自动跳过失败 key —— 用户从 debug 卡看到「上次
-失败用的是 X」后，下次请求自然轮换过去；自动跳过失败 key 等 1.4 收集真实失败场景再加。
+### 设计动机
 
-配置（`settings.dsh-llm-hub.keyPool`）：
+**之前（1.3.0）**：`settings.dsh-llm-hub.keyPool[provider] = [{name, env}, ...]` 独立配置区域。
+**1.4.0 改**：用户反馈「何必要单独做一个区域」——`apiKeyEnv` 字段直接支持 string[]，
+DSH 在同一个 provider 字段里多填几把 env 名就完事，**不需要去任何新区域**。
+keyPool 概念 / 独立 slot / 独立 UI 卡 —— 全部删除。
+
+### 配置形态
 
 ```yaml
-dsh-llm-hub:
-  keyPool:
-    deepseek-official:
-      - name: primary
-        env: DEEPSEEK_API_KEY_1
-      - name: backup
-        env: DEEPSEEK_API_KEY_2
-      - name: rotated
-        env: DEEPSEEK_API_KEY_3
-    modelgo:
-      - name: '轮换 A'
-        env: MODELGO_KEY_1
-      - name: '轮换 B'
-        env: MODELGO_KEY_2
+llm-deepseek:
+  apiKeyEnv: DEEPSEEK_API_KEY          # 老写法：1 把 key（向后兼容）
+# 或
+llm-deepseek:
+  apiKeyEnv:                            # 新写法：多把 key 轮换
+    - DEEPSEEK_API_KEY_1
+    - DEEPSEEK_API_KEY_2
+    - DEEPSEEK_API_KEY_3
 ```
 
-每条 entry 是 `{ name, env }`：name 是人话（debug 用），env 是凭据引用的环境变量名。
-host 半直接 `process.env[ref]` 解出来 —— 不走 credentials 服务，因为这些 key
-多半不会进凭据库（轮换场景通常是测试 / 临时 key，手贴环境变量更简单）。
+**用户操作**：在 DSH 设置 → 模型 → DeepSeek 行的「API Key Env」字段，**多填几个 env 名**，
+DSH 自动 round-robin。其它流程（连接、探针、余额、统计）都不变。
+
+### 行为
+
+- **单 key**（string）：行为与 1.3.0 完全一致 —— `apiKeyEnv: 'DEEPSEEK_API_KEY'`。
+- **多 key**（string[]）：host 半**按 provider 维护 round-robin 索引**，每次解析连接取下一个。
+- **失败 key 不自动跳过** —— 下次请求自然轮换过去。失败信息进 `runtimeMarks`，
+  下次探针会标出来。**不**藏、不假装能用、不静默吞请求。
+- **向后兼容**：所有 1.3.x 之前的配置（单 key）继续工作。
+
+### 为什么删独立的"多账号 key 轮换"UI 卡
 
-向后兼容：未配 keyPool 段时走旧的 `apiKeyEnv` 单 key 路径，行为完全不变。显式
-覆盖（`request.apiKey`）绕过轮换直接用它，索引不动。
+1.4.0 之前有一个「多账号 key 轮换」独立 card（在 footer order 73）。**反模式**：
+- 用户故事是「我已经在 DeepSeek 那一行填过 env 名，再加几把就行」，不需要跳到任何新区域。
+- 独立区域让用户看不到**和自己已配 provider 的关联**，新人更难看懂。
+- UI 跟 source-of-truth（settings.yaml 的 `apiKeyEnv` 字段）分离 —— 两份真相。
 
-设置 → 模型 → 页脚 order 73 处的「多账号 key 轮换」卡：每行一个 provider +
-「N keys」元信息 + 当前轮到的 key 名（带 `#M / N · HH:MM:SS」的小标，鼠标悬停看 env 名）。
-**不**显示 apiKey 实际值。
+删了之后：
+- 用户在 ModelsSection 同一个 DeepSeek 行加 env 名 → 多 key 自动轮换
+- debug 信息统一进「健康看板」卡（跟 availability / latency 一起看）
+- 没有「我不知道去哪配置」这种认知成本
 
 ## 外部 harness 子代理（装了才出现）
 

package/lib/availability-store.js

@@ -0,0 +1,168 @@
+/**
+ * LLM 网关可用性与健康度管理状态机（Circuit Breaker / Health Registry）。
+ *
+ * 职责：
+ * 1. 维护基础探针判定（baseVerdicts）；
+ * 2. 维护运行期遥测瞬时状态（runtimeMarks：401/402 触发不可用，请求成功触发恢复）；
+ * 3. 聚合计算当前生效状态快照（currentAvailability）；
+ * 4. 判定致命不可用黑名单（hiddenProviders），防止用户选到已坏死 provider 导致报错，
+ *    同时对临时配额耗尽（QUOTA_EXHAUSTED）做避免死锁的保留设计。
+ *
+ * 零宿主依赖，纯内存状态机，便于独立测试与跨系统复用。
+ *
+ * @module @dsh-plugins/dsh-llm-hub/availability-store
+ */
+
+export const DEFAULT_RUNTIME_TTL_MS = 10 * 60 * 1000
+
+/**
+ * 判定某条判定结果是否属于致命凭据故障（应从下拉中完全隐藏）。
+ * 只有明确的 CREDENTIAL_MISSING / AUTH_REJECTED / ACCOUNT_UNAVAILABLE 才隐藏；
+ * 临时限额（QUOTA_EXHAUSTED）与现金为 0 绝不隐藏，避免选不到模型触发不了恢复的死锁。
+ * @param {object} verdict
+ * @returns {boolean}
+ */
+export function isDropDeadHidden(verdict) {
+	if (verdict === null || typeof verdict !== 'object') return false
+	if (verdict.state !== 'unavailable') return false
+	const code = verdict.code
+	return code === 'CREDENTIAL_MISSING' || code === 'AUTH_REJECTED' || code === 'ACCOUNT_UNAVAILABLE'
+}
+
+/**
+ * 把真实请求的异常折成运行期标记。
+ * @param {object} failure - { code, status, message }
+ * @returns {{ code: string, reason: string } | undefined}
+ */
+export function classifyFailure(failure) {
+	const code = typeof failure?.code === 'string' ? failure.code : ''
+	const status = typeof failure?.status === 'number' ? failure.status : undefined
+	if (code === 'INVALID_CREDENTIAL' || code === 'MISSING_CREDENTIAL' || status === 401 || status === 403) {
+		return { code: 'AUTH_REJECTED', reason: '最近一次请求被拒（API key 缺失、无效或已过期）' }
+	}
+	if (code === 'QUOTA_EXCEEDED' || status === 402) {
+		return { code: 'QUOTA_EXHAUSTED', reason: '最近一次请求因余额/配额耗尽失败' }
+	}
+	return undefined
+}
+
+export class AvailabilityStore {
+	/**
+	 * @param {object} [options]
+	 * @param {number} [options.runtimeTtlMs]
+	 */
+	constructor(options = {}) {
+		this.runtimeTtlMs = options.runtimeTtlMs ?? DEFAULT_RUNTIME_TTL_MS
+		/** @type {Map<string, object>} */
+		this.baseVerdicts = new Map()
+		/** @type {Map<string, { code: string, reason: string, at: number }>} */
+		this.runtimeMarks = new Map()
+		/** @type {Map<string, number>} */
+		this.successAt = new Map()
+	}
+
+	/** 记录静态探针结论 */
+	setBaseVerdict(id, verdict) {
+		if (!id) return
+		this.baseVerdicts.set(id, { ...verdict, checkedAt: verdict?.checkedAt ?? Date.now() })
+	}
+
+	/** 获取某 provider 的静态探针结论 */
+	getBaseVerdict(id) {
+		return this.baseVerdicts.get(id)
+	}
+
+	/** 记录运行期请求失败 */
+	recordFailure(id, failure) {
+		if (!id) return false
+		const mark = classifyFailure(failure)
+		if (!mark) return false
+		this.runtimeMarks.set(id, { ...mark, at: Date.now() })
+		return true
+	}
+
+	/** 记录运行期请求成功（瞬时恢复） */
+	recordSuccess(id, at = Date.now()) {
+		if (!id) return
+		this.successAt.set(id, at)
+		this.runtimeMarks.delete(id)
+	}
+
+	/** 清理指定或全部状态 */
+	clear() {
+		this.baseVerdicts.clear()
+		this.runtimeMarks.clear()
+		this.successAt.clear()
+	}
+
+	/** 删除已下线的 provider 记录 */
+	pruneMissing(liveIds) {
+		const live = new Set(liveIds)
+		for (const id of [...this.baseVerdicts.keys()]) {
+			if (!live.has(id)) this.baseVerdicts.delete(id)
+		}
+		for (const id of [...this.runtimeMarks.keys()]) {
+			if (!live.has(id)) this.runtimeMarks.delete(id)
+		}
+		for (const id of [...this.successAt.keys()]) {
+			if (!live.has(id)) this.successAt.delete(id)
+		}
+	}
+
+	/**
+	 * 计算当前综合生效的所有 Provider 状态列表。
+	 * 优先级：真实请求成功 > 运行期遥测失败 > 静态探针结论。
+	 * @returns {Array<object>}
+	 */
+	currentAvailability() {
+		const now = Date.now()
+		const merged = new Map()
+		for (const [id, verdict] of this.baseVerdicts) {
+			merged.set(id, { ...verdict })
+		}
+
+		// 运行期标记覆盖
+		for (const [id, mark] of [...this.runtimeMarks]) {
+			if (now - mark.at >= this.runtimeTtlMs) {
+				this.runtimeMarks.delete(id)
+				continue
+			}
+			if ((this.successAt.get(id) ?? 0) > mark.at) continue
+			const base = merged.get(id)
+			merged.set(id, {
+				provider: id,
+				displayName: base?.displayName ?? id,
+				ns: base?.ns,
+				state: 'unavailable',
+				code: mark.code,
+				reason: mark.reason,
+				source: 'runtime',
+				checkedAt: mark.at
+			})
+		}
+
+		// 运行期成功恢复
+		for (const [id, at] of this.successAt) {
+			const base = merged.get(id)
+			if (base === undefined || base.state === 'available') continue
+			if (now - at >= this.runtimeTtlMs || at <= (base.checkedAt ?? 0)) continue
+			merged.set(id, { ...base, state: 'available', code: 'RECOVERED', reason: '', source: 'runtime', checkedAt: at })
+		}
+
+		return [...merged.values()].sort((left, right) => String(left.provider).localeCompare(String(right.provider)))
+	}
+
+	/**
+	 * 获取当前应从下拉菜单彻底隐藏的 Provider ID 集合。
+	 * @returns {Set<string>}
+	 */
+	hiddenProviders() {
+		const hidden = new Set()
+		for (const verdict of this.currentAvailability()) {
+			if (isDropDeadHidden(verdict)) {
+				hidden.add(verdict.provider)
+			}
+		}
+		return hidden
+	}
+}