@kenz1117/dsh-ui-usage-billing 1.0.6 → 1.0.8

package/lib/index.js

@@ -905,7 +905,8 @@ const MODEL_CATALOG = [
 				output: 6
 			}
 		},
-		peakHours: "Standard / Flex"
+		peakHours: "Standard / Flex",
+		tierSemantics: "latency"
 	},
 	{
 		key: "gemini-flash",
@@ -923,7 +924,8 @@ const MODEL_CATALOG = [
 				output: 3.75
 			}
 		},
-		peakHours: "Standard / Flex"
+		peakHours: "Standard / Flex",
+		tierSemantics: "latency"
 	},
 	{
 		key: "grok",
@@ -1638,8 +1640,9 @@ function formatTokens(value) {
 * Real-usage aggregation: folds every persisted session log into the
 * usage-stats document the dashboard renders.
 *
-* Each LLM call is attributed to the model of the `request/header` event that
-* precedes its `assistant/message` usage event. Costs are estimated with the
+* Each LLM call is attributed to the `message.source` carried by its own
+* `assistant/message` event (copied from the request at write time); the
+* sparse `request/header` is only a fallback. Costs are estimated with the
 * shared billing catalog (`pricing.ts`, in CNY), so only models the catalog
 * prices incur a cost — subscription-plan routes and unknown models price
 * zero while their tokens still count. Pure functions only: the persistence
@@ -1745,6 +1748,7 @@ function foldUsage(acc, usage, key, subscription, timeMs, official = false) {
 	acc.reasoning += usage.reasoningTokens ?? 0;
 	acc.cacheHit += cacheHit;
 	acc.cacheMiss += cacheMiss;
+	if ((usage.cacheWriteTokens ?? 0) > 0) acc.cacheWrite = (acc.cacheWrite ?? 0) + (usage.cacheWriteTokens ?? 0);
 	if (official) acc.officialCalls += 1;
 	if (!subscription && isPriced(key)) {
 		const thisCost = computeCostAt(modelOf(key), {
@@ -1796,11 +1800,23 @@ function workspaceNameOf(cwd) {
 	if (cwd === void 0 || cwd === "") return "—";
 	return cwd.split(/[\\/]/).filter(Boolean).at(-1) ?? "—";
 }
+/** TTFT 尖峰阈值（毫秒）：超过计为一次尖峰样本，用于定位服务端抖动。 */
+const PERF_SPIKE_MS = 1e4;
 /**
-* 账本迁移注册表。当前账本 schema（version 1）尚无字段变更需求，故为空表；
-* 机制已就绪，schema 变更时在此登记幂等迁移，见 {@link LedgerMigration}。
+* 账本迁移注册表。首条迁移给 1.0.6 及更早的行回填 foldVersion = 1（它们全部出自
+* header 归因算法）；此后新写入的行总带当前 {@link FOLD_VERSION}。
 */
-const LEDGER_MIGRATIONS = [];
+const LEDGER_MIGRATIONS = [{
+	id: "fold-version-backfill",
+	apply(document) {
+		let changed = false;
+		for (const session of document.sessions) if (session.foldVersion === void 0) {
+			session.foldVersion = 1;
+			changed = true;
+		}
+		return changed;
+	}
+}];
 /**
 * 在加载边界对账本文档应用未执行的迁移，并记录已应用 id 供写回。
 * @param document - 从持久化读出的原始账本文档。
@@ -1828,6 +1844,8 @@ function serializeFold(fold) {
 		byModel: Object.fromEntries(fold.byModel),
 		byDay: Object.fromEntries(fold.byDay),
 		byDayModels: Object.fromEntries([...fold.byDayModels].map(([day, models]) => [day, Object.fromEntries(models)])),
+		byTier: Object.fromEntries(fold.byTier),
+		byTool: Object.fromEntries(fold.byTool),
 		bySite: Object.fromEntries(fold.bySite),
 		unpricedModels: [...fold.unpricedModels],
 		planCalls: Object.fromEntries(fold.planCalls),
@@ -1844,6 +1862,8 @@ function deserializeFold(fold) {
 		byModel: new Map(Object.entries(fold.byModel)),
 		byDay: new Map(Object.entries(fold.byDay)),
 		byDayModels: new Map(Object.entries(fold.byDayModels).map(([day, models]) => [day, new Map(Object.entries(models))])),
+		byTier: new Map(Object.entries(fold.byTier ?? {})),
+		byTool: new Map(Object.entries(fold.byTool ?? {})),
 		bySite: new Map(Object.entries(fold.bySite)),
 		unpricedModels: new Set(fold.unpricedModels),
 		planCalls: new Map(Object.entries(fold.planCalls)),
@@ -1918,7 +1938,9 @@ function turnState(turns, turn) {
 }
 /**
 * Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
-* 其前置 request/header 记录的模型；同时提取最新会话标题、最后活跃时间，
+* 其 `assistant/message` 自带 `message.source` 记录的模型（agent-loop 落盘时从
+* 当次请求复制，每个调用一条，不依赖稀疏的 request/header）；source 缺失时
+* 兜底到最近一次 request/header 的状态。同时提取最新会话标题、最后活跃时间，
 * 并按轮次折叠每轮费用明细（turn/start → turn/end；调用按 (turn) 归组）。
 * @param events - the session's persisted events in log order.
 * @param subscriptionProviders - provider ids billed through subscription plans.
@@ -1937,6 +1959,8 @@ function foldSession(events, subscriptionProviders, officialProviderIds, routes
 		byModel: /* @__PURE__ */ new Map(),
 		byDay: /* @__PURE__ */ new Map(),
 		byDayModels: /* @__PURE__ */ new Map(),
+		byTier: /* @__PURE__ */ new Map(),
+		byTool: /* @__PURE__ */ new Map(),
 		bySite: /* @__PURE__ */ new Map(),
 		unpricedModels: /* @__PURE__ */ new Set(),
 		planCalls: /* @__PURE__ */ new Map(),
@@ -1957,6 +1981,7 @@ function foldSession(events, subscriptionProviders, officialProviderIds, routes
 	const turns = /* @__PURE__ */ new Map();
 	const steps = /* @__PURE__ */ new Map();
 	let lastOpenStepKey;
+	const toolSeen = /* @__PURE__ */ new Set();
 	for (const event of events) {
 		if (seedBoundary >= 0 && typeof event.seq === "number" && Number.isFinite(event.seq) && event.seq < seedBoundary) continue;
 		fold.lastActive = Math.max(fold.lastActive, event.time);
@@ -2018,11 +2043,28 @@ function foldSession(events, subscriptionProviders, officialProviderIds, routes
 					state.lastContentTime = event.time;
 				}
 			}
+			if (chunk?.type === "tool-call-delta" && typeof turn === "number" && typeof step === "number") {
+				const index = chunk.index;
+				const name = chunk.name;
+				const seenKey = `${turn}:${step}:${typeof index === "number" ? index : "-"}`;
+				if (!toolSeen.has(seenKey)) {
+					toolSeen.add(seenKey);
+					const toolName = typeof name === "string" && name !== "" ? name : "unknown";
+					fold.byTool.set(toolName, (fold.byTool.get(toolName) ?? 0) + 1);
+				}
+			}
 			continue;
 		}
 		if (event.type !== "assistant/message") continue;
 		const usage = event.data.usage;
 		if (usage === void 0) continue;
+		const source = event.data.message?.source;
+		if (source?.kind === "model" && typeof source.provider === "string" && typeof source.model === "string") {
+			key = resolveCatalogKey(source.model);
+			subscription = subscriptionProviders.has(source.provider);
+			official = officialProviderIds === void 0 ? isOfficialProvider(source.provider) : officialProviderIds.has(source.provider);
+			siteBucket = siteBucketKey(siteRefOf(source.provider, routes));
+		}
 		const modelKey = key;
 		const day = dayStamp(event.time);
 		if (!subscription && !isPriced(modelKey)) fold.unpricedModels.add(modelKey);
@@ -2031,6 +2073,7 @@ function foldSession(events, subscriptionProviders, officialProviderIds, routes
 		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time, official);
 		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time, official);
 		foldUsage(usageCell(fold.bySite, siteBucket), usage, modelKey, subscription, event.time, official);
+		foldUsage(usageCell(fold.byTier, tierAt(event.time)), usage, modelKey, subscription, event.time, official);
 		if (subscription) fold.planCalls.set(modelKey, (fold.planCalls.get(modelKey) ?? 0) + 1);
 		const turn = event.data.turn ?? -1;
 		const state = turnState(turns, turn);
@@ -2112,6 +2155,7 @@ function mergeUsageInto(acc, cell) {
 	acc.reasoning += cell.reasoning;
 	acc.cacheHit += cell.cacheHit;
 	acc.cacheMiss += cell.cacheMiss;
+	if (cell.cacheWrite !== void 0) acc.cacheWrite = (acc.cacheWrite ?? 0) + cell.cacheWrite;
 	acc.cost += cell.cost;
 	acc.officialCalls += cell.officialCalls;
 	acc.officialCost += cell.officialCost;
@@ -2151,6 +2195,7 @@ function createUsageAggregator(persistence, options = {}) {
 	const ledger = /* @__PURE__ */ new Map();
 	let ledgerLoaded = false;
 	let ledgerNeedsSave = false;
+	let ledgerAppliedMigrations;
 	let lastDoc;
 	let lastAt = 0;
 	/** 每次聚合取最新的 provider 路由视图（中转站零配置发现）；缺省按空处理（全部未知路由）。 */
@@ -2161,7 +2206,9 @@ function createUsageAggregator(persistence, options = {}) {
 		try {
 			const stored = await options.ledger.load();
 			if (stored !== null && typeof stored === "object" && stored.sessions !== void 0) {
-				if (runLedgerMigrations(stored)) ledgerNeedsSave = true;
+				const document = stored;
+				if (runLedgerMigrations(document)) ledgerNeedsSave = true;
+				ledgerAppliedMigrations = document.appliedMigrations;
 			}
 			for (const entry of ledgerSessionsOf(stored)) ledger.set(entry.id, entry);
 		} catch (error) {
@@ -2196,6 +2243,7 @@ function createUsageAggregator(persistence, options = {}) {
 		const included = /* @__PURE__ */ new Set();
 		const folds = [];
 		const skipped = [];
+		let staleLedgerSessions = 0;
 		for (const meta of metas) {
 			const id = String(meta.id);
 			seen.add(id);
@@ -2232,10 +2280,11 @@ function createUsageAggregator(persistence, options = {}) {
 						id,
 						...meta.cwd === void 0 ? {} : { cwd: meta.cwd },
 						...stamp === null ? {} : { stamp },
+						foldVersion: 2,
 						fold: serializeFold(fold)
 					};
 					const previous = ledger.get(id);
-					if (previous === void 0 || previous.stamp !== entry.stamp || previous.cwd !== entry.cwd || stamp === null && JSON.stringify(previous.fold) !== JSON.stringify(entry.fold)) {
+					if (previous === void 0 || previous.stamp !== entry.stamp || previous.cwd !== entry.cwd || previous.foldVersion !== entry.foldVersion || stamp === null && JSON.stringify(previous.fold) !== JSON.stringify(entry.fold)) {
 						ledger.set(id, entry);
 						ledgerNeedsSave = true;
 					}
@@ -2255,12 +2304,15 @@ function createUsageAggregator(persistence, options = {}) {
 			for (const entry of ledger.values()) {
 				if (included.has(entry.id)) continue;
 				try {
+					const stale = (entry.foldVersion ?? 1) < 2;
 					folds.push({
 						id: entry.id,
 						...entry.cwd === void 0 ? {} : { cwd: entry.cwd },
+						...stale ? { staleLedger: true } : {},
 						fold: deserializeFold(entry.fold)
 					});
 					included.add(entry.id);
+					if (stale) staleLedgerSessions += 1;
 				} catch (error) {
 					console.warn("[usage-billing] skip invalid durable ledger session", entry.id, error);
 				}
@@ -2269,7 +2321,8 @@ function createUsageAggregator(persistence, options = {}) {
 				await options.ledger.save({
 					version: 1,
 					updatedAt: now,
-					sessions: [...ledger.values()]
+					sessions: [...ledger.values()],
+					...ledgerAppliedMigrations === void 0 ? {} : { appliedMigrations: ledgerAppliedMigrations }
 				});
 				ledgerNeedsSave = false;
 			} catch (error) {
@@ -2281,6 +2334,8 @@ function createUsageAggregator(persistence, options = {}) {
 		const byModel = /* @__PURE__ */ new Map();
 		const byDay = /* @__PURE__ */ new Map();
 		const byDayModels = /* @__PURE__ */ new Map();
+		const byTier = /* @__PURE__ */ new Map();
+		const byTool = /* @__PURE__ */ new Map();
 		const bySite = /* @__PURE__ */ new Map();
 		const unpricedModels = /* @__PURE__ */ new Set();
 		const planCalls = /* @__PURE__ */ new Map();
@@ -2295,7 +2350,7 @@ function createUsageAggregator(persistence, options = {}) {
 		};
 		const perfModel = /* @__PURE__ */ new Map();
 		const perfHour = /* @__PURE__ */ new Map();
-		for (const { id: sessionId, cwd, fold } of folds) {
+		for (const { id: sessionId, cwd, fold, staleLedger } of folds) {
 			mergeUsageInto(total, fold.total);
 			roles.userChars += fold.roles.userChars;
 			roles.toolChars += fold.roles.toolChars;
@@ -2305,6 +2360,8 @@ function createUsageAggregator(persistence, options = {}) {
 			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);
 			for (const [siteKey, cell] of fold.bySite) mergeUsageInto(usageCell(bySite, siteKey), cell);
+			for (const [tierKey, cell] of fold.byTier) mergeUsageInto(usageCell(byTier, tierKey), cell);
+			for (const [toolName, count] of fold.byTool) byTool.set(toolName, (byTool.get(toolName) ?? 0) + count);
 			for (const id of fold.unpricedModels) unpricedModels.add(id);
 			for (const [modelKey, count] of fold.planCalls) planCalls.set(modelKey, (planCalls.get(modelKey) ?? 0) + count);
 			for (const sample of fold.perf) {
@@ -2356,6 +2413,7 @@ function createUsageAggregator(persistence, options = {}) {
 				id: sessionId,
 				...fold.title !== void 0 ? { title: fold.title } : {},
 				...cwd !== void 0 ? { cwd } : {},
+				...staleLedger === true ? { stale: true } : {},
 				calls: fold.total.calls,
 				cost: fold.total.cost,
 				lastActive: fold.lastActive
@@ -2380,6 +2438,8 @@ function createUsageAggregator(persistence, options = {}) {
 				ttftAvg: mean(acc.ttfts),
 				ttftP50: percentile(acc.ttfts, .5),
 				ttftP90: percentile(acc.ttfts, .9),
+				ttftMax: Math.max(...acc.ttfts),
+				ttftSpikes: acc.ttfts.filter((ttft) => ttft > PERF_SPIKE_MS).length,
 				...acc.tps.length === 0 ? {} : { tpsAvg: mean(acc.tps) },
 				latencyAvg: acc.latencies.length === 0 ? 0 : mean(acc.latencies),
 				estimatedSamples: acc.estimated
@@ -2402,9 +2462,15 @@ function createUsageAggregator(persistence, options = {}) {
 			bySession: sessionRows.slice(0, 100),
 			byTurn: turnRows.slice(0, 200),
 			byWorkspace: workspaces.slice(0, 100),
+			...byTier.size === 0 ? {} : { byTier: {
+				peak: byTier.get("peak") ?? emptyUsage(),
+				offPeak: byTier.get("offPeak") ?? emptyUsage()
+			} },
+			...byTool.size === 0 ? {} : { byTool: Object.fromEntries([...byTool].sort((a, b) => b[1] - a[1])) },
 			...bySite.size === 0 ? {} : { bySite: toRecord(bySite) },
 			...unpricedModels.size === 0 ? {} : { unpricedModels: [...unpricedModels].sort() },
 			...perf === void 0 ? {} : { perf },
+			...staleLedgerSessions > 0 ? { staleLedgerSessions } : {},
 			byRole: (() => {
 				const chars = roles.userChars + roles.toolChars;
 				const userShare = chars > 0 ? roles.userChars / chars : .5;

package/lib/types/aggregate.d.ts

@@ -2,8 +2,9 @@
  * Real-usage aggregation: folds every persisted session log into the
  * usage-stats document the dashboard renders.
  *
- * Each LLM call is attributed to the model of the `request/header` event that
- * precedes its `assistant/message` usage event. Costs are estimated with the
+ * Each LLM call is attributed to the `message.source` carried by its own
+ * `assistant/message` event (copied from the request at write time); the
+ * sparse `request/header` is only a fallback. Costs are estimated with the
  * shared billing catalog (`pricing.ts`, in CNY), so only models the catalog
  * prices incur a cost — subscription-plan routes and unknown models price
  * zero while their tokens still count. Pure functions only: the persistence
@@ -83,6 +84,11 @@ export interface ModelUsage {
     output: number;
     cacheHit: number;
     cacheMiss: number;
+    /**
+     * 显式缓存写入 token（部分厂商单独计价的 cache creation）——已包含在
+     * `cacheMiss` 内，单列供结构展示；旧快照缺失。
+     */
+    cacheWrite?: number;
     cost: number;
     /** 输出中的 reasoning（思考）token；已包含在 `output` 内，单列用于结构展示。 */
     reasoning: number;
@@ -146,6 +152,16 @@ export interface UsageStatsDocument {
     byDay: Record<string, ModelUsage>;
     /** 模型 × 日期 二维统计：趋势图按模型堆叠的输入（[date][modelKey]）。 */
     byDayModels: Record<string, Record<string, ModelUsage>>;
+    /**
+     * 峰谷分桶（真实判档）：折叠时逐调用按 `tierAt(event.time)` 归入高峰/低谷桶，
+     * 峰谷占比与「挪谷省钱」据此展示，不再按比例估算。旧快照可能缺失。
+     */
+    byTier?: {
+        peak: ModelUsage;
+        offPeak: ModelUsage;
+    };
+    /** 工具调用次数排行（键 = 工具名，按调用数倒序）；token 无法按工具归因，仅计次。旧快照可能缺失。 */
+    byTool?: Record<string, number>;
     /** 会话明细：按费用倒序，封顶 {@link SESSION_ROW_LIMIT} 行；旧快照可能缺失。 */
     bySession: SessionUsageRow[];
     /** 每轮费用明细：按起始时间倒序，封顶 {@link TURN_ROW_LIMIT} 行；旧快照可能缺失。 */
@@ -200,6 +216,10 @@ export interface ModelPerf {
     ttftP50: number;
     /** 首字延时 P90（毫秒）。 */
     ttftP90: number;
+    /** 首字延时最大值（毫秒）；定位偶发慢响应。 */
+    ttftMax: number;
+    /** 首字延时尖峰样本数（> 10s）；定位服务端抖动。 */
+    ttftSpikes: number;
     /** 平均生成速度（tokens/s）；生成了有效输出且时长可测时存在。 */
     tpsAvg?: number;
     /** 平均总延迟（首次请求 → 响应完成，毫秒）。 */
@@ -226,6 +246,8 @@ export interface SessionUsageRow {
     cost: number;
     /** 最后一个事件的时间戳（毫秒）。 */
     lastActive: number;
+    /** 数据来自旧算法折叠的持久账本行（日志已删/不可读，无法重算）；UI 据此标注置信度。 */
+    stale?: boolean;
 }
 /** 每轮费用明细行：仪表盘「每轮费用」图的数据源。 */
 export interface TurnUsageRow {
@@ -265,6 +287,8 @@ export declare const SESSION_ROW_LIMIT = 100;
 export declare const TURN_ROW_LIMIT = 200;
 /** 聚合文档的短 TTL（毫秒）：合并密集轮询，TTL 内直接复用上次的合并结果。 */
 export declare const AGGREGATE_TTL_MS = 5000;
+/** TTFT 尖峰阈值（毫秒）：超过计为一次尖峰样本，用于定位服务端抖动。 */
+export declare const PERF_SPIKE_MS = 10000;
 /** 单步性能样本（foldSession 的折叠产物；跨会话合并时按模型/小时再聚合）。 */
 export interface PerfSample {
     /** 计费目录键（模型；未收录模型原样保留）。 */
@@ -286,6 +310,10 @@ export interface SessionFold {
     byModel: Map<string, ModelUsage>;
     byDay: Map<string, ModelUsage>;
     byDayModels: Map<string, Map<string, ModelUsage>>;
+    /** 峰谷分桶：折叠时按调用时刻精确判档（tierAt），键 = 'peak' / 'offPeak'。 */
+    byTier: Map<string, ModelUsage>;
+    /** 工具调用次数（键 = 工具名；tool-call-delta 首见计数）。 */
+    byTool: Map<string, number>;
     /** 中转站归组：按 provider 路由归类到站点/直连/未知路由（key = {@link siteBucketKey}）。 */
     bySite: Map<string, ModelUsage>;
     /** 不可计价模型 id（未收录/无价，且非订阅）集合；跨会话合并后输出给面板提示。 */
@@ -318,6 +346,9 @@ export interface SerializedSessionFold {
     byModel: Record<string, ModelUsage>;
     byDay: Record<string, ModelUsage>;
     byDayModels: Record<string, Record<string, ModelUsage>>;
+    /** 1.0.8 起新增；旧账本行缺失（合并时按空处理，不触发重折算）。 */
+    byTier?: Record<string, ModelUsage>;
+    byTool?: Record<string, number>;
     bySite: Record<string, ModelUsage>;
     unpricedModels: string[];
     planCalls: Record<string, number>;
@@ -332,6 +363,11 @@ export interface UsageLedgerSession {
     cwd?: string;
     /** Stable log stamp (mtime + size) when the persistence backend exposes it. */
     stamp?: string;
+    /**
+     * 折叠该行时的算法版本（{@link FOLD_VERSION}）。缺失 = 1.0.6 及更早写入的
+     * 旧算法行（加载边界由迁移统一回填为 1）。
+     */
+    foldVersion?: number;
     fold: SerializedSessionFold;
 }
 /** On-disk durable usage ledger. Versioned independently from the dashboard document. */
@@ -342,10 +378,18 @@ export interface UsageLedgerDocument {
     /** 已应用的一次性配置迁移 id 列表（随文档落盘；缺省 = 尚未跑过任何迁移）。 */
     appliedMigrations?: string[];
 }
+/**
+ * 折叠算法版本：归账语义变化时递增。v1 = 按 request/header 归账（稀疏 header 把
+ * 两次 header 之间的用量串到上一个模型，订阅模型首当其冲，issue #14）；v2 =
+ * `assistant/message` 自带 source 归账（1.0.7 起）。持久账本行据此区分新旧算法：
+ * 日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
+ */
+export declare const FOLD_VERSION = 2;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并
  * bump {@link UsageLedgerDocument.version}；引擎保证幂等，重启不会重复执行。
+ * 可选字段的向后兼容回填（如 foldVersion）不 bump version：旧版本插件仍能读新文件。
  */
 export interface LedgerMigration {
     id: string;
@@ -353,8 +397,8 @@ export interface LedgerMigration {
     apply(document: UsageLedgerDocument): boolean;
 }
 /**
- * 账本迁移注册表。当前账本 schema（version 1）尚无字段变更需求，故为空表；
- * 机制已就绪，schema 变更时在此登记幂等迁移，见 {@link LedgerMigration}。
+ * 账本迁移注册表。首条迁移给 1.0.6 及更早的行回填 foldVersion = 1（它们全部出自
+ * header 归因算法）；此后新写入的行总带当前 {@link FOLD_VERSION}。
  */
 export declare const LEDGER_MIGRATIONS: readonly LedgerMigration[];
 /**
@@ -376,7 +420,9 @@ export interface UsageLedgerStore {
 export declare function messageTextLength(message: unknown): number;
 /**
  * Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
- * 其前置 request/header 记录的模型；同时提取最新会话标题、最后活跃时间，
+ * 其 `assistant/message` 自带 `message.source` 记录的模型（agent-loop 落盘时从
+ * 当次请求复制，每个调用一条，不依赖稀疏的 request/header）；source 缺失时
+ * 兜底到最近一次 request/header 的状态。同时提取最新会话标题、最后活跃时间，
  * 并按轮次折叠每轮费用明细（turn/start → turn/end；调用按 (turn) 归组）。
  * @param events - the session's persisted events in log order.
  * @param subscriptionProviders - provider ids billed through subscription plans.

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

@@ -16,6 +16,10 @@ export interface PerfModelData {
     ttftAvg: number;
     ttftP50: number;
     ttftP90: number;
+    /** 首字延时最大值（毫秒）；1.0.8 起新增，旧快照缺失。 */
+    ttftMax?: number;
+    /** 首字延时尖峰样本数（> 10s）；1.0.8 起新增，旧快照缺失。 */
+    ttftSpikes?: number;
     tpsAvg?: number;
     latencyAvg: number;
     estimatedSamples: number;

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

@@ -1,9 +1,10 @@
 /**
  * TokenPanel: 「Token」分区——把 token 从费用里独立出来洞察。
- * 三个板块 + 导出，全部由 `UsageStats` 的 byDay/byModel/total 派生，服务端零改动：
+ * 四个板块 + 导出，全部由 `UsageStats` 派生，服务端零改动：
  *  1. 每日 Token 堆叠趋势（未命中输入 / 缓存命中 / 输出[含 reasoning]），7/30 天切换；
  *  2. 模型 Token 总量排行 + 占比；
- *  3. Token 结构 KPI（缓存命中率 / reasoning 占比 / 输入:输出比 / 峰值日）。
+ *  3. Token 结构 KPI（缓存命中率 / reasoning 占比 / 输入:输出比 / 峰值日）+ 显式缓存写入；
+ *  4. 工具调用排行（byTool 计次；token 无法按工具归因）。
  */
 import type { UsageBillingKey } from './locales.ts';
 import type { UsageStats } from './UsageBilling.tsx';

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

@@ -75,18 +75,15 @@ export declare function projectMonthCost(byDay: Record<string, {
     cost: number;
 }>, monthPrefix: string, today: string): number;
 /**
- * 峰谷时段费用分摊：按每轮的起始时刻（北京时间高峰 9-12 / 14-18）把费用
- * 归入高峰 / 空闲两档。导出供测试：纯函数。
- * @param turns - 每轮费用行（需带 startedAt 与 cost）。
- * @returns 两档费用合计（人民币元）。
+ * 用户自定义单价显示重估：聚合发生在宿主进程（按内置目录计价），用户价只在
+ * 客户端显示层生效。对 byDayModels（day×model 完整二维）中命中用户价的模型
+ * 逐格平价重算 cost，并派生 byDay / byModel / total 的 cost。其余视图
+ * （bySite / byTier / bySession / byTurn）保持宿主原值——逐格时刻或行级归属
+ * 在客户端不可得，口径差异在设置面板注明。导出供测试：纯函数。
+ * @param stats - 服务端聚合文档。
+ * @returns 重估后的文档；无用户价或缺 byDayModels 时原样返回。
  */
-export declare function peakOffpeakCost(turns: readonly {
-    startedAt: number;
-    cost: number;
-}[]): {
-    peak: number;
-    offPeak: number;
-};
+export declare function recostWithUserPrices(stats: UsageStats): UsageStats;
 /** 近 7 天费用序列（含今天，缺日补 0）：触发卡 hover 速览的迷你柱数据源。
  * 导出供测试：纯函数（日期取本地时区）。 */
 export declare function activeDaysOf(byDay: Record<string, {
@@ -114,6 +111,8 @@ interface SessionBillingRow {
     id: string;
     title?: string;
     cwd?: string;
+    /** 数据来自旧算法折叠的持久账本行（原始日志已删，无法重算）。 */
+    stale?: boolean;
     calls: number;
     cost: number;
     lastActive: number;
@@ -139,6 +138,8 @@ export interface UsageStats {
         output: number;
         cacheHit: number;
         cacheMiss: number;
+        /** 显式缓存写入（cacheMiss 子集，部分厂商单独报告）；1.0.8 起新增，旧快照缺失。 */
+        cacheWrite?: number;
         cost: number;
         /** 输出中的 reasoning（思考）token；已含在 output 内。 */
         reasoning: number;
@@ -176,6 +177,22 @@ export interface UsageStats {
         cacheMiss: number;
         cost: number;
     }>>;
+    /**
+     * 峰谷分桶（全量逐调用真实判档）：1.0.8 起服务端按调用时刻精确归桶，
+     * 峰谷占比条优先用它（覆盖全部历史调用）；旧快照缺失时回退逐轮估算。
+     */
+    byTier?: {
+        peak: {
+            cost: number;
+            calls: number;
+        };
+        offPeak: {
+            cost: number;
+            calls: number;
+        };
+    };
+    /** 工具调用次数排行（键 = 工具名，按次数倒序）；旧快照缺失。 */
+    byTool?: Record<string, number>;
     /** 每轮费用明细（服务端聚合路径恒带）；旧快照可能缺失。 */
     byTurn?: readonly {
         sessionId: string;
@@ -218,6 +235,8 @@ export interface UsageStats {
     };
     /** 性能指标（TTFT/生成速度/总延迟）按模型与按小时；旧快照可能缺失。 */
     perf?: ClientPerf;
+    /** 旧版算法账本行兜底的会话数（模型归属可能失真）；0 或缺省 = 全部数据可信。 */
+    staleLedgerSessions?: number;
     /** 插件版本号（服务端读自包 package.json；旧快照缺失）。 */
     pluginVersion?: string;
 }

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.trendMetric' | 'billing.trendMetricCost' | 'billing.trendMetricTokens' | 'billing.trendEmpty' | 'billing.budget' | 'billing.budgetAmount' | 'billing.budgetSummary' | 'billing.sessions' | 'billing.sessionTitle' | '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.footer' | 'billing.footerCredit' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.promoBadge' | 'billing.promoUntil' | 'billing.promoOpenEnded' | 'billing.pricingTip' | 'billing.pricingUnit' | 'billing.pricingNotes' | 'billing.ubPeak' | 'billing.ubOff' | 'billing.peakBand' | 'billing.pricingSource' | 'billing.noteCache' | 'billing.noteBand' | 'billing.noteSource' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.reconcileDrift' | 'billing.reconcileDismiss' | '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.floatWindow' | 'billing.floatModeCombined' | 'billing.floatModeSubscription' | 'billing.floatMode' | 'billing.floatTargets' | 'billing.floatWindowHint' | 'billing.floatNoTargets' | 'billing.floatNoTargetsHint' | 'billing.cardDisplay' | 'billing.cardDisplayHint' | 'billing.cardMetric' | 'billing.cardMetricMoney' | 'billing.cardMetricTokens' | 'billing.triggerMonthTokens' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.subscriptionsStale' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.roundsHint' | 'billing.anomaly' | 'billing.workspaces' | 'billing.workspacesHint' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.thModel' | 'billing.thInputMiss' | 'billing.thInputHit' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | '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' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPos' | 'billing.peakAlertMode' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost' | 'billing.perfSamples' | 'billing.perfTtft' | 'billing.perfP50' | 'billing.perfP90' | 'billing.perfTps' | 'billing.perfLatency' | 'billing.perfEstimated' | 'billing.perfEmpty' | 'billing.perfTpsUnit' | 'billing.perfTitle' | 'billing.perfHint' | 'billing.heatmapYear' | 'billing.heatmapMonth' | 'billing.activeDays' | 'billing.streakDays' | 'billing.subscriptionAutoDetect' | 'billing.pluginInfo' | 'billing.pluginName' | 'billing.pluginDescription' | 'billing.pluginVersion' | 'billing.pluginAuthor' | 'billing.pluginRepository' | 'billing.pluginNpm' | 'billing.pluginLicense' | 'billing.tabToken' | 'billing.tokenExport' | 'billing.tokenExportCsv' | 'billing.tokenCacheHitRate' | 'billing.tokenReasoningShare' | 'billing.tokenReasoningShort' | 'billing.tokenIo' | 'billing.tokenPeak' | 'billing.tokenDaily' | 'billing.tokenByModel' | 'billing.tokenMiss' | 'billing.tokenHit' | 'billing.tokenOutput' | 'billing.tokenTotal' | 'billing.tokenShare' | 'billing.usageStatsTool' | 'billing.usageStatsToolHint' | 'billing.balanceGranted' | 'billing.balanceTopped' | 'billing.balanceDaily' | 'billing.balanceDaysLong' | 'billing.balanceDaysUnit' | 'billing.popTodayModel' | 'billing.popNoConsumption' | 'billing.popQuotaAlert' | 'billing.popRiskNone' | 'billing.popTitle' | 'billing.popDirectLead' | 'billing.popSubLead' | 'billing.popBalanceNormal' | 'billing.popBalanceLow' | 'billing.popQuotaNormal' | 'billing.popQuotaLow' | 'billing.alertBalanceLow' | 'billing.alertQuotaLow' | 'billing.unpricedHint' | 'billing.exportCsvSite' | 'billing.panelRelay' | 'billing.relaySite' | 'billing.relayDirect' | 'billing.relayUnknown' | 'billing.panelRelayQuota' | 'billing.relayBalance' | 'billing.relayNoQuota' | 'billing.relayWindowUsed' | 'billing.relayKindNewApi' | 'billing.relayKindSub2Api' | 'billing.relayKindUnknown' | 'billing.relayCalls';
+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.trendMetric' | 'billing.trendMetricCost' | 'billing.trendMetricTokens' | 'billing.trendEmpty' | 'billing.budget' | 'billing.budgetAmount' | 'billing.budgetSummary' | 'billing.sessions' | 'billing.sessionTitle' | '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.footer' | 'billing.footerCredit' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.promoBadge' | 'billing.promoUntil' | 'billing.promoOpenEnded' | 'billing.pricingTip' | 'billing.pricingUnit' | 'billing.pricingNotes' | 'billing.ubPeak' | 'billing.ubOff' | 'billing.ubStd' | 'billing.peakBand' | 'billing.pricingSource' | 'billing.noteCache' | 'billing.noteBand' | 'billing.noteSource' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.reconcileDrift' | 'billing.reconcileDismiss' | '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.floatWindow' | 'billing.floatModeCombined' | 'billing.floatModeSubscription' | 'billing.floatMode' | 'billing.floatTargets' | 'billing.floatWindowHint' | 'billing.floatNoTargets' | 'billing.floatNoTargetsHint' | 'billing.cardDisplay' | 'billing.cardDisplayHint' | 'billing.cardMetric' | 'billing.cardMetricMoney' | 'billing.cardMetricTokens' | 'billing.triggerMonthTokens' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.subscriptionsStale' | 'billing.staleLedgerNotice' | 'billing.tokenCacheWrite' | 'billing.toolRank' | 'billing.toolName' | 'billing.userPrices' | 'billing.userPricesHint' | 'billing.userPriceSave' | 'billing.sessionStaleBadge' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.roundsHint' | 'billing.anomaly' | 'billing.workspaces' | 'billing.workspacesHint' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.thModel' | 'billing.thInputMiss' | 'billing.thInputHit' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakSharePerCall' | 'billing.offPeakSavings' | 'billing.perfMax' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPos' | 'billing.peakAlertMode' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost' | 'billing.perfSamples' | 'billing.perfTtft' | 'billing.perfP50' | 'billing.perfP90' | 'billing.perfTps' | 'billing.perfLatency' | 'billing.perfEstimated' | 'billing.perfEmpty' | 'billing.perfTpsUnit' | 'billing.perfTitle' | 'billing.perfHint' | 'billing.heatmapYear' | 'billing.heatmapMonth' | 'billing.activeDays' | 'billing.streakDays' | 'billing.subscriptionAutoDetect' | 'billing.pluginInfo' | 'billing.pluginName' | 'billing.pluginDescription' | 'billing.pluginVersion' | 'billing.pluginAuthor' | 'billing.pluginRepository' | 'billing.pluginNpm' | 'billing.pluginLicense' | 'billing.tabToken' | 'billing.tokenExport' | 'billing.tokenExportCsv' | 'billing.tokenCacheHitRate' | 'billing.tokenReasoningShare' | 'billing.tokenReasoningShort' | 'billing.tokenIo' | 'billing.tokenPeak' | 'billing.tokenDaily' | 'billing.tokenByModel' | 'billing.tokenMiss' | 'billing.tokenHit' | 'billing.tokenOutput' | 'billing.tokenTotal' | 'billing.tokenShare' | 'billing.usageStatsTool' | 'billing.usageStatsToolHint' | 'billing.balanceGranted' | 'billing.balanceTopped' | 'billing.balanceDaily' | 'billing.balanceDaysLong' | 'billing.balanceDaysUnit' | 'billing.popTodayModel' | 'billing.popNoConsumption' | 'billing.popQuotaAlert' | 'billing.popRiskNone' | 'billing.popTitle' | 'billing.popDirectLead' | 'billing.popSubLead' | 'billing.popBalanceNormal' | 'billing.popBalanceLow' | 'billing.popQuotaNormal' | 'billing.popQuotaLow' | 'billing.alertBalanceLow' | 'billing.alertQuotaLow' | 'billing.unpricedHint' | 'billing.exportCsvSite' | 'billing.panelRelay' | 'billing.relaySite' | 'billing.relayDirect' | 'billing.relayUnknown' | 'billing.panelRelayQuota' | 'billing.relayBalance' | 'billing.relayNoQuota' | 'billing.relayWindowUsed' | 'billing.relayKindNewApi' | 'billing.relayKindSub2Api' | 'billing.relayKindUnknown' | 'billing.relayCalls';
 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

@@ -26,6 +26,32 @@ import type { LivePricing } from '../pricing-shared.ts';
  * live rate arrives the built-in value stays in force.
  */
 export declare const USD_TO_CNY = 6.79;
+/**
+ * 用户自定义单价（设置面板录入，localStorage 持久化）：覆盖内置/models.dev/
+ * dsh-spend 的全部价格来源，用于新模型上线目录未跟、或厂商未公布按量价的场景。
+ * 仅在客户端显示层生效——聚合发生在宿主进程，折叠时的成本仍按内置目录计算，
+ * 客户端检测到用户价后对受影响视图做显示重估（见 UsageBilling 的 recost）。
+ */
+export interface UserPrice {
+    /** 未命中输入单价（元或美元 / 每百万 token）。 */
+    input: number;
+    /** 缓存命中输入单价。 */
+    cacheHit: number;
+    /** 输出单价。 */
+    output: number;
+    /** 计价币种；缺省 CNY。 */
+    currency?: 'CNY' | 'USD';
+}
+/**
+ * 注入用户自定义单价。键 = 计费目录键；查询侧用归一化两跳宽松命中。
+ * 空对象 = 清除全部自定义价，回退内置目录。
+ * @param prices - 目录键 → 自定义单价。
+ */
+export declare function applyUserPrices(prices: Readonly<Record<string, UserPrice>>): void;
+/** 当前生效的用户自定义单价（设置面板回显用）；未设置时 undefined。 */
+export declare function getUserPrices(): Readonly<Record<string, UserPrice>> | undefined;
+/** 查一个计费键的用户自定义价（精确键 → 归一化键两跳）。 */
+export declare function userPriceOf(key: string): UserPrice | undefined;
 /**
  * Apply the node half's live pricing snapshot. Absent fields keep the
  * built-in catalog and rate; callers never fabricate values.
@@ -158,6 +184,13 @@ export interface PriceRow {
     /** 补充说明（如与标准价的关系）。 */
     note?: string;
 }
+/**
+ * 分档计价语义：厂商把「主档 / 低价档」的划分依据不同，界面需区分标注。
+ * - `timeOfDay`（缺省）：按调用时刻分档（DeepSeek 峰谷时段），档位是客观的；
+ * - `latency`：按用户选择的延迟档分档（Gemini Standard/Flex，Flex 半价换 1-15
+ *   分钟延迟），与时刻无关；逐调用无法从日志判定实际档位，成本按比例估算。
+ */
+export type TierSemantics = 'timeOfDay' | 'latency';
 /** One catalog entry: identity, brand color token, and price. */
 export interface ModelEntry {
     /** Model key used by `.dsh-usage-stats.json` `byModel`. */
@@ -172,6 +205,8 @@ export interface ModelEntry {
     price: ModelPrice;
     /** Peak-hour window label for time-of-day priced models. */
     peakHours?: string;
+    /** 分档语义；缺省 = 按时段（timeOfDay）。 */
+    tierSemantics?: TierSemantics;
     /**
      * 限时促销：生效期内 price 各档位按 factor 打折，过期自动恢复。
      * price 表本身永远保存刊例价，促销只在计价/显示出口处折算，不回写目录。
@@ -186,6 +221,8 @@ export interface ModelEntry {
     estimated?: boolean;
     /** 探活命中但无内置/models.dev 价：费率表标「未收录」，不参与计价。 */
     uncatalogued?: boolean;
+    /** 该条目当前按用户自定义单价计价（设置面板可维护）；费率表标注「自定义」。 */
+    userPriced?: boolean;
 }
 /**
  * Built-in catalog of current mainstream models as of 2026-08-16, priced from

package/lib/types/client/usage-billing-settings.d.ts

@@ -56,4 +56,23 @@ export declare const BILLING_CARD_STORAGE_KEY = "dsh.ui-usage-billing.card";
 export declare function loadBillingCardPrefs(): BillingCardPrefs;
 /** 写入计费卡偏好。失败静默（展示偏好非关键）。 */
 export declare function saveBillingCardPrefs(prefs: BillingCardPrefs): void;
+/** 用户自定义单价（与 client/pricing.ts 的 `UserPrice` 同形；此处不 import 以保持 node 半区无 client 依赖）。 */
+export interface StoredUserPrice {
+    /** 未命中输入单价（元或美元 / 每百万 token）。 */
+    input: number;
+    /** 缓存命中输入单价。 */
+    cacheHit: number;
+    /** 输出单价。 */
+    output: number;
+    /** 计价币种；缺省 CNY。 */
+    currency?: 'CNY' | 'USD';
+}
+/** 自定义价表：计费目录键 → 单价。 */
+export type UserPriceMap = Record<string, StoredUserPrice>;
+/** localStorage key（与其他 `dsh.ui-usage-billing.*` 偏好同命名空间）。 */
+export declare const USER_PRICES_STORAGE_KEY = "dsh.ui-usage-billing.prices";
+/** 读取用户自定义价（写入侧已校验，这里只挡住手工改坏的非数字行）。仅在浏览器半区调用。 */
+export declare function loadUserPrices(): UserPriceMap;
+/** 写入用户自定义价。失败静默（展示偏好非关键）。 */
+export declare function saveUserPrices(prices: UserPriceMap): void;
 //# sourceMappingURL=usage-billing-settings.d.ts.map