@kenz1117/dsh-ui-usage-billing 1.0.7 → 1.0.9

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",
@@ -1746,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), {
@@ -1758,6 +1761,28 @@ function foldUsage(acc, usage, key, subscription, timeMs, official = false) {
 		if (official) acc.officialCost += thisCost;
 	}
 }
+/**
+* 联网搜索辅助请求的单次费用估算默认值（人民币元）。DeepSeek 官方对搜索请求
+* （web_search 服务端工具注入上下文）照常计费，实测每次约 0.01~0.03 元，取中值；
+* 部署可在插件配置 `searchCallEstimateCny` 覆盖（设 0 关闭估算）。
+*/
+const DEFAULT_SEARCH_CALL_ESTIMATE_CNY = .02;
+/**
+* Fold one auxiliary web-search LLM request (issue #15) into an accumulator.
+* 这类调用绕过对话通道直连官方端点，日志只记请求（无响应/用量事件），token
+* 不可知：按「每次估值」计入费用并单独累计 `searchCalls`，不产生 token 维度。
+* @param acc - the accumulator to mutate.
+* @param estimateCny - per-call cost estimate in CNY; 0 disables the estimate.
+*/
+function foldSearchCall(acc, estimateCny) {
+	acc.calls += 1;
+	acc.searchCalls = (acc.searchCalls ?? 0) + 1;
+	acc.officialCalls += 1;
+	if (estimateCny > 0) {
+		acc.cost += estimateCny;
+		acc.officialCost += estimateCny;
+	}
+}
 /** Local-time date stamp (the host runs in the user's timezone). */
 function dayStamp(time) {
 	const date = new Date(time);
@@ -1797,6 +1822,8 @@ function workspaceNameOf(cwd) {
 	if (cwd === void 0 || cwd === "") return "—";
 	return cwd.split(/[\\/]/).filter(Boolean).at(-1) ?? "—";
 }
+/** TTFT 尖峰阈值（毫秒）：超过计为一次尖峰样本，用于定位服务端抖动。 */
+const PERF_SPIKE_MS = 1e4;
 /**
 * 账本迁移注册表。首条迁移给 1.0.6 及更早的行回填 foldVersion = 1（它们全部出自
 * header 归因算法）；此后新写入的行总带当前 {@link FOLD_VERSION}。
@@ -1839,6 +1866,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),
@@ -1855,6 +1884,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)),
@@ -1937,9 +1968,11 @@ function turnState(turns, turn) {
 * @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.
+* @param routes - 当前 provider 路由视图（中转站归组）。
+* @param searchCallEstimateCny - 联网搜索请求的单次费用估算（人民币元；0 关闭估算）。
 * @returns the per-session fold (cached by the incremental aggregator).
 */
-function foldSession(events, subscriptionProviders, officialProviderIds, routes = {}) {
+function foldSession(events, subscriptionProviders, officialProviderIds, routes = {}, searchCallEstimateCny = DEFAULT_SEARCH_CALL_ESTIMATE_CNY) {
 	let seedBoundary = -1;
 	for (const event of events) if (event.type === "session/end-seed" && typeof event.seq === "number" && Number.isFinite(event.seq)) seedBoundary = Math.max(seedBoundary, event.seq);
 	if (seedBoundary >= 0) {
@@ -1950,6 +1983,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(),
@@ -1970,6 +2005,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);
@@ -2019,6 +2055,21 @@ function foldSession(events, subscriptionProviders, officialProviderIds, routes
 			}
 			continue;
 		}
+		if (event.type === "web/deepseek-search-llm-request") {
+			const model = event.data.body?.model;
+			const modelKey = typeof model === "string" && model !== "" ? resolveCatalogKey(model) : "other";
+			const day = dayStamp(event.time);
+			foldSearchCall(fold.total, searchCallEstimateCny);
+			foldSearchCall(usageCell(fold.byModel, modelKey), searchCallEstimateCny);
+			foldSearchCall(usageCell(fold.byDay, day), searchCallEstimateCny);
+			foldSearchCall(modelDayCell(fold.byDayModels, day, modelKey), searchCallEstimateCny);
+			foldSearchCall(usageCell(fold.bySite, siteBucketKey({
+				kind: "direct",
+				provider: "deepseek"
+			})), searchCallEstimateCny);
+			foldSearchCall(usageCell(fold.byTier, tierAt(event.time)), searchCallEstimateCny);
+			continue;
+		}
 		if (event.type === "assistant/chunk") {
 			const data = event.data;
 			const turn = data.turn;
@@ -2031,6 +2082,16 @@ 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;
@@ -2051,6 +2112,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);
@@ -2132,9 +2194,11 @@ 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;
+	if (cell.searchCalls !== void 0) acc.searchCalls = (acc.searchCalls ?? 0) + cell.searchCalls;
 }
 /** 均值（数组非空时调用；空数组按 0 兜底）。 */
 function mean(values) {
@@ -2176,6 +2240,7 @@ function createUsageAggregator(persistence, options = {}) {
 	let lastAt = 0;
 	/** 每次聚合取最新的 provider 路由视图（中转站零配置发现）；缺省按空处理（全部未知路由）。 */
 	const routesOf = () => options.resolveRoutes?.() ?? {};
+	const searchEstimate = options.searchCallEstimateCny ?? .02;
 	const ensureLedgerLoaded = async () => {
 		if (ledgerLoaded || options.ledger === void 0) return;
 		ledgerLoaded = true;
@@ -2240,7 +2305,7 @@ function createUsageAggregator(persistence, options = {}) {
 				const { events } = await persistence.readFrom(meta.id, 0);
 				const after = await stampOf(meta);
 				if (stamp !== null && after !== stamp) continue;
-				const fold = foldSession(events, subscriptionProviders, officialProviderIds, routesOf());
+				const fold = foldSession(events, subscriptionProviders, officialProviderIds, routesOf(), searchEstimate);
 				cache.set(id, {
 					stamp,
 					fold
@@ -2256,7 +2321,7 @@ function createUsageAggregator(persistence, options = {}) {
 						id,
 						...meta.cwd === void 0 ? {} : { cwd: meta.cwd },
 						...stamp === null ? {} : { stamp },
-						foldVersion: 2,
+						foldVersion: 3,
 						fold: serializeFold(fold)
 					};
 					const previous = ledger.get(id);
@@ -2280,7 +2345,7 @@ function createUsageAggregator(persistence, options = {}) {
 			for (const entry of ledger.values()) {
 				if (included.has(entry.id)) continue;
 				try {
-					const stale = (entry.foldVersion ?? 1) < 2;
+					const stale = (entry.foldVersion ?? 1) < 3;
 					folds.push({
 						id: entry.id,
 						...entry.cwd === void 0 ? {} : { cwd: entry.cwd },
@@ -2310,6 +2375,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();
@@ -2334,6 +2401,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) {
@@ -2410,6 +2479,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
@@ -2432,8 +2503,14 @@ 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() },
+			...searchEstimate > 0 ? { searchCallEstimateCny: searchEstimate } : {},
 			...perf === void 0 ? {} : { perf },
 			...staleLedgerSessions > 0 ? { staleLedgerSessions } : {},
 			byRole: (() => {
@@ -4886,6 +4963,7 @@ function apply(ctx, config = {}) {
 		...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders },
 		resolveRoutes: () => readPiAiProviderRoutes(ctx.settings),
 		...workspaceTitleResolver === void 0 ? {} : { resolveWorkspaceTitle: workspaceTitleResolver },
+		...config.searchCallEstimateCny === void 0 ? {} : { searchCallEstimateCny: config.searchCallEstimateCny },
 		ledger: ledgerStore
 	});
 	const candidates = [

package/lib/types/aggregate.d.ts

@@ -74,6 +74,9 @@ export interface AggregateOptions {
     /** 独立的持久用量账本。启用后，已经成功折叠过的会话即使随后从
      *  sessionPersistence 中永久删除，也会继续计入累计用量。 */
     ledger?: UsageLedgerStore;
+    /** 联网搜索请求（`web/deepseek-search-llm-request`，无用量事件）的单次费用
+     *  估算（人民币元）；默认 {@link DEFAULT_SEARCH_CALL_ESTIMATE_CNY}，设 0 关闭。 */
+    searchCallEstimateCny?: number;
 }
 /** 每会话折叠缓存默认上限：超过则按 LRU 淘汰（P1-6 峰值内存治理）。 */
 export declare const DEFAULT_MAX_CACHE_SESSIONS = 400;
@@ -84,6 +87,11 @@ export interface ModelUsage {
     output: number;
     cacheHit: number;
     cacheMiss: number;
+    /**
+     * 显式缓存写入 token（部分厂商单独计价的 cache creation）——已包含在
+     * `cacheMiss` 内，单列供结构展示；旧快照缺失。
+     */
+    cacheWrite?: number;
     cost: number;
     /** 输出中的 reasoning（思考）token；已包含在 `output` 内，单列用于结构展示。 */
     reasoning: number;
@@ -93,6 +101,12 @@ export interface ModelUsage {
     officialCalls: number;
     /** 走官方渠道的费用（CNY）；三方费用 = cost - officialCost。 */
     officialCost: number;
+    /**
+     * 联网搜索辅助请求的估算调用数（`web/deepseek-search-llm-request`，日志只有
+     * 请求无用量事件）；已按每次 `searchCallEstimateCny` 估算计入 `cost`，不计
+     * token。旧快照缺失。
+     */
+    searchCalls?: number;
 }
 /** Zeroed usage accumulator. */
 export declare function emptyUsage(): ModelUsage;
@@ -108,6 +122,20 @@ export declare function emptyUsage(): ModelUsage;
  * @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, official?: boolean): void;
+/**
+ * 联网搜索辅助请求的单次费用估算默认值（人民币元）。DeepSeek 官方对搜索请求
+ * （web_search 服务端工具注入上下文）照常计费，实测每次约 0.01~0.03 元，取中值；
+ * 部署可在插件配置 `searchCallEstimateCny` 覆盖（设 0 关闭估算）。
+ */
+export declare const DEFAULT_SEARCH_CALL_ESTIMATE_CNY = 0.02;
+/**
+ * Fold one auxiliary web-search LLM request (issue #15) into an accumulator.
+ * 这类调用绕过对话通道直连官方端点，日志只记请求（无响应/用量事件），token
+ * 不可知：按「每次估值」计入费用并单独累计 `searchCalls`，不产生 token 维度。
+ * @param acc - the accumulator to mutate.
+ * @param estimateCny - per-call cost estimate in CNY; 0 disables the estimate.
+ */
+export declare function foldSearchCall(acc: ModelUsage, estimateCny: number): void;
 /** Local-time date stamp (the host runs in the user's timezone). */
 export declare function dayStamp(time: number): string;
 /** Local-time hour stamp `YYYY-MM-DDTHH` — the performance series bucket key. */
@@ -147,6 +175,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} 行；旧快照可能缺失。 */
@@ -167,6 +205,8 @@ export interface UsageStatsDocument {
     byRole?: RoleCost;
     /** 不可计价的模型 id（未收录 / 无价，费用按 0 计）；供面板提示用户自查与反馈。 */
     unpricedModels?: readonly string[];
+    /** 联网搜索请求的单次费用估算（人民币元，配置回显）；0 或缺省 = 未启用估算。 */
+    searchCallEstimateCny?: number;
     /**
      * 性能指标（TTFT / 生成速度 / 总延迟）按模型与按小时聚合；旧快照可能缺失。
      * 口径：TTFT = request/header → 首个内容 chunk；生成速度 = 输出 token ÷ 生成时长；
@@ -201,6 +241,10 @@ export interface ModelPerf {
     ttftP50: number;
     /** 首字延时 P90（毫秒）。 */
     ttftP90: number;
+    /** 首字延时最大值（毫秒）；定位偶发慢响应。 */
+    ttftMax: number;
+    /** 首字延时尖峰样本数（> 10s）；定位服务端抖动。 */
+    ttftSpikes: number;
     /** 平均生成速度（tokens/s）；生成了有效输出且时长可测时存在。 */
     tpsAvg?: number;
     /** 平均总延迟（首次请求 → 响应完成，毫秒）。 */
@@ -268,6 +312,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 {
     /** 计费目录键（模型；未收录模型原样保留）。 */
@@ -289,6 +335,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（未收录/无价，且非订阅）集合；跨会话合并后输出给面板提示。 */
@@ -321,6 +371,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>;
@@ -353,10 +406,11 @@ export interface UsageLedgerDocument {
 /**
  * 折叠算法版本：归账语义变化时递增。v1 = 按 request/header 归账（稀疏 header 把
  * 两次 header 之间的用量串到上一个模型，订阅模型首当其冲，issue #14）；v2 =
- * `assistant/message` 自带 source 归账（1.0.7 起）。持久账本行据此区分新旧算法：
- * 日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
+ * `assistant/message` 自带 source 归账（1.0.7 起）；v3 = 联网搜索请求按次估算
+ * 计费（issue #15，1.0.9 起）——旧行缺 `searchCalls` 维度与搜索估算费用。
+ * 持久账本行据此区分新旧算法：日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
  */
-export declare const FOLD_VERSION = 2;
+export declare const FOLD_VERSION = 3;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并
@@ -400,6 +454,8 @@ export declare function messageTextLength(message: unknown): number;
  * @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.
+ * @param routes - 当前 provider 路由视图（中转站归组）。
+ * @param searchCallEstimateCny - 联网搜索请求的单次费用估算（人民币元；0 关闭估算）。
  * @returns the per-session fold (cached by the incremental aggregator).
  */
 export declare function foldSession(events: readonly {
@@ -407,7 +463,7 @@ export declare function foldSession(events: readonly {
     time: number;
     data: never;
     seq?: number;
-}[], subscriptionProviders: ReadonlySet<string>, officialProviderIds?: ReadonlySet<string>, routes?: Readonly<Record<string, ProviderRouteView>>): SessionFold;
+}[], subscriptionProviders: ReadonlySet<string>, officialProviderIds?: ReadonlySet<string>, routes?: Readonly<Record<string, ProviderRouteView>>, searchCallEstimateCny?: number): SessionFold;
 /**
  * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——
  * 日志没动的会话直接复用，只有写过的会话重新折叠；整份文档另有短 TTL

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, {
@@ -141,9 +138,13 @@ export interface UsageStats {
         output: number;
         cacheHit: number;
         cacheMiss: number;
+        /** 显式缓存写入（cacheMiss 子集，部分厂商单独报告）；1.0.8 起新增，旧快照缺失。 */
+        cacheWrite?: number;
         cost: number;
         /** 输出中的 reasoning（思考）token；已含在 output 内。 */
         reasoning: number;
+        /** 联网搜索请求的估算调用数（已按次估值计入 cost）；1.0.9 起新增，旧快照缺失。 */
+        searchCalls?: number;
     };
     byModel: Record<string, {
         calls: number;
@@ -178,6 +179,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;
@@ -212,6 +229,8 @@ export interface UsageStats {
     }>;
     /** 不可计价模型 id（未收录/无价，费用按 0 计）；旧快照可能缺失。 */
     unpricedModels?: readonly string[];
+    /** 联网搜索请求的单次费用估算（人民币元，配置回显）；0 或缺省 = 未启用估算。 */
+    searchCallEstimateCny?: number;
     /** 按角色费用归因（估算口径：输出实测，输入按消息长度摊分）；旧快照可能缺失。 */
     byRole?: {
         user: number;

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.staleLedgerNotice' | '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.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.searchEstimateHint' | 'billing.siteListDisplay' | 'billing.siteListDisplayHint' | '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,39 @@ export declare const BILLING_CARD_STORAGE_KEY = "dsh.ui-usage-billing.card";
 export declare function loadBillingCardPrefs(): BillingCardPrefs;
 /** 写入计费卡偏好。失败静默（展示偏好非关键）。 */
 export declare function saveBillingCardPrefs(prefs: BillingCardPrefs): void;
+/**
+ * 中转站列表（中转站分布 / 中转站额度）的展示偏好（issue #17）。
+ * 纯 client 偏好，存 localStorage（不依赖 node 半区接口/设置 schema）。
+ */
+export interface SiteListPrefs {
+    /** 隐藏「未知路由」（bySite 的 unknown 桶）与「未识别」类型的中转站占位条目；默认隐藏。 */
+    hideUnidentified: boolean;
+}
+/** 默认站点列表偏好：隐藏无参考价值的占位条目，净化账单列表。 */
+export declare const DEFAULT_SITE_LIST_PREFS: SiteListPrefs;
+/** localStorage key（与其他 `dsh.ui-usage-billing.*` 偏好同命名空间）。 */
+export declare const SITE_LIST_STORAGE_KEY = "dsh.ui-usage-billing.sites";
+/** 读取站点列表偏好（含损坏/缺失回退到默认）。仅在浏览器半区调用。 */
+export declare function loadSiteListPrefs(): SiteListPrefs;
+/** 写入站点列表偏好。失败静默（展示偏好非关键）。 */
+export declare function saveSiteListPrefs(prefs: SiteListPrefs): 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