@dsh-plugins/dsh-llm-hub 0.7.3 → 1.3.0

package/lib/index.js

@@ -35,13 +35,90 @@ import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { applyHarness, harnessReport } from './harness.js'
 
+/**
+ * 用量统计 domain 的 spec。
+ *
+ * 必须是模块顶层的 const —— storageDomain 的 domain name + version 在 apply 之外
+ * 就被多处复用（spec 自检、清理路由、导出 CSV 的列顺序），放到 apply 里会逼着每次
+ * 都重建。
+ *
+ * schema 字段固定下来后**不要**再加可空字段 —— 上游 schema 升级要走 storageDomain 的
+ * version + compatibleVersions 机制（见 `defineDomain` 文档），不在记录里堆空字段。
+ */
+export const UsageRecordSchema = Object.freeze({
+	id: 'string',
+	provider: 'string',
+	model: 'string',
+	at: 'number',
+	inputTokens: 'number',
+	outputTokens: 'number',
+	cacheReadTokens: 'number',
+	cacheWriteTokens: 'number',
+	totalTokens: 'number',
+	finished: 'boolean'
+})
+
+/**
+ * 解析 `llm/stream` 的 usage chunk 字段为正数。
+ *
+ * 上游字段可能 undefined / 字符串 / NaN —— 全部折成数字或 0。
+ * `negative tokens` 没有意义，clamp 到 0（实测 anthropic-messages 在 0 token 完成时偶尔报 0，
+ * 而不是负数；但缓存命中时 cache_read 可能报超大值，得兜住）。
+ * @param usage - 上游的 usage 字段。
+ * @returns 归一化后的数字字段。
+ */
+export function normalizeUsageForTest(usage) {
+	const pick = (value) => {
+		if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return 0
+		return Math.floor(value)
+	}
+	return {
+		inputTokens: pick(usage?.inputTokens),
+		outputTokens: pick(usage?.outputTokens),
+		cacheReadTokens: pick(usage?.cacheReadTokens),
+		cacheWriteTokens: pick(usage?.cacheWriteTokens),
+		totalTokens: pick(usage?.totalTokens)
+	}
+}
+const normalizeUsage = normalizeUsageForTest
+
+/**
+ * 把一条用量记录写进指定 table —— 测试桩可以直接调，绕开 storageDomain open。
+ *
+ * 与 observer 写记录的字段保持一致；id 用时间戳 + 随机后缀避免同一毫秒冲突。
+ * @param table - 任意带 put 的 KV（真 storageDomain table 或内存桩都行）。
+ * @param entry - 与 observer 写记录相同的入参形态。
+ * @returns 写入的记录 id。
+ */
+export function recordUsageInto(table, entry) {
+	const id = `${entry.at}-${Math.random().toString(36).slice(2, 10)}`
+	table.put(id, {
+		id,
+		provider: entry.provider,
+		model: entry.model,
+		at: entry.at,
+		inputTokens: entry.usage.inputTokens,
+		outputTokens: entry.usage.outputTokens,
+		cacheReadTokens: entry.usage.cacheReadTokens,
+		cacheWriteTokens: entry.usage.cacheWriteTokens,
+		totalTokens: entry.usage.totalTokens,
+		finished: entry.finished
+	})
+	return id
+}
+
 const NS = 'llm-deepseek'
 /** 适配器自身的公网端点默认值。 */
 const DEFAULT_BASE_URL = 'https://api.deepseek.com'
 /** 适配器自身的凭据引用默认值。 */
 const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY'
 /** 调用方给的端点不得让我们无上限缓冲。 */
-const MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+/**
+ * 单个响应体的字节上限。网关可能返回超大 body（异常、被劫持、或对端 bug），
+ * 不设上限会把宿主内存打爆 —— DSH 是常驻进程，一次就够。
+ * 导出是为了测试能断言这个边界：变异测试确认过，改掉它而无测试失败等于没护栏。
+ */
+export const MAX_RESPONSE_BYTES = 4 * 1024 * 1024
 /** client 半读取余额的路由。 */
 const BALANCE_PATH = '/api/dsh-llm-hub/balance'
 /** 官方 pi-ai 适配器拥有的 settings 命名空间；这里只旁路读取，绝不注册 discovery。 */
@@ -58,10 +135,75 @@ const HARNESS_PATH = '/api/dsh-llm-hub/harness'
 /** 模型下拉可用性：读缓存 / 强制全量重探。 */
 const AVAILABILITY_PATH = '/api/dsh-llm-hub/availability'
 const AVAILABILITY_RECHECK_PATH = '/api/dsh-llm-hub/availability/recheck'
