@kenz1117/dsh-ui-usage-billing 0.2.3 → 0.2.5

package/README.md

@@ -14,6 +14,11 @@ DeepSeek Harness 计费仪表盘插件。从持久化会话日志实时聚合模
 - **真实用量**：服务端从会话日志实时聚合，无需手工维护统计文件。
 - **模型健康探测**：模型行的圆点反映各厂商接入状态（正常绿 / 异常红 / 未接入灰）。
 - **订阅计划豁免**：走 coding/token 套餐的模型照常统计 token，费用记 0。
+- **余额查询**：模型计费明细按厂商显示「余额」列，DeepSeek 通过官方余额 API 实时查询；未配置 / Key 无效 / 服务不可达均有状态提示，扩展点可接更多厂商。
+- **实时汇率与定价**：启动时自动拉取腾讯财经行情（USD→CNY）与 OpenRouter 官方模型价，失败自动降级内置默认值；此后每 6 小时自动刷新，单价表标注「今日汇率」与实时 / 内置徽标。
+- **动态刷新**：侧边栏入口与仪表盘每 30 秒自动更新，无需重启或手动刷新。
+- **更新时间**：模型计费明细表头显示最近一次统计的更新时间，精确到时分秒。
+- **北京时间统一**：统计聚合与仪表盘日期一律按北京时间归天，跨零点不漂移。
 - **离线自包含**：无图表库、无外部 CDN，全部使用设计令牌，适配深色/浅色主题。
 
 ## 截图
@@ -52,21 +57,23 @@ npm install @kenz1117/dsh-ui-usage-billing
   ├─ GET /api/billing/usage-stats ────────▶ ├─ sessionPersistence 遍历持久化会话日志
   │                                        ├─ 按 request/header 归属模型
   │                                        ├─ token 按缓存命中 / 未命中分桶
-  │                                        └─ 按单价表估算费用（人民币）
+  │                                        └─ 按实时单价表估算费用（人民币）
+  ├─ GET /api/billing/pricing ────────────▶ ├─ 腾讯财经 / OpenRouter 实时汇率与模型价
+  ├─ GET /api/billing/balance ────────────▶ ├─ DeepSeek 官方余额 API（凭据 seam 取 key）
   ├─ llm.models 健康探测 ─────────────────▶ └─ 返回聚合统计 JSON
   └─ 渲染仪表盘
 ```
 
-- **服务端**（`src/index.ts`）：注入 `webServer` 与 `sessionPersistence`，注册 `GET /api/billing/usage-stats`。每次调用折叠全部持久化日志：一次 LLM 调用归属到其前置 `request/header` 记录的模型，token 拆分到缓存命中 / 未命中桶，日期按本机时区归天。聚合逻辑见 `src/aggregate.ts`。
+- **服务端**（`src/index.ts`）：注入 `webServer`、`sessionPersistence` 与 `credentials`，注册 `GET /api/billing/usage-stats`、`/api/billing/pricing`、`/api/billing/balance`。每次调用折叠全部持久化日志：一次 LLM 调用归属到其前置 `request/header` 记录的模型，token 拆分到缓存命中 / 未命中桶，日期按本机时区归天。聚合逻辑见 `src/aggregate.ts`。
 - **浏览器端**（`src/client/`）：请求上述接口渲染仪表盘，通过 `llm.models` 探测各厂商连接状态。真实数据到达前显示全零空快照，不展示伪造样本。
 
 ## 计费引擎
 
-单价表（`src/client/pricing.ts`）采用**原生币种**存储：国内厂商直接录入人民币价格，国外厂商录入美元价格。费用统一以人民币计算与展示——仅美元计价模型经过汇率（CFETS 中间价 6.79，2026-08-14），国内模型全程不经过汇率换算。
+单价表（`src/client/pricing.ts`）采用**原生币种**存储：国内厂商直接录入人民币价格，国外厂商录入美元价格。费用统一以人民币计算与展示——美元模型按**实时汇率**折算，国内模型全程不经过汇率换算。启动时服务端拉取实时汇率与模型价（`src/pricing-fetch.ts`）：USD→CNY 优先腾讯财经行情（免 key、国内可达），失败依次降级 open.er-api 与内置默认值；之后每 6 小时后台刷新，单价表弹窗标注「今日汇率」与实时 / 内置徽标。
 
 ```
 cost（CNY）= (missInput × p_input + cacheHit × p_cacheHit + output × p_output) / 10⁶
