@kenz1117/dsh-ui-usage-billing 1.0.38 → 1.0.40

package/lib/index.js

@@ -2441,6 +2441,9 @@ function createUsageAggregator(persistence, options = {}) {
 	const ledger = /* @__PURE__ */ new Map();
 	let ledgerLoaded = false;
 	let ledgerNeedsSave = false;
+	let lastLedgerSaveAt = 0;
+	const unreadable = /* @__PURE__ */ new Map();
+	let inflight;
 	let ledgerAppliedMigrations;
 	let lastDoc;
 	let lastAt = 0;
@@ -2499,9 +2502,26 @@ function createUsageAggregator(persistence, options = {}) {
 			return null;
 		}
 	};
-	return { async aggregate() {
+	/** 落盘账本：force 无视节流（flush 用）；常规路径首次立即保存，之后按
+	*  LEDGER_SAVE_INTERVAL_MS 节流。失败仅告警——内存中的聚合值仍然正确。 */
+	const saveLedger = async (force) => {
+		if (options.ledger === void 0 || !ledgerNeedsSave) return;
+		if (!force && lastLedgerSaveAt !== 0 && Date.now() - lastLedgerSaveAt < 6e4) return;
+		try {
+			await options.ledger.save({
+				version: 1,
+				updatedAt: Date.now(),
+				sessions: [...ledger.values()],
+				...ledgerAppliedMigrations === void 0 ? {} : { appliedMigrations: ledgerAppliedMigrations }
+			});
+			ledgerNeedsSave = false;
+			lastLedgerSaveAt = Date.now();
+		} catch (error) {
+			console.warn("[usage-billing] failed to persist durable usage ledger:", error);
+		}
+	};
+	const aggregateOnce = async () => {
 		const now = Date.now();
-		if (lastDoc !== void 0 && now - lastAt < 5e3) return lastDoc;
 		await ensureLedgerLoaded();
 		let metas;
 		try {
@@ -2520,6 +2540,7 @@ function createUsageAggregator(persistence, options = {}) {
 			const id = String(meta.id);
 			seen.add(id);
 			const stamp = await stampOf(meta);
+			if (stamp !== null && unreadable.get(id) === stamp) continue;
 			const hit = cache.get(id);
 			if (hit !== void 0 && stamp !== null && hit.stamp === stamp) {
 				cache.delete(id);
@@ -2537,10 +2558,6 @@ function createUsageAggregator(persistence, options = {}) {
 				const ledgerRow = ledger.get(id);
 				if (ledgerRow !== void 0 && ledgerRow.stamp !== void 0 && stamp !== null && ledgerRow.stamp === stamp && (ledgerRow.foldVersion ?? 1) === 10 && ledgerRow.fingerprint === foldFingerprint) {
 					const fold = deserializeFold(ledgerRow.fold);
-					cache.set(id, {
-						stamp,
-						fold
-					});
 					folds.push({
 						id,
 						...cwd === void 0 ? {} : { cwd },
@@ -2606,10 +2623,12 @@ function createUsageAggregator(persistence, options = {}) {
 				recordLedger(id, cwd, stamp, fold);
 			} catch (error) {
 				skipped.push(id);
+				if (stamp !== null) unreadable.set(id, stamp);
 				console.warn("[usage-billing] skip unreadable session", id, error);
 			}
 		}
 		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;
@@ -2632,17 +2651,7 @@ function createUsageAggregator(persistence, options = {}) {
 					console.warn("[usage-billing] skip invalid durable ledger session", entry.id, error);
 				}
 			}
-			if (ledgerNeedsSave) try {
-				await options.ledger.save({
-					version: 1,
-					updatedAt: now,
-					sessions: [...ledger.values()],
-					...ledgerAppliedMigrations === void 0 ? {} : { appliedMigrations: ledgerAppliedMigrations }
-				});
-				ledgerNeedsSave = false;
-			} catch (error) {
-				console.warn("[usage-billing] failed to persist durable usage ledger:", error);
-			}
+			await saveLedger(false);
 		}
 		if (skipped.length > 0) console.warn(`[usage-billing] aggregated ${folds.length} sessions, skipped ${skipped.length} unreadable:`, skipped);
 		const total = emptyUsage();
@@ -2808,7 +2817,20 @@ function createUsageAggregator(persistence, options = {}) {
 		};
 		lastAt = now;
 		return lastDoc;
-	} };
+	};
+	return {
+		aggregate() {
+			if (lastDoc !== void 0 && Date.now() - lastAt < 5e3) return Promise.resolve(lastDoc);
+			inflight ??= aggregateOnce().finally(() => {
+				inflight = void 0;
+			});
+			return inflight;
+		},
+		async flush() {
+			if (inflight !== void 0) await inflight.catch(() => {});
+			await saveLedger(true);
+		}
+	};
 }
 //#endregion
 //#region lib/types/resilience.js
@@ -5290,11 +5312,14 @@ const ENABLE_USAGE_STATS_TOOL_FIELD = "enableUsageStatsTool";
 *
 * Serves `/api/billing/usage-stats`: real usage aggregated from every
 * persisted session log (see `aggregate.ts`) — the browser dashboard reads it
-* instead of showing an empty snapshot. When `sessionPersistence` is
-* unavailable (or aggregation fails), the configured `statsPath` /
-* `DSH_USAGE_STATS` / conventional JSON file is served as a fallback, and a
-* missing file answers `{ error }` so the dashboard shows zeros, never
-* fabricated samples.
+* instead of showing an empty snapshot. Aggregation is stale-while-revalidate:
+* requests get a short wait budget and fall back to the freshest persisted
+* snapshot while a slow full fold keeps running in the background (a heavy
+* user's first fold takes minutes and must not starve the single-process
+* host's RPC). When `sessionPersistence` is unavailable (or aggregation
+* fails), the configured `statsPath` / `DSH_USAGE_STATS` / conventional JSON
+* file is served as a fallback, and a missing file answers `{ error }` so the
+* dashboard shows zeros, never fabricated samples.
 */
 /** Peer 地址是否为回环（本地）。回环防护：本插件的端点只供本机浏览器用，
 *  局域网/远端请求一律拒绝，避免面板数据（含中转站 origin 与余额）外泄。 */
@@ -5368,6 +5393,10 @@ const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
 /** 统计快照的落盘节流（毫秒）：前端 30 秒轮询，快照最多每 30 秒写一次。 */
 const SNAPSHOT_INTERVAL_MS = 3e4;
+/** usage-stats 响应的等待预算（毫秒）：聚合在此预算内完成就回实时数据，
+*  超预算立即回最近快照（stale-while-revalidate），后台折叠继续跑。
+*  轻量用户暖缓存下的聚合是毫秒级，预算几乎不会触发。 */
+const RESPONSE_BUDGET_MS = 1500;
 /** 鉴权失败告警冷却（毫秒）：同一 provider 在窗口内只提示一次，避免 30 秒轮询刷屏。 */
 const AUTH_WARN_COOLDOWN_MS = 18e5;
 /**
@@ -5671,6 +5700,9 @@ function apply(ctx, config = {}) {
 		...config.searchCallEstimateCny === void 0 ? {} : { searchCallEstimateCny: config.searchCallEstimateCny },
 		ledger: ledgerStore
 	});
+	ctx.effect(() => () => {
+		aggregator.flush();
+	}, "usage-billing: ledger flush on dispose");
 	const candidates = [
 		config.statsPath,
 		process.env.DSH_USAGE_STATS,
@@ -6105,30 +6137,34 @@ function apply(ctx, config = {}) {
 		handler: async (req, res) => {
 			if (!guardLoopback(req, res)) return;
 			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			const decorate = (doc) => ({
+				...doc,
+				pluginVersion: PACKAGE_VERSION,
+				...config.monthlyBudget === void 0 ? {} : { budget: config.monthlyBudget },
+				...config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: config.lowBalanceThreshold }
+			});
+			const aggregating = aggregator.aggregate();
+			aggregating.then((stats) => {
+				persistSnapshot(decorate(stats));
+			}, () => {});
+			let fresh;
 			try {
-				const stats = await aggregator.aggregate();
-				const injected = {
-					...config.monthlyBudget === void 0 ? {} : { budget: config.monthlyBudget },
-					...config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: config.lowBalanceThreshold }
-				};
-				const payload = {
-					...stats,
-					pluginVersion: PACKAGE_VERSION,
-					...injected
-				};
-				persistSnapshot(payload);
-				res.end(JSON.stringify(payload));
-				return;
+				fresh = await Promise.race([aggregating.then((stats) => stats), new Promise((resolve) => {
+					setTimeout(() => {
+						resolve(void 0);
+					}, RESPONSE_BUDGET_MS).unref();
+				})]);
 			} catch (error) {
 				console.error("[usage-billing] usage-stats aggregate failed, falling back to snapshot:", error);
 			}
+			if (fresh !== void 0) {
+				res.end(JSON.stringify(decorate(fresh)));
+				return;
+			}
 			for (const candidate of candidates) {
 				const doc = await readSnapshot(candidate);
 				if (doc === null) continue;
-				if (config.monthlyBudget !== void 0) doc["budget"] = config.monthlyBudget;
-				if (config.lowBalanceThreshold !== void 0) doc["lowBalanceThreshold"] = config.lowBalanceThreshold;
-				doc["pluginVersion"] = PACKAGE_VERSION;
-				res.end(JSON.stringify(doc));
+				res.end(JSON.stringify(decorate(doc)));
 				return;
 			}
 			res.end(JSON.stringify({ error: "usage stats unavailable" }));

package/lib/types/aggregate.d.ts

@@ -358,6 +358,10 @@ export declare const SESSION_ROW_LIMIT = 100;
 export declare const TURN_ROW_LIMIT = 200;
 /** 聚合文档的短 TTL（毫秒）：合并密集轮询，TTL 内直接复用上次的合并结果。 */
 export declare const AGGREGATE_TTL_MS = 5000;
+/** 账本落盘节流间隔（毫秒）：保存是 O(会话数) 的全量序列化+原子重写，重度用户
+ *  上万会话时单次即秒级 CPU，每轮聚合都写会周期性白占宿主事件循环。首次保存
+ *  不受节流（冷启动全量折叠的成果要立即落盘），节流窗口内的改动由 flush 兜底。 */
+export declare const LEDGER_SAVE_INTERVAL_MS = 60000;
 /** TTFT 尖峰阈值（毫秒）：超过计为一次尖峰样本，用于定位服务端抖动。 */
 export declare const PERF_SPIKE_MS = 10000;
 /** 单步性能样本（foldSession 的折叠产物；跨会话合并时按模型/小时再聚合）。 */
@@ -535,11 +539,17 @@ export declare function foldSession(events: readonly {
 /**
  * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——
  * 日志没动的会话直接复用，只有写过的会话重新折叠；整份文档另有短 TTL
- * 合并密集轮询。缓存活在内存里（进程重启后首次全量折叠一次）。
+ * 合并密集轮询。带增量状态机的活跃会话由有界 LRU 承载（进程内有效）；
+ * 无状态机的账本行不占 LRU 名额，直接从 durable 账本反序列化复用，
+ * 进程重启后日志未动的会话零读取。
  */
 export interface UsageAggregator {
-    /** Aggregate current usage, reusing cached per-session folds when their logs are untouched. */
+    /** Aggregate current usage, reusing cached per-session folds when their logs are untouched.
+     *  并发调用共享同一次进行中的折叠（in-flight 去重），不会多倍全量重读。 */
     aggregate(): Promise<UsageStatsDocument>;
+    /** 立刻落盘未保存的账本改动（无视节流），供插件卸载时调用；
+     *  进行中的聚合先等完再存，折叠失败仍保存已成功部分。 */
+    flush(): Promise<void>;
 }
 /**
  * 聚合配置指纹：影响折叠语义的全部配置（订阅豁免、官方名单、路由别名、搜索估值）

package/lib/types/index.d.ts

@@ -3,11 +3,14 @@
  *
  * Serves `/api/billing/usage-stats`: real usage aggregated from every
  * persisted session log (see `aggregate.ts`) — the browser dashboard reads it
- * instead of showing an empty snapshot. When `sessionPersistence` is
- * unavailable (or aggregation fails), the configured `statsPath` /
- * `DSH_USAGE_STATS` / conventional JSON file is served as a fallback, and a
- * missing file answers `{ error }` so the dashboard shows zeros, never
- * fabricated samples.
+ * instead of showing an empty snapshot. Aggregation is stale-while-revalidate:
+ * requests get a short wait budget and fall back to the freshest persisted
+ * snapshot while a slow full fold keeps running in the background (a heavy
+ * user's first fold takes minutes and must not starve the single-process
+ * host's RPC). When `sessionPersistence` is unavailable (or aggregation
+ * fails), the configured `statsPath` / `DSH_USAGE_STATS` / conventional JSON
+ * file is served as a fallback, and a missing file answers `{ error }` so the
+ * dashboard shows zeros, never fabricated samples.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';

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.0.38",
+  "version": "1.0.40",
   "keywords": [
     "deepseek-harness",
     "deepseek",
@@ -129,6 +129,7 @@
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
+    "@types/react-dom": "^19.2.7",
     "jsdom": "^26.1.0",
     "lightningcss": "^1.32.0",
     "react": "^18.2.0",