@kenz1117/dsh-ui-usage-billing 0.5.0 → 0.7.0

package/lib/types/aggregate.d.ts

@@ -79,6 +79,18 @@ export interface UsageStatsDocument {
     byTurn?: TurnUsageRow[];
     /** 工作区聚合：按 cwd 末级目录归并，按费用倒序；旧快照可能缺失。 */
     byWorkspace?: WorkspaceUsageRow[];
+    /**
+     * 按角色费用归因（人民币元）：助手输出成本为实测计价；输入成本按会话内
+     * 用户消息 / 工具结果的文本长度占比启发式摊分（日志无角色级 token 实测，
+     * 属估算口径，UI 需标注）。旧快照可能缺失。
+     */
+    byRole?: RoleCost;
+}
+/** 按角色费用归因：user / tool 为输入成本的启发式摊分，assistant 为输出成本实测。 */
+export interface RoleCost {
+    user: number;
+    assistant: number;
+    tool: number;
 }
 /** 会话明细行：仪表盘「会话明细」面板的数据源。 */
 export interface SessionUsageRow {
@@ -141,11 +153,27 @@ interface SessionFold {
     planCalls: Map<string, number>;
     /** 每轮费用明细（按轮次号升序，不含 sessionId）；sessionId 在合并时补齐。 */
     turns: SessionTurnRow[];
+    /** 角色归因中间量：消息文本长度（user/tool）与输入/输出成本实测拆分。 */
+    roles: RoleFold;
     /** 日志里最新的 session/title 文本（无标题事件时 undefined）。 */
     title?: string;
     /** 最后一个事件的时间戳（毫秒）；空日志为 0。 */
     lastActive: number;
 }
+/** 角色归因的会话级中间量：字符占比用于把输入成本摊到 user/tool。 */
+interface RoleFold {
+    userChars: number;
+    toolChars: number;
+    /** 输入侧成本（缓存命中 + 未命中 + 缓存写入，人民币元）。 */
+    inputCost: number;
+    /** 输出侧成本（人民币元）。 */
+    outputCost: number;
+}
+/**
+ * 消息文本长度：user/tool 角色分摊输入成本的启发式依据。字符串内容取其
+ * 长度；内容块数组累计文本块长度；其余形状按 0 计（durable 边界收窄）。
+ */
+export declare function messageTextLength(message: unknown): number;
 /**
  * Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
  * 其前置 request/header 记录的模型；同时提取最新会话标题、最后活跃时间，

package/lib/types/balance.d.ts

@@ -14,7 +14,7 @@
  * provider's key once and every surface reuses it.
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { ProviderBalance } from './pricing-shared.ts';
+import type { CustomBalanceConfig, CustomBalanceExtract, ProviderBalance } from './pricing-shared.ts';
 /**
  * Query every configured provider's account balance. A provider is queried only
  * when its llm-pi-ai route has an `apiKeyEnv`; absent routes answer
@@ -26,4 +26,20 @@ import type { ProviderBalance } from './pricing-shared.ts';
 export declare function queryBalances(ctx: Context, providers: Readonly<Record<string, {
     apiKeyEnv?: string;
 }>>): Promise<readonly ProviderBalance[]>;
+/**
+ * 按 extract 规则从响应 JSON 求值。导出供测试：纯函数。
+ * @param rule - 提取规则（const / path / add / subtract / divide）。
+ * @param data - 响应 JSON。
+ * @returns 数值；取不到或结果非有限数返回 undefined。
+ */
+export declare function evalExtract(rule: CustomBalanceExtract, data: unknown): number | undefined;
+/**
+ * 查询自定义 Provider 余额（插件 config 的 `customBalances`）。每个条目独立
+ * 成败：占位符凭据缺失 → unconfigured；401/403 → unauthorized；网络或提取
+ * 失败 → unreachable。
+ * @param ctx - host context carrying the credentials seam.
+ * @param configs - 自定义余额配置列表。
+ * @returns 每个配置一行的余额结果。
+ */
+export declare function queryCustomBalances(ctx: Context, configs: readonly CustomBalanceConfig[]): Promise<readonly ProviderBalance[]>;
 //# sourceMappingURL=balance.d.ts.map

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

@@ -12,6 +12,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 { createBillingBudgetStore } from './budget-store.ts';
+import { type CatalogModel } from './pricing.ts';
 import { NS, type UsageBillingKey } from './locales.ts';
 /** Model-connectivity health reported by the host model directory probe. */
 export interface ModelHealth {
@@ -27,12 +28,14 @@ export interface ModelHealth {
     okProviders: readonly string[];
     /** Display names of providers whose catalog probe failed. */
     badProviders: readonly string[];
+    /** 探活得到的模型清单（系统里实际配置/预制的模型；无价格，费率表据此对标）。 */
+    catalog?: readonly CatalogModel[];
 }
 /** 仪表盘分区 Tab id。 */
 export type DashboardTab = 'overview' | 'trends' | 'providers' | 'details' | 'pricing';
 /**
  * Tab 定义（顺序即渲染顺序）：概览=主数字/预算/KPI/热力图，趋势=趋势图/每轮费用，
- * 厂商=厂商计费与订阅，明细=工作区/会话明细，单价=模型单价表。导出供测试断言
+ * 明细=厂商计费与订阅，统计=工作区/会话明细，费率=模型单价表。导出供测试断言
  * tab 与文案 key 对齐、decor 锚点落在正确分区。
  */
 export declare const DASHBOARD_TABS: readonly {
@@ -67,6 +70,31 @@ export declare function providerFromModelKey(modelKey: string): string | undefin
 export declare function projectMonthCost(byDay: Record<string, {
     cost: number;
 }>, monthPrefix: string, today: string): number;
+/**
+ * 峰谷时段费用分摊：按每轮的起始时刻（北京时间高峰 9-12 / 14-18）把费用
+ * 归入高峰 / 空闲两档。导出供测试：纯函数。
+ * @param turns - 每轮费用行（需带 startedAt 与 cost）。
+ * @returns 两档费用合计（人民币元）。
+ */
+export declare function peakOffpeakCost(turns: readonly {
+    startedAt: number;
+    cost: number;
+}[]): {
+    peak: number;
+    offPeak: number;
+};
+/**
+ * 近 7 天费用序列（含今天，缺日补 0）：触发卡 hover 速览的迷你柱数据源。
+ * 导出供测试：纯函数（日期取本地时区）。
+ * @param byDay - 按日费用表。
+ * @returns 7 个 `{ date, cost }`，最旧在前。
+ */
+export declare function lastSevenDays(byDay: Record<string, {
+    cost: number;
+}>): readonly {
+    date: string;
+    cost: number;
+}[];
 /** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
 export interface UsageBillingInjected {
     checkModels: () => Promise<ModelHealth>;

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

@@ -12,17 +12,20 @@ export interface BudgetPrefsState {
     enabled: boolean;
     /** 用户设置的月度预算（人民币元）；0 = 未设置（回退到宿主默认值）。 */
     amount: number;
-    /** 最近一次超支通知的日期戳（YYYY-MM-DD）：超支通知每天最多一次，跨重启生效。 */
-    lastAlertDay: string;
+    /** 各档提醒的最后通知日期戳（档位百分比字符串 → YYYY-MM-DD）：每档每天最多一次。 */
+    tierAlertDays: Record<string, string>;
     /** 最近一次余额不足通知的日期戳（YYYY-MM-DD）：余额告警同样每天最多一次。 */
     lastBalanceAlertDay: string;
+    /** 最近一次峰谷切换提醒的切换点时刻（毫秒）：同一切换点只提醒一次。 */
+    lastTierSwitchAt: number;
 }
 /** 预算偏好的完整写面（组件只能经这些 action 写入）；type 别名以兼容 ActionsDecl 的索引签名约束。 */
 export type BudgetPrefsActions = {
     setEnabled: (d: BudgetPrefsState, on: boolean) => void;
     setAmount: (d: BudgetPrefsState, value: number) => void;
-    markAlerted: (d: BudgetPrefsState, day: string) => void;
+    markTierAlerted: (d: BudgetPrefsState, tiers: readonly number[], day: string) => void;
     markBalanceAlerted: (d: BudgetPrefsState, day: string) => void;
+    markTierSwitchAlerted: (d: BudgetPrefsState, at: number) => void;
 };
 /**
  * Declare the budget-preferences store handle.

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

@@ -0,0 +1,33 @@
+/**
+ * 数据导出：把用量统计导出为 CSV / JSON 供对账。
+ *
+ * 纯函数生成文本（按日 / 按会话两个视角），DOM 下载副作用单独隔离在
+ * `downloadText`；金额一律人民币元（与聚合口径一致），文件名带日期范围。
+ */
+/** 按日聚合行（与 UsageStatsDocument.byDay 的行同形）。 */
+export interface DayExportRow {
+    calls: number;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    cost: number;
+}
+/** 会话导出行（与 SessionUsageRow 同形，结构化声明避免跨文件引用）。 */
+export interface SessionExportRow {
+    id: string;
+    title?: string;
+    cwd?: string;
+    calls: number;
+    cost: number;
+    lastActive: number;
+}
+/** 按日 CSV：日期,调用,输入,输出,缓存命中,缓存未命中,费用(元)。 */
+export declare function dayRowsCsv(byDay: Record<string, DayExportRow>): string;
+/** 按会话 CSV：会话 id,标题,项目,调用,费用(元),最后活跃(ISO)。 */
+export declare function sessionRowsCsv(rows: readonly SessionExportRow[]): string;
+/** 导出文件名：带日期范围（usage-2026-08-01_2026-08-22.csv）；无日期时只带前缀。 */
+export declare function exportFileName(prefix: string, ext: 'csv' | 'json', dates: readonly string[]): string;
+/** 触发浏览器下载（唯一 DOM 副作用；调用方在 click 手势里使用）。 */
+export declare function downloadText(filename: string, text: string, mime: string): void;
+//# sourceMappingURL=export.d.ts.map

package/lib/types/client/live-cost.d.ts

@@ -9,9 +9,15 @@
  * the current session id off the framework snapshot (`useSession` parent of
  * `sessionId`) and matches `bySession` (session total) and `byTurn` (latest
  * turn cost). Rendering is a pure function of the snapshot, never a side effect.
+ *
+ * The bar also carries two ambient signals: the current peak/off-peak pricing
+ * tier with a switch countdown (DeepSeek time-of-day pricing), and quota chips
+ * for subscription plans running low (≤20% remaining), so cost pressure is
+ * visible without opening the dashboard.
  */
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
 import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+import type { UsageBillingKey } from './locales.ts';
 /** The usage-stats shape the composer bar needs (a thin slice, not the whole doc). */
 export interface LiveStats {
     bySession?: readonly {
@@ -24,6 +30,15 @@ export interface LiveStats {
         cost: number;
     }[];
 }
+/** 订阅额度的薄切片（/api/billing/subscriptions 响应的行）。 */
+export interface QuotaSlice {
+    displayName: string;
+    status: string;
+    windows: readonly {
+        kind: string;
+        remainingPercent: number;
+    }[];
+}
 /**
  * 当前会话累计费用：bySession 里会话 id 匹配的那行；缺省为 0。
  * 导出供测试：纯函数。
@@ -41,11 +56,22 @@ export declare function sessionCostOf(stats: LiveStats | null, sessionId: string
  * @returns 最新一轮费用（人民币元）。
  */
 export declare function turnCostOf(stats: LiveStats | null, sessionId: string | undefined): number;
+/**
+ * 低额度预警 chips：查询成功（ok）且任一窗口剩余 ≤ threshold 的套餐，
+ * 按剩余升序、最多 3 枚。导出供测试：纯函数。
+ * @param quotas - 订阅额度行切片。
+ * @param threshold - 剩余百分比阈值（默认 20%）。
+ */
+export declare function lowQuotaChips(quotas: readonly QuotaSlice[], threshold?: number): readonly {
+    name: string;
+    kind: string;
+    pct: number;
+}[];
 /** Props: the session-scope snapshot selector the framework injects. */
 export interface LiveCostBarProps {
     useSession: SnapshotSelectorHook<ConversationSnapshot>;
     /** The owning dock's locale seat (bound to the billing NS). */
-    t: (key: 'billing.liveTurn' | 'billing.liveSession') => string;
+    t: (key: UsageBillingKey) => string;
 }
 /**
  * Render the live cost ticker for the current session.

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.budgetOverBody' | '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.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.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';
+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.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.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';
 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

@@ -27,6 +27,22 @@ export declare const USD_TO_CNY = 6.79;
  * @param pricing - the `/api/billing/pricing` response.
  */
 export declare function applyLivePricing(pricing: LivePricing): void;
+/**
+ * 注入探活得到的「系统里实际配置/预制的模型」清单（host 的 llm.models 返回
+ * groups[].models[]，含模型 id/name，无价格）。费率表据此对标现实可用模型——
+ * 有价的补价（内置目录 / models.dev 补充），无价的标「未收录」。纯内存状态，
+ * 供 `catalogEntries()` 渲染。
+ */
+export declare function applyLiveCatalogModels(models: readonly CatalogModel[]): void;
+/** 探活模型清单条目（host 的 ModelCatalogModel 投影出需要的字段）。 */
+export interface CatalogModel {
+    /** 模型 id（如 `deepseek-v4-flash`）。 */
+    id: string;
+    /** 显示名；缺省用 id。 */
+    name?: string;
+    /** 厂商显示名（探活 group 名）。 */
+    provider: string;
+}
 /**
  * 当前生效的 USD → CNY 汇率及其来源：live = 启动时实时拉取成功，
  * builtin = 实时拉取失败、正在用内置默认值。
@@ -52,6 +68,30 @@ export declare function isPeakHour(beijingHour: number): boolean;
  * @param timeMs - Unix epoch 毫秒；null/undefined/NaN 视为未知。
  */
 export declare function tierAt(timeMs: number | null | undefined): PriceTierId;
+/**
+ * 当前峰谷档位与距下次切换的时长。导出供测试：纯函数。
+ * @param nowMs - 当前时刻（epoch 毫秒）。
+ * @returns 当前档位与到下一个切换边界的毫秒数。
+ */
+export declare function tierCountdown(nowMs: number): {
+    tier: PriceTierId;
+    nextSwitchInMs: number;
+};
+/**
+ * 峰/谷切换预告：距下次切换不足 leadMs 时返回即将进入的档位与切换时刻，
+ * 否则 null。导出供测试：纯函数。
+ * @param nowMs - 当前时刻（epoch 毫秒）。
+ * @param leadMs - 提前量（毫秒）。
+ */
+export declare function upcomingTierSwitch(nowMs: number, leadMs: number): {
+    entering: PriceTierId;
+    atMs: number;
+} | null;
+/**
+ * 切换倒计时短格式：`1h23m` / `45m` / `3m`。导出供测试：纯函数。
+ * @param ms - 剩余毫秒数。
+ */
+export declare function formatSwitchCountdown(ms: number): string;
 /** Usage buckets consumed by one model (counts in raw tokens). */
 export interface TokenUsageBuckets {
     /** Uncached input tokens. */
@@ -100,6 +140,8 @@ export interface ModelEntry {
      * 展示时标注以免误当正式定价；正式定价公布后移除。
      */
     estimated?: boolean;
+    /** 探活命中但无内置/models.dev 价：费率表标「未收录」，不参与计价。 */
+    uncatalogued?: boolean;
 }
 /**
  * Built-in catalog of current mainstream models as of 2026-08-16, priced from
@@ -126,6 +168,17 @@ export declare const MODEL_CATALOG: readonly ModelEntry[];
 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;
+/**
+ * 模型是否可计价：内置目录或 models.dev 补充条目命中。聚合层的计价闸门
+ * （目录外模型不产生费用，避免兜底档误估）。
+ */
+export declare function isPriced(key: string): boolean;
+/**
+ * 费率表渲染的完整目录：内置 + models.dev 补充条目 + 探活模型（无价标记）。
+ * 探活模型去重（按归一化 id）：内置/补充已有的不再重复；无价的保留并标记
+ * `uncatalogued`，费率表据此显示「未收录」。
+ */
+export declare function catalogEntries(): readonly ModelEntry[];
 /** Resolve a price-table row by its CSS variable name (theme token or fallback color). */
 export declare function resolveToken(name: string): string;
 /**

package/lib/types/index.d.ts

@@ -12,7 +12,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 { SubscriptionPlanConfig } from './pricing-shared.ts';
+import type { CustomBalanceConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
 /** Plugin configuration. */
 export interface UsageBillingConfig {
@@ -29,6 +29,8 @@ export interface UsageBillingConfig {
     /** 余额不足告警阈值（人民币元）：余额低于此值时仪表盘每天提醒一次；
         不设置则客户端按默认阈值（50 元）兜底。 */
     lowBalanceThreshold?: number;
+    /** 自定义 Provider 余额查询（任意 HTTP 端点 + extract 规则，适配 NewApi/LiteLLM 等）。 */
+    customBalances?: readonly CustomBalanceConfig[];
 }
 /** Required services: the web server, the persisted session log store, and user settings. */
 export declare const inject: string[];

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

@@ -7,7 +7,15 @@
  * half caches whatever succeeded and the browser dashboard falls back to the
  * catalog for the rest — a total outage answers `{ source: 'builtin' }`.
  */
-import type { LivePricing } from './pricing-shared.ts';
+import type { ExtraModelPrice, LivePricing } from './pricing-shared.ts';
+/**
+ * models.dev 响应 → 目录外补充条目。不再按厂商白名单过滤：凡是有有效
+ * cost 的模型都纳入（探活模型可能来自任何预制厂商，白名单会漏掉）。厂商
+ * 显示名优先取映射，未命中用 provider id。导出供测试：纯函数。
+ * @param data - `https://models.dev/api.json` 的响应体。
+ * @returns 补充条目（按 provider 顺序稳定；仅含可计价的模型）。
+ */
+export declare function buildExtraModels(data: unknown): ExtraModelPrice[];
 /**
  * Fetch the live pricing once at boot. Both upstreams run in parallel; a
  * failure in either degrades independently to the built-in value.

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

@@ -21,6 +21,22 @@ export interface LivePricing {
     rate?: number;
     /** Overrides keyed by built-in catalog key (present when router matches succeeded). */
     prices?: Record<string, LivePrice>;
+    /**
+     * models.dev 补充的目录外模型价（USD / 1M tokens）：与宿主预制提供方对齐——
+     * pi-ai 预制目录的上游就是 models.dev，补进来的条目让「提供方支持但我们的
+     * 内置目录未收录」的模型也能计价并出现在费率表。
+     */
+    extraModels?: readonly ExtraModelPrice[];
+}
+/** models.dev 补充的目录外模型价（USD / 1M tokens）。 */
+export interface ExtraModelPrice {
+    /** 归一化模型 id（计费键，如 `deepseek-v4.5-flash`）。 */
+    key: string;
+    /** 显示名。 */
+    name: string;
+    /** 厂商显示名（与仪表盘厂商组同口径）。 */
+    provider: string;
+    price: LivePrice;
 }
 /** 余额查询失败的原因，前端据此显示文案。 */
 export type BalanceError = 'unconfigured' | 'unauthorized' | 'unreachable';
@@ -86,4 +102,38 @@ export interface SubscriptionPlanConfig {
     /** Z.ai region override; defaults to the settings-namespace `zaiRegion`. */
     region?: 'global' | 'bigmodel-cn';
 }
+/**
+ * 余额提取规则：从响应 JSON 取数。
+ * - `const`：数字常量；
+ * - `path`：点路径取值（如 `data.total_available`）；
+ * - `op: 'add' | 'subtract'` + `paths`：多路径加 / 减；
+ * - `op: 'divide'` + `path` + `by`：按除数缩放（适配 NewApi 等 quota 端点，
+ *   如 1 USD = 500000 quota）。
+ */
+export interface CustomBalanceExtract {
+    const?: number;
+    path?: string;
+    op?: 'add' | 'subtract' | 'divide';
+    paths?: readonly string[];
+    by?: number;
+}
+/** 一个自定义 Provider 余额查询配置（插件 config 的 `customBalances` 条目）。 */
+export interface CustomBalanceConfig {
+    /** 显示名（中文）。 */
+    label: string;
+    /** 显示名（英文）；缺省用 label。 */
+    labelEn?: string;
+    /** 余额币种（如 CNY / USD）；缺省 CNY。 */
+    unit?: string;
+    /** 查询端点（完整 URL）。 */
+    url: string;
+    /** HTTP 方法；缺省 GET。 */
+    method?: string;
+    /** 请求头；值支持 `{{ENV_NAME}}` 占位符，经凭据 seam 解析（仅请求头支持）。 */
+    headers?: Record<string, string>;
+    /** 余额提取规则。 */
+    extract: {
+        remaining: CustomBalanceExtract;
+    };
+}
 //# sourceMappingURL=pricing-shared.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.5.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -48,6 +48,7 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/dsh-api-remotes": "*",
+    "@deepseek-ai/dsh-atomic-write": "*",
     "@deepseek-ai/dsh-client-connection": "*",
     "@deepseek-ai/dsh-host-webserver": "*",
     "@deepseek-ai/dsh-client-locale": "*",
@@ -62,6 +63,7 @@
     "@deepseek-ai/dsh-session": "*",
     "@deepseek-ai/dsh-session-persistence": "*",
     "@deepseek-ai/dsh-settings": "*",
+    "@deepseek-ai/dsh-tools": "*",
     "@deepseek-ai/schemastery": "*",
     "@deepseek-ai/cordis": "*",
     "react": "^18.2.0"