@kidli1412/dsh-token-heatmap 0.1.5 → 0.1.6

package/README.md

@@ -49,7 +49,7 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 
 ## 工作原理 / How it works
 
-- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，增量折叠全部会话事件日志中的 token 用量样本（`assistant/chunk` 的 `usage` 与 `assistant/message` 的 `usage`；同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天），按天、按模型聚合，缓存到 `<DSH_HOME>/storages/token-heatmap-cache.json`，并通过回环受限端点 `GET /api/token-heatmap/usage` 提供；显示配置（开关 + 配色）由插件注册的 `token-heatmap` settings namespace 持有（settings.yaml），`GET/POST /api/token-heatmap/config` 作为回环兼容 API 读写同一 namespace，0.1.1 及更早的 `token-heatmap-config.json` 文档在启动时一次性迁移。
+- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，**实时折叠会话事件**（监听官方 `session/event`，每个 `assistant/chunk`/`assistant/message` 的 `usage` 事件即时写入缓存，不依赖 hero 屏挂载）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）；请求时 `collectUsage` 再做一次增量同步兜底，并枚举 **已归档（stored）会话**补齐历史——两种 `sessionPersistence` 接口都支持：0.1.2 线的 `listSnapshots()` + `readFrom()`，以及 0.1.3 起取代它们的 `list()` + `open()`/`handle.read()`。同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天；按天、按模型聚合，缓存到 `<DSH_HOME>/storages/token-heatmap-cache.json`。通过回环受限端点 `GET /api/token-heatmap/usage` 提供；显示配置（开关 + 配色）由插件注册的 `token-heatmap` settings namespace 持有（settings.yaml），`GET/POST /api/token-heatmap/config` 作为回环兼容 API 读写同一 namespace，0.1.1 及更早的 `token-heatmap-config.json` 文档在启动时一次性迁移。
 - **客户端**（`lib/client.js`）：手写 `__ModuleLoader__` bundle，注册进会话 `conversation.input.dock` 列表插槽，仅当 `session.composerPhase === "blank"`（新会话 hero 屏）且配置开关开启时渲染。框架真正的"卡片下方"插槽 `conversation.composer.dock` 在 hero 屏被 `!hero` 门控禁用，因此本插件利用 `input.dock` 容器（flex 列）的 CSS `order` 把自己排到输入卡片**之后**。配置卡注册进官方 `settings.plugin.item` 插槽（设置 → 插件 → 插件配置页签），经 settings scope 读写 `token-heatmap` namespace（该 namespace 由本插件在服务端注册，官方页签只渲染"Host 实际 serve 的 namespace ∩ 已注册 key"的卡片）。
 - 语义与 `dsh-token-meter` 的 `tokenUsage` 投影一致（参考插件 [dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats)，MIT）。
 
@@ -65,7 +65,8 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 - **Node**：`^22.19.0 || >=24.0.0`（与 DSH 一致）。
 - **宿主要求（dsh-market 显示）**：`engines.dsh: ^0.1.2-rc.1`，并将运行时依赖的 lockstep 宿主包声明为 `peerDependencies`（`dsh-host-webserver` / `dsh-session` / `dsh-session-persistence` / `dsh-settings` 与客户端模块 `dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`，均为 `^0.1.2-rc.1`）；插件市场会据此显示"宿主要求"并判断与当前 DSH 是否匹配。
 - **依赖**：`@deepseek-ai/dsh-settings` 自 0.1.3 起提升为 `^0.1.2-rc.1`、`@deepseek-ai/schemastery` 提升为 `^3.18.2`，与 DSH 0.1.2 版本线对齐。npm 的 prerelease 解析规则下 `^0.1.0-rc.7` 不会解析到 `0.1.2-rc.1`（只会装 `0.1.0-rc.8`），因此较低的范围会拉到与新版 DSH 不同 train 的 settings 副本。
