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

package/lib/types/aggregate.d.ts

@@ -27,13 +27,52 @@ export declare const DEFAULT_SUBSCRIPTION_PROVIDERS: readonly string[];
  * 调用与费用分桶展示；部署可由配置覆盖（见 {@link AggregateOptions}）。
  */
 export declare function isOfficialProvider(provider: string): boolean;
+/** 一个 provider 路由的站点视图（来自 llm-pi-ai providers 的 baseURL）。 */
+export interface ProviderRouteView {
+    /** 该路由配置的端点地址；无值 = 直连厂商（非中转站）。 */
+    baseURL?: string;
+}
+/** 站点归属分类：site=中转站（有 baseURL origin）；direct=直连；unknown=未知路由（配置已删）。 */
+export type SiteKind = 'site' | 'direct' | 'unknown';
+/** 一个 provider 路由归类后的站点引用。 */
+export interface SiteRef {
+    kind: SiteKind;
+    /** 站点归一化 origin（仅 site）。 */
+    origin?: string;
+    /** 原 provider 路由名。 */
+    provider: string;
+}
+/** 由 baseURL 归一化出站点 origin（协议 + 主机 + 端口）；解析失败回退原值。 */
+export declare function siteOriginOf(baseURL: string): string;
+/**
+ * 把一个 provider 路由归类为站点引用。判定顺序（与路由在 provider 配置里的状态一致）：
+ * - 路由存在于当前配置且配了 baseURL → 中转站 `site`（按 origin 归组，同站多 key 合并）；
+ * - 路由存在于当前配置但无 baseURL → 厂商直连 `direct`；
+ * - 路由不在当前配置里 → `unknown`（改过名 / 删除过，是「读不到」而非「直连」）。
+ * @param provider - 会话日志里的 provider 路由名（request/header 的 `config.provider`）。
+ * @param routes - 当前 provider 路由视图（来自 llm-pi-ai providers）。
+ */
+export declare function siteRefOf(provider: string, routes: Readonly<Record<string, ProviderRouteView>>): SiteRef;
+/** 站点桶的稳定 key：`site:<origin>` 与 `direct:<provider>` 分开，`unknown` 单一桶。 */
+export declare function siteBucketKey(ref: SiteRef): string;
 /** Aggregation tuning options. */
 export interface AggregateOptions {
     /** 订阅制 provider id 列表；默认 {@link DEFAULT_SUBSCRIPTION_PROVIDERS}。 */
     subscriptionProviders?: readonly string[];
     /** 官方渠道 provider id 列表；默认按 {@link isOfficialProvider} 判定（DeepSeek 官方直连）。 */
     officialProviderIds?: readonly string[];
+    /** 每会话折叠缓存的上限（默认 {@link DEFAULT_MAX_CACHE_SESSIONS}）；
+     *  超限时按最近使用先后淘汰最久未用的会话，防长期运行内存膨胀。 */
+    maxCacheSessions?: number;
+    /** 中转站归组来源：返回当前 provider 路由视图（llm-pi-ai providers 的 baseURL）。
+     *  每次聚合时调用取最新值；缺省时全部路由按「未知路由」处理（无配置发现）。 */
+    resolveRoutes?: () => Readonly<Record<string, ProviderRouteView>>;
+    /** 工作区标题解析：给定会话 cwd 返回项目显示标题；undefined = 回退到 cwd 末级目录名
+     *  （host 的 workspaceRegistry 为可选依赖，缺失时不注入，行为保持不变）。 */
+    resolveWorkspaceTitle?: (cwd: string) => string | undefined;
 }
+/** 每会话折叠缓存默认上限：超过则按 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;
@@ -96,6 +135,12 @@ export interface UsageStatsDocument {
     byTurn?: TurnUsageRow[];
     /** 工作区聚合：按 cwd 末级目录归并，按费用倒序；旧快照可能缺失。 */
     byWorkspace?: WorkspaceUsageRow[];
+    /**
+     * 中转站归组：按 provider 路由归类到站点（有 baseURL 按 origin 归组）、直连、未知路由；
+     * key 为 {@link siteBucketKey} 的稳定值（`site:<origin>` / `direct:<provider>` / `unknown`）。
+     * 旧快照可能缺失。
+     */
+    bySite?: Record<string, ModelUsage>;
     /**
      * 按角色费用归因（人民币元）：助手输出成本为实测计价；输入成本按会话内
      * 用户消息 / 工具结果的文本长度占比启发式摊分（日志无角色级 token 实测，
@@ -222,6 +267,8 @@ interface SessionFold {
     byModel: Map<string, ModelUsage>;
     byDay: Map<string, ModelUsage>;
     byDayModels: Map<string, Map<string, ModelUsage>>;
+    /** 中转站归组：按 provider 路由归类到站点/直连/未知路由（key = {@link siteBucketKey}）。 */
+    bySite: Map<string, ModelUsage>;
     /** 每个模型 key 在本会话内走订阅通道的调用数（合并时跨会话累加判定 plan）。 */
     planCalls: Map<string, number>;
     /** 每轮费用明细（按轮次号升序，不含 sessionId）；sessionId 在合并时补齐。 */