+/**
+ * 健康看板路由 —— 跟 availability 同一份数据，承诺的字段更全：
+ * - providers[].latencyMs：探测耗时（健康看板要看的延迟）
+ * - providers[].status：上游 HTTP 状态码（401 / 403 / 402 / 5xx 一眼可分）
+ * availability 路由沿用旧响应（向后兼容，老 client 不会炸）。
+ */
+const HEALTH_PATH = '/api/dsh-llm-hub/health'
+/**
+ * 用量统计：月度聚合 + 清除。
+ *
+ * 存储走 storageDomain —— 这是 DSH 的官方本地持久化服务，本插件依赖它写一条
+ * per-call 记录（provider / model / input / output / cacheRead / cacheWrite /
+ * 时间戳），路由层做月度聚合（按本地日历月，不是 UTC 月 —— 用户看的是「本月花了多少」）。
+ * 钱不在这算：开源 DSH 的 llm 服务只暴露 imageRequestPricing，没有 chat 文本定价接口，
+ * 强行给每个 provider 写硬编码价目表既过时又快塌。把 token 用量留给用户自己对照官方价目表，
+ * 导出见 `GET /api/dsh-llm-hub/usage/export`（CSV）。
+ */
+const USAGE_SUMMARY_PATH = '/api/dsh-llm-hub/usage/summary'
+const USAGE_EXPORT_PATH = '/api/dsh-llm-hub/usage/export'
+const USAGE_CLEAR_PATH = '/api/dsh-llm-hub/usage/clear'
+/**
+ * 余额预警：客户端把当前余额信封 POST 进来，host 半按 settings 阈值判定是否低于红线。
+ * 阈值不直接暴露前端 —— 一是数字本身没多大用，二是怕人改 settings 把阈值关掉再回来说没提示。
+ */
+const WARNING_CHECK_PATH = '/api/dsh-llm-hub/warning/check'
+/**
+ * 智能路由建议：把当前可用性 + 用户声明的 fallback 顺序折成「该用哪个」。
+ *
+ * **不做自动切换** —— DSH 的 `conversation.input.model` 是 single + user-controlled
+ * slot（`replaceRisk: shadows-shipped-ui`），没有供插件改的 setter；强行覆盖会
+ * 撞 README 红线。这条路由返回的是**建议**，真值为用户在 UI 里点一下。
+ *
+ * 请求体：当前已激活用户的 provider/model（如 'modelgo' / 'gpt-4o'），返回：
+ *   {
+ *     ok: true,
+ *     active: { provider, model, state: 'available'|'unknown'|'unavailable' },
+ *     candidates: [{ provider, model, state, ... }, ...],   // 主 → fallback → 备用
+ *     recommendation: { provider, model } | null,            // 第一个 available 的
+ *     reason: '...'                                          // 拿不到 recommendation 时
+ *   }
+ */
+const ROUTING_RESOLVE_PATH = '/api/dsh-llm-hub/routing/resolve'
+/** 模型别名：客户端渲染 model id 时显示短名（典型场景：deepseek-reasoner → 推理）。 */
+const ALIASES_PATH = '/api/dsh-llm-hub/aliases'
+/**
+ * 多账号 key 轮换：settings.dsh-llm-hub.keyPool[provider] 是 entry 数组。
+ *
+ * 设计取舍：
+ *   - **向后兼容**：未配 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。
+ */
+const KEYPOOL_STATUS_PATH = '/api/dsh-llm-hub/keypool/status'
+/** 路由配置从 settings 哪一段读 —— 顶层 dsh-llm-hub 段下，与 warning 同级。 */
+const ROUTING_KEY = 'routing'
 /** 探针结论的保鲜期；过期后下次读取顺手在后台重探，不阻塞下拉。 */
-const AVAILABILITY_TTL_MS = 5 * 60 * 1000
+/** 可用性缓存有效期。太长则换了 key 还在报旧状态，太短则每次开设置页都打一圈网关。 */
+export const AVAILABILITY_TTL_MS = 5 * 60 * 1000
 /** 一轮探测最长允许在途的时间；超过就允许再开一轮（超时兜底的兜底）。 */
-const STUCK_PROBE_MS = 60 * 1000
+/** 超过这个时间仍未结束的探测视为卡死，允许重新发起 —— 否则一次卡死永久占住槽位。 */
+export const STUCK_PROBE_MS = 60 * 1000
 /** 运行期失败标记的保鲜期：充值/续期后不必等手动刷新。 */
 const RUNTIME_TTL_MS = 10 * 60 * 1000
 /**
@@ -71,7 +213,8 @@ const RUNTIME_TTL_MS = 10 * 60 * 1000
  * 于是 `probing` 一直 true、判定再也不刷新 —— 表现为「面板停在旧结论上，下拉跟着旧结论走」。
  * 2026-09-16 实测踩到过一次。
  */
-const REQUEST_TIMEOUT_MS = 6000
+/** 单次外部请求超时。网关不响应时不能让探测挂死，否则 UI 一直转圈。 */
+export const REQUEST_TIMEOUT_MS = 6000
 /**
  * 给一次外部请求加超时，并保留调用方自己的取消。
  * @param signal - 调用方取消信号（可选）。
@@ -165,7 +308,7 @@ function readListing(body) {
  * @returns 解码后的正文。
  * @throws {Error} 当正文超过 {@link MAX_RESPONSE_BYTES} 时。
  */
