@kenz1117/dsh-ui-usage-billing 1.1.13 → 1.2.0

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,25 @@ 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
+ * 前缀判定——宿主内置的官方直连不经 llm-pi-ai 路由，其 provider 名不在路由表中，
+ * 按 unknown 一刀切会把它错杀成三方（回归修复）；配置外的同名网关残留可用
+ * `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 {
     /** 该路由配置的端点地址；无值 = 直连厂商（非中转站）。 */
@@ -49,19 +69,33 @@ export declare function siteOriginOf(baseURL: string): string;
  * 把一个 provider 路由归类为站点引用。判定顺序（与路由在 provider 配置里的状态一致）：
  * - 路由存在于当前配置且配了 baseURL → 中转站 `site`（按 origin 归组，同站多 key 合并）；
  * - 路由存在于当前配置但无 baseURL → 厂商直连 `direct`；
- * - 路由不在当前配置里 → `unknown`（改过名 / 删除过，是「读不到」而非「直连」）。
+ * - 路由不在当前配置里：内置官方直连（`deepseek` / `deepseek-*` 形态，不经 llm-pi-ai
+ *   网关）按 `direct` 归位——unknown 一刀切会把官方直连的费用堆进「未知路由」组、
+ *   且不算官方渠道（回归修复）；订阅豁免命中的通道（显式 `subscriptionProviders`
+ *   配置或判定函数）同样按 `direct` 归位——订阅管理类插件注册的通道不经路由表，
+ *   unknown 桶既掩盖归属又按 token 误计费（issue #37 的 grok build）；其余配置外
+ *   名称保留 unknown（无法核实通道）。
  * @param provider - 会话日志里的 provider 路由名（request/header 的 `config.provider`）。
  * @param routes - 当前 provider 路由视图（来自 llm-pi-ai providers）。
+ * @param opts - `subscription`：该调用是否已被订阅豁免判定命中。
  */
-export declare function siteRefOf(provider: string, routes: Readonly<Record<string, ProviderRouteView>>): SiteRef;
+export declare function siteRefOf(provider: string, routes: Readonly<Record<string, ProviderRouteView>>, opts?: {
+    subscription?: boolean;
+}): 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}。 */
+    /** 订阅制 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 +189,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;
@@ -220,6 +258,8 @@ export interface UsageStatsDocument {
      * 以 step/start 为起点估算并计 estimated。
      */
     perf?: PerfStats;
+    /** 只存在于账本、且缺 foldVersion 的旧会话数；无旧行时省略。 */
+    staleLedgerSessions?: number;
 }
 /** 按角色费用归因：user / tool 为输入成本的启发式摊分，assistant 为输出成本实测。 */
 export interface RoleCost {
@@ -234,8 +274,8 @@ export interface RoleCost {
 export interface PerfStats {
     /** 按模型聚合（键 = 计费目录键；未收录模型原样保留）。 */
     byModel: Record<string, ModelPerf>;
-    /** 按小时聚合（键 = {@link hourStamp}，北京时间）。 */
-    byHour: Record<string, HourPerf>;
+    /** 按小时×模型聚合（外键 = {@link hourStamp}，内键 = 模型目录键；北京时间）。 */
+    byHourModel: Record<string, Record<string, HourModelPerf>>;
 }
 /** 一个模型的性能统计：首字延时均值 / P50 / P90、生成速度均值、总延迟均值。 */
 export interface ModelPerf {
@@ -258,11 +298,11 @@ export interface ModelPerf {
     /** 以 step/start 估算的样本数（工具续写步骤无独立 request/header）。 */
     estimatedSamples: number;
 }
-/** 一个小时的性能统计（键 = {@link hourStamp}）。 */
-export interface HourPerf {
+/** 一个小时单模型的性能统计（外键 = {@link hourStamp}，内键 = 模型目录键）。 */
+export interface HourModelPerf {
     samples: number;
     ttftAvg: number;
-    /** 平均生成速度（tokens/s）；该小时无可测生成窗口时缺失。 */
+    /** 平均生成速度（tokens/s）；该小时该模型无可测生成窗口时缺失。 */
     tpsAvg?: number;
 }
 /** 会话明细行：仪表盘「会话明细」面板的数据源。 */
@@ -383,6 +423,8 @@ export interface SerializedSessionFold {
     byModel: Record<string, ModelUsage>;
     byDay: Record<string, ModelUsage>;
     byDayModels: Record<string, Record<string, ModelUsage>>;
+    /** 会话标题（session/title 事件的最新文本）；1.0.30 前的账本行不持久化它，缺失回退 id。 */
+    title?: string;
     /** 1.0.10（issue #16）新增；模型×日期×站点三维，旧账本行缺失（合并按空处理）。 */
     byDayModelsSite?: Record<string, Record<string, Record<string, ModelUsage>>>;
     /** 1.0.8 起新增；旧账本行缺失（合并时按空处理，不触发重折算）。 */
@@ -407,6 +449,11 @@ export interface UsageLedgerSession {
      * 旧算法行（加载边界由迁移统一回填为 1）。
      */
     foldVersion?: number;
+    /**
+     * 折叠该行时的聚合配置指纹（{@link configFingerprint}）。缺失 = 1.0.32 及
+     * 更早写入的行（配置不参与复用判定）；与当前指纹不一致的行不复用、全量重折。
+     */
+    fingerprint?: string;
     fold: SerializedSessionFold;
 }
 /** On-disk durable usage ledger. Versioned independently from the dashboard document. */
@@ -422,17 +469,16 @@ export interface UsageLedgerDocument {
  * 两次 header 之间的用量串到上一个模型，订阅模型首当其冲，issue #14）；v2 =
  * `assistant/message` 自带 source 归账（1.0.7 起）；v3 = 联网搜索请求按次估算
  * 计费（issue #15，1.0.9 起）；v4 = 模型×日期×站点三维桶（issue #16，按 origin
- * 绑定自定义价的显示层重估）——旧行缺该维度，按无 origin 价处理；
- * v6 = fork 种子边界改用持久化 `SessionHeader.seedLength`（5 及更早扫描最后一个
+ * 绑定自定义价的显示层重估）——旧行缺该维度，按无 origin 价处理；v5 = 峰谷
+ * 时代之前（2026-08-16T16:00Z）的 DeepSeek 事件按当时基础价计费（v4 把全部
+ * 历史套现行峰/谷档价，高估约 50%）；v6 = v1 峰谷窗口（至 2026-08-22T16:00Z）
+ * 的周末不豁免峰时（v5 错套现行周末全谷规则，低估该窗口周六日的峰时费用）；
+ * v7 = fork 种子边界改用持久化 `SessionHeader.seedLength`（v6 及更早扫描最后一个
  * `session/end-seed`，resume 续写后继续对话时把本会话历史段误判为种子丢弃，
  * 会话费用只剩最近一段，issue #29）。
  * 持久账本行据此区分新旧算法：日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
- * 8：官方公告自 2026-09-10 12:00（北京）起 V4 Pro 请求路由至 V4.1 Flash 按 Flash
- * 单价计费（V4.1 Pro 上线前）——pro 目录价改写为 Flash 价、V4 Pro 刊例（峰
- * 9/0.3/27、谷 4.5/0.15/13.5）进 FLASH_REPRICED_OFFPEAK 供分界前回算；v7 及更早
- * 的行把分界后的 pro 全部按 V4 Pro 刊例折算（高估数倍），bump 全量重折对齐时间线。
  */
-export declare const FOLD_VERSION = 8;
+export declare const FOLD_VERSION = 13;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并
@@ -473,15 +519,15 @@ 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 血缘边界（`SessionHeader.seedLength`，缺省 0）：
+ * @param seedLength - 持久化的 fork 血缘边界（存储元数据 `inheritedEventCount`，缺省 0）：
  *   fork 子会话日志里 `seq < seedLength` 的事件拷贝自父会话、已在父会话计费，
  *   折叠时跳过以避免重复计费；resume 续写复用同一会话日志（每次续写追加一个
- *   `session/end-seed` 标记）但 header 保持原 fork 值，历史段照常计费。
+ *   `session/end-seed` 标记）但继承切割保持原值，历史段照常计费。
  * @returns the per-session fold (cached by the incremental aggregator).
  */
 export declare function foldSession(events: readonly {
@@ -489,7 +535,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
@@ -505,6 +551,13 @@ export interface UsageAggregator {
      *  进行中的聚合先等完再存，折叠失败仍保存已成功部分。 */
     flush(): Promise<void>;
 }
+/**
+ * 聚合配置指纹：影响折叠语义的全部配置（订阅豁免、官方名单、路由别名、搜索估值）
+ * 的稳定序列化。账本行的复用判定携带该指纹——用户改配置后（如为 grok build 加
+ * 订阅豁免），历史账本行立即失效并全量重折，配置变更即时生效（issue #37）。
+ * 判定函数无法序列化，统一记为 `fn`（任何函数形态互视为同一指纹）。
+ */
+export declare function configFingerprint(subscriptionMatcher: SubscriptionMatcher, officialProviderIds: ReadonlySet<string> | undefined, routeAliases: Readonly<Record<string, string>>, searchEstimate: number): string;
 /**
  * Create the incremental usage aggregator.
  * @param persistence - the session persistence service.

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

@@ -1,12 +1,13 @@
 /**
- * PerfPanel: per-model latency/perf table + per-hour TTFT/generation-speed curve.
+ * PerfPanel: per-model latency/perf table + per-hour per-model comparison 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.
+ * dependency-free SVG hourly curve: one colored polyline per lit model with a
+ * metric tab (TTFT ms / tok/s) and clickable model chips; hovering snaps to the
+ * nearest hour and shows a crosshair + tooltip listing every lit model's value.
+ * Absent `perf` renders an empty state; the panel never fabricates samples.
  */
 import type { TrendSeriesModel } from './TrendChart.tsx';
 import type { UsageBillingKey } from './locales.ts';
@@ -24,8 +25,8 @@ export interface PerfModelData {
     latencyAvg: number;
     estimatedSamples: number;
 }
-/** 每小时性能统计（与服务端 `HourPerf` 同形）。 */
-export interface PerfHourData {
+/** 小时×模型性能统计（与服务端 `HourModelPerf` 同形）。 */
+export interface PerfHourModelData {
     samples: number;
     ttftAvg: number;
     tpsAvg?: number;
@@ -33,12 +34,13 @@ export interface PerfHourData {
 /** 性能指标文档（服务端可选 `perf` 字段；旧快照缺失）。 */
 export interface ClientPerf {
     byModel: Record<string, PerfModelData>;
-    byHour: Record<string, PerfHourData>;
+    /** 小时 → 模型 → 小时统计；旧 host 文档缺失时图表区按空态兜底。 */
+    byHourModel: Record<string, Record<string, PerfHourModelData>>;
 }
 /**
  * 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.models - model legend (key/name/color) for the table swatches and curve chips.
  * @param props.t - locale function.
  */
 export declare function PerfPanel({ perf, models, t, }: {

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

@@ -1,23 +1,75 @@
 /**
  * TokenPanel: 「Token」分区——把 token 从费用里独立出来洞察。
  * 四个板块 + 导出，全部由 `UsageStats` 派生，服务端零改动：
- *  1. 每日 Token 堆叠趋势（未命中输入 / 缓存命中 / 输出[含 reasoning]），7/30 天切换；
- *  2. 模型 Token 总量排行 + 占比；
+ *  1. 每日 Token 趋势，双视角切换（7/30 天）：
+ *     - 按结构：未命中输入 / 缓存命中 / 输出[含 reasoning] 三桶堆叠；
+ *     - 按模型：每天按模型堆叠，段 = 该模型当日「模型总 Token」（输入[含命中] + 输出），
+ *       分色复用趋势页 `chartModels`（同模型同色跨页一致）；
+ *       旧快照缺 `byDayModels` 时隐藏切换钮，仅保留结构视角。
+ *     悬停显示当日精确明细；图例 / 「模型 Token」表格行可点击聚焦单个模型
+ *     （目标段保持原色，其余段弱化，y 轴不变）。
+ *     归因边界：reasoning 无按日 × 模型明细（`byDayModels` 无该字段），图与导出不含此列。
+ *  2. 模型 Token 总量排行 + 占比（行点击 = 聚焦该模型并切到按模型视角）；
  *  3. Token 结构 KPI（缓存命中率 / reasoning 占比 / 输入:输出比 / 峰值日）+ 显式缓存写入；
  *  4. 工具调用排行（byTool 计次；token 无法按工具归因）。
  */
 import type { UsageBillingKey } from './locales.ts';
+import type { TrendSeriesModel } from './TrendChart.tsx';
 import type { UsageStats } from './UsageBilling.tsx';
+/** 每日 token 堆叠图元（按结构视角）。 */
+interface DailyBucket {
+    date: string;
+    miss: number;
+    hit: number;
+    output: number;
+    reasoning: number;
+}
+/** 按模型视角下某模型某日的 token 明细（`byDayModels` 无 reasoning 列）。 */
+interface ModelDayCell {
+    hit: number;
+    miss: number;
+    output: number;
+    /** 命中 + 未命中 + 输出（= 模型总 Token 口径）。 */
+    total: number;
+}
+/** 按模型视角的一天：各模型段 + 当日合计。 */
+interface DayModelsRow {
+    date: string;
+    models: Record<string, ModelDayCell>;
+    total: number;
+}
+/** 模型 token 行。 */
+interface ModelTokenRow {
+    key: string;
+    name: string;
+    input: number;
+    output: number;
+    reasoning: number;
+    calls: number;
+    cacheHit: number;
+    cacheMiss: number;
+    cacheHitRate: number;
+    total: number;
+    /** 占总 token 比例（0..1）。 */
+    share: number;
+}
+/** 导出全量 JSON 文档：按日结构 + 模型排行 + 按日×模型明细 + 总量（无 reasoning 列）。 */
+export declare function tokenDailyJson(days: readonly DailyBucket[], models: readonly ModelTokenRow[], dayModels: readonly DayModelsRow[], total: UsageStats['total']): string;
 /**
  * Token 洞察面板。
- * @param props.stats - usage-stats 文档（byDay/byModel/total）。
+ * @param props.stats - usage-stats 文档（byDay/byModel/byDayModels/total）。
  * @param props.trendDays - 每日 token 窗口（7/30 天）。
  * @param props.onTrendDays - 切换趋势窗口。
+ * @param props.models - 趋势页同款模型图例（key/name/色）：按模型视角的分色来源；缺省用兜底灰。
  */
 export declare function TokenPanel(props: {
     stats: UsageStats;
     trendDays: 7 | 30;
     onTrendDays: (d: 7 | 30) => void;
+    models?: readonly TrendSeriesModel[];
+    /** 金额格式化（跟随仪表盘币种切换）：费用构成区块展示用。 */
+    money: (cny: number) => string;
     t: (key: UsageBillingKey) => string;
 }): React.ReactNode;
+export {};
 //# sourceMappingURL=TokenPanel.d.ts.map

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

@@ -10,7 +10,7 @@
  *（billing.dashboard.decor）并注册计费指标服务（ctx.billingMetrics），主题
  * 插件主动注入装饰视觉、消费费用数据——billing 不反向依赖任何主题包。
  */
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import type { Context } from '@deepseek-ai/cordis';
 import { type UsageBillingKey } from './locales.ts';
 import { type BillingMetricsService } from './billing-service.ts';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -45,11 +45,18 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
         usageBilling: UsageBillingKey;
     }
 }
-/** Required services for the usage billing surface. */
+/** Required services for the usage billing surface.
+ *
+ * `remote.llm` is deliberately NOT injected: the LLM remote namespace only
+ * exists on 0.1.2-alpha.1 hosts, and a pending injection blocks the whole
+ * web boot on older hosts. `checkModels` probes `ctx.remote.llm` defensively
+ * instead — on hosts without it the model health check degrades to the
+ * static catalog result (the surrounding try/catch already swallows the
+ * undefined access). */
 export declare const inject: string[];
 /**
  * Client plugin body: the UsageBilling entry in the sidebar footer.
  * @param ctx - client root context.
  */
-export declare function apply(ctx: ClientContext): void;
+export declare function apply(ctx: Context): void;
 //# sourceMappingURL=apply.d.ts.map

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

@@ -5,7 +5,7 @@
  * store 引擎持久化到 localStorage（persist key 即存储身份），重启后保留。
  * 宿主 Config 的 monthlyBudget 仅作为金额未设置时的默认值，用户输入优先。
  */
-import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-store';
 /** 预算偏好状态。 */
 export interface BudgetPrefsState {
     /** 预算条开关：关 = 只显示标题行与开关，不显示进度。 */

package/lib/types/client/completion-notify.d.ts

@@ -5,8 +5,8 @@
  * 可选：跨 tab 只保留一个提醒 leader（Web Locks 优先，降级 localStorage 租约），
  * 避免多窗口同时弹同一条。配置持久化在 localStorage（默认关闭，用户在面板设置开启）。
  */
-import type { SessionListState } from '@deepseek-ai/dsh-client-runtime/client';
-import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
 /** 配置持久化 key：开启/关闭 + 提醒持续模式（0=常驻，其余=秒后自动关）。 */
 export declare const COMPLETION_NOTIFY_KEY = "dsh-billing-completion-notify-v1";
 export interface CompletionNotifyConfig {

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

@@ -6,17 +6,16 @@
  * composer card, same posture as ui-conversation's own StatsLine), so it stays
  * visible while working without opening the full dashboard. Data comes from the
  * same `/api/billing/usage-stats` endpoint the dashboard polls; the bar reads
- * 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 current session id from the session-scope standard kit and matches
+ * `bySession` (session total) and `byTurn` (latest turn cost). Rendering is a
+ * pure function of props and polled data, 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 { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { UsageBillingKey } from './locales.ts';
 /** The usage-stats shape the composer bar needs (a thin slice, not the whole doc). */
 export interface LiveStats {
@@ -67,15 +66,26 @@ export declare function lowQuotaChips(quotas: readonly QuotaSlice[], threshold?:
     kind: string;
     pct: number;
 }[];
-/** Props: the session-scope snapshot selector the framework injects. */
+/** Props: the framework's session identity plus the owning dock's locale seat. */
 export interface LiveCostBarProps {
-    useSession: SnapshotSelectorHook<ConversationSnapshot>;
+    /** Current Session identity supplied by the session-scope standard kit. */
+    sessionId: SessionId;
     /** The owning dock's locale seat (bound to the billing NS). */
     t: (key: UsageBillingKey) => string;
 }
 /**
  * Render the live cost ticker for the current session.
- * @param props - framework session snapshot hook and locale.
+ * @param props - framework session identity and locale.
  */
-export declare function LiveCostBar({ useSession, t }: LiveCostBarProps): React.ReactNode;
+export declare function LiveCostBar({ sessionId, t }: LiveCostBarProps): React.ReactNode;
+/**
+ * Render the compact inline chip for the composer tool row (position
+ * 「模型选择前」). Occupies a fixed minimal footprint — tier glyph + session
+ * spend — so it never crowds the model picker; the full breakdown (switch
+ * countdown, turn cost, quota alerts) rides the host Tooltip primitive (the
+ * native title never renders in the webview), and a low quota tints the chip
+ * amber/red instead of growing it.
+ * @param props - framework session identity and locale.
+ */
+export declare function LiveCostChip({ sessionId, t }: LiveCostBarProps): React.ReactNode;
 //# sourceMappingURL=live-cost.d.ts.map

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

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'title' | 'subtitle' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'totalCost' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'trendEmpty' | 'budget' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'project' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'estimated' | 'actual' | 'pricing' | 'showPricing' | 'hidePricing' | 'pricePerM' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'peakHours' | 'band' | 'openDashboard' | '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' | 'subscriptions' | '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' | 'floatPrev' | 'floatNext' | 'subscriptionsStale' | 'staleLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemove' | 'sessionStaleBadge' | 'sessionUntitled' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'workspaces' | 'workspacesHint' | 'plan' | 'remaining' | 'unknownModel' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'currentRound' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabDetails' | 'tabPricing' | 'tabSettings' | 'settingsHead' | 'settingsHint' | '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' | 'officialCost' | 'thirdPartyCost' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'heatmapYear' | 'heatmapMonth' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginInfo' | 'pluginName' | 'pluginDescription' | 'pluginVersion' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenCacheHitRate' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popQuotaAlert' | 'popRiskNone' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'popBalanceNormal' | 'popBalanceLow' | 'popQuotaNormal' | 'popQuotaLow' | 'alertBalanceLow' | 'alertQuotaLow' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'exportCsvSite' | 'panelRelay' | 'relaySite' | 'relayDirect' | 'relayUnknown' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'relayCalls';
+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' | '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' | 'sessionUntitled' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | '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' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapMonth' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | '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 的全部价格来源，用于新模型上线目录未跟、或厂商未公布按量价的场景。
@@ -41,6 +47,12 @@ export interface UserPrice {
     output: number;
     /** 计价币种；缺省 CNY。 */
     currency?: 'CNY' | 'USD';
+    /** 低谷档三桶（元或美元 / 每百万 token）；缺省 = 平档（峰谷同价）。 */
+    offPeak?: {
+        input: number;
+        cacheHit: number;
+        output: number;
+    };
 }
 /** 一条用户自定义价：绑定「模型（计费目录键）+ 可选来源（中转站 origin）」。
  *  origin 缺省 = 该模型的默认价；带 origin = 仅该中转站的同名模型用此价。 */
@@ -50,6 +62,22 @@ export interface UserPriceEntry extends UserPrice {
     /** 绑定来源（中转站 origin，如 `https://api.my-relay.com`）；缺省 = 默认价。 */
     origin?: string;
 }
