@kenz1117/dsh-ui-usage-billing 0.6.0 → 0.7.0

package/lib/index.js

@@ -4,9 +4,23 @@ import { join } from "node:path";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
+/** 运行时实时覆盖：undefined = 用内置目录与内置汇率（默认值降级）。 */
+let liveRate;
+let livePrices;
+let liveExtraModels;
+/**
+* Apply the node half's live pricing snapshot. Absent fields keep the
+* built-in catalog and rate; callers never fabricate values.
+* @param pricing - the `/api/billing/pricing` response.
+*/
+function applyLivePricing(pricing) {
+	liveRate = pricing.rate;
+	livePrices = pricing.prices;
+	liveExtraModels = pricing.extraModels;
+}
 /** 当前汇率：实时覆盖优先，缺省回退内置固定值。 */
 function currentRate() {
-	return 6.79;
+	return liveRate ?? 6.79;
 }
 /** Default share of traffic assumed to fall in the peak band (0..1). */
 const DEFAULT_PEAK_SHARE = .5;
@@ -544,11 +558,48 @@ const MODEL_KEY_ALIASES = {
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 function modelOf(key) {
 	const resolved = MODEL_KEY_ALIASES[key] ?? key;
-	return MODEL_CATALOG.find((entry) => entry.key === resolved) ?? (() => {
+	const found = MODEL_CATALOG.find((entry) => entry.key === resolved);
+	const extra = liveExtraModels?.find((item) => item.key === resolved);
+	const base = found ?? (extra !== void 0 ? extraEntryOf(extra) : (() => {
 		const fallback = MODEL_CATALOG.at(-1);
 		if (fallback !== void 0) return fallback;
 		throw new Error("MODEL_CATALOG must not be empty");
-	})();
+	})());
+	const live = livePrices?.[resolved];
+	if (live === void 0) return base;
+	return {
+		...base,
+		price: {
+			currency: "USD",
+			input: live.input,
+			cacheHit: live.cacheHit,
+			output: live.output
+		}
+	};
+}
+/** models.dev 补充条目转为目录条目：USD 直价（走汇率换算），无峰谷分档。 */
+function extraEntryOf(extra) {
+	return {
+		key: extra.key,
+		name: extra.name,
+		provider: extra.provider,
+		colorVar: "dsw-static-neutral-400",
+		price: {
+			currency: "USD",
+			input: extra.price.input,
+			cacheHit: extra.price.cacheHit,
+			output: extra.price.output
+		}
+	};
+}
+/**
+* 模型是否可计价：内置目录或 models.dev 补充条目命中。聚合层的计价闸门
+* （目录外模型不产生费用，避免兜底档误估）。
+*/
+function isPriced(key) {
+	const resolved = MODEL_KEY_ALIASES[key] ?? key;
+	if (MODEL_CATALOG.some((entry) => entry.key === resolved)) return true;
+	return (liveExtraModels ?? []).some((item) => item.key === resolved);
 }
 /**
 * Price one band's token usage in CNY. The stats `input` field is the TOTAL
@@ -681,7 +732,7 @@ function foldUsage(acc, usage, key, subscription, timeMs) {
 	acc.output += usage.outputTokens;
 	acc.cacheHit += cacheHit;
 	acc.cacheMiss += cacheMiss;
-	if (!subscription && MODEL_CATALOG.some((entry) => entry.key === key)) acc.cost += computeCostAt(modelOf(key), {
+	if (!subscription && isPriced(key)) acc.cost += computeCostAt(modelOf(key), {
 		input: cacheHit + cacheMiss,
 		cacheHit,
 		cacheMiss,
@@ -824,7 +875,7 @@ function foldSession(events, subscriptionProviders) {
 		state.output += usage.outputTokens;
 		state.cacheHit += usage.cacheReadTokens ?? 0;
 		state.cacheMiss += usage.inputTokens + (usage.cacheWriteTokens ?? 0);
-		if (!subscription && MODEL_CATALOG.some((entry) => entry.key === modelKey)) {
+		if (!subscription && isPriced(modelKey)) {
 			const buckets = {
 				input: (usage.cacheReadTokens ?? 0) + usage.inputTokens + (usage.cacheWriteTokens ?? 0),
 				cacheHit: usage.cacheReadTokens ?? 0,
@@ -1198,6 +1249,125 @@ async function queryBalances(ctx, providers) {
 		return querier(ctx, env);
 	}));
 }
+/** 点路径取值：`data.total_available` → 逐层下钻；任一缺失返回 undefined。 */
+function getPath(data, path) {
+	let cursor = data;
+	for (const segment of path.split(".")) {
+		if (cursor === null || typeof cursor !== "object") return void 0;
+		cursor = cursor[segment];
+	}
+	return cursor;
+}
+/**
+* 按 extract 规则从响应 JSON 求值。导出供测试：纯函数。
+* @param rule - 提取规则（const / path / add / subtract / divide）。
+* @param data - 响应 JSON。
+* @returns 数值；取不到或结果非有限数返回 undefined。
+*/
+function evalExtract(rule, data) {
+	if (typeof rule.const === "number" && Number.isFinite(rule.const)) return rule.const;
+	if (rule.op === "add" || rule.op === "subtract") {
+		const paths = rule.paths ?? [];
+		if (paths.length === 0) return void 0;
+		let total;
+		for (const path of paths) {
+			const value = toNumber(getPath(data, path));
+			if (value === void 0) return void 0;
+			total = total === void 0 ? value : rule.op === "add" ? total + value : total - value;
+		}
+		return total;
+	}
+	const base = typeof rule.path === "string" ? toNumber(getPath(data, rule.path)) : void 0;
+	if (base === void 0) return void 0;
+	if (rule.op === "divide") {
+		const by = rule.by;
+		if (typeof by !== "number" || !Number.isFinite(by) || by === 0) return void 0;
+		return base / by;
+	}
+	return base;
+}
+/** 请求头占位符解析：`{{ENV_NAME}}` 经凭据 seam 替换；解析失败返回 null。 */
+async function resolveHeaders(ctx, headers) {
+	const resolved = {};
+	for (const [key, value] of Object.entries(headers)) {
+		const match = /^\{\{([A-Z0-9_]+)\}\}$/i.exec(value.trim());
+		if (match === null) {
+			resolved[key] = value;
+			continue;
+		}
+		const hit = await ctx.credentials.resolve(credentialRef(match[1] ?? ""));
+		if (hit === void 0 || hit.value === "") return null;
+		resolved[key] = value.replace(match[0], hit.value);
+	}
+	return resolved;
+}
+/**
+* 查询自定义 Provider 余额（插件 config 的 `customBalances`）。每个条目独立
+* 成败：占位符凭据缺失 → unconfigured；401/403 → unauthorized；网络或提取
+* 失败 → unreachable。
+* @param ctx - host context carrying the credentials seam.
+* @param configs - 自定义余额配置列表。
+* @returns 每个配置一行的余额结果。
+*/
+async function queryCustomBalances(ctx, configs) {
+	return await Promise.all(configs.map(async (config) => {
+		const provider = `custom:${config.label}`;
+		const displayName = config.label;
+		if (typeof config.url !== "string" || config.url === "") return {
+			provider,
+			displayName,
+			error: "unconfigured"
+		};
+		const headers = await resolveHeaders(ctx, config.headers ?? {});
+		if (headers === null) return {
+			provider,
+			displayName,
+			error: "unconfigured"
+		};
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$1);
+		try {
+			const response = await fetch(config.url, {
+				method: config.method ?? "GET",
+				headers: {
+					accept: "application/json",
+					...headers
+				},
+				signal: controller.signal
+			});
+			if (response.status === 401 || response.status === 403) return {
+				provider,
+				displayName,
+				error: "unauthorized"
+			};
+			if (!response.ok) return {
+				provider,
+				displayName,
+				error: "unreachable"
+			};
+			const remaining = evalExtract(config.extract.remaining, await response.json());
+			if (remaining === void 0) return {
+				provider,
+				displayName,
+				error: "unreachable"
+			};
+			return {
+				provider,
+				displayName,
+				currency: config.unit ?? "CNY",
+				totalBalance: remaining
+			};
+		} catch {
+			return {
+				provider,
+				displayName,
+				error: "unreachable"
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	}));
+}
 //#endregion
 //#region lib/types/pricing-fetch.js
 /**
@@ -1235,6 +1405,41 @@ const RATE_SOURCES = [{
 }];
 /** OpenRouter's public model list: per-token USD prices, no key needed. */
 const ROUTER_URL = "https://openrouter.ai/api/v1/models";
+/** models.dev 公开目录：pi-ai 预制提供方的上游数据源（USD / 1M tokens）。
+* 接入它即与宿主「系统设置里预制的提供方模型」对齐——预制条目来自同一份数据。 */
+const MODELS_DEV_URL = "https://models.dev/api.json";
+/**
+* models.dev provider id → 仪表盘厂商显示名。探测到的模型若其厂商显示名与此
+* 映射命中则用之；未命中的回退为探活模型自带的厂商名（系统配置里的显示名）。
+* 不作为过滤条件——只用于给 models.dev 条目补一个可读的厂商名。
+*/
+const MODELS_DEV_PROVIDERS = {
+	deepseek: "DeepSeek",
+	zhipu: "智谱 AI",
+	zhipuai: "智谱 AI",
+	zai: "智谱 AI",
+	qwen: "阿里通义",
+	alibaba: "阿里通义",
+	moonshot: "月之暗面",
+	moonshotai: "月之暗面",
+	volcengine: "字节豆包",
+	doubao: "字节豆包",
+	minimax: "MiniMax",
+	baidu: "百度文心",
+	tencent: "腾讯混元",
+	hunyuan: "腾讯混元",
+	stepfun: "阶跃星辰",
+	iflytek: "科大讯飞",
+	sensetime: "商汤",
+	baichuan: "百川智能",
+	"01.ai": "零一万物",
+	openai: "OpenAI",
+	google: "Google",
+	xai: "xAI",
+	meta: "Meta",
+	anthropic: "Anthropic",
+	mistral: "Mistral"
+};
 /**
 * Built-in catalog key → OpenRouter model-id candidates. Matching prefers an
 * exact id, then a single strong substring hit (the router id contains the
@@ -1335,19 +1540,70 @@ function buildPrices(models) {
 	}
 	return Object.keys(result).length > 0 ? result : void 0;
 }
+/** 有限正数收窄（models.dev cost 字段的 durable 边界）。 */
+function asPrice(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+/**
+* models.dev 响应 → 目录外补充条目。不再按厂商白名单过滤：凡是有有效
+* cost 的模型都纳入（探活模型可能来自任何预制厂商，白名单会漏掉）。厂商
+* 显示名优先取映射，未命中用 provider id。导出供测试：纯函数。
+* @param data - `https://models.dev/api.json` 的响应体。
+* @returns 补充条目（按 provider 顺序稳定；仅含可计价的模型）。
+*/
+function buildExtraModels(data) {
+	if (data === null || typeof data !== "object") return [];
+	const catalogKeys = new Set([...MODEL_CATALOG.map((entry) => entry.key.toLowerCase()), ...Object.keys(MODEL_KEY_ALIASES).map((key) => MODEL_KEY_ALIASES[key]?.toLowerCase() ?? key.toLowerCase())]);
+	const extras = [];
+	for (const [providerId, providerDoc] of Object.entries(data)) {
+		if (providerDoc === null || typeof providerDoc !== "object") continue;
+		const models = providerDoc.models;
+		if (models === null || typeof models !== "object") continue;
+		for (const [modelId, modelDoc] of Object.entries(models)) {
+			const catalogKey = (MODEL_KEY_ALIASES[modelId] ?? modelId).toLowerCase();
+			if (catalogKeys.has(catalogKey)) continue;
+			const key = catalogKey;
+			if (modelDoc === null || typeof modelDoc !== "object") continue;
+			const cost = modelDoc.cost;
+			if (cost === null || typeof cost !== "object") continue;
+			const input = asPrice(cost.input);
+			const output = asPrice(cost.output);
+			if (input === void 0 || output === void 0) continue;
+			const cacheRead = asPrice(cost.cache_read) ?? input * .1;
+			const name = modelDoc.name;
+			extras.push({
+				key,
+				name: typeof name === "string" && name !== "" ? name : modelId,
+				provider: MODELS_DEV_PROVIDERS[providerId.toLowerCase()] ?? providerId,
+				price: {
+					input,
+					cacheHit: cacheRead,
+					output
+				}
+			});
+		}
+	}
+	return extras;
+}
 /**
 * Fetch the live pricing once at boot. Both upstreams run in parallel; a
 * failure in either degrades independently to the built-in value.
 * @returns the live pricing snapshot (builtin when everything failed).
 */
 async function fetchLivePricing() {
-	const [rate, models] = await Promise.all([fetchRate(), fetchRouterModels()]);
+	const [rate, models, modelsDev] = await Promise.all([
+		fetchRate(),
+		fetchRouterModels(),
+		fetchJson(MODELS_DEV_URL)
+	]);
 	const prices = models === void 0 ? void 0 : buildPrices(models);
-	if (rate === void 0 && prices === void 0) return { source: "builtin" };
+	const extraModels = modelsDev === null ? void 0 : buildExtraModels(modelsDev);
+	if (rate === void 0 && prices === void 0 && (extraModels === void 0 || extraModels.length === 0)) return { source: "builtin" };
 	return {
 		source: "live",
 		...rate !== void 0 ? { rate } : {},
-		...prices !== void 0 ? { prices } : {}
+		...prices !== void 0 ? { prices } : {},
+		...extraModels !== void 0 && extraModels.length > 0 ? { extraModels } : {}
 	};
 }
 //#endregion
@@ -1485,8 +1741,8 @@ function kimiWindow(value, kind) {
 	const record = value;
 	const limit = numberOrNull(record.limit ?? record.total);
 	const remaining = numberOrNull(record.remaining);
-	if (limit === null || remaining === null || limit <= 0) return null;
-	const usedPercent = round1(clampPercent((limit - remaining) / limit * 100) ?? 0);
+	if (remaining === null) return null;
+	const usedPercent = limit !== null && limit > 0 ? round1(clampPercent((limit - remaining) / limit * 100) ?? 0) : remaining > 0 ? 0 : 100;
 	const resetsAt = toIso(record.resetTime ?? record.reset_time ?? record.resetsAt);
 	return {
 		kind,
@@ -1999,6 +2255,7 @@ function apply(ctx, config = {}) {
 	let live = { source: "builtin" };
 	const refreshPricing = async () => {
 		live = await fetchLivePricing();
+		applyLivePricing(live);
 	};
 	refreshPricing();
 	ctx.effect(() => {
@@ -2025,7 +2282,8 @@ function apply(ctx, config = {}) {
 			const providers = { ...await readPiAiProviders(ctx.settings) };
 			if (providers["deepseek"] === void 0) providers["deepseek"] = { apiKeyEnv: config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV };
 			const balances = await queryBalances(ctx, providers);
-			res.end(JSON.stringify({ balances }));
+			const custom = await queryCustomBalances(ctx, config.customBalances ?? []);
+			res.end(JSON.stringify({ balances: [...balances, ...custom] }));
 		}
 	}), "usage-billing: balance route");
 	let quotaCache = {

package/lib/types/balance.d.ts

@@ -14,7 +14,7 @@
  * provider's key once and every surface reuses it.
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { ProviderBalance } from './pricing-shared.ts';
+import type { CustomBalanceConfig, CustomBalanceExtract, ProviderBalance } from './pricing-shared.ts';
 /**
  * Query every configured provider's account balance. A provider is queried only
  * when its llm-pi-ai route has an `apiKeyEnv`; absent routes answer
@@ -26,4 +26,20 @@ import type { ProviderBalance } from './pricing-shared.ts';
 export declare function queryBalances(ctx: Context, providers: Readonly<Record<string, {
     apiKeyEnv?: string;
 }>>): Promise<readonly ProviderBalance[]>;
+/**
+ * 按 extract 规则从响应 JSON 求值。导出供测试：纯函数。
+ * @param rule - 提取规则（const / path / add / subtract / divide）。
+ * @param data - 响应 JSON。
+ * @returns 数值；取不到或结果非有限数返回 undefined。
+ */
+export declare function evalExtract(rule: CustomBalanceExtract, data: unknown): number | undefined;
+/**
+ * 查询自定义 Provider 余额（插件 config 的 `customBalances`）。每个条目独立
+ * 成败：占位符凭据缺失 → unconfigured；401/403 → unauthorized；网络或提取
+ * 失败 → unreachable。
+ * @param ctx - host context carrying the credentials seam.
+ * @param configs - 自定义余额配置列表。
+ * @returns 每个配置一行的余额结果。
+ */
+export declare function queryCustomBalances(ctx: Context, configs: readonly CustomBalanceConfig[]): Promise<readonly ProviderBalance[]>;
 //# sourceMappingURL=balance.d.ts.map

package/lib/types/client/UsageBilling.d.ts

@@ -12,6 +12,7 @@
 import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SidebarFooterActionOwnerProps } from '@deepseek-ai/dsh-client-ui-sidebar/client';
 import type { createBillingBudgetStore } from './budget-store.ts';
+import { type CatalogModel } from './pricing.ts';
 import { NS, type UsageBillingKey } from './locales.ts';
 /** Model-connectivity health reported by the host model directory probe. */
 export interface ModelHealth {
@@ -27,6 +28,8 @@ export interface ModelHealth {
     okProviders: readonly string[];
     /** Display names of providers whose catalog probe failed. */
     badProviders: readonly string[];
+    /** 探活得到的模型清单（系统里实际配置/预制的模型；无价格，费率表据此对标）。 */
+    catalog?: readonly CatalogModel[];
 }
 /** 仪表盘分区 Tab id。 */
 export type DashboardTab = 'overview' | 'trends' | 'providers' | 'details' | 'pricing';

package/lib/types/client/budget-store.d.ts

@@ -16,6 +16,8 @@ export interface BudgetPrefsState {
     tierAlertDays: Record<string, string>;
     /** 最近一次余额不足通知的日期戳（YYYY-MM-DD）：余额告警同样每天最多一次。 */
     lastBalanceAlertDay: string;
+    /** 最近一次峰谷切换提醒的切换点时刻（毫秒）：同一切换点只提醒一次。 */
+    lastTierSwitchAt: number;
 }
 /** 预算偏好的完整写面（组件只能经这些 action 写入）；type 别名以兼容 ActionsDecl 的索引签名约束。 */
 export type BudgetPrefsActions = {
@@ -23,6 +25,7 @@ export type BudgetPrefsActions = {
     setAmount: (d: BudgetPrefsState, value: number) => void;
     markTierAlerted: (d: BudgetPrefsState, tiers: readonly number[], day: string) => void;
     markBalanceAlerted: (d: BudgetPrefsState, day: string) => void;
+    markTierSwitchAlerted: (d: BudgetPrefsState, at: number) => void;
 };
 /**
  * Declare the budget-preferences store handle.

package/lib/types/client/live-cost.d.ts

@@ -9,9 +9,15 @@
  * the current session id off the framework snapshot (`useSession` parent of
  * `sessionId`) and matches `bySession` (session total) and `byTurn` (latest
  * turn cost). Rendering is a pure function of the snapshot, never a side effect.
+ *
+ * The bar also carries two ambient signals: the current peak/off-peak pricing
+ * tier with a switch countdown (DeepSeek time-of-day pricing), and quota chips
+ * for subscription plans running low (≤20% remaining), so cost pressure is
+ * visible without opening the dashboard.
  */
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
 import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+import type { UsageBillingKey } from './locales.ts';
 /** The usage-stats shape the composer bar needs (a thin slice, not the whole doc). */
 export interface LiveStats {
     bySession?: readonly {
@@ -24,6 +30,15 @@ export interface LiveStats {
         cost: number;
     }[];
 }
+/** 订阅额度的薄切片（/api/billing/subscriptions 响应的行）。 */
+export interface QuotaSlice {
+    displayName: string;
+    status: string;
+    windows: readonly {
+        kind: string;
+        remainingPercent: number;
+    }[];
+}
 /**
  * 当前会话累计费用：bySession 里会话 id 匹配的那行；缺省为 0。
  * 导出供测试：纯函数。
@@ -41,11 +56,22 @@ export declare function sessionCostOf(stats: LiveStats | null, sessionId: string
  * @returns 最新一轮费用（人民币元）。
  */
 export declare function turnCostOf(stats: LiveStats | null, sessionId: string | undefined): number;
+/**
+ * 低额度预警 chips：查询成功（ok）且任一窗口剩余 ≤ threshold 的套餐，
+ * 按剩余升序、最多 3 枚。导出供测试：纯函数。
+ * @param quotas - 订阅额度行切片。
+ * @param threshold - 剩余百分比阈值（默认 20%）。
+ */
+export declare function lowQuotaChips(quotas: readonly QuotaSlice[], threshold?: number): readonly {
+    name: string;
+    kind: string;
+    pct: number;
+}[];
 /** Props: the session-scope snapshot selector the framework injects. */
 export interface LiveCostBarProps {
     useSession: SnapshotSelectorHook<ConversationSnapshot>;
     /** The owning dock's locale seat (bound to the billing NS). */
-    t: (key: 'billing.liveTurn' | 'billing.liveSession') => string;
+    t: (key: UsageBillingKey) => string;
 }
 /**
  * Render the live cost ticker for the current session.

package/lib/types/client/locales.d.ts

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trend7d' | 'billing.trend30d' | 'billing.trendEmpty' | 'billing.budget' | 'billing.sessions' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.anomaly' | 'billing.workspaces' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trend7d' | 'billing.trend30d' | 'billing.trendEmpty' | 'billing.budget' | 'billing.sessions' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionExhausted' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.anomaly' | 'billing.workspaces' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/client/pricing.d.ts

@@ -27,6 +27,22 @@ export declare const USD_TO_CNY = 6.79;
  * @param pricing - the `/api/billing/pricing` response.
  */
 export declare function applyLivePricing(pricing: LivePricing): void;
+/**
+ * 注入探活得到的「系统里实际配置/预制的模型」清单（host 的 llm.models 返回
+ * groups[].models[]，含模型 id/name，无价格）。费率表据此对标现实可用模型——
+ * 有价的补价（内置目录 / models.dev 补充），无价的标「未收录」。纯内存状态，
+ * 供 `catalogEntries()` 渲染。
+ */
+export declare function applyLiveCatalogModels(models: readonly CatalogModel[]): void;
+/** 探活模型清单条目（host 的 ModelCatalogModel 投影出需要的字段）。 */
+export interface CatalogModel {
+    /** 模型 id（如 `deepseek-v4-flash`）。 */
+    id: string;
+    /** 显示名；缺省用 id。 */
+    name?: string;
+    /** 厂商显示名（探活 group 名）。 */
+    provider: string;
+}
 /**
  * 当前生效的 USD → CNY 汇率及其来源：live = 启动时实时拉取成功，
  * builtin = 实时拉取失败、正在用内置默认值。
@@ -52,6 +68,30 @@ export declare function isPeakHour(beijingHour: number): boolean;
  * @param timeMs - Unix epoch 毫秒；null/undefined/NaN 视为未知。
  */
 export declare function tierAt(timeMs: number | null | undefined): PriceTierId;
+/**
+ * 当前峰谷档位与距下次切换的时长。导出供测试：纯函数。
+ * @param nowMs - 当前时刻（epoch 毫秒）。
+ * @returns 当前档位与到下一个切换边界的毫秒数。
+ */
+export declare function tierCountdown(nowMs: number): {
+    tier: PriceTierId;
+    nextSwitchInMs: number;
+};
+/**
+ * 峰/谷切换预告：距下次切换不足 leadMs 时返回即将进入的档位与切换时刻，
+ * 否则 null。导出供测试：纯函数。
+ * @param nowMs - 当前时刻（epoch 毫秒）。
+ * @param leadMs - 提前量（毫秒）。
+ */
+export declare function upcomingTierSwitch(nowMs: number, leadMs: number): {
+    entering: PriceTierId;
+    atMs: number;
+} | null;
+/**
+ * 切换倒计时短格式：`1h23m` / `45m` / `3m`。导出供测试：纯函数。
+ * @param ms - 剩余毫秒数。
+ */
+export declare function formatSwitchCountdown(ms: number): string;
 /** Usage buckets consumed by one model (counts in raw tokens). */
 export interface TokenUsageBuckets {
     /** Uncached input tokens. */
@@ -100,6 +140,8 @@ export interface ModelEntry {
      * 展示时标注以免误当正式定价；正式定价公布后移除。
      */
     estimated?: boolean;
+    /** 探活命中但无内置/models.dev 价：费率表标「未收录」，不参与计价。 */
+    uncatalogued?: boolean;
 }
 /**
  * Built-in catalog of current mainstream models as of 2026-08-16, priced from
@@ -126,6 +168,17 @@ export declare const MODEL_CATALOG: readonly ModelEntry[];
 export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 export declare function modelOf(key: string): ModelEntry;
+/**
+ * 模型是否可计价：内置目录或 models.dev 补充条目命中。聚合层的计价闸门
+ * （目录外模型不产生费用，避免兜底档误估）。
+ */
+export declare function isPriced(key: string): boolean;
+/**
+ * 费率表渲染的完整目录：内置 + models.dev 补充条目 + 探活模型（无价标记）。
+ * 探活模型去重（按归一化 id）：内置/补充已有的不再重复；无价的保留并标记
+ * `uncatalogued`，费率表据此显示「未收录」。
+ */
+export declare function catalogEntries(): readonly ModelEntry[];
 /** Resolve a price-table row by its CSS variable name (theme token or fallback color). */
 export declare function resolveToken(name: string): string;
 /**

package/lib/types/index.d.ts

@@ -12,7 +12,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
 import type { SettingsProvider } from '@deepseek-ai/dsh-settings';
-import type { SubscriptionPlanConfig } from './pricing-shared.ts';
+import type { CustomBalanceConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
 /** Plugin configuration. */
 export interface UsageBillingConfig {
@@ -29,6 +29,8 @@ export interface UsageBillingConfig {
     /** 余额不足告警阈值（人民币元）：余额低于此值时仪表盘每天提醒一次；
         不设置则客户端按默认阈值（50 元）兜底。 */
     lowBalanceThreshold?: number;
+    /** 自定义 Provider 余额查询（任意 HTTP 端点 + extract 规则，适配 NewApi/LiteLLM 等）。 */
+    customBalances?: readonly CustomBalanceConfig[];
 }
 /** Required services: the web server, the persisted session log store, and user settings. */
 export declare const inject: string[];

package/lib/types/pricing-fetch.d.ts

@@ -7,7 +7,15 @@
  * half caches whatever succeeded and the browser dashboard falls back to the
  * catalog for the rest — a total outage answers `{ source: 'builtin' }`.
  */
-import type { LivePricing } from './pricing-shared.ts';
+import type { ExtraModelPrice, LivePricing } from './pricing-shared.ts';
+/**
+ * models.dev 响应 → 目录外补充条目。不再按厂商白名单过滤：凡是有有效
+ * cost 的模型都纳入（探活模型可能来自任何预制厂商，白名单会漏掉）。厂商
+ * 显示名优先取映射，未命中用 provider id。导出供测试：纯函数。
+ * @param data - `https://models.dev/api.json` 的响应体。
+ * @returns 补充条目（按 provider 顺序稳定；仅含可计价的模型）。
+ */
+export declare function buildExtraModels(data: unknown): ExtraModelPrice[];
 /**
  * Fetch the live pricing once at boot. Both upstreams run in parallel; a
  * failure in either degrades independently to the built-in value.