-           —— 价格为原生币种；美元模型按 USD × 6.79 折算
+           —— 价格为原生币种；美元模型按实时 USD → CNY 汇率折算
 ```
 
 统计中的 `input` 为总输入（cacheHit + cacheMiss），估算按命中 / 未命中分拆计价，避免重复计费。支持双档计费的模型按 `DEFAULT_PEAK_SHARE`（默认 0.5）混合高峰与低谷档。
@@ -100,6 +107,45 @@ cost（CNY）= (missInput × p_input + cacheHit × p_cacheHit + output × p_outp
 
 ## HTTP API
 
+### `GET /api/billing/pricing`
+
+实时定价文档（汇率 + 模型价，6 小时后台刷新），浏览器端单价表数据源：
+
+```json
+{
+  "source": "live",
+  "rate": 7.11,
+  "rateTime": "2026-08-16T12:00:00+08:00",
+  "models": {
+    "deepseek-chat": { "input": 0.5, "output": 2, "cacheHit": 0.1 }
+  }
+}
+```
+
+`source` 为 `live`（腾讯财经 / OpenRouter 拉到）或 `builtin`（全部降级内置默认值）；`rate` 为 USD→CNY 实时汇率。
+
+### `GET /api/billing/balance`
+
+各接入厂商账户余额（凭据 seam 按 `balanceApiKeyEnv` 取 key）：
+
+```json
+{
+  "balances": [
+    {
+      "provider": "deepseek",
+      "displayName": "DeepSeek",
+      "ok": true,
+      "currency": "CNY",
+      "total": 12.34,
+      "available": 10.56,
+      "granted": 1.78
+    }
+  ]
+}
+```
+
+查询失败时对应条目带 `error`（`unconfigured` / `unauthorized` / `unreachable`），表格按此渲染状态提示。
+
 ### `GET /api/billing/usage-stats`
 
 聚合统计文档，浏览器端数据源：
@@ -135,6 +181,8 @@ cost（CNY）= (missInput × p_input + cacheHit × p_cacheHit + output × p_outp
 | 字段 | 默认 | 说明 |
 |---|---|---|
 | `statsPath` | 未设置 | 回退统计文件 `.dsh-usage-stats.json` 的绝对路径（`sessionPersistence` 不可用时生效） |
+| `balanceApiKeyEnv` | `DEEPSEEK_API_KEY` | 余额查询使用的 DeepSeek 凭据引用（环境变量名），经 `ctx.credentials` 解析 |
+| `subscriptionProviders` | `kimi-coding`、`xiaomi-token-plan-cn` | 订阅制（coding / token 套餐）provider id 列表，照常统计 token、费用记 0 |
 
 ## 开发
 

package/lib/client.js

@@ -33,93 +33,93 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var UsageBilling_module_css_default = {
-			"panelTitle": "VWh0dG_panelTitle",
-			"chartLegendLine": "VWh0dG_chartLegendLine",
-			"dashboardModal": "VWh0dG_dashboardModal",
-			"emptyRow": "VWh0dG_emptyRow",
-			"heroValue": "VWh0dG_heroValue",
+			"triggerAmount": "VWh0dG_triggerAmount",
+			"bandPriceOff": "VWh0dG_bandPriceOff",
+			"chartBar": "VWh0dG_chartBar",
+			"bandTag": "VWh0dG_bandTag",
+			"triggerMonth": "VWh0dG_triggerMonth",
+			"chartTooltipSwatch": "VWh0dG_chartTooltipSwatch",
+			"deltaDown": "VWh0dG_deltaDown",
+			"modelTable": "VWh0dG_modelTable",
+			"pricingTable": "VWh0dG_pricingTable",
+			"heroSideItem": "VWh0dG_heroSideItem",
 			"modelDot": "VWh0dG_modelDot",
-			"chartLegendBar": "VWh0dG_chartLegendBar",
+			"pricingChevronOpen": "VWh0dG_pricingChevronOpen",
+			"kpiValue": "VWh0dG_kpiValue",
+			"flatTag": "VWh0dG_flatTag",
+			"panel": "VWh0dG_panel",
+			"triggerAmountSub": "VWh0dG_triggerAmountSub",
+			"dashboard": "VWh0dG_dashboard",
+			"kpiTile": "VWh0dG_kpiTile",
+			"heroMain": "VWh0dG_heroMain",
+			"healthBad": "VWh0dG_healthBad",
 			"rateBadge": "VWh0dG_rateBadge",
+			"heroMeta": "VWh0dG_heroMeta",
+			"triggerDivider": "VWh0dG_triggerDivider",
 			"bandTagOff": "VWh0dG_bandTagOff",
+			"triggerToday": "VWh0dG_triggerToday",
 			"heroSideLabel": "VWh0dG_heroSideLabel",
-			"triggerAmountSub": "VWh0dG_triggerAmountSub",
-			"healthIdle": "VWh0dG_healthIdle",
-			"chartGrid": "VWh0dG_chartGrid",
-			"deltaUp": "VWh0dG_deltaUp",
-			"healthBadgeOk": "VWh0dG_healthBadgeOk",
-			"kpiValue": "VWh0dG_kpiValue",
-			"kpiGrid": "VWh0dG_kpiGrid",
-			"heroSide": "VWh0dG_heroSide",
-			"chartDot": "VWh0dG_chartDot",
-			"heroSideItem": "VWh0dG_heroSideItem",
-			"chartTooltipSwatch": "VWh0dG_chartTooltipSwatch",
-			"deltaDown": "VWh0dG_deltaDown",
-			"rateBadgeLive": "VWh0dG_rateBadgeLive",
-			"pricingChevron": "VWh0dG_pricingChevron",
-			"heroLabel": "VWh0dG_heroLabel",
-			"trigger": "VWh0dG_trigger",
-			"chartAxisLabel": "VWh0dG_chartAxisLabel",
-			"modelTable": "VWh0dG_modelTable",
-			"chartBar": "VWh0dG_chartBar",
 			"modelProvider": "VWh0dG_modelProvider",
-			"dashboardBody": "VWh0dG_dashboardBody",
+			"chartEmpty": "VWh0dG_chartEmpty",
+			"heroLabel": "VWh0dG_heroLabel",
+			"deltaUp": "VWh0dG_deltaUp",
 			"chartCrosshair": "VWh0dG_chartCrosshair",
-			"triggerAmount": "VWh0dG_triggerAmount",
-			"chartTooltip": "VWh0dG_chartTooltip",
+			"chartTooltipRow": "VWh0dG_chartTooltipRow",
+			"chartLegendBar": "VWh0dG_chartLegendBar",
+			"triggerIcon": "VWh0dG_triggerIcon",
+			"railButton": "VWh0dG_railButton",
+			"chartStack": "VWh0dG_chartStack",
+			"panelTitle": "VWh0dG_panelTitle",
+			"modelName": "VWh0dG_modelName",
+			"chartAxisLabel": "VWh0dG_chartAxisLabel",
+			"heroSide": "VWh0dG_heroSide",
+			"healthOk": "VWh0dG_healthOk",
+			"heroSideValue": "VWh0dG_heroSideValue",
+			"kpiDetail": "VWh0dG_kpiDetail",
 			"pricingToggleText": "VWh0dG_pricingToggleText",
 			"closeButton": "VWh0dG_closeButton",
-			"costCol": "VWh0dG_costCol",
-			"bandPriceOff": "VWh0dG_bandPriceOff",
-			"hero": "VWh0dG_hero",
-			"heroMain": "VWh0dG_heroMain",
-			"chartEmpty": "VWh0dG_chartEmpty",
-			"triggerMeta": "VWh0dG_triggerMeta",
-			"kpiDetail": "VWh0dG_kpiDetail",
-			"pricingChevronOpen": "VWh0dG_pricingChevronOpen",
 			"dashboardTitle": "VWh0dG_dashboardTitle",
+			"dashboardBody": "VWh0dG_dashboardBody",
+			"chartLegendLine": "VWh0dG_chartLegendLine",
+			"chartLegend": "VWh0dG_chartLegend",
+			"numCol": "VWh0dG_numCol",
+			"healthBadgeBad": "VWh0dG_healthBadgeBad",
+			"kpiGrid": "VWh0dG_kpiGrid",
+			"chartDot": "VWh0dG_chartDot",
 			"healthDot": "VWh0dG_healthDot",
-			"planTag": "VWh0dG_planTag",
-			"heroSideValue": "VWh0dG_heroSideValue",
-			"pricingToggle": "VWh0dG_pricingToggle",
-			"triggerDivider": "VWh0dG_triggerDivider",
-			"panelHint": "VWh0dG_panelHint",
-			"modelCell": "VWh0dG_modelCell",
-			"healthOk": "VWh0dG_healthOk",
-			"chartWrap": "VWh0dG_chartWrap",
-			"bandTag": "VWh0dG_bandTag",
-			"kpiGreen": "VWh0dG_kpiGreen",
-			"flatTag": "VWh0dG_flatTag",
+			"pricingChevron": "VWh0dG_pricingChevron",
+			"emptyRow": "VWh0dG_emptyRow",
+			"rateBadgeBuiltin": "VWh0dG_rateBadgeBuiltin",
+			"healthIdle": "VWh0dG_healthIdle",
+			"trigger": "VWh0dG_trigger",
 			"dashboardHead": "VWh0dG_dashboardHead",
-			"pricingTable": "VWh0dG_pricingTable",
-			"kpiLabel": "VWh0dG_kpiLabel",
-			"numCol": "VWh0dG_numCol",
 			"tableScroll": "VWh0dG_tableScroll",
-			"chartStack": "VWh0dG_chartStack",
-			"modelName": "VWh0dG_modelName",
-			"dashboard": "VWh0dG_dashboard",
-			"rateBadgeBuiltin": "VWh0dG_rateBadgeBuiltin",
-			"kpiTile": "VWh0dG_kpiTile",
-			"panel": "VWh0dG_panel",
-			"bandPrice": "VWh0dG_bandPrice",
-			"healthBad": "VWh0dG_healthBad",
-			"chartLegend": "VWh0dG_chartLegend",
+			"kpiGreen": "VWh0dG_kpiGreen",
+			"na": "VWh0dG_na",
+			"healthBadgeOk": "VWh0dG_healthBadgeOk",
+			"hero": "VWh0dG_hero",
+			"chartTooltipDate": "VWh0dG_chartTooltipDate",
+			"modelCell": "VWh0dG_modelCell",
+			"planTag": "VWh0dG_planTag",
+			"costCol": "VWh0dG_costCol",
+			"panelHead": "VWh0dG_panelHead",
+			"kpiLabel": "VWh0dG_kpiLabel",
+			"chartWrap": "VWh0dG_chartWrap",
+			"heroValue": "VWh0dG_heroValue",
+			"triggerMeta": "VWh0dG_triggerMeta",
+			"chartGrid": "VWh0dG_chartGrid",
 			"chartLine": "VWh0dG_chartLine",
-			"chartTooltipRow": "VWh0dG_chartTooltipRow",
-			"triggerMonth": "VWh0dG_triggerMonth",
-			"healthBadgeBad": "VWh0dG_healthBadgeBad",
-			"railButton": "VWh0dG_railButton",
-			"triggerIcon": "VWh0dG_triggerIcon",
+			"chartTooltip": "VWh0dG_chartTooltip",
+			"rateBadgeLive": "VWh0dG_rateBadgeLive",
 			"healthBadge": "VWh0dG_healthBadge",
-			"chartSvg": "VWh0dG_chartSvg",
-			"panelHead": "VWh0dG_panelHead",
-			"heroMeta": "VWh0dG_heroMeta",
-			"delta": "VWh0dG_delta",
-			"chartTooltipDate": "VWh0dG_chartTooltipDate",
-			"triggerToday": "VWh0dG_triggerToday",
 			"dashboardRight": "VWh0dG_dashboardRight",
 			"dashboardSubtitle": "VWh0dG_dashboardSubtitle",
-			"na": "VWh0dG_na"
+			"pricingToggle": "VWh0dG_pricingToggle",
+			"delta": "VWh0dG_delta",
+			"dashboardModal": "VWh0dG_dashboardModal",
+			"bandPrice": "VWh0dG_bandPrice",
+			"chartSvg": "VWh0dG_chartSvg",
+			"panelHint": "VWh0dG_panelHint"
 		};
 		/** 运行时实时覆盖：undefined = 用内置目录与内置汇率（默认值降级）。 */
 		let liveRate;
@@ -155,8 +155,9 @@ window.__ModuleLoader__.load({
 		* costs no tokens: the estimator treats them as ¥0 and the billing table
 		* labels them 订阅包含. Add any model key your deployment serves through a
 		* plan here; leave empty when every route is pay-as-you-go.
+		* kimi-k3: 月之暗面 coding plan 通道的调用按套餐计费，费用记 0。
 		*/
-		const SUBSCRIPTION_PLAN_KEYS = [];
+		const SUBSCRIPTION_PLAN_KEYS = ["kimi-k3"];
 		/** Whether one stats model key is billed through a subscription plan. */
 		function isSubscriptionPlan(key) {
 			return SUBSCRIPTION_PLAN_KEYS.includes(key);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kenz1117/dsh-ui-usage-billing",
   "description": "Usage billing dashboard for DeepSeek Harness: sidebar cost metrics plus a full dashboard modal, priced from a current multi-provider catalog with real usage aggregated from session logs.",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "publishConfig": {
     "access": "public"
   },