-- **0.1.4（DSH 0.1.2 适配）**：rc.1 起 live session 不再携带 `.events` 数组（改用 `session.seq` + `session.eventAt(seq)`，与官方 `dsh-token-meter` 相同），新会话判断从 `composerPhase === "blank"` 改为布尔 `session.blank`；`sessionPersistence` 在 rc.1 不再提供会话枚举（list/listSnapshots 已移除），持久化历史的增量刷新降级为保留已有缓存、只累计 live 会话。客户端注入模块列表同步为新架构模块（见上）。
+- **0.1.4（DSH 0.1.2 适配）**：rc.1 起 live session 不再携带 `.events` 数组（改用 `session.seq` + `session.eventAt(seq)`，与官方 `dsh-token-meter` 相同），新会话判断从 `composerPhase === "blank"` 改为布尔 `session.blank`；`sessionPersistence` 的 stored 会话枚举在 0.1.3-alpha.2 被替换（`listSnapshots`/`readFrom` → `list()` + `open()`/`handle.read()`），两条接口见 0.1.6 条目。客户端注入模块列表同步为新架构模块（见上）。
+- **0.1.6（session/event 实时折叠 + stored 会话枚举修复）**：`apply()` 注册官方 `session/event` 监听器，每个 usage 事件即时折叠进缓存，解决 live 会话仅在 hero 屏挂载时才折叠而漏计同一日其他会话用量的问题（表现为当日总量偏小、历史天数丢失）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）。**stored 会话枚举修复**：0.1.3-alpha.2 起 `sessionPersistence` 移除了 `readFrom()` 与 `listSnapshots()`，只保留 `list()` + `open()`/`handle.read()`；旧实现只探测 `list`/`listSnapshots` 却无条件调用 `readFrom`，导致每个 stored 会话抛错并被吞成一条 warn —— 表现为热力图只剩进程内 live 的几天。现在两条接口都支持（`list()` 的 `revision` 同样用于跳过未变更的日志，增量仍按 `seq` 去重与连续性校验），stored 会话可完整补齐历史；两者都不可用时不再误判为"日志被截断"，而是保留已折叠天数并告警。token 口径与 `dsh-token-meter` 一致（input + output + cacheRead + cacheWrite，不含 reasoningTokens）。
 
 ## License
 

package/lib/index.js