@@ -263,7 +310,7 @@ export declare function foldSession(events: readonly {
     type: string;
     time: number;
     data: never;
-}[], subscriptionProviders: ReadonlySet<string>, officialProviderIds?: ReadonlySet<string>): SessionFold;
+}[], subscriptionProviders: ReadonlySet<string>, officialProviderIds?: ReadonlySet<string>, routes?: Readonly<Record<string, ProviderRouteView>>): SessionFold;
 /**
  * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——
  * 日志没动的会话直接复用，只有写过的会话重新折叠；整份文档另有短 TTL

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,111 @@ 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;
+    }[];
+    /** 中转站归组（key = `site:<origin>` / `direct:<provider>` / `unknown`）；旧快照可能缺失。 */
+    bySite?: Record<string, {
+        calls: number;
+        input: number;
+        output: number;
+        cacheHit: number;
+        cacheMiss: number;
+        cost: number;
+        reasoning: 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' | 'billing.balanceGranted' | 'billing.balanceTopped' | 'billing.balanceDaily' | 'billing.balanceDaysLong' | 'billing.balanceDaysUnit' | 'billing.popTodayModel' | 'billing.popNoConsumption' | 'billing.popQuotaAlert' | 'billing.popRiskNone' | 'billing.popTitle' | 'billing.popDirectLead' | 'billing.popSubLead' | 'billing.popBalanceNormal' | 'billing.popBalanceLow' | 'billing.popQuotaNormal' | 'billing.popQuotaLow' | 'billing.alertBalanceLow' | 'billing.alertQuotaLow' | 'billing.panelRelay' | 'billing.relaySite' | 'billing.relayDirect' | 'billing.relayUnknown' | 'billing.panelRelayQuota' | 'billing.relayBalance' | 'billing.relayNoQuota' | 'billing.relayWindowUsed' | 'billing.relayKindNewApi' | 'billing.relayKindSub2Api' | 'billing.relayKindUnknown' | 'billing.relayCalls';
 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,11 +31,37 @@ 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[];
 /**
- * 解析订阅适配器需要的 API Key：从 llm-pi-ai 设置的 `providers.<id>.apiKeyEnv`
+ * 读取 llm-pi-ai 设置的 `providers` 字典（`<route> → { apiKeyEnv? }`）。
+ * 余额查询复用同一份来源：部署为某个 provider 配一次 key，多个 surface 共享。
+ * @param settings - the settings service (reads the llm-pi-ai namespace).
+ * @returns the providers dict; empty when the namespace is unreadable.
+ */
+/** 一个 llm-pi-ai provider 路由的读取视图：只取三块——apiKeyEnv（凭据引用）、
+ *  baseURL（中转站零配置发现的来源）、displayName（站点显示名）。 */
+export interface PiAiProviderRoute {
+    apiKeyEnv?: string;
+    baseURL?: string;
+    displayName?: string;
+}
+/** 同步读取 provider 路由的 baseURL 视图（中转站零配置发现来源）。
+ *  `settings.describe` 是同步调用，聚合器每次折叠取最新站点映射，无需缓存/过期。
+ *  注意：返回**全部可读路由**（baseURL 可选），聚合层据此区分「路由存在但无
+ *  baseURL=直连」与「路由已删除=未知路由」两种不同归属。
+ * @param settings - the settings service (reads the llm-pi-ai namespace).
+ * @returns `<route> → { baseURL? }`；命名空间不可读时返回空。
+ */
+export declare function readPiAiProviderRoutes(settings: SettingsProvider): Readonly<Record<string, {
+    baseURL?: string;
+}>>;
+/**
+  * 解析订阅适配器需要的 API Key：从 llm-pi-ai 设置的 `providers.<id>.apiKeyEnv`
  * 读引用（如 kimi-coding → KIMI_CODING_API_KEY），再经凭据 seam 解析成实际值。
  * 同时识别出用户配置了 key 的订阅套餐（供面板只显示已识别的）。
  * @param settings - the settings service (reads the llm-pi-ai namespace).

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 匹配用。 */
@@ -101,6 +103,27 @@ export interface SubscriptionQuota {
 export interface SubscriptionResponse {
     quotas: readonly SubscriptionQuota[];
 }
+/** 中转站程序类型；`unknown` = 两个端点都没读出额度。 */
+export type RelayKind = 'new-api' | 'sub2api' | 'unknown';
+/** 中转站额度的一行（`/api/billing/relay-quotas` 的一行）。 */
+export interface RelayQuota {
+    /** llm-pi-ai providers 路由名。 */
+    route: string;
+    /** 站点 origin（baseURL 归一化）。 */
+    origin: string;
+    /** 站点显示名。 */
+    displayName: string;
+    kind: RelayKind;
+    status: SubscriptionStatus;
+    /** 上游明确携带的钱包余额（不猜币种，币种由上游决定）。 */
+    balance?: number;
+    /** 解析出的滚动额度窗口（used/total 比值）。 */
+    windows?: readonly SubscriptionWindow[];
+}
+/** Response of `/api/billing/relay-quotas`. */
+export interface RelayResponse {
+    quotas: readonly RelayQuota[];
+}
 /** Config for one subscription adapter (validated in apply). */
 export interface SubscriptionPlanConfig {
     /** Adapter id: `kimi` / `zai` / `opencode-go`. */

package/lib/types/relay.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 中转站额度查询（node 半区）：识别并读取 New API 系与 Sub2API 的「余额 / 额度窗口」。
+ *
+ * 适用场景：用户把某条 llm-pi-ai provider 路由的 `baseURL` 指向第三方中转站
+ * （New API / One API / VoAPI / Sub2API 等）。这类站点不卖官方余额，卖的是
+ * 按 key 的额度（used/total）或多个滚动窗口。本模块对**配了 baseURL 且有
+ * apiKeyEnv** 的路由逐个探测两个已知端点，能解析出额度就返回；解析不出的
+ * 静默标记 unavailable，绝不臆造金额（与 balance/subscriptions 一致的姿态）。
+ *
+ * 探测顺序：先 Sub2API `/v1/usage`（标准化程度高），再 New API `/api/status`；
+ * 404 = 不是该套程序，继续试下一种；401/403 = 是但 key 不对（unauthorized）；
+ * 网络/5xx 走熔断门短路一段时间。同一站点多把 key 是独立额度，分别列出。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RelayQuota, SubscriptionWindow } from './pricing-shared.ts';
+/** 一个待探测的中转站路由（来自 llm-pi-ai providers 的 baseURL + apiKeyEnv）。 */
+export interface RelayRoute {
+    /** llm-pi-ai providers 路由名（key）。 */
+    route: string;
+    /** 该路由配置的端点地址（origin 来源）。 */
+    baseURL: string;
+    /** 该路由解析到的 apiKeyEnv 引用。 */
+    apiKeyEnv: string;
+    /** 站点显示名；缺省用路由名。 */
+    displayName?: string;
+}
+/**
+ * 解析 Sub2API `/v1/usage` 响应：能取到 balance 或 quota/used 就识别为 sub2api。
+ * 三种形态（窗口 / 分组 / 钱包余额）都宽容处理：有 `quota/total` 给出窗口，
+ * 有 `balance` 给出余额，两者可同时存在。
+ * @param data - `/v1/usage` 的 JSON 响应。
+ * @returns 解析结果；两者都取不到返回 null（不是 Sub2API 或响应漂移）。
+ */
+export declare function parseSub2ApiUsage(data: unknown): {
+    balance?: number;
+    windows?: readonly SubscriptionWindow[];
+} | null;
+/**
+ * 解析 New API `/api/status` 响应：New API 系（One API / VoAPI 分支）的额度是
+ * 按记录行的 ratio（已用比例）。只给出窗口，不猜金额（币种防猜）。
+ * @param data - `/api/status` 的 JSON 响应。
+ * @returns 窗口；取不到比例返回 null（响应漂移）。
+ */
+export declare function parseNewApiStatus(data: unknown): {
+    windows?: readonly SubscriptionWindow[];
+} | null;
+/**
+ * 查询单个中转站路由的额度。先试 Sub2API，再试 New API；任一读出额度即返回。
+ * @param ctx - host context carrying the credentials seam.
+ * @param route - 待探测的路由（baseURL + apiKeyEnv）。
+ * @returns 该路由的一行额度结果（status 标记成败）。
+ */
+export declare function queryRelayQuota(ctx: Context, route: RelayRoute): Promise<RelayQuota>;
+/**
+ * 批量查询多个中转站路由的额度（每个独立成败，互不影响）。
+ * @param ctx - host context carrying the credentials seam.
+ * @param routes - 配了 baseURL 且 apiKeyEnv 有值的路由列表。
+ * @returns 每个路由一行的额度结果。
+ */
+export declare function queryRelayQuotas(ctx: Context, routes: readonly RelayRoute[]): Promise<readonly RelayQuota[]>;
+//# sourceMappingURL=relay.d.ts.map