@kenz1117/dsh-ui-usage-billing 0.2.6 → 0.4.0

package/lib/types/aggregate.d.ts

@@ -11,16 +11,14 @@
  */
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
 import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import { MODEL_KEY_ALIASES } from './client/pricing.ts';
+export { MODEL_KEY_ALIASES };
 /**
- * Real provider model ids map to their billing-catalog keys. Unknown ids stay
- * as-is and price zero (they are not in the catalog; subscription-plan routes
- * like kimi-coding / token plans fall here and therefore cost nothing).
- */
-export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
-/**
- * 走订阅套餐（coding / token / agent plan）的 provider id：这些通道的调用
- * 按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
- * 部署可在 plugin config 的 `subscriptionProviders` 中覆盖。
+ * 走订阅套餐（coding / token plan / opencode 订阅）的 provider id：这些通道的
+ * 调用按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
+ * 与 pi-ai 内置提供方对齐（含各地区变体：qwen/xiaomi 的 token-plan、opencode 与
+ * opencode-go、zai-coding-cn）；部署可在 plugin config 的 `subscriptionProviders`
+ * 中覆盖。
  */
 export declare const DEFAULT_SUBSCRIPTION_PROVIDERS: readonly string[];
 /** Aggregation tuning options. */
@@ -36,6 +34,8 @@ export interface ModelUsage {
     cacheHit: number;
     cacheMiss: number;
     cost: number;
+    /** 该模型本次统计的所有调用是否都走订阅通道（coding/token plan）；混合通道不置位。 */
+    plan?: boolean;
 }
 /** Zeroed usage accumulator. */
 export declare function emptyUsage(): ModelUsage;
@@ -47,15 +47,22 @@ export declare function emptyUsage(): ModelUsage;
  * @param usage - the provider-reported usage of one call.
  * @param key - the billing-catalog key this call belongs to.
  * @param subscription - whether the call went through a subscription plan; such calls never cost money.
+ * @param timeMs - the call's wall-clock time (epoch ms); drives peak/off-peak pricing.
  */
-export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean): void;
+export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean, timeMs: number): void;
 /** Local-time date stamp (the host runs in the user's timezone). */
 export declare function dayStamp(time: number): string;
+/** cwd 未知时工作区聚合的占位名（UI 显示 em dash，保持语言无关）。 */
+export declare const UNKNOWN_WORKSPACE_NAME = "\u2014";
+/** 工作区名：取 cwd 的末级目录名；无 cwd 时返回 {@link UNKNOWN_WORKSPACE_NAME}。 */
+export declare function workspaceNameOf(cwd: string | undefined): string;
 /**
  * The persistence surface the aggregate reads: enough of
- * `SessionPersistence` to list sessions and read each log once.
+ * `SessionPersistence` to list sessions and read each log once; `locate`
+ * is optional — backends exposing it give the incremental cache a cheap
+ * invalidation stamp (artifact mtime + size), others always re-fold.
  */