-async function readBounded(response, url) {
+export async function readBounded(response, url) {
 	const oversized = () => new Error(`${url} answered with more than ${MAX_RESPONSE_BYTES} bytes`)
 	const declared = Number(response.headers.get('content-length') ?? NaN)
 	if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
@@ -214,7 +357,12 @@ function sendJson(response, status, payload) {
 }
 
 export const name = 'dsh-llm-hub'
-/** 发现注册表在 llm 服务上；余额路由在 webServer 上。两者都是硬依赖。 */
+/**
+ * 硬依赖：llm（注册发现 + 监听 llm/stream + 过滤 listProviders）、webServer（HTTP 路由）。
+ *
+ * 用量统计走的是**局部注入**：`storageDomain` 缺席时不报错，本插件其余功能照常工作
+ * —— 没有 storageDomain 也能用余额/可用性/harness，只是没法跨会话记 token 用量。
+ */
 export const inject = ['llm', 'webServer']
 
 /**
@@ -242,6 +390,84 @@ export function apply(ctx) {
 		}
 	}
 
+	/**
+	 * 余额预警阈值（按 provider / kind）。
+	 *
+	 * 设置来源：`dsh-llm-hub` 段下的 `warning` 子对象，形如：
+	 *   dsh-llm-hub:
+	 *     warning:
+	 *       deepseek-official: { cashCNY: 10 }
+	 *       minimax: { planPercent: 10 }
+	 *
+	 * 单位说明：
+	 *   - `cashCNY`：CNY 现金余额下限，低于此值红色警告。默认 10 元。
+	 *   - `planPercent`：plan 配额「余量」下限，低于此值红色警告。默认 10%。
+	 *
+	 * 阈值不暴露给前端 —— 客户端只渲染「是否低于阈值 + 该充钱了」的二元判断；
+	 * 数字本身留在 host 半，跨域读取会把它推走不是用户的本意。
+	 *
+	 * @returns 阈值表，未配置时返回默认值。
+	 */
+	const warningThresholds = () => {
+		const section = sectionOf() ?? {}
+		const warning = section.warning !== null && typeof section.warning === 'object' ? section.warning : {}
+		const readNumber = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
+		return {
+			cashCNY: readNumber(warning.cashCNY, 10),
+			planPercent: readNumber(warning.planPercent, 10)
+		}
+	}
+
+	/**
+	 * 按 provider id + 余额信封判断「是否低于阈值、显示什么文案」。
+	 *
+	 * cash 类（DeepSeek 官方直连 / moonshot / stepfun 等）：
+	 *   primary currency 是 CNY 时按 cashCNY 比，金额作为数字；
+	 *   非 CNY 时按 USD 1 元近似换算（保守提示）。
+	 * plan 类（minimax / zhipu 配额）：任一 item 的 percent < planPercent 即触发。
+	 *
+	 * 没匹配到 kind / 缺数字 → 返回 null（不显示警告）。
+	 * @param provider - 段内键名。
+	 * @param balance - 余额信封（PiAiCard 走的形态）。
+	 * @param total - DeepSeek 官方直连 primary.total 字符串。
+	 * @param currency - DeepSeek 官方直连 primary.currency。
+	 * @returns 警告文本或 null。
+	 */
+	const warningFor = (provider, balance, total, currency) => {
+		const thresholds = warningThresholds()
+		if (balance !== undefined && balance !== null) {
+			if (balance.kind === 'cash' && Array.isArray(balance.items) && balance.items.length > 0) {
+				const first = balance.items[0]
+				const amountStr = typeof first?.amount === 'string' ? first.amount : ''
+				const amount = Number(amountStr)
+				if (Number.isFinite(amount) && amount <= thresholds.cashCNY) {
+					return { level: 'low', text: `${provider} 余额 ${amountStr} 低于 ${thresholds.cashCNY}，充值一下` }
+				}
+			}
+			if ((balance.kind === 'plan' || balance.kind === 'quota') && Array.isArray(balance.items)) {
+				for (const item of balance.items) {
+					if (typeof item?.percent !== 'number') continue
+					if (item.percent < thresholds.planPercent) {
+						return { level: 'low', text: `${provider} ${item.label ?? '配额'} 余 ${item.percent}% 低于 ${thresholds.planPercent}%` }
+					}
+				}
+			}
+		}
+		if (typeof total === 'string' && currency === 'CNY') {
+			const value = Number(total)
+			if (Number.isFinite(value) && value <= thresholds.cashCNY) {
+				return { level: 'low', text: `DeepSeek 余额 ¥${total} 低于 ${thresholds.cashCNY}，充值一下` }
+			}
+		}
+		if (typeof total === 'string' && currency === 'USD') {
+			const value = Number(total)
+			if (Number.isFinite(value) && value <= 1) {
+				return { level: 'low', text: `DeepSeek 余额 $${total} 已不足 1 美元，充值一下` }
+			}
+		}
+		return null
+	}
+
 	/**
 	 * 巡检 settings 段里 `models: []` 的 provider，去对应网关拉一份目录写回。
 	 * 启动时跑一次，避免 settings.yaml 里留 `models: []` 这个事实空头；下次 reload / 重启
@@ -279,9 +505,60 @@ export function apply(ctx) {
 		return updates
 	}
 
+	/**
+	 * 读 `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 位置。
+	 */
+	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 }
+	}
+
 	/**
 	 * 解析本次调用要用的连接事实。
-	 * @param request - 可选的一次性覆盖（发现草稿会带 baseURL / apiKey）。
+	 *
+	 * 解析顺序（向后兼容）：
+	 *   1) request.apiKey 一次性覆盖 —— 跳过轮换、原样返回（不污染索引）
+	 *   2) keyPool[provider] 命中 → round-robin 取下一个，env var 解析密钥
+	 *   3) 旧的 `apiKeyEnv` 单 key 路径（行为完全不变）
+	 *
+	 * 返 ref 不变 —— 客户端拿到的是凭据引用（keyPool 的 env 名），实际值是
+	 * `process.env[ref]` 解出来的字符串；下游诊断（探针 / 余额路由）能继续
+	 * 看到当前用的是哪个 env。
+	 * @param request - 可选的一次性覆盖（发现草稿会带 baseURL / apiKey / provider）。
 	 * @returns baseURL、凭据引用与可用密钥。
 	 */
 	const connectionFacts = async (request = {}) => {
@@ -292,15 +569,26 @@ export function apply(ctx) {
 			process.env.DEEPSEEK_BASE_URL,
 			DEFAULT_BASE_URL
 		) ?? DEFAULT_BASE_URL).replace(/\/+$/, '')
-		const ref = label(request.apiKeyEnv, section.apiKeyEnv) ?? DEFAULT_API_KEY_ENV
 		const explicit = label(request.apiKey)