+/**
+ * 中转站 origin 宽松匹配：双方规范化到 `protocol://host[:port]` 后比较。
+ * 宿主侧站点桶的 origin 来自 `new URL(baseURL).origin`，用户手填的来源常缺
+ * 协议、带路径或尾斜杠——精确全等会让自定义价静默失效（issue #18）。
+ * 规范化失败（无法解析成 URL）时回退小写去尾斜杠的字面比较。
+ * @param a - 用户录入的来源（可缺协议/带路径）。
+ * @param b - 宿主站点桶的 origin（`new URL().origin` 形态）。
+ */
+/**
+ * 把用户手填的中转站来源规范化为 `protocol://host[:port]` 形态：缺协议补
+ * `https://`、带路径取 origin。无法解析时回退小写去尾斜杠的字面值。
+ * 与 {@link originsMatch} 的比较口径一致——保存前规范化一次，匹配时双向兜底。
+ * @param raw - 用户录入的来源（可缺协议/带路径）。
+ */
+export declare function normalizeOriginInput(raw: string): string;
+export declare function originsMatch(a: string, b: string): boolean;
 /**
  * 注入用户自定义单价列表。每条含模型目录键 + 可选来源（origin）。空数组 = 清除全部
  * 自定义价，回退内置目录。
@@ -65,6 +93,20 @@ export declare function getUserPrices(): Readonly<UserPriceEntry[]> | undefined;
  * @param origin - 调用来源（中转站 origin）；缺省仅查默认价。
  */
 export declare function userPriceOf(key: string, origin?: string): UserPrice | undefined;