-export type UsagePersistence = Pick<SessionPersistence, 'list' | 'readFrom'>;
+export type UsagePersistence = Pick<SessionPersistence, 'list' | 'readFrom'> & Partial<Pick<SessionPersistence, 'locate'>>;
 /** The usage-stats document served to the billing dashboard. */
 export interface UsageStatsDocument {
     version: number;
@@ -66,9 +73,110 @@ export interface UsageStatsDocument {
     byDay: Record<string, ModelUsage>;
     /** 模型 × 日期 二维统计：趋势图按模型堆叠的输入（[date][modelKey]）。 */
     byDayModels: Record<string, Record<string, ModelUsage>>;
+    /** 会话明细：按费用倒序，封顶 {@link SESSION_ROW_LIMIT} 行；旧快照可能缺失。 */
+    bySession: SessionUsageRow[];
+    /** 每轮费用明细：按起始时间倒序，封顶 {@link TURN_ROW_LIMIT} 行；旧快照可能缺失。 */
+    byTurn?: TurnUsageRow[];
+    /** 工作区聚合：按 cwd 末级目录归并，按费用倒序；旧快照可能缺失。 */
+    byWorkspace?: WorkspaceUsageRow[];
+}
+/** 会话明细行：仪表盘「会话明细」面板的数据源。 */
+export interface SessionUsageRow {
+    /** 会话 id（字符串形式）。 */
+    id: string;
+    /** 日志里最新的 session/title 文本；无标题事件时缺失。 */
+    title?: string;
+    /** 会话创建时的工作目录（项目路径）；未知时缺失。 */
+    cwd?: string;
+    calls: number;
+    cost: number;
+    /** 最后一个事件的时间戳（毫秒）。 */
+    lastActive: number;
+}
+/** 每轮费用明细行：仪表盘「每轮费用」图的数据源。 */
+export interface TurnUsageRow {
+    /** 会话 id（字符串形式）：不同会话的轮次号相互独立，展示时需区分。 */
+    sessionId: string;
+    /** 会话内轮次号。 */
+    turn: number;
+    /** 归因模型 key（计费目录键；未收录原样保留）。 */
+    model: string;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    /** 该轮成本（人民币元，按调用时刻精确判高峰/空闲档）。 */
+    cost: number;
+    /** 轮起始时刻（毫秒）。 */
+    startedAt: number;
+    /** 轮结束时刻（毫秒）；未结束轮缺失。 */
+    endedAt?: number;
 }
+/** 会话内折叠的每轮行（不含 sessionId，合并时补齐）。 */
+type SessionTurnRow = Omit<TurnUsageRow, 'sessionId'>;
+/** 工作区聚合行：按会话 cwd 的末级目录归并。 */
+export interface WorkspaceUsageRow {
+    /** 目录末级名；cwd 未知的会话归入「未命名」。 */
+    name: string;
+    calls: number;
+    cost: number;
+    input: number;
+    output: number;
+    /** 该工作区最近一次活跃时刻（毫秒）。 */
+    lastActive: number;
+}
+/** 会话明细行的响应封顶：控制 payload 体积，重度用户的完整长尾不逐行下发。 */
+export declare const SESSION_ROW_LIMIT = 100;
+/** 每轮费用行的响应封顶：同样控制 payload 体积。 */
+export declare const TURN_ROW_LIMIT = 200;
+/** 聚合文档的短 TTL（毫秒）：合并密集轮询，TTL 内直接复用上次的合并结果。 */
+export declare const AGGREGATE_TTL_MS = 5000;
+/** One persisted session's folded usage plus drill-down metadata. */
+interface SessionFold {
+    total: ModelUsage;
+    byModel: Map<string, ModelUsage>;
+    byDay: Map<string, ModelUsage>;
+    byDayModels: Map<string, Map<string, ModelUsage>>;
+    /** 每个模型 key 在本会话内走订阅通道的调用数（合并时跨会话累加判定 plan）。 */
+    planCalls: Map<string, number>;
+    /** 每轮费用明细（按轮次号升序，不含 sessionId）；sessionId 在合并时补齐。 */
+    turns: SessionTurnRow[];
+    /** 日志里最新的 session/title 文本（无标题事件时 undefined）。 */
+    title?: string;
+    /** 最后一个事件的时间戳（毫秒）；空日志为 0。 */
+    lastActive: number;
+}
+/**
+ * Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
+ * 其前置 request/header 记录的模型；同时提取最新会话标题、最后活跃时间，
+ * 并按轮次折叠每轮费用明细（turn/start → turn/end；调用按 (turn) 归组）。
+ * @param events - the session's persisted events in log order.
+ * @param subscriptionProviders - provider ids billed through subscription plans.
+ * @returns the per-session fold (cached by the incremental aggregator).
+ */
+export declare function foldSession(events: readonly {
+    type: string;
+    time: number;
+    data: never;
+}[], subscriptionProviders: ReadonlySet<string>): SessionFold;
+/**
+ * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——
+ * 日志没动的会话直接复用，只有写过的会话重新折叠；整份文档另有短 TTL
+ * 合并密集轮询。缓存活在内存里（进程重启后首次全量折叠一次）。
+ */
+export interface UsageAggregator {
+    /** Aggregate current usage, reusing cached per-session folds when their logs are untouched. */
+    aggregate(): Promise<UsageStatsDocument>;
+}
+/**
+ * Create the incremental usage aggregator.
+ * @param persistence - the session persistence service.
+ * @param options - aggregation tuning (e.g. subscription-plan providers).
+ * @returns the aggregator holding the per-session fold cache.
+ */
+export declare function createUsageAggregator(persistence: UsagePersistence, options?: AggregateOptions): UsageAggregator;
 /**
- * Aggregate real usage from every persisted session log.
+ * Aggregate real usage from every persisted session log (one-shot, no cache).
  * @param persistence - the session persistence service.
  * @param options - aggregation tuning (e.g. subscription-plan providers).
  * @returns the usage-stats document (same shape the dashboard expects).

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

@@ -1,9 +1,10 @@
 /**
  * TrendChart: dependency-free SVG chart of daily cost + calls.
  *
- * The columns are GROUPED per model — one bar per model per day, each in its
- * brand color, so per-model cost is directly comparable. The blue line is the
- * total call volume across all models, plotted on its own right-hand axis.
+ * The columns are STACKED per day — one bar per day, with each model's cost
+ * as a colored segment inside the bar, so the daily total reads at a glance
+ * and the model mix stays visible. The blue line is the total call volume
+ * across all models, plotted on its own right-hand axis.
  * A hover crosshair shows the day's model breakdown. No chart library — the
  * surface stays self-contained and offline.
  */
@@ -28,7 +29,7 @@ export interface TrendPoint {
     byModel?: Readonly<Record<string, number>>;
 }
 /**
- * Render the daily grouped cost bars plus the total-calls line.
+ * Render the daily stacked cost bars plus the total-calls line.
  * @param props.data - sorted daily rows (ascending date).
  * @param props.models - the model legend, in bar order.
  */

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

@@ -9,8 +9,9 @@
  * before real data arrives the dashboard shows an empty (zero) snapshot,
  * never fabricated samples.
  */
-import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+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 { createBillingBudgetStore } from './budget-store.ts';
 import { NS } from './locales.ts';
 /** Model-connectivity health reported by the host model directory probe. */
 export interface ModelHealth {
@@ -27,10 +28,35 @@ export interface ModelHealth {
     /** Display names of providers whose catalog probe failed. */
     badProviders: readonly string[];
 }
-/** Full props type for the UsageBilling component. */
-type UsageBillingProps = PropsRuntime<'sidebar.footer.action'> & SidebarFooterActionOwnerProps & InjectFace<{
+/**
+ * The dashboard's display names (中文厂商名) never equal the provider names a
+ * user actually configures (deepseek, zhipu, qwen…), so the dot match also
+ * accepts a bidirectional substring hit and a display-name alias list.
+ * 导出供一致性守卫测试：catalog 每个厂商都必须在此登记（Custom 除外），
+ * 防止新增厂商漏配导致健康绿灯不亮。
+ */
+export declare const PROVIDER_ALIASES: Readonly<Record<string, readonly string[]>>;
+/**
+ * 从真实 model id 反推提供方显示名：目录未收录的模型（key 落回「其他」）
+ * 只靠 entry.provider（Custom）永远点不亮健康灯，这里用厂商别名对 model id
+ * 做强匹配（别名作为完整 id / 前缀 / 独立段）与弱匹配（长别名子串），
+ * 命中即显示厂商名并点亮健康点；无命中保持 Custom。
+ * 导出供守卫测试：短别名（mi/yi）仅允许前缀形式，防止 minimax 等误吞。
+ */
+export declare function providerFromModelKey(modelKey: string): string | undefined;
+/** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
+export interface UsageBillingInjected {
     checkModels: () => Promise<ModelHealth>;
-}> & PropsLocale<typeof NS>;
+    publishCosts: (costs: {
+        todayCost: number;
+        monthCost: number;
+    }) => void;
+    registerOpen: (handler: () => void) => () => void;
+}
+/** 预算 store 的 props 份额（useStore 读取 + actions 写面）。 */
+type BillingBudgetStoreProps = PropsStore<ReturnType<typeof createBillingBudgetStore>>;
+/** Full props type for the UsageBilling component. */
+type UsageBillingProps = PropsRuntime<'sidebar.footer.action'> & SidebarFooterActionOwnerProps & InjectFace<UsageBillingInjected> & PropsRenderSlots<'billing.dashboard.decor'> & BillingBudgetStoreProps & PropsLocale<typeof NS>;
 /**
  * UsageBilling: sidebar trigger plus the billing dashboard modal.
  * @param props - framework-provided sidebar and locale props.

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

@@ -5,9 +5,40 @@
  * Displays compact cost/token/cache metrics in the sidebar footer, above the
  * Settings button, plus a model-health dot (green when any connected model
  * route responds). Expands to a detailed dashboard panel on click.
+ *
+ * 与主题插件（如 acid-zine）的协作走 slot 与服务：billing 声明装饰孔位
+ *（billing.dashboard.decor）并注册计费指标服务（ctx.billingMetrics），主题
+ * 插件主动注入装饰视觉、消费费用数据——billing 不反向依赖任何主题包。
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
 import { type UsageBillingKey } from './locales.ts';
+import { type BillingMetricsService } from './billing-service.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * Dashboard 弹窗内的装饰孔位：主题插件（如 acid-zine）按 position 锚点
+         * 注入 MacDots、撕角便签、胶带标题、条码等 ZINE 元素。kind=list，可多个
+         * 注册者并列；未注入时走 billing 默认视觉。
+         */
+        'billing.dashboard.decor': {
+            kind: 'list';
+            scope: 'root';
+            owner: BillingDashboardDecorOwnerProps;
+        };
+    }
+}
+/** Dashboard 装饰的锚点位置：head/headTitle=窗口标题区；hero=主数字卡；trend/models=面板标题；footer=面板底部。 */
+export type BillingDecorPosition = 'head' | 'headTitle' | 'hero' | 'trend' | 'models' | 'footer';
+/** Dashboard 装饰组件收到的所有者数据：当前锚点。 */
+export interface BillingDashboardDecorOwnerProps {
+    position: BillingDecorPosition;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** 计费指标服务（billing 插件提供；主题插件可选消费）。 */
+        billingMetrics?: BillingMetricsService;
+    }
+}
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         /** The usage billing surface's copy. */

