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

package/lib/index.js

@@ -34,6 +34,11 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { applyHarness, harnessReport } from './harness.js'
+import { detectBillingMode, sortProviders } from './sorter.js'
+import { AvailabilityStore, isDropDeadHidden, classifyFailure } from './availability-store.js'
+
+export { detectBillingMode, sortProviders } from './sorter.js'
+export { AvailabilityStore, isDropDeadHidden, classifyFailure } from './availability-store.js'
 
 /**
  * 用量统计 domain 的 spec。
@@ -129,6 +134,7 @@ const PIAI_PROBE_PATH = '/api/dsh-llm-hub/pi-ai/probe'
 const PIAI_CATALOG_PATH = '/api/dsh-llm-hub/pi-ai/catalog'
 const PIAI_BALANCE_PATH = '/api/dsh-llm-hub/pi-ai/balance'
 const PIAI_MODELS_PATH = '/api/dsh-llm-hub/pi-ai/models'
+const BILLING_MODE_PATH = '/api/dsh-llm-hub/billing-mode'
 const META_PATH = '/api/dsh-llm-hub/meta'
 /** harness 探测自检路由；宿主 info 日志不落盘，靠它从外部确认注册结果。 */
 const HARNESS_PATH = '/api/dsh-llm-hub/harness'
@@ -177,25 +183,166 @@ const WARNING_CHECK_PATH = '/api/dsh-llm-hub/warning/check'
  *   }
  */
 const ROUTING_RESOLVE_PATH = '/api/dsh-llm-hub/routing/resolve'
+/**
+ * 路由组状态：`GET /api/dsh-llm-hub/routing/state`。
+ *
+ * composer 快切 chip 的数据源 —— 返回当前模式（manual/smart）、激活组、每个组
+ * 的候选与可用状态、以及 smart 模式最近一次的真实路由判断（lastDecision）。
+ */
+const ROUTING_STATE_PATH = '/api/dsh-llm-hub/routing/state'
+/**
+ * 切换模式 / 组：`POST /api/dsh-llm-hub/routing/select`。
+ *
+ * 请求体 `{ mode?, activeGroup? }`（都可选，至少一个）。写回 settings 的
+ * `dsh-llm-hub.routing` 段 —— 状态持久化，重启不丢。
+ */
+const ROUTING_SELECT_PATH = '/api/dsh-llm-hub/routing/select'
+/** 插件自有的 settings 命名空间（1.5.0 起注册）—— routing / warning / aliases 都住这里。 */
+const HUB_NS = 'dsh-llm-hub'
 /** 模型别名：客户端渲染 model id 时显示短名（典型场景：deepseek-reasoner → 推理）。 */
 const ALIASES_PATH = '/api/dsh-llm-hub/aliases'
 /**
- * 多账号 key 轮换：settings.dsh-llm-hub.keyPool[provider] 是 entry 数组。
+ * 1.4.0 多 Key 轮换纯函数：支持 string（单 key）或 string[]（多 key round-robin）。
+ *
+ * @param {string|string[]|undefined} refs - 单 Key 或多 Key 环境变量名数组
+ * @param {string} provider - Provider 标识（用于维护独立索引）
+ * @param {Map<string, number>} [stateMap] - 轮换游标存储
+ * @returns {{ ref: string, index: number, total: number } | undefined}
+ */
+export function pickRotatedEnv(refs, provider, stateMap) {
+	if (typeof refs === 'string' && refs.length > 0) {
+		return { ref: refs, index: 0, total: 1 }
+	}
+	if (Array.isArray(refs)) {
+		const list = refs.filter((r) => typeof r === 'string' && r.trim().length > 0)
+		if (list.length === 0) return undefined
+		const current = stateMap ? (stateMap.get(provider) ?? 0) : 0
+		const index = current % list.length
+		if (stateMap) stateMap.set(provider, (current + 1) % list.length)
+		return { ref: list[index], index, total: list.length }
+	}
+	return undefined
+}
+
+/**
+ * 智能识别计费模式：'usage'（按量付费）| 'subscription'（套餐）。
+ * 优先级：
+ * 1. 显式覆盖：profile?.billingMode
+ * 2. 定时限额特征（5h/周/月/resetsAt/quota/plan/percent）→ 'subscription'
+ * 3. 原厂域名（deepseek.com / bigmodel.cn / openai.com 等）或现金余额 → 'usage'
+ * 4. 兜底 → 'usage'
+
+
+/**
+ * 「provider/model」字符串解析（路由组的真源实现；closure 里的
+ * `parseRouteEntry` 是同语义副本 —— 测不出 export，所以这里留正源）。
  *
- * 设计取舍：
- *   - **向后兼容**：未配 keyPool 段时直接走原 apiKeyEnv 单 key 路径，行为完全
- *     不变；现有 80 个测试不破。
- *   - **round-robin**（非失败感知）：每次解析按索引取下一个 entry；不加锁、不跨
- *     session 持久化（重启会从 0 开始）。失败的 key 不会自动跳过 —— 用户从
- *     debug 路由看到「上次失败的是 X」，下次请求自然轮换过去。这是 1.x 的轻量方案，
- *     真要自动跳过失败 key 等 1.1 收集了真实失败场景再加。
- *   - **不覆盖显式 key**：request.apiKey 是一次性覆盖（发现草稿用的），绕过
- *     轮换直接用它；轮换索引不动。
- *   - **provider 范围**：DeepSeek 官方直连用 NS = 'llm-deepseek' 作为 key，pi-ai
- *     provider 用 provider 自己的 id（modelgo / minimax ...）；keyPool 段里
- *     直接用 provider id 作 key。
+ * provider 严格（字母数字与连字符/下划线），model 放宽（允许 `.` `+` —— DSH
+ * 真实 id 会含它们），缺斜杠 / 空段 / 非法字符一律 undefined。
+ * @param {string} entry - 配置里的一行。
+ * @returns {{ provider: string, model: string } | undefined}
  */
