@kenz1117/dsh-ui-usage-billing 1.0.28 → 1.0.29

package/lib/types/aggregate.d.ts

@@ -10,6 +10,7 @@
  * zero while their tokens still count. Pure functions only: the persistence
  * handle is injected, so the fold is unit-testable without a host.
  */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
 import type { TokenUsage } from '@deepseek-ai/dsh-llm';
 import { MODEL_KEY_ALIASES, resolveCatalogKey } from './client/pricing.ts';
@@ -17,9 +18,9 @@ export { MODEL_KEY_ALIASES, resolveCatalogKey };
 /**
  * 走订阅套餐（coding / token plan / opencode 订阅）的 provider id：这些通道的
  * 调用按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
- * 与 pi-ai 内置提供方对齐（含各地区变体：qwen/xiaomi 的 token-plan、opencode 与
- * opencode-go、zai-coding-cn）；部署可在 plugin config 的 `subscriptionProviders`
- * 中覆盖。
+ * 此列表保留为显式配置的参考基线；聚合层缺省改用与订阅卡一致的
+ * `isSubscriptionProviderId` 判定（覆盖本列表与全部 `*-token-plan` / `*-coding` 变体），
+ * 部署仍可在 plugin config 的 `subscriptionProviders` 中显式覆盖。
  */
 export declare const DEFAULT_SUBSCRIPTION_PROVIDERS: readonly string[];
 /**
@@ -28,6 +29,23 @@ export declare const DEFAULT_SUBSCRIPTION_PROVIDERS: readonly string[];
  * 调用与费用分桶展示；部署可由配置覆盖（见 {@link AggregateOptions}）。
  */
 export declare function isOfficialProvider(provider: string): boolean;