+/**
+ * 查一个模型（可选来源）的完整用户价条目（含 origin 绑定信息）。
+ * 匹配优先级：origin 宽松精确命中（模型×来源）→ 无来源默认价。
+ * @param key - 计费目录键。
+ * @param origin - 调用来源（中转站 origin）；缺省仅查默认价。
+ */
+export declare function userPriceEntryOf(key: string, origin?: string): UserPriceEntry | undefined;
+/**
+ * 查一个模型的「带来源」用户价条目（无视来源值，取第一条命中模型名的
+ * 带 origin 条目）。供 recost 在三维站点数据缺失时兜底：用户填了来源价
+ * 就按它重估，而不是静默回退宿主原价（issue #18）。
+ * @param key - 计费目录键。
+ */
+export declare function userOriginPriceEntryOf(key: string): UserPriceEntry | undefined;
 /**
  * Apply the node half's live pricing snapshot. Absent fields keep the
  * built-in catalog and rate; callers never fabricate values.
@@ -281,14 +323,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;
@@ -341,6 +375,24 @@ export declare function resolveToken(name: string): string;
  * @returns the estimated cost in CNY.
  */
 export declare function computeCost(entry: ModelEntry, buckets: TokenUsageBuckets, peakShare?: number, nowMs?: number): number;
