dsh-balance-widget 0.3.2 → 0.4.1

package/README.en.md

@@ -11,6 +11,12 @@
 
 A balance & cost widget for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) Web GUI: a 💰 icon in the corner of the conversation session header. Click it to see your DeepSeek account balance and the current session's estimated spend.
 
+## Preview
+
+| Balance always visible | Popover on click |
+| --- | --- |
+| ![Balance corner](docs/screenshot-corner.png) | ![Popover detail](docs/screenshot-popover.png) |
+
 ## How it differs from similar plugins
 
 | Aspect | This plugin | Others (dsh-balance / dsh-token-price / ...) |
@@ -32,6 +38,10 @@ A balance & cost widget for the [DeepSeek Harness](https://github.com/deepseek-a
 - **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.
+- **Sidebar card** — a persistent card at the sidebar footer shows balance, a remaining-ratio bar, and today's total; globally visible, refreshes every 60s.
+- **Remaining-ratio bar** — blue (healthy) → amber (below lowThreshold) → red (below criticalThreshold).
+- **Official price auto-sync** — fetches the DeepSeek official pricing page on startup and every 12h; falls back to built-in rates on failure.
+- **Agent tool** — a `deepseek_billing` tool lets the model answer "how much balance do I have / how much did today cost".
 - **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

package/README.md

@@ -11,6 +11,12 @@
 
 DeepSeek Harness (DSH) Web GUI 的余额与成本小部件：在会话头部右上角（角落）渲染一个 💰 图标，点击弹出账户余额与本会话的估算成本。
 
+## 效果预览
+
+| 余额常驻右上角 | 点击弹出详情 |
+| --- | --- |
+| ![余额常驻](docs/screenshot-corner.png) | ![弹框详情](docs/screenshot-popover.png) |
+
 ## 与同类插件的区别
 
 | 特点 | 本插件 | 同类插件（dsh-balance / dsh-token-price 等） |
@@ -32,6 +38,10 @@ DeepSeek Harness (DSH) Web GUI 的余额与成本小部件：在会话头部右
 - **今天总成本（估算）** — 遍历 `~/.dsh/sessions/` 下所有会话，累加今天（自然日）的 token 用量 × 单价。
 - **Token 用量** — 同时展示本会话输入（含缓存命中）/ 输出 token 数。
 - **一键充值** — 弹层底部「去充值」链接直达 DeepSeek 官方充值页（platform.deepseek.com/top_up），新窗口打开。
+- **侧边栏常驻卡片** — 侧边栏底部（设置上方）显示余额 + 剩余比例条 + 今日花费，全局可见，60 秒自动刷新。
+- **余额剩余比例条** — 蓝色（充足）→ 琥珀（低于 lowThreshold）→ 红色（低于 criticalThreshold）三档。
+- **官方价格自动同步** — 启动时 + 每 12 小时抓取 DeepSeek 官方定价页，改价自动跟进；失败回退内置价目表。
+- **模型工具查询** — 新增 `deepseek_billing` 工具，可直接问模型"余额多少/今天花了多少"。
 - **按需刷新** — 无轮询、无后台请求；只有点击图标时才发起查询，不消耗任何 token。
 
 ## 架构

package/lib/client.js

@@ -8,7 +8,7 @@ window.__ModuleLoader__.load({
 		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_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 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)}}.dshbw_side{display:flex;flex-direction:column;gap:4px;padding:6px 8px;margin:0 8px 4px;border-radius:8px;background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary)}.dshbw_side:hover{background:var(--dsw-alias-interactive-bg-hover)}.dshbw_sideTop{display:flex;align-items:center;justify-content:space-between;gap:8px;font-size:12px;line-height:18px}.dshbw_sideAmount{font-weight:600}.dshbw_sideAmount[data-level=\"1\"]{color:var(--dsw-alias-state-warn-primary)}.dshbw_sideAmount[data-level=\"2\"]{color:var(--dsw-alias-state-error-primary)}.dshbw_bar{height:4px;border-radius:2px;background:var(--dsw-alias-border-l2);overflow:hidden}.dshbw_barFill{height:100%;border-radius:2px;transition:width .4s ease}.dshbw_barFill[data-level=\"0\"]{background:var(--dsw-alias-state-business-primary)}.dshbw_barFill[data-level=\"1\"]{background:var(--dsw-alias-state-warn-primary)}.dshbw_barFill[data-level=\"2\"]{background:var(--dsw-alias-state-error-primary)}.dshbw_sideFoot{display:flex;justify-content:space-between;font-size:10px;line-height:14px;color:var(--dsw-alias-label-tertiary)}.dshbw_sideWrap{position:relative}.dshbw_side{display:flex;flex-direction:column;gap:4px;width:100%;padding:6px 8px;margin:0 8px 4px;border:none;border-radius:8px;background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);cursor:pointer;font-family:inherit;text-align:left}.dshbw_side:hover{background:var(--dsw-alias-interactive-bg-hover)}.dshbw_sidePop{position:absolute;bottom:calc(100% + 8px);left:8px;z-index:70;min-width:240px;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_sidePopHead{display:flex;align-items:center;justify-content:space-between;margin-bottom:6px}.dshbw_sidePopTitle{font-weight:600}.dshbw_sidePopClose{background:none;border:none;cursor:pointer;color:var(--dsw-alias-label-tertiary);font-size:16px;line-height:1;padding:0 2px;font-family:inherit}.dshbw_sidePopClose:hover{color:var(--dsw-alias-label-primary)}.dshbw_sidePopFoot{display:flex;align-items:center;justify-content:space-between;gap:8px;margin-top:10px}.dshbw_sidePopRefresh{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:22px;height:22px;border-radius:6px;padding:0;font-family:inherit}.dshbw_sidePopRefresh:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l3);background:var(--dsw-alias-interactive-bg-hover)}";
 		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");
@@ -30,7 +30,20 @@ window.__ModuleLoader__.load({
 			"err": "dshbw_err",
 			"hint": "dshbw_hint",
 			"foot": "dshbw_foot",
-			"link": "dshbw_link"
+			"link": "dshbw_link",
+			"side": "dshbw_side",
+			"sideWrap": "dshbw_sideWrap",
+			"sideTop": "dshbw_sideTop",
+			"sideAmount": "dshbw_sideAmount",
+			"bar": "dshbw_bar",
+			"barFill": "dshbw_barFill",
+			"sideFoot": "dshbw_sideFoot",
+			"sidePop": "dshbw_sidePop",
+			"sidePopHead": "dshbw_sidePopHead",
+			"sidePopTitle": "dshbw_sidePopTitle",
+			"sidePopClose": "dshbw_sidePopClose",
+			"sidePopFoot": "dshbw_sidePopFoot",
+			"sidePopRefresh": "dshbw_sidePopRefresh"
 		};
 		//#endregion
 		//#region lib/types/client/pricing.js
@@ -180,99 +193,48 @@ window.__ModuleLoader__.load({
 			return { symbol, total, currency: entry.currency };
 		}
 		//#endregion
-		//#region lib/types/client/ExplainIcon.js
+		//#region lib/types/client/SidebarBalanceCard.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).
+		* Sidebar footer card: balance + remaining-ratio bar + today cost.
+		* Root-scoped (global, not per-session) — fetches balance itself and
+		* refreshes every 60s. Clicking opens a detail popover (balance, today
+		* cost, top-up, refresh) using only global data.
+		* @param {Object} props - wide (sidebar expanded), 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
-		* slot. Clicking opens a popover with the account balance and the current
-		* session's estimated spend (priced from the tokenUsage projection).
-		* @param {Object} props - useProjection (framework), sessionId (slot scope).
-		*/
-		function BalanceWidget({ useProjection, sessionId, t }) {
+		function SidebarBalanceCard({ wide, t }) {
 			const [open, setOpen] = (0, react.useState)(false);
 			const [balance, setBalance] = (0, react.useState)(null);
-			const [modelId, setModelId] = (0, react.useState)("deepseek-v4-flash");
-			const [lastCost, setLastCost] = (0, react.useState)(null);
 			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) => {
+			const [error, setError] = (0, react.useState)(null);
+			const [loading, setLoading] = (0, react.useState)(false);
+			const refresh = async (showLoading) => {
 				if (showLoading) setLoading(true);
 				setError(null);
-				const [balanceResult, lastResult, todayResult] = await Promise.all([
+				const [bResult, tResult] = 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);
+				if (bResult.ok) {
+					setBalance(displayBalance(bResult.balanceInfos));
+					if (typeof bResult.lowThreshold === "number" && bResult.lowThreshold >= 0) setLowThreshold(bResult.lowThreshold);
+					if (typeof bResult.criticalThreshold === "number" && bResult.criticalThreshold >= 0) setCriticalThreshold(bResult.criticalThreshold);
 				} else {
-					setBalance(null);
-					failures.push(`余额: ${balanceResult.error}`);
+					failures.push(`余额: ${bResult.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}`);
+				if (tResult.ok) setTodayCost(tResult.cost);
+				else if (tResult.error) failures.push(`今日: ${tResult.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);
+				refresh(false);
+				const timer = setInterval(() => refresh(false), 60000);
 				return () => clearInterval(timer);
 			}, []);
-			// Close the popover when clicking anywhere outside the widget.
+			// Close the popover when clicking outside the card.
 			const wrapRef = (0, react.useRef)(null);
 			(0, react.useEffect)(() => {
 				if (!open) return;
@@ -283,144 +245,98 @@ window.__ModuleLoader__.load({
 				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 level = balance === null ? 0 : balance.total < criticalThreshold ? 2 : balance.total < lowThreshold ? 1 : 0;
+			// Remaining-ratio: 100% at lowThreshold (or above), 0% at 0.
+			let percent = 100;
+			if (balance !== null && balance.total < lowThreshold) {
+				percent = lowThreshold <= 0 ? 100 : Math.max(0, Math.round(balance.total / lowThreshold * 100));
+			}
 			const toggle = async () => {
 				const next = !open;
 				setOpen(next);
-				if (next) await refreshAll(true);
-			};
-			const onRefresh = async () => {
-				setRefreshing(true);
-				await refreshAll(false);
-				setRefreshing(false);
+				if (next) await refresh(true);
 			};
 			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", {
+				className: styles.sideWrap,
+				children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+					children: [(0, react_jsx_runtime.jsx)("button", {
 						type: "button",
-						className: styles.btn,
-						"data-level": balanceLevel > 0 ? balanceLevel : undefined,
-						"aria-label": t("aria"),
-						title: balanceLevel > 0 ? t(`warn.title.${balanceLevel}`) : t("title"),
+						className: styles.side,
+						title: t("title"),
 						onClick: toggle,
-						children: ["💰", balance !== null && (0, react_jsx_runtime.jsx)("span", {
-							children: `${balance.symbol}${balance.total.toFixed(2)}`
-						})]
-					}), open && (0, react_jsx_runtime.jsx)("div", {
-						className: styles.pop,
-						role: "dialog",
 						children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 							children: [(0, react_jsx_runtime.jsx)("div", {
-								className: styles.head,
+								className: styles.sideTop,
 								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, {})
+										children: "💰"
+									}), (0, react_jsx_runtime.jsx)("span", {
+										className: styles.sideAmount,
+										"data-level": level > 0 ? level : undefined,
+										children: balance !== null ? `${balance.symbol}${balance.total.toFixed(2)}` : "—"
 									})]
 								})
 							}), (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", {
-										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)}` : "—"
-									})]
+								className: styles.bar,
+								"aria-label": t("side.bar"),
+								children: (0, react_jsx_runtime.jsx)("div", {
+									className: styles.barFill,
+									"data-level": level,
+									style: { width: `${percent}%` }
 								})
-							}), 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,
+								className: styles.sideFoot,
 								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 									children: [(0, react_jsx_runtime.jsx)("span", {
-										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
-											})]
-										})
+										children: t("todayCostShort")
 									}), (0, react_jsx_runtime.jsx)("span", {
-										className: styles.val,
-										children: priced !== null ? formatCny(priced.total) : "—"
+										children: todayCost !== null ? formatCny(todayCost) : "—"
 									})]
 								})
