@kenz1117/dsh-ui-usage-billing 0.9.6 → 0.9.7

package/lib/types/aggregate.d.ts

@@ -33,7 +33,12 @@ export interface AggregateOptions {
     subscriptionProviders?: readonly string[];
     /** 官方渠道 provider id 列表；默认按 {@link isOfficialProvider} 判定（DeepSeek 官方直连）。 */
     officialProviderIds?: readonly string[];
+    /** 每会话折叠缓存的上限（默认 {@link DEFAULT_MAX_CACHE_SESSIONS}）；
+     *  超限时按最近使用先后淘汰最久未用的会话，防长期运行内存膨胀。 */
+    maxCacheSessions?: number;
 }
+/** 每会话折叠缓存默认上限：超过则按 LRU 淘汰（P1-6 峰值内存治理）。 */
+export declare const DEFAULT_MAX_CACHE_SESSIONS = 400;
 /** One model's aggregated usage plus estimated cost in CNY. */
 export interface ModelUsage {
     calls: number;

package/lib/types/balance.d.ts

@@ -2,12 +2,11 @@
  * Account-balance queries for the billing dashboard.
  *
  * Only providers with a public balance endpoint can report one. Today that is
- * DeepSeek (`GET https://api.deepseek.com/user/balance`) and Moonshot/Kimi
- * (`GET https://api.moonshot.cn/v1/users/me/balance`), both Bearer 鉴权 with a
- * documented JSON shape; the other mainstream providers expose no standard
- * balance API (or require a non-Bearer auth flow), so their rows in the model
- * table show an unavailable state. The lookup map below is the extension point
- * for future providers.
+ * DeepSeek, Moonshot/Kimi, StepFun, SiliconFlow, and xAI (Grok) — all Bearer
+ * 鉴权 with a documented JSON shape; the other mainstream providers expose no
+ * standard balance API (or require a non-Bearer auth flow), so their rows in
+ * the model table show an unavailable state. The lookup map below is the
+ * extension point for future providers.
  *
  * API keys are read from the `llm-pi-ai` settings namespace (`providers.<id>.apiKeyEnv`),
  * the same source the subscription adapter uses, so a deployment configures a

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

@@ -0,0 +1,45 @@
+/**
+ * PerfPanel: per-model latency/perf table + per-hour TTFT/generation-speed curve.
+ *
+ * Reads the optional `perf` field of the usage-stats document (aggregated by
+ * the host from session logs). Renders a per-model table of TTFT mean/P50/P90,
+ * generation speed, total latency and estimated-step count, plus a small
+ * dependency-free SVG twin-series hourly curve (TTFT in ms on the left axis,
+ * tokens/s on the right). Absent `perf` (older snapshot or stream-less logs)
+ * renders an empty state; the panel never fabricates samples.
+ */
+import type { TrendSeriesModel } from './TrendChart.tsx';
+import type { UsageBillingKey } from './locales.ts';
+/** 每模型性能统计（与服务端 `ModelPerf` 同形）。 */
+export interface PerfModelData {
+    samples: number;
+    ttftAvg: number;
+    ttftP50: number;
+    ttftP90: number;
+    tpsAvg?: number;
+    latencyAvg: number;
+    estimatedSamples: number;
+}
+/** 每小时性能统计（与服务端 `HourPerf` 同形）。 */
+export interface PerfHourData {
+    samples: number;
+    ttftAvg: number;
+    tpsAvg?: number;
+}
+/** 性能指标文档（服务端可选 `perf` 字段；旧快照缺失）。 */
+export interface ClientPerf {
+    byModel: Record<string, PerfModelData>;
+    byHour: Record<string, PerfHourData>;
+}
+/**
+ * Render the performance panel.
+ * @param props.perf - the optional perf doc; `undefined`/empty renders an empty state.
+ * @param props.models - model legend (key/name/color) for the table swatches and curve legend.
+ * @param props.t - locale function.
+ */
+export declare function PerfPanel({ perf, models, t, }: {
+    perf: ClientPerf | undefined;
+    models: readonly TrendSeriesModel[];
+    t: (key: UsageBillingKey) => string;
+}): React.ReactNode;
+//# sourceMappingURL=PerfPanel.d.ts.map

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

@@ -0,0 +1,12 @@
+/**
+ * PluginInfoCard: 「设置 → 插件信息」卡——展示头像/作者、GitHub 仓库、版本号、
+ * 许可证等插件元信息。版本号来自服务端 usage-stats 的 `pluginVersion`（读自
+ * 包 package.json），其余元信息静态来自 `plugin-info.ts`。无版本号时显示 em dash。
+ */
+import type { UsageBillingKey } from './locales.ts';
+/** 信息卡 props：locale 函数 + 版本号（服务端下发，可为空）。 */
+export declare function PluginInfoCard({ t, version }: {
+    t: (key: UsageBillingKey) => string;
+    version: string | undefined;
+}): React.ReactNode;
+//# sourceMappingURL=PluginInfoCard.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * TokenPanel: 「Token」分区——把 token 从费用里独立出来洞察。
+ * 三个板块 + 导出，全部由 `UsageStats` 的 byDay/byModel/total 派生，服务端零改动：
+ *  1. 每日 Token 堆叠趋势（未命中输入 / 缓存命中 / 输出[含 reasoning]），7/30 天切换；
+ *  2. 模型 Token 总量排行 + 占比；
+ *  3. Token 结构 KPI（缓存命中率 / reasoning 占比 / 输入:输出比 / 峰值日）。
+ */
+import type { UsageBillingKey } from './locales.ts';
+import { type CostCurrency } from './pricing.ts';
+import type { UsageStats } from './UsageBilling.tsx';
+/**
+ * Token 洞察面板。
+ * @param props.stats - usage-stats 文档（byDay/byModel/total）。
+ * @param props.trendDays - 每日 token 窗口（7/30 天）。
+ * @param props.onTrendDays - 切换趋势窗口。
+ */
+export declare function TokenPanel(props: {
+    stats: UsageStats;
+    currency: CostCurrency;
+    trendDays: 7 | 30;
+    onTrendDays: (d: 7 | 30) => void;
+    t: (key: UsageBillingKey) => string;
+}): React.ReactNode;
+//# sourceMappingURL=TokenPanel.d.ts.map

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

@@ -11,6 +11,7 @@
  */
 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 ClientPerf } from './PerfPanel.tsx';
 import type { createBillingBudgetStore } from './budget-store.ts';
 import { type CatalogModel } from './pricing.ts';
 import { NS, type UsageBillingKey } from './locales.ts';
