@kenz1117/dsh-ui-usage-billing 0.2.2 → 0.2.4

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 = {
-			"costCol": "VWh0dG_costCol",
+			"panelTitle": "VWh0dG_panelTitle",
+			"chartLegendLine": "VWh0dG_chartLegendLine",
+			"dashboardModal": "VWh0dG_dashboardModal",
+			"emptyRow": "VWh0dG_emptyRow",
+			"heroValue": "VWh0dG_heroValue",
+			"modelDot": "VWh0dG_modelDot",
+			"chartLegendBar": "VWh0dG_chartLegendBar",
 			"rateBadge": "VWh0dG_rateBadge",
-			"pricingToggleText": "VWh0dG_pricingToggleText",
 			"bandTagOff": "VWh0dG_bandTagOff",
-			"healthDot": "VWh0dG_healthDot",
-			"kpiTile": "VWh0dG_kpiTile",
+			"heroSideLabel": "VWh0dG_heroSideLabel",
+			"triggerAmountSub": "VWh0dG_triggerAmountSub",
+			"healthIdle": "VWh0dG_healthIdle",
+			"chartGrid": "VWh0dG_chartGrid",
 			"deltaUp": "VWh0dG_deltaUp",
-			"delta": "VWh0dG_delta",
-			"panelHead": "VWh0dG_panelHead",
-			"panelTitle": "VWh0dG_panelTitle",
+			"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",
+			"chartCrosshair": "VWh0dG_chartCrosshair",
+			"triggerAmount": "VWh0dG_triggerAmount",
+			"chartTooltip": "VWh0dG_chartTooltip",
+			"pricingToggleText": "VWh0dG_pricingToggleText",
+			"closeButton": "VWh0dG_closeButton",
+			"costCol": "VWh0dG_costCol",
+			"bandPriceOff": "VWh0dG_bandPriceOff",
 			"hero": "VWh0dG_hero",
-			"emptyRow": "VWh0dG_emptyRow",
-			"dashboardModal": "VWh0dG_dashboardModal",
-			"chartLegendBar": "VWh0dG_chartLegendBar",
-			"tableScroll": "VWh0dG_tableScroll",
 			"heroMain": "VWh0dG_heroMain",
-			"heroSide": "VWh0dG_heroSide",
-			"pricingTable": "VWh0dG_pricingTable",
+			"chartEmpty": "VWh0dG_chartEmpty",
+			"triggerMeta": "VWh0dG_triggerMeta",
 			"kpiDetail": "VWh0dG_kpiDetail",
-			"healthBadgeOk": "VWh0dG_healthBadgeOk",
-			"triggerDivider": "VWh0dG_triggerDivider",
-			"heroLabel": "VWh0dG_heroLabel",
+			"pricingChevronOpen": "VWh0dG_pricingChevronOpen",
+			"dashboardTitle": "VWh0dG_dashboardTitle",
+			"healthDot": "VWh0dG_healthDot",
+			"planTag": "VWh0dG_planTag",
+			"heroSideValue": "VWh0dG_heroSideValue",
 			"pricingToggle": "VWh0dG_pricingToggle",
-			"dashboardRight": "VWh0dG_dashboardRight",
-			"railButton": "VWh0dG_railButton",
-			"kpiLabel": "VWh0dG_kpiLabel",
-			"healthBadge": "VWh0dG_healthBadge",
-			"triggerMonth": "VWh0dG_triggerMonth",
-			"triggerToday": "VWh0dG_triggerToday",
-			"rateBadgeBuiltin": "VWh0dG_rateBadgeBuiltin",
-			"dashboardSubtitle": "VWh0dG_dashboardSubtitle",
+			"triggerDivider": "VWh0dG_triggerDivider",
+			"panelHint": "VWh0dG_panelHint",
+			"modelCell": "VWh0dG_modelCell",
+			"healthOk": "VWh0dG_healthOk",
+			"chartWrap": "VWh0dG_chartWrap",
+			"bandTag": "VWh0dG_bandTag",
+			"kpiGreen": "VWh0dG_kpiGreen",
 			"flatTag": "VWh0dG_flatTag",
+			"dashboardHead": "VWh0dG_dashboardHead",
+			"pricingTable": "VWh0dG_pricingTable",
+			"kpiLabel": "VWh0dG_kpiLabel",
+			"numCol": "VWh0dG_numCol",
+			"tableScroll": "VWh0dG_tableScroll",
+			"chartStack": "VWh0dG_chartStack",
+			"modelName": "VWh0dG_modelName",
 			"dashboard": "VWh0dG_dashboard",
-			"chartWrap": "VWh0dG_chartWrap",
+			"rateBadgeBuiltin": "VWh0dG_rateBadgeBuiltin",
+			"kpiTile": "VWh0dG_kpiTile",
 			"panel": "VWh0dG_panel",
-			"chartLegendLine": "VWh0dG_chartLegendLine",
-			"deltaDown": "VWh0dG_deltaDown",
-			"kpiGrid": "VWh0dG_kpiGrid",
-			"chartSvg": "VWh0dG_chartSvg",
-			"closeButton": "VWh0dG_closeButton",
+			"bandPrice": "VWh0dG_bandPrice",
+			"healthBad": "VWh0dG_healthBad",
 			"chartLegend": "VWh0dG_chartLegend",
-			"modelName": "VWh0dG_modelName",
-			"pricingChevron": "VWh0dG_pricingChevron",
-			"na": "VWh0dG_na",
-			"healthBadgeBad": "VWh0dG_healthBadgeBad",
-			"chartStack": "VWh0dG_chartStack",
+			"chartLine": "VWh0dG_chartLine",
 			"chartTooltipRow": "VWh0dG_chartTooltipRow",
-			"modelTable": "VWh0dG_modelTable",
-			"chartCrosshair": "VWh0dG_chartCrosshair",
-			"bandTag": "VWh0dG_bandTag",
-			"heroValue": "VWh0dG_heroValue",
+			"triggerMonth": "VWh0dG_triggerMonth",
+			"healthBadgeBad": "VWh0dG_healthBadgeBad",
+			"railButton": "VWh0dG_railButton",
+			"triggerIcon": "VWh0dG_triggerIcon",
+			"healthBadge": "VWh0dG_healthBadge",
+			"chartSvg": "VWh0dG_chartSvg",
+			"panelHead": "VWh0dG_panelHead",
 			"heroMeta": "VWh0dG_heroMeta",
-			"healthOk": "VWh0dG_healthOk",
-			"kpiValue": "VWh0dG_kpiValue",
-			"planTag": "VWh0dG_planTag",
-			"heroSideLabel": "VWh0dG_heroSideLabel",
-			"chartDot": "VWh0dG_chartDot",
-			"healthBad": "VWh0dG_healthBad",
-			"kpiGreen": "VWh0dG_kpiGreen",
-			"heroSideItem": "VWh0dG_heroSideItem",
-			"pricingChevronOpen": "VWh0dG_pricingChevronOpen",
-			"dashboardBody": "VWh0dG_dashboardBody",
-			"panelHint": "VWh0dG_panelHint",
+			"delta": "VWh0dG_delta",
 			"chartTooltipDate": "VWh0dG_chartTooltipDate",
-			"heroSideValue": "VWh0dG_heroSideValue",
-			"triggerAmount": "VWh0dG_triggerAmount",
-			"trigger": "VWh0dG_trigger",
-			"chartAxisLabel": "VWh0dG_chartAxisLabel",
-			"modelProvider": "VWh0dG_modelProvider",
-			"chartGrid": "VWh0dG_chartGrid",
-			"healthIdle": "VWh0dG_healthIdle",
-			"chartLine": "VWh0dG_chartLine",
-			"numCol": "VWh0dG_numCol",
-			"rateBadgeLive": "VWh0dG_rateBadgeLive",
-			"triggerAmountSub": "VWh0dG_triggerAmountSub",
-			"bandPrice": "VWh0dG_bandPrice",
-			"dashboardTitle": "VWh0dG_dashboardTitle",
-			"triggerIcon": "VWh0dG_triggerIcon",
-			"dashboardHead": "VWh0dG_dashboardHead",
-			"bandPriceOff": "VWh0dG_bandPriceOff",
-			"chartTooltip": "VWh0dG_chartTooltip",
-			"chartEmpty": "VWh0dG_chartEmpty",
-			"modelCell": "VWh0dG_modelCell",
-			"modelDot": "VWh0dG_modelDot",
-			"chartTooltipSwatch": "VWh0dG_chartTooltipSwatch",
-			"triggerMeta": "VWh0dG_triggerMeta"
+			"triggerToday": "VWh0dG_triggerToday",
+			"dashboardRight": "VWh0dG_dashboardRight",
+			"dashboardSubtitle": "VWh0dG_dashboardSubtitle",
+			"na": "VWh0dG_na"
 		};
 		/** 运行时实时覆盖：undefined = 用内置目录与内置汇率（默认值降级）。 */
 		let liveRate;