-		let apiKey = explicit
-		if (apiKey === undefined) {
-			const credentials = ctx.get('credentials')
-			if (credentials !== undefined) {
-				const hit = await credentials.resolve(ref)
-				apiKey = label(hit?.value)
-			}
+		if (explicit !== undefined) {
+			// 一次性覆盖：保留旧 ref 行为（client.js 的 request.apiKeyEnv 兜底）。
+			const ref = label(request.apiKeyEnv, section.apiKeyEnv) ?? DEFAULT_API_KEY_ENV
+			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
+		let apiKey
+		const credentials = ctx.get('credentials')
+		if (credentials !== undefined) {
+			const hit = await credentials.resolve(ref)
+			apiKey = label(hit?.value)
 		}
 		if (apiKey === undefined) apiKey = label(process.env[ref])
 		return { baseURL, ref, apiKey }
@@ -946,36 +1234,38 @@ export function apply(ctx) {
 			return { state: 'unavailable', code: 'CREDENTIAL_MISSING', source: 'credential', reason: `没配 API key（${ref} 解析不到），请求会直接失败` }
 		}
 		const url = `${baseURL}/models`
+		const startedAt = Date.now()
 		let response
 		try {
 			response = await fetch(url, { method: 'GET', headers: { accept: 'application/json', authorization: `Bearer ${apiKey}` }, signal: timeoutSignal() })
 		} catch (error) {
-			return { state: 'unknown', code: 'UNREACHABLE', source: 'probe', reason: `探测不到 ${baseURL}：${describeError(error)}` }
+			return { state: 'unknown', code: 'UNREACHABLE', source: 'probe', reason: `探测不到 ${baseURL}：${describeError(error)}`, latencyMs: Date.now() - startedAt }
 		}
+		const latencyMs = Date.now() - startedAt
 		if (response.status === 401 || response.status === 403) {
-			return { state: 'unavailable', code: 'AUTH_REJECTED', source: 'probe', reason: `API key 被拒（HTTP ${response.status}）` }
+			return { state: 'unavailable', code: 'AUTH_REJECTED', source: 'probe', status: response.status, reason: `API key 被拒（HTTP ${response.status}）`, latencyMs }
 		}
 		if (response.status === 402) {
-			return { state: 'unavailable', code: 'PAYMENT_REQUIRED', source: 'probe', reason: '账户欠费（HTTP 402）' }
+			return { state: 'unavailable', code: 'PAYMENT_REQUIRED', source: 'probe', status: response.status, reason: '账户欠费（HTTP 402）', latencyMs }
 		}
 		if (!response.ok && response.status !== 404) {
-			return { state: 'unknown', code: 'HTTP_ERROR', source: 'probe', reason: `${url} 返回 HTTP ${response.status}` }
+			return { state: 'unknown', code: 'HTTP_ERROR', source: 'probe', status: response.status, reason: `${url} 返回 HTTP ${response.status}`, latencyMs }
 		}
 		// 余额：官方直连有公开的 /user/balance，is_available=false 就是「调不了」。
 		// 查不通不构成隐藏理由 —— 那只说明余额接口这次没通。
 		try {
 			const body = shapeBalance(await getJson('/user/balance'))
 			if (body.isAvailable !== true) {
-				return { state: 'unavailable', code: 'ACCOUNT_UNAVAILABLE', source: 'balance', reason: '账户不可用（/user/balance 报 is_available=false）' }
+				return { state: 'unavailable', code: 'ACCOUNT_UNAVAILABLE', source: 'balance', reason: '账户不可用（/user/balance 报 is_available=false）', latencyMs }
 			}
 			const total = Number(body.balances[0]?.total ?? NaN)
 			if (Number.isFinite(total) && total <= 0) {
-				return { state: 'unavailable', code: 'BALANCE_EMPTY', source: 'balance', reason: '账户余额为 0' }
+				return { state: 'unavailable', code: 'BALANCE_EMPTY', source: 'balance', reason: '账户余额为 0', latencyMs }
 			}
 		} catch {
 			// 静默：余额查不通 ≠ 模型不可用
 		}
-		return { state: 'available', code: 'OK', source: 'probe', reason: '' }
+		return { state: 'available', code: 'OK', source: 'probe', reason: '', latencyMs }
 	}
 
 	/**
@@ -1034,22 +1324,26 @@ export function apply(ctx) {
 			return { state: 'unavailable', code: 'CREDENTIAL_MISSING', source: 'credential', reason: `apiKeyEnv 指向的 ${ref} 解析不到，请求会直接失败` }
 		}
 		const listing = await piaiListing(profile, {}, provider)
+		const latencyMs = typeof listing.latencyMs === 'number' ? listing.latencyMs : undefined
 		if (!listing.ok && listing.code === 'HTTP_ERROR') {
 			if (listing.status === 401 || listing.status === 403) {
-				return { state: 'unavailable', code: 'AUTH_REJECTED', source: 'probe', reason: `网关拒绝了这个 key（HTTP ${listing.status}）` }
+				return { state: 'unavailable', code: 'AUTH_REJECTED', source: 'probe', status: listing.status, reason: `网关拒绝了这个 key（HTTP ${listing.status}）`, latencyMs }
 			}
 			if (listing.status === 402) {
-				return { state: 'unavailable', code: 'PAYMENT_REQUIRED', source: 'probe', reason: '网关要求付费（HTTP 402）' }
+				return { state: 'unavailable', code: 'PAYMENT_REQUIRED', source: 'probe', status: listing.status, reason: '网关要求付费（HTTP 402）', latencyMs }
 			}
-			return { state: 'unknown', code: 'HTTP_ERROR', source: 'probe', reason: `网关返回 HTTP ${listing.status}` }
+			return { state: 'unknown', code: 'HTTP_ERROR', source: 'probe', status: listing.status, reason: `网关返回 HTTP ${listing.status}`, latencyMs }
 		}
 		const exhausted = await exhaustedFromBalance(provider)
-		if (exhausted !== undefined) return exhausted
+		if (exhausted !== undefined) {
+			if (latencyMs !== undefined) exhausted.latencyMs = latencyMs
+			return exhausted
+		}
 		if (!listing.ok) {
 			// 404 / 连不上 / 协议不支持目录端点 —— 都不足以断言模型不可用。
-			return { state: 'unknown', code: listing.code ?? 'PROBE_UNKNOWN', source: 'probe', reason: listing.error ?? '网关探测无结论' }
+			return { state: 'unknown', code: listing.code ?? 'PROBE_UNKNOWN', source: 'probe', reason: listing.error ?? '网关探测无结论', latencyMs }
 		}
-		return { state: 'available', code: 'OK', source: 'probe', reason: '' }
+		return { state: 'available', code: 'OK', source: 'probe', reason: '', latencyMs }
 	}
 
 	/**
@@ -1241,10 +1535,40 @@ export function apply(ctx) {
 
 	ctx.on('llm/stream', (options, next) => {
 		const provider = typeof options?.provider === 'string' ? options.provider : undefined
+		const modelId = typeof options?.model === 'string' ? options.model : ''
 		const inner = next()
 		if (provider === undefined) return inner
+		// 用量聚合：usage chunk 可能在 finish 之前或同时到达。
+		// 累积（而非只留最后一次）—— 部分 provider 会先发 cached tokens 的 usage、
+		// 再发最终的 output tokens usage，两次叠加才是这轮的真实成本。
+		let usageAccum = null
+		const onFinish = (finished) => {
+			try {
+				recordUsage({
+					provider,
+					model: modelId,
+					at: Date.now(),
+					usage: usageAccum ?? { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: 0 },
+					finished
+				})
+			} catch {
+				// 记不上就算了，不能因为记账把流弄坏
+			}
+		}
 		return (async function* observeProviderOutcome() {
 			for await (const chunk of inner) {
+				if (chunk?.type === 'usage') {
+					const normalized = normalizeUsage(chunk.usage)
+					usageAccum = usageAccum === null
+						? normalized
+						: {
+							inputTokens: usageAccum.inputTokens + normalized.inputTokens,
+							outputTokens: usageAccum.outputTokens + normalized.outputTokens,
+							cacheReadTokens: usageAccum.cacheReadTokens + normalized.cacheReadTokens,
+							cacheWriteTokens: usageAccum.cacheWriteTokens + normalized.cacheWriteTokens,
+							totalTokens: Math.max(usageAccum.totalTokens, normalized.totalTokens)
+						}
+				}
 				if (chunk?.type === 'finish') {
 					try {
 						const kind = chunk.reason?.kind
@@ -1252,9 +1576,11 @@ export function apply(ctx) {
 						if (kind === 'error' || kind === 'aborted') {
 							const classified = classifyFailure(chunk.reason?.failure)
 							if (classified !== undefined) runtimeMarks.set(provider, { ...classified, at: Date.now() })
+							onFinish(false)
 						} else {
 							successAt.set(provider, Date.now())
 							runtimeMarks.delete(provider)
+							onFinish(true)
 						}
 						announceHiddenChange(before)
 					} catch {
@@ -1369,6 +1695,35 @@ export function apply(ctx) {
 		}
 	}), 'dsh-llm-hub: availability route')
 
+	// 健康看板：复用 availability 数据，附加 latencyMs / status 字段。
+	// 触发重探是异步的、不阻塞响应 —— 用户点重探看到 loading，点完了切回稳态。
+	const healthPayload = () => {
+		const payload = availabilityPayload()
+		ensureAvailabilityFresh()
+		return payload
+	}
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: HEALTH_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, healthPayload())
+		}
+	}), 'dsh-llm-hub: health route')
+
 	ctx.effect(() => ctx.webServer.register({
 		kind: 'exact',
 		path: AVAILABILITY_RECHECK_PATH,
@@ -1430,20 +1785,627 @@ export function apply(ctx) {
 		})()
 	})
 
-	// ── harness 子代理 ────────────────────────────────────────────────────────
+	// ── 用量统计 ────────────────────────────────────────────────────────────
 	//
-	// 把本机装好的外部 agent CLI（codex / claude / agy）注册成子代理提供方，详见
-	// `./harness.js`。
+	// 每次真实模型调用都记一条 per-call 记录（provider / model / tokens / 时间），
+	// 通过 storageDomain 落到本机 SQLite。client 半按月聚合展示。
 	//
-	// 为什么用**局部注入**而不是加进模块顶部的 `inject` 数组：`inject` 是硬依赖，
-	// 少一个服务整个插件就不加载 —— 那会让「宿主没装子代理栈」的部署连余额和模型
-	// 发现一起失去。局部注入只让 harness 这一段跟着服务走，缺了就不启用。
-	ctx.inject(['subagents', 'subprocess'], (scope) => {
-		applyHarness(scope).catch((error) => {
-			scope.logger?.warn?.(`dsh-llm-hub: harness 探测失败：${error?.message ?? error}`)
-		})
+	// 与余额/可用性**不**共享失败路径：storageDomain 缺席或损坏只关掉用量统计，
+	// 其余功能照常工作 —— 因此走局部注入，不写进模块顶部的 inject 数组。
+	//
+	// 故意**不**算钱：开源 DSH 的 llm 服务只暴露 imageRequestPricing，没 chat 文本
+	// 定价接口。每个 provider 写硬编码价目表既过时又快塌；把 token 用量留给用户自己
+	// 对照官方价目表，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
+		recordUsageInto(table, entry)
+	}
+
+	ctx.inject(['storageDomain'], async (scope) => {
+		let disposed = false
+		let handle = null
+		try {
+			const sd = await import('@deepseek-ai/dsh-storage-domain')
+			const defineDomain = sd.defineDomain
+			const domainTable = sd.domainTable
+			if (typeof defineDomain !== 'function' || typeof domainTable !== 'function') {
+				throw new Error('dsh-storage-domain exports missing')
+			}
+			// v1：首次发布。schema 字段已稳定（参见顶部的 UsageRecordSchema）。
+			// 上游 schema 升级要走 version bump，不在记录里堆可空字段。
+			const UsageDomain = defineDomain({
+				name: 'dsh_llm_hub_usage',
+				version: 1,
+				tables: {
+					records: domainTable({
+						id: 'string',
+						provider: 'string',
+						model: 'string',
+						at: 'number',
+						inputTokens: 'number',
+						outputTokens: 'number',
+						cacheReadTokens: 'number',
+						cacheWriteTokens: 'number',
+						totalTokens: 'number',
+						finished: 'boolean'
+					})
+				}
+			})
+			const domain = await scope.storageDomain.open(UsageDomain)
+			if (disposed) {
+				domain.close()
+				return
+			}
+			handle = domain
+			usageTable.current = domain.table('records')
+			usageReady.current = true
+			ctx.logger.info('dsh-llm-hub: 用量统计已就绪（按月聚合见 /api/dsh-llm-hub/usage/summary）')
+		} catch (error) {
+			ctx.logger.warn(`dsh-llm-hub: 用量统计未启用：${describeError(error)}`)
+		}
+		// 卸载时关 domain（参照 dsh-user-mirror 的处理：句柄漏了会在 turn/end 炸
+		// "Cannot read properties of undefined (reading 'prepare')"）。
+		return () => {
+			disposed = true
+			usageReady.current = false
+			usageTable.current = null
+			if (handle !== null) {
+				try { handle.close() } catch { /* 关失败即进程退出 */ }
+				handle = null
+			}
+		}
 	})
 