@@ -32,7 +33,7 @@ export interface ModelHealth {
     catalog?: readonly CatalogModel[];
 }
 /** 仪表盘分区 Tab id。 */
-export type DashboardTab = 'overview' | 'trends' | 'providers' | 'details' | 'pricing' | 'settings';
+export type DashboardTab = 'overview' | 'token' | 'trends' | 'providers' | 'pricing' | 'settings';
 /**
  * Tab 定义（顺序即渲染顺序）：概览=主数字/KPI/热力图，趋势=趋势图/每轮费用，
  * 明细=厂商计费与订阅，统计=工作区/会话明细，费率=模型单价表，设置=预算与峰谷提醒。
@@ -83,6 +84,16 @@ export declare function peakOffpeakCost(turns: readonly {
     peak: number;
     offPeak: number;
 };
+/** 近 7 天费用序列（含今天，缺日补 0）：触发卡 hover 速览的迷你柱数据源。
+ * 导出供测试：纯函数（日期取本地时区）。 */
+export declare function activeDaysOf(byDay: Record<string, {
+    cost: number;
+}>): number;
+/** 连续使用天数：从今天往前连续「有调用记录」的天数；今天无记录则为 0。
+ * 导出供测试：纯函数（日期取本地时区）。 */
+export declare function streakDaysOf(byDay: Record<string, {
+    cost: number;
+}>, now?: number): number;
 /**
  * 近 7 天费用序列（含今天，缺日补 0）：触发卡 hover 速览的迷你柱数据源。
  * 导出供测试：纯函数（日期取本地时区）。
@@ -95,6 +106,101 @@ export declare function lastSevenDays(byDay: Record<string, {
     date: string;
     cost: number;
 }[];
+/** 会话明细行（与服务端 SessionUsageRow 同形；旧快照可能缺失整个 bySession）。 */
+interface SessionBillingRow {
+    id: string;
+    title?: string;
+    cwd?: string;
+    calls: number;
+    cost: number;
+    lastActive: number;
+}
+/** Usage stats structure from `.dsh-usage-stats.json`. */
+export interface UsageStats {
+    /** 服务端聚合时间戳（毫秒）；旧快照可能缺失。 */
+    updatedAt?: number;
+    /** 月度预算（人民币元）：宿主 Config 注入；未配置时不渲染预算条。 */
+    budget?: number;
+    /** 余额不足告警阈值（人民币元）：宿主 Config 注入；未配置时客户端用默认值。 */
+    lowBalanceThreshold?: number;
+    /** 会话明细（按费用倒序，服务端已封顶）；旧快照可能缺失。 */
+    bySession?: readonly SessionBillingRow[];
+    total: {
+        calls: number;
+        input: number;
+        output: number;
+        cacheHit: number;
+        cacheMiss: number;
+        cost: number;
+        /** 输出中的 reasoning（思考）token；已含在 output 内。 */
+        reasoning: number;
+    };
+    byModel: Record<string, {
+        calls: number;
+        input: number;
+        output: number;
+        cacheHit: number;
+        cacheMiss: number;
+        cost: number;
+        reasoning: number;
+        /** Billed through a subscription plan (no per-token cost). */
+        plan?: boolean;
+        /** 走官方 DeepSeek 直连的调用数（其余为第三方）；旧快照可能缺失。 */
+        officialCalls?: number;
+        /** 走官方渠道的费用（CNY）；旧快照可能缺失。 */
+        officialCost?: number;
+    }>;
+    byDay: Record<string, {
+        calls: number;
+        input: number;
+        output: number;
+        cacheHit: number;
+        cacheMiss: number;
+        cost: number;
+        reasoning: number;
+    }>;
+    /** 模型 × 日期 二维统计（趋势图堆叠柱的输入）；旧快照可能缺失，渲染时降级为单色柱。 */
+    byDayModels?: Record<string, Record<string, {
+        calls: number;
+        input: number;
+        output: number;
+        cacheHit: number;
+        cacheMiss: number;
+        cost: number;
+    }>>;
+    /** 每轮费用明细（服务端聚合路径恒带）；旧快照可能缺失。 */
+    byTurn?: readonly {
+        sessionId: string;
+        turn: number;
+        model: string;
+        input: number;
+        output: number;
+        cacheHit: number;
+        cacheMiss: number;
+        cost: number;
+        startedAt: number;
+        endedAt?: number;
+    }[];
+    /** 工作区聚合（按 cwd 末级目录）；旧快照可能缺失。 */
+    byWorkspace?: readonly {
+        name: string;
+        calls: number;
+        cost: number;
+        input: number;
+        output: number;
+        lastActive: number;
+    }[];
+    /** 按角色费用归因（估算口径：输出实测，输入按消息长度摊分）；旧快照可能缺失。 */
+    byRole?: {
+        user: number;
+        assistant: number;
+        tool: number;
+    };
+    /** 性能指标（TTFT/生成速度/总延迟）按模型与按小时；旧快照可能缺失。 */
+    perf?: ClientPerf;
+    /** 插件版本号（服务端读自包 package.json；旧快照缺失）。 */
+    pluginVersion?: string;
+}
 /** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
 export interface UsageBillingInjected {
     checkModels: () => Promise<ModelHealth>;

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

@@ -20,16 +20,18 @@ export interface HeatmapDay {
     value: number;
 }
 /**
- * Render the month heatmap.
+ * Render the month or year heatmap.
  * @param props.days - daily cost rows (keys are `YYYY-MM-DD`).
  * @param props.currency - display currency for the hover amount.
  * @param props.now - anchor date (defaults to today); injectable for tests.
  * @param props.t - locale function (used for the legend labels).
+ * @param props.range - `month` (calendar month) or `year` (last 52 weeks, GitHub style).
  */
