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

package/lib/types/aggregate.d.ts

@@ -392,6 +392,36 @@ export interface PerfSample {
     /** 无独立 request/header，以 step/start 起算（工具续写步骤）。 */
     estimated: boolean;
 }
+/**
+ * 会话级性能摘要（per model）：账本持久化形态——替代逐样本持久化，体积
+ * O(模型数) 而非 O(样本数)。计数/求和/极值精确合并；分位数（P50/P90）
+ * 在跨会话合并时按样本数加权（展示级近似）。进程内折叠的会话仍保留
+ * 完整样本（doc 生成走精确插值），仅账本恢复行以摘要参与聚合。
+ */
+export interface PerfModelDigest {
+    /** 样本数。 */
+    samples: number;
+    ttftSum: number;
+    ttftMax: number;
+    ttftSpikes: number;
+    ttftP50: number;
+    ttftP90: number;
+    /** 有可测生成速度的样本数。 */
+    tpsCount: number;
+    tpsSum: number;
+    /** 有可测总延迟的样本数。 */
+    latencyCount: number;
+    latencySum: number;
+    /** 以 step/start 估算的样本数。 */
+    estimated: number;
+}
+/** 会话级 小时×模型 性能摘要（只用均值，合并无损）。 */
+export interface PerfHourDigest {
+    samples: number;
+    ttftSum: number;
+    tpsCount: number;
+    tpsSum: number;
+}
 /** One persisted session's folded usage plus drill-down metadata. */
 export interface SessionFold {
     total: ModelUsage;
@@ -412,8 +442,13 @@ export interface SessionFold {
     planCalls: Map<string, number>;
     /** 每轮费用明细（按轮次号升序，不含 sessionId）；sessionId 在合并时补齐。 */
     turns: SessionTurnRow[];
-    /** 性能样本（有可测 TTFT 的调用，按事件次序折叠）。 */
+    /** 性能样本（有可测 TTFT 的调用，按事件次序折叠）；仅进程内折叠产生，
+     *  账本恢复行恒为空（其性能在 {@link SessionFold.perfDigest} 里）。 */
     perf: PerfSample[];
+    /** 账本恢复行的模型级性能摘要；进程内折叠恒为空（序列化时从样本构建）。 */
+    perfDigest: Map<string, PerfModelDigest>;
+    /** 账本恢复行的小时×模型性能摘要；进程内折叠恒为空。 */
+    perfHourDigest: Map<string, Map<string, PerfHourDigest>>;
     /** 角色归因中间量：消息文本长度（user/tool）与输入/输出成本实测拆分。 */
     roles: RoleFold;
     /** 日志里最新的 session/title 文本（无标题事件时 undefined）。 */
@@ -447,7 +482,11 @@ export interface SerializedSessionFold {
     unpricedModels: string[];
     planCalls: Record<string, number>;
     turns: SessionTurnRow[];
-    perf: PerfSample[];
+    /** v16 起以摘要持久化性能（体积 O(模型数) 而非 O(样本数)）；旧行的
+     *  `perf` 逐样本数组由加载边界迁移转换为摘要。 */
+    perfDigest: Record<string, PerfModelDigest>;
+    /** 小时×模型摘要（键 = {@link hourStamp}）；同上由迁移补齐。 */
+    perfHourDigest: Record<string, Record<string, PerfHourDigest>>;
     roles: RoleFold;
     lastActive: number;
 }
@@ -491,7 +530,7 @@ export interface UsageLedgerDocument {
  * 会话费用只剩最近一段，issue #29）。
  * 持久账本行据此区分新旧算法：日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
  */
-export declare const FOLD_VERSION = 15;
+export declare const FOLD_VERSION = 16;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并
@@ -505,7 +544,9 @@ export interface LedgerMigration {
 }
 /**
  * 账本迁移注册表。首条迁移给 1.0.6 及更早的行回填 foldVersion = 1（它们全部出自
- * header 归因算法）；此后新写入的行总带当前 {@link FOLD_VERSION}。
+ * header 归因算法）；perf 摘要化迁移把 v15 及更早行的逐样本 `perf` 数组转换为
+ * `perfDigest`/`perfHourDigest` 摘要（日志已删的行不再被重折，迁移是它们唯一的
+ * 收缩机会）；此后新写入的行总带当前 {@link FOLD_VERSION} 与摘要形态。
  */
 export declare const LEDGER_MIGRATIONS: readonly LedgerMigration[];
 /**
@@ -560,10 +601,25 @@ export interface UsageAggregator {
     /** Aggregate current usage, reusing cached per-session folds when their logs are untouched.
      *  并发调用共享同一次进行中的折叠（in-flight 去重），不会多倍全量重读。 */
     aggregate(): Promise<UsageStatsDocument>;
+    /**
+     * 按会话 id 取该会话的完整累计用量。doc 的 `byTurn` 封顶（最近 200 轮），
+     * 用户回到旧会话续聊时其轮次已被挤出，从 doc 反推会低估——这里直接读该
+     * 会话的缓存/账本折叠，是该会话的精确值（含联网搜索估算，口径与 total 一致）。
+     * @param sessionId - 会话 id（String(SessionId) 形态，与账本键同口径）。
+     * @returns 会话累计；日志与账本均无该会话时 undefined（调用方自行兜底）。
+     */
+    sessionUsageOf(sessionId: string): Promise<SessionUsageSummary | undefined>;
     /** 立刻落盘未保存的账本改动（无视节流），供插件卸载时调用；
      *  进行中的聚合先等完再存，折叠失败仍保存已成功部分。 */
     flush(): Promise<void>;
 }
+/** 单会话累计用量（{@link UsageAggregator.sessionUsageOf} 的返回）。 */
+export interface SessionUsageSummary {
+    calls: number;
+    cost: number;
+    input: number;
+    output: number;
+}
 /**
  * 聚合配置指纹：影响折叠语义的全部配置（订阅豁免、官方名单、路由别名、搜索估值）
  * 的稳定序列化。账本行的复用判定携带该指纹——用户改配置后（如为 grok build 加

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