@kenz1117/dsh-ui-usage-billing 0.4.2 → 0.6.0

package/lib/index.js

@@ -1,6 +1,8 @@
 import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 /** 当前汇率：实时覆盖优先，缺省回退内置固定值。 */
 function currentRate() {
@@ -272,7 +274,8 @@ const MODEL_CATALOG = [
 			input: 4,
 			cacheHit: .4,
 			output: 12
-		}
+		},
+		estimated: true
 	},
 	{
 		key: "minimax",
@@ -356,7 +359,8 @@ const MODEL_CATALOG = [
 			input: 5,
 			cacheHit: .5,
 			output: 10
-		}
+		},
+		estimated: true
 	},
 	{
 		key: "sensenova",
@@ -368,7 +372,8 @@ const MODEL_CATALOG = [
 			input: 4.5,
 			cacheHit: .45,
 			output: 9
-		}
+		},
+		estimated: true
 	},
 	{
 		key: "baichuan",
@@ -594,6 +599,28 @@ function computeCostAt(entry, buckets, timeMs, peakShare = DEFAULT_PEAK_SHARE) {
 	if (timeMs === null || timeMs === void 0 || !Number.isFinite(timeMs)) return computeCost(entry, buckets, peakShare);
 	return priceBandCost(tierAt(timeMs) === "peak" ? entry.price : entry.price.offPeak, buckets, entry.price.currency);
 }
+/**
+* Format an amount with adaptive precision and the given currency symbol.
+* @param amount - the amount (CNY by default; pass `usd` for dollar display).
+* @param currency - display currency; default `cny`.
+*/
+function formatMoney(amount, currency = "cny") {
+	const value = Number(amount);
+	if (!Number.isFinite(value)) return currency === "cny" ? "¥0" : "$0";
+	const symbol = currency === "cny" ? "¥" : "$";
+	if (value <= 0) return `${symbol}0`;
+	if (value >= 1e3) return `${symbol}${value.toFixed(0)}`;
+	if (value >= 10) return `${symbol}${value.toFixed(1)}`;
+	if (value >= .1) return `${symbol}${value.toFixed(2)}`;
+	return `${symbol}${value.toFixed(3)}`;
+}
+/** Format a large token count with B/M/K suffix. */
+function formatTokens(value) {
+	if (value >= 1e9) return `${(value / 1e9).toFixed(2)}B`;
+	if (value >= 1e6) return `${(value / 1e6).toFixed(1)}M`;
+	if (value >= 1e3) return `${(value / 1e3).toFixed(0)}K`;
+	return String(value);
+}
 //#endregion
 //#region lib/types/aggregate.js
 /**
@@ -672,6 +699,22 @@ function workspaceNameOf(cwd) {
 	if (cwd === void 0 || cwd === "") return "—";
 	return cwd.split(/[\\/]/).filter(Boolean).at(-1) ?? "—";
 }
+/**
+* 消息文本长度：user/tool 角色分摊输入成本的启发式依据。字符串内容取其
+* 长度；内容块数组累计文本块长度；其余形状按 0 计（durable 边界收窄）。
+*/
+function messageTextLength(message) {
+	if (message === null || typeof message !== "object") return 0;
+	const content = message.content;
+	if (typeof content === "string") return content.length;
+	if (!Array.isArray(content)) return 0;
+	let total = 0;
+	for (const block of content) {
+		const text = block?.text;
+		if (typeof text === "string") total += text.length;
+	}
+	return total;
+}
 /** Get-or-create one model cell inside a usage map (avoids non-null assertions). */
 function usageCell(map, key) {
 	const existing = map.get(key);
@@ -722,6 +765,12 @@ function foldSession(events, subscriptionProviders) {
 		byDayModels: /* @__PURE__ */ new Map(),
 		planCalls: /* @__PURE__ */ new Map(),
 		turns: [],
+		roles: {
+			userChars: 0,
+			toolChars: 0,
+			inputCost: 0,
+			outputCost: 0
+		},
 		lastActive: 0
 	};
 	let key = "other";
@@ -734,6 +783,14 @@ function foldSession(events, subscriptionProviders) {
 			if (typeof title === "string" && title.length > 0) fold.title = title;
 			continue;
 		}
+		if (event.type === "user/message") {
+			fold.roles.userChars += messageTextLength(event.data.message);
+			continue;
+		}
+		if (event.type === "tool/result") {
+			fold.roles.toolChars += messageTextLength(event.data.message);
+			continue;
+		}
 		if (event.type === "turn/start") {
 			const state = turnState(turns, event.data.turn ?? -1);
 			if (event.time < state.startedAt) state.startedAt = event.time;
@@ -767,12 +824,24 @@ function foldSession(events, subscriptionProviders) {
 		state.output += usage.outputTokens;
 		state.cacheHit += usage.cacheReadTokens ?? 0;
 		state.cacheMiss += usage.inputTokens + (usage.cacheWriteTokens ?? 0);
-		if (!subscription && MODEL_CATALOG.some((entry) => entry.key === modelKey)) state.cost += computeCostAt(modelOf(modelKey), {
-			input: (usage.cacheReadTokens ?? 0) + usage.inputTokens + (usage.cacheWriteTokens ?? 0),
-			cacheHit: usage.cacheReadTokens ?? 0,
-			cacheMiss: usage.inputTokens + (usage.cacheWriteTokens ?? 0),
-			output: usage.outputTokens
-		}, event.time);
+		if (!subscription && MODEL_CATALOG.some((entry) => entry.key === modelKey)) {
+			const buckets = {
+				input: (usage.cacheReadTokens ?? 0) + usage.inputTokens + (usage.cacheWriteTokens ?? 0),
+				cacheHit: usage.cacheReadTokens ?? 0,
+				cacheMiss: usage.inputTokens + (usage.cacheWriteTokens ?? 0),
+				output: usage.outputTokens
+			};
+			const fullCost = computeCostAt(modelOf(modelKey), buckets, event.time);
+			state.cost += fullCost;
+			const outputCost = computeCostAt(modelOf(modelKey), {
+				input: 0,
+				cacheHit: 0,
+				cacheMiss: 0,
+				output: usage.outputTokens
+			}, event.time);
+			fold.roles.outputCost += outputCost;
+			fold.roles.inputCost += fullCost - outputCost;
+		}
 		if (state.startedAt === Number.MAX_SAFE_INTEGER) state.startedAt = event.time;
 	}
 	fold.turns = [...turns.values()].filter((state) => state.input > 0 || state.output > 0).sort((a, b) => a.turn - b.turn).map((state) => ({
@@ -857,9 +926,19 @@ function createUsageAggregator(persistence, options = {}) {
 		const sessionRows = [];
 		const turnRows = [];
 		const workspaceMap = /* @__PURE__ */ new Map();
+		const roles = {
+			userChars: 0,
+			toolChars: 0,
+			inputCost: 0,
+			outputCost: 0
+		};
 		for (const { meta, fold } of folds) {
 			const sessionId = String(meta.id);
 			mergeUsageInto(total, fold.total);
+			roles.userChars += fold.roles.userChars;
+			roles.toolChars += fold.roles.toolChars;
+			roles.inputCost += fold.roles.inputCost;
+			roles.outputCost += fold.roles.outputCost;
 			for (const [modelKey, cell] of fold.byModel) mergeUsageInto(usageCell(byModel, modelKey), cell);
 			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);
@@ -915,7 +994,16 @@ function createUsageAggregator(persistence, options = {}) {
 			byDayModels: toModelDayRecord(byDayModels),
 			bySession: sessionRows.slice(0, 100),
 			byTurn: turnRows.slice(0, 200),
-			byWorkspace: workspaces.slice(0, 100)
+			byWorkspace: workspaces.slice(0, 100),
+			byRole: (() => {
+				const chars = roles.userChars + roles.toolChars;
+				const userShare = chars > 0 ? roles.userChars / chars : .5;
+				return {
+					user: roles.inputCost * userShare,
+					assistant: roles.outputCost,
+					tool: roles.inputCost * (1 - userShare)
+				};
+			})()
 		};
 		lastAt = now;
 		return lastDoc;
@@ -1673,6 +1761,8 @@ 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";
+/** 统计快照的落盘节流（毫秒）：前端 30 秒轮询，快照最多每 30 秒写一次。 */
+const SNAPSHOT_INTERVAL_MS = 3e4;
 /** Required services: the web server, the persisted session log store, and user settings. */
 const inject = [
 	"webServer",
@@ -1684,6 +1774,7 @@ const inject = [
 * 订阅 provider id（llm-pi-ai 设置键）→ billing 适配器 key 的映射。
 * 复用 dsh 既有的 llm-pi-ai provider 配置（apiKeyEnv 引用），不引入新配置面。
 */
+/** key 只取字符串凭据字段：zaiRegion 是区域枚举，由下方区域逻辑单独赋值。 */
 const SUBSCRIPTION_KEY_SOURCES = [
 	{
 		provider: "kimi-coding",
@@ -1755,12 +1846,156 @@ async function resolveSubscriptionKeys(settings, credentials) {
 function apply(ctx, config = {}) {
 	const aggregator = createUsageAggregator(ctx.sessionPersistence, { ...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders } });
 	const cwd = process.cwd();
+	const snapshotPath = join(homedir(), ".dsh/.dsh-usage-stats.json");
 	const candidates = [
 		config.statsPath,
 		process.env.DSH_USAGE_STATS,
 		join(cwd, ".dsh-usage-stats.json"),
-		join(homedir(), ".dsh/.dsh-usage-stats.json")
+		snapshotPath
 	].filter((path) => typeof path === "string" && path.length > 0);
+	let lastSnapshotAt = 0;
+	const persistSnapshot = (doc) => {
+		const now = Date.now();
+		if (now - lastSnapshotAt < SNAPSHOT_INTERVAL_MS) return;
+		lastSnapshotAt = now;
+		writeFileAtomic(snapshotPath, JSON.stringify({
+			...doc,
+			_writer: {
+				pid: process.pid,
+				at: now
+			}
+		}), {
+			mode: 384,
+			dirMode: 448
+		}).catch(() => {});
+	};
+	(async () => {
+		try {
+			const text = await readFile(snapshotPath, "utf8");
+			const writer = JSON.parse(text)._writer;
+			if (writer?.pid !== void 0 && writer.pid !== process.pid && writer.at !== void 0 && Date.now() - writer.at < 6e4) console.warn(`[usage-billing] 检测到另一实例（pid ${writer.pid}）正在提供用量统计，双实例可能导致提醒重复。`);
+		} catch {}
+	})();
+	ctx.inject(["tools"], (toolsCtx) => {
+		toolsCtx.tools.register(defineTool({
+			name: "usage_stats",
+			description: "查询本机 DeepSeek Harness 的模型用量与估算费用（人民币，按官方目录价估算，非账单）。range 取值：today=今天，month=本月，session=当前会话，all=累计。",
+			parameters: { range: {
+				type: "string",
+				enum: [
+					"today",
+					"month",
+					"session",
+					"all"
+				],
+				required: true,
+				description: "统计范围：today / month / session / all"
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						range: {
+							type: "string",
+							required: true
+						},
+						cost: {
+							type: "number",
+							required: true,
+							description: "估算费用（人民币元）"
+						},
+						calls: {
+							type: "number",
+							required: true
+						},
+						input: {
+							type: "number",
+							required: true,
+							description: "输入 tokens"
+						},
+						output: {
+							type: "number",
+							required: true,
+							description: "输出 tokens"
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `用量（${value.range}）：估算费用 ${formatMoney(value.cost)}，调用 ${value.calls} 次，输入 ${formatTokens(value.input)} tokens，输出 ${formatTokens(value.output)} tokens`
+				}]
+			},
+			async execute(args, exec) {
+				const stats = await aggregator.aggregate();
+				const zero = {
+					range: args.range,
+					cost: 0,
+					calls: 0,
+					input: 0,
+					output: 0
+				};
+				if (args.range === "all") return {
+					range: args.range,
+					cost: stats.total.cost,
+					calls: stats.total.calls,
+					input: stats.total.input,
+					output: stats.total.output
+				};
+				if (args.range === "today") {
+					const day = stats.byDay[dayStamp(Date.now())];
+					return day === void 0 ? zero : {
+						range: args.range,
+						cost: day.cost,
+						calls: day.calls,
+						input: day.input,
+						output: day.output
+					};
+				}
+				if (args.range === "month") {
+					const prefix = dayStamp(Date.now()).slice(0, 7);
+					let cost = 0;
+					let calls = 0;
+					let input = 0;
+					let output = 0;
+					for (const [date, day] of Object.entries(stats.byDay)) {
+						if (!date.startsWith(prefix)) continue;
+						cost += day.cost;
+						calls += day.calls;
+						input += day.input;
+						output += day.output;
+					}
+					return {
+						range: args.range,
+						cost,
+						calls,
+						input,
+						output
+					};
+				}
+				const sessionId = exec.agent?.id;
+				if (sessionId === void 0) throw new Error("usage_stats 的 session 范围需要 agent 会话上下文");
+				let cost = 0;
+				let calls = 0;
+				let input = 0;
+				let output = 0;
+				for (const turn of stats.byTurn ?? []) {
+					if (turn.sessionId !== String(sessionId)) continue;
+					cost += turn.cost;
+					calls += 1;
+					input += turn.input;
+					output += turn.output;
+				}
+				return {
+					range: args.range,
+					cost,
+					calls,
+					input,
+					output
+				};
+			}
+		}));
+	});
 	let live = { source: "builtin" };
 	const refreshPricing = async () => {
 		live = await fetchLivePricing();
@@ -1834,10 +2069,12 @@ function apply(ctx, config = {}) {
 					...config.monthlyBudget === void 0 ? {} : { budget: config.monthlyBudget },
 					...config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: config.lowBalanceThreshold }
 				};
-				res.end(JSON.stringify(Object.keys(injected).length === 0 ? stats : {
+				const payload = Object.keys(injected).length === 0 ? stats : {
 					...stats,
 					...injected
-				}));
+				};
+				persistSnapshot(payload);
+				res.end(JSON.stringify(payload));
 				return;
 			} catch {}
 			for (const candidate of candidates) try {

package/lib/types/aggregate.d.ts

@@ -79,6 +79,18 @@ export interface UsageStatsDocument {
     byTurn?: TurnUsageRow[];
     /** 工作区聚合：按 cwd 末级目录归并，按费用倒序；旧快照可能缺失。 */
     byWorkspace?: WorkspaceUsageRow[];
+    /**
+     * 按角色费用归因（人民币元）：助手输出成本为实测计价；输入成本按会话内
+     * 用户消息 / 工具结果的文本长度占比启发式摊分（日志无角色级 token 实测，
+     * 属估算口径，UI 需标注）。旧快照可能缺失。
+     */
+    byRole?: RoleCost;
+}
+/** 按角色费用归因：user / tool 为输入成本的启发式摊分，assistant 为输出成本实测。 */
+export interface RoleCost {
+    user: number;
+    assistant: number;
+    tool: number;
 }
 /** 会话明细行：仪表盘「会话明细」面板的数据源。 */
 export interface SessionUsageRow {
@@ -141,11 +153,27 @@ interface SessionFold {
     planCalls: Map<string, number>;
     /** 每轮费用明细（按轮次号升序，不含 sessionId）；sessionId 在合并时补齐。 */
     turns: SessionTurnRow[];
+    /** 角色归因中间量：消息文本长度（user/tool）与输入/输出成本实测拆分。 */
+    roles: RoleFold;
     /** 日志里最新的 session/title 文本（无标题事件时 undefined）。 */
     title?: string;
     /** 最后一个事件的时间戳（毫秒）；空日志为 0。 */
     lastActive: number;
 }
+/** 角色归因的会话级中间量：字符占比用于把输入成本摊到 user/tool。 */
+interface RoleFold {
+    userChars: number;
+    toolChars: number;
+    /** 输入侧成本（缓存命中 + 未命中 + 缓存写入，人民币元）。 */
+    inputCost: number;
+    /** 输出侧成本（人民币元）。 */
+    outputCost: number;
+}
+/**
+ * 消息文本长度：user/tool 角色分摊输入成本的启发式依据。字符串内容取其
+ * 长度；内容块数组累计文本块长度；其余形状按 0 计（durable 边界收窄）。
+ */
+export declare function messageTextLength(message: unknown): number;
 /**
  * Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
  * 其前置 request/header 记录的模型；同时提取最新会话标题、最后活跃时间，

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

@@ -8,6 +8,7 @@
  * A hover crosshair shows the day's model breakdown. No chart library — the
  * surface stays self-contained and offline.
  */
+import { type CostCurrency } from './pricing.ts';
 /** One model's legend identity: key, display name, and brand color. */
 export interface TrendSeriesModel {
     /** Stats key (`byModel` key), also the `byModel` map key. */
@@ -32,9 +33,11 @@ export interface TrendPoint {
  * Render the daily stacked cost bars plus the total-calls line.
  * @param props.data - sorted daily rows (ascending date).
  * @param props.models - the model legend, in bar order.
+ * @param props.currency - display currency for the cost labels.
  */
-export declare function TrendChart({ data, models }: {
+export declare function TrendChart({ data, models, currency }: {
     data: readonly TrendPoint[];
     models?: readonly TrendSeriesModel[];
+    currency?: CostCurrency;
 }): React.ReactNode;
 //# sourceMappingURL=TrendChart.d.ts.map

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

@@ -12,22 +12,33 @@
 import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SidebarFooterActionOwnerProps } from '@deepseek-ai/dsh-client-ui-sidebar/client';
 import type { createBillingBudgetStore } from './budget-store.ts';
-import { NS } from './locales.ts';
+import { NS, type UsageBillingKey } from './locales.ts';
 /** Model-connectivity health reported by the host model directory probe. */
 export interface ModelHealth {
     /** Whether the probe completed (false while still loading). */
     checked: boolean;
     /** True when at least one connected provider answered its model catalog. */
     available: boolean;
-    /** Connected provider count. */
-    providers: number;
-    /** Provider count whose catalog probe failed. */
+    /** 可用模型总数：累加每个厂商成功 advertise 的模型数，而非厂商数。 */
+    models: number;
+    /** 失效厂商数（目录探测失败的厂商；失败信息不细分到模型级）。 */
     failures: number;
     /** Display names of providers that answered their model catalog (live). */
     okProviders: readonly string[];
     /** Display names of providers whose catalog probe failed. */
     badProviders: readonly string[];
 }
+/** 仪表盘分区 Tab id。 */
+export type DashboardTab = 'overview' | 'trends' | 'providers' | 'details' | 'pricing';
+/**
+ * Tab 定义（顺序即渲染顺序）：概览=主数字/预算/KPI/热力图，趋势=趋势图/每轮费用，
+ * 明细=厂商计费与订阅，统计=工作区/会话明细，费率=模型单价表。导出供测试断言
+ * tab 与文案 key 对齐、decor 锚点落在正确分区。
+ */
+export declare const DASHBOARD_TABS: readonly {
+    id: DashboardTab;
+    labelKey: UsageBillingKey;
+}[];
 /**
  * The dashboard's display names (中文厂商名) never equal the provider names a
  * user actually configures (deepseek, zhipu, qwen…), so the dot match also
@@ -44,6 +55,43 @@ export declare const PROVIDER_ALIASES: Readonly<Record<string, readonly string[]
  * 导出供守卫测试：短别名（mi/yi）仅允许前缀形式，防止 minimax 等误吞。
  */
 export declare function providerFromModelKey(modelKey: string): string | undefined;
+/**
+ * 本月预计总花费：按本月已有记录的平均日消耗 × 本月天数外推；无本月记录时
+ * 回退为最近 7 天日均 × 本月天数；无任何记录时返回 0（调用方不展示）。
+ * 导出供测试：纯函数，不依赖组件。
+ * @param byDay - 按日费用表。
+ * @param monthPrefix - 本月前缀（YYYY-MM）。
+ * @param today - 今日日期戳（YYYY-MM-DD）。
+ * @returns 本月预计花费（人民币元）；无数据时为 0。
+ */
+export declare function projectMonthCost(byDay: Record<string, {
+    cost: number;
+}>, monthPrefix: string, today: string): number;
+/**
+ * 峰谷时段费用分摊：按每轮的起始时刻（北京时间高峰 9-12 / 14-18）把费用
+ * 归入高峰 / 空闲两档。导出供测试：纯函数。
+ * @param turns - 每轮费用行（需带 startedAt 与 cost）。
+ * @returns 两档费用合计（人民币元）。
+ */
+export declare function peakOffpeakCost(turns: readonly {
+    startedAt: number;
+    cost: number;
+}[]): {
+    peak: number;
+    offPeak: number;
+};
+/**
+ * 近 7 天费用序列（含今天，缺日补 0）：触发卡 hover 速览的迷你柱数据源。
+ * 导出供测试：纯函数（日期取本地时区）。
+ * @param byDay - 按日费用表。
+ * @returns 7 个 `{ date, cost }`，最旧在前。
+ */
+export declare function lastSevenDays(byDay: Record<string, {
+    cost: number;
+}>): readonly {
+    date: string;
+    cost: number;
+}[];
 /** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
 export interface UsageBillingInjected {
     checkModels: () => Promise<ModelHealth>;

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

@@ -0,0 +1,52 @@
+/**
+ * Cost-spike anomaly detection (pure): marks turns whose cost exceeds a
+ * rolling baseline, with attribution chips. Shared by the per-turn chart and
+ * any future surface; kept free of React so it unit-tests without a host.
+ *
+ * Adapted from the community dsh-usage-chart flagAnomalies semantics: the
+ * baseline is the previous up-to-`window` turns (rows without a cost are
+ * skipped, so the window counts effective rows).
+ */
+/** 异常归因 chip：输出增长 / 上下文膨胀 / 缓存命中率下降。 */
+export type AnomalyReason = 'output-growth' | 'context-bloat' | 'cache-hit-drop';
+/** 一轮异常标记（按会话+轮次定位）。 */
+export interface AnomalyFlag {
+    /** 会话 id（与数据行一致，用于定位该轮）。 */
+    sessionId: string;
+    /** 会话内轮次号。 */
+    turn: number;
+    /** 该轮成本（人民币元）。 */
+    cost: number;
+    /** 归因原因（可为空：只有突增事实、无明确归因）。 */
+    reasons: readonly AnomalyReason[];
+}
+/** 异常判定所需的每轮数据形状（TurnUsageRow 的子集）。 */
+export interface AnomalyRound {
+    sessionId: string;
+    turn: number;
+    /** 该轮成本；未估算（订阅/未知）时可为 0——基线窗口跳过 0 成本轮。 */
+    cost: number;
+    output: number;
+    input: number;
+    cacheHit: number;
+    cacheMiss: number;
+}
+/** 异常判定调参。 */
+export interface AnomalyOptions {
+    /** 对比窗口：取该轮之前至多 window 轮做基线。默认 6。 */
+    window?: number;
+    /** 突增阈值：成本超过基线均值 × threshold 即标记。默认 2。 */
+    threshold?: number;
+    /** 归因阈值：输出/输入超过基线均值 × 该值归因为增长。默认 1.8。 */
+    reasonFactor?: number;
+    /** 归因阈值：缓存命中率低于基线该百分点归因为下降。默认 15。 */
+    reasonHitDropPp?: number;
+}
+/**
+ * 标记成本异常轮次（按时间顺序传入；最近的轮次排在末尾）。
+ * @param rounds - 按起始时间升序的轮次序列（最早在前）。
+ * @param options - 窗口/阈值/归因灵敏度。
+ * @returns 异常标记数组（保持输入顺序）。
+ */
+export declare function flagAnomalies(rounds: readonly AnomalyRound[], options?: AnomalyOptions): AnomalyFlag[];
+//# sourceMappingURL=anomaly.d.ts.map

package/lib/types/client/budget-store.d.ts

@@ -12,8 +12,8 @@ export interface BudgetPrefsState {
     enabled: boolean;
     /** 用户设置的月度预算（人民币元）；0 = 未设置（回退到宿主默认值）。 */
     amount: number;
-    /** 最近一次超支通知的日期戳（YYYY-MM-DD）：超支通知每天最多一次，跨重启生效。 */
-    lastAlertDay: string;
+    /** 各档提醒的最后通知日期戳（档位百分比字符串 → YYYY-MM-DD）：每档每天最多一次。 */
+    tierAlertDays: Record<string, string>;
     /** 最近一次余额不足通知的日期戳（YYYY-MM-DD）：余额告警同样每天最多一次。 */
     lastBalanceAlertDay: string;
 }
@@ -21,7 +21,7 @@ export interface BudgetPrefsState {
 export type BudgetPrefsActions = {
     setEnabled: (d: BudgetPrefsState, on: boolean) => void;
     setAmount: (d: BudgetPrefsState, value: number) => void;
-    markAlerted: (d: BudgetPrefsState, day: string) => void;
+    markTierAlerted: (d: BudgetPrefsState, tiers: readonly number[], day: string) => void;
     markBalanceAlerted: (d: BudgetPrefsState, day: string) => void;
 };
 /**

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

@@ -0,0 +1,33 @@
+/**
+ * 数据导出：把用量统计导出为 CSV / JSON 供对账。
+ *
+ * 纯函数生成文本（按日 / 按会话两个视角），DOM 下载副作用单独隔离在
+ * `downloadText`；金额一律人民币元（与聚合口径一致），文件名带日期范围。
+ */
+/** 按日聚合行（与 UsageStatsDocument.byDay 的行同形）。 */
+export interface DayExportRow {
+    calls: number;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    cost: number;
+}
+/** 会话导出行（与 SessionUsageRow 同形，结构化声明避免跨文件引用）。 */
+export interface SessionExportRow {
+    id: string;
+    title?: string;
+    cwd?: string;
+    calls: number;
+    cost: number;
+    lastActive: number;
+}
+/** 按日 CSV：日期,调用,输入,输出,缓存命中,缓存未命中,费用(元)。 */
+export declare function dayRowsCsv(byDay: Record<string, DayExportRow>): string;
+/** 按会话 CSV：会话 id,标题,项目,调用,费用(元),最后活跃(ISO)。 */
+export declare function sessionRowsCsv(rows: readonly SessionExportRow[]): string;
+/** 导出文件名：带日期范围（usage-2026-08-01_2026-08-22.csv）；无日期时只带前缀。 */
+export declare function exportFileName(prefix: string, ext: 'csv' | 'json', dates: readonly string[]): string;
+/** 触发浏览器下载（唯一 DOM 副作用；调用方在 click 手势里使用）。 */
+export declare function downloadText(filename: string, text: string, mime: string): void;
+//# sourceMappingURL=export.d.ts.map

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

@@ -0,0 +1,35 @@
+/**
+ * UsageHeatmap: dependency-free month calendar heatmap of daily cost.
+ *
+ * Styled after an "activity map": one large rounded cell per day with the
+ * date number printed inside, laid out in a 7-column grid (Sunday-first).
+ * Week-first data layout: each week is one array element of 7 cells, so the
+ * grid auto-rows place them correctly without per-cell gridColumnStart hacks.
+ * Cell intensity is the day's cost quantized to five levels against the month
+ * maximum (mint-green gradient, like the reference activity map). Leading
+ * slots before the 1st and trailing slots after the last day carry the
+ * cross-month dates as gray placeholders; future days of this month render as
+ * gray placeholders too. Hover shows the exact date and amount.
+ */
+import { type CostCurrency } from './pricing.ts';
+/** One heatmap day. */
+export interface HeatmapDay {
+    /** ISO date `YYYY-MM-DD` (local calendar). */
+    date: string;
+    /** Value to intensity-map (daily cost in CNY). */
+    value: number;
+}
+/**
+ * Render the month heatmap.
+ * @param props.days - daily cost rows (keys are `YYYY-MM-DD`).
+ * @param props.currency - display currency for the hover amount.
+ * @param props.now - anchor date (defaults to today); injectable for tests.
+ * @param props.t - locale function (used for the legend labels).
+ */
+export declare function UsageHeatmap({ days, currency, now, t }: {
+    days: readonly HeatmapDay[];
+    currency: CostCurrency;
+    now?: Date;
+    t: (key: 'billing.costAbbr' | 'billing.noData' | 'billing.heatmapLess' | 'billing.heatmapMore') => string;
+}): React.ReactNode;
+//# sourceMappingURL=heatmap.d.ts.map