-const KEYPOOL_STATUS_PATH = '/api/dsh-llm-hub/keypool/status'
+export function parseRouteEntryPure(entry) {
+	if (typeof entry !== 'string') return undefined
+	const ROUTE_KEY_RE = /^[a-z0-9][a-z0-9_-]*$/i
+	const ROUTE_MODEL_RE = /^[a-z0-9][a-z0-9_.+-]*$/i
+	const slash = entry.indexOf('/')
+	if (slash <= 0 || slash === entry.length - 1) return undefined
+	const provider = entry.slice(0, slash).trim()
+	const model = entry.slice(slash + 1).trim()
+	if (!ROUTE_KEY_RE.test(provider) || !ROUTE_MODEL_RE.test(model)) return undefined
+	return { provider, model }
+}
+
+/**
+ * 把 settings 的 `routing` 段折成路由组列表（1.5.0 智能路由组的真源实现）。
+ *
+ * 形态：
+ *   routing:
+ *     mode: smart            # manual | smart（缺省 manual）
+ *     activeGroup: company   # 缺省取第一个组
+ *     groups:
+ *       - id: company
+ *         label: 公司
+ *         primary: modelgo/gpt-4o
+ *         fallbacks: [modelgo/claude-3.5-sonnet]
+ *       - id: personal
+ *         primary: deepseek-official/deepseek-chat
+ *         fallbacks: [minimax/MiniMax-M2.7]
+ *
+ * 兼容：没有 `groups` 时 flat 的 `primary/fallbacks` 折成一个 id 为
+ * `default` 的组 —— 老配置不写 groups 也能继续用。
+ *
+ * @param {object|undefined|null} routing - settings.routing 段。
+ * @returns {{ groups: Array, mode: 'manual'|'smart', activeGroup: string }}
+ */
+export function parseRoutingGroups(routing) {
+	const r = routing !== null && typeof routing === 'object' ? routing : {}
+	const mode = r.mode === 'smart' ? 'smart' : 'manual'
+	const groups = []
+	const seen = new Set()
+	for (const raw of Array.isArray(r.groups) ? r.groups : []) {
+		if (raw === null || typeof raw !== 'object') continue
+		const id = typeof raw.id === 'string' ? raw.id.trim() : ''
+		if (id === '' || seen.has(id)) continue
+		const primary = parseRouteEntryPure(raw.primary) ?? null
+		const fallbacks = (Array.isArray(raw.fallbacks) ? raw.fallbacks : [])
+			.map(parseRouteEntryPure)
+			.filter((entry) => entry !== undefined)
+		if (primary === null && fallbacks.length === 0) continue
+		seen.add(id)
+		groups.push({
+			id,
+			label: typeof raw.label === 'string' && raw.label.trim() !== '' ? raw.label.trim() : null,
+			primary,
+			fallbacks
+		})
+	}
+	if (groups.length === 0) {
+		// legacy 形态：flat primary + fallbacks 折成 default 组。
+		const primary = parseRouteEntryPure(r.primary) ?? null
+		const fallbacks = (Array.isArray(r.fallbacks) ? r.fallbacks : [])
+			.map(parseRouteEntryPure)
+			.filter((entry) => entry !== undefined)
+		if (primary !== null || fallbacks.length > 0) {
+			groups.push({ id: 'default', label: null, primary, fallbacks })
+		}
+	}
+	const declared = typeof r.activeGroup === 'string' ? r.activeGroup.trim() : ''
+	const activeGroup = groups.some((group) => group.id === declared) ? declared : (groups[0]?.id ?? '')
+	return { groups, mode, activeGroup }
+}
+
+/**
+ * 智能路由裁决（真源实现，waterfall 与测试共用）。
+ *
+ * 语义：按组内「primary → fallbacks」顺序，取第一个**未探明不可用**的候选；
+ * 额度耗尽（402）/ 网关探测失败都会在可用性表里标 `unavailable`，于是被跳过
+ * —— 这就是「按额度自动切换」。全不可用时不动原配置（让请求照常打出去、
+ * 错误可见），并给 reason。
+ *
+ * @param {Array<{ provider: string, model: string }>} entries - 组内候选，primary 在前。
+ * @param {(provider: string) => string} stateFor - provider 级可用状态：'available' | 'unknown' | 'unavailable'。
+ * @param {{ provider: string, model: string } | null} active - 本次请求机器本来要用的配置。
+ * @returns {{ to: { provider: string, model: string } | null, reason: string | null, switched: boolean }}
+ */
+export function pickSmartRoute(entries, stateFor, active) {
+	const list = Array.isArray(entries) ? entries : []
+	if (list.length === 0) {
+		return { to: null, reason: '当前组没有可用候选 —— 去设置里加 primary / fallbacks', switched: false }
+	}
+	const winner = list.find((entry) => stateFor(entry.provider) !== 'unavailable')
+	if (winner === undefined) {
+		return { to: null, reason: '主力与 fallbacks 全部不可用 —— 充值或换一个再说', switched: false }
+	}
+	const activeKey = active === null || active === undefined ? null : `${active.provider}/${active.model}`
+	const winnerKey = `${winner.provider}/${winner.model}`
+	if (winnerKey === activeKey) {
+		return { to: null, reason: null, switched: false }
+	}
+	return { to: { provider: winner.provider, model: winner.model }, reason: null, switched: true }
+}
+
 /** 路由配置从 settings 哪一段读 —— 顶层 dsh-llm-hub 段下，与 warning 同级。 */
 const ROUTING_KEY = 'routing'
 /** 探针结论的保鲜期；过期后下次读取顺手在后台重探，不阻塞下拉。 */
