@kidli1412/dsh-token-heatmap 0.1.0

package/lib/usage.js

@@ -0,0 +1,251 @@
+/**
+ * dsh-token-heatmap — pure per-day, per-model token-usage aggregation over
+ * session event logs. Kept free of cordis imports so it can be unit-tested
+ * and validated against real logs outside the running harness.
+ *
+ * Aggregation semantics mirror `dsh-token-meter`'s `tokenUsage` projection
+ * (and the reference plugin dsh-usage-stats, MIT © Ychris12138): a usage
+ * sample rides an `assistant/chunk` (`data.chunk.type === "usage"`) or an
+ * `assistant/message` (`data.usage`); a repeated sample for the same
+ * (turn, step) REPLACES the earlier value instead of double counting it, and
+ * the replacement is re-attributed to the day of the later event.
+ *
+ * Each sample is additionally attributed to the model that produced it:
+ * `assistant/message` carries `data.message.source.model`; usage chunks fall
+ * back to the last `request/header` `data.header.config.model`; samples with
+ * no model information land in the `unknown/unknown` bucket.
+ *
+ * @module dsh-token-heatmap/usage
+ */
+
+/** Local-calendar `YYYY-MM-DD` key for a millisecond epoch. */
+export function dayKey(timeMs) {
+	const date = new Date(timeMs);
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/** Empty token bucket. */
+export function zeroBuckets() {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0
+	};
+}
+
+/** Provider usage → buckets (missing cache fields are absent in some reports). */
+export function bucketsOf(usage) {
+	return {
+		inputTokens: usage.inputTokens ?? 0,
+		outputTokens: usage.outputTokens ?? 0,
+		cacheReadTokens: usage.cacheReadTokens ?? 0,
+		cacheWriteTokens: usage.cacheWriteTokens ?? 0
+	};
+}
+
+/** Total tokens across all buckets. */
+export function totalTokens(buckets) {
+	return buckets.inputTokens + buckets.outputTokens + buckets.cacheReadTokens + buckets.cacheWriteTokens;
+}
+
+/** Prompt-side cache hit rate in percent (0–100, one decimal), or null when no prompt tokens were reported. */
+export function cacheHitRate(buckets) {
+	const input = buckets.inputTokens ?? 0;
+	const cacheRead = buckets.cacheReadTokens ?? 0;
+	const cacheWrite = buckets.cacheWriteTokens ?? 0;
+	const promptTokens = input + cacheRead + cacheWrite;
+	if (promptTokens <= 0) return null;
+	return Math.round((cacheRead / promptTokens) * 1000) / 10;
+}
+
+function addInto(target, source) {
+	target.inputTokens += source.inputTokens;
+	target.outputTokens += source.outputTokens;
+	target.cacheReadTokens += source.cacheReadTokens;
+	target.cacheWriteTokens += source.cacheWriteTokens;
+	return target;
+}
+
+function subtractFrom(target, source) {
+	target.inputTokens -= source.inputTokens;
+	target.outputTokens -= source.outputTokens;
+	target.cacheReadTokens -= source.cacheReadTokens;
+	target.cacheWriteTokens -= source.cacheWriteTokens;
+	return target;
+}
+
+/** Extract the usage sample an event carries, if any. */
+function sampleOf(event) {
+	if (event.type === "assistant/chunk" && event.data?.chunk?.type === "usage") {
+		return {
+			key: `${event.data.turn}:${event.data.step}`,
+			usage: event.data.chunk.usage
+		};
+	}
+	if (event.type === "assistant/message" && event.data?.usage !== void 0) {
+		return {
+			key: `${event.data.turn}:${event.data.step}`,
+			usage: event.data.usage
+		};
+	}
+	return void 0;
+}
+
+/**
+ * The `provider/model` attribution key of a usage sample: the exact provider
+ * route plus the model id, so the SAME model served by different providers
+ * stays distinct. `assistant/message` names its provider via
+ * `data.message.source`; usage chunks fall back to the last `request/header`
+ * `data.header.config`; samples with no model information land in
+ * `unknown/unknown`.
+ */
+function modelOf(event) {
+	const source = event.data?.message?.source;
+	if (source !== void 0 && typeof source.model === "string") {
+		return `${typeof source.provider === "string" && source.provider.length > 0 ? source.provider : "unknown"}/${source.model}`;
+	}
+	const config = event.data?.header?.config;
+	if (config !== void 0 && typeof config.model === "string") {
+		return `${typeof config.provider === "string" && config.provider.length > 0 ? config.provider : "unknown"}/${config.model}`;
+	}
+	return void 0;
+}
+
+/** Day entry: totals plus a per-model bucket map. */
+function entryOf(byDay, day) {
+	let entry = byDay.get(day);
+	if (entry === void 0) {
+		entry = {
+			totals: zeroBuckets(),
+			models: new Map()
+		};
+		byDay.set(day, entry);
+	}
+	return entry;
+}
+
+/**
+ * One session's incremental fold state. `days` holds the already-folded
+ * per-day entries; `lastSample`/`currentModel` let a later event slice keep
+ * the replace-last-sample semantics and model attribution across fold
+ * boundaries without replaying the whole log.
+ */
+export function createUsageState() {
+	return {
+		days: new Map(),
+		lastSample: null,
+		currentModel: null,
+		consumed: 0
+	};
+}
+
+/**
+ * Fold a slice of NEW events onto an existing session state (mutating).
+ * Replacements for the same (turn, step) subtract the previous sample's
+ * buckets from the day/model bucket they were attributed to, so a slice
+ * starting mid-step (e.g. a usage chunk at the tail of the previous fold)
+ * stays exact.
+ * @param state - session fold state (mutated in place).
+ * @param events - the new events, in seq order, starting after the last fold.
+ */
+export function applyUsageDelta(state, events) {
+	let last = state.lastSample;
+	let currentModel = state.currentModel;
+	for (const event of events) {
+		if (event.type === "request/header") {
+			const model = modelOf(event);
+			if (model !== void 0) currentModel = model;
+		}
+		const sample = sampleOf(event);
+		if (sample === void 0) continue;
+		const buckets = bucketsOf(sample.usage);
+		const model = modelOf(event) ?? currentModel ?? "unknown/unknown";
+		const day = dayKey(event.time);
+		const entry = entryOf(state.days, day);
+		if (last !== null && last.key === sample.key) {
+			// Same turn/step re-reported: replace instead of double counting.
+			const previous = state.days.get(last.day);
+			if (previous !== void 0) {
+				subtractFrom(previous.totals, last.buckets);
+				const previousModel = previous.models.get(last.model);
+				if (previousModel !== void 0) subtractFrom(previousModel, last.buckets);
+			}
+		}
+		addInto(entry.totals, buckets);
+		let modelBucket = entry.models.get(model);
+		if (modelBucket === void 0) {
+			modelBucket = zeroBuckets();
+			entry.models.set(model, modelBucket);
+		}
+		addInto(modelBucket, buckets);
+		last = { key: sample.key, day, model, buckets };
+	}
+	state.lastSample = last;
+	state.currentModel = currentModel;
+}
+
+/**
+ * Fold one session's events into per-day, per-model token buckets.
+ * @param events - session event log in seq order.
+ * @returns Map<`YYYY-MM-DD`, { totals, models: Map<model, buckets> }> with
+ *   only days that saw usage.
+ */
+export function foldUsage(events) {
+	const state = createUsageState();
+	applyUsageDelta(state, events);
+	return state.days;
+}
+
+/**
+ * Merge one session's folded days into a global per-day map.
+ * @param byDay - global map to mutate.
+ * @param sessionDays - session day map (from foldUsage or a state).
+ */
+export function mergeInto(byDay, sessionDays) {
+	for (const [day, entry] of sessionDays) {
+		const target = entryOf(byDay, day);
+		addInto(target.totals, entry.totals);
+		for (const [model, buckets] of entry.models) {
+			let modelBucket = target.models.get(model);
+			if (modelBucket === void 0) {
+				modelBucket = zeroBuckets();
+				target.models.set(model, modelBucket);
+			}
+			addInto(modelBucket, buckets);
+		}
+	}
+}
+
+/**
+ * Render a global per-day map into the wire shape for the usage endpoint.
+ * @param byDay - day → entry map.
+ * @param updatedAt - computation timestamp.
+ * @returns `{ days, total, updatedAt }` with `days` sorted ascending; each
+ *   day carries `models` (descending by tokens) and a `cacheHitRate` percent.
+ */
+export function renderUsage(byDay, updatedAt) {
+	const days = [...byDay.entries()]
+		.map(([date, entry]) => {
+			const models = [...entry.models.entries()]
+				.map(([model, buckets]) => ({
+					model,
+					...buckets,
+					tokens: totalTokens(buckets),
+					cacheHitRate: cacheHitRate(buckets)
+				}))
+				.sort((a, b) => b.tokens - a.tokens);
+			return {
+				date,
+				...entry.totals,
+				tokens: totalTokens(entry.totals),
+				cacheHitRate: cacheHitRate(entry.totals),
+				models
+			};
+		})
+		.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+	const total = days.reduce((sum, day) => sum + day.tokens, 0);
+	return { days, total, updatedAt };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@kidli1412/dsh-token-heatmap",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "docs",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "scripts": {
+    "check": "node --check lib/usage.js && node --check lib/config.js && node --check lib/index.js && node --check lib/client.js",
+    "test": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KIDLi1412/dsh-token-heatmap.git"
+  },
+  "homepage": "https://github.com/KIDLi1412/dsh-token-heatmap#readme",
+  "bugs": {
+    "url": "https://github.com/KIDLi1412/dsh-token-heatmap/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "token",
+    "usage",
+    "heatmap"
+  ]
+}