package/lib/types/client/billing-service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 计费指标服务（ctx.billingMetrics）：把 UsageBilling 的实时费用摘要与
+ * 弹窗打开能力开放给其他插件（如 acid-zine 主题的贴纸层）消费。
+ *
+ * 依赖方向为「billing 提供服务、主题适配消费」：billing 插件是唯一的
+ * 写入方（组件通过 inject 的 publishCosts / registerOpen 写入），消费方
+ * 只读费用快照并触发弹窗打开——billing 不反向依赖任何主题包。
+ */
+/** 计费摘要（精简版，仅供外部展示；金额为人民币元）。 */
+export interface BillingCosts {
+    todayCost: number;
+    monthCost: number;
+}
+/** 消费方（如酸-zine 贴纸层）可用的只读接口。 */
+export interface BillingMetricsService {
+    /** 当前费用快照；从未发布过则 undefined。 */
+    readCosts(): BillingCosts | undefined;
+    /**
+     * 订阅费用更新；立即收到当前值一次（若无值则为 undefined）。
+     * @param listener - 费用回调。
+     * @returns 退订函数。
+     */
+    subscribeCosts(listener: (costs: BillingCosts | undefined) => void): () => void;
+    /** 打开计费仪表盘（若 billing 弹窗已挂载）。 */
+    openDashboard(): void;
+}
+/** 服务运行时：在只读接口之上追加写入入口，仅 apply 与组件使用。 */
+export interface BillingMetricsRuntime extends BillingMetricsService {
+    /** 发布最新费用摘要（UsageBilling 组件每次渲染数据变化时调用）。 */
+    publishCosts(costs: BillingCosts): void;
+    /**
+     * 注册弹窗打开回调；组件卸载时应解除。
+     * @param handler - 打开弹窗的处理函数。
+     * @returns 解除注册的函数。
+     */
+    registerOpen(handler: () => void): () => void;
+}
+/** 创建计费指标运行时（apply 内调用，随插件纤维存活）。 */
+export declare function createBillingMetrics(): BillingMetricsRuntime;
+//# sourceMappingURL=billing-service.d.ts.map