@@ -385,8 +532,62 @@ export const inject = ['llm', 'webServer']
  */
 export function apply(ctx) {
 
+	// ── 插件自有 settings 命名空间（dsh-llm-hub）────────────────────────────
+	//
+	// 1.5.0 起：routing / warning / aliases 的真源从 `llm-deepseek` 段迁到独立
+	// 的 `dsh-llm-hub` 段 —— README 文档里写的顶层 `dsh-llm-hub:` 键此前**从未
+	// 被读到过**（没注册过命名空间，settings.get 会抛），这是 1.1.0 起的历史
+	// 缺陷，这里一起修掉。
+	//
+	// schema 尽量懒加载 `@deepseek-ai/schemastery`；失败时退回 `Object` 构造器
+	// （schemastery 接受原生构造器作为 schema）。注册失败不 fatal：配置读取退
+	// 回 legacy 路径，智能路由降级为「只建议」。
+	let hubRegistered = false
+	ctx.inject(['settings'], (settingsCtx) => {
+		void (async () => {
+			let schema
+			try {
+				const mod = await import('@deepseek-ai/schemastery')
+				const z = (mod && typeof mod === 'object' ? mod.default ?? mod : mod)
+				const groupItem = z.object({ id: z.string().required(), label: z.string(), primary: z.string(), fallbacks: z.array(z.string()) })
+				schema = z.object({
+					routing: z.object({
+						mode: z.union(['manual', 'smart']).default('manual'),
+						activeGroup: z.string().default(''),
+						groups: z.array(groupItem).default([])
+					}).default({}),
+					warning: z.object({ cashCNY: z.number().default(10), planPercent: z.number().default(10) }).default({}),
+					aliases: z.dict(z.string()).default({})
+				})
+			} catch {
+				// 零依赖环境：schemastery 没解析到 —— 用原生构造器兜底。
+				schema = Object
+			}
+			try {
+				settingsCtx.settings.register(HUB_NS, schema)
+				hubRegistered = true
+			} catch (error) {
+				ctx.logger.warn(`dsh-llm-hub: settings ns "dsh-llm-hub" register failed: ${error?.message ?? error}`)
+			}
+		})()
+	})
+
 	/**
-	 * 当前已解析的 `llm-deepseek` 设置段。
+	 * 读 `dsh-llm-hub` 设置段（1.5.0 起的真源）。
+	 * @returns 已解析设置段；未注册 / 未配置时为 `undefined`。
+	 */
+	const hubSectionOf = () => {
+		const settings = ctx.get('settings')
+		if (settings === undefined) return undefined
+		try {
+			const value = settings.get(HUB_NS)
+			return value !== null && typeof value === 'object' ? value : undefined
+		} catch {
+			return undefined
+		}
+	}
+
+	/** 当前已解析的 `llm-deepseek` 设置段。
 	 *
 	 * 每次调用惰性重读：apply 时该段可能尚未注册，而适配器本身也按请求重解析
 	 * 连接事实 —— 惰性读才能让两边看同一份修订。
@@ -423,8 +624,11 @@ export function apply(ctx) {
 	 * @returns 阈值表，未配置时返回默认值。
 	 */
 	const warningThresholds = () => {
-		const section = sectionOf() ?? {}
-		const warning = section.warning !== null && typeof section.warning === 'object' ? section.warning : {}
+		// 真源是 dsh-llm-hub 段（1.5.0 注册）；legacy llm-deepseek 段只补缺。
+		const hub = hubSectionOf() ?? {}
+		const legacy = sectionOf() ?? {}
+		const merged = { ...(legacy.warning !== null && typeof legacy.warning === 'object' ? legacy.warning : {}), ...(hub.warning !== null && typeof hub.warning === 'object' ? hub.warning : {}) }
+		const warning = merged
 		const readNumber = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
 		return {
 			cashCNY: readNumber(warning.cashCNY, 10),
@@ -522,56 +726,23 @@ export function apply(ctx) {
 	/**
 	 * 读 `settings.dsh-llm-hub.keyPool[provider]` 段。
 	 *
-	 * 每条 entry 是 `{ name, env }` —— name 是人话（debug 用），env 是
-	 * 凭据服务引用的环境变量名；后者用 `process.env[ref]` 直接读，**不**走
-	 * credentials 服务，因为这些 key 多半不会进凭据库（轮换场景通常是
-	 * 测试 / 临时 key，手贴环境变量更简单）。
-	 *
-	 * @returns 规范化后的 entry 数组（缺 name 或 env 的过滤掉）；没配或非数组返 `undefined`。
-	 */
-	const keyPoolOf = (provider) => {
-		const section = sectionOf() ?? {}
-		const raw = section.keyPool
-		if (raw === null || typeof raw !== 'object') return undefined
-		const entries = raw[provider]
-		if (!Array.isArray(entries)) return undefined
-		const out = []
-		for (const entry of entries) {
-			if (entry === null || typeof entry !== 'object') continue
-			const name = typeof entry.name === 'string' && entry.name.trim().length > 0 ? entry.name.trim() : undefined
-			const env = typeof entry.env === 'string' && entry.env.trim().length > 0 ? entry.env.trim() : undefined
-			if (env === undefined) continue
-			out.push({ name: name ?? env, env })
-		}
-		return out.length > 0 ? out : undefined
-	}
-
 	/**
-	 * 给一个 provider 取轮换到的下一个 entry + 索引推进 +1。
-	 * @returns `{ entry, index }` —— entry 是 { name, env }；index 是 0-based 位置。
+	 * 多 Key 自动轮换索引 —— per provider 维护独立的自增游标。
+	 * @type {Map<string, number>}
 	 */
-	const rotateKeyPool = (provider) => {
-		const entries = keyPoolOf(provider)
-		if (entries === undefined) return undefined
-		const current = keyPoolIndex.current.get(provider) ?? 0
-		const index = current % entries.length
-		keyPoolIndex.current.set(provider, (current + 1) % entries.length)
-		const entry = entries[index]
-		keyPoolLastChosen.current.set(provider, { entry, index, at: Date.now() })
-		return { entry, index }
-	}
+	const keyRotationIndex = new Map()
 
 	/**
 	 * 解析本次调用要用的连接事实。
 	 *
 	 * 解析顺序（向后兼容）：
 	 *   1) request.apiKey 一次性覆盖 —— 跳过轮换、原样返回（不污染索引）
-	 *   2) keyPool[provider] 命中 → round-robin 取下一个，env var 解析密钥
-	 *   3) 旧的 `apiKeyEnv` 单 key 路径（行为完全不变）
+	 *   2) section.apiKeyEnv 是 string[] → 按 provider 轮换取下一个 ref，
+	 *      再走 credentials 服务或 process.env 解析密钥
+	 *   3) section.apiKeyEnv 是 string → 原单 key 路径（行为完全不变）
 	 *
-	 * 返 ref 不变 —— 客户端拿到的是凭据引用（keyPool 的 env 名），实际值是
-	 * `process.env[ref]` 解出来的字符串；下游诊断（探针 / 余额路由）能继续
-	 * 看到当前用的是哪个 env。
+	 * 返 ref 不变 —— 客户端拿到的是凭据引用；下游诊断（探针 / 余额路由）
+	 * 能继续看到当前用的是哪个 env。
 	 * @param request - 可选的一次性覆盖（发现草稿会带 baseURL / apiKey / provider）。
 	 * @returns baseURL、凭据引用与可用密钥。
 	 */
@@ -590,14 +761,10 @@ export function apply(ctx) {
 			return { baseURL, ref, apiKey: explicit }
 		}
 		const providerKey = label(request.provider) ?? DEEPSEEK_PROVIDER
-		const pool = rotateKeyPool(providerKey)
-		if (pool !== undefined) {
-			const apiKey = label(process.env[pool.entry.env])
-			if (apiKey !== undefined) return { baseURL, ref: pool.entry.env, apiKey }
-			// 配了 keyPool 但 env var 没值 —— 退回旧单 key 路径，不让 keyPool
-			// 静默吞掉请求。
-		}
-		const ref = label(request.apiKeyEnv, section.apiKeyEnv) ?? DEFAULT_API_KEY_ENV
+		const picked = pickRotatedEnv(section.apiKeyEnv, providerKey, keyRotationIndex)
+		const ref = picked === undefined
+			? (label(request.apiKeyEnv, section.apiKeyEnv) ?? DEFAULT_API_KEY_ENV)
+			: picked.ref
 		let apiKey
 		const credentials = ctx.get('credentials')
 		if (credentials !== undefined) {
@@ -705,6 +872,37 @@ export function apply(ctx) {
 				return
 			}
 			try {
+				const section = sectionOf() ?? {}
+				const refs = Array.isArray(section.apiKeyEnv)
+					? section.apiKeyEnv.filter((r) => typeof r === 'string' && r.trim().length > 0)
+					: (typeof section.apiKeyEnv === 'string' && section.apiKeyEnv.trim().length > 0
+						? [section.apiKeyEnv.trim()]
+						: [DEFAULT_API_KEY_ENV])
+				const credentials = ctx.get('credentials')
+				const keys = await Promise.all(refs.map(async (ref) => {
+					let apiKey
+					if (credentials !== undefined) {
+						const hit = await credentials.resolve(ref)
+						apiKey = label(hit?.value)
+					}
+					if (apiKey === undefined) apiKey = label(process.env[ref])
+					if (!apiKey) return { ref, keyMasked: '未配置', isAvailable: false, total: '0.00', error: '未找到密钥', ok: false }
+					try {
+						const raw = await getJson('/user/balance', { apiKey })
+						const shaped = shapeBalance(raw)
+						const first = shaped.balances?.[0]
+						return {
+							ref,
+							keyMasked: maskKey(apiKey),
+							isAvailable: shaped.isAvailable,
+							total: first?.total ?? '0.00',
+							currency: first?.currency ?? 'CNY',
+							ok: true
+						}
+					} catch (e) {
+						return { ref, keyMasked: maskKey(apiKey), isAvailable: false, total: '0.00', error: e instanceof Error ? e.message : String(e), ok: false }
+					}
+				}))
 				const { apiKey } = await connectionFacts()
 				const payload = shapeBalance(await getJson('/user/balance'))
 				if (request.method === 'HEAD') {
@@ -712,12 +910,67 @@ export function apply(ctx) {
 					response.end()
 					return
 				}
-				send(200, { ok: true, apiKey: apiKey ?? null, keyMasked: maskKey(apiKey), ...payload })
+				send(200, {
+					ok: true,
+					apiKey: apiKey ?? null,
+					keyMasked: maskKey(apiKey),
+					billingMode: section.billingMode || 'usage',
+					keys,
+					...payload
+				})
 			} catch (error) {
 				send(502, { ok: false, error: error instanceof Error ? error.message : String(error) })
 			}
 		}
 	}), 'dsh-llm-hub: balance route')
+
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: BILLING_MODE_PATH,
+		handler: async (request, response) => {
+			const send = (status, payload) => {
+				response.writeHead(status, {
+					'content-type': 'application/json; charset=utf-8',
+					'cache-control': 'no-store'
+				})
+				response.end(JSON.stringify(payload))
+			}
+			if (request.method !== 'POST') {
+				response.writeHead(405, { allow: 'POST' })
+				response.end()
+				return
+			}
+			if (!sameOrigin(request)) {
+				send(403, { ok: false, error: 'cross-origin requests are refused' })
+				return
+			}
+			try {
+				const collected = []
+				for await (const chunk of request) collected.push(chunk)
+				const body = JSON.parse(Buffer.concat(collected).toString('utf8'))
+				const provider = label(body?.provider)
+				const mode = label(body?.mode)
+				if (mode !== 'usage' && mode !== 'subscription') {
+					send(400, { ok: false, error: 'mode must be "usage" or "subscription"' })
+					return
+				}
+				const settings = ctx.get('settings')
+				if (!settings) {
+					send(500, { ok: false, error: 'settings service not available' })
+					return
+				}
+				if (provider === 'deepseek' || provider === 'llm-deepseek' || provider === 'deepseek-official') {
+					await settings.update('llm-deepseek', { billingMode: mode })
+				} else if (provider) {
+					const profile = piaiProfileOf(provider) ?? {}
+					await settings.update(PIAI_NS, { providers: { [provider]: { ...profile, billingMode: mode } } })
+				}
+				send(200, { ok: true, provider, mode })
+			} catch (error) {
+				send(500, { ok: false, error: error instanceof Error ? error.message : String(error) })
+			}
+		}
+	}), 'dsh-llm-hub: set billing mode route')
 	//#endregion
 
 	//#region 3) pi-ai 旁路补缺
