@kenz1117/dsh-ui-usage-billing 1.4.18 → 1.4.20

package/lib/index.js

@@ -2422,8 +2422,10 @@ function emptyUsage() {
 * @param pricedCost - 调用方预算好的本次费用（同一条消息折叠进多个桶时计价结果相同，
 *   逐桶重算会让最热路径付出 N 倍常数）；提供时跳过内部的计价闸门与计算，
 *   调用方保证其已按 `!subscription && isPriced(key)` 判定。
+* @param unverifiedChannel - 本次调用是否来自未知通道（配置外 provider）。未知通道的
+*   支出主体无法核实，费用一律记 0（token 照常统计，issue #82）。
 */
-function foldUsage(acc, usage, key, subscription, timeMs, official = false, pricedCost) {
+function foldUsage(acc, usage, key, subscription, timeMs, official = false, pricedCost, unverifiedChannel = false) {
 	const cacheHit = usage.cacheReadTokens ?? 0;
 	const cacheMiss = usage.inputTokens + (usage.cacheWriteTokens ?? 0);
 	acc.calls += 1;
@@ -2439,7 +2441,7 @@ function foldUsage(acc, usage, key, subscription, timeMs, official = false, pric
 		if (official) acc.officialCost += pricedCost;
 		return;
 	}
-	if (!subscription && isPriced(key)) {
+	if (!subscription && !unverifiedChannel && isPriced(key)) {
 		const thisCost = computeCostAt(modelOf(key), {
 			input: cacheHit + cacheMiss,
 			cacheHit,
@@ -2994,8 +2996,9 @@ function foldInto(fold, machine, events, subscriptionProviders, officialProvider
 		}
 		const modelKey = key;
 		const day = dayStamp(event.time);
-		const priced = !subscription && isPriced(modelKey);
-		if (!subscription && !priced) fold.unpricedModels.add(modelKey);
+		const unverifiedChannel = siteBucket === "unknown";
+		const priced = !subscription && !unverifiedChannel && isPriced(modelKey);
+		if (!subscription && !isPriced(modelKey)) fold.unpricedModels.add(modelKey);
 		const entry = priced ? modelOf(modelKey) : void 0;
 		const thisCost = entry === void 0 ? void 0 : computeCostAt(entry, {
 			input: (usage.cacheReadTokens ?? 0) + usage.inputTokens + (usage.cacheWriteTokens ?? 0),
@@ -3003,13 +3006,13 @@ function foldInto(fold, machine, events, subscriptionProviders, officialProvider
 			cacheMiss: usage.inputTokens + (usage.cacheWriteTokens ?? 0),
 			output: usage.outputTokens
 		}, event.time);
-		foldUsage(fold.total, usage, modelKey, subscription, event.time, official, thisCost);
-		foldUsage(usageCell(fold.byModel, modelKey), usage, modelKey, subscription, event.time, official, thisCost);
-		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time, official, thisCost);
-		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time, official, thisCost);
-		foldUsage(modelDaySiteCell(fold.byDayModelsSite, day, modelKey, siteBucket), usage, modelKey, subscription, event.time, official, thisCost);
-		foldUsage(usageCell(fold.bySite, siteBucket), usage, modelKey, subscription, event.time, official, thisCost);
-		foldUsage(usageCell(fold.byTier, tierAt(event.time)), usage, modelKey, subscription, event.time, official, thisCost);
+		foldUsage(fold.total, usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
+		foldUsage(usageCell(fold.byModel, modelKey), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
+		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
+		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
+		foldUsage(modelDaySiteCell(fold.byDayModelsSite, day, modelKey, siteBucket), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
+		foldUsage(usageCell(fold.bySite, siteBucket), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
+		foldUsage(usageCell(fold.byTier, tierAt(event.time)), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
 		if (subscription) fold.planCalls.set(modelKey, (fold.planCalls.get(modelKey) ?? 0) + 1);
 		const turn = event.data.turn ?? -1;
 		const state = turnState(turns, turn);
@@ -3207,7 +3210,7 @@ function createUsageAggregator(persistence, options = {}) {
 			id,
 			...cwd === void 0 ? {} : { cwd },
 			...stamp === null ? {} : { stamp },
-			foldVersion: 16,
+			foldVersion: 17,
 			fingerprint: foldFingerprint,
 			fold: serializeFold(fold)
 		};
@@ -3304,7 +3307,7 @@ function createUsageAggregator(persistence, options = {}) {
 			try {
 				const cwd = meta.cwd;
 				const ledgerRow = ledger.get(id);
-				if (ledgerRow !== void 0 && ledgerRow.stamp !== void 0 && stamp !== null && ledgerRow.stamp === stamp && (ledgerRow.foldVersion ?? 1) === 16 && ledgerRow.fingerprint === foldFingerprint) {
+				if (ledgerRow !== void 0 && ledgerRow.stamp !== void 0 && stamp !== null && ledgerRow.stamp === stamp && (ledgerRow.foldVersion ?? 1) === 17 && ledgerRow.fingerprint === foldFingerprint) {
 					const fold = deserializeFold(ledgerRow.fold);
 					folds.push({
 						id,
@@ -3386,7 +3389,7 @@ function createUsageAggregator(persistence, options = {}) {
 			for (const entry of ledger.values()) {
 				if (included.has(entry.id)) continue;
 				try {
-					const stale = (entry.foldVersion ?? 1) < 16 || entry.fingerprint !== foldFingerprint;
+					const stale = (entry.foldVersion ?? 1) < 17 || entry.fingerprint !== foldFingerprint;
 					folds.push({
 						id: entry.id,
 						...entry.cwd === void 0 ? {} : { cwd: entry.cwd },
@@ -6409,10 +6412,12 @@ async function queryRelayQuotas(ctx, routes) {
 /**
 * usage-stats 工具开关的共享设置契约（node 与 client 两端共用）。
 *
-* 宿主把已注册的设置命名空间服务给浏览器；node 半区在 apply 阶段读一次该值决定
-* 是否向模型注入 `usage_stats` 工具（工具注入是启动期决策，改开关后重载应用生效），
-* client 半区在「设置」Tab 渲染开关并写入同一命名空间。缺省的默认行为是关闭——
-* 避免该工具默认占用模型每次请求的上下文（coding 场景通常在仪表盘看用量）。
+* 旧宿主（≤0.1.6）把该开关存设置命名空间；宿主 0.1.7+ 起注册面移除，改存插件
+* 条目 config 的 volatile 字段（Config schema 投影），写回经 settings.update，
+* 提交后引用原位更新、`usage_stats` 工具即时注册/注销（无需重载应用）。
+* client 半区在「设置」Tab 渲染开关并经 /api/billing/usage-tool 写入，node 半区
+* 按宿主世代选择通道。缺省的默认行为是关闭——避免该工具默认占用模型每次请求
+* 的上下文（coding 场景通常在仪表盘看用量）。
 */
 /** 设置命名空间 id（小写 kebab-case）。 */
 const BILLING_SETTINGS_NAMESPACE = "ui-usage-billing";
@@ -6523,6 +6528,13 @@ function validateSettingsNamespace(value) {
 const usageBillingSettingsNs = validateSettingsNamespace(BILLING_SETTINGS_NAMESPACE);
 /** 该命名空间的 wire schema：`enableUsageStatsTool` 布尔，默认关闭（issue 诉求）。 */
 const UsageBillingSettingsSchema = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z.boolean().default(false) });
+/**
+* Loader 挂载时对条目 config 做校验的 Config 声明：`enableUsageStatsTool` 标记
+* volatile，宿主 0.1.7+ 设置系统据此把它投影为可实时编辑的开关（describe/update）。
+* schemastery 非严格 object 透传未声明键，其余 config 字段不受影响；未导出 Config
+* 的旧宿主直接把原始 config 交给 apply，普通布尔形态由读取端兼容。
+*/
+const Config = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z.boolean().default(false).volatile() });
 /** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
 const PRICING_REFRESH_INTERVAL_MS = 216e5;
 /** 历史回放预热的延迟：等宿主启动高峰（插件加载 / 路由挂载）过去再全量折叠，
@@ -6872,6 +6884,22 @@ function adaptSessionPersistence(raw) {
 	};
 }
 /**
+* 读取 usage_stats 工具开关的当前生效值：宿主 0.1.7+ 经 Config 解析后是 volatile
+* 引用（.get() 即时反映设置写入，无需重载），直连 apply（测试）与未导出 Config 的
+* 旧宿主组合是普通布尔；缺省/非法值一律回 DEFAULT。
+* @param config - apply 收到的插件 config。
+* @returns 开关当前生效值。
+*/
+function readUsageStatsToggle(config) {
+	const field = config[ENABLE_USAGE_STATS_TOOL_FIELD];
+	if (typeof field === "boolean") return field;
+	if (typeof field === "object" && field !== null && typeof field.get === "function") {
+		const current = field.get();
+		return typeof current === "boolean" ? current : false;
+	}
+	return false;
+}
+/**
 * Host plugin body: serve real aggregated usage to the browser dashboard.
 * @param ctx - host context carrying webServer and sessionPersistence.
 * @param config - optional statsPath override.
@@ -6879,6 +6907,7 @@ function adaptSessionPersistence(raw) {
 function apply(ctx, config = {}) {
 	const trustedHosts = normalizeTrustedHosts(config.trustedHosts);
 	let usageSettingsScope;
+	let liveSettings;
 	const cwd = process.cwd();
 	const dshHome = resolveDshHome();
 	const snapshotPath = config.snapshotPath ?? join(dshHome, ".dsh-usage-stats.json");
@@ -7023,131 +7052,113 @@ function apply(ctx, config = {}) {
 			}
 		}
 	}), "usage-billing: notify-claim route");
-	ctx.inject(["settings"], (sctx) => {
-		const legacy = sctx.settings;
-		if (typeof legacy.register !== "function") return;
-		const scope = legacy.register(usageBillingSettingsNs, UsageBillingSettingsSchema, { base: { enableUsageStatsTool: config.enableUsageStatsTool ?? false } });
-		usageSettingsScope = scope;
-		ctx.inject(["tools"], (toolsCtx) => {
-			if (scope.get().enableUsageStatsTool) toolsCtx.tools.register(defineTool({
-				name: "usage_stats",
-				description: "查询本机 DeepSeek Harness 的模型用量与估算费用（人民币，按官方目录价估算，非账单）。range 取值：today=今天，month=本月，session=当前会话，all=累计。",
-				parameters: { range: {
-					type: "string",
-					enum: [
-						"today",
-						"month",
-						"session",
-						"all",
-						"bySite",
-						"relay"
-					],
-					required: true,
-					description: "统计范围：today / month / session / all / bySite / relay"
-				} },
-				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 === "bySite" || args.range === "relay") return {
-						range: args.range,
-						...sumSiteBuckets(stats.bySite ?? {}, args.range)
-					};
-					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;
+	let usageToolDisposer;
+	let usageToolRegister;
+	const syncUsageTool = () => {
+		if (usageToolRegister === void 0) return;
+		if (readUsageStatsToggle(config)) {
+			if (usageToolDisposer === void 0) usageToolDisposer = usageToolRegister();
+			return;
+		}
+		if (usageToolDisposer !== void 0) {
+			usageToolDisposer();
+			usageToolDisposer = void 0;
+		}
+	};
+	ctx.inject(["tools"], (toolsCtx) => {
+		usageToolRegister = () => toolsCtx.tools.register(defineTool({
+			name: "usage_stats",
+			description: "查询本机 DeepSeek Harness 的模型用量与估算费用（人民币，按官方目录价估算，非账单）。range 取值：today=今天，month=本月，session=当前会话，all=累计。",
+			parameters: { range: {
+				type: "string",
+				enum: [
+					"today",
+					"month",
+					"session",
+					"all",
+					"bySite",
+					"relay"
+				],
+				required: true,
+				description: "统计范围：today / month / session / all / bySite / relay"
+			} },
+			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"
 						}
-						return {
-							range: args.range,
-							cost,
-							calls,
-							input,
-							output
-						};
 					}
-					const sessionId = exec.agent?.id;
-					if (sessionId === void 0) throw new Error("usage_stats 的 session 范围需要 agent 会话上下文");
-					const summary = await aggregator.sessionUsageOf(String(sessionId));
-					if (summary !== void 0) return {
+				},
+				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 === "bySite" || args.range === "relay") return {
+					range: args.range,
+					...sumSiteBuckets(stats.bySite ?? {}, args.range)
+				};
+				if (args.range === "today") {
+					const day = stats.byDay[dayStamp(Date.now())];
+					return day === void 0 ? zero : {
 						range: args.range,
-						...summary
+						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 turn of stats.byTurn ?? []) {
-						if (turn.sessionId !== String(sessionId)) continue;
-						cost += turn.cost;
-						calls += 1;
-						input += turn.input;
-						output += turn.output;
+					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,
@@ -7157,8 +7168,48 @@ function apply(ctx, config = {}) {
 						output
 					};
 				}
-			}));
-		});
+				const sessionId = exec.agent?.id;
+				if (sessionId === void 0) throw new Error("usage_stats 的 session 范围需要 agent 会话上下文");
+				const summary = await aggregator.sessionUsageOf(String(sessionId));
+				if (summary !== void 0) return {
+					range: args.range,
+					...summary
+				};
+				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
+				};
+			}
+		}));
+		syncUsageTool();
+		ctx.on("loader/volatile-update", syncUsageTool);
+	});
+	ctx.inject(["settings"], (sctx) => {
+		const legacy = sctx.settings;
+		if (typeof legacy.register === "function") {
+			usageSettingsScope = legacy.register(usageBillingSettingsNs, UsageBillingSettingsSchema, { base: { enableUsageStatsTool: readUsageStatsToggle(config) } });
+			return;
+		}
+		const forms = legacy;
+		if (typeof forms.update !== "function") return;
+		liveSettings = {
+			update: (ns, patch) => forms.update(ns, patch),
+			ns: ctx.fiber.entry?.options.id ?? usageBillingSettingsNs
+		};
 	});
 	let live = { source: "builtin" };
 	let pricingSyncedAt = 0;
@@ -7301,7 +7352,7 @@ function apply(ctx, config = {}) {
 				return;
 			}
 			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			const enabled = usageSettingsScope?.get().enableUsageStatsTool ?? false;
+			const enabled = usageSettingsScope !== void 0 ? usageSettingsScope.get().enableUsageStatsTool : readUsageStatsToggle(config);
 			if (req.method === "GET") {
 				res.end(JSON.stringify({ enabled }));
 				return;
@@ -7325,18 +7376,23 @@ function apply(ctx, config = {}) {
 						return;
 					}
 				}
-				const parsed = JSON.parse(body === "" ? "{}" : body);
-				if (usageSettingsScope === void 0) {
+				const next = JSON.parse(body === "" ? "{}" : body).enabled === true;
+				if (usageSettingsScope !== void 0) {
+					await usageSettingsScope.update({ enableUsageStatsTool: next });
+					syncUsageTool();
+				} else if (liveSettings !== void 0) {
+					await liveSettings.update(liveSettings.ns, { [ENABLE_USAGE_STATS_TOOL_FIELD]: next });
+					syncUsageTool();
+				} else {
 					res.end(JSON.stringify({ error: "settings unavailable" }));
 					return;
 				}
-				const next = parsed.enabled === true;
-				await usageSettingsScope.update({ enableUsageStatsTool: next });
 				res.end(JSON.stringify({
 					ok: true,
 					enabled: next
 				}));
-			} catch {
+			} catch (error) {
+				console.warn("[usage-billing] usage-tool toggle write-back failed:", error);
 				res.end(JSON.stringify({ error: "invalid" }));
 			}
 		}
@@ -7476,4 +7532,4 @@ function apply(ctx, config = {}) {
 	}), "usage-billing: usage-stats route");
 }
 //#endregion
-export { adaptSessionPersistence, apply, createFileUsageLedgerStore, guardLoopback, inject, normalizeTrustedHosts, readPiAiProviderRoutes, resolveSubscriptionKeys };
+export { Config, adaptSessionPersistence, apply, createFileUsageLedgerStore, guardLoopback, inject, normalizeTrustedHosts, readPiAiProviderRoutes, resolveSubscriptionKeys };

package/lib/types/aggregate.d.ts

@@ -174,8 +174,10 @@ export declare function emptyUsage(): ModelUsage;
  * @param pricedCost - 调用方预算好的本次费用（同一条消息折叠进多个桶时计价结果相同，
  *   逐桶重算会让最热路径付出 N 倍常数）；提供时跳过内部的计价闸门与计算，
  *   调用方保证其已按 `!subscription && isPriced(key)` 判定。
+ * @param unverifiedChannel - 本次调用是否来自未知通道（配置外 provider）。未知通道的
+ *   支出主体无法核实，费用一律记 0（token 照常统计，issue #82）。
  */
-export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean, timeMs: number, official?: boolean, pricedCost?: number): void;
+export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean, timeMs: number, official?: boolean, pricedCost?: number, unverifiedChannel?: boolean): void;
 /**
  * 联网搜索辅助请求的单次费用估算默认值（人民币元）。DeepSeek 官方对搜索请求
  * （web_search 服务端工具注入上下文）照常计费，实测每次约 0.01~0.03 元，取中值；
@@ -552,7 +554,7 @@ export interface UsageLedgerDocument {
  * 会话费用只剩最近一段，issue #29）。
  * 持久账本行据此区分新旧算法：日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
  */
-export declare const FOLD_VERSION = 16;
+export declare const FOLD_VERSION = 17;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并

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

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'staleLedgerNotice' | 'unreadableNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption';
+export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'unknownChannelHint' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'staleLedgerNotice' | 'unreadableNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/client/usage-billing-settings.d.ts

@@ -1,10 +1,12 @@
 /**
  * usage-stats 工具开关的共享设置契约（node 与 client 两端共用）。
  *
- * 宿主把已注册的设置命名空间服务给浏览器；node 半区在 apply 阶段读一次该值决定
- * 是否向模型注入 `usage_stats` 工具（工具注入是启动期决策，改开关后重载应用生效），
- * client 半区在「设置」Tab 渲染开关并写入同一命名空间。缺省的默认行为是关闭——
- * 避免该工具默认占用模型每次请求的上下文（coding 场景通常在仪表盘看用量）。
+ * 旧宿主（≤0.1.6）把该开关存设置命名空间；宿主 0.1.7+ 起注册面移除，改存插件
+ * 条目 config 的 volatile 字段（Config schema 投影），写回经 settings.update，
+ * 提交后引用原位更新、`usage_stats` 工具即时注册/注销（无需重载应用）。
+ * client 半区在「设置」Tab 渲染开关并经 /api/billing/usage-tool 写入，node 半区
+ * 按宿主世代选择通道。缺省的默认行为是关闭——避免该工具默认占用模型每次请求
+ * 的上下文（coding 场景通常在仪表盘看用量）。
  */
 import type { CostCurrency, UserPriceEntry } from './pricing.ts';
 /** 设置命名空间 id（小写 kebab-case）。 */

package/lib/types/index.d.ts

@@ -15,6 +15,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import z from '@deepseek-ai/schemastery';
 import { type UsageLedgerStore, type UsagePersistence } from './aggregate.ts';
 import type { CustomBalanceConfig, DeclaredEndpointConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
@@ -42,6 +43,23 @@ export declare function normalizeTrustedHosts(hosts: readonly string[] | undefin
  * @returns 是否放行；false = 已拒绝并结束响应。
  */
 export declare function guardLoopback(req: IncomingMessage, res: ServerResponse, trustedHosts?: ReadonlySet<string>): boolean;
+/** 宿主 0.1.7+ 经 Config schema 解析后，volatile 字段在 config 中的稳定引用形态
+ *  （cosmokit `Volatile<T>` 的最小结构镜像，避免为类型引入直接依赖）。 */
+export interface VolatileToggle {
+    /** @returns 当前生效的布尔快照（设置写入后原位更新，无需重载插件）。 */
+    get(): boolean;
+}
+/**
+ * Loader 挂载时对条目 config 做校验的 Config 声明：`enableUsageStatsTool` 标记
+ * volatile，宿主 0.1.7+ 设置系统据此把它投影为可实时编辑的开关（describe/update）。
+ * schemastery 非严格 object 透传未声明键，其余 config 字段不受影响；未导出 Config
+ * 的旧宿主直接把原始 config 交给 apply，普通布尔形态由读取端兼容。
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enableUsageStatsTool: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enableUsageStatsTool: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
 /** Plugin configuration. */
 export interface UsageBillingConfig {
     /** Absolute path to a `.dsh-usage-stats.json` fallback file. */
@@ -83,9 +101,10 @@ export interface UsageBillingConfig {
      * 例：`['llm.example.com']`。
      */
     trustedHosts?: string[];
-    /** `usage_stats` 工具注入的组合 base（默认 false：不注入）；与设置命名空间同字段，
-     *  作为用户设置（设置 Tab 开关）的组合兜底。该工具占用每次请求的上下文，coding 场景多在仪表盘查看。 */
-    enableUsageStatsTool?: boolean;
+    /** `usage_stats` 工具注入开关（默认 false：不注入）。宿主 0.1.7+ 经 Config
+     *  解析后是 volatile 引用（设置写入即时反映），直连 apply（测试）是普通布尔；
+     *  读取统一走 readUsageStatsToggle。该工具占用每次请求的上下文，coding 场景多在仪表盘查看。 */
+    enableUsageStatsTool?: boolean | VolatileToggle;
     /**
      * 联网搜索请求（`web/deepseek-search-llm-request`，日志只有请求、无用量事件）
      * 的单次费用估算（人民币元）。这类调用直连官方 api.deepseek.com，开放平台照常

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": "1.4.18",
+  "version": "1.4.20",
   "keywords": [
     "deepseek-harness",
     "deepseek",
@@ -119,7 +119,7 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "*",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
     "@deepseek-ai/dsh-api-gateway": "0.1.7-rc.1",
     "@deepseek-ai/dsh-api-remotes": "0.1.7-rc.1",
     "@deepseek-ai/dsh-api-session-controller": "0.1.7-rc.1",
@@ -149,7 +149,7 @@
     "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.1",
     "@deepseek-ai/dsh-user-approval": "0.1.7-rc.1",
     "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "@shikijs/langs": "^4.3.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.1.0",