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

package/lib/types/client/usage-billing-settings.d.ts

@@ -73,6 +73,28 @@ export declare const SITE_LIST_STORAGE_KEY = "dsh.ui-usage-billing.sites";
 export declare function loadSiteListPrefs(): SiteListPrefs;
 /** 写入站点列表偏好。失败静默（展示偏好非关键）。 */
 export declare function saveSiteListPrefs(prefs: SiteListPrefs): void;
+/**
+ * 即时代费条（平价消耗胶囊，composer dock 的 LiveCostBar）的显示偏好。
+ * 纯 client 偏好，存 localStorage（不依赖 node 半区接口/设置 schema）；
+ * 设置 Tab 与 LiveCostBar 分属两个 React 树，跨树同步走 localStorage +
+ * `LIVE_COST_BAR_PREF_EVENT` CustomEvent（同文档即时生效，跨标签页靠 storage 事件）。
+ */
+export interface LiveCostBarPrefs {
+    /** 是否显示输入框下方的即时代费条胶囊（默认 true：保持历史行为）。 */
+    show: boolean;
+    /** 胶囊位置：below = 输入框下方（默认）；above = 输入框上方；toolbar = 工具行模型选择前的内联 chip。 */
+    position: 'below' | 'above' | 'toolbar';
+}
+/** 默认即时代费条偏好：显示在输入框下方（升级用户零感知）。 */
+export declare const DEFAULT_LIVE_COST_BAR_PREFS: LiveCostBarPrefs;
+/** localStorage key（与其他 `dsh.ui-usage-billing.*` 偏好同命名空间）。 */
+export declare const LIVE_COST_BAR_STORAGE_KEY = "dsh.ui-usage-billing.livecost";
+/** 设置 Tab 切换后派发的 CustomEvent 名（LiveCostBar 监听它即时显隐）。 */
+export declare const LIVE_COST_BAR_PREF_EVENT = "dsh.ui-usage-billing.livecost-pref";
+/** 读取即时代费条偏好（含损坏/缺失回退到默认）。仅在浏览器半区调用。 */
+export declare function loadLiveCostBarPrefs(): LiveCostBarPrefs;
+/** 写入即时代费条偏好。失败静默（展示偏好非关键）。 */
+export declare function saveLiveCostBarPrefs(prefs: LiveCostBarPrefs): void;
 /** 用户自定义单价（与 client/pricing.ts 的 `UserPriceEntry` 同形；type import，无运行时依赖）。 */
 export type StoredUserPrice = UserPriceEntry;
 /** 自定义价表：模型（+可选来源）→ 单价，条目列表（支持同名模型绑定不同中转站 origin）。 */
@@ -87,4 +109,24 @@ export declare const USER_PRICES_STORAGE_KEY = "dsh.ui-usage-billing.prices";
 export declare function loadUserPrices(): UserPriceMap;
 /** 写入用户自定义价。失败静默（展示偏好非关键）。 */
 export declare function saveUserPrices(prices: UserPriceMap): void;
+/** 性能曲线的指标视角。 */
+export type PerfMetric = 'ttft' | 'tps';
+/**
+ * 性能面板的视图偏好：当前指标 tab 与点亮的模型曲线集合。
+ * 纯 client 偏好，存 localStorage（不依赖 node 半区接口/设置 schema）。
+ */
+export interface PerfViewPrefs {
+    /** 当前指标：首字延时（ms）/ 生成速度（tok/s）。 */
+    metric: PerfMetric;
+    /** 点亮的模型键列表；缺省 = 按样本数前 5（用户未碰过图例时跟随默认）。 */
+    models?: string[];
+}
+/** 默认性能视图偏好：首字延时 tab；模型集合跟随默认（前 5）。 */
+export declare const DEFAULT_PERF_VIEW_PREFS: PerfViewPrefs;
+/** localStorage key（与其他 `dsh.ui-usage-billing.*` 偏好同命名空间）。 */
+export declare const PERF_VIEW_STORAGE_KEY = "dsh.ui-usage-billing.perf";
+/** 读取性能视图偏好（含损坏/缺失回退到默认）。仅在浏览器半区调用。 */
+export declare function loadPerfViewPrefs(): PerfViewPrefs;
+/** 写入性能视图偏好。失败静默（展示偏好非关键）。 */
+export declare function savePerfViewPrefs(prefs: PerfViewPrefs): void;
 //# sourceMappingURL=usage-billing-settings.d.ts.map

package/lib/types/index.d.ts

@@ -16,7 +16,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';
 /**
@@ -68,6 +68,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
@@ -110,6 +122,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,19 @@
 {
   "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.1.13",
+  "version": "1.2.0",
+  "keywords": [
+    "deepseek-harness",
+    "deepseek",
+    "dsh",
+    "dsh-plugin",
+    "billing",
+    "cost-tracking",
+    "token-usage",
+    "usage-stats",
+    "llm",
+    "dashboard"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -40,15 +52,20 @@
       "platform": "web"
     },
     "compatibility": {
-      "dsh": ">=0.1.0-rc.8 <0.1.1-0 || >=0.1.1-rc.1 <0.1.2-0",
+      "dsh": ">=0.1.2-alpha.1",
       "dshReleases": {
-        "0.1.0-rc.8": "compatible",
-        "0.1.1-rc.1": "compatible",
-        "0.1.1-rc.2": "compatible"
+        "0.1.2-alpha.1": "compatible",
+        "0.1.2-alpha.2": "compatible",
+        "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.3-alpha.1": "compatible"
       }
     }
   },
   "scripts": {
+    "build": "tsc -b tsconfig.json && tsdown",
     "bundle": "tsdown",
     "watch": "tsdown --watch",
     "test": "vitest run"
@@ -56,7 +73,7 @@
   "license": "MIT",
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.0-rc.8 <0.1.1-0 || >=0.1.1-rc.1 <0.1.2-0"
+    "dsh": ">=0.1.2-alpha.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "*",
@@ -84,27 +101,30 @@
     "clsx": "^2.1.1"
   },
   "devDependencies": {
-    "typescript": "^5.9.2",
     "@deepseek-ai/cordis": "*",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-api-remotes": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-api-session-controller": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-atomic-write": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-locale": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-store": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-credentials": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-host-webserver": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-llm": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-scope": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-persistence": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-settings": "0.1.2-alpha.5",
-    "@deepseek-ai/dsh-tools": "0.1.2-alpha.5",
+    "@deepseek-ai/dsh-api-gateway": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-atomic-write": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-store": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-credentials": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-invariants": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-scope": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.1.0",
@@ -115,7 +135,9 @@
     "lightningcss": "^1.32.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
+    "semver": "^7.7.2",
     "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
     "use-sync-external-store": "1.2.0",
     "vitest": "^4.1.8"
   },