-							}), (0, react_jsx_runtime.jsx)("div", {
-								className: styles.row,
+							})]
+						})
+					}), open && (0, react_jsx_runtime.jsx)("div", {
+						className: styles.sidePop,
+						role: "dialog",
+						children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+							children: [(0, react_jsx_runtime.jsx)("div", {
+								className: styles.sidePopHead,
 								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
 									children: [(0, react_jsx_runtime.jsx)("span", {
-										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) : "—"
+										className: styles.sidePopTitle,
+										children: t("title")
+									}), (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										className: styles.sidePopClose,
+										"aria-label": t("close"),
+										onClick: () => setOpen(false),
+										children: "×"
 									})]
 								})
 							}), (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", {
-										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
-											})]
-										})
+										children: t("balance")
 									}), (0, react_jsx_runtime.jsx)("span", {
 										className: styles.val,
-										children: loading ? "…" : todayCost !== null ? formatCny(todayCost) : "—"
+										"data-level": level > 0 ? level : undefined,
+										children: loading ? "…" : balance !== null ? `${balance.symbol}${balance.total.toFixed(2)}` : "—"
 									})]
 								})
-							}), priced !== null && (0, react_jsx_runtime.jsx)("div", {
+							}), level > 0 && (0, react_jsx_runtime.jsx)("div", {
+								className: styles.err,
+								role: "status",
+								children: t(`warn.text.${level}`)
+							}), (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", {
-										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
-											})]
-										})
+										children: t("todayCost")
 									}), (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`
+										children: loading ? "…" : todayCost !== null ? formatCny(todayCost) : "—"
 									})]
 								})
 							}), error !== null && (0, react_jsx_runtime.jsx)("div", {
@@ -428,24 +344,21 @@ window.__ModuleLoader__.load({
 								role: "status",
 								children: error
 							}), (0, react_jsx_runtime.jsx)("div", {
-								className: styles.hint,
-								children: lastUpdated !== null ? `${t("updatedAt")} ${formatTime(lastUpdated)} · ${t("hint")}` : t("hint")
-							}), (0, react_jsx_runtime.jsx)("div", {
-								className: styles.foot,
+								className: styles.sidePopFoot,
 								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")]
-										})
+										children: t("topUp")
 									}), (0, react_jsx_runtime.jsx)("button", {
 										type: "button",
-										className: styles.btn,
-										onClick: () => setOpen(false),
-										children: t("close")
+										className: styles.sidePopRefresh,
+										"aria-label": t("refresh.aria"),
+										title: t("refresh.title"),
+										onClick: () => refresh(true),
+										children: (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconRefreshOutline14, {})
 									})]
 								})
 							})]
@@ -465,21 +378,13 @@ window.__ModuleLoader__.load({
 			"refresh.aria": "刷新数据",
 			"refresh.title": "刷新余额与成本",
 			"balance": "账户余额",
-			"sessionCost": "这个对话已花费",
-			"lastPromptCost": "最近一次提问",
 			"todayCost": "今天总成本",
-			"tokens": "Token 用量",
-			"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": "更新于",
+			"side.bar": "余额剩余比例",
+			"todayCostShort": "今日",
 			"hint": "价格为估算值，实际以官方账单为准。",
 			"topUp": "去充值",
 			"close": "关闭"
@@ -491,21 +396,13 @@ window.__ModuleLoader__.load({
 			"refresh.aria": "Refresh data",
 			"refresh.title": "Refresh balance and costs",
 			"balance": "Account balance",
-			"sessionCost": "This chat spent",
-			"lastPromptCost": "Last prompt",
 			"todayCost": "Today total",
-			"tokens": "Token usage",
-			"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",
+			"side.bar": "Balance remaining ratio",
+			"todayCostShort": "Today",
 			"hint": "Prices are estimates; actual billing from the provider is authoritative.",
 			"topUp": "Top up",
 			"close": "Close"
@@ -518,8 +415,9 @@ window.__ModuleLoader__.load({
 			"locale"
 		];
 		/**
-		* Client plugin body: register the corner balance widget in the
-		* conversation session header utilities slot.
+		* Client plugin body: register the sidebar footer balance card (the
+		* single entry point since v0.4.1; the former header widget is removed
+		* to avoid duplicate always-visible balances).
 		* @param ctx - client root context.
 		*/
 		function apply(ctx) {
@@ -527,13 +425,12 @@ window.__ModuleLoader__.load({
 				zh,
 				en
 			}), "dsh-balance-widget: dictionaries");
-			ctx.slots.inject("conversation.session.header.utilities", () => ctx.slots.register({
-				name: "conversation.session.header.utilities",
+			ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
+				name: "sidebar.footer.action",
 				id: "balance-widget",
-				order: 90,
-				locale: NS,
-				inject: (sessionId) => ({ sessionId })
-			}, BalanceWidget));
+				order: 10,
+				locale: NS
+			}, SidebarBalanceCard));
 		}
 		//#endregion
 		exports.apply = apply;

package/lib/index.js

@@ -221,14 +221,25 @@ async function fetchBalance(ctx, config) {
 /**
  * Pricing table (CNY per 1M tokens, official 2026-08-17 peak/off-peak).
  * Mirrors the client half; kept here so host-computed costs use the same
- * numbers.
+ * numbers. Mutable: syncOfficialPricing() may replace it with freshly parsed
+ * official rates (falling back to these defaults on failure).
  */
-const PRICING = {
+const DEFAULT_PRICING = {
 	"deepseek-v4-flash": { peak: { inputMiss: 3.0, inputHit: 0.10, output: 9.0 }, offPeak: { inputMiss: 1.5, inputHit: 0.05, output: 4.5 } },
 	"deepseek-v4-pro": { peak: { inputMiss: 9.0, inputHit: 0.30, output: 27.0 }, offPeak: { inputMiss: 4.5, inputHit: 0.15, output: 13.5 } },
 	"deepseek-chat": { peak: { inputMiss: 3.0, inputHit: 0.10, output: 9.0 }, offPeak: { inputMiss: 1.5, inputHit: 0.05, output: 4.5 } },
 	"deepseek-reasoner": { peak: { inputMiss: 9.0, inputHit: 0.30, output: 27.0 }, offPeak: { inputMiss: 4.5, inputHit: 0.15, output: 13.5 } }
 };
+let pricingTable = { ...DEFAULT_PRICING };
+/** Source of the current pricing: "default" | "synced". */
+let pricingSource = "default";
+/** Last successful sync time (ms epoch), or null. */
+let pricingSyncedAt = null;
+
+/** Official pricing page (parsed for peak/off-peak rates). */
+const PRICING_URL = "https://api-docs.deepseek.com/zh-cn/quick_start/pricing/";
+const PRICE_SYNC_INTERVAL_MS = 12 * 60 * 60 * 1000;
+
 const PRICING_ALIASES = {
 	"deepseek-vision": "deepseek-v4-flash",
 	"deepseek-official": "deepseek-v4-flash"
@@ -243,7 +254,7 @@ function isPeak(date) {
 /** Map a provider/model id to a pricing key. */
 function pricingKey(modelId) {
 	if (modelId === void 0 || modelId === null) return "deepseek-v4-flash";
-	if (PRICING[modelId] !== void 0) return modelId;
+	if (pricingTable[modelId] !== void 0) return modelId;
 	const alias = PRICING_ALIASES[modelId];
 	if (alias !== void 0) return alias;
 	// heuristic: pro/reasoner-ish names price as pro
@@ -258,10 +269,104 @@ function priceUsage(usage, modelId, timeMs) {
 	const hit = usage.cacheReadTokens ?? 0;
 	const output = usage.outputTokens ?? 0;
 	if (input + hit + output <= 0) return 0;
-	const table = isPeak(new Date(timeMs ?? Date.now())) ? PRICING[pricingKey(modelId)].peak : PRICING[pricingKey(modelId)].offPeak;
+	const table = isPeak(new Date(timeMs ?? Date.now())) ? pricingTable[pricingKey(modelId)].peak : pricingTable[pricingKey(modelId)].offPeak;
 	return (input * table.inputMiss + hit * table.inputHit + output * table.output) / 1e6;
 }
 
+/**
+ * Parse the official pricing page into our pricingTable shape.
+ * The page is HTML; we look for per-model peak/off-peak "per 1M tokens" rates.
+ * Returns true on success (pricingTable updated), false on any failure
+ * (pricingTable left untouched).
+ */
+async function syncOfficialPricing() {
+	try {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), 15000);
+		const response = await fetch(PRICING_URL, { signal: controller.signal });
+		clearTimeout(timer);
+		if (!response.ok) return false;
+		const html = await response.text();
+		const parsed = parsePricingPage(html);
+		if (parsed === null || Object.keys(parsed).length === 0) return false;
+		// Merge over defaults so any model we cannot parse keeps its fallback.
+		const merged = { ...DEFAULT_PRICING };
+		for (const [model, rates] of Object.entries(parsed)) merged[model] = rates;
+		pricingTable = merged;
+		pricingSource = "synced";
+		pricingSyncedAt = Date.now();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Best-effort parse of the official pricing page HTML. Looks for the standard
+ * "deepseek-v4-flash" / "deepseek-v4-pro" model blocks and per-million-token
+ * rates. This is heuristic: it tolerates missing fields and returns a partial
+ * table rather than failing the whole sync.
+ */
+function parsePricingPage(html) {
+	const out = {};
+	const modelIds = ["deepseek-v4-flash", "deepseek-v4-pro"];
+	for (const model of modelIds) {
+		const block = extractModelBlock(html, model);
+		if (block === null) continue;
+		const rates = parseRates(block);
+		if (rates !== null) out[model] = rates;
+	}
+	return out;
+}
+
+/** Extract the HTML section mentioning a model id (crude but robust). */
+function extractModelBlock(html, model) {
+	const idx = html.indexOf(model);
+	if (idx < 0) return null;
+	const start = Math.max(0, idx - 400);
+	const end = Math.min(html.length, idx + 3000);
+	return html.slice(start, end);
+}
+
+/**
+ * Parse per-1M-token rates from a block of HTML text. Looks for numbers near
+ * "输入"/"缓存命中"/"输出" (CN page) or "input"/"cache"/"output" (EN page),
+ * preferring the off-peak row. Returns { offPeak, peak } or null.
+ */
+function parseRates(block) {
+	// Strip tags to plain text for simpler matching.
+	const text = block.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+	const num = (pattern) => {
+		const m = text.match(pattern);
+		if (!m) return void 0;
+		const v = parseFloat(m[1].replace(/[¥$,\s]/g, ""));
+		return Number.isFinite(v) ? v : void 0;
+	};
+	// Try patterns for off-peak (空闲/off-peak) first, then any.
+	const offPeakInputMiss = num(/缓存未命中[^\d]*([\d.]+)/) ?? num(/cache[\s-]*miss[^\d]*([\d.]+)/);
+	const offPeakInputHit = num(/缓存命中[^\d]*([\d.]+)/) ?? num(/cache[\s-]*hit[^\d]*([\d.]+)/);
+	const offPeakOutput = num(/输出[^\d]*([\d.]+)/) ?? num(/output[^\d]*([\d.]+)/);
+	if (offPeakInputMiss === void 0 || offPeakOutput === void 0) return null;
+	const peakInputMiss = (offPeakInputMiss ?? 0) * 2;
+	const peakInputHit = (offPeakInputHit ?? 0) * 2;
+	const peakOutput = (offPeakOutput ?? 0) * 2;
+	return {
+		peak: { inputMiss: peakInputMiss, inputHit: peakInputHit, output: peakOutput },
+		offPeak: { inputMiss: offPeakInputMiss, inputHit: offPeakInputHit ?? 0, output: offPeakOutput }
+	};
+}
+
+/** Kick off the first sync (fire-and-forget) and schedule the interval. */
+function startPricingSync() {
+	syncOfficialPricing().catch(() => {});
+	const timer = setInterval(() => {
+		syncOfficialPricing().catch(() => {});
+	}, PRICE_SYNC_INTERVAL_MS);
+	// Unref so the interval never keeps the process alive on its own.
+	if (typeof timer.unref === "function") timer.unref();
+	return timer;
+}
+
 /**
  * Resolve the DSH sessions root directory (defaults to ~/.dsh/sessions).
  * Avoids importing dsh-home-paths to keep zero external dependencies.
@@ -525,7 +630,7 @@ function makeRoutes(ctx, config) {
 					writeJson(res, 502, { error: outcome.error, modelId: config.modelId });
 					return;
 				}
-				writeJson(res, 200, { ...outcome.value, modelId: config.modelId });
+				writeJson(res, 200, { ...outcome.value, modelId: config.modelId, pricingSource, pricingSyncedAt });
 			}
 		},
 		{
@@ -539,18 +644,83 @@ function makeRoutes(ctx, config) {
 					return { value: todayCost(perSession) };
 				};
 				const outcome = await dedupe(key, () => cachedOrCompute(key, compute));
-				writeJson(res, 200, { ...outcome.value, modelId: config.modelId });
+				writeJson(res, 200, { ...outcome.value, modelId: config.modelId, pricingSource, pricingSyncedAt });
 			}
 		}
 	];
 }
 
+/**
+ * Build the `deepseek_billing` agent tool: lets the model query balance and
+ * session costs directly ("how much balance do I have?"). Hand-constructed
+ * tool object (no defineTool import) to keep zero external dependencies;
+ * mirrors the shape defineTool produces.
+ */
+function buildBillingTool(ctx, config) {
+	return {
+		name: "deepseek_billing",
+		description: "Query the DeepSeek account balance and estimated session costs. Use when the user asks about their balance, spending, or token costs. query = 'balance' (account balance), 'cost' (current session estimated cost), or 'both'.",
+		parameters: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					enum: ["balance", "cost", "both"],
+					description: "What to query: balance, cost, or both."
+				}
+			},
+			required: ["query"]
+		},
+		async execute(args) {
+			const query = args?.query ?? "both";
+			const parts = [];
+			if (query === "balance" || query === "both") {
+				const result = await fetchBalance(ctx, config);
+				if (result.ok) {
+					const info = (result.balance_infos ?? [])[0];
+					if (info !== void 0) {
+						parts.push(`Balance: ${info.currency} ${info.total_balance} (granted ${info.granted_balance}, topped up ${info.topped_up_balance})`);
+					} else {
+						parts.push("Balance: unavailable (no balance info returned)");
+					}
+				} else {
+					parts.push(`Balance query failed: ${result.error}`);
+				}
+			}
+			if (query === "cost" || query === "both") {
+				try {
+					const perSession = await collectAllSessionSamples();
+					const today = todayCost(perSession);
+					parts.push(`Today's estimated cost: CNY ${today.cost.toFixed(4)} (${today.inputTokens} input tokens, ${today.outputTokens} output tokens)`);
+				} catch (error) {
+					parts.push(`Cost query failed: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			}
+			return { result: parts.join("\n") };
+		}
+	};
+}
+
 /** Cordis plugin apply: register routes on the host webServer. */
 export function apply(ctx, config) {
 	const resolved = resolveConfig(config);
 	const routes = makeRoutes(ctx, resolved);
 	const disposers = routes.map((route) => ctx.webServer.register(route));
+	// Register the agent-facing billing tool when the tools service exists.
+	let toolDisposer;
+	try {
+		if (ctx.tools !== void 0 && typeof ctx.tools.register === "function") {
+			toolDisposer = ctx.tools.register(buildBillingTool(ctx, resolved));
+		}
+	} catch (error) {
+		ctx.logger?.warn?.("[dsh-balance-widget] tool registration failed: %s", error instanceof Error ? error.message : String(error));
+	}
+	// Kick off official price sync (fire-and-forget) and keep the interval
+	// handle for teardown.
+	const syncTimer = startPricingSync();
 	ctx.effect(() => () => {
+		clearInterval(syncTimer);
 		for (const dispose of disposers) dispose();
+		if (typeof toolDisposer === "function") toolDisposer();
 	}, "dsh-balance-widget: routes");
 }

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.3.2",
+  "version": "0.4.1",
   "type": "module",
   "main": "lib/index.js",
   "files": [