@@ -891,6 +1144,7 @@ export function apply(ctx) {
 			// 已配置的 id 列表：前端拉到网关目录后要据此把「已经在用的」默认勾上，
 			// 光有数量做不到这件事。
 			modelIds: models.map((m) => (m !== null && typeof m === 'object' ? m.id : m)).filter((id) => typeof id === 'string'),
+			billingMode: label(profile.billingMode) ?? null,
 			balanceAdapter: balanceAdapterFor(provider, profile) ?? null
 		}
 	}
@@ -1245,12 +1499,14 @@ export function apply(ctx) {
 	//     比多显示一个不能用的更糟：前者让人以为插件坏了。
 	//   · 服务端只管判定；「从下拉里摘掉」在 client 半做（目录无法在 host 侧过滤）。
 
+	/** 可用性与健康状态机实例 */
+	const availabilityStore = new AvailabilityStore({ runtimeTtlMs: RUNTIME_TTL_MS })
 	/** provider -> 探针判定（凭据 / 探测 / 余额）。 */
-	const baseVerdicts = new Map()
+	const baseVerdicts = availabilityStore.baseVerdicts
 	/** provider -> 最近一次运行期失败判定（真实请求的鉴权/欠费错误）。 */
-	const runtimeMarks = new Map()
+	const runtimeMarks = availabilityStore.runtimeMarks
 	/** provider -> 最近一次真实请求成功的时刻。 */
-	const successAt = new Map()
+	const successAt = availabilityStore.successAt
 	/** 全量重探的去重句柄。 */
 	let probeAll = null
 	/** 探针代际：手动重探会 +1，让在途的旧探针彻底作废。 */
@@ -1464,79 +1720,11 @@ export function apply(ctx) {
 		refreshAvailability(stuck).catch(() => {})
 	}
 
-	/** 把真实请求的失败/成功折成运行期标记。 */
-	const classifyFailure = (failure) => {
-		const code = typeof failure?.code === 'string' ? failure.code : ''
-		const status = typeof failure?.status === 'number' ? failure.status : undefined
-		// MISSING_CREDENTIAL 也归这一类：pi-ai 解析不到 apiKeyEnv 时抛的就是它，
-		// 与「key 无效」对使用者的意义一样 —— 这条路由现在调不了。
-		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
-	}
-
 	/** 汇总：运行期标记优先于探针判定，真实成功又覆盖运行期失败。 */
-	const currentAvailability = () => {
-		const now = Date.now()
-		const merged = new Map()
-		for (const [id, verdict] of baseVerdicts) merged.set(id, verdict)
-		for (const [id, mark] of [...runtimeMarks]) {
-			if (now - mark.at >= RUNTIME_TTL_MS) {
-				runtimeMarks.delete(id)
-				continue
-			}
-			if ((successAt.get(id) ?? 0) > mark.at) continue
-			const base = merged.get(id)
-			merged.set(id, {
-				provider: id,
-				displayName: base?.displayName ?? id,
-				ns: base?.ns ?? PIAI_NS,
-				state: 'unavailable',
-				code: mark.code,
-				reason: mark.reason,
-				source: 'runtime',
-				checkedAt: mark.at
-			})
-		}
-		for (const [id, at] of successAt) {
-			const base = merged.get(id)
-			if (base === undefined || base.state === 'available') continue
-			if (now - at >= RUNTIME_TTL_MS || at <= base.checkedAt) continue
-			merged.set(id, { ...base, state: 'available', code: 'RECOVERED', reason: '', source: 'runtime', checkedAt: at })
-		}
-		return [...merged.values()].sort((left, right) => left.provider.localeCompare(right.provider))
-	}
-
-	/**
-	 * 判定是否属于应从模型下拉彻底摘掉的严重凭据故障。
-	 *
-	 * ⚠️ 设计原则（避免死锁）：
-	 * 只有确凿的凭据故障（CREDENTIAL_MISSING / AUTH_REJECTED / ACCOUNT_UNAVAILABLE）才从下拉框剔除。
-	 * 配额耗尽（QUOTA_EXHAUSTED）与现金余额为 0（BALANCE_EMPTY / PAYMENT_REQUIRED）属于临时限额/计费状态，
-	 * 绝不能从下拉框中剔除，否则会导致：
-	 * 1) 用户在界面上永久丢失模型入口；
-	 * 2) 5小时滚动配额或周配额恢复后，用户因无法选模型而无法触发运行期遥测恢复；
-	 * 3) 形成死锁。
-	 */
-	const 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'
-	}
+	const currentAvailability = () => availabilityStore.currentAvailability()
 
 	/** 当前该从下拉里摘掉的 provider 集合。 */