package/lib/types/client/budget-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 预算偏好 store：本月预算的开关与金额。
+ *
+ * 用户在仪表盘里用开关控制预算条显隐、用数字输入框设置金额；状态经框架
+ * store 引擎持久化到 localStorage（persist key 即存储身份），重启后保留。
+ * 宿主 Config 的 monthlyBudget 仅作为金额未设置时的默认值，用户输入优先。
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+/** 预算偏好状态。 */
+export interface BudgetPrefsState {
+    /** 预算条开关：关 = 只显示标题行与开关，不显示进度。 */
+    enabled: boolean;
+    /** 用户设置的月度预算（人民币元）；0 = 未设置（回退到宿主默认值）。 */
+    amount: number;
+    /** 最近一次超支通知的日期戳（YYYY-MM-DD）：超支通知每天最多一次，跨重启生效。 */
+    lastAlertDay: string;
+    /** 最近一次余额不足通知的日期戳（YYYY-MM-DD）：余额告警同样每天最多一次。 */
+    lastBalanceAlertDay: string;
+}
+/** 预算偏好的完整写面（组件只能经这些 action 写入）；type 别名以兼容 ActionsDecl 的索引签名约束。 */
+export type BudgetPrefsActions = {
+    setEnabled: (d: BudgetPrefsState, on: boolean) => void;
+    setAmount: (d: BudgetPrefsState, value: number) => void;
+    markAlerted: (d: BudgetPrefsState, day: string) => void;
+    markBalanceAlerted: (d: BudgetPrefsState, day: string) => void;
+};
+/**
+ * Declare the budget-preferences store handle.
+ * @returns the store handle for the register call's store seat.
+ */
+export declare function createBillingBudgetStore(): EngineStoreHandle<BudgetPrefsState, BudgetPrefsActions>;
+//# sourceMappingURL=budget-store.d.ts.map

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

