@kenz1117/dsh-ui-usage-billing 0.2.6 → 0.3.0

package/lib/index.js

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
@@ -9,18 +9,6 @@ function currentRate() {
 /** Default share of traffic assumed to fall in the peak band (0..1). */
 const DEFAULT_PEAK_SHARE = .5;
 /**
-* Model keys served through a subscription plan (e.g. a coding plan or topic
-* plan) instead of metered per-token API billing. Usage through these routes
-* costs no tokens: the estimator treats them as ¥0 and the billing table
-* labels them 订阅包含. Add any model key your deployment serves through a
-* plan here; leave empty when every route is pay-as-you-go.
-*/
-const SUBSCRIPTION_PLAN_KEYS = [];
-/** Whether one stats model key is billed through a subscription plan. */
-function isSubscriptionPlan(key) {
-	return SUBSCRIPTION_PLAN_KEYS.includes(key);
-}
-/**
 * Built-in catalog of current mainstream models as of 2026-08-16, priced from
 * each provider's official price page. Domestic providers are OpenAI-API
 * compatible and publish RMB prices directly; overseas providers publish USD
@@ -240,6 +228,18 @@ const MODEL_CATALOG = [
 			output: 100
 		}
 	},
+	{
+		key: "mimo-v2.5",
+		name: "MiMo V2.5",
+		provider: "小米",
+		colorVar: "dsw-static-green-400",
+		price: {
+			currency: "CNY",
+			input: 4,
+			cacheHit: .4,
+			output: 12
+		}
+	},
 	{
 		key: "minimax",
 		name: "MiniMax-M3",
@@ -520,7 +520,6 @@ function priceBandCost(band, buckets, currency) {
 * @returns the estimated cost in CNY.
 */
 function computeCost(entry, buckets, peakShare = DEFAULT_PEAK_SHARE) {
-	if (isSubscriptionPlan(entry.key)) return 0;
 	const peak = priceBandCost(entry.price, buckets, entry.price.currency);
 	const off = entry.price.offPeak === void 0 ? peak : priceBandCost(entry.price.offPeak, buckets, entry.price.currency);
 	return peak * peakShare + off * (1 - peakShare);
@@ -552,14 +551,28 @@ const MODEL_KEY_ALIASES = {
 	"qwen-max": "qwen-max",
 	"hunyuan-t1": "hunyuan-t1",
 	"step-3.7-flash": "step",
-	"seed-2.0-mini": "doubao-mini"
+	"seed-2.0-mini": "doubao-mini",
+	"k3": "kimi-k3",
+	"kimi-k3": "kimi-k3"
 };
 /**
-* 走订阅套餐（coding / token / agent plan）的 provider id：这些通道的调用
-* 按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
-* 部署可在 plugin config 的 `subscriptionProviders` 中覆盖。
+* 走订阅套餐（coding / token plan / opencode 订阅）的 provider id：这些通道的
+* 调用按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
+* 与 pi-ai 内置提供方对齐（含各地区变体：qwen/xiaomi 的 token-plan、opencode 与
+* opencode-go、zai-coding-cn）；部署可在 plugin config 的 `subscriptionProviders`
+* 中覆盖。
 */
-const DEFAULT_SUBSCRIPTION_PROVIDERS = ["kimi-coding", "xiaomi-token-plan-cn"];
+const DEFAULT_SUBSCRIPTION_PROVIDERS = [
+	"kimi-coding",
+	"zai-coding-cn",
+	"opencode",
+	"opencode-go",
+	"qwen-token-plan",
+	"qwen-token-plan-cn",
+	"xiaomi-token-plan-ams",
+	"xiaomi-token-plan-cn",
+	"xiaomi-token-plan-sgp"
+];
 /** Zeroed usage accumulator. */
 function emptyUsage() {
 	return {
@@ -588,12 +601,12 @@ function foldUsage(acc, usage, key, subscription) {
 	acc.output += usage.outputTokens;
 	acc.cacheHit += cacheHit;
 	acc.cacheMiss += cacheMiss;
-	acc.cost = !subscription && MODEL_CATALOG.some((entry) => entry.key === key) ? computeCost(modelOf(key), {
-		input: acc.input,
-		cacheHit: acc.cacheHit,
-		cacheMiss: acc.cacheMiss,
-		output: acc.output
-	}) : 0;
+	if (!subscription && MODEL_CATALOG.some((entry) => entry.key === key)) acc.cost += computeCost(modelOf(key), {
+		input: cacheHit + cacheMiss,
+		cacheHit,
+		cacheMiss,
+		output: usage.outputTokens
+	});
 }
 /** Local-time date stamp (the host runs in the user's timezone). */
 function dayStamp(time) {
@@ -619,48 +632,155 @@ function modelDayCell(map, day, modelKey) {
 	return usageCell(models, modelKey);
 }
 /**
-* Aggregate real usage from every persisted session log.
+* Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
+* 其前置 request/header 记录的模型；同时提取最新会话标题与最后活跃时间。
+* @param events - the session's persisted events in log order.
+* @param subscriptionProviders - provider ids billed through subscription plans.
+* @returns the per-session fold (cached by the incremental aggregator).
+*/
+function foldSession(events, subscriptionProviders) {
+	const fold = {
+		total: emptyUsage(),
+		byModel: /* @__PURE__ */ new Map(),
+		byDay: /* @__PURE__ */ new Map(),
+		byDayModels: /* @__PURE__ */ new Map(),
+		planCalls: /* @__PURE__ */ new Map(),
+		lastActive: 0
+	};
+	let key = "other";
+	let subscription = false;
+	for (const event of events) {
+		fold.lastActive = Math.max(fold.lastActive, event.time);
+		if (event.type === "session/title") {
+			const title = event.data.title;
+			if (typeof title === "string" && title.length > 0) fold.title = title;
+			continue;
+		}
+		if (event.type === "request/header") {
+			const { model, provider } = event.data.header.config;
+			key = MODEL_KEY_ALIASES[model] ?? model;
+			subscription = subscriptionProviders.has(provider);
+			continue;
+		}
+		if (event.type !== "assistant/message") continue;
+		const usage = event.data.usage;
+		if (usage === void 0) continue;
+		const modelKey = key;
+		const day = dayStamp(event.time);
+		foldUsage(fold.total, usage, modelKey, subscription);
+		foldUsage(usageCell(fold.byModel, modelKey), usage, modelKey, subscription);
+		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription);
+		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription);
+		if (subscription) fold.planCalls.set(modelKey, (fold.planCalls.get(modelKey) ?? 0) + 1);
+	}
+	return fold;
+}
+/** Accumulate one ModelUsage into another (merge step of the incremental aggregator). */
+function mergeUsageInto(acc, cell) {
+	acc.calls += cell.calls;
+	acc.input += cell.input;
+	acc.output += cell.output;
+	acc.cacheHit += cell.cacheHit;
+	acc.cacheMiss += cell.cacheMiss;
+	acc.cost += cell.cost;
+}
+/**
+* Create the incremental usage aggregator.
 * @param persistence - the session persistence service.
 * @param options - aggregation tuning (e.g. subscription-plan providers).
-* @returns the usage-stats document (same shape the dashboard expects).
+* @returns the aggregator holding the per-session fold cache.
 */
-async function aggregateUsage(persistence, options = {}) {
+function createUsageAggregator(persistence, options = {}) {
 	const subscriptionProviders = new Set(options.subscriptionProviders ?? DEFAULT_SUBSCRIPTION_PROVIDERS);
-	const total = emptyUsage();
-	const byModel = /* @__PURE__ */ new Map();
-	const byDay = /* @__PURE__ */ new Map();
-	const byModelDay = /* @__PURE__ */ new Map();
-	for (const meta of await persistence.list()) {
-		const { events } = await persistence.readFrom(meta.id, 0);
-		let key = "other";
-		let subscription = false;
-		for (const event of events) {
-			if (event.type === "request/header") {
-				const { model, provider } = event.data.header.config;
-				key = MODEL_KEY_ALIASES[model] ?? model;
-				subscription = subscriptionProviders.has(provider);
+	const cache = /* @__PURE__ */ new Map();
+	let lastDoc;
+	let lastAt = 0;
+	/** 失效键：日志文件的 mtime+size；拿不到（后端无 locate / 文件丢失）时每次重折。 */
+	const stampOf = async (meta) => {
+		const location = persistence.locate?.(meta);
+		if (location === void 0) return null;
+		try {
+			const info = await stat(location.path);
+			return `${String(info.mtimeMs)}:${String(info.size)}`;
+		} catch {
+			return null;
+		}
+	};
+	return { async aggregate() {
+		const now = Date.now();
+		if (lastDoc !== void 0 && now - lastAt < 5e3) return lastDoc;
+		const metas = await persistence.list();
+		const seen = /* @__PURE__ */ new Set();
+		const folds = [];
+		for (const meta of metas) {
+			const id = String(meta.id);
+			seen.add(id);
+			const stamp = await stampOf(meta);
+			const hit = cache.get(id);
+			if (hit !== void 0 && stamp !== null && hit.stamp === stamp) {
+				folds.push({
+					meta,
+					fold: hit.fold
+				});
 				continue;
 			}
-			if (event.type !== "assistant/message" || event.data.usage === void 0) continue;
-			const modelKey = key;
-			const day = dayStamp(event.time);
-			foldUsage(total, event.data.usage, modelKey, subscription);
-			foldUsage(usageCell(byModel, modelKey), event.data.usage, modelKey, subscription);
-			foldUsage(usageCell(byDay, day), event.data.usage, modelKey, subscription);
-			foldUsage(modelDayCell(byModelDay, day, modelKey), event.data.usage, modelKey, subscription);
+			const { events } = await persistence.readFrom(meta.id, 0);
+			const fold = foldSession(events, subscriptionProviders);
+			cache.set(id, {
+				stamp,
+				fold
+			});
+			folds.push({
+				meta,
+				fold
+			});
 		}
-	}
-	const toRecord = (map) => Object.fromEntries(map);
-	const toModelDayRecord = (map) => Object.fromEntries([...map].map(([day, models]) => [day, Object.fromEntries(models)]));
-	return {
-		version: 2,
-		updatedAt: Date.now(),
-		source: "session-logs",
-		total,
-		byModel: toRecord(byModel),
-		byDay: toRecord(byDay),
-		byDayModels: toModelDayRecord(byModelDay)
-	};
+		for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
+		const total = emptyUsage();
+		const byModel = /* @__PURE__ */ new Map();
+		const byDay = /* @__PURE__ */ new Map();
+		const byDayModels = /* @__PURE__ */ new Map();
+		const planCalls = /* @__PURE__ */ new Map();
+		const sessionRows = [];
+		for (const { meta, fold } of folds) {
+			mergeUsageInto(total, fold.total);
+			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);
+			for (const [modelKey, count] of fold.planCalls) planCalls.set(modelKey, (planCalls.get(modelKey) ?? 0) + count);
+			if (fold.total.calls > 0) sessionRows.push({
+				id: String(meta.id),
+				...fold.title !== void 0 ? { title: fold.title } : {},
+				...meta.cwd !== void 0 ? { cwd: meta.cwd } : {},
+				calls: fold.total.calls,
+				cost: fold.total.cost,
+				lastActive: fold.lastActive
+			});
+		}
+		sessionRows.sort((a, b) => b.cost - a.cost || b.lastActive - a.lastActive);
+		const toRecord = (map) => {
+			const record = {};
+			for (const [key, cell] of map) if (planCalls.get(key) === cell.calls && cell.calls > 0) record[key] = {
+				...cell,
+				plan: true
+			};
+			else record[key] = cell;
+			return record;
+		};
+		const toModelDayRecord = (map) => Object.fromEntries([...map].map(([day, models]) => [day, Object.fromEntries(models)]));
+		lastDoc = {
+			version: 2,
+			updatedAt: now,
+			source: "session-logs",
+			total,
+			byModel: toRecord(byModel),
+			byDay: toRecord(byDay),
+			byDayModels: toModelDayRecord(byDayModels),
+			bySession: sessionRows.slice(0, 100)
+		};
+		lastAt = now;
+		return lastDoc;
+	} };
 }
 //#endregion
 //#region lib/types/balance.js
@@ -938,6 +1058,7 @@ const inject = [
 * @param config - optional statsPath override.
 */
 function apply(ctx, config = {}) {
+	const aggregator = createUsageAggregator(ctx.sessionPersistence, { ...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders } });
 	const cwd = process.cwd();
 	const candidates = [
 		config.statsPath,
@@ -981,13 +1102,23 @@ function apply(ctx, config = {}) {
 		handler: async (_req, res) => {
 			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
 			try {
-				res.end(JSON.stringify(await aggregateUsage(ctx.sessionPersistence, { ...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders } })));
+				const stats = await aggregator.aggregate();
+				const injected = {
+					...config.monthlyBudget === void 0 ? {} : { budget: config.monthlyBudget },
+					...config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: config.lowBalanceThreshold }
+				};
+				res.end(JSON.stringify(Object.keys(injected).length === 0 ? stats : {
+					...stats,
+					...injected
+				}));
 				return;
 			} catch {}
 			for (const candidate of candidates) try {
 				const text = await readFile(candidate, "utf8");
-				JSON.parse(text);
-				res.end(text);
+				const doc = JSON.parse(text);
+				if (config.monthlyBudget !== void 0) doc["budget"] = config.monthlyBudget;
+				if (config.lowBalanceThreshold !== void 0) doc["lowBalanceThreshold"] = config.lowBalanceThreshold;
+				res.end(JSON.stringify(doc));
 				return;
 			} catch {}
 			res.end(JSON.stringify({ error: "usage stats unavailable" }));

package/lib/types/aggregate.d.ts

@@ -18,9 +18,11 @@ import type { TokenUsage } from '@deepseek-ai/dsh-llm';
  */
 export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
 /**
- * 走订阅套餐（coding / token / agent plan）的 provider id：这些通道的调用
- * 按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
- * 部署可在 plugin config 的 `subscriptionProviders` 中覆盖。
+ * 走订阅套餐（coding / token plan / opencode 订阅）的 provider id：这些通道的
+ * 调用按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
+ * 与 pi-ai 内置提供方对齐（含各地区变体：qwen/xiaomi 的 token-plan、opencode 与
+ * opencode-go、zai-coding-cn）；部署可在 plugin config 的 `subscriptionProviders`
+ * 中覆盖。
  */
 export declare const DEFAULT_SUBSCRIPTION_PROVIDERS: readonly string[];
 /** Aggregation tuning options. */
@@ -36,6 +38,8 @@ export interface ModelUsage {
     cacheHit: number;
     cacheMiss: number;
     cost: number;
+    /** 该模型本次统计的所有调用是否都走订阅通道（coding/token plan）；混合通道不置位。 */
+    plan?: boolean;
 }
 /** Zeroed usage accumulator. */
 export declare function emptyUsage(): ModelUsage;
@@ -53,9 +57,11 @@ export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: strin
 export declare function dayStamp(time: number): string;
 /**
  * The persistence surface the aggregate reads: enough of
- * `SessionPersistence` to list sessions and read each log once.
+ * `SessionPersistence` to list sessions and read each log once; `locate`
+ * is optional — backends exposing it give the incremental cache a cheap
+ * invalidation stamp (artifact mtime + size), others always re-fold.
  */
-export type UsagePersistence = Pick<SessionPersistence, 'list' | 'readFrom'>;
+export type UsagePersistence = Pick<SessionPersistence, 'list' | 'readFrom'> & Partial<Pick<SessionPersistence, 'locate'>>;
 /** The usage-stats document served to the billing dashboard. */
 export interface UsageStatsDocument {
     version: number;
@@ -66,12 +72,73 @@ export interface UsageStatsDocument {
     byDay: Record<string, ModelUsage>;
     /** 模型 × 日期 二维统计：趋势图按模型堆叠的输入（[date][modelKey]）。 */
     byDayModels: Record<string, Record<string, ModelUsage>>;
+    /** 会话明细：按费用倒序，封顶 {@link SESSION_ROW_LIMIT} 行；旧快照可能缺失。 */
+    bySession: SessionUsageRow[];
 }
+/** 会话明细行：仪表盘「会话明细」面板的数据源。 */
+export interface SessionUsageRow {
+    /** 会话 id（字符串形式）。 */
+    id: string;
+    /** 日志里最新的 session/title 文本；无标题事件时缺失。 */
+    title?: string;
+    /** 会话创建时的工作目录（项目路径）；未知时缺失。 */
+    cwd?: string;
+    calls: number;
+    cost: number;
+    /** 最后一个事件的时间戳（毫秒）。 */
+    lastActive: number;
+}
+/** 会话明细行的响应封顶：控制 payload 体积，重度用户的完整长尾不逐行下发。 */
+export declare const SESSION_ROW_LIMIT = 100;
+/** 聚合文档的短 TTL（毫秒）：合并密集轮询，TTL 内直接复用上次的合并结果。 */
+export declare const AGGREGATE_TTL_MS = 5000;
+/** One persisted session's folded usage plus drill-down metadata. */
+interface SessionFold {
+    total: ModelUsage;
+    byModel: Map<string, ModelUsage>;
+    byDay: Map<string, ModelUsage>;
+    byDayModels: Map<string, Map<string, ModelUsage>>;
+    /** 每个模型 key 在本会话内走订阅通道的调用数（合并时跨会话累加判定 plan）。 */
+    planCalls: Map<string, number>;
+    /** 日志里最新的 session/title 文本（无标题事件时 undefined）。 */
+    title?: string;
+    /** 最后一个事件的时间戳（毫秒）；空日志为 0。 */
+    lastActive: number;
+}
+/**
+ * Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
+ * 其前置 request/header 记录的模型；同时提取最新会话标题与最后活跃时间。
+ * @param events - the session's persisted events in log order.
+ * @param subscriptionProviders - provider ids billed through subscription plans.
+ * @returns the per-session fold (cached by the incremental aggregator).
+ */
+export declare function foldSession(events: readonly {
+    type: string;
+    time: number;
+    data: never;
+}[], subscriptionProviders: ReadonlySet<string>): SessionFold;
+/**
+ * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——
+ * 日志没动的会话直接复用，只有写过的会话重新折叠；整份文档另有短 TTL
+ * 合并密集轮询。缓存活在内存里（进程重启后首次全量折叠一次）。
+ */
+export interface UsageAggregator {
+    /** Aggregate current usage, reusing cached per-session folds when their logs are untouched. */
+    aggregate(): Promise<UsageStatsDocument>;
+}
+/**
+ * Create the incremental usage aggregator.
+ * @param persistence - the session persistence service.
+ * @param options - aggregation tuning (e.g. subscription-plan providers).
+ * @returns the aggregator holding the per-session fold cache.
+ */
+export declare function createUsageAggregator(persistence: UsagePersistence, options?: AggregateOptions): UsageAggregator;
 /**
- * Aggregate real usage from every persisted session log.
+ * Aggregate real usage from every persisted session log (one-shot, no cache).
  * @param persistence - the session persistence service.
  * @param options - aggregation tuning (e.g. subscription-plan providers).
  * @returns the usage-stats document (same shape the dashboard expects).
  */
 export declare function aggregateUsage(persistence: UsagePersistence, options?: AggregateOptions): Promise<UsageStatsDocument>;
+export {};
 //# sourceMappingURL=aggregate.d.ts.map

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

@@ -1,9 +1,10 @@
 /**
  * TrendChart: dependency-free SVG chart of daily cost + calls.
  *
- * The columns are GROUPED per model — one bar per model per day, each in its
- * brand color, so per-model cost is directly comparable. The blue line is the
- * total call volume across all models, plotted on its own right-hand axis.
+ * The columns are STACKED per day — one bar per day, with each model's cost
+ * as a colored segment inside the bar, so the daily total reads at a glance
+ * and the model mix stays visible. The blue line is the total call volume
+ * across all models, plotted on its own right-hand axis.
  * A hover crosshair shows the day's model breakdown. No chart library — the
  * surface stays self-contained and offline.
  */
@@ -28,7 +29,7 @@ export interface TrendPoint {
     byModel?: Readonly<Record<string, number>>;
 }
 /**
- * Render the daily grouped cost bars plus the total-calls line.
+ * 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.
  */

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

@@ -9,8 +9,9 @@
  * before real data arrives the dashboard shows an empty (zero) snapshot,
  * never fabricated samples.
  */
-import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+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';
 /** Model-connectivity health reported by the host model directory probe. */
 export interface ModelHealth {
@@ -27,10 +28,35 @@ export interface ModelHealth {
     /** Display names of providers whose catalog probe failed. */
     badProviders: readonly string[];
 }
-/** Full props type for the UsageBilling component. */
-type UsageBillingProps = PropsRuntime<'sidebar.footer.action'> & SidebarFooterActionOwnerProps & InjectFace<{
+/**
+ * The dashboard's display names (中文厂商名) never equal the provider names a
+ * user actually configures (deepseek, zhipu, qwen…), so the dot match also
+ * accepts a bidirectional substring hit and a display-name alias list.
+ * 导出供一致性守卫测试：catalog 每个厂商都必须在此登记（Custom 除外），
+ * 防止新增厂商漏配导致健康绿灯不亮。
+ */
+export declare const PROVIDER_ALIASES: Readonly<Record<string, readonly string[]>>;
+/**
+ * 从真实 model id 反推提供方显示名：目录未收录的模型（key 落回「其他」）
+ * 只靠 entry.provider（Custom）永远点不亮健康灯，这里用厂商别名对 model id
+ * 做强匹配（别名作为完整 id / 前缀 / 独立段）与弱匹配（长别名子串），
+ * 命中即显示厂商名并点亮健康点；无命中保持 Custom。
+ * 导出供守卫测试：短别名（mi/yi）仅允许前缀形式，防止 minimax 等误吞。
+ */
+export declare function providerFromModelKey(modelKey: string): string | undefined;
+/** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
+export interface UsageBillingInjected {
     checkModels: () => Promise<ModelHealth>;
-}> & PropsLocale<typeof NS>;
+    publishCosts: (costs: {
+        todayCost: number;
+        monthCost: number;
+    }) => void;
+    registerOpen: (handler: () => void) => () => void;
+}
+/** 预算 store 的 props 份额（useStore 读取 + actions 写面）。 */
+type BillingBudgetStoreProps = PropsStore<ReturnType<typeof createBillingBudgetStore>>;
+/** Full props type for the UsageBilling component. */
+type UsageBillingProps = PropsRuntime<'sidebar.footer.action'> & SidebarFooterActionOwnerProps & InjectFace<UsageBillingInjected> & PropsRenderSlots<'billing.dashboard.decor'> & BillingBudgetStoreProps & PropsLocale<typeof NS>;
 /**
  * UsageBilling: sidebar trigger plus the billing dashboard modal.
  * @param props - framework-provided sidebar and locale props.

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

@@ -5,9 +5,40 @@
  * Displays compact cost/token/cache metrics in the sidebar footer, above the
  * Settings button, plus a model-health dot (green when any connected model
  * route responds). Expands to a detailed dashboard panel on click.
+ *
+ * 与主题插件（如 acid-zine）的协作走 slot 与服务：billing 声明装饰孔位
+ *（billing.dashboard.decor）并注册计费指标服务（ctx.billingMetrics），主题
+ * 插件主动注入装饰视觉、消费费用数据——billing 不反向依赖任何主题包。
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
 import { type UsageBillingKey } from './locales.ts';
+import { type BillingMetricsService } from './billing-service.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * Dashboard 弹窗内的装饰孔位：主题插件（如 acid-zine）按 position 锚点
+         * 注入 MacDots、撕角便签、胶带标题、条码等 ZINE 元素。kind=list，可多个
+         * 注册者并列；未注入时走 billing 默认视觉。
+         */
+        'billing.dashboard.decor': {
+            kind: 'list';
+            scope: 'root';
+            owner: BillingDashboardDecorOwnerProps;
+        };
+    }
+}
+/** Dashboard 装饰的锚点位置：head/headTitle=窗口标题区；hero=主数字卡；trend/models=面板标题；footer=面板底部。 */
+export type BillingDecorPosition = 'head' | 'headTitle' | 'hero' | 'trend' | 'models' | 'footer';
+/** Dashboard 装饰组件收到的所有者数据：当前锚点。 */
+export interface BillingDashboardDecorOwnerProps {
+    position: BillingDecorPosition;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** 计费指标服务（billing 插件提供；主题插件可选消费）。 */
+        billingMetrics?: BillingMetricsService;
+    }
+}
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         /** The usage billing surface's copy. */

package/lib/types/client/billing-service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 计费指标服务（ctx.billingMetrics）：把 UsageBilling 的实时费用摘要与
+ * 弹窗打开能力开放给其他插件（如 acid-zine 主题的贴纸层）消费。
+ *
+ * 依赖方向为「billing 提供服务、主题适配消费」：billing 插件是唯一的
+ * 写入方（组件通过 inject 的 publishCosts / registerOpen 写入），消费方
+ * 只读费用快照并触发弹窗打开——billing 不反向依赖任何主题包。
+ */
+/** 计费摘要（精简版，仅供外部展示；金额为人民币元）。 */
+export interface BillingCosts {
+    todayCost: number;
+    monthCost: number;
+}
+/** 消费方（如酸-zine 贴纸层）可用的只读接口。 */
+export interface BillingMetricsService {
+    /** 当前费用快照；从未发布过则 undefined。 */
+    readCosts(): BillingCosts | undefined;
+    /**
+     * 订阅费用更新；立即收到当前值一次（若无值则为 undefined）。
+     * @param listener - 费用回调。
+     * @returns 退订函数。
+     */
+    subscribeCosts(listener: (costs: BillingCosts | undefined) => void): () => void;
+    /** 打开计费仪表盘（若 billing 弹窗已挂载）。 */
+    openDashboard(): void;
+}
+/** 服务运行时：在只读接口之上追加写入入口，仅 apply 与组件使用。 */
+export interface BillingMetricsRuntime extends BillingMetricsService {
+    /** 发布最新费用摘要（UsageBilling 组件每次渲染数据变化时调用）。 */
+    publishCosts(costs: BillingCosts): void;
+    /**
+     * 注册弹窗打开回调；组件卸载时应解除。
+     * @param handler - 打开弹窗的处理函数。
+     * @returns 解除注册的函数。
+     */
+    registerOpen(handler: () => void): () => void;
+}
+/** 创建计费指标运行时（apply 内调用，随插件纤维存活）。 */
+export declare function createBillingMetrics(): BillingMetricsRuntime;
+//# sourceMappingURL=billing-service.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * 预算偏好 store：本月预算的开关与金额。
+ *
+ * 用户在仪表盘里用开关控制预算条显隐、用数字输入框设置金额；状态经框架
+ * store 引擎持久化到 localStorage（persist key 即存储身份），重启后保留。
+ * 宿主 Config 的 monthlyBudget 仅作为金额未设置时的默认值，用户输入优先。
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+/** 预算偏好状态。 */
+export interface BudgetPrefsState {
+    /** 预算条开关：关 = 只显示标题行与开关，不显示进度。 */
+    enabled: boolean;
+    /** 用户设置的月度预算（人民币元）；0 = 未设置（回退到宿主默认值）。 */
+    amount: number;
+    /** 最近一次超支通知的日期戳（YYYY-MM-DD）：超支通知每天最多一次，跨重启生效。 */
+    lastAlertDay: string;
+    /** 最近一次余额不足通知的日期戳（YYYY-MM-DD）：余额告警同样每天最多一次。 */
+    lastBalanceAlertDay: string;
+}
+/** 预算偏好的完整写面（组件只能经这些 action 写入）；type 别名以兼容 ActionsDecl 的索引签名约束。 */
+export type BudgetPrefsActions = {
+    setEnabled: (d: BudgetPrefsState, on: boolean) => void;
+    setAmount: (d: BudgetPrefsState, value: number) => void;
+    markAlerted: (d: BudgetPrefsState, day: string) => void;
+    markBalanceAlerted: (d: BudgetPrefsState, day: string) => void;
+};
+/**
+ * Declare the budget-preferences store handle.
+ * @returns the store handle for the register call's store seat.
+ */
+export declare function createBillingBudgetStore(): EngineStoreHandle<BudgetPrefsState, BudgetPrefsActions>;
+//# sourceMappingURL=budget-store.d.ts.map

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

@@ -8,4 +8,6 @@
 export { inject, apply } from './apply.ts';
 export { UsageBilling } from './UsageBilling.tsx';
 export type { UsageBillingKey } from './locales.ts';
+export type { BillingCosts, BillingMetricsService } from './billing-service.ts';
+export type { BillingDecorPosition, BillingDashboardDecorOwnerProps } from './apply.ts';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trendEmpty' | 'billing.models' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trend7d' | 'billing.trend30d' | 'billing.trendEmpty' | 'billing.budget' | 'billing.sessions' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetOverBody' | 'billing.models' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.balanceDays' | 'billing.balanceLowBody';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;