-	const hiddenProviders = () => {
-		const hidden = new Set()
-		for (const verdict of currentAvailability()) {
-			if (isDropDeadHidden(verdict)) hidden.add(verdict.provider)
-		}
-		return hidden
-	}
+	const hiddenProviders = () => availabilityStore.hiddenProviders()
 
 	const sameHidden = (left, right) => left.size === right.size && [...left].every((id) => right.has(id))
 
@@ -1701,12 +1889,33 @@ export function apply(ctx) {
 			return () => {}
 		}
 		const original = service.listProviders
+
+		const billingModeOf = (id) => {
+			if (!id || typeof id !== 'string') return 'usage'
+			const cleanId = id.replace(/^pi-ai:/, '')
+			if (cleanId === 'deepseek-official' || cleanId === 'deepseek' || cleanId === 'llm-deepseek') {
+				const section = sectionOf()
+				if (section?.billingMode === 'usage' || section?.billingMode === 'subscription') {
+					return section.billingMode
+				}
+				return 'usage'
+			}
+			const profile = piaiProfileOf(cleanId) || piaiProfileOf(id)
+			if (profile?.billingMode === 'usage' || profile?.billingMode === 'subscription') {
+				return profile.billingMode
+			}
+			return detectBillingMode(profile || { provider: cleanId })
+		}
+
 		const filtered = function (...args) {
 			const providers = original.apply(this, args)
 			if (!Array.isArray(providers)) return providers
-			const hidden = hiddenProviders()
-			if (hidden.size === 0) return providers
-			return providers.filter((provider) => !hidden.has(provider?.id))
+			const hidden = availabilityStore.hiddenProviders()
+			// 用户要求：LLM 下拉列表优先使用套餐额度，套餐排在上面，按量付费排在下面，从上往下选最容易先选到套餐。
+			return sortProviders(providers, (id) => ({
+				available: !hidden.has(id),
+				billingMode: billingModeOf(id)
+			}), { filterUnavailable: true })
 		}
 		// ⚠️ 不要用 `service.listProviders !== filtered` 校验「写进去了没有」：
 		// cordis 的服务访问返回 traceable 代理，每次读方法都是一个新的包装对象，永远不相等。
