@kenz1117/dsh-ui-usage-billing 0.9.0 → 0.9.2

package/lib/index.js

@@ -76,6 +76,14 @@ const PLAN_KNOWLEDGE = {
 	"doubao-token-plan": {
 		type: "code",
 		subscriptionCny: 0
+	},
+	"minimax": {
+		type: "code",
+		subscriptionCny: 0
+	},
+	"minimax-token-plan": {
+		type: "code",
+		subscriptionCny: 0
 	}
 };
 /** provider id（llm-pi-ai 设置键）→ plan 知识；未命中默认 token。 */
@@ -170,7 +178,8 @@ function currentRate() {
 /** Default share of traffic assumed to fall in the peak band (0..1). */
 const DEFAULT_PEAK_SHARE = .5;
 /**
-* 高峰时段判定（北京时间，UTC+8，无夏令时）：09:00–12:00、14:00–18:00。
+* 工作日高峰时段判定（北京时间，UTC+8，无夏令时）：09:00–12:00、14:00–18:00。
+* 周末（周六/周日）北京全天为低谷，不调用本函数判定峰/平。
 * @param beijingHour - 北京时间的小时数（0–23）。
 */
 function isPeakHour(beijingHour) {
@@ -179,12 +188,19 @@ function isPeakHour(beijingHour) {
 /**
 * 由时刻（epoch 毫秒）推断计费时段；时刻未知/非法时按高峰计（保守：未知
 * 时刻不低估成本，与社区 dsh-usage-chart 的 tierAt 语义一致）。
+* 周末（北京时间周六/周日）全天不区分峰谷，统一按低谷价。
 * @param timeMs - Unix epoch 毫秒；null/undefined/NaN 视为未知。
 */
 function tierAt(timeMs) {
 	if (timeMs === null || timeMs === void 0 || !Number.isFinite(timeMs)) return "peak";
+	if (isBeijingWeekend(timeMs)) return "offPeak";
 	return isPeakHour((new Date(timeMs).getUTCHours() + 8) % 24) ? "peak" : "offPeak";
 }
+/** 时刻是否落在北京时间周末（周六/周日）。 */
+function isBeijingWeekend(timeMs) {
+	const day = new Date(timeMs + 8 * 36e5).getUTCDay();
+	return day === 0 || day === 6;
+}
 /**
 * Built-in catalog of current mainstream models as of 2026-08-16, priced from
 * each provider's official price page. Domestic providers are OpenAI-API
@@ -711,9 +727,55 @@ const MODEL_KEY_ALIASES = {
 	"k3": "kimi-k3",
 	"kimi-k3": "kimi-k3"
 };
+/**
+* 模型 id 归一化：小写、去括号附注（如 `gpt5.6 luna(go)` 只看主体）、再去所有
+* 非字母数字分隔符（空格 / 横杠 / 点 / 下划线）。用于日志里的模型 id 与计费
+* 目录键做宽松匹配，提升「大小写/分隔符差异导致未收录」的识别率。
+* @param id - 原始模型 id（日志或目录键）。
+* @returns 归一化键（字母数字小写串）。
+*/
+function canonModelId(id) {
+	return String(id).toLowerCase().replace(/\([^)]*\)/g, "").replace(/[^a-z0-9]+/g, "");
+}
+/**
+* 目录常量键的归一化索引：归一化键 → 真实计费键。只索引静态来源（内置目录、
+* 别名表、dsh-spend 兜底键）；models.dev 补充条目是运行时注入，单独实时匹配。
+*/
+const CATALOG_CANON_INDEX = (() => {
+	const map = /* @__PURE__ */ new Map();
+	const add = (candidate, target) => {
+		const canon = canonModelId(candidate);
+		if (canon !== "" && !map.has(canon)) map.set(canon, target);
+	};
+	for (const entry of MODEL_CATALOG) add(entry.key, entry.key);
+	for (const [alias, key] of Object.entries(MODEL_KEY_ALIASES)) add(alias, key);
+	for (const rate of FALLBACK_RATES) add(rate.key, rate.key);
+	return map;
+})();
+/**
+* 解析真实日志模型 id → 计费目录键。先精确别名映射（既有行为）；未命中时做
+* 归一化匹配（忽略大小写/分隔符/括号附注），命中内置目录 / 别名目标 / 兜底键 /
+* models.dev 补充键即返回其真实键；完全未知时保持原样（回退 other，不计费）。
+* 供聚合层折叠与客户端渲染共用，两侧一致。
+* @param id - 真实模型 id（日志里出现的形式）。
+* @returns 计费目录键。
+*/
+function resolveCatalogKey(id) {
+	const exact = MODEL_KEY_ALIASES[id] ?? id;
+	if (exact === id) {
+		const canon = canonModelId(id);
+		if (canon !== "") {
+			const hit = CATALOG_CANON_INDEX.get(canon);
+			if (hit !== void 0) return hit;
+			const extraHit = (liveExtraModels ?? []).find((item) => canonModelId(item.key) === canon);
+			if (extraHit !== void 0) return extraHit.key;
+		}
+	}
+	return exact;
+}
 /** 取一个计费键的实时单价（实时覆盖 > dsh-spend 官方价兜底）。 */
 function livePriceOf(key) {
-	const resolved = MODEL_KEY_ALIASES[key] ?? key;
+	const resolved = resolveCatalogKey(key);
 	const live = livePrices?.[resolved];
 	if (live !== void 0) return live;
 	const fallback = FALLBACK_RATES.find((rate) => rate.key.toLowerCase() === resolved.toLowerCase());
@@ -726,7 +788,7 @@ function livePriceOf(key) {
 }
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 function modelOf(key) {
-	const resolved = MODEL_KEY_ALIASES[key] ?? key;
+	const resolved = resolveCatalogKey(key);
 	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) : (() => {
@@ -766,7 +828,7 @@ function extraEntryOf(extra) {
 * 聚合层的计价闸门（目录外模型不产生费用，避免兜底档误估）。
 */
 function isPriced(key) {
-	const resolved = MODEL_KEY_ALIASES[key] ?? key;
+	const resolved = resolveCatalogKey(key);
 	if (MODEL_CATALOG.some((entry) => entry.key === resolved)) return true;
 	if ((liveExtraModels ?? []).some((item) => item.key === resolved)) return true;
 	return FALLBACK_RATES.some((rate) => rate.key.toLowerCase() === resolved.toLowerCase());
@@ -873,6 +935,14 @@ const DEFAULT_SUBSCRIPTION_PROVIDERS = [
 	"xiaomi-token-plan-cn",
 	"xiaomi-token-plan-sgp"
 ];
+/**
+* 官方渠道 provider id 判定：`deepseek` 前缀（DeepSeek 官方直连）视为官方，
+* 其余 provider（第三方中转/代理）视为「三方」。用于「官方 vs 三方」token、
+* 调用与费用分桶展示；部署可由配置覆盖（见 {@link AggregateOptions}）。
+*/
+function isOfficialProvider(provider) {
+	return /^deepseek(?:-[a-z0-9-]+)?$/i.test(provider.trim());
+}
 /** Zeroed usage accumulator. */
 function emptyUsage() {
 	return {
@@ -881,7 +951,9 @@ function emptyUsage() {
 		output: 0,
 		cacheHit: 0,
 		cacheMiss: 0,
-		cost: 0
+		cost: 0,
+		officialCalls: 0,
+		officialCost: 0
 	};
 }
 /**
@@ -893,8 +965,9 @@ function emptyUsage() {
 * @param key - the billing-catalog key this call belongs to.
 * @param subscription - whether the call went through a subscription plan; such calls never cost money.
 * @param timeMs - the call's wall-clock time (epoch ms); drives peak/off-peak pricing.
+* @param official - whether the call went through the official DeepSeek channel (vs a third-party relay).
 */
-function foldUsage(acc, usage, key, subscription, timeMs) {
+function foldUsage(acc, usage, key, subscription, timeMs, official = false) {
 	const cacheHit = usage.cacheReadTokens ?? 0;
 	const cacheMiss = usage.inputTokens + (usage.cacheWriteTokens ?? 0);
 	acc.calls += 1;
@@ -902,12 +975,17 @@ function foldUsage(acc, usage, key, subscription, timeMs) {
 	acc.output += usage.outputTokens;
 	acc.cacheHit += cacheHit;
 	acc.cacheMiss += cacheMiss;
-	if (!subscription && isPriced(key)) acc.cost += computeCostAt(modelOf(key), {
-		input: cacheHit + cacheMiss,
-		cacheHit,
-		cacheMiss,
-		output: usage.outputTokens
-	}, timeMs);
+	if (official) acc.officialCalls += 1;
+	if (!subscription && isPriced(key)) {
+		const thisCost = computeCostAt(modelOf(key), {
+			input: cacheHit + cacheMiss,
+			cacheHit,
+			cacheMiss,
+			output: usage.outputTokens
+		}, timeMs);
+		acc.cost += thisCost;
+		if (official) acc.officialCost += thisCost;
+	}
 }
 /** Local-time date stamp (the host runs in the user's timezone). */
 function dayStamp(time) {
@@ -976,9 +1054,11 @@ function turnState(turns, turn) {
 * 并按轮次折叠每轮费用明细（turn/start → turn/end；调用按 (turn) 归组）。
 * @param events - the session's persisted events in log order.
 * @param subscriptionProviders - provider ids billed through subscription plans.
+* @param officialProviderIds - provider ids treated as the official DeepSeek channel
+*   (default: any `deepseek`-prefixed id). Others count as third-party.
 * @returns the per-session fold (cached by the incremental aggregator).
 */
-function foldSession(events, subscriptionProviders) {
+function foldSession(events, subscriptionProviders, officialProviderIds) {
 	const fold = {
 		total: emptyUsage(),
 		byModel: /* @__PURE__ */ new Map(),
@@ -996,6 +1076,7 @@ function foldSession(events, subscriptionProviders) {
 	};
 	let key = "other";
 	let subscription = false;
+	let official = false;
 	const turns = /* @__PURE__ */ new Map();
 	for (const event of events) {
 		fold.lastActive = Math.max(fold.lastActive, event.time);
@@ -1025,8 +1106,9 @@ function foldSession(events, subscriptionProviders) {
 		}
 		if (event.type === "request/header") {
 			const { model, provider } = event.data.header.config;
-			key = MODEL_KEY_ALIASES[model] ?? model;
+			key = resolveCatalogKey(model);
 			subscription = subscriptionProviders.has(provider);
+			official = officialProviderIds === void 0 ? isOfficialProvider(provider) : officialProviderIds.has(provider);
 			continue;
 		}
 		if (event.type !== "assistant/message") continue;
@@ -1034,10 +1116,10 @@ function foldSession(events, subscriptionProviders) {
 		if (usage === void 0) continue;
 		const modelKey = key;
 		const day = dayStamp(event.time);
-		foldUsage(fold.total, usage, modelKey, subscription, event.time);
-		foldUsage(usageCell(fold.byModel, modelKey), usage, modelKey, subscription, event.time);
-		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time);
-		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time);
+		foldUsage(fold.total, usage, modelKey, subscription, event.time, official);
+		foldUsage(usageCell(fold.byModel, modelKey), usage, modelKey, subscription, event.time, official);
+		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time, official);
+		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time, official);
 		if (subscription) fold.planCalls.set(modelKey, (fold.planCalls.get(modelKey) ?? 0) + 1);
 		const state = turnState(turns, event.data.turn ?? -1);
 		state.model = modelKey;
@@ -1086,6 +1168,8 @@ function mergeUsageInto(acc, cell) {
 	acc.cacheHit += cell.cacheHit;
 	acc.cacheMiss += cell.cacheMiss;
 	acc.cost += cell.cost;
+	acc.officialCalls += cell.officialCalls;
+	acc.officialCost += cell.officialCost;
 }
 /**
 * Create the incremental usage aggregator.
@@ -1095,6 +1179,7 @@ function mergeUsageInto(acc, cell) {
 */
 function createUsageAggregator(persistence, options = {}) {
 	const subscriptionProviders = new Set(options.subscriptionProviders ?? DEFAULT_SUBSCRIPTION_PROVIDERS);
+	const officialProviderIds = options.officialProviderIds === void 0 ? void 0 : new Set(options.officialProviderIds);
 	const cache = /* @__PURE__ */ new Map();
 	let lastDoc;
 	let lastAt = 0;
@@ -1115,6 +1200,7 @@ function createUsageAggregator(persistence, options = {}) {
 		const metas = await persistence.list();
 		const seen = /* @__PURE__ */ new Set();
 		const folds = [];
+		const skipped = [];
 		for (const meta of metas) {
 			const id = String(meta.id);
 			seen.add(id);
@@ -1127,18 +1213,24 @@ function createUsageAggregator(persistence, options = {}) {
 				});
 				continue;
 			}
-			const { events } = await persistence.readFrom(meta.id, 0);
-			const fold = foldSession(events, subscriptionProviders);
-			cache.set(id, {
-				stamp,
-				fold
-			});
-			folds.push({
-				meta,
-				fold
-			});
+			try {
+				const { events } = await persistence.readFrom(meta.id, 0);
+				const fold = foldSession(events, subscriptionProviders, officialProviderIds);
+				cache.set(id, {
+					stamp,
+					fold
+				});
+				folds.push({
+					meta,
+					fold
+				});
+			} catch (error) {
+				skipped.push(id);
+				console.warn("[usage-billing] skip unreadable session", id, error);
+			}
 		}
 		for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
+		if (skipped.length > 0) console.warn(`[usage-billing] aggregated ${folds.length} sessions, skipped ${skipped.length} unreadable:`, skipped);
 		const total = emptyUsage();
 		const byModel = /* @__PURE__ */ new Map();
 		const byDay = /* @__PURE__ */ new Map();
@@ -1255,6 +1347,8 @@ const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
 const MOONSHOT_BALANCE_URL = "https://api.moonshot.cn/v1/users/me/balance";
 /** 阶跃星辰 StepFun 官方账户信息接口（platform.stepfun.com/docs/api-reference/accounts/get）。 */
 const STEPFUN_BALANCE_URL = "https://api.stepfun.com/v1/accounts";
+/** 硅基流动 SiliconFlow 官方用户信息接口（docs.siliconflow.cn/cn/api-reference/user/query-user-info）。 */
+const SILICONFLOW_BALANCE_URL = "https://api.siliconflow.cn/v1/user/info";
 /** 数字归一化：接口返回的余额是字符串（如 `"110.00"`），统一转 number。 */
 function toNumber(value) {
 	if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -1383,6 +1477,25 @@ function queryStepFun(ctx, apiKeyEnv) {
 		};
 	});
 }
+/**
+* Query the SiliconFlow (硅基流动) account balance.
+* @param ctx - host context carrying the credentials seam.
+* @param apiKeyEnv - credential reference resolving the SiliconFlow API key.
+* @returns the balance row, or an error row when the key/endpoint misbehaves.
+*/
+function querySiliconFlow(ctx, apiKeyEnv) {
+	return queryBearerBalance(ctx, SILICONFLOW_BALANCE_URL, apiKeyEnv, "硅基流动", "硅基流动", (data) => {
+		const doc = data;
+		const inner = doc.data ?? doc;
+		const totalBalance = toNumber(inner.balance ?? inner.balance_cny);
+		return {
+			provider: "硅基流动",
+			displayName: "硅基流动",
+			currency: "CNY",
+			...totalBalance !== void 0 ? { totalBalance } : {}
+		};
+	});
+}
 const QUERIERS = [
 	{
 		route: "deepseek",
@@ -1398,6 +1511,11 @@ const QUERIERS = [
 		route: "stepfun",
 		displayName: "阶跃星辰",
 		querier: queryStepFun
+	},
+	{
+		route: "siliconflow",
+		displayName: "硅基流动",
+		querier: querySiliconFlow
 	}
 ];
 /**
@@ -1796,6 +1914,8 @@ const EMPTY_SUBSCRIPTION_KEYS = {
 	kimiApiKey: "",
 	zaiApiKey: "",
 	opencodeApiKey: "",
+	minmaxApiKey: "",
+	openrouterApiKey: "",
 	zaiRegion: "global"
 };
 /** 订阅类 provider 的显示名（未命中的回退为 id 本身）。 */
@@ -1816,10 +1936,12 @@ const SUBSCRIPTION_DISPLAY_NAMES = {
 	"ernie": "百度文心 Plan",
 	"baidu": "百度文心 Plan",
 	"wenxin": "百度文心 Plan",
-	"minimax": "MiniMax Coding Plan"
+	"minimax": "MiniMax Coding Plan",
+	"minimax-token-plan": "MiniMax Token Plan",
+	"openrouter": "OpenRouter"
 };
 /** 订阅类 provider id 判定：带 coding / agent-plan / token-plan 后缀，或已知订阅通道。 */
-const SUBSCRIPTION_ID_RE = /(?:^|-)(?:coding|agent[-_]?plan|token[-_]?plan)(?:$|-|_)|^(?:opencode|opencode-go|kimi-coding|zai-coding|minimax)/i;
+const SUBSCRIPTION_ID_RE = /(?:^|-)(?:coding|agent[-_]?plan|token[-_]?plan)(?:$|-|_)|^(?:opencode|opencode-go|kimi-coding|zai-coding|minimax|minimax-token-plan|openrouter)/i;
 /** 是否是订阅类 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
 function isSubscriptionProviderId(providerId) {
 	if (SUBSCRIPTION_ID_RE.test(providerId)) return true;
@@ -1830,7 +1952,10 @@ const SUBSCRIPTION_ADAPTERS = {
 	"kimi-coding": { collect: collectKimi },
 	"zai-coding-cn": { collect: collectZai },
 	"opencode": { collect: collectOpenCodeGo },
-	"opencode-go": { collect: collectOpenCodeGo }
+	"opencode-go": { collect: collectOpenCodeGo },
+	"minimax": { collect: collectMiniMax },
+	"minimax-token-plan": { collect: collectMiniMax },
+	"openrouter": { collect: collectOpenRouter }
 };
 /** 有额度适配器的 provider id 集合（识别用）。 */
 const ADAPTER_PROVIDER_IDS = new Set(Object.keys(SUBSCRIPTION_ADAPTERS));
@@ -2154,6 +2279,128 @@ async function collectOpenCodeGo(keys, config, timeoutMs) {
 	}
 }
 /**
+* 单条 MiniMax 记录抽一个窗口。`remaining_percent` 是剩余%;已用% = 100 - 剩余。
+* `status === 3` 表示不限量档,跳过该窗。导出供测试:纯函数。
+* @param record - 一条 model_remains 记录。
+* @param kind - 窗口类型(session=5h 滚动 / weekly=7d)。
+* @param remainPctKey - 剩余百分比字段。
+* @param statusKey - 限量状态字段(3=不限量)。
+* @param resetKey - 重置时刻字段(epoch 秒/毫秒/ISO)。
+*/
+function minmaxWindow(record, kind, remainPctKey, statusKey, resetKey) {
+	if (record === void 0) return null;
+	if (Number(record[statusKey]) === 3) return null;
+	const remain = numberOrNull(record[remainPctKey]);
+	if (remain === null) return null;
+	const usedPercent = round1(clampPercent(100 - (remain <= 1 ? remain * 100 : remain)) ?? 0);
+	const resetsAt = toIso(record[resetKey]);
+	return {
+		kind,
+		usedPercent,
+		remainingPercent: round1(100 - usedPercent),
+		...resetsAt === null ? {} : { resetsAt }
+	};
+}
+/**
+* 解析 MiniMax Token Plan `/v1/token_plan/remains` 响应。取 general(或 MiniMax-M*)
+* 一行抽出 5h/7d 窗口(total_count 常为 0,以 remaining_percent 为准),不按模型拆条。
+* 导出供测试:纯函数。
+* @param body - 接口响应 JSON。
+* @returns 窗口列表;无可用窗口时为空数组。
+*/
+function parseMiniMaxRemains(body) {
+	const doc = body ?? {};
+	const payload = doc.data ?? doc;
+	const rows = Array.isArray(payload.model_remains) ? payload.model_remains : Array.isArray(doc.model_remains) ? doc.model_remains : [];
+	if (rows.length === 0) return [];
+	const record = rows.find((row) => {
+		const name = String(row.model_name ?? "").toLowerCase();
+		return name === "general" || /^minimax-m/i.test(name);
+	}) ?? rows[0] ?? void 0;
+	return [minmaxWindow(record, "session", "current_interval_remaining_percent", "current_interval_status", "end_time"), minmaxWindow(record, "weekly", "current_weekly_remaining_percent", "current_weekly_status", "weekly_end_time")].filter((hit) => hit !== null);
+}
+/** Collect the MiniMax Token Plan quota. */
+async function collectMiniMax(keys, config, timeoutMs) {
+	const apiKey = keys.minmaxApiKey.trim();
+	const base = config.baseUrl ?? "https://www.minimaxi.com";
+	if (apiKey === "") return {
+		provider: config.provider,
+		displayName: "MiniMax Coding Plan",
+		status: "not-configured",
+		windows: []
+	};
+	try {
+		const windows = parseMiniMaxRemains(await requestJson(`${base}/v1/token_plan/remains`, { headers: {
+			authorization: `Bearer ${apiKey}`,
+			accept: "application/json"
+		} }, timeoutMs));
+		return {
+			provider: config.provider,
+			displayName: "MiniMax Coding Plan",
+			status: windows.length > 0 ? "ok" : "invalid-response",
+			windows
+		};
+	} catch (error) {
+		return {
+			provider: config.provider,
+			displayName: "MiniMax Coding Plan",
+			status: statusOf(error),
+			windows: []
+		};
+	}
+}
+/**
+* 解析 OpenRouter `/api/v1/credits` 响应:已用% = total_usage / total_credits。
+* 导出供测试:纯函数。
+* @param body - 接口响应 JSON。
+* @returns 窗口列表;无有效额度时为 []。
+*/
+function parseOpenRouterCredits(body) {
+	const doc = body ?? {};
+	const data = doc.data ?? doc;
+	const total = numberOrNull(data.total_credits ?? data.credits);
+	const used = numberOrNull(data.total_usage ?? data.usage);
+	if (total === null || total <= 0 || used === null) return [];
+	const usedPercent = round1(clampPercent(used / total * 100) ?? 0);
+	const resetsAt = toIso(data.resets_at ?? data.next_reset_time);
+	return [{
+		kind: "billing",
+		usedPercent,
+		remainingPercent: round1(100 - usedPercent),
+		...resetsAt === null ? {} : { resetsAt }
+	}];
+}
+/** Collect the OpenRouter prepaid credits usage. */
+async function collectOpenRouter(keys, config, timeoutMs) {
+	const apiKey = keys.openrouterApiKey.trim();
+	const base = config.baseUrl ?? "https://openrouter.ai";
+	if (apiKey === "") return {
+		provider: config.provider,
+		displayName: "OpenRouter",
+		status: "not-configured",
+		windows: []
+	};
+	try {
+		const windows = parseOpenRouterCredits(await requestJson(`${base}/api/v1/credits`, { headers: {
+			authorization: `Bearer ${apiKey}`,
+			accept: "application/json"
+		} }, timeoutMs));
+		return {
+			provider: config.provider,
+			displayName: "OpenRouter",
+			status: windows.length > 0 ? "ok" : "invalid-response",
+			windows
+		};
+	} catch (error) {
+		return {
+			provider: config.provider,
+			displayName: "OpenRouter",
+			status: statusOf(error),
+			windows: []
+		};
+	}
+}
+/**
 * Collect quota for the given plans concurrently (adapter-backed plans only;
 * identified plans without an adapter are surfaced by the caller as "no
 * quota API" rows).
@@ -2223,6 +2470,18 @@ const SUBSCRIPTION_KEY_SOURCES = [
 	{
 		provider: "opencode-go",
 		key: "opencodeApiKey"
+	},
+	{
+		provider: "minimax",
+		key: "minmaxApiKey"
+	},
+	{
+		provider: "minimax-token-plan",
+		key: "minmaxApiKey"
+	},
+	{
+		provider: "openrouter",
+		key: "openrouterApiKey"
 	}
 ];
 /**
@@ -2519,7 +2778,9 @@ function apply(ctx, config = {}) {
 				persistSnapshot(payload);
 				res.end(JSON.stringify(payload));
 				return;
-			} catch {}
+			} catch (error) {
+				console.error("[usage-billing] usage-stats aggregate failed, falling back to snapshot:", error);
+			}
 			for (const candidate of candidates) try {
 				const text = await readFile(candidate, "utf8");
 				const doc = JSON.parse(text);

package/lib/types/aggregate.d.ts

@@ -11,8 +11,8 @@
  */
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
 import type { TokenUsage } from '@deepseek-ai/dsh-llm';
-import { MODEL_KEY_ALIASES } from './client/pricing.ts';
-export { MODEL_KEY_ALIASES };
+import { MODEL_KEY_ALIASES, resolveCatalogKey } from './client/pricing.ts';
+export { MODEL_KEY_ALIASES, resolveCatalogKey };
 /**
  * 走订阅套餐（coding / token plan / opencode 订阅）的 provider id：这些通道的
  * 调用按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
@@ -21,10 +21,18 @@ export { MODEL_KEY_ALIASES };
  * 中覆盖。
  */
 export declare const DEFAULT_SUBSCRIPTION_PROVIDERS: readonly string[];
+/**
+ * 官方渠道 provider id 判定：`deepseek` 前缀（DeepSeek 官方直连）视为官方，
+ * 其余 provider（第三方中转/代理）视为「三方」。用于「官方 vs 三方」token、
+ * 调用与费用分桶展示；部署可由配置覆盖（见 {@link AggregateOptions}）。
+ */
+export declare function isOfficialProvider(provider: string): boolean;
 /** Aggregation tuning options. */
 export interface AggregateOptions {
     /** 订阅制 provider id 列表；默认 {@link DEFAULT_SUBSCRIPTION_PROVIDERS}。 */
     subscriptionProviders?: readonly string[];
+    /** 官方渠道 provider id 列表；默认按 {@link isOfficialProvider} 判定（DeepSeek 官方直连）。 */
+    officialProviderIds?: readonly string[];
 }
 /** One model's aggregated usage plus estimated cost in CNY. */
 export interface ModelUsage {
@@ -36,6 +44,10 @@ export interface ModelUsage {
     cost: number;
     /** 该模型本次统计的所有调用是否都走订阅通道（coding/token plan）；混合通道不置位。 */
     plan?: boolean;
+    /** 走官方渠道的调用数（DeepSeek 官方直连；其余为三方）。 */
+    officialCalls: number;
+    /** 走官方渠道的费用（CNY）；三方费用 = cost - officialCost。 */
+    officialCost: number;
 }
 /** Zeroed usage accumulator. */
 export declare function emptyUsage(): ModelUsage;
@@ -48,8 +60,9 @@ export declare function emptyUsage(): ModelUsage;
  * @param key - the billing-catalog key this call belongs to.
  * @param subscription - whether the call went through a subscription plan; such calls never cost money.
  * @param timeMs - the call's wall-clock time (epoch ms); drives peak/off-peak pricing.
+ * @param official - whether the call went through the official DeepSeek channel (vs a third-party relay).
  */
-export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean, timeMs: number): void;
+export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean, timeMs: number, official?: boolean): void;
 /** Local-time date stamp (the host runs in the user's timezone). */
 export declare function dayStamp(time: number): string;
 /** cwd 未知时工作区聚合的占位名（UI 显示 em dash，保持语言无关）。 */
@@ -180,13 +193,15 @@ export declare function messageTextLength(message: unknown): number;
  * 并按轮次折叠每轮费用明细（turn/start → turn/end；调用按 (turn) 归组）。
  * @param events - the session's persisted events in log order.
  * @param subscriptionProviders - provider ids billed through subscription plans.
+ * @param officialProviderIds - provider ids treated as the official DeepSeek channel
+ *   (default: any `deepseek`-prefixed id). Others count as third-party.
  * @returns the per-session fold (cached by the incremental aggregator).
  */
 export declare function foldSession(events: readonly {
     type: string;
     time: number;
     data: never;
-}[], subscriptionProviders: ReadonlySet<string>): SessionFold;
+}[], subscriptionProviders: ReadonlySet<string>, officialProviderIds?: ReadonlySet<string>): SessionFold;
 /**
  * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——
  * 日志没动的会话直接复用，只有写过的会话重新折叠；整份文档另有短 TTL

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

@@ -0,0 +1,18 @@
+/**
+ * 峰谷切换提醒浮层：切档前状态条（右下角或居中）。用 `position: fixed` 即可在
+ * 任意宿主容器内覆盖整个视口，因此不需要 portal。布局为「档位徽标 + 大号等宽
+ * 倒计时 + 一句说明 + 关闭」，克制冷调、无重力阴影。渲染是受控的：父组件把命中
+ * （hit）与偏好传入，显示剩余分钟并在切换后消失。
+ */
+import type { PeakAlertConfig, PeakAlertHit } from './peak-alert.ts';
+import type { UsageBillingKey } from './locales.ts';
+/** Props: 命中的切档、偏好、国际化、关闭回调。 */
+export interface PeakAlertBannerProps {
+    hit: PeakAlertHit;
+    config: PeakAlertConfig;
+    t: (key: UsageBillingKey) => string;
+    onDismiss: () => void;
+}
+/** 渲染一个切档前提醒状态条。 */
+export declare function PeakAlertBanner({ hit, config, t, onDismiss }: PeakAlertBannerProps): React.ReactNode;
+//# sourceMappingURL=PeakAlertBanner.d.ts.map

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

@@ -32,11 +32,11 @@ export interface ModelHealth {
     catalog?: readonly CatalogModel[];
 }
 /** 仪表盘分区 Tab id。 */
-export type DashboardTab = 'overview' | 'trends' | 'providers' | 'details' | 'pricing';
+export type DashboardTab = 'overview' | 'trends' | 'providers' | 'details' | 'pricing' | 'settings';
 /**
- * Tab 定义（顺序即渲染顺序）：概览=主数字/预算/KPI/热力图，趋势=趋势图/每轮费用，
- * 明细=厂商计费与订阅，统计=工作区/会话明细，费率=模型单价表。导出供测试断言
- * tab 与文案 key 对齐、decor 锚点落在正确分区。
+ * Tab 定义（顺序即渲染顺序）：概览=主数字/KPI/热力图，趋势=趋势图/每轮费用，
+ * 明细=厂商计费与订阅，统计=工作区/会话明细，费率=模型单价表，设置=预算与峰谷提醒。
+ * 导出供测试断言 tab 与文案 key 对齐、decor 锚点落在正确分区。
  */
 export declare const DASHBOARD_TABS: readonly {
     id: DashboardTab;

package/lib/types/client/completion-notify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 对话完成提醒：监听宿主 `sessions.list` 的会话状态迁移，一个会话
+ * `running → completed`（或不再 running）时触发一次桌面通知。
+ *
+ * 可选：跨 tab 只保留一个提醒 leader（Web Locks 优先，降级 localStorage 租约），
+ * 避免多窗口同时弹同一条。配置持久化在 localStorage（默认关闭，用户在面板设置开启）。
+ */
+import type { SessionListState } from '@deepseek-ai/dsh-client-runtime/client';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+/** 配置持久化 key：开启/关闭 + 提醒持续模式（0=常驻，其余=秒后自动关）。 */
+export declare const COMPLETION_NOTIFY_KEY = "dsh-billing-completion-notify-v1";
+export interface CompletionNotifyConfig {
+    enabled: boolean;
+    /** 通知停留秒数；0 = 常驻（requireInteraction）。 */
+    timeout: number;
+}
+/** 读取本地配置（缺失/损坏时回退默认）。 */
+export declare function loadNotifyConfig(): CompletionNotifyConfig;
+/** 保存配置；存储失败静默（通知功能降级为关闭，不影响其他能力）。 */
+export declare function saveNotifyConfig(config: CompletionNotifyConfig): void;
+/**
+ * 安装对话完成提醒：订阅 sessions.list 快照，用 `previousFinished` 记住每条
+ * 会话上次是运行中还是已完成；只有「之前运行中 → 现在已完成」的迁移才提醒，
+ * 首次快照只建立基线、不提醒。返回清理函数（dispose 时释放订阅）。
+ * @param list - `ctx.sessions.list`（宿主注入的会话列表快照源）。
+ */
+export declare function installCompletionNotifier(list: ObservableSnapshot<SessionListState>, getConfig: () => CompletionNotifyConfig): () => void;
+//# sourceMappingURL=completion-notify.d.ts.map