+/**
+ * 按调用时刻精确判定高峰/空闲档并计价（P0-1：替代固定比例混合）。时刻未知
+ * （null/NaN，理论不发生在真实事件流）时回退 {@link DEFAULT_PEAK_SHARE} 混合，
+ * 保持旧语义不低估。平档模型（无 offPeak）两个时段同价。限时促销与峰谷档
+ * 同口径：按事件时刻判定该笔流量当时享受的单价。
+ *
+ * 历史正确性（按变更节点分段适用规则，不统一套现行价重算历史）：
+ * - 早于 {@link PEAK_ERA_START_MS} 的事件按当时官方基础价
+ *   （{@link LEGACY_DEEPSEEK_BANDS}）计费；
+ * - 峰谷开闸至 {@link WEEKEND_OFFPEAK_START_MS} 之间按 v1 规则（周末不豁免，
+ *   周六日 9-12 / 14-18 计峰）；
+ * - 周末全谷分界起按现行规则（{@link tierAt}，周六日全天低谷）。
+ * @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 CNY（USD 计价模型已按当前汇率折算）。
+ */
 export declare function computeCostAt(entry: ModelEntry, buckets: TokenUsageBuckets, timeMs: number | null | undefined, peakShare?: number): number;
 /** 人民币 → 美元（显示换算用）：用当前生效汇率（实时优先，缺失回退内置），
  *  与计价链路的 `currentRate()` 同口径，避免实时汇率生效时 USD 显示与计价不一致。 */

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