@@ -665,6 +665,12 @@ window.__ModuleLoader__.load({
 		* Estimate the CNY cost of one model's token usage, mixing the peak and
 		* off-peak bands by the given peak share (flat-priced models cost the same in
 		* both bands).
+		*
+		* 计费维度是「缓存命中价 × 时段价」的交叉：每个时段档内部分别按缓存命中
+		* 价（cacheHit）与未命中价（input/cacheMiss）计价，两个时段档再按
+		* peakShare 混合。时段定义以北京时间为准（如 DeepSeek V4 高峰
+		* 09:00-12:00 / 14:00-18:00）。因聚合只有按日 token 量、没有请求级时间戳，
+		* 时段只能按比例估算，而非逐请求判定。
 		* @param entry - the catalog entry whose prices apply.
 		* @param buckets - token usage counts.
 		* @param peakShare - share of traffic in the peak band (0..1); defaults to {@link DEFAULT_PEAK_SHARE}.
@@ -1062,6 +1068,41 @@ window.__ModuleLoader__.load({
 		const USAGE_STATS_PATH = "/api/billing/usage-stats";
 		/** Path to the live-pricing endpoint served by this plugin's node half. */
 		const PRICING_PATH = "/api/billing/pricing";
+		/** Path to the account-balance endpoint served by this plugin's node half. */
+		const BALANCE_PATH = "/api/billing/balance";
+		/** 弹窗打开期间统计与定价的自动刷新间隔（毫秒）。 */
+		const STATS_REFRESH_INTERVAL_MS = 3e4;
+		/**
+		* 本地时区（北京时间）日期戳：与服务端聚合的 dayStamp 一致。不要用
+		* `toISOString()`——那是 UTC，北京时间的凌晨 0-8 点会取到前一天。
+		*/
+		function localDayStamp(time = Date.now()) {
+			const date = new Date(time);
+			const pad = (n) => String(n).padStart(2, "0");
+			return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+		}
+		/** 本地时区时钟：`HH:MM:SS`。 */
+		function formatClock(time) {
+			const date = new Date(time);
+			const pad = (n) => String(n).padStart(2, "0");
+			return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+		}
+		/**
+		* 高区分度图表色板：趋势图柱、图例与计费表圆点按模型分配。不用模型品牌色
+		* （目录里多为蓝色系，视觉上几乎分不开），保证每个模型一眼可辨。
+		*/
+		const CHART_PALETTE = [
+			"#3b82f6",
+			"#06b6d4",
+			"#8b5cf6",
+			"#f59e0b",
+			"#10b981",
+			"#ef4444",
+			"#ec4899",
+			"#6366f1",
+			"#f97316",
+			"#14b8a6"
+		];
 		/** Empty snapshot: shown before (or without) real host data — zeros, never fabricated samples. */
 		const EMPTY_STATS = {
 			total: {
@@ -1089,7 +1130,8 @@ window.__ModuleLoader__.load({
 					total: candidate.total ?? EMPTY_STATS.total,
 					byModel: candidate.byModel ?? {},
 					byDay: candidate.byDay ?? {},
-					...candidate.byDayModels !== void 0 ? { byDayModels: candidate.byDayModels } : {}
+					...candidate.byDayModels !== void 0 ? { byDayModels: candidate.byDayModels } : {},
+					...candidate.updatedAt !== void 0 ? { updatedAt: candidate.updatedAt } : {}
 				};
 			} catch {
 				return null;
@@ -1122,6 +1164,22 @@ window.__ModuleLoader__.load({
 			} catch {}
 		}
 		/**
+		* 拉取各提供方账户余额（供模型计费明细表的余额列）；失败返回空列表。
+		* @returns the balance rows, or an empty list on any failure.
+		*/
+		async function fetchBalances() {
+			try {
+				const response = await fetch(BALANCE_PATH);
+				if (!response.ok) return [];
+				const text = await response.text();
+				const parsed = JSON.parse(text);
+				if (parsed !== null && typeof parsed === "object" && "balances" in parsed) return parsed.balances;
+				return [];
+			} catch {
+				return [];
+			}
+		}
+		/**
 		* Sidebar footer trigger: compact pill in wide mode, icon in rail mode.
 		* @param props - framework props plus `wide` column state.
 		*/
@@ -1193,15 +1251,30 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* The centered billing dashboard modal.
-		* @param props - stats, locale function, close handler, and model health.
+		* @param props - stats, locale function, close handler, model health, balances.
 		*/
-		function BillingDashboard({ stats, t, onClose, health }) {
+		function BillingDashboard({ stats, t, onClose, health, balances }) {
 			const { total, byModel, byDay } = stats;
 			const [pricingOpen, setPricingOpen] = (0, react.useState)(false);
 			const rateInfo = getRateInfo();
+			const balanceFor = (provider) => balances.find((balance) => normalizeProvider(balance.provider) === normalizeProvider(provider));
+			const renderBalance = (balance) => {
+				if (balance === void 0) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: UsageBilling_module_css_default.na,
+					children: "—"
+				});
+				if (balance.error === "unconfigured") return t("billing.balanceUnconfigured");
+				if (balance.error === "unauthorized") return t("billing.balanceUnauthorized");
+				if (balance.error === "unreachable") return t("billing.balanceUnreachable");
+				if (balance.totalBalance === void 0) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: UsageBilling_module_css_default.na,
+					children: "—"
+				});
+				return balance.currency === "USD" ? `$${balance.totalBalance.toFixed(2)}` : formatMoney(balance.totalBalance);
+			};
 			const cacheHitRate = total.cacheHit + total.cacheMiss > 0 ? total.cacheHit / (total.cacheHit + total.cacheMiss) * 100 : 0;
 			const dates = Object.keys(byDay).sort();
-			const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+			const today = localDayStamp();
 			const todayCost = byDay[today]?.cost ?? 0;
 			const monthPrefix = today.slice(0, 7);
 			const yearPrefix = today.slice(0, 4);
@@ -1213,7 +1286,7 @@ window.__ModuleLoader__.load({
 				for (let offset = 6; offset >= 0; offset -= 1) {
 					const day = /* @__PURE__ */ new Date();
 					day.setDate(day.getDate() - offset);
-					out.push(day.toISOString().slice(0, 10));
+					out.push(localDayStamp(day.getTime()));
 				}
 				return out;
 			}, []);
@@ -1248,7 +1321,6 @@ window.__ModuleLoader__.load({
 					key,
 					name: entry.name,
 					provider: entry.provider,
-					color: resolveToken(entry.colorVar),
 					calls: data.calls,
 					input: data.input,
 					output: data.output,
@@ -1257,7 +1329,10 @@ window.__ModuleLoader__.load({
 					plan: isSubscriptionPlan(key),
 					...data.cost > 0 ? { actual: data.cost } : {}
 				};
-			}).sort((a, b) => (b.actual ?? b.estimated) - (a.actual ?? a.estimated)), [byModel]);
+			}).sort((a, b) => (b.actual ?? b.estimated) - (a.actual ?? a.estimated)).map((row, index) => ({
+				...row,
+				color: CHART_PALETTE[index % CHART_PALETTE.length] ?? "#8b95a3"
+			})), [byModel]);
 			const estimatedTotal = modelRows.reduce((sum, row) => sum + row.estimated, 0);
 			const displayTotal = total.cost > 0 ? total.cost : estimatedTotal;
 			const avgPerCall = total.calls > 0 ? displayTotal / total.calls : 0;
@@ -1482,13 +1557,9 @@ window.__ModuleLoader__.load({
 									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
 										className: UsageBilling_module_css_default.panelTitle,
 										children: t("billing.models")
-									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 										className: UsageBilling_module_css_default.panelHint,
-										children: [
-											t("billing.estimated"),
-											" · ",
-											t("billing.pricePerM")
-										]
+										children: stats.updatedAt !== void 0 ? `${t("billing.lastUpdated")} ${formatClock(stats.updatedAt)}` : ""
 									})]
 								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 									className: UsageBilling_module_css_default.tableScroll,
@@ -1514,11 +1585,11 @@ window.__ModuleLoader__.load({
 											}),
 											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("th", {
 												className: UsageBilling_module_css_default.numCol,
-												children: t("billing.estimated")
+												children: t("billing.actual")
 											}),
 											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("th", {
 												className: UsageBilling_module_css_default.numCol,
-												children: t("billing.actual")
+												children: t("billing.balance")
 											})
 										] }) }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("tbody", { children: [modelRows.length === 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("tr", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("td", {
 											colSpan: 7,
@@ -1554,13 +1625,6 @@ window.__ModuleLoader__.load({
 												className: UsageBilling_module_css_default.numCol,
 												children: formatPercent(row.cacheHitRate)
 											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("td", {
-												className: clsx(UsageBilling_module_css_default.numCol, UsageBilling_module_css_default.costCol),
-												children: row.plan ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-													className: UsageBilling_module_css_default.planTag,
-													children: "订阅包含"
-												}) : formatMoney(row.estimated)
-											}),
 											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("td", {
 												className: UsageBilling_module_css_default.numCol,
 												children: row.plan ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -1570,6 +1634,10 @@ window.__ModuleLoader__.load({
 													className: UsageBilling_module_css_default.na,
 													children: "—"
 												})
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("td", {
+												className: UsageBilling_module_css_default.numCol,
+												children: renderBalance(balanceFor(row.provider))
 											})
 										] }, row.key))] })]
 									})
