@kenz1117/dsh-ui-usage-billing 1.2.7 → 1.2.8

package/lib/index.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { mkdir, readFile, stat } from "node:fs/promises";
+import { lstat, mkdir, readFile, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { SessionLogOffset } from "@deepseek-ai/dsh-session/types";
@@ -305,7 +305,7 @@ function tierAt(timeMs) {
 }
 /** 时刻是否落在北京时间周末（周六/周日）。 */
 function isBeijingWeekend(timeMs) {
-	const day = new Date(timeMs + 288e5).getUTCDay();
+	const day = new Date(timeMs + 8 * 36e5).getUTCDay();
 	return day === 0 || day === 6;
 }
 /**
@@ -3062,8 +3062,8 @@ function createUsageAggregator(persistence, options = {}) {
 		};
 		const toModelDayRecord = (map) => Object.fromEntries([...map].map(([day, models]) => [day, Object.fromEntries(models)]));
 		const toModelDaySiteRecord = (map) => Object.fromEntries([...map].map(([day, models]) => [day, Object.fromEntries([...models].map(([model, sites]) => [model, Object.fromEntries(sites)]))]));
-		const modelKeys = /* @__PURE__ */ new Set([...perfModel.keys(), ...perfModelDigest.keys()]);
-		const hourKeys = /* @__PURE__ */ new Set([...perfHourModel.keys(), ...perfHourDigest.keys()]);
+		const modelKeys = new Set([...perfModel.keys(), ...perfModelDigest.keys()]);
+		const hourKeys = new Set([...perfHourModel.keys(), ...perfHourDigest.keys()]);
 		const perf = modelKeys.size === 0 && hourKeys.size === 0 ? void 0 : {
 			byModel: Object.fromEntries([...modelKeys].map((model) => {
 				const live = perfModel.get(model);
@@ -3074,7 +3074,7 @@ function createUsageAggregator(persistence, options = {}) {
 			byHourModel: Object.fromEntries([...hourKeys].sort().map((hour) => {
 				const liveModels = perfHourModel.get(hour);
 				const digestModels = perfHourDigest.get(hour);
-				const modelKeysInHour = /* @__PURE__ */ new Set([...liveModels?.keys() ?? [], ...digestModels?.keys() ?? []]);
+				const modelKeysInHour = new Set([...liveModels?.keys() ?? [], ...digestModels?.keys() ?? []]);
 				return [hour, Object.fromEntries([...modelKeysInHour].map((model) => {
 					const live = liveModels?.get(model);
 					const restored = digestModels?.get(model);
@@ -3277,11 +3277,7 @@ function tc3Authorization(secretId, secretKey, payload, timestamp) {
 	const canonicalRequest = `POST\n/\n\n${`content-type:application/json; charset=utf-8\nhost:${TOKENHUB_HOST}\n`}\ncontent-type;host\n${createHash("sha256").update(payload).digest("hex")}`;
 	const hashedCanonical = createHash("sha256").update(canonicalRequest).digest("hex");
 	const stringToSign = `TC3-HMAC-SHA256\n${String(timestamp)}\n${date}/${TOKENHUB_SERVICE}/tc3_request\n${hashedCanonical}`;
-	const kDate = createHmac("sha256", date).update(secretKey).digest();
-	const kService = createHmac("sha256", kDate).update(TOKENHUB_SERVICE).digest();
-	const kSigning = createHmac("sha256", kService).update("tc3_request").digest();
-	const signature = createHmac("sha256", kSigning).update(stringToSign).digest("hex");
-	return `TC3-HMAC-SHA256 Credential=${secretId}/${date}/${TOKENHUB_SERVICE}/tc3_request, SignedHeaders=content-type;host, Signature=${signature}`;
+	return `TC3-HMAC-SHA256 Credential=${secretId}/${date}/${TOKENHUB_SERVICE}/tc3_request, SignedHeaders=content-type;host, Signature=${createHmac("sha256", createHmac("sha256", createHmac("sha256", createHmac("sha256", date).update(secretKey).digest()).update(TOKENHUB_SERVICE).digest()).update("tc3_request").digest()).update(stringToSign).digest("hex")}`;
 }
 /**
 * 调用一次 TokenHub 管控面接口：TC3 签名 + 超时保护，返回响应 JSON 的 `Response`。
@@ -4045,7 +4041,7 @@ const declaredGate = createCooldownGate({
 	cooldownMs: 6e4
 });
 /** 会触及原型链的路径段：一律拒绝（读结果不是文档自带字段）。 */
-const FORBIDDEN_SEGMENTS = /* @__PURE__ */ new Set([
+const FORBIDDEN_SEGMENTS = new Set([
 	"__proto__",
 	"constructor",
 	"prototype"
@@ -4595,7 +4591,7 @@ function asPrice(value) {
 */
 function buildExtraModels(data) {
 	if (data === null || typeof data !== "object") return [];
-	const catalogKeys = /* @__PURE__ */ new Set([...MODEL_CATALOG.map((entry) => entry.key.toLowerCase()), ...Object.keys(MODEL_KEY_ALIASES).map((key) => MODEL_KEY_ALIASES[key]?.toLowerCase() ?? key.toLowerCase())]);
+	const catalogKeys = new Set([...MODEL_CATALOG.map((entry) => entry.key.toLowerCase()), ...Object.keys(MODEL_KEY_ALIASES).map((key) => MODEL_KEY_ALIASES[key]?.toLowerCase() ?? key.toLowerCase())]);
 	const extras = [];
 	for (const [providerId, providerDoc] of Object.entries(data)) {
 		if (providerDoc === null || typeof providerDoc !== "object") continue;
@@ -5315,7 +5311,7 @@ const relayGate = createCooldownGate({
 /** Abort a relay fetch when the upstream hangs beyond this budget. */
 const FETCH_TIMEOUT_MS = 8e3;
 /** 指纹识别缓存 TTL（毫秒）：识别结果低频变化，5 分钟内同 origin 不再重复探测。 */
-const FINGERPRINT_TTL_MS = 3e5;
+const FINGERPRINT_TTL_MS = 300 * 1e3;
 /** 每 origin 的识别结果缓存：`kind` 是识别出的中转站程序，`at` 是探测时刻。 */
 const fingerprintCache = /* @__PURE__ */ new Map();
 /** Number, or null when the value is not a finite number (nor numeric string). */
@@ -5451,7 +5447,7 @@ function originOf(baseURL) {
 * 子路径只会得到 404/非中转站格式，因而面板应排除它们，避免误判为
 * 「未识别」。中转站面板只列真正的第三方中转程序。
 */
-const OFFICIAL_HOSTS = /* @__PURE__ */ new Set([
+const OFFICIAL_HOSTS = new Set([
 	"api.deepseek.com",
 	"api.openai.com",
 	"open.bigmodel.cn",
@@ -5704,10 +5700,10 @@ const usageBillingSettingsNs = validateSettingsNamespace(BILLING_SETTINGS_NAMESP
 /** 该命名空间的 wire schema：`enableUsageStatsTool` 布尔，默认关闭（issue 诉求）。 */
 const UsageBillingSettingsSchema = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z.boolean().default(false) });
 /** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
-const PRICING_REFRESH_INTERVAL_MS = 216e5;
+const PRICING_REFRESH_INTERVAL_MS = 360 * 60 * 1e3;
 /** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
-const SUBSCRIPTION_CACHE_MS = 3e5;
-const BALANCE_CACHE_MS = 3e5;
+const SUBSCRIPTION_CACHE_MS = 300 * 1e3;
+const BALANCE_CACHE_MS = 300 * 1e3;
 /** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
 const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 /**
@@ -5724,7 +5720,7 @@ const SNAPSHOT_INTERVAL_MS = 3e5;
 *  轻量用户暖缓存下的聚合是毫秒级，预算几乎不会触发。 */
 const RESPONSE_BUDGET_MS = 1500;
 /** 鉴权失败告警冷却（毫秒）：同一 provider 在窗口内只提示一次，避免 30 秒轮询刷屏。 */
-const AUTH_WARN_COOLDOWN_MS = 18e5;
+const AUTH_WARN_COOLDOWN_MS = 1800 * 1e3;
 /**
 * 鉴权失败分类告警（P1-5）：余额 / 订阅查询返回 unauthorized 时，按
 * `source:provider` 去重并冷却告警，提示检查 llm-pi-ai 里该 provider 的 apiKeyEnv。
@@ -5738,6 +5734,32 @@ function warnAuthOnce(source, provider, displayName) {
 	authWarnedAt.set(key, now);
 	console.warn(`[usage-billing] ${displayName}（${provider}）鉴权失败：请检查 llm-pi-ai 设置中该 provider 的凭据环境变量是否正确/有效。`);
 }
+/** 锁等待上限：账本提交是毫秒级 read-render-commit，2s 已数倍于正常持锁时长。 */
+const LEDGER_LOCK_WAIT_MS = 2e3;
+/**
+* 锁年龄超过该值判为崩溃残留的孤儿锁。正常持锁是毫秒级文件提交，没有活跃
+* writer 会合法持有 60s；库层刻意不做年龄判定（它无法假设调用方的操作时长），
+* 本调用方知道自己操作的上界，可以给出有依据的清理阈值。
+*/
+const STALE_LEDGER_LOCK_MS = 6e4;
+/**
+* 锁等待超时后的孤儿锁自愈（issue #48）：仅当锁文件年龄超过
+* STALE_LEDGER_LOCK_MS 才清理，避免误删慢 writer 的活跃锁。
+* @param ledgerPath - 账本文件路径（锁为其 `.lock` 兄弟文件）。
+* @returns 是否清理了孤儿锁；false = 锁已消失或太新鲜，调用方上抛原错误。
+*/
+async function reclaimStaleLedgerLock(ledgerPath) {
+	let ageMs;
+	try {
+		ageMs = Date.now() - (await lstat(`${ledgerPath}.lock`)).mtimeMs;
+	} catch {
+		return false;
+	}
+	if (ageMs < STALE_LEDGER_LOCK_MS) return false;
+	console.warn(`[usage-billing] 账本锁已存在 ${Math.round(ageMs / 1e3)}s（崩溃残留），清理后重试：${ledgerPath}.lock`);
+	await rm(`${ledgerPath}.lock`, { force: true });
+	return true;
+}
 /**
 * Create the atomic file-backed durable-ledger store. The previous complete file
 * is retained as `.bak`; a malformed/missing main file falls back to that backup.
@@ -5758,7 +5780,7 @@ function createFileUsageLedgerStore(ledgerPath) {
 				recursive: true,
 				mode: 448
 			});
-			await withFileLock(ledgerPath, async () => {
+			const commit = async () => {
 				try {
 					const existing = await readFile(ledgerPath, "utf8");
 					JSON.parse(existing);
@@ -5771,7 +5793,14 @@ function createFileUsageLedgerStore(ledgerPath) {
 					mode: 384,
 					dirMode: 448
 				});
-			});
+			};
+			try {
+				await withFileLock(ledgerPath, commit, { waitMs: LEDGER_LOCK_WAIT_MS });
+			} catch (error) {
+				if (!(error instanceof Error) || !error.message.includes("timed out waiting for the writer lock")) throw error;
+				if (!await reclaimStaleLedgerLock(ledgerPath)) throw error;
+				await withFileLock(ledgerPath, commit, { waitMs: LEDGER_LOCK_WAIT_MS });
+			}
 		}
 	};
 }
@@ -6012,8 +6041,7 @@ function apply(ctx, config = {}) {
 	})();
 	const persistReconcileRef = () => {
 		if (reconcileRef === null) return;
-		const payload = JSON.stringify({ ref: reconcileRef });
-		writeFileAtomic(reconcilePath, payload, {
+		writeFileAtomic(reconcilePath, JSON.stringify({ ref: reconcileRef }), {
 			mode: 384,
 			dirMode: 448
 		}).catch(() => {});

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

@@ -16,6 +16,8 @@
 import type { UsageBillingKey } from './locales.ts';
 import type { TrendSeriesModel } from './TrendChart.tsx';
 import type { UsageStats } from './UsageBilling.tsx';
+/** 短数字刻度：`1.2M` / `3.4K`。导出供概览 KPI 峰值日卡复用。 */
+export declare function shortNumber(v: number): string;
 /** 每日 token 堆叠图元（按结构视角）。 */
 interface DailyBucket {
     date: string;

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

@@ -62,6 +62,13 @@ export declare const PROVIDER_ALIASES: Readonly<Record<string, readonly string[]
 export declare function providerFromModelKey(modelKey: string): string | undefined;
 /** 仅供测试：暴露厂商映射表（subscriptionVendorOf 仍是唯一消费入口）。 */
 export declare const SUBSCRIPTION_VENDORS_FOR_TEST: Readonly<Record<string, string>>;
+/**
+ * 余额 provider → 官方充值页 URL。匹配顺序：归一化名精确/前缀命中 →
+ * 经 PROVIDER_ALIASES 反查（余额 provider 名多为中文显示名，归一化仍是中文，
+ * 需先命中 display 名再用其英文别名重试）。未收录返回 undefined。
+ * 导出供测试：纯函数，不依赖组件。
+ */
+export declare function rechargeUrlOf(provider: string): string | undefined;
 /**
  * 本月预计总花费：按本月已有记录的平均日消耗 × 本月天数外推；无本月记录时
  * 回退为最近 7 天日均 × 本月天数；无任何记录时返回 0（调用方不展示）。
@@ -125,6 +132,38 @@ export declare function lastSevenDays(byDay: Record<string, {
  * @returns 本周一到今天的合计；`today` 本身不在表里（无调用）时为 0。
  */
 export declare function sinceMondayOf<T>(byDay: Record<string, T>, today: string, pick?: (row: T) => number): number;
+/** 平均成本的统计范围（issue #47）；`all` = 全量累计，不进逐日求和。 */
+export type AvgCostRange = 'today' | '7d' | 'week' | 'month' | 'all';
+/** 全局 KPI 按日聚合行的最小字段（byDay 行 = ModelUsage，结构兼容）。 */
+interface KpiDayRow {
+    cost: number;
+    calls: number;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    reasoning?: number;
+}
+/** 全局 KPI 聚合结果：KPI 七卡按所选范围重算所需的全部字段。 */
+export interface KpiAgg {
+    cost: number;
+    calls: number;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    reasoning: number;
+    /** 范围内总处理 Token（缓存读+缓存写+输出）最大的日期戳；窗口无数据时 undefined。 */
+    peakDay: string | undefined;
+    /** 峰值日的总处理 Token 量；窗口无数据时 0。 */
+    peakTokens: number;
+}
+/**
+ * 按范围聚合 byDay（issue #47）：今日 / 近 7 天（含今天）/ 本周（周一起）/
+ * 本月。日期戳字典序即时间序（与 dailyBurnRate 同口径）；累计口径由调用方
+ * 直接取 total（含搜索估值兜底），不走此函数。
+ */
+export declare function sumByDayRange(byDay: Record<string, KpiDayRow>, today: string, range: Exclude<AvgCostRange, 'all'>): KpiAgg;
 /** 会话明细行（与服务端 SessionUsageRow 同形；旧快照可能缺失整个 bySession）。 */
 interface SessionBillingRow {
     id: string;

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' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'trendEmpty' | 'budget' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | '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' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'triggerMonthTokens' | 'subscriptionsStale' | 'staleLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionIncluded' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapMonth' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenCacheHitRate' | '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';
+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' | 'trendEmpty' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | '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' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | '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' | 'heatmapMonth' | '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';
 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

@@ -30,7 +30,7 @@ export interface FloatWindowPrefs {
     /** `subscription` 模式下可切换展示的订阅通道 provider id 列表（每次显示一张）。 */
     targets: string[];
 }
-/** 默认浮窗偏好：综合模式、无指定目标（向后兼容现有综合速览卡）。 */
+/** 默认浮窗偏好：综合模式、无指定目标。 */
 export declare const DEFAULT_FLOAT_WINDOW_PREFS: FloatWindowPrefs;
 /** localStorage key（与 budget store 的 `dsh.ui-usage-billing.*` 命名空间一致）。 */
 export declare const FLOAT_WINDOW_STORAGE_KEY = "dsh.ui-usage-billing.float";
@@ -41,15 +41,19 @@ export declare function loadFloatWindowPrefs(): FloatWindowPrefs;
 export declare function saveFloatWindowPrefs(prefs: FloatWindowPrefs): void;
 /** 左下角计费卡的主指标视角。 */
 export type BillingCardMetric = 'money' | 'tokens';
+/** 计费卡主数字的统计范围（单值卡面，issue #47 反馈）。 */
+export type BillingCardSpan = 'day' | 'week' | 'month';
 /**
- * 计费卡显示偏好：卡面主行/副行与迷你柱的计价视角。
+ * 计费卡显示偏好：卡面主数字与迷你柱的计价视角 + 主数字统计范围。
  * 纯 client 偏好，存 localStorage（不依赖 node 半区接口/设置 schema）。
  */
 export interface BillingCardPrefs {
     /** 主指标：花费金额（CNY/USD 按币种）/ Token 消耗。 */
     metric: BillingCardMetric;
+    /** 主数字统计范围：今日 / 本周 / 本月（默认今日）。 */
+    span: BillingCardSpan;
 }
-/** 默认计费卡偏好：花费金额（向后兼容现有金额视图）。 */
+/** 默认计费卡偏好：花费金额 + 今日口径。 */
 export declare const DEFAULT_BILLING_CARD_PREFS: BillingCardPrefs;
 /** localStorage key（与 budget store 的 `dsh.ui-usage-billing.*` 命名空间一致）。 */
 export declare const BILLING_CARD_STORAGE_KEY = "dsh.ui-usage-billing.card";
@@ -57,6 +61,14 @@ export declare const BILLING_CARD_STORAGE_KEY = "dsh.ui-usage-billing.card";
 export declare function loadBillingCardPrefs(): BillingCardPrefs;
 /** 写入计费卡偏好。失败静默（展示偏好非关键）。 */
 export declare function saveBillingCardPrefs(prefs: BillingCardPrefs): void;
+/** 概览 KPI 全局统计范围（今日/近7天/本周/本月/累计），与组件内 AvgCostRange 同构。 */
+export type KpiRangePref = 'today' | '7d' | 'week' | 'month' | 'all';
+/** localStorage key（与其他 `dsh.ui-usage-billing.*` 偏好同命名空间）。 */
+export declare const KPI_RANGE_STORAGE_KEY = "dsh.ui-usage-billing.kpi-range";
+/** 读取 KPI 全局范围偏好（损坏/越界回退「累计」）。仅在浏览器半区调用。 */
+export declare function loadKpiRange(): KpiRangePref;
+/** 写入 KPI 全局范围偏好。失败静默（展示偏好非关键）。 */
+export declare function saveKpiRange(range: KpiRangePref): void;
 /**
  * 中转站列表（中转站分布 / 中转站额度）的展示偏好（issue #17）。
  * 纯 client 偏好，存 localStorage（不依赖 node 半区接口/设置 schema）。
@@ -82,10 +94,10 @@ export declare function saveSiteListPrefs(prefs: SiteListPrefs): void;
 export interface LiveCostBarPrefs {
     /** 是否显示输入框下方的即时代费条胶囊（默认 true：保持历史行为）。 */
     show: boolean;
-    /** 胶囊位置：below = 输入框下方（默认）；above = 输入框上方；toolbar = 工具行模型选择前的内联 chip。 */
+    /** 胶囊位置：toolbar = 输入框内部工具行内联 chip（默认，issue #47）；below = 输入框下方；above = 输入框上方。 */
     position: 'below' | 'above' | 'toolbar';
 }
-/** 默认即时代费条偏好：显示在输入框下方（升级用户零感知）。 */
+/** 默认即时代费条偏好：显示在输入框内部（工具行内联 chip，issue #47 反馈「上方/下方」都打断输入视线）。 */
 export declare const DEFAULT_LIVE_COST_BAR_PREFS: LiveCostBarPrefs;
 /** localStorage key（与其他 `dsh.ui-usage-billing.*` 偏好同命名空间）。 */
 export declare const LIVE_COST_BAR_STORAGE_KEY = "dsh.ui-usage-billing.livecost";

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.2.7",
+  "version": "1.2.8",
   "keywords": [
     "deepseek-harness",
     "deepseek",