+	/**
+	 * 给一个时间戳算「本地日历月」的起点 —— 用户看的是"本月"，不是 UTC 月。
+	 * 跨年/跨月自动滚到下个月的第一天零点。
+	 * @param timestamp - 任意 ms 时刻。
+	 * @returns 同月零点的 ms 时刻。
+	 */
+	const monthStartOf = (timestamp) => {
+		const d = new Date(timestamp)
+		return new Date(d.getFullYear(), d.getMonth(), 1).getTime()
+	}
+
+	/**
+	 * 把全部记录按月聚合，返回「本月 + 历史月份」两组数据。
+	 * 客户端默认渲染本月；要更长的历史用 export 路由。
+	 * @returns 月度聚合结果。
+	 */
+	const aggregateUsage = () => {
+		const table = usageTable.current
+		if (table === null) return { ready: false, current: null, history: [] }
+		const now = Date.now()
+		const currentMonth = monthStartOf(now)
+		const byMonth = new Map()
+		try {
+			// storageDomain 的 table API：list() 拿全部记录。
+			// 实际签名以 dsh-storage-domain 的 .d.ts 为准 —— 这一行写错了整个聚合就空。
+			const records = typeof table.list === 'function' ? table.list() : []
+			for (const record of records) {
+				if (record === null || typeof record !== 'object') continue
+				const at = typeof record.at === 'number' ? record.at : 0
+				const monthStart = monthStartOf(at)
+				const bucket = byMonth.get(monthStart) ?? {
+					monthStart,
+					calls: 0,
+					inputTokens: 0,
+					outputTokens: 0,
+					cacheReadTokens: 0,
+					cacheWriteTokens: 0,
+					totalTokens: 0,
+					byModel: {}
+				}
+				accumulateInto(bucket, record)
+				byMonth.set(monthStart, bucket)
+			}
+		} catch {
+			// 聚合失败不算账
+		}
+		const months = [...byMonth.values()].sort((left, right) => right.monthStart - left.monthStart)
+		const current = months.find((bucket) => bucket.monthStart === currentMonth) ?? { monthStart: currentMonth, calls: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: 0, byModel: {} }
+		const history = months.filter((bucket) => bucket.monthStart !== currentMonth).slice(0, 12)
+		return {
+			ready: true,
+			current: shapeMonth(current),
+			history: history.map(shapeMonth)
+		}
+	}
+
+	/**
+	 * 月份桶 → 给客户端的序列化形态：按 model 分组排个序（calls 降序），只保留前 5。
+	 * @param bucket - 累计的原始桶。
+	 * @returns 序列化后的月份。
+	 */
+	const shapeMonth = (bucket) => {
+		const byModel = Object.values(bucket.byModel)
+			.sort((left, right) => right.calls - left.calls)
+			.slice(0, 5)
+		return {
+			monthStart: bucket.monthStart,
+			calls: bucket.calls,
+			inputTokens: bucket.inputTokens,
+			outputTokens: bucket.outputTokens,
+			cacheReadTokens: bucket.cacheReadTokens,
+			cacheWriteTokens: bucket.cacheWriteTokens,
+			totalTokens: bucket.totalTokens,
+			topModels: byModel
+		}
+	}
+
+	const accumulateInto = (bucket, record) => {
+		bucket.calls += 1
+		bucket.inputTokens += typeof record.inputTokens === 'number' ? record.inputTokens : 0
+		bucket.outputTokens += typeof record.outputTokens === 'number' ? record.outputTokens : 0
+		bucket.cacheReadTokens += typeof record.cacheReadTokens === 'number' ? record.cacheReadTokens : 0
+		bucket.cacheWriteTokens += typeof record.cacheWriteTokens === 'number' ? record.cacheWriteTokens : 0
+		bucket.totalTokens += typeof record.totalTokens === 'number' ? record.totalTokens : 0
+		const key = `${record.provider}/${record.model}`
+		const slot = bucket.byModel[key] ?? { provider: record.provider, model: record.model, calls: 0, inputTokens: 0, outputTokens: 0 }
+		slot.calls += 1
+		slot.inputTokens += typeof record.inputTokens === 'number' ? record.inputTokens : 0
+		slot.outputTokens += typeof record.outputTokens === 'number' ? record.outputTokens : 0
+		bucket.byModel[key] = slot
+	}
+
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: USAGE_SUMMARY_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, aggregateUsage())
+		}
+	}), 'dsh-llm-hub: usage summary route')
+
+	/**
+	 * 把所有记录导出成 CSV —— 不算钱：留给用户对照官方价目表自己定价。
+	 *
+	 * 字段顺序固定，方便 grep / awk；列名与 summary 路由对齐。
+	 */
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: USAGE_EXPORT_PATH,
+		handler: (request, response) => {
+			if (request.method !== 'GET' && request.method !== 'HEAD') {
+				response.writeHead(405, { allow: 'GET, HEAD' })
+				response.end()
+				return
+			}
+			if (!sameOrigin(request)) {
+				response.writeHead(403, { 'content-type': 'application/json; charset=utf-8' })
+				response.end(JSON.stringify({ ok: false, error: 'cross-origin reads are refused' }))
+				return
+			}
+			const table = usageTable.current
+			if (table === null) {
+				response.writeHead(503, { 'content-type': 'application/json; charset=utf-8' })
+				response.end(JSON.stringify({ ok: false, error: '用量统计未启用' }))
+				return
+			}
+			if (request.method === 'HEAD') {
+				response.writeHead(200, { 'content-type': 'text/csv; charset=utf-8' })
+				response.end()
+				return
+			}
+			let records = []
+			try {
+				records = typeof table.list === 'function' ? table.list() : []
+			} catch {
+				records = []
+			}
+			const header = 'id,provider,model,at,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,total_tokens,finished\n'
+			const escape = (value) => {
+				const text = String(value ?? '')
+				return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text
+			}
+			const lines = records.map((record) => [
+				escape(record.id),
+				escape(record.provider),
+				escape(record.model),
+				record.at ?? 0,
+				record.inputTokens ?? 0,
+				record.outputTokens ?? 0,
+				record.cacheReadTokens ?? 0,
+				record.cacheWriteTokens ?? 0,
+				record.totalTokens ?? 0,
+				record.finished === true ? 'true' : 'false'
+			].join(','))
+			response.writeHead(200, {
+				'content-type': 'text/csv; charset=utf-8',
+				'content-disposition': `attachment; filename="dsh-llm-hub-usage-${new Date().toISOString().slice(0, 10)}.csv"`,
+				'cache-control': 'no-store'
+			})
+			response.end(header + lines.join('\n') + (lines.length > 0 ? '\n' : ''))
+		}
+	}), 'dsh-llm-hub: usage export route')
+
+	/**
+	 * 清空用量记录 —— 显式 POST，避免被预取/前进后退误触发。
+	 */
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: USAGE_CLEAR_PATH,
+		handler: (request, response) => {
+			if (request.method !== 'POST') {
+				response.writeHead(405, { allow: 'POST' })
+				response.end()
+				return
+			}
+			if (!sameOrigin(request)) {
+				response.writeHead(403, { 'content-type': 'application/json; charset=utf-8' })
+				response.end(JSON.stringify({ ok: false, error: 'cross-origin writes are refused' }))
+				return
+			}
+			const table = usageTable.current
+			if (table === null) {
+				response.writeHead(503, { 'content-type': 'application/json; charset=utf-8' })
+				response.end(JSON.stringify({ ok: false, error: '用量统计未启用' }))
+				return
+			}
+			let removed = 0
+			try {
+				const records = typeof table.list === 'function' ? table.list() : []
+				for (const record of records) {
+					if (record?.id === undefined) continue
+					table.delete(record.id)
+					removed += 1
+				}
+			} catch (error) {
+				response.writeHead(500, { 'content-type': 'application/json; charset=utf-8' })
+				response.end(JSON.stringify({ ok: false, error: describeError(error) }))
+				return
+			}
+			response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+			response.end(JSON.stringify({ ok: true, removed }))
+		}
+	}), 'dsh-llm-hub: usage clear route')
+
+	/**
+	 * 余额预警判定 —— 客户端把当前余额信封 POST 进来，host 半返回
+	 * 「是否低于阈值 + 人话提示」。
+	 *
+	 * 请求体形态（任一字段缺失都按 null 处理）：
+	 *   {
+	 *     provider: 'deepseek-official' | 'minimax' | 'moonshot' | ...,
+	 *     // 任选一种：
+	 *     deepseek: { total: '8.50', currency: 'CNY' },           // 官方直连 cash
+	 *     envelope: { ok: true, kind: 'cash'|'plan'|'quota', items: [...] }  // pi-ai
+	 *   }
+	 *
+	 * 响应：`{ ok, level: 'low'|null, text: '...', thresholds: { cashCNY, planPercent } }`。
+	 * 阈值不在响应里：客户端不需要数字本身，只判定是否警告。
+	 */
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: WARNING_CHECK_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
+			}
+			let payload
+			try {
+				const collected = []
+				for await (const chunk of request) collected.push(chunk)
+				payload = JSON.parse(Buffer.concat(collected).toString('utf8'))
+			} catch {
+				sendJson(response, 400, { ok: false, error: '请求内容不是合法 JSON' })
+				return
+			}
+			const provider = typeof payload?.provider === 'string' ? payload.provider : ''
+			const deepseekTotal = typeof payload?.deepseek?.total === 'string' ? payload.deepseek.total : ''
+			const deepseekCurrency = typeof payload?.deepseek?.currency === 'string' ? payload.deepseek.currency : ''
+			const envelope = payload?.envelope
+			const warn = warningFor(provider, envelope, deepseekTotal, deepseekCurrency)
+			sendJson(response, 200, {
+				ok: true,
+				level: warn?.level ?? null,
+				text: warn?.text ?? null
+			})
+		}
+	}), 'dsh-llm-hub: warning check route')
+
+	// ── 智能路由建议 ─────────────────────────────────────────────────────────
+	//
+	// 用户在 settings 里声明 `routing.primary` + `routing.fallbacks[]`，host 半按
+	// 当前可用性判定，给出「该用哪个」。**只建议，不替用户点** —— DSH 的
+	// `conversation.input.model` 是 single + user-controlled slot，没有供插件
+	// 改值的 setter；强行覆盖会撞 README 红线（`replaceRisk: shadows-shipped-ui`）。
+	//
+	// 设计取舍：
+	//   - 配置形态：「provider/model」字符串数组，与 pi-ai 段内 provider 键名 + 已配
+	//     model id 对齐；不正则解析，避免「用户写 'minimax'」在 settings 改后无法识别。
+	//   - 判定顺序：primary → fallbacks[]；任一 available 的就是 recommendation。
+	//   - 全不可用：返 null + reason「全部不可用」，让 UI 显示而不要 fallback 兜底。
+	//   - 主动查询当前用户已选的（POST 进来），把它的状态塞进 active 字段 —— UI 用
+	//     这个渲染「你现在用的 X 不可用了，点这里切到 Y」的引导。
+	const ROUTE_KEY_RE = /^[a-z0-9][a-z0-9_-]*$/i
+	// model id 放宽一点：DSH 真实 id 会含 '.'（claude-3.5-sonnet、deepseek-reasoner 之类）。
+	// 还是禁掉 '/' '/' 与空白（避免再被切回去当路由），其他字符都放行。
+	const ROUTE_MODEL_RE = /^[a-z0-9][a-z0-9_.+-]*$/i
+
+	/**
+	 * 解析「provider/model」字符串。
+	 * @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 }
+	}
+
+	/**
+	 * 读 `routing.primary` + `routing.fallbacks[]`。
+	 * @returns 配置好的顺序数组（primary 在前），无效项过滤掉。空数组表示未配置。
+	 */
+	const routingCandidatesOf = () => {
+		const section = sectionOf() ?? {}
+		const routing = section[ROUTING_KEY] !== null && typeof section[ROUTING_KEY] === 'object' ? section[ROUTING_KEY] : {}
+		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)
+		}
+		return out
+	}
+
+	/**
+	 * 给一个 (provider, model) 找它在当前可用性表里的判定。
+	 * @param provider - provider id。
+	 * @param model - model id。
+	 * @returns 该组合的 state（unknown / unavailable / available），未探测到为 'unknown'。
+	 */
+	const stateFor = (provider, model) => {
+		// 直接去 baseVerdicts 拿 —— availability payload 是这个的视图。
+		for (const verdict of baseVerdicts.values()) {
+			if (verdict.provider === provider) return verdict.state
+		}
+		return 'unknown'
+	}
+
+	/**
+	 * 路由解析：给客户端返回「该用哪个 + 原因」。
+	 * @param active - 客户端 POST 进来的当前已激活 (provider, model)。
+	 * @returns 路由建议载荷。
+	 */
+	const resolveRoute = (active) => {
+		const candidates = routingCandidatesOf()
+		const verdicts = new Map()
+		for (const candidate of candidates) {
+			verdicts.set(`${candidate.provider}/${candidate.model}`, stateFor(candidate.provider, candidate.model))
+		}
+		// active 可能是 undefined / null / 字符串 —— undefined 与 null 都视为「没激活」。
+		const activeParsed = active === undefined || active === null ? null : parseRouteEntry(active)
+		const activeState = activeParsed === null
+			? null
+			: verdicts.get(`${activeParsed.provider}/${activeParsed.model}`) ?? stateFor(activeParsed.provider, activeParsed.model)
+		const recommendation = candidates.find((candidate) => verdicts.get(`${candidate.provider}/${candidate.model}`) === 'available')
+		const reason = candidates.length === 0
+			? '尚未在 settings.dsh-llm-hub.routing 配置主力模型 / fallbacks'
+			: (recommendation === undefined ? '主力与 fallbacks 全部不可用 —— 充值或换一个再说' : null)
+		return {
+			ok: true,
+			active: activeParsed === null
+				? null
+				: { provider: activeParsed.provider, model: activeParsed.model, state: activeState },
+			candidates: candidates.map((candidate) => ({
+				provider: candidate.provider,
+				model: candidate.model,
+				state: verdicts.get(`${candidate.provider}/${candidate.model}`) ?? 'unknown'
+			})),
+			recommendation: recommendation === undefined ? null : { provider: recommendation.provider, model: recommendation.model },
+			reason
+		}
+	}
+
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: ROUTING_RESOLVE_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
+			}
+			let payload
+			try {
+				const collected = []
+				for await (const chunk of request) collected.push(chunk)
+				payload = JSON.parse(Buffer.concat(collected).toString('utf8'))
+			} catch {
+				sendJson(response, 400, { ok: false, error: '请求内容不是合法 JSON' })
+				return
+			}
+			sendJson(response, 200, resolveRoute(payload?.active))
+		}
+	}), 'dsh-llm-hub: routing resolve route')
+
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: ROUTING_RESOLVE_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
+			}
+			let payload
+			try {
+				const collected = []
+				for await (const chunk of request) collected.push(chunk)
+				payload = JSON.parse(Buffer.concat(collected).toString('utf8'))
+			} catch {
+				sendJson(response, 400, { ok: false, error: '请求内容不是合法 JSON' })
+				return
+			}
+			sendJson(response, 200, resolveRoute(payload?.active))
+		}
+	}), 'dsh-llm-hub: routing resolve route')
+
+	// ── 模型别名 ──────────────────────────────────────────────────────────────
+	//
+	// settings.dsh-llm-hub.aliases：把长 model id 映射成短显示名，典型场景：
+	//   aliases:
+	//     'deepseek-official/deepseek-reasoner': '推理'
+	//     'modelgo/claude-3.5-sonnet': 'Sonnet'
+	//
+	// 设计取舍：
+	//   - **只渲染短名 + 留完整 id 在 title**：别名只是「人话」，不能让 client 把 id
+	//     也丢了 —— 用户复制 model id 粘到配置文件里的时候不能是「推理」。
+	//   - **不绑死 provider**：key 是 `<provider>/<model>`，缺斜杠或 provider 含
+	//     '/' 的不合法；保证 key 是 settings 段内的稳定引用。
+	//   - **空值过滤**：值是空字符串或纯空白时视为未配置；不让「短名 = 」这种
+	//     占位塞进 UI。
+	//   - **路由是 GET**：纯读，不需要 POST；每次拉目录时连同读。
+	const ALIAS_KEY_RE = /^[a-z0-9][a-z0-9_-]*\/[a-z0-9][a-z0-9_.+-]*$/i
+
+	/**
+	 * 读 `aliases` 段为「键 → 短名」map。
+	 * @returns 规范化后的别名表（空值 / 非法 key 全过滤掉）。
+	 */
+	const aliasesOf = () => {
+		const section = sectionOf() ?? {}
+		const raw = section.aliases !== null && typeof section.aliases === 'object' ? section.aliases : {}
+		const out = {}
+		for (const [key, value] of Object.entries(raw)) {
+			if (!ALIAS_KEY_RE.test(key)) continue
+			if (typeof value !== 'string') continue
+			const trimmed = value.trim()
+			if (trimmed.length === 0) continue
+			out[key] = trimmed
+		}
+		return out
+	}
+
+	/**
+	 * 给一个 (provider, model) 找短名（无别名时返 null）。
+	 * @param provider - provider id。
+	 * @param model - model id。
+	 * @returns 别名或 null。
+	 */
+	const aliasFor = (provider, model) => {
+		if (typeof provider !== 'string' || typeof model !== 'string') return null
+		const key = `${provider}/${model}`
+		const aliases = aliasesOf()
+		return aliases[key] ?? null
+	}
+
+	ctx.effect(() => ctx.webServer.register({
+		kind: 'exact',
+		path: ALIASES_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, { ok: true, aliases: aliasesOf() })
+		}
+	}), '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 子代理 ────────────────────────────────────────────────────────
+
 	// 自检路由：`GET /api/dsh-llm-hub/harness` 报告探到了什么、注册了几个。
 	//
 	// 为什么需要它：宿主的 `info` 级日志**不落盘**（实测 launchd.log 里只有