@@ -1862,10 +2071,6 @@ export function apply(ctx) {
 	// 对照官方价目表，CSV 导出（`GET /api/dsh-llm-hub/usage/export`）已经做了。
 	const usageTable = { current: null }
 	const usageReady = { current: false }
-	// 多账号 key 轮换：每个 provider 一个 round-robin 索引。重启后归零，跨 session
-	// 不持久化 —— 失败的 key 不会自动跳过，下次自然轮换过去（看 debug 路由查清）。
-	const keyPoolIndex = { current: new Map() }
-	const keyPoolLastChosen = { current: new Map() }
 	const recordUsage = (entry) => {
 		const table = usageTable.current
 		if (table === null) return
@@ -2214,36 +2419,43 @@ export function apply(ctx) {
 	const ROUTE_MODEL_RE = /^[a-z0-9][a-z0-9_.+-]*$/i
 
 	/**
-	 * 解析「provider/model」字符串。
+	 * 解析「provider/model」字符串 —— 委托给模块级真源 `parseRouteEntryPure`。
 	 * @param entry - 配置里的一行。
 	 * @returns 解析后的 { provider, model }，无效时为 `undefined`。
 	 */
-	const parseRouteEntry = (entry) => {
-		if (typeof entry !== 'string') return undefined
-		const slash = entry.indexOf('/')
-		if (slash <= 0 || slash === entry.length - 1) return undefined
-		const provider = entry.slice(0, slash).trim()
-		const model = entry.slice(slash + 1).trim()
-		// provider 严格（要拿去找 settings 段查），model 放宽（DSH 真实 id 可能含 .）
-		if (!ROUTE_KEY_RE.test(provider) || !ROUTE_MODEL_RE.test(model)) return undefined
-		return { provider, model }
+	const parseRouteEntry = (entry) => parseRouteEntryPure(entry)
+
+	/**
+	 * 合并读 settings 的 `routing` 段：真源 `dsh-llm-hub`（1.5.0 注册），
+	 * legacy `llm-deepseek` 段只补缺 —— 用户科研把配置写在新旧两处也能读。
+	 * @returns 合并后的 routing 对象（可能为空对象）。
+	 */
+	const routingObjOf = () => {
+		const hub = hubSectionOf() ?? {}
+		const legacy = sectionOf() ?? {}
+		const hubRouting = hub.routing !== null && typeof hub.routing === 'object' ? hub.routing : {}
+		const legacyRouting = legacy.routing !== null && typeof legacy.routing === 'object' ? legacy.routing : {}
+		return { ...legacyRouting, ...hubRouting }
 	}
 
 	/**
-	 * 读 `routing.primary` + `routing.fallbacks[]`。
-	 * @returns 配置好的顺序数组（primary 在前），无效项过滤掉。空数组表示未配置。
+	 * 读路由组（真源实现 `parseRoutingGroups`，settings 惰性重读）。
+	 * @returns {{ groups: Array, mode: 'manual'|'smart', activeGroup: string }}
 	 */
-	const routingCandidatesOf = () => {
-		const section = sectionOf() ?? {}
-		const routing = section[ROUTING_KEY] !== null && typeof section[ROUTING_KEY] === 'object' ? section[ROUTING_KEY] : {}
+	const routingGroupsOf = () => parseRoutingGroups(routingObjOf())
+
+	/**
+	 * legacy 候选列表（老 resolve 语义保留）：当前激活组展开成
+	 * primary → fallbacks 顺序数组。
+	 * @returns 配置好的顺序数组，无效项过滤掉。空数组表示未配置。
+	 */
+	const routingCandidatesOf = (groupId) => {
+		const state = routingGroupsOf()
+		const group = state.groups.find((candidate) => candidate.id === groupId) ?? state.groups[0]
+		if (group === undefined) return []
 		const out = []
-		const primary = parseRouteEntry(routing.primary)
-		if (primary !== undefined) out.push(primary)
-		const fallbacks = Array.isArray(routing.fallbacks) ? routing.fallbacks : []
-		for (const fallback of fallbacks) {
-			const parsed = parseRouteEntry(fallback)
-			if (parsed !== undefined) out.push(parsed)
-		}
+		if (group.primary !== null) out.push(group.primary)
+		for (const fallback of group.fallbacks) out.push(fallback)
 		return out
 	}
 
@@ -2262,12 +2474,15 @@ export function apply(ctx) {
 	}
 
 	/**
-	 * 路由解析：给客户端返回「该用哪个 + 原因」。
+	 * 路由解析：给客户端返回「该用哪个 + 原因」（1.5.0 起按组解析）。
 	 * @param active - 客户端 POST 进来的当前已激活 (provider, model)。
-	 * @returns 路由建议载荷。
+	 * @param groupId - 指定组 id；缺省用当前激活组。
+	 * @returns 路由建议载荷（附 mode / activeGroup / groups 摘要）。
 	 */
-	const resolveRoute = (active) => {
-		const candidates = routingCandidatesOf()
+	const resolveRoute = (active, groupId) => {
+		const state = routingGroupsOf()
+		const candidates = routingCandidatesOf(typeof groupId === 'string' && groupId !== '' ? groupId : undefined)
+		const activeGroup = state.groups.some((group) => group.id === groupId) ? groupId : state.activeGroup
 		const verdicts = new Map()
 		for (const candidate of candidates) {
 			verdicts.set(`${candidate.provider}/${candidate.model}`, stateFor(candidate.provider, candidate.model))
@@ -2283,6 +2498,13 @@ export function apply(ctx) {
 			: (recommendation === undefined ? '主力与 fallbacks 全部不可用 —— 充值或换一个再说' : null)
 		return {
 			ok: true,
+			mode: state.mode,
+			activeGroup,
+			groups: state.groups.map((group) => ({
+				id: group.id,
+				label: group.label,
+				candidateCount: (group.primary !== null ? 1 : 0) + group.fallbacks.length
+			})),
 			active: activeParsed === null
 				? null
 				: { provider: activeParsed.provider, model: activeParsed.model, state: activeState },
@@ -2318,10 +2540,174 @@ export function apply(ctx) {
 				sendJson(response, 400, { ok: false, error: '请求内容不是合法 JSON' })
 				return
 			}
-			sendJson(response, 200, resolveRoute(payload?.active))
+			sendJson(response, 200, resolveRoute(payload?.active, typeof payload?.group === 'string' ? payload.group : undefined))
 		}
 	}), 'dsh-llm-hub: routing resolve route')
 
+	// ── 智能路由组 + 模式接管（1.5.0）────────────────────────────────────────
+	//
+	// 上面的 resolveRoute 是「建议」；这一段是「接管」：
+	//
+	//   · 配置（settings.dsh-llm-hub.routing）：mode = manual|smart、activeGroup、
+	//     groups[] —— 每组 primary + fallbacks[]，「公司」「个人」就是两个组。
+	//   · smart 模式：监听 `agent/request` waterfall，每次模型调用拿机器本要用
+	//     的 config，按激活组 primary → fallbacks 找第一个未探明不可用的候选，
+	//     直接替换 provider/model —— **完全接管**，composer 下拉显示什么不再
+	//     决定实际路由（额度耗尽 = 探测 unavailable = 被跳过，这就是「按额度
+	//     自动切换」）。waterfall 是官方请求改写点（«Replace the frozen call
+	//     configuration»），合法；README 里「不做自动切换」的旧红线只针对
+	//     composer slot 本身，这条不碰 slot。
+	//   · manual 模式：行为与 1.1.0 完全一致 —— 只建议，不改请求。
+	//   · 切组 / 切模式：POST /routing/select 持久化进 settings，重启不丢。
+	//
+	// 稳定状态：最近一次 smart 判断存 `lastSmartDecision`（内存即可，用于 chip
+	// 展示「当前实际路由」）。
+	const lastSmartDecision = { at: 0, group: null, from: null, to: null, reason: null }
+
+	/** smart 状态给前端（不带 settings 原文）。 */
+	const smartStateOf = () => {
+		const state = routingGroupsOf()
+		const groups = state.groups.map((group) => {
+			const candidates = [
+				...(group.primary !== null ? [group.primary] : []),
+				...group.fallbacks
+			]
+			const winner = pickSmartRoute(candidates, (provider) => stateFor(provider, ''), null)
+			return {
+				id: group.id,
+				label: group.label,
+				candidates: candidates.map((candidate) => ({
+					provider: candidate.provider,
+					model: candidate.model,
+					state: stateFor(candidate.provider, candidate.model)
+				})),
+				wouldRoute: winner.to,
+				reason: winner.reason
+			}
+		})
+		return {
+			ok: true,
+			mode: state.mode,
+			activeGroup: state.activeGroup,
+			groups,
+			lastDecision: lastSmartDecision.at > 0 ? {
+				at: lastSmartDecision.at,
+				group: lastSmartDecision.group,
+				from: lastSmartDecision.from,
+				to: lastSmartDecision.to,
+				reason: lastSmartDecision.reason
+			} : null
+		}
+	}
+
+	/** 读 settings 的 routing 段并按需覆写 mode / activeGroup，持久化。 */
+	const applyRoutingSelect = async (patch) => {
+		const settings = ctx.get('settings')
+		if (settings === undefined || hubRegistered !== true) {
+			return { ok: false, error: 'settings 命名空间 dsh-llm-hub 尚未就绪 —— 稍后重试' }
+		}
+		const current = routingObjOf()
+		const merged = { ...current }
+		if (patch.mode === 'manual' || patch.mode === 'smart') merged.mode = patch.mode
+		if (typeof patch.activeGroup === 'string' && patch.activeGroup.trim() !== '') merged.activeGroup = patch.activeGroup.trim()
+		try {
+			await settings.update(HUB_NS, { routing: merged })
+			return { ok: true, ...smartStateOf() }
+		} catch (error) {
+			return { ok: false, error: `写不进 settings（${error?.message ?? error}）` }
+		}
+	}
+
+	/** 读一个 POST body（JSON）；非法返 null。 */
+	const readPostBody = async (request) => {
+		try {
+			const collected = []
+			for await (const chunk of request) collected.push(chunk)
+			return JSON.parse(Buffer.concat(collected).toString('utf8'))
+		} catch {
+			return null
+		}
+	}
+
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: ROUTING_STATE_PATH,
+		handler: (request, response) => {
+			if (request.method !== 'GET' && request.method !== 'HEAD') {
+				response.writeHead(405, { allow: 'GET, HEAD' })
+				response.end()
+				return
+			}
+			if (!sameOrigin(request)) {
+				sendJson(response, 403, { ok: false, error: 'cross-origin reads are refused' })
+				return
+			}
+			if (request.method === 'HEAD') {
+				response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+				response.end()
+				return
+			}
+			ensureAvailabilityFresh()
+			sendJson(response, 200, smartStateOf())
+		}
+	}), 'dsh-llm-hub: routing state route')
+
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: ROUTING_SELECT_PATH,
+		handler: async (request, response) => {
+			if (request.method !== 'POST') {
+				response.writeHead(405, { allow: 'POST' })
+				response.end()
+				return
+			}
+			if (!sameOrigin(request)) {
+				sendJson(response, 403, { ok: false, error: 'cross-origin writes are refused' })
+				return
+			}
+			const payload = await readPostBody(request)
+			if (payload === null) {
+				sendJson(response, 400, { ok: false, error: '请求内容不是合法 JSON' })
+				return
+			}
+			const result = await applyRoutingSelect({
+				mode: payload?.mode,
+				activeGroup: payload?.activeGroup
+			})
+			sendJson(response, result.ok === true ? 200 : 503, result)
+		}
+	}), 'dsh-llm-hub: routing select route')
+
+	// smart 模式的请求接管。global: true —— 根上下文的监听要覆盖所有 agent
+	// （含子代理），否则「自动按额度切换」只对当前会话生效。
+	// 任何异常都吞掉并返回 next() 的原 config：路由接管必须 fail-open，不能
+	// 因为分组配置写错了一行让会话发不出请求。
+	ctx.on('agent/request', async (payload, next) => {
+		const config = await next()
+		try {
+			if (config === null || typeof config !== 'object') return config
+			const state = routingGroupsOf()
+			if (state.mode !== 'smart' || state.groups.length === 0) return config
+			const group = state.groups.find((candidate) => candidate.id === state.activeGroup) ?? state.groups[0]
+			const candidates = [
+				...(group.primary !== null ? [group.primary] : []),
+				...group.fallbacks
+			]
+			const active = { provider: config.provider, model: config.model }
+			const decision = pickSmartRoute(candidates, (provider) => stateFor(provider, ''), active)
+			lastSmartDecision.at = Date.now()
+			lastSmartDecision.group = group.id
+			lastSmartDecision.from = active
+			lastSmartDecision.to = decision.to
+			lastSmartDecision.reason = decision.reason
+			if (decision.switched !== true || decision.to === null) return config
+			return { ...config, provider: decision.to.provider, model: decision.to.model }
+		} catch (error) {
+			ctx.logger.warn(`dsh-llm-hub: smart routing intercept failed, keeping original config: ${error?.message ?? error}`)
+			return config
+		}
+	}, { global: true })
+
 	// ── 模型别名 ──────────────────────────────────────────────────────────────
 	//
 	// settings.dsh-llm-hub.aliases：把长 model id 映射成短显示名，典型场景：
