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

package/lib/index.js

@@ -1,10 +1,26 @@
 import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 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;
@@ -542,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
@@ -597,6 +650,28 @@ function computeCostAt(entry, buckets, timeMs, peakShare = DEFAULT_PEAK_SHARE) {
 	if (timeMs === null || timeMs === void 0 || !Number.isFinite(timeMs)) return computeCost(entry, buckets, peakShare);
 	return priceBandCost(tierAt(timeMs) === "peak" ? entry.price : entry.price.offPeak, buckets, entry.price.currency);
 }
+/**
+* Format an amount with adaptive precision and the given currency symbol.
+* @param amount - the amount (CNY by default; pass `usd` for dollar display).
+* @param currency - display currency; default `cny`.
+*/
+function formatMoney(amount, currency = "cny") {
+	const value = Number(amount);
+	if (!Number.isFinite(value)) return currency === "cny" ? "¥0" : "$0";
+	const symbol = currency === "cny" ? "¥" : "$";
+	if (value <= 0) return `${symbol}0`;
+	if (value >= 1e3) return `${symbol}${value.toFixed(0)}`;
+	if (value >= 10) return `${symbol}${value.toFixed(1)}`;
+	if (value >= .1) return `${symbol}${value.toFixed(2)}`;
+	return `${symbol}${value.toFixed(3)}`;
+}
+/** Format a large token count with B/M/K suffix. */
+function formatTokens(value) {
+	if (value >= 1e9) return `${(value / 1e9).toFixed(2)}B`;
+	if (value >= 1e6) return `${(value / 1e6).toFixed(1)}M`;
+	if (value >= 1e3) return `${(value / 1e3).toFixed(0)}K`;
+	return String(value);
+}
 //#endregion
 //#region lib/types/aggregate.js
 /**
@@ -657,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,
@@ -675,6 +750,22 @@ function workspaceNameOf(cwd) {
 	if (cwd === void 0 || cwd === "") return "—";
 	return cwd.split(/[\\/]/).filter(Boolean).at(-1) ?? "—";
 }
+/**
+* 消息文本长度：user/tool 角色分摊输入成本的启发式依据。字符串内容取其
+* 长度；内容块数组累计文本块长度；其余形状按 0 计（durable 边界收窄）。
+*/
+function messageTextLength(message) {
+	if (message === null || typeof message !== "object") return 0;
+	const content = message.content;
+	if (typeof content === "string") return content.length;
+	if (!Array.isArray(content)) return 0;
+	let total = 0;
+	for (const block of content) {
+		const text = block?.text;
+		if (typeof text === "string") total += text.length;
+	}
+	return total;
+}
 /** Get-or-create one model cell inside a usage map (avoids non-null assertions). */
 function usageCell(map, key) {
 	const existing = map.get(key);
@@ -725,6 +816,12 @@ function foldSession(events, subscriptionProviders) {
 		byDayModels: /* @__PURE__ */ new Map(),
 		planCalls: /* @__PURE__ */ new Map(),
 		turns: [],
+		roles: {
+			userChars: 0,
+			toolChars: 0,
+			inputCost: 0,
+			outputCost: 0
+		},
 		lastActive: 0
 	};
 	let key = "other";
@@ -737,6 +834,14 @@ function foldSession(events, subscriptionProviders) {
 			if (typeof title === "string" && title.length > 0) fold.title = title;
 			continue;
 		}
+		if (event.type === "user/message") {
+			fold.roles.userChars += messageTextLength(event.data.message);
+			continue;
+		}
+		if (event.type === "tool/result") {
+			fold.roles.toolChars += messageTextLength(event.data.message);
+			continue;
+		}
 		if (event.type === "turn/start") {
 			const state = turnState(turns, event.data.turn ?? -1);
 			if (event.time < state.startedAt) state.startedAt = event.time;
@@ -770,12 +875,24 @@ 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)) state.cost += computeCostAt(modelOf(modelKey), {
-			input: (usage.cacheReadTokens ?? 0) + usage.inputTokens + (usage.cacheWriteTokens ?? 0),
-			cacheHit: usage.cacheReadTokens ?? 0,
-			cacheMiss: usage.inputTokens + (usage.cacheWriteTokens ?? 0),
-			output: usage.outputTokens
-		}, event.time);
+		if (!subscription && isPriced(modelKey)) {
+			const buckets = {
+				input: (usage.cacheReadTokens ?? 0) + usage.inputTokens + (usage.cacheWriteTokens ?? 0),
+				cacheHit: usage.cacheReadTokens ?? 0,
+				cacheMiss: usage.inputTokens + (usage.cacheWriteTokens ?? 0),
+				output: usage.outputTokens
+			};
+			const fullCost = computeCostAt(modelOf(modelKey), buckets, event.time);
+			state.cost += fullCost;
+			const outputCost = computeCostAt(modelOf(modelKey), {
+				input: 0,
+				cacheHit: 0,
+				cacheMiss: 0,
+				output: usage.outputTokens
+			}, event.time);
+			fold.roles.outputCost += outputCost;
+			fold.roles.inputCost += fullCost - outputCost;
+		}
 		if (state.startedAt === Number.MAX_SAFE_INTEGER) state.startedAt = event.time;
 	}
 	fold.turns = [...turns.values()].filter((state) => state.input > 0 || state.output > 0).sort((a, b) => a.turn - b.turn).map((state) => ({
@@ -860,9 +977,19 @@ function createUsageAggregator(persistence, options = {}) {
 		const sessionRows = [];
 		const turnRows = [];
 		const workspaceMap = /* @__PURE__ */ new Map();
+		const roles = {
+			userChars: 0,
+			toolChars: 0,
+			inputCost: 0,
+			outputCost: 0
+		};
 		for (const { meta, fold } of folds) {
 			const sessionId = String(meta.id);
 			mergeUsageInto(total, fold.total);
+			roles.userChars += fold.roles.userChars;
+			roles.toolChars += fold.roles.toolChars;
+			roles.inputCost += fold.roles.inputCost;
+			roles.outputCost += fold.roles.outputCost;
 			for (const [modelKey, cell] of fold.byModel) mergeUsageInto(usageCell(byModel, modelKey), cell);
 			for (const [day, cell] of fold.byDay) mergeUsageInto(usageCell(byDay, day), cell);
 			for (const [day, models] of fold.byDayModels) for (const [modelKey, cell] of models) mergeUsageInto(modelDayCell(byDayModels, day, modelKey), cell);
@@ -918,7 +1045,16 @@ function createUsageAggregator(persistence, options = {}) {
 			byDayModels: toModelDayRecord(byDayModels),
 			bySession: sessionRows.slice(0, 100),
 			byTurn: turnRows.slice(0, 200),
-			byWorkspace: workspaces.slice(0, 100)
+			byWorkspace: workspaces.slice(0, 100),
+			byRole: (() => {
+				const chars = roles.userChars + roles.toolChars;
+				const userShare = chars > 0 ? roles.userChars / chars : .5;
+				return {
+					user: roles.inputCost * userShare,
+					assistant: roles.outputCost,
+					tool: roles.inputCost * (1 - userShare)
+				};
+			})()
 		};
 		lastAt = now;
 		return lastDoc;
@@ -1113,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
 /**
@@ -1150,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
@@ -1250,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
@@ -1400,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,
@@ -1676,6 +2017,8 @@ const PRICING_REFRESH_INTERVAL_MS = 360 * 60 * 1e3;
 const SUBSCRIPTION_CACHE_MS = 300 * 1e3;
 /** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
 const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
+/** 统计快照的落盘节流（毫秒）：前端 30 秒轮询，快照最多每 30 秒写一次。 */
+const SNAPSHOT_INTERVAL_MS = 3e4;
 /** Required services: the web server, the persisted session log store, and user settings. */
 const inject = [
 	"webServer",
@@ -1759,15 +2102,160 @@ async function resolveSubscriptionKeys(settings, credentials) {
 function apply(ctx, config = {}) {
 	const aggregator = createUsageAggregator(ctx.sessionPersistence, { ...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders } });
 	const cwd = process.cwd();
+	const snapshotPath = join(homedir(), ".dsh/.dsh-usage-stats.json");
 	const candidates = [
 		config.statsPath,
 		process.env.DSH_USAGE_STATS,
 		join(cwd, ".dsh-usage-stats.json"),
-		join(homedir(), ".dsh/.dsh-usage-stats.json")
+		snapshotPath
 	].filter((path) => typeof path === "string" && path.length > 0);
+	let lastSnapshotAt = 0;
+	const persistSnapshot = (doc) => {
+		const now = Date.now();
+		if (now - lastSnapshotAt < SNAPSHOT_INTERVAL_MS) return;
+		lastSnapshotAt = now;
+		writeFileAtomic(snapshotPath, JSON.stringify({
+			...doc,
+			_writer: {
+				pid: process.pid,
+				at: now
+			}
+		}), {
+			mode: 384,
+			dirMode: 448
+		}).catch(() => {});
+	};
+	(async () => {
+		try {
+			const text = await readFile(snapshotPath, "utf8");
+			const writer = JSON.parse(text)._writer;
+			if (writer?.pid !== void 0 && writer.pid !== process.pid && writer.at !== void 0 && Date.now() - writer.at < 6e4) console.warn(`[usage-billing] 检测到另一实例（pid ${writer.pid}）正在提供用量统计，双实例可能导致提醒重复。`);
+		} catch {}
+	})();
+	ctx.inject(["tools"], (toolsCtx) => {
+		toolsCtx.tools.register(defineTool({
+			name: "usage_stats",
+			description: "查询本机 DeepSeek Harness 的模型用量与估算费用（人民币，按官方目录价估算，非账单）。range 取值：today=今天，month=本月，session=当前会话，all=累计。",
+			parameters: { range: {
+				type: "string",
+				enum: [
+					"today",
+					"month",
+					"session",
+					"all"
+				],
+				required: true,
+				description: "统计范围：today / month / session / all"
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						range: {
+							type: "string",
+							required: true
+						},
+						cost: {
+							type: "number",
+							required: true,
+							description: "估算费用（人民币元）"
+						},
+						calls: {
+							type: "number",
+							required: true
+						},
+						input: {
+							type: "number",
+							required: true,
+							description: "输入 tokens"
+						},
+						output: {
+							type: "number",
+							required: true,
+							description: "输出 tokens"
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `用量（${value.range}）：估算费用 ${formatMoney(value.cost)}，调用 ${value.calls} 次，输入 ${formatTokens(value.input)} tokens，输出 ${formatTokens(value.output)} tokens`
+				}]
+			},
+			async execute(args, exec) {
+				const stats = await aggregator.aggregate();
+				const zero = {
+					range: args.range,
+					cost: 0,
+					calls: 0,
+					input: 0,
+					output: 0
+				};
+				if (args.range === "all") return {
+					range: args.range,
+					cost: stats.total.cost,
+					calls: stats.total.calls,
+					input: stats.total.input,
+					output: stats.total.output
+				};
+				if (args.range === "today") {
+					const day = stats.byDay[dayStamp(Date.now())];
+					return day === void 0 ? zero : {
+						range: args.range,
+						cost: day.cost,
+						calls: day.calls,
+						input: day.input,
+						output: day.output
+					};
+				}
+				if (args.range === "month") {
+					const prefix = dayStamp(Date.now()).slice(0, 7);
+					let cost = 0;
+					let calls = 0;
+					let input = 0;
+					let output = 0;
+					for (const [date, day] of Object.entries(stats.byDay)) {
+						if (!date.startsWith(prefix)) continue;
+						cost += day.cost;
+						calls += day.calls;
+						input += day.input;
+						output += day.output;
+					}
+					return {
+						range: args.range,
+						cost,
+						calls,
+						input,
+						output
+					};
+				}
+				const sessionId = exec.agent?.id;
+				if (sessionId === void 0) throw new Error("usage_stats 的 session 范围需要 agent 会话上下文");
+				let cost = 0;
+				let calls = 0;
+				let input = 0;
+				let output = 0;
+				for (const turn of stats.byTurn ?? []) {
+					if (turn.sessionId !== String(sessionId)) continue;
+					cost += turn.cost;
+					calls += 1;
+					input += turn.input;
+					output += turn.output;
+				}
+				return {
+					range: args.range,
+					cost,
+					calls,
+					input,
+					output
+				};
+			}
+		}));
+	});
 	let live = { source: "builtin" };
 	const refreshPricing = async () => {
 		live = await fetchLivePricing();
+		applyLivePricing(live);
 	};
 	refreshPricing();
 	ctx.effect(() => {
@@ -1794,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 = {
@@ -1838,10 +2327,12 @@ function apply(ctx, config = {}) {
 					...config.monthlyBudget === void 0 ? {} : { budget: config.monthlyBudget },
 					...config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: config.lowBalanceThreshold }
 				};
-				res.end(JSON.stringify(Object.keys(injected).length === 0 ? stats : {
+				const payload = Object.keys(injected).length === 0 ? stats : {
 					...stats,
 					...injected
-				}));
+				};
+				persistSnapshot(payload);
+				res.end(JSON.stringify(payload));
 				return;
 			} catch {}
 			for (const candidate of candidates) try {