+/** DeepSeek 官方直连端点的归一化 origin（`siteOriginOf` 口径）：有 baseURL 的路由只有它算官方。 */
+export declare const OFFICIAL_DEEPSEEK_ORIGIN = "https://api.deepseek.com";
+/**
+ * 官方渠道判定（通道优先）：显式 `officialProviderIds` 配置最优先；否则看站点归组——
+ * 有 baseURL 的路由只有 origin 为 DeepSeek 官方域才算官方（修复：名为 `deepseek-*`
+ * 的中转/网关路由曾被按 id 前缀误判为官方，腾讯网关的 DeepSeek 全被计成官方渠道）；
+ * 直连路由（配置在册、无 baseURL）退回按 provider id 前缀判定；**不在当前配置里的
+ * 未知路由一律不算官方**（无法核实通道，不装确定——历史路由用 `routeAliases` 归位）。
+ */
+export declare function officialChannelOf(provider: string, ref: SiteRef, officialProviderIds?: ReadonlySet<string>): boolean;
+/**
+ * 订阅制 provider 匹配器：显式列表（配置覆盖）或判定函数（默认
+ * {@link isSubscriptionProviderId}，与订阅卡识别同一正则口径，修复两者不一致）。
+ */
+export type SubscriptionMatcher = ReadonlySet<string> | ((provider: string) => boolean);
+/** 一个 provider 是否走订阅套餐计费（豁免按 token 计价）。 */
+export declare function isSubscriptionCall(subscription: SubscriptionMatcher, provider: string): boolean;
 /** 一个 provider 路由的站点视图（来自 llm-pi-ai providers 的 baseURL）。 */
 export interface ProviderRouteView {
     /** 该路由配置的端点地址；无值 = 直连厂商（非中转站）。 */
@@ -58,10 +76,16 @@ export declare function siteRefOf(provider: string, routes: Readonly<Record<stri
 export declare function siteBucketKey(ref: SiteRef): string;
 /** Aggregation tuning options. */
 export interface AggregateOptions {
-    /** 订阅制 provider id 列表；默认 {@link DEFAULT_SUBSCRIPTION_PROVIDERS}。 */
+    /** 订阅制 provider id 列表；缺省按订阅卡同款 id 判定（`isSubscriptionProviderId`）。 */
     subscriptionProviders?: readonly string[];
-    /** 官方渠道 provider id 列表；默认按 {@link isOfficialProvider} 判定（DeepSeek 官方直连）。 */
+    /** 官方渠道 provider id 列表；缺省按 {@link officialChannelOf} 判定（通道 origin 优先）。 */
     officialProviderIds?: readonly string[];
+    /**
+     * 历史路由别名（旧路由名 → 当前路由名）：改过名 / 删除过的 provider 路由，
+     * 其历史用量原会落「未知路由」桶；配置别名后按目标路由归组（站点、订阅、
+     * 官方判定都用别名后的路由名）。
+     */
+    routeAliases?: Readonly<Record<string, string>>;
     /** 每会话折叠缓存的上限（默认 {@link DEFAULT_MAX_CACHE_SESSIONS}）；
      *  超限时按最近使用先后淘汰最久未用的会话，防长期运行内存膨胀。 */
     maxCacheSessions?: number;
@@ -155,11 +179,15 @@ export declare const UNKNOWN_WORKSPACE_NAME = "\u2014";
 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; `locate`
- * is optional — backends exposing it give the incremental cache a cheap
- * invalidation stamp (artifact mtime + size), others always re-fold.
+ * `SessionPersistence` to list sessions and read each log once. Two
+ * optional invalidation-stamp sources, checked in order:
+ * `stampOf` (host 0.1.3+: the persistence revision token, exposed by the
+ * host-shape adapter) then `locate` (host 0.1.2: artifact mtime + size).
+ * Neither present means every round re-folds.
  */
-export type UsagePersistence = Pick<SessionPersistence, 'list' | 'readFrom'> & Partial<Pick<SessionPersistence, 'locate'>>;
+export type UsagePersistence = Pick<SessionPersistence, 'list' | 'readFrom'> & Partial<Pick<SessionPersistence, 'locate'>> & Partial<{
+    stampOf(id: SessionId): Promise<string | null>;
+}>;
 /** The usage-stats document served to the billing dashboard. */
 export interface UsageStatsDocument {
     version: number;
@@ -429,7 +457,7 @@ export interface UsageLedgerDocument {
  * 会话费用只剩最近一段，issue #29）。
  * 持久账本行据此区分新旧算法：日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
  */
-export declare const FOLD_VERSION = 7;
+export declare const FOLD_VERSION = 8;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并
@@ -470,9 +498,9 @@ export declare function messageTextLength(message: unknown): number;
  * 兜底到最近一次 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.
+ * @param subscriptionProviders - 订阅套餐匹配器（显式集合或判定函数）。
  * @param officialProviderIds - provider ids treated as the official DeepSeek channel
- *   (default: any `deepseek`-prefixed id). Others count as third-party.
+ *   (default: channel-origin based via {@link officialChannelOf}). Others count as third-party.
  * @param routes - 当前 provider 路由视图（中转站归组）。
  * @param searchCallEstimateCny - 联网搜索请求的单次费用估算（人民币元；0 关闭估算）。
  * @param seedLength - 持久化的 fork 血缘边界（存储元数据 `inheritedEventCount`，缺省 0）：
@@ -486,7 +514,7 @@ export declare function foldSession(events: readonly {
     time: number;
     data: unknown;
     seq?: number;
-}[], subscriptionProviders: ReadonlySet<string>, officialProviderIds?: ReadonlySet<string>, routes?: Readonly<Record<string, ProviderRouteView>>, searchCallEstimateCny?: number, seedLength?: number): SessionFold;
+}[], subscriptionProviders: SubscriptionMatcher, officialProviderIds?: ReadonlySet<string>, routes?: Readonly<Record<string, ProviderRouteView>>, searchCallEstimateCny?: number, seedLength?: number, routeAliases?: Readonly<Record<string, string>>): SessionFold;
 /**
  * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——
  * 日志没动的会话直接复用，只有写过的会话重新折叠；整份文档另有短 TTL

package/lib/types/balance.d.ts

@@ -33,26 +33,6 @@ export declare function pickTokenDanceBalanceCny(data: unknown): number | undefi
 export declare function queryBalances(ctx: Context, providers: Readonly<Record<string, {
     apiKeyEnv?: string;
 }>>): Promise<readonly ProviderBalance[]>;
-/**
- * 构造云 API 3.0 TC3-HMAC-SHA256 签名（官方签名方法 v3）。导出供测试：纯函数，
- * 输入确定则签名确定。Action 不参与签名——它走 `X-TC-Action` 请求头。
- * @param secretId - 云 API SecretId。
- * @param secretKey - 云 API SecretKey。
- * @param payload - 已序列化的请求体（含 Action/Version/Region 公共参数）。
- * @param timestamp - 签名时间戳（秒）。
- * @returns Authorization 头的值。
- */
-export declare function tc3Authorization(secretId: string, secretKey: string, payload: string, timestamp: number): string;
-/**
- * 在套餐余量对象里防御性提取「剩余额度」：官方 SubPackageBalance/PackageInfo
- * 的字段名未稳定公开（issue #18 调研期），按语义键名扫描——命中 remaining /
- * balance / left 语义键直接用；命中 total 与 used 则相减推导。数字一律经
- * {@link toNumber} 归一化（上游可能给字符串）。
- * 导出供测试：纯函数。
- * @param source - 套餐详情里的余量对象（PackageInfo / SubPackageBalance 等）。
- * @returns 剩余额度（上游单位，通常为 token 数或元）；提取不到返回 undefined。
- */
-export declare function pickRemainingQuota(source: unknown): number | undefined;
 /**
  * 按 extract 规则从响应 JSON 求值。导出供测试：纯函数。
  * @param rule - 提取规则（const / path / add / subtract / divide）。

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

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'trendEmpty' | 'budget' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'project' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'triggerMonthTokens' | 'subscriptionsStale' | 'staleLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'workspaces' | 'workspacesHint' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionIncluded' | 'free' | 'official' | 'thirdParty' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapMonth' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginVersion' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenCacheHitRate' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown';
+export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'trendEmpty' | 'budget' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'project' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'triggerMonthTokens' | 'subscriptionsStale' | 'staleLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'workspaces' | 'workspacesHint' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionIncluded' | 'free' | 'official' | 'thirdParty' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapMonth' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginVersion' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenCacheHitRate' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown';
 export 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

@@ -26,6 +26,12 @@ import type { LivePricing } from '../pricing-shared.ts';
  * live rate arrives the built-in value stays in force.
  */
 export declare const USD_TO_CNY = 6.79;
+/**
+ * 注入用户自定义模型别名（node 半区在插件启动时调用一次）。纯内存状态：
+ * 聚合折叠与客户端渲染共用同一份（两侧一致性由同一注入点保证）。
+ * @param aliases - `model id → 目录键` 映射；undefined/空 = 清除，回退内置表。
+ */
+export declare function applyUserModelAliases(aliases: Readonly<Record<string, string>> | undefined): void;
 /**
  * 用户自定义单价（设置面板录入，localStorage 持久化）：覆盖内置/models.dev/
  * dsh-spend 的全部价格来源，用于新模型上线目录未跟、或厂商未公布按量价的场景。
@@ -324,14 +330,6 @@ export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
  * @returns 归一化键（字母数字小写串）。
  */
 export declare function canonModelId(id: string): string;
-/**
- * 解析真实日志模型 id → 计费目录键。先精确别名映射（既有行为）；未命中时做
- * 归一化匹配（忽略大小写/分隔符/括号附注），命中内置目录 / 别名目标 / 兜底键 /
- * models.dev 补充键即返回其真实键；完全未知时保持原样（回退 other，不计费）。
- * 供聚合层折叠与客户端渲染共用，两侧一致。
- * @param id - 真实模型 id（日志里出现的形式）。
- * @returns 计费目录键。
- */
 export declare function resolveCatalogKey(id: string): string;
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 export declare function modelOf(key: string): ModelEntry;

package/lib/types/client/provider-display.d.ts

@@ -17,5 +17,12 @@ type ProviderLang = 'zh' | 'en';
 export declare function localizeProviderName(name: string, lang: ProviderLang): string;
 /** 判断一个厂商显示名是否包含中文（用于测试/守卫：保证映射覆盖完整）。 */
 export declare function hasCjk(name: string): boolean;
+/**
+ * 站点桶 key（`site:<origin>` / `direct:<provider>` / `unknown`）→ 通道显示名。
+ * @param siteKey - 聚合文档 bySite 的桶 key。
+ * @param lang - 显示语言；zh（缺省）用内置中文名，en 走英文章表。
+ * @returns 未知路由桶返回 undefined（渲染层用 locale 文案兜底）。
+ */
+export declare function channelDisplayName(siteKey: string, lang?: ProviderLang): string | undefined;
 export {};
 //# sourceMappingURL=provider-display.d.ts.map

package/lib/types/index.d.ts

@@ -13,7 +13,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 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 UsageLedgerStore } from './aggregate.ts';
+import { type UsageLedgerStore, type UsagePersistence } from './aggregate.ts';
 import type { CustomBalanceConfig, DeclaredEndpointConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
 /**
@@ -65,6 +65,18 @@ export interface UsageBillingConfig {
      * 计费但本地日志无 usage，按次估值计入今日/本月费用；默认 0.02 元/次，设 0 关闭。
      */
     searchCallEstimateCny?: number;
+    /**
+     * 历史路由别名（旧 provider 路由名 → 当前路由名）：改过名/删除过的路由，其
+     * 历史用量原会落「未知路由」桶且站点/订阅/官方判定全部失效；配置别名后按
+     * 目标路由归位。例：`{ "deepseek-official": "tencent", "tencent-cloud": "tencent" }`。
+     */
+    routeAliases?: Record<string, string>;
+    /**
+     * 用户自定义模型别名（真实日志 model id → 计费目录键）：目录外的新模型无需
+     * 等发版，配置一条别名即完成识别与计价（值必须是 MODEL_CATALOG 的既有 key，
+     * 如 `{ "hy4-preview": "hunyuan" }`）。聚合折叠与客户端渲染共用同一映射。
+     */
+    modelKeyAliases?: Record<string, string>;
 }
 /**
  * Create the atomic file-backed durable-ledger store. The previous complete file
@@ -107,6 +119,17 @@ export declare function resolveSubscriptionKeys(settings: SettingsProvider, cred
     keys: SubscriptionKeys;
     identified: IdentifiedSubscriptionPlan[];
 }>;
+/**
+ * 宿主 persistence 形状适配。宿主 0.1.3 起 SessionPersistence 改为
+ * SessionHandle 模型（open(id,'read') 后经 handle.read(offset) 读，fork 边界
+ * 挂在 handle.inheritedEventCount，list 返回 {header, revision} 快照行，
+ * 0.1.2 的 readFrom/locate 消失）。这里按结构探测把两种宿主形状都收敛为
+ * 聚合层期望的 0.1.2 面貌：0.1.2 直接带 readFrom 的原样直通；0.1.3 的
+ * 读取转为 open → handle.read，revision 令牌经 stampOf 暴露给增量缓存。
+ * 候选时刻的运行时对象是宿主注入的外部形状，结构断言即 durable 收窄点。
+ * 导出供测试：纯函数（不触 ctx）。
+ */
+export declare function adaptSessionPersistence(raw: unknown): UsagePersistence;
 /**
  * Host plugin body: serve real aggregated usage to the browser dashboard.
  * @param ctx - host context carrying webServer and sessionPersistence.

package/lib/types/subscriptions.d.ts

@@ -24,6 +24,8 @@ export interface SubscriptionKeys {
     minmaxApiKey: string;
     /** OpenRouter API key（credits 已用%）。 */
     openrouterApiKey: string;
+    /** 腾讯云云 API 密钥对（`<SecretId>:<SecretKey>`，管控面用，非 TokenHub 推理 key）。 */
+    tencentCloudApi: string;
     /** Z.ai 区域（global / bigmodel-cn）。 */
     zaiRegion: 'global' | 'bigmodel-cn';
 }

package/lib/types/tc3.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tencent Cloud TokenHub control-plane access (cloud API 3.0, TC3-HMAC-SHA256).
+ *
+ * Shared by two surfaces that read the same Token Plan:
+ * - `balance.ts` — the balance row (absolute remaining quota);
+ * - `subscriptions.ts` — the subscription card (monthly window + plan name).
+ *
+ * Credentials are a cloud API key pair (`<SecretId>:<SecretKey>`), NOT the
+ * TokenHub inference key. Field names on the control plane are not fully
+ * stable, so parsing stays defensive (semantic-key scanning).
+ */
+/** TokenHub 管控面 API 端点（cloud.tencent.cn/document/api/1823/132270）。 */
+export declare const TOKENHUB_HOST = "tokenhub.tencentcloudapi.com";
+/** 管控面调用超时（毫秒）：余额与订阅面板共用同一预算。 */
+export declare const TOKENHUB_TIMEOUT_MS = 8000;
+/** 腾讯云凭据引用值格式：`<SecretId>:<SecretKey>`（分隔符取首个冒号）。 */
+export declare function parseTencentCredential(value: string): {
+    secretId: string;
+    secretKey: string;
+} | undefined;
+/**
+ * 构造云 API 3.0 TC3-HMAC-SHA256 签名（官方签名方法 v3）。导出供测试：纯函数，
+ * 输入确定则签名确定。Action 不参与签名——它走 `X-TC-Action` 请求头。
+ * @param secretId - 云 API SecretId。
+ * @param secretKey - 云 API SecretKey。
+ * @param payload - 已序列化的请求体（含 Action/Version/Region 公共参数）。
+ * @param timestamp - 签名时间戳（秒）。
+ * @returns Authorization 头的值。
+ */
+export declare function tc3Authorization(secretId: string, secretKey: string, payload: string, timestamp: number): string;
+/**
+ * 调用一次 TokenHub 管控面接口：TC3 签名 + 超时保护，返回响应 JSON 的 `Response`。
+ * 业务错误（Response.Error）与 HTTP 层错误都带 `code` 抛出，调用方按
+ * unauthorized / unreachable / invalid 归类。
+ */
+export declare function callTokenHub(secretId: string, secretKey: string, action: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+/** 数字归一化：上游可能给字符串数字；非有限数返回 undefined。 */
+export declare function toNumber(value: unknown): number | undefined;
+/**
+ * 在套餐余量对象里防御性提取「剩余额度」：官方 SubPackageBalance/PackageInfo
+ * 的字段名未稳定公开（issue #18 调研期），按语义键名扫描——命中 remaining /
+ * balance / left 语义键直接用；命中 total 与 used 则相减推导。数字一律经
+ * {@link toNumber} 归一化（上游可能给字符串）。
+ * 导出供测试：纯函数。
+ * @param source - 套餐详情里的余量对象（PackageInfo / SubPackageBalance 等）。
+ * @returns 剩余额度（上游单位，通常为 token 数或元）；提取不到返回 undefined。
+ */
+export declare function pickRemainingQuota(source: unknown): number | undefined;
+/**
+ * 防御性提取「总额度」：语义键 total / limit / quota。与
+ * {@link pickRemainingQuota} 配对使用——两者都能取到时订阅卡才能算出
+ * 已用百分比窗口；只有剩余值时窗口保持为空（绝不猜总额度）。
+ * 注意排除键名：`RemainingQuota` / `UsedQuota` 这类键同样含 quota 子串，
+ * 必须先剔除剩余 / 已用语义，否则会把剩余值误当总额度（有单测守卫）。
+ * @param source - 套餐详情里的额度对象（PackageInfo / SubPackageBalance 等）。
+ */
+export declare function pickTotalQuota(source: unknown): number | undefined;
+/** 套餐列表里提取第一个启用套餐的 TeamId：集合字段名做候选兼容。 */
+export declare function firstEnabledTeamId(inner: Record<string, unknown>): string | undefined;
+//# sourceMappingURL=tc3.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": "1.0.28",
+  "version": "1.0.29",
   "keywords": [
     "deepseek-harness",
     "deepseek",
@@ -59,7 +59,8 @@
         "0.1.2-alpha.3": "compatible",
         "0.1.2-alpha.4": "compatible",
         "0.1.2-alpha.5": "compatible",
-        "0.1.2-rc.1": "compatible"
+        "0.1.2-rc.1": "compatible",
+        "0.1.3-alpha.1": "compatible"
       }
     }
   },