@kenz1117/dsh-ui-usage-billing 1.7.1 → 1.7.3

package/lib/index.js

@@ -1225,6 +1225,30 @@ const BUILTIN_MODEL_CATALOG = [
 			output: 100
 		}
 	},
+	{
+		key: "kimi-k3.1-pro",
+		name: "Kimi K3.1 Pro",
+		provider: "月之暗面",
+		colorVar: "dsw-static-neutral-bluish-700",
+		price: {
+			currency: "CNY",
+			input: 13,
+			cacheHit: 1.3,
+			output: 68
+		}
+	},
+	{
+		key: "kimi-k3.1-pro-highspeed",
+		name: "Kimi K3.1 Pro Highspeed",
+		provider: "月之暗面",
+		colorVar: "dsw-static-neutral-bluish-600",
+		price: {
+			currency: "CNY",
+			input: 26,
+			cacheHit: 1.3,
+			output: 136
+		}
+	},
 	{
 		key: "mimo-v2.6-pro",
 		name: "MiMo V2.6 Pro",
@@ -3988,6 +4012,11 @@ const BUILTIN_MODEL_KEY_ALIASES = {
 	"seed-2.0-mini": "doubao-mini",
 	"k3": "kimi-k3",
 	"kimi-k3": "kimi-k3",
+	"kimi-k3.1-pro": "kimi-k3.1-pro",
+	"kimi-k3.1-pro-highspeed": "kimi-k3.1-pro-highspeed",
+	"k3.1-pro": "kimi-k3.1-pro",
+	"k3.1-pro-highspeed": "kimi-k3.1-pro-highspeed",
+	"k3-256k": "kimi-k3",
 	"kimi-k2.8-preview": "kimi-k2.8-preview",
 	"kimi-k2.8": "kimi-k2.8-preview",
 	"kimi-k2-8-preview": "kimi-k2.8-preview",
@@ -5159,7 +5188,8 @@ function createUsageAggregator(persistence, options = {}) {
 	const foldFingerprintOf = (registered, routes) => configFingerprint(subscriptionMatcher, officialProviderIds, routeAliases, searchEstimate, options.modelKeyAliases, registered, routeOriginsOf(routes));
 	let foldFingerprint = foldFingerprintOf(/* @__PURE__ */ new Set(), {});
 	const FOLD_CHUNK_EVENTS = 8e3;
-	const FOLD_YIELD_SESSIONS = 8;
+	const FOLD_SLICE_MS = 8;
+	const foldAllowedAt = Date.now() + Math.max(0, options.deferFoldMs ?? 0);
 	/** 惰性失效（价目表时序）：账本/缓存行若以「当时不可计价」的模型落盘，
 	*  而价目表现在能计价了，该行必须重折——否则显示层按实时价算出的
 	*  「目录价预估」与服务端 cost=0 并存，出现「明细比总额高」的双口径
@@ -5197,6 +5227,10 @@ function createUsageAggregator(persistence, options = {}) {
 				const document = stored;
 				if (runLedgerMigrations(document)) ledgerNeedsSave = true;
 				ledgerAppliedMigrations = document.appliedMigrations;
+				for (const refusal of document.refused ?? []) if (typeof refusal?.id === "string" && typeof refusal?.stamp === "string") unreadable.set(refusal.id, {
+					stamp: refusal.stamp,
+					format: refusal.format === true
+				});
 			}
 			for (const entry of ledgerSessionsOf(stored)) ledger.set(entry.id, entry);
 		} catch (error) {
@@ -5231,6 +5265,11 @@ function createUsageAggregator(persistence, options = {}) {
 				version: 1,
 				updatedAt: Date.now(),
 				sessions: [...ledger.values()],
+				...unreadable.size === 0 ? {} : { refused: [...unreadable].slice(0, 500).map(([id, mark]) => ({
+					id,
+					stamp: mark.stamp,
+					format: mark.format
+				})) },
 				...ledgerAppliedMigrations === void 0 ? {} : { appliedMigrations: ledgerAppliedMigrations }
 			});
 			ledgerNeedsSave = false;
@@ -5239,20 +5278,19 @@ function createUsageAggregator(persistence, options = {}) {
 			console.warn("[usage-billing] failed to persist durable usage ledger:", error);
 		}
 	};
-	const aggregateOnce = async () => {
+	/**
+	* 一轮聚合。mode='full' 走完整流程（list + 逐会话失效判定 + 折叠/复用）；
+	* mode='ledger-only' 只吃账本存档出轻文档（冷phase，issue #105）：不 list、
+	* 不读任何日志，doc 带 staleSnapshot=true 且**不进 TTL 缓存**（lastDoc 不动，
+	* 开门后的下一轮即完整折叠）——轻文档的每行折叠反序列化有 WeakMap 记忆，
+	* 重复构建只付 O(行数) 的汇总合并，冷phase里每个请求都可负担。
+	*/
+	const aggregateOnce = async (mode) => {
 		const now = Date.now();
 		await ensureLedgerLoaded();
 		const registeredProviders = options.resolveRegisteredProviders?.() ?? /* @__PURE__ */ new Set();
 		const roundRoutes = routesOf(registeredProviders);
 		foldFingerprint = foldFingerprintOf(registeredProviders, roundRoutes);
-		let metas;
-		try {
-			metas = await persistence.list();
-		} catch (error) {
-			if (options.ledger === void 0 || ledger.size === 0) throw error;
-			console.warn("[usage-billing] session list unavailable; serving durable usage ledger:", error);
-			metas = [];
-		}
 		const seen = /* @__PURE__ */ new Set();
 		const included = /* @__PURE__ */ new Set();
 		const folds = [];
@@ -5262,132 +5300,164 @@ function createUsageAggregator(persistence, options = {}) {
 		let formatUnreadable = 0;
 		let noLedgerUnreadable = 0;
 		let staleLedgerSessions = 0;
-		for (const [metaIndex, meta] of metas.entries()) {
-			if (metaIndex > 0 && metaIndex % FOLD_YIELD_SESSIONS === 0) await new Promise((resolve) => {
-				setImmediate(resolve);
-			});
-			const id = String(meta.id);
-			seen.add(id);
-			const stamp = await stampOf(meta);
-			const mark = unreadable.get(id);
-			if (stamp !== null && mark !== void 0 && mark.stamp === stamp) {
-				carriedUnreadable += 1;
-				if (mark.format) carriedFormatUnreadable += 1;
-				if (!ledger.has(id)) noLedgerUnreadable += 1;
-				continue;
-			}
+		if (mode === "full") {
+			let metas;
 			try {
-				const cwd = meta.cwd;
-				const subOf = subParentOf(meta);
-				const ledgerRow = ledger.get(id);
-				if (ledgerRow !== void 0 && ledgerRow.stamp !== void 0 && stamp !== null && ledgerRow.stamp === stamp && (ledgerRow.foldVersion ?? 1) === 23 && ledgerRow.fingerprint === foldFingerprint && !foldNeedsReprice(ledgerRow.fold)) {
-					const fold = deserializedFoldOf(ledgerRow.fold);
-					folds.push({
-						id,
-						...cwd === void 0 ? {} : { cwd },
-						...subOf === void 0 ? {} : { subOf },
-						fold
+				metas = await persistence.list();
+			} catch (error) {
+				if (options.ledger === void 0 || ledger.size === 0) throw error;
+				console.warn("[usage-billing] session list unavailable; serving durable usage ledger:", error);
+				metas = [];
+			}
+			let sliceAt = Date.now();
+			for (const meta of metas) {
+				if (Date.now() - sliceAt >= FOLD_SLICE_MS) {
+					await new Promise((resolve) => {
+						setImmediate(resolve);
 					});
-					included.add(id);
-					continue;
+					sliceAt = Date.now();
 				}
-				const hit = cache.get(id);
-				if (hit !== void 0 && stamp !== null && hit.stamp === stamp && hit.fingerprint === foldFingerprint && ![...hit.fold.unpricedModels].some((key) => isPriced(key))) {
-					cache.delete(id);
-					cache.set(id, hit);
-					folds.push({
-						id,
-						...meta.cwd === void 0 ? {} : { cwd: meta.cwd },
-						...subOf === void 0 ? {} : { subOf },
-						fold: hit.fold
-					});
-					included.add(id);
+				const id = String(meta.id);
+				seen.add(id);
+				const stamp = await stampOf(meta);
+				const mark = unreadable.get(id);
+				if (stamp !== null && mark !== void 0 && mark.stamp === stamp) {
+					carriedUnreadable += 1;
+					if (mark.format) carriedFormatUnreadable += 1;
+					if (!ledger.has(id)) noLedgerUnreadable += 1;
 					continue;
 				}
-				const previous = cache.get(id);
-				if (previous?.machine !== void 0 && previous.lastSeq !== void 0 && previous.fingerprint === foldFingerprint && ![...previous.fold.unpricedModels].some((key) => isPriced(key))) {
-					const from = previous.lastSeq + 1;
-					const { events, inheritedEventCount } = await persistence.readFrom(meta.id, sessionLogOffsetOf(from));
-					const after = await stampOf(meta);
-					if (stamp !== null && after !== stamp) {
+				try {
+					const cwd = meta.cwd;
+					const subOf = subParentOf(meta);
+					const ledgerRow = ledger.get(id);
+					if (ledgerRow !== void 0 && ledgerRow.stamp !== void 0 && stamp !== null && ledgerRow.stamp === stamp && (ledgerRow.foldVersion ?? 1) === 23 && ledgerRow.fingerprint === foldFingerprint && !foldNeedsReprice(ledgerRow.fold)) {
+						const fold = deserializedFoldOf(ledgerRow.fold);
+						folds.push({
+							id,
+							...cwd === void 0 ? {} : { cwd },
+							...subOf === void 0 ? {} : { subOf },
+							fold
+						});
+						included.add(id);
+						continue;
+					}
+					const hit = cache.get(id);
+					if (hit !== void 0 && stamp !== null && hit.stamp === stamp && hit.fingerprint === foldFingerprint && ![...hit.fold.unpricedModels].some((key) => isPriced(key))) {
 						cache.delete(id);
+						cache.set(id, hit);
+						folds.push({
+							id,
+							...meta.cwd === void 0 ? {} : { cwd: meta.cwd },
+							...subOf === void 0 ? {} : { subOf },
+							fold: hit.fold
+						});
+						included.add(id);
 						continue;
 					}
-					const first = events[0]?.seq;
-					if (events.length === 0 || first !== from) {
+					const previous = cache.get(id);
+					if (previous?.machine !== void 0 && previous.lastSeq !== void 0 && previous.fingerprint === foldFingerprint && ![...previous.fold.unpricedModels].some((key) => isPriced(key))) {
+						const from = previous.lastSeq + 1;
+						const { events, inheritedEventCount } = await persistence.readFrom(meta.id, sessionLogOffsetOf(from));
+						const after = await stampOf(meta);
+						if (stamp !== null && after !== stamp) {
+							cache.delete(id);
+							continue;
+						}
+						const first = events[0]?.seq;
+						if (events.length === 0 || first !== from) {
+							cache.delete(id);
+							continue;
+						}
+						foldInto(previous.fold, previous.machine, events, subscriptionMatcher, officialProviderIds, roundRoutes, searchEstimate, inheritedEventCount, routeAliases);
+						refreshTurns(previous.fold, previous.machine);
+						previous.lastSeq = events[events.length - 1]?.seq ?? previous.lastSeq;
+						previous.stamp = stamp;
 						cache.delete(id);
+						cache.set(id, previous);
+						folds.push({
+							id,
+							...cwd === void 0 ? {} : { cwd },
+							...subOf === void 0 ? {} : { subOf },
+							fold: previous.fold
+						});
+						included.add(id);
+						recordLedger(id, cwd, stamp, previous.fold, subOf);
 						continue;
 					}
-					foldInto(previous.fold, previous.machine, events, subscriptionMatcher, officialProviderIds, roundRoutes, searchEstimate, inheritedEventCount, routeAliases);
-					refreshTurns(previous.fold, previous.machine);
-					previous.lastSeq = events[events.length - 1]?.seq ?? previous.lastSeq;
-					previous.stamp = stamp;
-					cache.delete(id);
-					cache.set(id, previous);
+					const { events, inheritedEventCount } = await persistence.readFrom(meta.id, sessionLogOffsetOf(0));
+					const after = await stampOf(meta);
+					if (stamp !== null && after !== stamp) continue;
+					const fold = freshFold();
+					const machine = freshMachine();
+					for (let start = 0; start < events.length; start += FOLD_CHUNK_EVENTS) {
+						foldInto(fold, machine, events.slice(start, start + FOLD_CHUNK_EVENTS), subscriptionMatcher, officialProviderIds, roundRoutes, searchEstimate, inheritedEventCount, routeAliases);
+						if (start + FOLD_CHUNK_EVENTS < events.length && Date.now() - sliceAt >= FOLD_SLICE_MS) {
+							await new Promise((resolve) => {
+								setImmediate(resolve);
+							});
+							sliceAt = Date.now();
+						}
+					}
+					refreshTurns(fold, machine);
+					const last = events[events.length - 1];
+					cache.set(id, {
+						stamp,
+						fold,
+						machine,
+						...last !== void 0 && typeof last.seq === "number" ? { lastSeq: last.seq } : {},
+						fingerprint: foldFingerprint
+					});
 					folds.push({
 						id,
 						...cwd === void 0 ? {} : { cwd },
 						...subOf === void 0 ? {} : { subOf },
-						fold: previous.fold
+						fold
 					});
 					included.add(id);
-					recordLedger(id, cwd, stamp, previous.fold, subOf);
-					continue;
-				}
-				const { events, inheritedEventCount } = await persistence.readFrom(meta.id, sessionLogOffsetOf(0));
-				const after = await stampOf(meta);
-				if (stamp !== null && after !== stamp) continue;
-				const fold = freshFold();
-				const machine = freshMachine();
-				for (let start = 0; start < events.length; start += FOLD_CHUNK_EVENTS) {
-					foldInto(fold, machine, events.slice(start, start + FOLD_CHUNK_EVENTS), subscriptionMatcher, officialProviderIds, roundRoutes, searchEstimate, inheritedEventCount, routeAliases);
-					if (start + FOLD_CHUNK_EVENTS < events.length) await new Promise((resolve) => {
-						setImmediate(resolve);
-					});
-				}
-				refreshTurns(fold, machine);
-				const last = events[events.length - 1];
-				cache.set(id, {
-					stamp,
-					fold,
-					machine,
-					...last !== void 0 && typeof last.seq === "number" ? { lastSeq: last.seq } : {},
-					fingerprint: foldFingerprint
-				});
-				folds.push({
-					id,
-					...cwd === void 0 ? {} : { cwd },
-					...subOf === void 0 ? {} : { subOf },
-					fold
-				});
-				included.add(id);
-				recordLedger(id, cwd, stamp, fold, subOf);
-			} catch (error) {
-				skipped.push(id);
-				const format = isFormatUnsupportedError(error);
-				if (format) formatUnreadable += 1;
-				if (!ledger.has(id)) noLedgerUnreadable += 1;
-				if (stamp !== null) unreadable.set(id, {
-					stamp,
-					format
-				});
-				if (options.resolveSessionTitle !== void 0) {
-					const hint = options.resolveSessionTitle(meta);
-					if (hint !== void 0) titleHints.set(id, hint);
+					recordLedger(id, cwd, stamp, fold, subOf);
+				} catch (error) {
+					skipped.push(id);
+					const format = isFormatUnsupportedError(error);
+					if (format) formatUnreadable += 1;
+					if (!ledger.has(id)) noLedgerUnreadable += 1;
+					if (stamp !== null) {
+						unreadable.set(id, {
+							stamp,
+							format
+						});
+						ledgerNeedsSave = true;
+					}
+					if (options.resolveSessionTitle !== void 0) {
+						const hint = options.resolveSessionTitle(meta);
+						if (hint !== void 0) titleHints.set(id, hint);
+					}
+					console.warn("[usage-billing] skip unreadable session", id, error);
 				}
-				console.warn("[usage-billing] skip unreadable session", id, error);
+				if (included.has(id)) titleHints.delete(id);
 			}
-			if (included.has(id)) titleHints.delete(id);
 		}
-		for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
-		for (const key of [...unreadable.keys()]) if (!seen.has(key)) unreadable.delete(key);
-		while (cache.size > maxCacheSessions) {
-			const oldest = cache.keys().next();
-			if (oldest.done === true) break;
-			cache.delete(oldest.value);
+		if (mode === "full") {
+			for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
+			for (const key of [...unreadable.keys()]) if (!seen.has(key)) {
+				unreadable.delete(key);
+				ledgerNeedsSave = true;
+			}
+			while (cache.size > maxCacheSessions) {
+				const oldest = cache.keys().next();
+				if (oldest.done === true) break;
+				cache.delete(oldest.value);
+			}
 		}
 		if (options.ledger !== void 0) {
+			let fallbackSliceAt = Date.now();
 			for (const entry of ledger.values()) {
+				if (Date.now() - fallbackSliceAt >= FOLD_SLICE_MS) {
+					await new Promise((resolve) => {
+						setImmediate(resolve);
+					});
+					fallbackSliceAt = Date.now();
+				}
 				if (included.has(entry.id)) continue;
 				try {
 					const stale = (entry.foldVersion ?? 1) < 23 || entry.fingerprint !== foldFingerprint;
@@ -5565,7 +5635,7 @@ function createUsageAggregator(persistence, options = {}) {
 		};
 		const unreadableTotal = skipped.length + carriedUnreadable;
 		const formatUnreadableTotal = formatUnreadable + carriedFormatUnreadable;
-		lastDoc = {
+		const document = {
 			version: 4,
 			updatedAt: now,
 			source: "session-logs",
@@ -5599,15 +5669,21 @@ function createUsageAggregator(persistence, options = {}) {
 					assistant: roles.outputCost,
 					tool: roles.inputCost * (1 - userShare)
 				};
-			})()
+			})(),
+			...mode === "ledger-only" ? { staleSnapshot: true } : {}
 		};
-		lastAt = now;
-		return lastDoc;
+		if (mode === "full") {
+			lastDoc = document;
+			lastAt = now;
+		}
+		return document;
 	};
 	return {
 		aggregate() {
-			if (lastDoc !== void 0 && Date.now() - lastAt < 5e3) return Promise.resolve(lastDoc);
-			inflight ??= aggregateOnce().finally(() => {
+			const now = Date.now();
+			if (lastDoc !== void 0 && now - lastAt < 5e3) return Promise.resolve(lastDoc);
+			if (now < foldAllowedAt) return inflight ?? aggregateOnce("ledger-only");
+			inflight ??= aggregateOnce("full").finally(() => {
 				inflight = void 0;
 			});
 			return inflight;
@@ -9306,9 +9382,19 @@ const UsageBillingSettingsSchema = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z
 /** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
 /** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
 const PRICING_REFRESH_INTERVAL_MS = 216e5;
-/** 历史回放预热的延迟：等宿主启动高峰（插件加载 / 路由挂载）过去再全量折叠，
-*  避免抢启动期的 CPU；纯延迟不阻塞任何请求，面板提前打开也只会提前聚合。 */
-const WARMUP_DELAY_MS = 3e3;
+/** 启动后延迟全量折叠的默认时长（毫秒，issue #105）：冷phase内 /api/billing/*
+*  只出账本轻文档（不读日志），到点后预热定时器照常完整折叠——UI 一加载的
+*  轮询不再把全量折叠拉进启动关键路径。可用 config.replayDelayMs 覆盖；0 = 旧
+*  行为（随到随折）。20 秒的取值：小账本用户只损失十几秒新鲜度，重账本用户的
+*  启动高峰（插件加载/索引/首批会话写入）已经过去；配合聚合器的墙钟分片让出
+*  （FOLD_SLICE_MS），折叠真跑起来时单片阻塞也被压在 ~8ms。
+*/
+const DEFAULT_REPLAY_DELAY_MS = 2e4;
+/** 手写收窄（schemastery 不能当形状校验器，S-7）：非有限非负数字回落默认值。 */
+function readReplayDelayMs(value) {
+	if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
+	return DEFAULT_REPLAY_DELAY_MS;
+}
 /** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
 const SUBSCRIPTION_CACHE_MS = 3e5;
 const BALANCE_CACHE_MS = 3e5;
@@ -9792,6 +9878,7 @@ function apply(ctx, config = {}) {
 			swallowed("minimax-plan-classify-failed", error);
 		}
 	};
+	const replayDelayMs = readReplayDelayMs(config.replayDelayMs);
 	const aggregator = createUsageAggregator(adaptSessionPersistence(ctx.sessionPersistence), {
 		subscriptionMatcher: subscriptionRoutes,
 		...config.routeAliases === void 0 ? {} : { routeAliases: config.routeAliases },
@@ -9801,6 +9888,7 @@ function apply(ctx, config = {}) {
 		...workspaceTitleResolver === void 0 ? {} : { resolveWorkspaceTitle: workspaceTitleResolver },
 		...sessionTitleResolver === void 0 ? {} : { resolveSessionTitle: sessionTitleResolver },
 		...config.searchCallEstimateCny === void 0 ? {} : { searchCallEstimateCny: config.searchCallEstimateCny },
+		deferFoldMs: replayDelayMs,
 		ledger: ledgerStore
 	});
 	refreshMiniMaxPlanRoutes();
@@ -9814,7 +9902,7 @@ function apply(ctx, config = {}) {
 		}).catch((error) => {
 			console.warn("[usage-billing] historical replay warmup failed; will fold on first dashboard request:", error);
 		});
-	}, WARMUP_DELAY_MS);
+	}, replayDelayMs);
 	ctx.effect(() => () => {
 		clearTimeout(warmupTimer);
 	}, "usage-billing: historical replay warmup timer");

package/lib/types/aggregate.d.ts

@@ -179,6 +179,13 @@ export interface AggregateOptions {
     /** 联网搜索请求（`web/deepseek-search-llm-request`，无用量事件）的单次费用
      *  估算（人民币元）；默认 {@link DEFAULT_SEARCH_CALL_ESTIMATE_CNY}，设 0 关闭。 */
     searchCallEstimateCny?: number;
+    /**
+     * 启动冷phase时长（毫秒，自聚合器创建起算，issue #105）：期间 aggregate()
+     * 只出账本轻文档——不 list 会话、不读任何日志，文档带 `staleSnapshot: true`，
+     * UI 一加载的轮询不再把「全量折叠」拉进启动关键路径。到点后首个请求（或预热
+     * 定时器）照常完整折叠。0 / 缺省 = 不设闸（旧行为：随到随折）。
+     */
+    deferFoldMs?: number;
 }
 /** 每会话折叠缓存默认上限：超过则按 LRU 淘汰（P1-6 峰值内存治理）。 */
 export declare const DEFAULT_MAX_CACHE_SESSIONS = 400;
@@ -352,6 +359,12 @@ export interface UsageStatsDocument {
     unreadableFormatSessions?: number;
     /** 未统计中无任何账本存档、完全未计入的子集（区别于有存档按最近可用点计入的）；无存档缺失时省略。 */
     unreadableNoLedgerSessions?: number;
+    /**
+     * 冷phase轻文档标记（issue #105）：本档全部出自账本存档、未读任何会话日志
+     * （启动后 replayDelayMs 内的请求）。客户端复用既有「数据滞后」横幅呈现
+     * （issue #103 加的 staleSnapshot 通道，此前无生产方），零新增客户端体积。
+     */
+    staleSnapshot?: boolean;
 }
 /** 按角色费用归因：user / tool 为输入成本的启发式摊分，assistant 为输出成本实测。 */
 export interface RoleCost {
@@ -637,6 +650,19 @@ export interface UsageLedgerDocument {
     sessions: UsageLedgerSession[];
     /** 已应用的一次性配置迁移 id 列表（随文档落盘；缺省 = 尚未跑过任何迁移）。 */
     appliedMigrations?: string[];
+    /**
+     * 拒读会话负缓存（issue #105）：读失败（含格式拒读）会话的失败时 stamp。落盘
+     * 后重启不再重读——宿主对读不动的日志要解压解析到拒绝点才抛错，单条数百 ms、
+     * 老用户上百条时是每次启动的固定大头（负缓存此前只在内存，重启即失）。stamp
+     * 变化（日志被改写/追加）后照常失效重试；会话消失由 seen 清理兜底。
+     */
+    refused?: UsageLedgerRefusal[];
+}
+/** 账本里的一条拒读记录：会话 id + 失败时的失效键 + 是否格式拒读（计数细分用）。 */
+export interface UsageLedgerRefusal {
+    id: string;
+    stamp: string;
+    format: boolean;
 }
 /**
  * 多实例账本合并（自审计延期项：save 路径 last-writer-wins 丢写）：同一
@@ -666,6 +692,9 @@ export declare function mergeUsageLedgerDocuments(document: UsageLedgerDocument,
  * 持久账本行据此区分新旧算法：日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
  */
 export declare const FOLD_VERSION = 23;
+/** 账本里拒读记录的条数上限：防异常环境（大量损坏日志）把账本撑爆；
+ *  超限按 Map 插入序保留前 N 条（最早发现的先留，stamp 失效的自然被清理让位）。 */
+export declare const LEDGER_REFUSED_CAP = 500;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并

package/lib/types/client/domain/forecast.d.ts

@@ -10,8 +10,14 @@ export declare function dailyBurnRate(byDay: Record<string, {
     cost: number;
 }>, today: string): number;
 /**
- * 本月预计总花费：按本月已有记录的平均日消耗 × 本月天数外推；无本月记录时
- * 回退为最近 7 天日均 × 本月天数；无任何记录时返回 0（调用方不展示）。
+ * 本月预计总花费：**已发生 + 近 7 天节奏 × 本月剩余天数**。
+ *
+ * 口径变更（2026-10-23）：旧口径拿「本月有记录的天数」当分母求日均再乘整月天数，
+ * 稀疏使用的月份会被放大数倍——实测一个只有 4 天记录、其余 19 天没用的月份被外推
+ * 成实际值的 4 倍（¥3.4 → ¥15.0 的旧算法给 ¥572.9）。新口径只外推「还没发生的
+ * 那些天」，且节奏基准取近 7 个自然日（含空闲天）：近期没花钱就不虚增。
+ *
+ * 无本月记录时回退为最近 7 天（活跃天）日均 × 剩余天数；无任何记录时返回 0。
  * 导出供测试：纯函数，不依赖组件。
  * @param byDay - 按日费用表。
  * @param monthPrefix - 本月前缀（YYYY-MM）。

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

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'liveSessionSub' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'unknownChannelHint' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'cardDeltaBadge' | 'cardDeltaShow' | 'cardDeltaHide' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'balanceStaleNotice' | 'staleLedgerNotice' | 'staleSnapshotNotice' | 'unreadableNotice' | 'unreadableFormatNotice' | 'unreadableNoLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'sessionSubCost' | 'sessionSubCalls' | 'sessionSubRow' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'cellEstimateHint' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'densityLabel' | 'densityHint' | 'densityCompact' | 'densityDefault' | 'densityComfortable' | 'motionLabel' | 'motionHint' | 'motionOff' | 'motionSubtle' | 'motionRich' | 'settingsNavDisplayPref' | 'settingsNavBudget' | 'settingsNavAlert' | 'settingsNavDisplay' | 'settingsNavAdvanced' | 'settingsNavAbout' | 'settingsSearchPlaceholder' | 'settingsSearchEmpty' | 'sessionsViewAll' | 'sessionViewerSearch' | 'modelBudgetTitle' | 'modelBudgetHint' | 'modelBudgetBody' | 'modelBudgetPlaceholder' | 'moreWorksTitle' | 'adEngramName' | 'adEngramDesc' | 'adRainbowName' | 'adRainbowDesc' | 'kpiDescCacheHit' | 'kpiDescTokens' | 'kpiDescAvgCost' | 'kpiDescCalls' | 'kpiDescReasoning' | 'kpiDescIo' | 'kpiDescPeak' | 'healthDotLive' | 'healthDotFailed' | 'healthDotUnknown' | 'settingsSectionDisplay' | 'emptyHint' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption' | 'commandUsageLabel' | 'commandUsageDescription' | 'sessionOpen' | 'sessionOpenFailed' | 'sessionOpenUnavailable' | 'contextOccupancy' | 'contextWindow' | 'contextSystem' | 'contextTools' | 'contextMessages' | 'contextNoData' | 'tabContext' | 'tabAgents' | 'contextNextRequest' | 'contextLastRequest' | 'contextComposition' | 'contextCompositionHint' | 'agentsSummary' | 'agentsCount' | 'agentsDelegations' | 'agentsRoots' | 'agentsMostExpensive' | 'agentsChainTotal' | 'agentsNoData' | 'agentsSubagent' | 'agentsRoot';
+export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'monthProjectedHint' | 'liveTurn' | 'liveSession' | 'liveSessionSub' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'unknownChannelHint' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'cardDeltaBadge' | 'cardDeltaShow' | 'cardDeltaHide' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'balanceStaleNotice' | 'staleLedgerNotice' | 'staleSnapshotNotice' | 'unreadableNotice' | 'unreadableFormatNotice' | 'unreadableNoLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'sessionSubCost' | 'sessionSubCalls' | 'sessionSubRow' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'cellEstimateHint' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'densityLabel' | 'densityHint' | 'densityCompact' | 'densityDefault' | 'densityComfortable' | 'motionLabel' | 'motionHint' | 'motionOff' | 'motionSubtle' | 'motionRich' | 'settingsNavDisplayPref' | 'settingsNavBudget' | 'settingsNavAlert' | 'settingsNavDisplay' | 'settingsNavAdvanced' | 'settingsNavAbout' | 'settingsSearchPlaceholder' | 'settingsSearchEmpty' | 'sessionsViewAll' | 'sessionViewerSearch' | 'modelBudgetTitle' | 'modelBudgetHint' | 'modelBudgetBody' | 'modelBudgetPlaceholder' | 'moreWorksTitle' | 'adEngramName' | 'adEngramDesc' | 'adRainbowName' | 'adRainbowDesc' | 'kpiDescCacheHit' | 'kpiDescTokens' | 'kpiDescAvgCost' | 'kpiDescCalls' | 'kpiDescReasoning' | 'kpiDescIo' | 'kpiDescPeak' | 'healthDotLive' | 'healthDotFailed' | 'healthDotUnknown' | 'settingsSectionDisplay' | 'emptyHint' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption' | 'commandUsageLabel' | 'commandUsageDescription' | 'sessionOpen' | 'sessionOpenFailed' | 'sessionOpenUnavailable' | 'contextOccupancy' | 'contextWindow' | 'contextSystem' | 'contextTools' | 'contextMessages' | 'contextNoData' | 'tabContext' | 'tabAgents' | 'contextNextRequest' | 'contextLastRequest' | 'contextComposition' | 'contextCompositionHint' | 'agentsSummary' | 'agentsCount' | 'agentsDelegations' | 'agentsRoots' | 'agentsMostExpensive' | 'agentsChainTotal' | 'agentsNoData' | 'agentsSubagent' | 'agentsRoot';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/config.d.ts

@@ -96,5 +96,13 @@ export interface UsageBillingConfig {
      * 如 `{ "hy4-preview": "hunyuan" }`）。聚合折叠与客户端渲染共用同一映射。
      */
     modelKeyAliases?: Record<string, string>;
+    /**
+     * 启动后延迟全量折叠的时长（毫秒，issue #105）：聚合器创建起 `replayDelayMs`
+     * 之内，`/api/billing/*` 只出账本轻文档（不读任何会话日志，面板以「数据滞后」
+     * 横幅提示，复用 issue #103 的 staleSnapshot 通道），到点后预热定时器照常完整
+     * 折叠。默认 20 000（20 秒）；重账本用户（数千会话 / 数十 MB 日志）可调大到
+     * 180 000；0 = 旧行为（随到随折，首屏轮询即触发全量折叠）。
+     */
+    replayDelayMs?: number;
 }
 //# sourceMappingURL=config.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kenz1117/dsh-ui-usage-billing",
   "description": "Usage billing dashboard for DeepSeek Harness: sidebar cost metrics plus a full dashboard modal, priced from a current multi-provider catalog with real usage aggregated from session logs.",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "keywords": [
     "deepseek-harness",
     "deepseek",