@@ -2344,8 +2730,13 @@ export function apply(ctx) {
 	 * @returns 规范化后的别名表（空值 / 非法 key 全过滤掉）。
 	 */
 	const aliasesOf = () => {
-		const section = sectionOf() ?? {}
-		const raw = section.aliases !== null && typeof section.aliases === 'object' ? section.aliases : {}
+		// 真源是 dsh-llm-hub 段（1.5.0 注册）；legacy llm-deepseek 段只补缺。
+		const hub = hubSectionOf() ?? {}
+		const legacy = sectionOf() ?? {}
+		const raw = {
+			...(legacy.aliases !== null && typeof legacy.aliases === 'object' ? legacy.aliases : {}),
+			...(hub.aliases !== null && typeof hub.aliases === 'object' ? hub.aliases : {})
+		}
 		const out = {}
 		for (const [key, value] of Object.entries(raw)) {
 			if (!ALIAS_KEY_RE.test(key)) continue
@@ -2392,55 +2783,6 @@ export function apply(ctx) {
 		}
 	}), 'dsh-llm-hub: aliases route')
 
-	/**
-	 * KeyPool 调试路由 —— 让 client 看到每个 provider 当前轮到了哪个 entry。
-	 * 不暴露 apiKey 实际值（只有 name + env 名）；401 / 403 类失败时用户从
-	 * 这里看「轮到哪个 env 上次失败」，下次请求轮换过去。
-	 */
-	const keyPoolDebugPayload = () => {
-		const section = sectionOf() ?? {}
-		const raw = section.keyPool
-		const pool = raw !== null && typeof raw === 'object' ? raw : {}
-		const providers = []
-		for (const [provider, entries] of Object.entries(pool)) {
-			if (!Array.isArray(entries)) continue
-			const lastChosen = keyPoolLastChosen.current.get(provider)
-			providers.push({
-				provider,
-				total: entries.length,
-				lastChosen: lastChosen === undefined ? null : {
-					name: lastChosen.entry.name,
-					env: lastChosen.entry.env,
-					index: lastChosen.index,
-					at: lastChosen.at
-				},
-				nextIndex: keyPoolIndex.current.get(provider) ?? 0
-			})
-		}
-		return { ok: true, providers }
-	}
-
-	ctx.effect(() => ctx.webServer.register({
-		kind: 'exact',
-		path: KEYPOOL_STATUS_PATH,
-		handler: (request, response) => {
-			if (request.method !== 'GET' && request.method !== 'HEAD') {
-				response.writeHead(405, { allow: 'GET, HEAD' })
-				response.end()
-				return
-			}
-			if (!sameOrigin(request)) {
-				sendJson(response, 403, { ok: false, error: 'cross-origin reads are refused' })
-				return
-			}
-			if (request.method === 'HEAD') {
-				response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
-				response.end()
-				return
-			}
-			sendJson(response, 200, keyPoolDebugPayload())
-		}
-	}), 'dsh-llm-hub: keypool status route')
 
 	// ── harness 子代理 ────────────────────────────────────────────────────────