@@ -291,7 +291,7 @@ async function saveCache(ctx, cache) {
 		await mkdir(dirname(path), { recursive: true });
 		const serialized = { version: CACHE_VERSION, sessions: {} };
 		for (const [id, state] of Object.entries(cache.sessions)) serialized.sessions[id] = serializeSession(state);
-		const tmp = `${path}.tmp`;
+		const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
 		await writeFile(tmp, JSON.stringify(serialized), "utf8");
 		await rename(tmp, path);
 	} catch (error) {
@@ -414,23 +414,58 @@ function liveSessionEvents(session, from) {
 	return { count: session.seq, events };
 }
 
+/**
+ * Read one stored session's events from `fromSeq` onward, across the two
+ * `sessionPersistence` generations this plugin declares compatibility with:
+ *
+ * - 0.1.0-rc.8 … 0.1.2-rc.1 expose `readFrom(id, fromSeq)`;
+ * - 0.1.3-alpha.2 and later dropped `readFrom`/`listSnapshots` in favour of
+ *   `open(id, "read")` + `handle.read()`, which returns the whole log — the
+ *   caller's `seq`-based delta filter makes the extra prefix harmless.
+ *
+ * @returns `{ events }` in seq order, or `null` when the backend offers
+ *   neither read path (callers must not treat that as an empty log).
+ */
+async function readSessionEvents(persistence, id, fromSeq) {
+	if (typeof persistence.readFrom === "function") {
+		const { events } = await persistence.readFrom(id, fromSeq);
+		return { events };
+	}
+	if (typeof persistence.open === "function") {
+		const handle = await persistence.open(id, "read");
+		try {
+			const { events } = await handle.read();
+			return { events };
+		} finally {
+			if (typeof handle.close === "function") await handle.close();
+		}
+	}
+	return null;
+}
+
 /**
  * Collect per-day usage across live and persisted sessions, incrementally.
  *
  * Live sessions: fold only the in-memory events added since the last fold.
- * Persisted sessions: skipped when the backend's opaque revision is
- * unchanged (`sessionPersistence.listSnapshots`, falling back to always
- * reading the delta); when the revision changes, the new events are verified
- * to be contiguous with the last folded seq — a gap or an empty delta means
- * the log was truncated/rewritten, so the session is refolded from scratch.
- * Sessions that vanished are dropped, and a session switching between
+ * Persisted sessions: enumerated through `sessionPersistence` and skipped when
+ * the backend's opaque revision is unchanged (`listSnapshots` on the 0.1.2
+ * train, `list()` on 0.1.3+); when the revision changes, the new events are
+ * verified to be contiguous with the last folded seq — a gap or an empty delta
+ * means the log was truncated/rewritten, so the session is refolded from
+ * scratch. Sessions that vanished are dropped, and a session switching between
  * live/persisted is refolded from scratch to stay exact.
- * On DSH 0.1.2+ (rc.1) sessionPersistence no longer exposes a session
- * enumeration (list/listSnapshots are gone), so persisted-only history is
- * kept in the cache untouched instead of being refreshed or dropped.
+ * A backend that offers neither `readFrom()` nor `open()` (the 0.1.2+ shape
+ * this plugin was first adapted to) cannot be read at all: its already-folded
+ * days are kept untouched and the session/event listener covers everything
+ * appended from now on.
  */
 export async function collectUsage(ctx) {
 	return withLock(async () => {
+		// Primary: incremental session-event fold. The session/event listener
+		// (see apply) folds live sessions in real time regardless of hero-screen
+		// mounting; this request-time fold is a sync point that catches anything
+		// the listener has not yet reached. Both share the per-session `consumed`
+		// cursor, so they never double count.
 		const cache = await loadCache();
 		const live = ctx.get("sessions");
 		const attached = new Set();
@@ -461,7 +496,8 @@ export async function collectUsage(ctx) {
 		);
 		if (canEnumeratePersisted) {
 			// Prefer the backend's opaque per-log revisions (no file I/O in the
-			// plugin, works for any backend that exposes listSnapshots).
+			// plugin): `listSnapshots` is the 0.1.2 spelling, `list()` returns
+			// the same snapshots on 0.1.3+.
 			let snapshots = null;
 			if (typeof persistence.listSnapshots === "function") {
 				try {
@@ -470,6 +506,7 @@ export async function collectUsage(ctx) {
 					ctx.logger.warn(`token-heatmap: listSnapshots failed, falling back to list(): ${String(error)}`);
 				}
 			}
+			if (snapshots === null && typeof persistence.list === "function") snapshots = await persistence.list();
 			const metas = snapshots !== null ? snapshots.map((entry) => entry.header) : await persistence.list();
 			const revisionOf = new Map();
 			if (snapshots !== null) for (const entry of snapshots) revisionOf.set(entry.header.id, entry.revision);
@@ -478,18 +515,31 @@ export async function collectUsage(ctx) {
 				if (attached.has(meta.id)) continue;
 				const state = cache.sessions[meta.id] ?? createUsageState();
 				const revision = revisionOf.get(meta.id);
-				const changed = state.kind !== "persisted" || (revision !== void 0 && revision !== state.revision) || revision === void 0;
+				// A revision-less backend must be read every pass; with revisions,
+				// an unchanged log is skipped entirely.
+				const changed = state.kind !== "persisted" || revision === void 0 || revision !== state.revision;
 				if (changed) {
 					try {
 						const wasPersisted = state.kind === "persisted";
 						const fromSeq = wasPersisted ? state.consumed : 0;
-						const { events } = await persistence.readFrom(meta.id, fromSeq);
+						const read = await readSessionEvents(persistence, meta.id, fromSeq);
+						if (read === null) {
+							// No read path on this backend: keep the folded days as they
+							// are rather than reporting an empty log as a rewrite.
+							ctx.logger.warn(`token-heatmap: sessionPersistence exposes neither readFrom() nor open() on this DSH; stored session "${meta.id}" cannot be read`);
+							cache.sessions[meta.id] = state;
+							continue;
+						}
+						const events = read.events;
 						if (!wasPersisted) {
 							state.days = new Map();
 							state.lastSample = null;
 							state.currentModel = null;
 							state.consumed = 0;
 						}
+						// `consumed` is the seq of the last folded event; both read paths
+						// yield events carrying their own seq, so the delta filter and the
+						// contiguity check below stay index-agnostic.
 						const fresh = wasPersisted ? events.filter((event) => event.seq > (state.consumed ?? 0)) : events;
 						const contiguous = fresh.length === 0 ? state.consumed === 0 : fresh[0].seq === state.consumed + 1;
 						if (!contiguous && state.consumed > 0) {
@@ -498,9 +548,8 @@ export async function collectUsage(ctx) {
 							state.lastSample = null;
 							state.currentModel = null;
 							state.consumed = 0;
-							const { events: allEvents } = await persistence.readFrom(meta.id, 0);
-							applyUsageDelta(state, allEvents);
-							state.consumed = allEvents.length > 0 ? allEvents[allEvents.length - 1].seq : 0;
+							applyUsageDelta(state, events);
+							state.consumed = events.length > 0 ? events[events.length - 1].seq : 0;
 						} else if (fresh.length > 0) {
 							applyUsageDelta(state, fresh);
 							state.consumed = fresh[fresh.length - 1].seq;
@@ -558,6 +607,70 @@ function apply(ctx) {
 	// Best-effort, fire-and-forget: import the pre-0.1.2 config document into
 	// the namespace and drop the file (see migrateLegacyConfig).
 	migrateLegacyConfig(ctx);
+	// Real-time fold: listen to session/event and fold each usage event into
+	// the cache immediately, so live session usage is captured regardless of
+	// whether the hero screen is mounted (the client polls the usage endpoint
+	// only there) and regardless of what sessionPersistence can enumerate —
+	// this is the path that keeps counting on a host whose stored logs are
+	// unreachable. The request-time fold in collectUsage stays as a sync point;
+	// both share the per-session `consumed` cursor so they never double count.
+	if (typeof ctx.on === "function") ctx.effect(() => {
+		let saveTimer = null;
+		let disposed = false;
+		const disposer = ctx.on("session/event", (session, event) => {
+			loadCache().then((cache) => {
+				if (disposed) return;
+				const state = cache.sessions[session.id] ?? createUsageState();
+				const seq = typeof event.seq === "number" ? event.seq : void 0;
+				if (seq !== void 0 && seq < (state.consumed ?? 0)) return;
+				applyUsageDelta(state, [event]);
+				if (seq !== void 0) state.consumed = Math.max(state.consumed ?? 0, seq + 1);
+				state.kind = "live";
+				cache.sessions[session.id] = state;
+				if (saveTimer === null) {
+					saveTimer = setTimeout(() => {
+						saveTimer = null;
+						saveCache(ctx, cache).catch(() => {});
+					}, 2000);
+				}
+			}).catch(() => {});
+		});
+		return () => {
+			disposed = true;
+			if (saveTimer !== null) clearTimeout(saveTimer);
+			if (typeof disposer === "function") disposer();
+		};
+	}, "token-heatmap: session/event fold");
+	// Initial fold of live sessions that existed before this plugin loaded
+	// (e.g. resumed sessions): fold their in-memory tail from the last cursor
+	// so the heatmap has history before the first session/event arrives.
+	ctx.effect(() => {
+		let disposed = false;
+		loadCache().then(async (cache) => {
+			if (disposed) return;
+			const sessions = typeof ctx.get === "function" ? ctx.get("sessions") : void 0;
+			if (sessions === void 0) return;
+			for (const session of sessions.list()) {
+				if (disposed) return;
+				const state = cache.sessions[session.id] ?? createUsageState();
+				if (state.kind !== "live") {
+					state.days = new Map();
+					state.lastSample = null;
+					state.currentModel = null;
+					state.consumed = 0;
+				}
+				const { count, events } = liveSessionEvents(session, state.consumed ?? 0);
+				if ((state.consumed ?? 0) < count) {
+					applyUsageDelta(state, events);
+					state.consumed = count;
+				}
+				state.kind = "live";
+				cache.sessions[session.id] = state;
+			}
+			if (!disposed) await saveCache(ctx, cache);
+		}).catch(() => {});
+		return () => { disposed = true; };
+	}, "token-heatmap: initial live fold");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: USAGE_PATH,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kidli1412/dsh-token-heatmap",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "DSH web plugin: GitHub-style daily token-usage heatmap on the new-session screen with a selectable calendar-year view, green/blue color schemes and a display switch (设置 → 插件 → 插件配置), plus today / this-month / all-time totals.",
   "type": "module",
   "main": "lib/index.js",