-export declare function UsageHeatmap({ days, currency, now, t }: {
+export declare function UsageHeatmap({ days, currency, now, t, range }: {
     days: readonly HeatmapDay[];
     currency: CostCurrency;
     now?: Date;
+    range?: 'month' | 'year';
     t: (key: 'billing.costAbbr' | 'billing.noData' | 'billing.heatmapLess' | 'billing.heatmapMore') => string;
 }): React.ReactNode;
 //# sourceMappingURL=heatmap.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.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | '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.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | '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.pricingTip' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionExhausted' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.anomaly' | 'billing.workspaces' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | '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.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | '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.pricingTip' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionExhausted' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.anomaly' | 'billing.workspaces' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost' | 'billing.perfSamples' | 'billing.perfTtft' | 'billing.perfP50' | 'billing.perfP90' | 'billing.perfTps' | 'billing.perfLatency' | 'billing.perfEstimated' | 'billing.perfEmpty' | 'billing.perfTpsUnit' | 'billing.perfTitle' | 'billing.perfHint' | 'billing.heatmapYear' | 'billing.heatmapMonth' | 'billing.activeDays' | 'billing.streakDays' | 'billing.subscriptionAutoDetect' | 'billing.pluginInfo' | 'billing.pluginName' | 'billing.pluginDescription' | 'billing.pluginVersion' | 'billing.pluginAuthor' | 'billing.pluginRepository' | 'billing.pluginNpm' | 'billing.pluginLicense' | 'billing.tabToken' | 'billing.tokenExport' | 'billing.tokenExportCsv' | 'billing.tokenCacheHitRate' | 'billing.tokenReasoningShare' | 'billing.tokenReasoningShort' | 'billing.tokenIo' | 'billing.tokenPeak' | 'billing.tokenDaily' | 'billing.tokenByModel' | 'billing.tokenMiss' | 'billing.tokenHit' | 'billing.tokenOutput' | 'billing.tokenTotal' | 'billing.tokenShare' | 'billing.usageStatsTool' | 'billing.usageStatsToolHint';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/client/plan-knowledge.d.ts

@@ -33,11 +33,17 @@ export interface PlanTier {
     /** 额度口径的人话描述（官方未公布精确额度时）。 */
     label?: string;
 }
-/** One plan row: provider id (after alias) → plan shape + optional subscription fee. */
+/** 原生币订阅月费（金额 + 币种 + 计费周期）。 */
+export interface SubscriptionMount {
+    amount: number;
+    currency: 'CNY' | 'USD';
+    period: 'month' | 'week' | 'day';
+}
+/** One plan row: provider id (after plan alias) → plan shape + optional subscription fee. */
 export interface PlanKnowledgeEntry {
     type: PlanType;
-    /** 订阅月费（人民币元）；code 计划用，计入「本月预计」。 */
-    subscriptionCny?: number;
+    /** 原生币订阅月费（如 $10/月）；code 计划用，折算后计入「本月预计」。 */
+    subscription?: SubscriptionMount;
     /** 自动识别的档位月费与周期额度口径（订阅卡片展示）。 */
     tier?: PlanTier;
 }
@@ -46,10 +52,23 @@ export interface PlanKnowledgeEntry {
  * 覆盖我们实际会识别到的订阅通道；其余按量 API 不计入此表（默认 token）。
  */
 export declare const PLAN_KNOWLEDGE: Readonly<Record<string, PlanKnowledgeEntry>>;
+/**
+ * 订阅/plan provider id 变体 → PLAN_KNOWLEDGE 规范键（引用 dsh-spend 的别名归一化）。
+ * 部署配置的订阅 provider id 写法不一（glm/zhipu/bigmodel、ark/volcengine、
+ * kimi/moonshot、xiaomi…），先归一化再匹配，提升"自动识别"覆盖率。
+ * 注意：裸 qwen/dashscope/tongyi 等是按量 API（token 计费）而非订阅，不归一到
+ * 订阅键——只有显式 token-plan 后缀才由 SUBSCRIPTION_ID_RE 判定为订阅。
+ */
+export declare const PLAN_PROVIDER_ALIASES: Readonly<Record<string, string>>;
+/** 归一化订阅 provider id：别名命中则映射到规范键，否则原样返回。 */
+export declare function normalizePlanProvider(providerId: string): string;
 /** provider id（llm-pi-ai 设置键）→ plan 知识；未命中默认 token。 */
 export declare function planTypeOf(providerId: string): PlanType;
-/** 订阅月费（人民币元）；非 code 或未配置时为 0。 */
-export declare function subscriptionCnyOf(providerId: string): number;
+/**
+ * 订阅月费折算为人民币：原生币 × 实时汇率（USD→CNY）。汇率缺失时返回 0，
+ * 避免用假设汇率造成失真（跨币种保护：金额统一折成 CNY 再相加）。
+ */
+export declare function subscriptionFeeCnyOf(providerId: string, rate: number | undefined): number;
 /** 自动识别的档位月费与周期额度口径（订阅卡片展示）；无档位知识返回 undefined。 */
 export declare function tierInfoOf(providerId: string): PlanTier | undefined;
 export interface FallbackRate {

package/lib/types/client/plugin-info.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 插件元信息（「设置 → 插件信息卡」展示）：名称 / 描述 / 作者 / 仓库 / 许可证。
+ * 版本号不含在此——由服务端从自身 package.json 读取（pluginVersion），
+ * 这样发布版版本与源码单一来源，不会两处不同步。
+ */
+/** npm 包名。 */
+export declare const PLUGIN_NAME = "@kenz1117/dsh-ui-usage-billing";
+/** 一句话描述。 */
+export declare const PLUGIN_DESCRIPTION = "Usage billing dashboard for DeepSeek Harness";
+/** 作者显示名。 */
+export declare const PLUGIN_AUTHOR_NAME = "KenZ";
+/** 作者 GitHub 账号（仓库/作者页链接）。 */
+export declare const PLUGIN_AUTHOR_HANDLE = "kenz1117";
+/** 源码仓库（可点击）。 */
+export declare const PLUGIN_REPOSITORY = "https://github.com/kenz1117/dsh-ui-usage-billing";
+/** npm 包主页（可点击）。 */
+export declare const PLUGIN_NPM_URL = "https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing";
+/** 许可证。 */
+export declare const PLUGIN_LICENSE = "MIT";
+//# sourceMappingURL=plugin-info.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * usage-stats 工具开关的共享设置契约（node 与 client 两端共用）。
+ *
+ * 宿主把已注册的设置命名空间服务给浏览器；node 半区在 apply 阶段读一次该值决定
+ * 是否向模型注入 `usage_stats` 工具（工具注入是启动期决策，改开关后重载应用生效），
+ * client 半区在「设置」Tab 渲染开关并写入同一命名空间。缺省的默认行为是关闭——
+ * 避免该工具默认占用模型每次请求的上下文（coding 场景通常在仪表盘看用量）。
+ */
+/** 设置命名空间 id（小写 kebab-case）。 */
+export declare const BILLING_SETTINGS_NAMESPACE = "ui-usage-billing";
+/** 该命名空间下用户可编辑的字段名。 */
+export declare const ENABLE_USAGE_STATS_TOOL_FIELD = "enableUsageStatsTool";
+/** 该命名空间下用户可编辑的子集。 */
+export interface UsageBillingSettings {
+    /** 是否向模型注入 `usage_stats` 动态工具（默认 false：不注入）。 */
+    enableUsageStatsTool: boolean;
+}
+/** 默认值：工具不注入（贴合 issue 诉求）。 */
+export declare const DEFAULT_ENABLE_USAGE_STATS_TOOL = false;
+//# sourceMappingURL=usage-billing-settings.d.ts.map

package/lib/types/index.d.ts

@@ -11,7 +11,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
-import type { SettingsProvider } from '@deepseek-ai/dsh-settings';
+import { type SettingsProvider } from '@deepseek-ai/dsh-settings';
 import type { CustomBalanceConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
 /** Plugin configuration. */
@@ -31,6 +31,9 @@ export interface UsageBillingConfig {
     lowBalanceThreshold?: number;
     /** 自定义 Provider 余额查询（任意 HTTP 端点 + extract 规则，适配 NewApi/LiteLLM 等）。 */
     customBalances?: readonly CustomBalanceConfig[];
+    /** `usage_stats` 工具注入的组合 base（默认 false：不注入）；与设置命名空间同字段，
+     *  作为用户设置（设置 Tab 开关）的组合兜底。该工具占用每次请求的上下文，coding 场景多在仪表盘查看。 */
+    enableUsageStatsTool?: boolean;
 }
 /** Required services: the web server, the persisted session log store, and user settings. */
 export declare const inject: string[];

package/lib/types/pricing-shared.d.ts

@@ -38,8 +38,10 @@ export interface ExtraModelPrice {
     provider: string;
     price: LivePrice;
 }
-/** 余额查询失败的原因，前端据此显示文案。 */
-export type BalanceError = 'unconfigured' | 'unauthorized' | 'unreachable';
+/** 余额查询失败的原因，前端据此显示文案。
+ *  `invalid` 表示上游返回 2xx 但响应结构偏离预期（接口改版/漂移），
+ *  与"网络不可达"（unreachable）区分，便于定位是上游变更还是网络问题。 */
+export type BalanceError = 'unconfigured' | 'unauthorized' | 'unreachable' | 'invalid';
 /** 一个提供方的账户余额（`/api/billing/balance` 的一行）。 */
 export interface ProviderBalance {
     /** 提供方 id（小写，如 `deepseek`），与模型表 provider 匹配用。 */

package/lib/types/resilience.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 上游网络请求的稳定性工具：有限重试（指数退避）与每平台熔断冷却门。
+ *
+ * 计费插件对三类上游做实时请求——pricing（汇率 / OpenRouter / models.dev）、
+ * balance（各厂商余额）、subscriptions（各订阅额度）。单次失败会被调用方降级，
+ * 但反复的瞬时失败（网络波动 / 5xx / 429）会让 30 秒轮询每次打满超时。这里提供
+ * 两个纯工具：`withRetry` 对可重试错误做指数退避，`createCooldownGate` 在单一
+ * 上游连续失败后短路一段时间，避免把请求打到已不可用的服务上。
+ */
+/** 是否是可重试的错误：网络性失败（TypeError / Abort / Timeout）或 5xx / 429。
+ *  401 / 403 鉴权失败与 404 不可重试——重试只放大错误、不会变好。 */
+export declare function isRetryableError(error: unknown): boolean;
+/** 重试配置。 */
+export interface RetryOptions {
+    /** 除首次尝试外的额外重试次数（默认 1）。 */
+    retries?: number;
+    /** 首次退避基数（默认 250ms）。 */
+    baseDelayMs?: number;
+    /** 退避上限（默认 2000ms）。 */
+    maxDelayMs?: number;
+    /** 何时重试；默认 {@link isRetryableError}。 */
+    shouldRetry?: (error: unknown) => boolean;
+}
+/**
+ * 对一次上游请求做有限重试：可重试错误时按指数退避（+同量级抖动）重试。
+ * @param fn - 发起请求的异步函数。
+ * @param options - 重试策略（见 {@link RetryOptions}）。
+ * @returns fn 的结果；重试耗尽后抛出最后一次错误。
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/** 熔断冷却门配置。 */
+export interface CooldownGateOptions {
+    /** 连续失败达到该次数进入冷却（默认 3）。 */
+    failures?: number;
+    /** 冷却时长（默认 30 秒）。 */
+    cooldownMs?: number;
+}
+/** 每平台熔断门：check 是否允许请求；fail / success 上报结果。 */
+export interface CooldownGate {
+    /** 该平台是否允许发起请求。false 表示处于冷却中，调用方应短路为不可用。 */
+    check(key: string): boolean;
+    /** 上报一次失败（可能进入冷却）。 */
+    fail(key: string): void;
+    /** 上报一次成功（重置失败计数与冷却）。 */
+    success(key: string): void;
+}
+/** 每平台冷熔断：连续失败达阈值后短路一段真实时间，成功后复位。 */
+export declare function createCooldownGate(options?: CooldownGateOptions): CooldownGate;
+//# sourceMappingURL=resilience.d.ts.map

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": "0.9.6",
+  "version": "0.9.7",
   "publishConfig": {
     "access": "public"
   },