@@ -8,4 +8,6 @@
 export { inject, apply } from './apply.ts';
 export { UsageBilling } from './UsageBilling.tsx';
 export type { UsageBillingKey } from './locales.ts';
+export type { BillingCosts, BillingMetricsService } from './billing-service.ts';
+export type { BillingDecorPosition, BillingDashboardDecorOwnerProps } from './apply.ts';
 //# sourceMappingURL=index.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.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trendEmpty' | 'billing.models' | '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.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | '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.budgetOverBody' | 'billing.models' | '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.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.balanceDays' | 'billing.balanceLowBody';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

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

@@ -37,16 +37,21 @@ export declare function getRateInfo(): {
 };
 /** Default share of traffic assumed to fall in the peak band (0..1). */
 export declare const DEFAULT_PEAK_SHARE = 0.5;
+/** 计费时段档位：高峰 / 空闲（官方 DeepSeek 刊例价：高峰 = 空闲 × 2）。 */
+export type PriceTierId = 'peak' | 'offPeak';
+/** 成本显示币种：人民币（国内模型直价）/ 美元（国外模型直价或换算显示）。 */
+export type CostCurrency = 'cny' | 'usd';
 /**
- * Model keys served through a subscription plan (e.g. a coding plan or topic
- * plan) instead of metered per-token API billing. Usage through these routes
- * costs no tokens: the estimator treats them as ¥0 and the billing table
- * labels them 订阅包含. Add any model key your deployment serves through a
- * plan here; leave empty when every route is pay-as-you-go.
+ * 高峰时段判定（北京时间，UTC+8，无夏令时）：09:00–12:00、14:00–18:00。
+ * @param beijingHour - 北京时间的小时数（0–23）。
  */
