dsh-balance-widget 0.2.1 → 0.3.1

package/README.en.md

@@ -31,6 +31,7 @@ A balance & cost widget for the [DeepSeek Harness](https://github.com/deepseek-a
 - **Last prompt cost (estimate)** — Parses the current session file and prices the last turn's token usage, answering "how much did that last prompt cost".
 - **Today total cost (estimate)** — Walks every session under `~/.dsh/sessions/` and sums today's (calendar day) token usage × price.
 - **Token usage** — Also shows the session's input (incl. cache hits) / output tokens.
+- **One-click top-up** — a "⚡ Top up" link in the popover footer jumps to the official DeepSeek top-up page (platform.deepseek.com/top_up) in a new tab.
 - **On-demand refresh** — No polling, no background requests; endpoints are only hit when you click the icon. Costs zero tokens to use.
 
 ## Why this plugin
@@ -73,18 +74,57 @@ Then restart `dsh web`.
 
 ## Configuration
 
-In `~/.dsh/profiles/web/cordis.patch.yml`:
+### Where the config file lives
+
+DSH plugin configuration lives in:
+
+```
+~/.dsh/profiles/web/cordis.patch.yml
+```
+
+### All options
+
+Append to `cordis.patch.yml` (only change the lines you need; the rest stay at defaults):
 
 ```yaml
 - id: balance-widget
   name: dsh-balance-widget
   config:
-    balanceBaseURL: https://api.deepseek.com   # official balance endpoint
-    balanceApiKeyEnv: DEEPSEEK_API_KEY          # credential ref for the API key
-    requestTimeoutMs: 5000                      # balance request timeout
+    balanceBaseURL: https://api.deepseek.com   # official balance endpoint (rarely changed)
+    balanceApiKeyEnv: DEEPSEEK_API_KEY          # credential ref for the API key (rarely changed)
+    requestTimeoutMs: 5000                      # balance request timeout (ms)
     modelId: deepseek-v4-flash                  # pricing model (or deepseek-v4-pro)
+    lowThreshold: 5                             # balance below this (¥) turns the icon amber
+    criticalThreshold: 1                        # balance below this (¥) turns the icon red
+```
+
+### Example: custom balance thresholds
+
+By default the icon turns **amber below ¥5 and red below ¥1**. To warn at ¥10 / ¥3 instead:
+
+```yaml
+- id: balance-widget
+  name: dsh-balance-widget
+  config:
+    lowThreshold: 10
+    criticalThreshold: 3
+```
+
+Restart `dsh web` for changes to take effect.
+
+### Example: price with V4-Pro
+
+If you mainly use DeepSeek-V4-Pro, point the pricing model at it for a more accurate estimate:
+
+```yaml
+- id: balance-widget
+  name: dsh-balance-widget
+  config:
+    modelId: deepseek-v4-pro
 ```
 
+> **Note**: `cordis.patch.yml` may already contain lines for other plugins — append new lines without touching existing ones.
+
 ## Pricing
 
 Built-in DeepSeek official peak/off-peak pricing (CNY per 1M tokens), effective 2026-08-17. Peak windows are Beijing time 09:00–12:00 and 14:00–18:00; prices are double the off-peak rates:

package/README.md

@@ -31,6 +31,7 @@ DeepSeek Harness (DSH) Web GUI 的余额与成本小部件：在会话头部右
 - **最近一次提问成本（估算）** — 从当前会话文件解析最后一个 turn 的 token 用量 × 单价，回答"刚才那条提问花了多少"。
 - **今天总成本（估算）** — 遍历 `~/.dsh/sessions/` 下所有会话，累加今天（自然日）的 token 用量 × 单价。
 - **Token 用量** — 同时展示本会话输入（含缓存命中）/ 输出 token 数。
+- **一键充值** — 弹层底部「⚡ 去充值」链接直达 DeepSeek 官方充值页（platform.deepseek.com/top_up），新窗口打开。
 - **按需刷新** — 无轮询、无后台请求；只有点击图标时才发起查询，不消耗任何 token。
 
 ## 架构
@@ -69,18 +70,59 @@ dsh plugin --profile web add "link:$(pwd)"
 
 ## 配置
 
-在 `~/.dsh/profiles/web/cordis.patch.yml` 中：
+### 配置文件在哪
+
+DSH 的插件配置统一放在这个文件里：
+
+```
+~/.dsh/profiles/web/cordis.patch.yml
+```
+
+> `~` 是你的用户主目录（macOS 是 `/Users/你的用户名`）。
+
+### 全部配置项
+
+在 `cordis.patch.yml` 中追加以下内容（**只改你需要的那几行**，其余保持默认即可）：
 
 ```yaml
 - id: balance-widget
   name: dsh-balance-widget
   config:
-    balanceBaseURL: https://api.deepseek.com   # 官方余额接口
-    balanceApiKeyEnv: DEEPSEEK_API_KEY          # 凭据服务中的密钥 ref
-    requestTimeoutMs: 5000                      # 余额查询超时
+    balanceBaseURL: https://api.deepseek.com   # 官方余额接口（一般不用改）
+    balanceApiKeyEnv: DEEPSEEK_API_KEY          # 凭据服务中的密钥 ref（一般不用改）
+    requestTimeoutMs: 5000                      # 余额查询超时（毫秒）
     modelId: deepseek-v4-flash                  # 成本计价模型（可改 deepseek-v4-pro）
+    lowThreshold: 5                             # 余额低于此值（¥）图标变黄提醒
+    criticalThreshold: 1                        # 余额低于此值（¥）图标变红警告
 ```
 
+### 示例：调整余额预警阈值
+
+默认余额 **低于 ¥5 变黄、低于 ¥1 变红**。想改成"低于 ¥10 提醒、低于 ¥3 警告"：
+
+```yaml
+- id: balance-widget
+  name: dsh-balance-widget
+  config:
+    lowThreshold: 10
+    criticalThreshold: 3
+```
+
+改完**重启 `dsh web`** 生效。
+
+### 示例：成本按 V4-Pro 计价
+
+如果主要使用 DeepSeek-V4-Pro 模型，把计价模型改掉，成本估算更准：
+
+```yaml
+- id: balance-widget
+  name: dsh-balance-widget
+  config:
+    modelId: deepseek-v4-pro
+```
+
+> **提示**：`cordis.patch.yml` 可能有其他插件的配置行，追加时注意**不要改动已有的行**，只加新内容。
+
 ## 定价说明
 
 内置 DeepSeek 官方 2026-08-17 峰谷定价（元 / 百万 tokens），高峰时段为北京时间 09:00–12:00、14:00–18:00，价格为空闲时段两倍：

package/lib/client.js

@@ -6,8 +6,9 @@ window.__ModuleLoader__.load({
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let react = require("react");
+		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 		//#region lib/types/client/styles.js
-		const css = ".dshbw_wrap{position:relative;display:inline-flex;align-items:center}.dshbw_btn{background:none;border:none;cursor:pointer;color:var(--dsw-alias-label-secondary);display:inline-flex;align-items:center;gap:4px;padding:2px 6px;border-radius:6px;font-size:12px;line-height:18px;font-family:inherit}.dshbw_btn:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.dshbw_pop{position:absolute;top:calc(100% + 6px);right:0;z-index:60;min-width:230px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l3);border-radius:10px;box-shadow:0 8px 24px rgba(0,0,0,.18);padding:12px 14px;font-size:12px;line-height:20px;color:var(--dsw-alias-label-primary)}.dshbw_row{display:flex;justify-content:space-between;gap:12px;padding:2px 0}.dshbw_val{font-weight:600;color:var(--dsw-alias-label-primary)}.dshbw_err{color:var(--dsw-alias-state-error-primary);font-size:11px;line-height:16px;margin-top:6px}.dshbw_hint{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;margin-top:6px;border-top:1px solid var(--dsw-alias-border-l1);padding-top:6px}.dshbw_foot{margin-top:8px;text-align:right}";
+		const css = ".dshbw_wrap{position:relative;display:inline-flex;align-items:center}.dshbw_btn{background:none;border:none;cursor:pointer;color:var(--dsw-alias-label-secondary);display:inline-flex;align-items:center;gap:4px;padding:2px 6px;border-radius:6px;font-size:12px;line-height:18px;font-family:inherit}.dshbw_btn:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.dshbw_btn[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_btn[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_pop{position:absolute;top:calc(100% + 6px);right:0;z-index:60;min-width:230px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l3);border-radius:10px;box-shadow:0 8px 24px rgba(0,0,0,.18);padding:12px 14px;font-size:12px;line-height:20px;color:var(--dsw-alias-label-primary)}.dshbw_head{display:flex;align-items:center;justify-content:space-between;margin-bottom:4px}.dshbw_title{font-weight:600;color:var(--dsw-alias-label-primary)}.dshbw_refresh{background:none;border:1px solid var(--dsw-alias-border-l2);cursor:pointer;color:var(--dsw-alias-label-secondary);display:inline-flex;align-items:center;justify-content:center;width:24px;height:24px;border-radius:6px;font-size:13px;line-height:1;padding:0;font-family:inherit}.dshbw_refresh:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l3);background:var(--dsw-alias-interactive-bg-hover)}.dshbw_refresh[data-spinning=true]{animation:dshbw-spin .8s linear infinite}.dshbw_row{display:flex;justify-content:space-between;align-items:center;gap:12px;padding:2px 0}.dshbw_label{display:inline-flex;align-items:center;min-width:0}.dshbw_val{font-weight:600;color:var(--dsw-alias-label-primary)}.dshbw_val[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_val[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_err{color:var(--dsw-alias-state-error-primary);font-size:11px;line-height:16px;margin-top:6px}.dshbw_hint{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;margin-top:6px;border-top:1px solid var(--dsw-alias-border-l1);padding-top:6px}.dshbw_foot{display:flex;align-items:center;justify-content:space-between;gap:8px;margin-top:8px}.dshbw_link{background:none;border:none;cursor:pointer;color:var(--dsw-alias-state-business-primary);display:inline-flex;align-items:center;gap:4px;padding:2px 6px;border-radius:6px;font-size:12px;line-height:18px;font-family:inherit;text-decoration:none}.dshbw_link:hover{color:var(--dsw-alias-state-business-primary);text-decoration:underline}@keyframes dshbw-spin{from{transform:rotate(0deg)}to{transform:rotate(360deg)}}";
 		const tagId = "dsh-balance-widget/styles.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -20,11 +21,16 @@ window.__ModuleLoader__.load({
 			"wrap": "dshbw_wrap",
 			"btn": "dshbw_btn",
 			"pop": "dshbw_pop",
+			"head": "dshbw_head",
+			"title": "dshbw_title",
+			"refresh": "dshbw_refresh",
 			"row": "dshbw_row",
+			"label": "dshbw_label",
 			"val": "dshbw_val",
 			"err": "dshbw_err",
 			"hint": "dshbw_hint",
-			"foot": "dshbw_foot"
+			"foot": "dshbw_foot",
+			"link": "dshbw_link"
 		};
 		//#endregion
 		//#region lib/types/client/pricing.js
@@ -100,6 +106,12 @@ window.__ModuleLoader__.load({
 			if (value >= 1e3) return `${(value / 1e3).toFixed(1)}K`;
 			return String(value);
 		}
+		/** Format an epoch ms as HH:MM local time. */
+		function formatTime(ms) {
+			if (ms === void 0 || ms === null) return "—";
+			const d = new Date(ms);
+			return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+		}
 		//#endregion
 		//#region lib/types/client/balance-api.js
 		/** Same-origin balance route (host half registers it over ctx.webServer). */
@@ -107,6 +119,8 @@ window.__ModuleLoader__.load({
 		/** Same-origin cost routes. */
 		const LAST_COST_ROUTE = "/api/dsh-balance/last-cost";
 		const TODAY_COST_ROUTE = "/api/dsh-balance/today-cost";
+		/** Official DeepSeek platform top-up page (opens in a new tab). */
+		const TOP_UP_URL = "https://platform.deepseek.com/top_up";
 		/**
 		* Fetch the account balance from the host proxy.
 		* @returns { ok, balanceInfos?, modelId?, error? }
@@ -125,7 +139,13 @@ window.__ModuleLoader__.load({
 				}
 				const payload = await response.json();
 				if (payload.ok === false) return { ok: false, error: payload.error ?? "unknown balance error" };
-				return { ok: true, balanceInfos: payload.balance_infos ?? [], modelId: payload.modelId };
+				return {
+					ok: true,
+					balanceInfos: payload.balance_infos ?? [],
+					modelId: payload.modelId,
+					lowThreshold: payload.lowThreshold,
+					criticalThreshold: payload.criticalThreshold
+				};
 			} catch (error) {
 				return { ok: false, error: error instanceof Error ? error.message : String(error) };
 			}
@@ -160,6 +180,28 @@ window.__ModuleLoader__.load({
 			return { symbol, total, currency: entry.currency };
 		}
 		//#endregion
+		//#region lib/types/client/ExplainIcon.js
+		/**
+		* A small ⓘ marker with a hover tooltip explaining a term. Wraps the
+		* official DSH Tooltip so the popover stays visually consistent.
+		* @param {Object} props - label (tooltip text), t (locale).
+		*/
+		function ExplainIcon({ label, t }) {
+			return (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Tooltip, {
+				label: label,
+				side: "top",
+				delayMs: 300,
+				children: (0, react_jsx_runtime.jsx)("span", {
+					role: "img",
+					"aria-label": t("explain.aria"),
+					style: { cursor: "help", color: "var(--dsw-alias-label-tertiary)", marginLeft: 3, fontSize: 11, lineHeight: 1 },
+					children: (0, react_jsx_runtime.jsx)("span", {
+						children: "ⓘ"
+					})
+				})
+			});
+		}
+		//#endregion
 		//#region lib/types/client/BalanceWidget.js
 		/**
 		* Corner widget: a small balance button in the session header utilities
@@ -175,41 +217,102 @@ window.__ModuleLoader__.load({
 			const [todayCost, setTodayCost] = (0, react.useState)(null);
 			const [error, setError] = (0, react.useState)(null);
 			const [loading, setLoading] = (0, react.useState)(false);
+			const [refreshing, setRefreshing] = (0, react.useState)(false);
+			const [lastUpdated, setLastUpdated] = (0, react.useState)(null);
+			const [lowThreshold, setLowThreshold] = (0, react.useState)(5);
+			const [criticalThreshold, setCriticalThreshold] = (0, react.useState)(1);
 			const usage = useProjection("tokenUsage");
 			const priced = priceSession(usage, modelId);
+			/** Balance severity: 0=ok, 1=low, 2=critical (thresholds from host config). */
+			const balanceLevel = balance === null ? 0 : balance.total < criticalThreshold ? 2 : balance.total < lowThreshold ? 1 : 0;
+			/** Fetch balance only (used for the always-visible corner amount). */
+			const refreshBalance = async () => {
+				const result = await fetchBalance();
+				if (result.ok) {
+					setBalance(displayBalance(result.balanceInfos));
+					setLastUpdated(Date.now());
+					if (typeof result.modelId === "string" && result.modelId !== "") setModelId(result.modelId);
+					if (typeof result.lowThreshold === "number" && result.lowThreshold >= 0) setLowThreshold(result.lowThreshold);
+					if (typeof result.criticalThreshold === "number" && result.criticalThreshold >= 0) setCriticalThreshold(result.criticalThreshold);
+				}
+			};
+			/** Fetch all data; optionally keeps the popover's silent loading state. */
+			const refreshAll = async (showLoading) => {
+				if (showLoading) setLoading(true);
+				setError(null);
+				const [balanceResult, lastResult, todayResult] = await Promise.all([
+					fetchBalance(),
+					fetchCost(LAST_COST_ROUTE, sessionId),
+					fetchCost(TODAY_COST_ROUTE)
+				]);
+				// Collect every failure into one fresh message; never accumulate
+				// across refreshes (each refresh starts from a clean slate).
+				const failures = [];
+				if (balanceResult.ok) {
+					setBalance(displayBalance(balanceResult.balanceInfos));
+					setLastUpdated(Date.now());
+					if (typeof balanceResult.modelId === "string" && balanceResult.modelId !== "") setModelId(balanceResult.modelId);
+					if (typeof balanceResult.lowThreshold === "number" && balanceResult.lowThreshold >= 0) setLowThreshold(balanceResult.lowThreshold);
+					if (typeof balanceResult.criticalThreshold === "number" && balanceResult.criticalThreshold >= 0) setCriticalThreshold(balanceResult.criticalThreshold);
+				} else {
+					setBalance(null);
+					failures.push(`余额: ${balanceResult.error}`);
+				}
+				if (lastResult.ok) setLastCost(lastResult.cost);
+				else if (lastResult.error) failures.push(`最近提问: ${lastResult.error}`);
+				if (todayResult.ok) setTodayCost(todayResult.cost);
+				else if (todayResult.error) failures.push(`今日: ${todayResult.error}`);
+				setError(failures.length > 0 ? failures.join("；") : null);
+				if (showLoading) setLoading(false);
+			};
+			// Fetch balance on mount, then auto-refresh every 60s so the corner
+			// amount never goes stale (balance changes only on usage/top-up).
+			(0, react.useEffect)(() => {
+				refreshBalance();
+				const timer = setInterval(refreshBalance, 60000);
+				return () => clearInterval(timer);
+			}, []);
+			// Close the popover when clicking anywhere outside the widget.
+			const wrapRef = (0, react.useRef)(null);
+			(0, react.useEffect)(() => {
+				if (!open) return;
+				const onDocClick = (event) => {
+					const el = wrapRef.current;
+					if (el !== null && !el.contains(event.target)) setOpen(false);
+				};
+				document.addEventListener("mousedown", onDocClick);
+				return () => document.removeEventListener("mousedown", onDocClick);
+			}, [open]);
+			// While the popover is open, silently refresh costs every 30s so the
+			// figures keep up with ongoing conversation activity. The host caches
+			// cost computations, so this is cheap.
+			(0, react.useEffect)(() => {
+				if (!open) return;
+				const timer = setInterval(() => {
+					refreshAll(false);
+				}, 30000);
+				return () => clearInterval(timer);
+			}, [open]);
 			const toggle = async () => {
 				const next = !open;
 				setOpen(next);
-				if (next) {
-					setLoading(true);
-					setError(null);
-					const [balanceResult, lastResult, todayResult] = await Promise.all([
-						fetchBalance(),
-						fetchCost(LAST_COST_ROUTE, sessionId),
-						fetchCost(TODAY_COST_ROUTE)
-					]);
-					if (balanceResult.ok) {
-						setBalance(displayBalance(balanceResult.balanceInfos));
-						if (typeof balanceResult.modelId === "string" && balanceResult.modelId !== "") setModelId(balanceResult.modelId);
-					} else {
-						setBalance(null);
-						setError(balanceResult.error);
-					}
-					if (lastResult.ok) setLastCost(lastResult.cost);
-					else if (!lastResult.ok && lastResult.error) setError((error ?? "") + (error ? " " : "") + `last: ${lastResult.error}`);
-					if (todayResult.ok) setTodayCost(todayResult.cost);
-					else if (!todayResult.ok && todayResult.error) setError((error ?? "") + (error ? " " : "") + `today: ${todayResult.error}`);
-					setLoading(false);
-				}
+				if (next) await refreshAll(true);
+			};
+			const onRefresh = async () => {
+				setRefreshing(true);
+				await refreshAll(false);
+				setRefreshing(false);
 			};
 			return (0, react_jsx_runtime.jsx)("div", {
+				ref: wrapRef,
 				className: styles.wrap,
 				children: (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, {
 					children: [(0, react_jsx_runtime.jsxs)("button", {
 						type: "button",
 						className: styles.btn,
+						"data-level": balanceLevel > 0 ? balanceLevel : undefined,
 						"aria-label": t("aria"),
-						title: t("title"),
+						title: balanceLevel > 0 ? t(`warn.title.${balanceLevel}`) : t("title"),
 						onClick: toggle,
 						children: ["💰", balance !== null && (0, react_jsx_runtime.jsx)("span", {
 							children: `${balance.symbol}${balance.total.toFixed(2)}`
@@ -219,20 +322,54 @@ window.__ModuleLoader__.load({
 						role: "dialog",
 						children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 							children: [(0, react_jsx_runtime.jsx)("div", {
+								className: styles.head,
+								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+									children: [(0, react_jsx_runtime.jsx)("span", {
+										className: styles.title,
+										children: t("title")
+									}), (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										className: styles.refresh,
+										"aria-label": t("refresh.aria"),
+										title: t("refresh.title"),
+										"data-spinning": refreshing || undefined,
+										disabled: refreshing,
+										onClick: onRefresh,
+										children: (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconRefreshOutline14, {})
+									})]
+								})
+							}), (0, react_jsx_runtime.jsx)("div", {
 								className: styles.row,
 								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 									children: [(0, react_jsx_runtime.jsx)("span", {
-										children: t("balance")
+										className: styles.label,
+										children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+											children: [t("balance"), (0, react_jsx_runtime.jsx)(ExplainIcon, {
+												label: t("explain.balance"),
+												t
+											})]
+										})
 									}), (0, react_jsx_runtime.jsx)("span", {
 										className: styles.val,
+										"data-level": balanceLevel > 0 ? balanceLevel : undefined,
 										children: loading ? "…" : balance !== null ? `${balance.symbol}${balance.total.toFixed(2)}` : "—"
 									})]
 								})
+							}), balanceLevel > 0 && (0, react_jsx_runtime.jsx)("div", {
+								className: styles.err,
+								role: "status",
+								children: t(`warn.text.${balanceLevel}`)
 							}), (0, react_jsx_runtime.jsx)("div", {
 								className: styles.row,
 								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 									children: [(0, react_jsx_runtime.jsx)("span", {
-										children: t("sessionCost")
+										className: styles.label,
+										children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+											children: [t("sessionCost"), (0, react_jsx_runtime.jsx)(ExplainIcon, {
+												label: t("explain.sessionCost"),
+												t
+											})]
+										})
 									}), (0, react_jsx_runtime.jsx)("span", {
 										className: styles.val,
 										children: priced !== null ? formatCny(priced.total) : "—"
@@ -242,7 +379,13 @@ window.__ModuleLoader__.load({
 								className: styles.row,
 								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 									children: [(0, react_jsx_runtime.jsx)("span", {
-										children: t("lastPromptCost")
+										className: styles.label,
+										children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+											children: [t("lastPromptCost"), (0, react_jsx_runtime.jsx)(ExplainIcon, {
+												label: t("explain.lastPromptCost"),
+												t
+											})]
+										})
 									}), (0, react_jsx_runtime.jsx)("span", {
 										className: styles.val,
 										children: loading ? "…" : lastCost !== null ? formatCny(lastCost) : "—"
@@ -252,7 +395,13 @@ window.__ModuleLoader__.load({
 								className: styles.row,
 								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 									children: [(0, react_jsx_runtime.jsx)("span", {
-										children: t("todayCost")
+										className: styles.label,
+										children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+											children: [t("todayCost"), (0, react_jsx_runtime.jsx)(ExplainIcon, {
+												label: t("explain.todayCost"),
+												t
+											})]
+										})
 									}), (0, react_jsx_runtime.jsx)("span", {
 										className: styles.val,
 										children: loading ? "…" : todayCost !== null ? formatCny(todayCost) : "—"
@@ -262,7 +411,13 @@ window.__ModuleLoader__.load({
 								className: styles.row,
 								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 									children: [(0, react_jsx_runtime.jsx)("span", {
-										children: t("tokens")
+										className: styles.label,
+										children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+											children: [t("tokens"), (0, react_jsx_runtime.jsx)(ExplainIcon, {
+												label: t("explain.tokens"),
+												t
+											})]
+										})
 									}), (0, react_jsx_runtime.jsx)("span", {
 										className: styles.val,
 										children: `${formatTokens((usage.uncachedInputTokens ?? 0) + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0))} in / ${formatTokens(usage.outputTokens ?? 0)} out`
@@ -274,14 +429,24 @@ window.__ModuleLoader__.load({
 								children: error
 							}), (0, react_jsx_runtime.jsx)("div", {
 								className: styles.hint,
-								children: t("hint")
+								children: lastUpdated !== null ? `${t("updatedAt")} ${formatTime(lastUpdated)} · ${t("hint")}` : t("hint")
 							}), (0, react_jsx_runtime.jsx)("div", {
 								className: styles.foot,
-								children: (0, react_jsx_runtime.jsx)("button", {
-									type: "button",
-									className: styles.btn,
-									onClick: () => setOpen(false),
-									children: t("close")
+								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+									children: [(0, react_jsx_runtime.jsx)("a", {
+										className: styles.link,
+										href: TOP_UP_URL,
+										target: "_blank",
+										rel: "noreferrer",
+										children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+											children: ["⚡", t("topUp")]
+										})
+									}), (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										className: styles.btn,
+										onClick: () => setOpen(false),
+										children: t("close")
+									})]
 								})
 							})]
 						})
@@ -297,24 +462,52 @@ window.__ModuleLoader__.load({
 		const zh = {
 			"aria": "查看账户余额与成本",
 			"title": "余额与成本",
+			"refresh.aria": "刷新数据",
+			"refresh.title": "刷新余额与成本",
 			"balance": "账户余额",
-			"sessionCost": "本会话成本（估算）",
-			"lastPromptCost": "最近一次提问（估算）",
-			"todayCost": "今天总成本（估算）",
+			"sessionCost": "这个对话已花费",
+			"lastPromptCost": "最近一次提问",
+			"todayCost": "今天总成本",
 			"tokens": "Token 用量",
-			"hint": "价格按 DeepSeek 官方峰谷定价估算，实际以账单为准。",
+			"explain.aria": "解释",
+			"explain.balance": "DeepSeek 账户可用余额，实时查询官方接口（每 60 秒刷新）。",
+			"explain.sessionCost": "当前这个对话从开始到现在累计的费用，按官方峰谷定价估算。",
+			"explain.lastPromptCost": "你刚发的这条提问（含 AI 回复）的费用估算。",
+			"explain.todayCost": "今天所有对话（含其他窗口）的费用合计估算。",
+			"explain.tokens": "本会话消耗的 token 数。1 token ≈ 0.75 个英文单词 ≈ 1 个汉字。",
+			"warn.title.1": "余额不足 ¥5，建议及时充值",
+			"warn.title.2": "余额低于 ¥1，即将耗尽！",
+			"warn.text.1": "⚠️ 余额不足 ¥5，建议及时充值。",
+			"warn.text.2": "⛔ 余额低于 ¥1，即将耗尽，请立即充值！",
+			"updatedAt": "更新于",
+			"hint": "价格为估算值，实际以官方账单为准。",
+			"topUp": "去充值",
 			"close": "关闭"
 		};
 		/** English dictionary, checked complete against the zh key set. */
 		const en = {
 			"aria": "View account balance and costs",
 			"title": "Balance & cost",
+			"refresh.aria": "Refresh data",
+			"refresh.title": "Refresh balance and costs",
 			"balance": "Account balance",
-			"sessionCost": "This session cost (est.)",
-			"lastPromptCost": "Last prompt (est.)",
-			"todayCost": "Today total (est.)",
+			"sessionCost": "This chat spent",
+			"lastPromptCost": "Last prompt",
+			"todayCost": "Today total",
 			"tokens": "Token usage",
-			"hint": "Prices estimated from DeepSeek official peak/off-peak rates; billing is authoritative.",
+			"explain.aria": "Explain",
+			"explain.balance": "DeepSeek account balance, fetched live from the official API.",
+			"explain.sessionCost": "Total estimated cost of this conversation since it started, priced at official peak/off-peak rates.",
+			"explain.lastPromptCost": "Estimated cost of your latest prompt, including the AI reply.",
+			"explain.todayCost": "Estimated total cost across all conversations today.",
+			"explain.tokens": "Tokens used by this session. 1 token ≈ 0.75 English words ≈ 1 CJK character.",
+			"warn.title.1": "Balance below ¥5, consider topping up",
+			"warn.title.2": "Balance below ¥1, almost exhausted!",
+			"warn.text.1": "⚠️ Balance below ¥5, consider topping up.",
+			"warn.text.2": "⛔ Balance below ¥1, almost exhausted — top up now!",
+			"updatedAt": "Updated",
+			"hint": "Prices are estimates; actual billing from the provider is authoritative.",
+			"topUp": "Top up",
 			"close": "Close"
 		};
 		//#endregion

package/lib/index.js

@@ -46,13 +46,17 @@ const CONFIG_FIELDS = {
 	balanceBaseURL: "string",
 	balanceApiKeyEnv: "string",
 	requestTimeoutMs: "number",
-	modelId: "string"
+	modelId: "string",
+	lowThreshold: "number",
+	criticalThreshold: "number"
 };
 const CONFIG_DEFAULTS = {
 	balanceBaseURL: DEFAULT_BASE_URL,
 	balanceApiKeyEnv: DEFAULT_API_KEY_ENV,
 	requestTimeoutMs: 5000,
-	modelId: DEFAULT_MODEL_ID
+	modelId: DEFAULT_MODEL_ID,
+	lowThreshold: 5,
+	criticalThreshold: 1
 };
 
 export const Config = {
@@ -102,7 +106,13 @@ function resolveConfig(raw) {
 			: Config.defaults.requestTimeoutMs,
 		modelId: typeof value.modelId === "string" && value.modelId !== ""
 			? value.modelId
-			: Config.defaults.modelId
+			: Config.defaults.modelId,
+		lowThreshold: typeof value.lowThreshold === "number" && Number.isFinite(value.lowThreshold) && value.lowThreshold >= 0
+			? value.lowThreshold
+			: Config.defaults.lowThreshold,
+		criticalThreshold: typeof value.criticalThreshold === "number" && Number.isFinite(value.criticalThreshold) && value.criticalThreshold >= 0
+			? value.criticalThreshold
+			: Config.defaults.criticalThreshold
 	};
 }
 
@@ -290,19 +300,50 @@ function awaitImportFs() {
 	return _fs;
 }
 
+/** Cache the zstd availability probe (run once per process). */
+let _zstdAvailable = void 0;
+
+/**
+ * Probe whether the zstd CLI is available, caching the result.
+ * macOS does not ship zstd by default, so this must be checked lazily and
+ * surfaced as a distinct error rather than a silent "session not found".
+ */
+async function isZstdAvailable() {
+	if (_zstdAvailable !== void 0) return _zstdAvailable;
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const execFileP = promisify(execFile);
+	try {
+		await execFileP("zstd", ["--version"], { timeout: 5000 });
+		_zstdAvailable = true;
+	} catch {
+		_zstdAvailable = false;
+	}
+	return _zstdAvailable;
+}
+
 /**
- * Decompress a .zstd session file to text via the zstd CLI (present on
- * macOS/Linux with zstd installed). Returns undefined on failure.
+ * Decompress a .zstd session file to text via the zstd CLI.
+ * @returns { ok: true, text } | { ok: false, error }
  */
 async function decompressSession(path) {
+	if (!(await isZstdAvailable())) {
+		return {
+			ok: false,
+			error: "zstd CLI not found — install it (e.g. `brew install zstd`) to read session files"
+		};
+	}
 	const { execFile } = await import("node:child_process");
 	const { promisify } = await import("node:util");
 	const execFileP = promisify(execFile);
 	try {
 		const { stdout } = await execFileP("zstd", ["-d", "-c", path], { maxBuffer: 512 * 1024 * 1024 });
-		return stdout;
-	} catch {
-		return void 0;
+		return { ok: true, text: stdout };
+	} catch (error) {
+		return {
+			ok: false,
+			error: `failed to decompress session file: ${error instanceof Error ? error.message : String(error)}`
+		};
 	}
 }
 
@@ -397,13 +438,33 @@ async function collectAllSessionSamples() {
 	}
 	const perSession = [];
 	for (const file of files) {
-		const text = await decompressSession(file);
-		if (text === void 0) continue;
-		perSession.push(parseSessionUsages(text));
+		const result = await decompressSession(file);
+		if (!result.ok) continue;
+		perSession.push(parseSessionUsages(result.text));
 	}
 	return perSession;
 }
 
+/** Simple in-memory TTL cache for cost computations (30s). */
+const costCache = new Map();
+const COST_CACHE_TTL_MS = 30000;
+function cachedOrCompute(key, compute) {
+	const hit = costCache.get(key);
+	if (hit !== void 0 && Date.now() - hit.at < COST_CACHE_TTL_MS) return hit.value;
+	const value = compute();
+	costCache.set(key, { at: Date.now(), value });
+	return value;
+}
+/** In-flight dedupe: key → shared promise, dropped when settled. */
+const costInflight = new Map();
+function dedupe(key, compute) {
+	const pending = costInflight.get(key);
+	if (pending !== void 0) return pending;
+	const promise = compute().finally(() => costInflight.delete(key));
+	costInflight.set(key, promise);
+	return promise;
+}
+
 /** Build the route table for the balance widget. */
 function makeRoutes(ctx, config) {
 	return [
@@ -414,9 +475,19 @@ function makeRoutes(ctx, config) {
 				if (!guard(req, res, "GET")) return;
 				const result = await fetchBalance(ctx, config);
 				if (result.ok) {
-					writeJson(res, 200, { ...result, modelId: config.modelId });
+					writeJson(res, 200, {
+						...result,
+						modelId: config.modelId,
+						lowThreshold: config.lowThreshold,
+						criticalThreshold: config.criticalThreshold
+					});
 				} else {
-					writeJson(res, 502, { error: result.error, modelId: config.modelId });
+					writeJson(res, 502, {
+						error: result.error,
+						modelId: config.modelId,
+						lowThreshold: config.lowThreshold,
+						criticalThreshold: config.criticalThreshold
+					});
 				}
 			}
 		},
@@ -442,14 +513,19 @@ function makeRoutes(ctx, config) {
 					writeJson(res, 404, { error: `session ${sessionId} not found`, modelId: config.modelId });
 					return;
 				}
-				const text = await decompressSession(file);
-				if (text === void 0) {
-					writeJson(res, 502, { error: "failed to read session file", modelId: config.modelId });
+				const key = `last:${sessionId}`;
+				const compute = async () => {
+					const result = await decompressSession(file);
+					if (!result.ok) return { error: result.error };
+					const samples = parseSessionUsages(result.text);
+					return { value: lastTurnCost(samples) };
+				};
+				const outcome = await dedupe(key, () => cachedOrCompute(key, compute));
+				if (outcome.error !== void 0) {
+					writeJson(res, 502, { error: outcome.error, modelId: config.modelId });
 					return;
 				}
-				const samples = parseSessionUsages(text);
-				const result = lastTurnCost(samples);
-				writeJson(res, 200, { ...result, modelId: config.modelId });
+				writeJson(res, 200, { ...outcome.value, modelId: config.modelId });
 			}
 		},
 		{
@@ -457,9 +533,13 @@ function makeRoutes(ctx, config) {
 			path: API.todayCost,
 			handler: async (req, res) => {
 				if (!guard(req, res, "GET")) return;
-				const perSession = await collectAllSessionSamples();
-				const result = todayCost(perSession);
-				writeJson(res, 200, { ...result, modelId: config.modelId });
+				const key = "today";
+				const compute = async () => {
+					const perSession = await collectAllSessionSamples();
+					return { value: todayCost(perSession) };
+				};
+				const outcome = await dedupe(key, () => cachedOrCompute(key, compute));
+				writeJson(res, 200, { ...outcome.value, modelId: config.modelId });
 			}
 		}
 	];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-balance-widget",
   "description": "Balance & cost widget for the dsh web GUI: a corner icon in the conversation session header that shows the DeepSeek account balance and the current session's estimated spend on click. Host half proxies the official /user/balance API over ctx.webServer (loopback-only); client half renders the icon and popover. Zero external dependencies — works on Node 24.",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "main": "lib/index.js",
   "files": [