@kenz1117/dsh-ui-usage-billing 0.9.3 → 0.9.5

package/lib/index.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -27,11 +28,23 @@ import { credentialRef } from "@deepseek-ai/dsh-credentials";
 const PLAN_KNOWLEDGE = {
 	"opencode-go": {
 		type: "code",
-		subscriptionCny: 70
+		subscriptionCny: 70,
+		tier: {
+			amount: 10,
+			currency: "USD",
+			periodDays: 7,
+			label: "周额度 $30"
+		}
 	},
 	opencode: {
 		type: "code",
-		subscriptionCny: 70
+		subscriptionCny: 70,
+		tier: {
+			amount: 10,
+			currency: "USD",
+			periodDays: 7,
+			label: "周额度 $30"
+		}
 	},
 	"kimi-coding": {
 		type: "code",
@@ -993,6 +1006,12 @@ function dayStamp(time) {
 	const pad = (n) => String(n).padStart(2, "0");
 	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
 }
+/** Local-time hour stamp `YYYY-MM-DDTHH` — the performance series bucket key. */
+function hourStamp(time) {
+	const date = new Date(time);
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}`;
+}
 /** 工作区名：取 cwd 的末级目录名；无 cwd 时返回 {@link UNKNOWN_WORKSPACE_NAME}。 */
 function workspaceNameOf(cwd) {
 	if (cwd === void 0 || cwd === "") return "—";
@@ -1066,6 +1085,7 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 		byDayModels: /* @__PURE__ */ new Map(),
 		planCalls: /* @__PURE__ */ new Map(),
 		turns: [],
+		perf: [],
 		roles: {
 			userChars: 0,
 			toolChars: 0,
@@ -1078,6 +1098,8 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 	let subscription = false;
 	let official = false;
 	const turns = /* @__PURE__ */ new Map();
+	const steps = /* @__PURE__ */ new Map();
+	let lastOpenStepKey;
 	for (const event of events) {
 		fold.lastActive = Math.max(fold.lastActive, event.time);
 		if (event.type === "session/title") {
@@ -1104,11 +1126,39 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 			if (state !== void 0) state.endedAt = event.time;
 			continue;
 		}
+		if (event.type === "step/start") {
+			const turn = event.data.turn;
+			const step = event.data.step;
+			if (typeof turn === "number" && typeof step === "number") {
+				const stepKey = `${turn}:${step}`;
+				steps.set(stepKey, { startTime: event.time });
+				lastOpenStepKey = stepKey;
+			}
+			continue;
+		}
 		if (event.type === "request/header") {
 			const { model, provider } = event.data.header.config;
 			key = resolveCatalogKey(model);
 			subscription = subscriptionProviders.has(provider);
 			official = officialProviderIds === void 0 ? isOfficialProvider(provider) : officialProviderIds.has(provider);
+			if (lastOpenStepKey !== void 0) {
+				const stepState = steps.get(lastOpenStepKey);
+				if (stepState !== void 0 && stepState.requestTime === void 0) stepState.requestTime = event.time;
+			}
+			continue;
+		}
+		if (event.type === "assistant/chunk") {
+			const data = event.data;
+			const turn = data.turn;
+			const step = data.step;
+			const chunk = data.chunk;
+			if (typeof turn === "number" && typeof step === "number" && chunk !== void 0 && chunk.type !== "usage" && chunk.type !== "finish") {
+				const state = steps.get(`${turn}:${step}`);
+				if (state !== void 0) {
+					if (state.firstContentTime === void 0) state.firstContentTime = event.time;
+					state.lastContentTime = event.time;
+				}
+			}
 			continue;
 		}
 		if (event.type !== "assistant/message") continue;
@@ -1121,7 +1171,8 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time, official);
 		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time, official);
 		if (subscription) fold.planCalls.set(modelKey, (fold.planCalls.get(modelKey) ?? 0) + 1);
-		const state = turnState(turns, event.data.turn ?? -1);
+		const turn = event.data.turn ?? -1;
+		const state = turnState(turns, turn);
 		state.model = modelKey;
 		state.input += usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
 		state.output += usage.outputTokens;
@@ -1146,6 +1197,15 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 			fold.roles.inputCost += fullCost - outputCost;
 		}
 		if (state.startedAt === Number.MAX_SAFE_INTEGER) state.startedAt = event.time;
+		const stepNum = event.data.step;
+		if (typeof stepNum === "number") {
+			const perfState = steps.get(`${turn}:${stepNum}`);
+			if (perfState !== void 0) {
+				const sample = perfSampleOf(perfState, modelKey, usage.outputTokens ?? 0, event.time);
+				if (sample !== void 0) fold.perf.push(sample);
+				steps.delete(`${turn}:${stepNum}`);
+			}
+		}
 	}
 	fold.turns = [...turns.values()].filter((state) => state.input > 0 || state.output > 0).sort((a, b) => a.turn - b.turn).map((state) => ({
 		turn: state.turn,
@@ -1160,6 +1220,29 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 	}));
 	return fold;
 }
+/**
+* 生成一个 step 的性能样本；无效 / 超出 sane 上限（15 分钟）时返回 undefined，
+* 避免单条异常记录（时区错位 / 服务端抖动）拉偏均值。
+*/
+function perfSampleOf(state, model, outputTokens, endTime) {
+	const start = state.requestTime ?? state.startTime;
+	const first = state.firstContentTime;
+	const last = state.lastContentTime;
+	if (start === void 0 || first === void 0 || first < start) return void 0;
+	const ttftMs = first - start;
+	if (!Number.isFinite(ttftMs) || ttftMs < 0 || ttftMs > 9e5) return void 0;
+	const genMs = last !== void 0 && last > first ? last - first : void 0;
+	const latencyMs = endTime >= start ? endTime - start : void 0;
+	const tps = genMs !== void 0 && genMs > 0 && outputTokens > 0 ? outputTokens / (genMs / 1e3) : void 0;
+	return {
+		model,
+		hour: hourStamp(endTime),
+		ttftMs,
+		...tps === void 0 || !Number.isFinite(tps) || tps <= 0 ? {} : { tps },
+		estimated: state.requestTime === void 0,
+		...latencyMs === void 0 ? {} : { latencyMs }
+	};
+}
 /** Accumulate one ModelUsage into another (merge step of the incremental aggregator). */
 function mergeUsageInto(acc, cell) {
 	acc.calls += cell.calls;
@@ -1171,6 +1254,27 @@ function mergeUsageInto(acc, cell) {
 	acc.officialCalls += cell.officialCalls;
 	acc.officialCost += cell.officialCost;
 }
+/** 均值（数组非空时调用；空数组按 0 兜底）。 */
+function mean(values) {
+	if (values.length === 0) return 0;
+	return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+/** 分位数（0..1）：先拷贝排序，再线性插值；空数组返回 0。 */
+function percentile(values, p) {
+	if (values.length === 0) return 0;
+	const sorted = [...values].sort((a, b) => a - b);
+	const idx = (sorted.length - 1) * p;
+	const lo = Math.floor(idx);
+	const hi = Math.ceil(idx);
+	if (lo === hi) {
+		const value = sorted[lo];
+		return value === void 0 ? 0 : value;
+	}
+	const a = sorted[lo];
+	const b = sorted[hi];
+	if (a === void 0 || b === void 0) return 0;
+	return a + (b - a) * (idx - lo);
+}
 /**
 * Create the incremental usage aggregator.
 * @param persistence - the session persistence service.
@@ -1245,6 +1349,8 @@ function createUsageAggregator(persistence, options = {}) {
 			inputCost: 0,
 			outputCost: 0
 		};
+		const perfModel = /* @__PURE__ */ new Map();
+		const perfHour = /* @__PURE__ */ new Map();
 		for (const { meta, fold } of folds) {
 			const sessionId = String(meta.id);
 			mergeUsageInto(total, fold.total);
@@ -1256,6 +1362,32 @@ 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 [modelKey, count] of fold.planCalls) planCalls.set(modelKey, (planCalls.get(modelKey) ?? 0) + count);
+			for (const sample of fold.perf) {
+				let modelAccum = perfModel.get(sample.model);
+				if (modelAccum === void 0) {
+					modelAccum = {
+						ttfts: [],
+						tps: [],
+						latencies: [],
+						estimated: 0
+					};
+					perfModel.set(sample.model, modelAccum);
+				}
+				modelAccum.ttfts.push(sample.ttftMs);
+				if (sample.tps !== void 0) modelAccum.tps.push(sample.tps);
+				if (sample.latencyMs !== void 0) modelAccum.latencies.push(sample.latencyMs);
+				if (sample.estimated) modelAccum.estimated += 1;
+				let hourAccum = perfHour.get(sample.hour);
+				if (hourAccum === void 0) {
+					hourAccum = {
+						ttfts: [],
+						tps: []
+					};
+					perfHour.set(sample.hour, hourAccum);
+				}
+				hourAccum.ttfts.push(sample.ttftMs);
+				if (sample.tps !== void 0) hourAccum.tps.push(sample.tps);
+			}
 			for (const row of fold.turns) turnRows.push({
 				sessionId,
 				...row
@@ -1297,6 +1429,22 @@ function createUsageAggregator(persistence, options = {}) {
 			return record;
 		};
 		const toModelDayRecord = (map) => Object.fromEntries([...map].map(([day, models]) => [day, Object.fromEntries(models)]));
+		const perf = perfModel.size === 0 ? void 0 : {
+			byModel: Object.fromEntries([...perfModel].map(([model, acc]) => [model, {
+				samples: acc.ttfts.length,
+				ttftAvg: mean(acc.ttfts),
+				ttftP50: percentile(acc.ttfts, .5),
+				ttftP90: percentile(acc.ttfts, .9),
+				...acc.tps.length === 0 ? {} : { tpsAvg: mean(acc.tps) },
+				latencyAvg: acc.latencies.length === 0 ? 0 : mean(acc.latencies),
+				estimatedSamples: acc.estimated
+			}])),
+			byHour: Object.fromEntries([...perfHour].map(([hour, acc]) => [hour, {
+				samples: acc.ttfts.length,
+				ttftAvg: mean(acc.ttfts),
+				...acc.tps.length === 0 ? {} : { tpsAvg: mean(acc.tps) }
+			}]))
+		};
 		lastDoc = {
 			version: 3,
 			updatedAt: now,
@@ -1308,6 +1456,7 @@ function createUsageAggregator(persistence, options = {}) {
 			bySession: sessionRows.slice(0, 100),
 			byTurn: turnRows.slice(0, 200),
 			byWorkspace: workspaces.slice(0, 100),
+			...perf === void 0 ? {} : { perf },
 			byRole: (() => {
 				const chars = roles.userChars + roles.toolChars;
 				const userShare = chars > 0 ? roles.userChars / chars : .5;
@@ -1921,7 +2070,7 @@ const EMPTY_SUBSCRIPTION_KEYS = {
 /** 订阅类 provider 的显示名（未命中的回退为 id 本身）。 */
 const SUBSCRIPTION_DISPLAY_NAMES = {
 	"kimi-coding": "Kimi For Coding",
-	"zai-coding-cn": "Z.ai Coding Plan",
+	"zai-coding-cn": "Z.ai Coding Plan（国内）",
 	"zai-coding": "Z.ai Coding Plan",
 	"opencode": "OpenCode Plan",
 	"opencode-go": "OpenCode Go",
@@ -1941,7 +2090,7 @@ const SUBSCRIPTION_DISPLAY_NAMES = {
 	"openrouter": "OpenRouter"
 };
 /** 订阅类 provider id 判定：带 coding / agent-plan / token-plan 后缀，或已知订阅通道。 */
-const SUBSCRIPTION_ID_RE = /(?:^|-)(?:coding|agent[-_]?plan|token[-_]?plan)(?:$|-|_)|^(?:opencode|opencode-go|kimi-coding|zai-coding|minimax|minimax-token-plan|openrouter)/i;
+const SUBSCRIPTION_ID_RE = /* @__PURE__ */ new RegExp("(?:^|-)(?:coding|agent[-_]?plan|token[-_]?plan)(?:$|-|_)|^(?:opencode|opencode-go|kimi-coding|zai-coding|minimax|minimax-token-plan|openrouter)", "i");
 /** 是否是订阅类 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
 function isSubscriptionProviderId(providerId) {
 	if (SUBSCRIPTION_ID_RE.test(providerId)) return true;
@@ -2440,6 +2589,11 @@ const PRICING_REFRESH_INTERVAL_MS = 360 * 60 * 1e3;
 const SUBSCRIPTION_CACHE_MS = 300 * 1e3;
 /** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
 const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
+/**
+* 本插件版本号：从包自身的 package.json 读取（单一来源），随 usage-stats
+* 下发，供「设置 → 插件信息卡」展示。发布版 lib/index.js 相对包根解析。
+*/
+const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
 /** 统计快照的落盘节流（毫秒）：前端 30 秒轮询，快照最多每 30 秒写一次。 */
 const SNAPSHOT_INTERVAL_MS = 3e4;
 /** Required services: the web server, the persisted session log store, and user settings. */
@@ -2771,8 +2925,9 @@ function apply(ctx, config = {}) {
 					...config.monthlyBudget === void 0 ? {} : { budget: config.monthlyBudget },
 					...config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: config.lowBalanceThreshold }
 				};
-				const payload = Object.keys(injected).length === 0 ? stats : {
+				const payload = {
 					...stats,
+					pluginVersion: PACKAGE_VERSION,
 					...injected
 				};
 				persistSnapshot(payload);
@@ -2786,6 +2941,7 @@ function apply(ctx, config = {}) {
 				const doc = JSON.parse(text);
 				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));
 				return;
 			} catch {}

package/lib/types/aggregate.d.ts

@@ -65,6 +65,8 @@ export declare function emptyUsage(): ModelUsage;
 export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean, timeMs: number, official?: boolean): 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. */
+export declare function hourStamp(time: number): string;
 /** cwd 未知时工作区聚合的占位名（UI 显示 em dash，保持语言无关）。 */
 export declare const UNKNOWN_WORKSPACE_NAME = "\u2014";
 /** 工作区名：取 cwd 的末级目录名；无 cwd 时返回 {@link UNKNOWN_WORKSPACE_NAME}。 */
@@ -98,6 +100,13 @@ export interface UsageStatsDocument {
      * 属估算口径，UI 需标注）。旧快照可能缺失。
      */
     byRole?: RoleCost;
+    /**
+     * 性能指标（TTFT / 生成速度 / 总延迟）按模型与按小时聚合；旧快照可能缺失。
+     * 口径：TTFT = request/header → 首个内容 chunk；生成速度 = 输出 token ÷ 生成时长；
+     * 总延迟 = request/header → assistant/message。工具续写步骤无独立请求头，
+     * 以 step/start 为起点估算并计 estimated。
+     */
+    perf?: PerfStats;
 }
 /** 按角色费用归因：user / tool 为输入成本的启发式摊分，assistant 为输出成本实测。 */
 export interface RoleCost {
@@ -105,6 +114,40 @@ export interface RoleCost {
     assistant: number;
     tool: number;
 }
+/**
+ * 性能指标（TTFT / 生成速度 / 总延迟）：按模型与按小时聚合，供「性能」面板渲染。
+ * 旧快照（无 perf 字段）缺失时客户端按无数据兜底。
+ */
+export interface PerfStats {
+    /** 按模型聚合（键 = 计费目录键；未收录模型原样保留）。 */
+    byModel: Record<string, ModelPerf>;
+    /** 按小时聚合（键 = {@link hourStamp}，北京时间）。 */
+    byHour: Record<string, HourPerf>;
+}
+/** 一个模型的性能统计：首字延时均值 / P50 / P90、生成速度均值、总延迟均值。 */
+export interface ModelPerf {
+    /** 有效性能样本数（有可测 TTFT 的调用；不含损毁样本）。 */
+    samples: number;
+    /** 平均首字延时（毫秒）。 */
+    ttftAvg: number;
+    /** 首字延时 P50（毫秒）。 */
+    ttftP50: number;
+    /** 首字延时 P90（毫秒）。 */
+    ttftP90: number;
+    /** 平均生成速度（tokens/s）；生成了有效输出且时长可测时存在。 */
+    tpsAvg?: number;
+    /** 平均总延迟（首次请求 → 响应完成，毫秒）。 */
+    latencyAvg: number;
+    /** 以 step/start 估算的样本数（工具续写步骤无独立 request/header）。 */
+    estimatedSamples: number;
+}
+/** 一个小时的性能统计（键 = {@link hourStamp}）。 */
+export interface HourPerf {
+    samples: number;
+    ttftAvg: number;
+    /** 平均生成速度（tokens/s）；该小时无可测生成窗口时缺失。 */
+    tpsAvg?: number;
+}
 /** 会话明细行：仪表盘「会话明细」面板的数据源。 */
 export interface SessionUsageRow {
     /** 会话 id（字符串形式）。 */
@@ -156,6 +199,21 @@ export declare const SESSION_ROW_LIMIT = 100;
 export declare const TURN_ROW_LIMIT = 200;
 /** 聚合文档的短 TTL（毫秒）：合并密集轮询，TTL 内直接复用上次的合并结果。 */
 export declare const AGGREGATE_TTL_MS = 5000;
+/** 单步性能样本（foldSession 的折叠产物；跨会话合并时按模型/小时再聚合）。 */
+export interface PerfSample {
+    /** 计费目录键（模型；未收录模型原样保留）。 */
+    model: string;
+    /** 北京时间小时戳（{@link hourStamp}）——性能曲线的时间桶键。 */
+    hour: string;
+    /** 首字延时（毫秒）；无效样本（超出 sane 上限）不入样本集。 */
+    ttftMs: number;
+    /** 生成速度（tokens/s）；无有效生成窗口或无输出时缺失。 */
+    tps?: number;
+    /** 总延迟（首次请求 → 响应完成，毫秒）；只测到内容但完成时刻优先于起点时缺失。 */
+    latencyMs?: number;
+    /** 无独立 request/header，以 step/start 起算（工具续写步骤）。 */
+    estimated: boolean;
+}
 /** One persisted session's folded usage plus drill-down metadata. */
 interface SessionFold {
     total: ModelUsage;
@@ -166,6 +224,8 @@ interface SessionFold {
     planCalls: Map<string, number>;
     /** 每轮费用明细（按轮次号升序，不含 sessionId）；sessionId 在合并时补齐。 */
     turns: SessionTurnRow[];
+    /** 性能样本（有可测 TTFT 的调用，按事件次序折叠）。 */
+    perf: PerfSample[];
     /** 角色归因中间量：消息文本长度（user/tool）与输入/输出成本实测拆分。 */
     roles: RoleFold;
     /** 日志里最新的 session/title 文本（无标题事件时 undefined）。 */

package/lib/types/client/plan-knowledge.d.ts

@@ -15,11 +15,31 @@
  */
 /** Plan type: code = subscription + quota, token = per-token usage. */
 export type PlanType = 'code' | 'token';
+/**
+ * 订阅档位知识（自动识别的「档位月费 + 周期额度口径」）：供订阅卡片在
+ * 厂商官方未提供实时额度接口时展示参考口径。currency 为原生币种；费用与
+ * 额度按官方订阅周期（天/周/月）计量时，periodDays 表述该重置周期。
+ */
+export interface PlanTier {
+    /** 档位月费（原生币种值）。 */
+    amount: number;
+    currency: 'CNY' | 'USD';
+    /** 周期额度口径：每 periodDays 天重置的一个额度窗。 */
+    periodDays: number;
+    /** 周期请求额度（若有）。 */
+    requests?: number;
+    /** 周期 token 额度（若有）。 */
+    tokens?: number;
+    /** 额度口径的人话描述（官方未公布精确额度时）。 */
+    label?: string;
+}
 /** One plan row: provider id (after alias) → plan shape + optional subscription fee. */
 export interface PlanKnowledgeEntry {
     type: PlanType;
     /** 订阅月费（人民币元）；code 计划用，计入「本月预计」。 */
     subscriptionCny?: number;
+    /** 自动识别的档位月费与周期额度口径（订阅卡片展示）。 */
+    tier?: PlanTier;
 }
 /**
  * 订阅/计划 provider id → plan 知识（引用 dsh-spend 的 code/token 双口径）。
@@ -30,6 +50,8 @@ export declare const PLAN_KNOWLEDGE: Readonly<Record<string, PlanKnowledgeEntry>
 export declare function planTypeOf(providerId: string): PlanType;
 /** 订阅月费（人民币元）；非 code 或未配置时为 0。 */
 export declare function subscriptionCnyOf(providerId: string): number;
+/** 自动识别的档位月费与周期额度口径（订阅卡片展示）；无档位知识返回 undefined。 */
+export declare function tierInfoOf(providerId: string): PlanTier | undefined;
 export interface FallbackRate {
     /** 归一化模型 id（计费键，与 catalogEntries 的 key 同口径）。 */
     key: string;

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": "0.9.3",
+  "version": "0.9.5",
   "publishConfig": {
     "access": "public"
   },