-export declare const SUBSCRIPTION_PLAN_KEYS: readonly string[];
-/** Whether one stats model key is billed through a subscription plan. */
-export declare function isSubscriptionPlan(key: string): boolean;
+export declare function isPeakHour(beijingHour: number): boolean;
+/**
+ * 由时刻（epoch 毫秒）推断计费时段；时刻未知/非法时按高峰计（保守：未知
+ * 时刻不低估成本，与社区 dsh-usage-chart 的 tierAt 语义一致）。
+ * @param timeMs - Unix epoch 毫秒；null/undefined/NaN 视为未知。
+ */
+export declare function tierAt(timeMs: number | null | undefined): PriceTierId;
 /** Usage buckets consumed by one model (counts in raw tokens). */
 export interface TokenUsageBuckets {
     /** Uncached input tokens. */
@@ -107,6 +112,13 @@ export interface ModelEntry {
  * from 2026-08-17, and Gemini's Flex tier discounts spare-capacity traffic.
  */
 export declare const MODEL_CATALOG: readonly ModelEntry[];
+/**
+ * 真实 provider model id → 计费目录键（`MODEL_CATALOG[].key`）的映射。未知 id
+ * 原样保留并落回 `other`（未知模型不估算费用）。聚合层（aggregate.ts）在折叠时
+ * 用同一张表把日志里的 model id 归并为目录键，客户端渲染（`modelOf`）也按它
+ * 解析，两侧共用一份映射，避免同一模型两侧不一致导致「未收录」。
+ */
+export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 export declare function modelOf(key: string): ModelEntry;
 /** Resolve a price-table row by its CSS variable name (theme token or fallback color). */
@@ -127,8 +139,25 @@ export declare function resolveToken(name: string): string;
  * @returns the estimated cost in CNY.
  */
 export declare function computeCost(entry: ModelEntry, buckets: TokenUsageBuckets, peakShare?: number): number;
-/** Format a CNY amount with adaptive precision. */
-export declare function formatMoney(cny: number): string;
+/**
+ * 按调用时刻精确判定高峰/空闲档并计价（P0-1：替代固定比例混合）。时刻未知
+ * （null/NaN，理论不发生在真实事件流）时回退 {@link DEFAULT_PEAK_SHARE} 混合，
+ * 保持旧语义不低估。平档模型（无 offPeak）两个时段同价。
+ * @param entry - the catalog entry whose prices apply.
+ * @param buckets - token usage counts.
+ * @param timeMs - the call's wall-clock time (epoch ms); null falls back to the peak-share mix.
+ * @param peakShare - fallback mix used only when `timeMs` is missing.
+ * @returns the estimated cost in the entry's native currency.
+ */
+export declare function computeCostAt(entry: ModelEntry, buckets: TokenUsageBuckets, timeMs: number | null | undefined, peakShare?: number): number;
+/** 人民币 → 美元（显示换算用）：1 USD = {@link USD_TO_CNY} CNY。 */
+export declare function cnyToUsd(cny: number): number;
+/**
+ * Format an amount with adaptive precision and the given currency symbol.
+ * @param amount - the amount (CNY by default; pass `usd` for dollar display).
+ * @param currency - display currency; default `cny`.
+ */
+export declare function formatMoney(amount: number, currency?: CostCurrency): string;
 /**
  * Format a per-1M-token price in its native currency (free when the rate is
  * zero): CNY for domestic models, USD for overseas ones.

package/lib/types/index.d.ts

@@ -10,17 +10,38 @@
  * fabricated samples.
  */
 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 IdentifiedSubscriptionPlan, type SubscriptionKeys, type SubscriptionPlanConfig } from './subscriptions.ts';
 /** Plugin configuration. */
 export interface UsageBillingConfig {
     /** Absolute path to a `.dsh-usage-stats.json` fallback file. */
     statsPath?: string;
     /** 订阅制（coding / token / agent plan）provider id 列表；默认 kimi-coding、xiaomi-token-plan-cn。 */
     subscriptionProviders?: string[];
+    /** 订阅套餐额度适配器（kimi / zai / opencode-go）；默认全部内置。 */
+    subscriptionPlans?: readonly SubscriptionPlanConfig[];
     /** 余额查询用的 DeepSeek 凭据引用（环境变量名）；默认 DEEPSEEK_API_KEY。 */
     balanceApiKeyEnv?: string;
+    /** 月度预算（人民币元）；设置后随 usage-stats 下发，仪表盘显示预算进度条。 */
+    monthlyBudget?: number;
+    /** 余额不足告警阈值（人民币元）：余额低于此值时仪表盘每天提醒一次；
+        不设置则客户端按默认阈值（50 元）兜底。 */
+    lowBalanceThreshold?: number;
 }
-/** Required services: the web server and the persisted session log store. */
+/** 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`
+ * 读引用（如 kimi-coding → KIMI_CODING_API_KEY），再经凭据 seam 解析成实际值。
+ * 同时识别出用户配置了 key 的订阅套餐（供面板只显示已识别的）。
+ * @param settings - the settings service (reads the llm-pi-ai namespace).
+ * @param credentials - the credentials service (resolves the env refs).
+ */
+export declare function resolveSubscriptionKeys(settings: SettingsProvider, credentials: CredentialProvider): Promise<{
+    keys: SubscriptionKeys;
+    identified: IdentifiedSubscriptionPlan[];
+}>;
 /**
  * Host plugin body: serve real aggregated usage to the browser dashboard.
  * @param ctx - host context carrying webServer and sessionPersistence.

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

@@ -47,4 +47,43 @@ export interface ProviderBalance {
 export interface BalanceResponse {
     balances: readonly ProviderBalance[];
 }
+/** Quota query result status; the dashboard maps each to a row state. */
+export type SubscriptionStatus = 'ok' | 'not-configured' | 'unauthorized' | 'rate-limited' | 'unavailable' | 'invalid-response';
+/** One quota window (session / weekly / monthly / billing). */
+export interface SubscriptionWindow {
+    kind: 'session' | 'weekly' | 'monthly' | 'billing';
+    /** Used share in percent (0–100, one decimal). */
+    usedPercent: number;
+    /** Remaining share in percent (0–100, one decimal). */
+    remainingPercent: number;
+    /** ISO reset time; absent when the provider reports none. */
+    resetsAt?: string;
+    /** Absolute remaining amount; present when the provider reports one. */
+    remaining?: number;
+}
+/** One provider's subscription plan quota row. */
+export interface SubscriptionQuota {
+    /** Adapter id: `kimi` / `zai` / `opencode-go`. */
+    provider: string;
+    /** Human display name (e.g. Kimi For Coding). */
+    displayName: string;
+    /** Plan label; absent when the provider did not name one. */
+    plan?: string;
+    status: SubscriptionStatus;
+    /** Quota windows, newest-window first; empty when the query failed. */
+    windows: readonly SubscriptionWindow[];
+}
+/** Response of `/api/billing/subscriptions`. */
+export interface SubscriptionResponse {
+    quotas: readonly SubscriptionQuota[];
+}
+/** Config for one subscription adapter (validated in apply). */
+export interface SubscriptionPlanConfig {
+    /** Adapter id: `kimi` / `zai` / `opencode-go`. */
+    provider: string;
+    /** API base URL override; defaults to the provider's public endpoint. */
+    baseUrl?: string;
+    /** Z.ai region override; defaults to the settings-namespace `zaiRegion`. */
+    region?: 'global' | 'bigmodel-cn';
+}
 //# sourceMappingURL=pricing-shared.d.ts.map

package/lib/types/subscriptions.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Subscription-plan quota polling (node half): how much of each coding/token
+ * plan is left. The billing dashboard already exempts subscription providers
+ * from per-token cost; this module surfaces the REMAINING quota so the user
+ * sees plan headroom instead of a blank row.
+ *
+ * The panel shows only the plans the user actually configured: adapters with
+ * a known quota API (Kimi, Z.ai, OpenCode Go) query the remaining amount;
+ * other subscription providers the harness recognizes (volcengine / baidu /
+ * qwen / xiaomi token plans, agent plans…) are identified and listed with a
+ * "no quota API" marker rather than hidden. API keys come from the `llm-pi-ai`
+ * settings namespace (`apiKeyEnv` refs) resolved through the credentials seam.
+ */
+import type { SubscriptionPlanConfig, SubscriptionQuota } from './pricing-shared.ts';
+/** 订阅适配器需要的凭据（来自 llm-pi-ai 设置命名空间）。 */
+export interface SubscriptionKeys {
+    /** Kimi For Coding API key。 */
+    kimiApiKey: string;
+    /** Z.ai API key。 */
+    zaiApiKey: string;
+    /** OpenCode Go API key。 */
+    opencodeApiKey: string;
+    /** Z.ai 区域（global / bigmodel-cn）。 */
+    zaiRegion: 'global' | 'bigmodel-cn';
+}
+/** 空凭据：全部未配置时的初始值。 */
+export declare const EMPTY_SUBSCRIPTION_KEYS: SubscriptionKeys;
+/** 已识别的一个订阅套餐（用户在 llm-pi-ai 里配置了 key 的订阅类 provider）。 */
+export interface IdentifiedSubscriptionPlan {
+    /** llm-pi-ai 的 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
+    provider: string;
+    /** 显示名（映射表命中则用映射，否则用 id）。 */
+    displayName: string;
+    /** 是否有额度查询适配器。 */
+    adapter: boolean;
+    /** 适配器区域覆盖（zai-coding-cn → bigmodel-cn）。 */
+    region?: 'global' | 'bigmodel-cn';
+}
+/** 是否是订阅类 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
+export declare function isSubscriptionProviderId(providerId: string): boolean;
+/**
+ * 从 llm-pi-ai 设置里识别订阅套餐：带订阅类 id 且配置了 apiKeyEnv 的 provider。
+ * @param providers - the `providers` map of the llm-pi-ai settings namespace.
+ * @returns identified plans in configuration order.
+ */
+export declare function identifySubscriptionPlans(providers: Record<string, {
+    apiKeyEnv?: string;
+} | undefined> | undefined): IdentifiedSubscriptionPlan[];
+/**
+ * Collect quota for the given plans concurrently (adapter-backed plans only;
+ * identified plans without an adapter are surfaced by the caller as "no
+ * quota API" rows).
+ * @param keys - the API keys from the llm-pi-ai settings namespace.
+ * @param plans - adapter-backed plans to poll; empty by default.
+ * @param timeoutMs - per-request timeout; defaults to 15s.
+ * @returns the quotas in plan order (unknown providers degrade to `unavailable`).
+ */
+export declare function collectSubscriptions(keys: SubscriptionKeys, plans?: readonly SubscriptionPlanConfig[], timeoutMs?: number): Promise<readonly SubscriptionQuota[]>;
+//# sourceMappingURL=subscriptions.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.2.6",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -56,10 +56,13 @@
     "@deepseek-ai/dsh-client-ui-sidebar": "*",
     "@deepseek-ai/dsh-client-ui-primitives": "*",
     "@deepseek-ai/dsh-client-ui-slots": "*",
+    "@deepseek-ai/dsh-credentials": "*",
     "@deepseek-ai/dsh-invariants": "*",
     "@deepseek-ai/dsh-llm": "*",
     "@deepseek-ai/dsh-session": "*",
     "@deepseek-ai/dsh-session-persistence": "*",
+    "@deepseek-ai/dsh-settings": "*",
+    "@deepseek-ai/schemastery": "*",
     "@deepseek-ai/cordis": "*",
     "react": "^18.2.0"
   },
@@ -73,6 +76,7 @@
     "@deepseek-ai/dsh-client-ui-conversation": "*",
     "@deepseek-ai/dsh-client-ui-primitives": "*",
     "@deepseek-ai/dsh-client-ui-slots": "*",
+    "@deepseek-ai/dsh-client-web-react": "*",
     "@deepseek-ai/dsh-invariants": "*",
     "@testing-library/react": "^16.1.0",
     "@types/react": "~18.3.1",