@@ -1703,23 +1771,37 @@ window.__ModuleLoader__.load({
 			const { t, checkModels } = props;
 			const [stats, setStats] = (0, react.useState)(EMPTY_STATS);
 			const [health, setHealth] = (0, react.useState)(IDLE_HEALTH);
+			const [balances, setBalances] = (0, react.useState)([]);
 			const [open, setOpen] = (0, react.useState)(false);
 			const close = (0, react.useCallback)(() => {
 				setOpen(false);
 			}, []);
+			const reloadStats = (0, react.useCallback)(() => {
+				loadUsageStats().then((data) => {
+					if (data !== null) setStats(data);
+				});
+				fetchBalances().then((list) => {
+					if (list.length > 0) setBalances(list);
+				});
+			}, []);
 			const openDashboard = (0, react.useCallback)(() => {
+				reloadStats();
+				loadLivePricing();
 				setOpen(true);
-			}, []);
+			}, [reloadStats]);
 			(0, react.useEffect)(() => {
-				let mounted = true;
-				loadUsageStats().then((data) => {
-					if (mounted && data !== null) setStats(data);
-				});
+				reloadStats();
 				loadLivePricing();
+			}, [reloadStats]);
+			(0, react.useEffect)(() => {
+				const timer = setInterval(() => {
+					reloadStats();
+					loadLivePricing();
+				}, STATS_REFRESH_INTERVAL_MS);
 				return () => {
-					mounted = false;
+					clearInterval(timer);
 				};
-			}, []);
+			}, [reloadStats]);
 			(0, react.useEffect)(() => {
 				let mounted = true;
 				checkModels().then((result) => {
@@ -1729,7 +1811,7 @@ window.__ModuleLoader__.load({
 					mounted = false;
 				};
 			}, [checkModels]);
-			const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+			const today = localDayStamp();
 			const monthCost = Object.entries(stats.byDay).filter(([date]) => date.startsWith(today.slice(0, 7))).reduce((sum, [, day]) => sum + day.cost, 0);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(UsageBillingTrigger, {
 				...props,
@@ -1740,7 +1822,8 @@ window.__ModuleLoader__.load({
 				stats,
 				t,
 				onClose: close,
-				health
+				health,
+				balances
 			})] });
 		}
 		//#endregion
@@ -1783,7 +1866,11 @@ window.__ModuleLoader__.load({
 			"billing.noData": "暂无计费数据",
 			"billing.todayRate": "今日汇率",
 			"billing.rateLive": "实时",
-			"billing.rateBuiltin": "内置"
+			"billing.rateBuiltin": "内置",
+			"billing.balance": "余额",
+			"billing.balanceUnconfigured": "未配置",
+			"billing.balanceUnauthorized": "密钥无效",
+			"billing.balanceUnreachable": "查询失败"
 		};
 		const en = {
 			"billing.title": "Usage",
@@ -1822,7 +1909,11 @@ window.__ModuleLoader__.load({
 			"billing.noData": "No billing data yet",
 			"billing.todayRate": "Today rate",
 			"billing.rateLive": "Live",
-			"billing.rateBuiltin": "Built-in"
+			"billing.rateBuiltin": "Built-in",
+			"billing.balance": "Balance",
+			"billing.balanceUnconfigured": "Not set",
+			"billing.balanceUnauthorized": "Bad key",
+			"billing.balanceUnreachable": "Unavailable"
 		};
 		//#endregion
 		//#region src/client/apply.ts

package/lib/index.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
 /** 当前汇率：实时覆盖优先，缺省回退内置固定值。 */
 function currentRate() {
 	return 6.79;
@@ -507,6 +508,12 @@ function priceBandCost(band, buckets, currency) {
 * Estimate the CNY cost of one model's token usage, mixing the peak and
 * off-peak bands by the given peak share (flat-priced models cost the same in
 * both bands).
+*
+* 计费维度是「缓存命中价 × 时段价」的交叉：每个时段档内部分别按缓存命中
+* 价（cacheHit）与未命中价（input/cacheMiss）计价，两个时段档再按
+* peakShare 混合。时段定义以北京时间为准（如 DeepSeek V4 高峰
+* 09:00-12:00 / 14:00-18:00）。因聚合只有按日 token 量、没有请求级时间戳，
+* 时段只能按比例估算，而非逐请求判定。
 * @param entry - the catalog entry whose prices apply.
 * @param buckets - token usage counts.
 * @param peakShare - share of traffic in the peak band (0..1); defaults to {@link DEFAULT_PEAK_SHARE}.
@@ -656,6 +663,101 @@ async function aggregateUsage(persistence, options = {}) {
 	};
 }
 //#endregion
+//#region lib/types/balance.js
+/**
+* Account-balance queries for the billing dashboard.
+*
+* Only providers with a public balance endpoint can report one. Today that is
+* DeepSeek (`GET https://api.deepseek.com/user/balance`, Bearer 鉴权); the
+* other mainstream providers (OpenAI, 智谱, 通义, Kimi…) expose no standard
+* balance API, so their rows in the model table show an unavailable state.
+* The lookup map below is the extension point for future providers.
+*/
+/** Abort a balance fetch when the upstream hangs beyond this budget. */
+const FETCH_TIMEOUT_MS$1 = 8e3;
+/** DeepSeek 官方余额接口（官方文档 api-docs.deepseek.com/api/get-user-balance）。 */
+const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
+/** 数字归一化：接口返回的余额是字符串（如 `"110.00"`），统一转 number。 */
+function toNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+/**
+* Query the DeepSeek account balance through the configured credential.
+* @param ctx - host context carrying the credentials seam.
+* @param apiKeyEnv - credential reference resolving the DeepSeek API key.
+* @returns the balance row, or an error row when the key/endpoint misbehaves.
+*/
+async function queryDeepSeek(ctx, apiKeyEnv) {
+	const hit = await ctx.credentials.resolve(credentialRef(apiKeyEnv));
+	if (hit === void 0) return {
+		provider: "deepseek",
+		displayName: "DeepSeek",
+		error: "unconfigured"
+	};
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$1);
+	try {
+		const response = await fetch(DEEPSEEK_BALANCE_URL, {
+			headers: {
+				accept: "application/json",
+				authorization: `Bearer ${hit.value}`
+			},
+			signal: controller.signal
+		});
+		if (response.status === 401 || response.status === 403) return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			error: "unauthorized"
+		};
+		if (!response.ok) return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			error: "unreachable"
+		};
+		const data = await response.json();
+		const info = (Array.isArray(data.balance_infos) ? data.balance_infos : [])[0];
+		const currency = typeof info?.currency === "string" ? info.currency : void 0;
+		const totalBalance = toNumber(info?.total_balance);
+		const grantedBalance = toNumber(info?.granted_balance);
+		const toppedUpBalance = toNumber(info?.topped_up_balance);
+		const isAvailable = typeof data.is_available === "boolean" ? data.is_available : void 0;
+		return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			...currency !== void 0 ? { currency } : {},
+			...totalBalance !== void 0 ? { totalBalance } : {},
+			...grantedBalance !== void 0 ? { grantedBalance } : {},
+			...toppedUpBalance !== void 0 ? { toppedUpBalance } : {},
+			...isAvailable !== void 0 ? { isAvailable } : {}
+		};
+	} catch {
+		return {
+			provider: "deepseek",
+			displayName: "DeepSeek",
+			error: "unreachable"
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+const QUERIERS = [{
+	provider: "deepseek",
+	querier: queryDeepSeek
+}];
+/**
+* Query every configured provider's account balance.
+* @param ctx - host context carrying the credentials seam.
+* @param balanceApiKeyEnv - credential reference for the DeepSeek key.
+* @returns the balance rows (one per provider).
+*/
+async function queryBalances(ctx, balanceApiKeyEnv) {
+	return await Promise.all(QUERIERS.map(({ querier }) => querier(ctx, balanceApiKeyEnv)));
+}
+//#endregion
 //#region lib/types/pricing-fetch.js
 /**
 * One-shot live pricing refresh for the billing dashboard.
@@ -820,8 +922,16 @@ async function fetchLivePricing() {
 * missing file answers `{ error }` so the dashboard shows zeros, never
 * fabricated samples.
 */
+/** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
+const PRICING_REFRESH_INTERVAL_MS = 360 * 60 * 1e3;
+/** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
+const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 /** Required services: the web server and the persisted session log store. */
-const inject = ["webServer", "sessionPersistence"];
+const inject = [
+	"webServer",
+	"sessionPersistence",
+	"credentials"
+];
 /**
 * Host plugin body: serve real aggregated usage to the browser dashboard.
 * @param ctx - host context carrying webServer and sessionPersistence.
@@ -836,9 +946,18 @@ function apply(ctx, config = {}) {
 		join(homedir(), ".dsh/.dsh-usage-stats.json")
 	].filter((path) => typeof path === "string" && path.length > 0);
 	let live = { source: "builtin" };
-	fetchLivePricing().then((result) => {
-		live = result;
-	});
+	const refreshPricing = async () => {
+		live = await fetchLivePricing();
+	};
+	refreshPricing();
+	ctx.effect(() => {
+		const timer = setInterval(() => {
+			refreshPricing();
+		}, PRICING_REFRESH_INTERVAL_MS);
+		return () => {
+			clearInterval(timer);
+		};
+	}, "usage-billing: pricing refresh timer");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/pricing",
@@ -847,6 +966,15 @@ function apply(ctx, config = {}) {
 			res.end(JSON.stringify(live));
 		}
 	}), "usage-billing: pricing route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/balance",
+		handler: async (_req, res) => {
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			const balances = await queryBalances(ctx, config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV);
+			res.end(JSON.stringify({ balances }));
+		}
+	}), "usage-billing: balance route");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/usage-stats",

package/lib/types/balance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Account-balance queries for the billing dashboard.
+ *
+ * Only providers with a public balance endpoint can report one. Today that is
+ * DeepSeek (`GET https://api.deepseek.com/user/balance`, Bearer 鉴权); the
+ * other mainstream providers (OpenAI, 智谱, 通义, Kimi…) expose no standard
+ * balance API, so their rows in the model table show an unavailable state.
+ * The lookup map below is the extension point for future providers.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ProviderBalance } from './pricing-shared.ts';
+/**
+ * Query every configured provider's account balance.
+ * @param ctx - host context carrying the credentials seam.
+ * @param balanceApiKeyEnv - credential reference for the DeepSeek key.
+ * @returns the balance rows (one per provider).
+ */
+export declare function queryBalances(ctx: Context, balanceApiKeyEnv: string): Promise<readonly ProviderBalance[]>;
+//# sourceMappingURL=balance.d.ts.map

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

@@ -1,9 +1,11 @@
 /**
- * TrendChart: dependency-free SVG stacked bar chart of daily cost per model.
- * Each day's column stacks every model's share in its brand color, so the
- * total trend and the per-model composition are visible at once. A hover
- * crosshair shows the day's model breakdown. No chart library — the surface
- * stays self-contained and offline.
+ * TrendChart: dependency-free SVG chart of daily cost + calls.
+ *
+ * The columns are GROUPED per model — one bar per model per day, each in its
+ * brand color, so per-model cost is directly comparable. The blue line is the
+ * total call volume across all models, plotted on its own right-hand axis.
+ * A hover crosshair shows the day's model breakdown. No chart library — the
+ * surface stays self-contained and offline.
  */
 /** One model's legend identity: key, display name, and brand color. */
 export interface TrendSeriesModel {
@@ -11,7 +13,7 @@ export interface TrendSeriesModel {
     key: string;
     /** Human-readable model name. */
     name: string;
-    /** Resolved brand color for the stack segment and legend swatch. */
+    /** Resolved brand color for the bar and legend swatch (empty = single-color fallback). */
     color: string;
 }
 /** One day row fed to the chart. */
@@ -20,15 +22,15 @@ export interface TrendPoint {
     date: string;
     /** Total cost that day. */
     cost: number;
-    /** API calls that day. */
+    /** API calls that day (total across models). */
     calls: number;
-    /** Per-model cost that day (stats key → CNY); absent entries stack zero. */
+    /** Per-model cost that day (stats key → CNY); absent entries plot zero. */
     byModel?: Readonly<Record<string, number>>;
 }
 /**
- * Render the daily per-model stacked cost chart.
+ * Render the daily grouped cost bars plus the total-calls line.
  * @param props.data - sorted daily rows (ascending date).
- * @param props.models - the model legend, in stack order (bottom first).
+ * @param props.models - the model legend, in bar order.
  */
 export declare function TrendChart({ data, models }: {
     data: readonly TrendPoint[];

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.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trendEmpty' | 'billing.models' | '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';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trendEmpty' | 'billing.models' | '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';
 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

@@ -115,6 +115,12 @@ export declare function resolveToken(name: string): string;
  * Estimate the CNY cost of one model's token usage, mixing the peak and
  * off-peak bands by the given peak share (flat-priced models cost the same in
  * both bands).
+ *
+ * 计费维度是「缓存命中价 × 时段价」的交叉：每个时段档内部分别按缓存命中
+ * 价（cacheHit）与未命中价（input/cacheMiss）计价，两个时段档再按
+ * peakShare 混合。时段定义以北京时间为准（如 DeepSeek V4 高峰
+ * 09:00-12:00 / 14:00-18:00）。因聚合只有按日 token 量、没有请求级时间戳，
+ * 时段只能按比例估算，而非逐请求判定。
  * @param entry - the catalog entry whose prices apply.
  * @param buckets - token usage counts.
  * @param peakShare - share of traffic in the peak band (0..1); defaults to {@link DEFAULT_PEAK_SHARE}.

package/lib/types/index.d.ts

@@ -16,6 +16,8 @@ export interface UsageBillingConfig {
     statsPath?: string;
     /** 订阅制（coding / token / agent plan）provider id 列表；默认 kimi-coding、xiaomi-token-plan-cn。 */
     subscriptionProviders?: string[];
+    /** 余额查询用的 DeepSeek 凭据引用（环境变量名）；默认 DEEPSEEK_API_KEY。 */
+    balanceApiKeyEnv?: string;
 }
 /** Required services: the web server and the persisted session log store. */
 export declare const inject: string[];

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

@@ -22,4 +22,29 @@ export interface LivePricing {
     /** Overrides keyed by built-in catalog key (present when router matches succeeded). */
     prices?: Record<string, LivePrice>;
 }
+/** 余额查询失败的原因，前端据此显示文案。 */
+export type BalanceError = 'unconfigured' | 'unauthorized' | 'unreachable';
+/** 一个提供方的账户余额（`/api/billing/balance` 的一行）。 */
+export interface ProviderBalance {
+    /** 提供方 id（小写，如 `deepseek`），与模型表 provider 匹配用。 */
+    provider: string;
+    /** 显示名（如 `DeepSeek`）。 */
+    displayName: string;
+    /** 余额币种（CNY / USD）。 */
+    currency?: string;
+    /** 总可用余额（含赠金与充值）。 */
+    totalBalance?: number;
+    /** 未过期赠金余额。 */
+    grantedBalance?: number;
+    /** 充值余额。 */
+    toppedUpBalance?: number;
+    /** 余额是否足以继续调用。 */
+    isAvailable?: boolean;
+    /** 未配置/鉴权失败/网络不可达等失败原因；缺省 = 查询成功。 */
+    error?: BalanceError;
+}
+/** Response of `/api/billing/balance` consumed by the dashboard. */
+export interface BalanceResponse {
+    balances: readonly ProviderBalance[];
+}
 //# 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.2.2",
+  "version": "0.2.4",
   "publishConfig": {
     "access": "public"
   },