dsh-balance-widget 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-balance-widget contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,106 @@
+# dsh-balance-widget
+
+[中文](README.md) | **English**
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/LL-cmyk-so/dsh-balance-widget?style=flat-square&label=Stars" alt="Stars">
+  <img src="https://img.shields.io/github/license/LL-cmyk-so/dsh-balance-widget?style=flat-square" alt="License">
+  <img src="https://img.shields.io/github/last-commit/LL-cmyk-so/dsh-balance-widget?style=flat-square" alt="Last commit">
+  <img src="https://img.shields.io/badge/Node%2024-ready-brightgreen?style=flat-square" alt="Node 24">
+  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen?style=flat-square" alt="Zero deps">
+</p>
+
+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.
+
+## How it differs from similar plugins
+
+| Aspect | This plugin | Others (dsh-balance / dsh-token-price / ...) |
+| --- | --- | --- |
+| **Zero external dependencies** | ✅ Imports no `@deepseek-ai/*` packages, no native modules | ❌ Most depend on dsh SDK packages |
+| **Node 24 ready** | ✅ Works out of the box on any profile layout | ⚠️ Many community plugins still error on Node 24 |
+| **Boot stability** | ✅ Registers routes via official `ctx.webServer`; never conflicts with apiproxy | ⚠️ Some self-host HTTP servers that crash `dsh web` on boot |
+| **On-demand queries** | ✅ Fetches balance only on click; no polling, zero background requests | Some always-on badges refresh on a timer |
+| **Peak/off-peak pricing** | ✅ Built-in official 2026-08-17 rate table, auto-switches by window | Partial support |
+| **Security** | ✅ API key stays in the host process; loopback-only guard | Varies |
+
+**In one line**: *The zero-dependency, Node 24-ready balance/cost widget that never breaks `dsh web` boot.*
+
+## Features
+
+- **Account balance** — On click, the host proxies DeepSeek's official `GET /user/balance` and shows the `¥` balance. The API key is resolved through the host credentials service and never leaves the host process; the browser only talks to same-origin routes.
+- **Session cost (estimate)** — Computed from the session's `tokenUsage` projection × DeepSeek's official peak/off-peak price table. Follows the configured model (default `deepseek-v4-flash`, switchable to `deepseek-v4-pro`) and the Beijing-time peak/off-peak windows automatically.
+- **Token usage** — Also shows the session's input (incl. cache hits) / output tokens.
+- **On-demand refresh** — No polling, no background requests; the balance endpoint is only hit when you click the icon. Costs zero tokens to use.
+
+## Why this plugin
+
+- **Zero external dependencies** — the host half imports no `@deepseek-ai/*` packages and no native modules, so it loads from any profile layout and works on **Node 24** (many community cordis plugins still lag on Node 24).
+- **Uses official APIs only** — routes are registered through `ctx.webServer` (the same seam `dsh-ssh` uses) with loopback-only guards; no conflicting custom HTTP servers.
+
+## Architecture
+
+```
+host half (lib/index.js)
+  ctx.webServer.register:
+    GET /api/dsh-balance/balance → official /user/balance (loopback-only guard)
+    GET /api/dsh-balance/cost    → reserved route (cost priced client-side)
+
+client half (lib/client.js)
+  ctx.slots.inject("conversation.session.header.utilities")
+    → 💰 icon (session header, top-right corner)
+    → click fetches same-origin /api/dsh-balance/balance → popover with balance + cost + tokens
+```
+
+## Installation
+
+From npm (once published):
+
+```sh
+dsh plugin --profile web add dsh-balance-widget
+```
+
+From GitHub (development):
+
+```sh
+git clone https://github.com/LL-cmyk-so/dsh-balance-widget.git
+cd dsh-balance-widget
+dsh plugin --profile web add "link:$(pwd)"
+```
+
+Then restart `dsh web`.
+
+## Configuration
+
+In `~/.dsh/profiles/web/cordis.patch.yml`:
+
+```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
+    modelId: deepseek-v4-flash                  # pricing model (or deepseek-v4-pro)
+```
+
+## 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:
+
+| Model | Window | Cache hit (input) | Cache miss (input) | Output |
+| --- | --- | --- | --- | --- |
+| V4-Flash | Off-peak | 0.05 | 1.5 | 4.5 |
+| V4-Flash | Peak | 0.10 | 3.0 | 9.0 |
+| V4-Pro | Off-peak | 0.15 | 4.5 | 13.5 |
+| V4-Pro | Peak | 0.30 | 9.0 | 27.0 |
+
+`deepseek-chat` / `deepseek-reasoner` aliases map to Flash / Pro pricing respectively. Costs are **estimates**; actual billing from the provider is authoritative.
+
+## Verify
+
+- Config tree: `dsh --profile web --dump-config` should show a `balance-widget` entry.
+- Balance route: after restarting dsh web, `curl -s http://127.0.0.1:3080/api/dsh-balance/balance` should return `{ ok, balance_infos, modelId }`.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,102 @@
+# dsh-balance-widget
+
+**中文** | [English](README.en.md)
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/LL-cmyk-so/dsh-balance-widget?style=flat-square&label=Stars" alt="Stars">
+  <img src="https://img.shields.io/github/license/LL-cmyk-so/dsh-balance-widget?style=flat-square" alt="License">
+  <img src="https://img.shields.io/github/last-commit/LL-cmyk-so/dsh-balance-widget?style=flat-square" alt="Last commit">
+  <img src="https://img.shields.io/badge/Node%2024-ready-brightgreen?style=flat-square" alt="Node 24">
+  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen?style=flat-square" alt="Zero deps">
+</p>
+
+DeepSeek Harness (DSH) Web GUI 的余额与成本小部件：在会话头部右上角（角落）渲染一个 💰 图标，点击弹出账户余额与本会话的估算成本。
+
+## 与同类插件的区别
+
+| 特点 | 本插件 | 同类插件（dsh-balance / dsh-token-price 等） |
+| --- | --- | --- |
+| **零外部依赖** | ✅ 不 import 任何 `@deepseek-ai/*` 包，无原生模块 | ❌ 多数依赖 dsh SDK 包 |
+| **Node 24 兼容** | ✅ 天然兼容（零依赖设计），任何 profile 布局可加载 | ⚠️ 不少社区插件在 Node 24 下报错 |
+| **启动稳定性** | ✅ 用官方 `ctx.webServer` 注册路由，不与 apiproxy 冲突 | ⚠️ 有的自建 HTTP 服务导致 dsh web 启动崩溃 |
+| **按需查询** | ✅ 点击才查余额，无轮询、零后台请求 | 有的常驻徽章定时刷新 |
+| **峰谷定价** | ✅ 内置官方 2026-08-17 峰谷价表，自动按时段切换 | 部分支持 |
+| **安全性** | ✅ API key 仅在宿主进程，loopback-only 守卫 | 参差不齐 |
+
+**一句话**：*零依赖、Node 24 就绪、永不拖垮 dsh web 启动的余额/成本小部件。*
+
+## 功能
+
+- **账户余额** — 点击图标时经宿主代理查询 DeepSeek 官方 `GET /user/balance`，展示 `¥` 余额；API key 只在宿主进程内读取（凭据服务），浏览器不接触密钥。
+- **本会话成本（估算）** — 由会话的 `tokenUsage` 投影 × DeepSeek 官方峰谷定价表计算，随当前会话模型（默认 `deepseek-v4-flash`，可在配置中改为 `deepseek-v4-pro`）与北京时间高峰/空闲时段自动切换。
+- **Token 用量** — 同时展示本会话输入（含缓存命中）/ 输出 token 数。
+- **按需刷新** — 无轮询、无后台请求；只有点击图标时才发起余额查询，不消耗任何 token。
+
+## 架构
+
+```
+host 半区 (lib/index.js)
+  ctx.webServer.register:
+    GET /api/dsh-balance/balance → 官方 /user/balance（loopback-only 守卫）
+    GET /api/dsh-balance/cost    → 保留路由（成本目前客户端计价）
+  依赖：零外部 @deepseek-ai/* import，任何 profile 布局均可解析
+
+client 半区 (lib/client.js)
+  ctx.slots.inject("conversation.session.header.utilities")
+    → 💰 图标（会话头部右上角）
+    → 点击 fetch 同源 /api/dsh-balance/balance → 弹层展示余额 + 成本 + token
+```
+
+## 安装
+
+npm 安装（发布后）：
+
+```sh
+dsh plugin --profile web add dsh-balance-widget
+```
+
+GitHub 仓库安装（开发调试）：
+
+```sh
+git clone https://github.com/LL-cmyk-so/dsh-balance-widget.git
+cd dsh-balance-widget
+dsh plugin --profile web add "link:$(pwd)"
+```
+
+装完重启 `dsh web` 生效。
+
+## 配置
+
+在 `~/.dsh/profiles/web/cordis.patch.yml` 中：
+
+```yaml
+- id: balance-widget
+  name: dsh-balance-widget
+  config:
+    balanceBaseURL: https://api.deepseek.com   # 官方余额接口
+    balanceApiKeyEnv: DEEPSEEK_API_KEY          # 凭据服务中的密钥 ref
+    requestTimeoutMs: 5000                      # 余额查询超时
+    modelId: deepseek-v4-flash                  # 成本计价模型（可改 deepseek-v4-pro）
+```
+
+## 定价说明
+
+内置 DeepSeek 官方 2026-08-17 峰谷定价（元 / 百万 tokens），高峰时段为北京时间 09:00–12:00、14:00–18:00，价格为空闲时段两倍：
+
+| 模型 | 时段 | 缓存命中(输入) | 缓存未命中(输入) | 输出 |
+| --- | --- | --- | --- | --- |
+| V4-Flash | 空闲 | 0.05 | 1.5 | 4.5 |
+| V4-Flash | 高峰 | 0.10 | 3.0 | 9.0 |
+| V4-Pro | 空闲 | 0.15 | 4.5 | 13.5 |
+| V4-Pro | 高峰 | 0.30 | 9.0 | 27.0 |
+
+`deepseek-chat` / `deepseek-reasoner` 别名分别映射到 Flash / Pro 价格。成本为**估算值**，实际以官方账单为准。
+
+## 验证
+
+- 配置树：`dsh --profile web --dump-config` 应出现 `balance-widget` 条目
+- 余额路由：重启 dsh web 后 `curl -s http://127.0.0.1:3080/api/dsh-balance/balance` 应返回 `{ ok, balance_infos, modelId }`
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-balance-widget bundle patch: inserts the dual-face plugin row into the
+# web profile roster. The row is a bare plugin by package name: the node half
+# (exports ".") runs in the host process and registers the balance/cost API
+# routes; the `dsh.client` declaration in package.json makes the browser half
+# (exports "./client", served at /plugins/<id>/client.js) load in the web GUI.
+- insert:
+    - id: balance-widget
+      name: 'dsh-balance-widget'

package/lib/client.js

@@ -0,0 +1,294 @@
+window.__ModuleLoader__.load({
+	id: "dsh-balance-widget",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+		//#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 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");
+			tag.dataset.plugin = "dsh-balance-widget";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+		var styles = {
+			"wrap": "dshbw_wrap",
+			"btn": "dshbw_btn",
+			"pop": "dshbw_pop",
+			"row": "dshbw_row",
+			"val": "dshbw_val",
+			"err": "dshbw_err",
+			"hint": "dshbw_hint",
+			"foot": "dshbw_foot"
+		};
+		//#endregion
+		//#region lib/types/client/pricing.js
+		/**
+		* DeepSeek official pricing, in CNY per 1M tokens, effective 2026-08-17
+		* (peak/off-peak two-tier billing). Peak windows are Beijing time:
+		* 09:00-12:00 and 14:00-18:00; off-peak is half the peak price.
+		* Prices are hard-coded from the official announcement and are estimates
+		* for display — actual billing is authoritative from the provider.
+		*/
+		const 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 }
+			}
+		};
+		/** Fall back to Flash pricing for unknown model ids. */
+		function pricingFor(modelId) {
+			return PRICING[modelId] ?? PRICING["deepseek-v4-flash"];
+		}
+		/**
+		* Whether `date` falls inside a Beijing-time peak window.
+		* The host's local timezone is used; the widget is for a CN deployment.
+		*/
+		function isPeak(date) {
+			const hour = date.getHours();
+			return (hour >= 9 && hour < 12) || (hour >= 14 && hour < 18);
+		}
+		/**
+		* Price one session's token usage into a CNY estimate.
+		* @param usage - tokenUsage projection value.
+		* @param modelId - provider model id used for pricing.
+		* @returns { input, output, total } in CNY, or null when usage is absent.
+		*/
+		function priceSession(usage, modelId) {
+			if (usage === void 0 || usage === null) return null;
+			const input = usage.uncachedInputTokens ?? 0;
+			const hit = usage.cacheReadTokens ?? 0;
+			const write = usage.cacheWriteTokens ?? 0;
+			const output = usage.outputTokens ?? 0;
+			if (input + hit + write + output <= 0) return null;
+			const table = isPeak(new Date()) ? pricingFor(modelId).peak : pricingFor(modelId).offPeak;
+			const inputCost = (input * table.inputMiss + (hit + write) * table.inputHit) / 1e6;
+			const outputCost = (output * table.output) / 1e6;
+			return {
+				input: inputCost,
+				output: outputCost,
+				total: inputCost + outputCost
+			};
+		}
+		/** Format a CNY amount: ¥ + 3 significant decimals (drop trailing zeros). */
+		function formatCny(value) {
+			if (value === void 0 || value === null || !Number.isFinite(value)) return "—";
+			const rounded = Math.round(value * 1e4) / 1e4;
+			return `¥${rounded.toLocaleString("zh-CN", { minimumFractionDigits: 0, maximumFractionDigits: 4 })}`;
+		}
+		/** Format token counts compactly: 1234 -> 1.2K. */
+		function formatTokens(value) {
+			if (value === void 0 || value === null) return "—";
+			if (value >= 1e6) return `${(value / 1e6).toFixed(1)}M`;
+			if (value >= 1e3) return `${(value / 1e3).toFixed(1)}K`;
+			return String(value);
+		}
+		//#endregion
+		//#region lib/types/client/balance-api.js
+		/** Same-origin balance route (host half registers it over ctx.webServer). */
+		const BALANCE_ROUTE = "/api/dsh-balance/balance";
+		/**
+		* Fetch the account balance from the host proxy.
+		* @returns { ok, balanceInfos?, error? }
+		*/
+		async function fetchBalance() {
+			try {
+				const response = await fetch(BALANCE_ROUTE, { headers: { accept: "application/json" } });
+				if (!response.ok) {
+					let detail = "";
+					try {
+						detail = (await response.json()).error ?? "";
+					} catch (_error) {
+						/* ignore body parse failure */
+					}
+					return { ok: false, error: detail || `balance endpoint responded ${response.status}` };
+				}
+				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 };
+			} catch (error) {
+				return { ok: false, error: error instanceof Error ? error.message : String(error) };
+			}
+		}
+		/** Pick the display balance from balance_infos (prefer CNY, else first). */
+		function displayBalance(balanceInfos) {
+			if (!Array.isArray(balanceInfos) || balanceInfos.length === 0) return null;
+			const cny = balanceInfos.find((entry) => (entry.currency ?? "").toUpperCase() === "CNY");
+			const entry = cny ?? balanceInfos[0];
+			const total = Number(entry.total_balance);
+			if (!Number.isFinite(total)) return null;
+			const symbol = (entry.currency ?? "").toUpperCase() === "CNY" ? "¥" : (entry.currency ?? "") + " ";
+			return { symbol, total, currency: entry.currency };
+		}
+		//#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 }) {
+			const [open, setOpen] = (0, react.useState)(false);
+			const [balance, setBalance] = (0, react.useState)(null);
+			const [modelId, setModelId] = (0, react.useState)("deepseek-v4-flash");
+			const [error, setError] = (0, react.useState)(null);
+			const [loading, setLoading] = (0, react.useState)(false);
+			const usage = useProjection("tokenUsage");
+			const priced = priceSession(usage, modelId);
+			const toggle = async () => {
+				const next = !open;
+				setOpen(next);
+				if (next) {
+					setLoading(true);
+					setError(null);
+					const result = await fetchBalance();
+					if (result.ok) {
+						setBalance(displayBalance(result.balanceInfos));
+						if (typeof result.modelId === "string" && result.modelId !== "") setModelId(result.modelId);
+					} else {
+						setBalance(null);
+						setError(result.error);
+					}
+					setLoading(false);
+				}
+			};
+			return (0, react_jsx_runtime.jsx)("div", {
+				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,
+						"aria-label": t("aria"),
+						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.row,
+								children: (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
+									children: [(0, react_jsx_runtime.jsx)("span", {
+										children: t("balance")
+									}), (0, react_jsx_runtime.jsx)("span", {
+										className: styles.val,
+										children: loading ? "…" : 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", {
+										children: t("sessionCost")
+									}), (0, react_jsx_runtime.jsx)("span", {
+										className: styles.val,
+										children: priced !== null ? formatCny(priced.total) : "—"
+									})]
+								})
+							}), priced !== null && (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("tokens")
+									}), (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`
+									})]
+								})
+							}), error !== null && (0, react_jsx_runtime.jsx)("div", {
+								className: styles.err,
+								role: "status",
+								children: error
+							}), (0, react_jsx_runtime.jsx)("div", {
+								className: styles.hint,
+								children: 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")
+								})
+							})]
+						})
+					})]
+				})
+			});
+		}
+		//#endregion
+		//#region lib/types/client/locales.js
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "balance-widget";
+		/** Simplified Chinese dictionary (the key-set source of truth). */
+		const zh = {
+			"aria": "查看账户余额与本轮成本",
+			"title": "余额与成本",
+			"balance": "账户余额",
+			"sessionCost": "本会话成本（估算）",
+			"tokens": "Token 用量",
+			"hint": "价格按 DeepSeek 官方峰谷定价估算，实际以账单为准。",
+			"close": "关闭"
+		};
+		/** English dictionary, checked complete against the zh key set. */
+		const en = {
+			"aria": "View account balance and session cost",
+			"title": "Balance & cost",
+			"balance": "Account balance",
+			"sessionCost": "This session cost (est.)",
+			"tokens": "Token usage",
+			"hint": "Prices estimated from DeepSeek official peak/off-peak rates; billing is authoritative.",
+			"close": "Close"
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required services: the seat's slot registry and locale registry. */
+		const inject = [
+			"slots",
+			"locale"
+		];
+		/**
+		* Client plugin body: register the corner balance widget in the
+		* conversation session header utilities slot.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => ctx.locale.register(NS, {
+				zh,
+				en
+			}), "dsh-balance-widget: dictionaries");
+			ctx.slots.inject("conversation.session.header.utilities", () => ctx.slots.register({
+				name: "conversation.session.header.utilities",
+				id: "balance-widget",
+				order: 90,
+				locale: NS,
+				inject: (sessionId) => ({ sessionId })
+			}, BalanceWidget));
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,246 @@
+/**
+ * dsh-balance-widget — host half.
+ *
+ * Registers two loopback-only API routes over ctx.webServer:
+ *   GET /api/dsh-balance/balance  → DeepSeek account balance (official /user/balance)
+ *   GET /api/dsh-balance/cost     → cost endpoint (reserved; pricing is client-side)
+ *
+ * The API key is resolved through the host's credentials service (the same
+ * seam dsh-llm uses) and never leaves the host process: the browser only
+ * talks to these same-origin routes. Routes are guarded loopback-only,
+ * mirroring dsh-ssh's pattern. This module deliberately imports NO
+ * @deepseek-ai/* packages so it resolves from any profile layout (npm,
+ * workspace link, or flat fallback).
+ */
+
+/** Stable cordis plugin name (also the client bundle mount id). */
+export const name = "balance-widget";
+
+/** Services required before the balance surface can mount. */
+export const inject = ["webServer"];
+
+/** Route paths shared with the browser half (spelled here, not imported). */
+export const API = {
+	balance: "/api/dsh-balance/balance",
+	cost: "/api/dsh-balance/cost"
+};
+
+/** Default DeepSeek API base (mirrors dsh-llm-deepseek's PUBLIC_BASE_URL). */
+const DEFAULT_BASE_URL = "https://api.deepseek.com";
+/** Default credential ref, mirrors dsh-llm-deepseek's DEFAULT_API_KEY_ENV. */
+const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
+/** Default model used to price client-side session cost. */
+const DEFAULT_MODEL_ID = "deepseek-v4-flash";
+
+/**
+ * Config schema exposed to the cordis loader. Cordis calls
+ * `Config["~standard"].validate(config)` and expects a Standard Schema
+ * (version 1) result — the same interface @deepseek-ai/schemastery produces.
+ * We hand-build it here so the host half keeps ZERO external imports (the
+ * workspace-link layout cannot resolve @deepseek-ai/* from the plugin's own
+ * path, and importing nothing sidesteps that entirely).
+ */
+const CONFIG_FIELDS = {
+	balanceBaseURL: "string",
+	balanceApiKeyEnv: "string",
+	requestTimeoutMs: "number",
+	modelId: "string"
+};
+const CONFIG_DEFAULTS = {
+	balanceBaseURL: DEFAULT_BASE_URL,
+	balanceApiKeyEnv: DEFAULT_API_KEY_ENV,
+	requestTimeoutMs: 5000,
+	modelId: DEFAULT_MODEL_ID
+};
+
+export const Config = {
+	"~standard": {
+		version: 1,
+		vendor: "dsh-balance-widget",
+		validate(value) {
+			if (value === void 0 || value === null) value = {};
+			if (typeof value !== "object") {
+				return { issues: [{ message: "config must be an object", path: [] }] };
+			}
+			const out = {};
+			for (const [key, type] of Object.entries(CONFIG_FIELDS)) {
+				const raw = value[key];
+				const fallback = CONFIG_DEFAULTS[key];
+				if (raw === void 0 || raw === null) {
+					out[key] = fallback;
+					continue;
+				}
+				if (type === "string" && typeof raw === "string" && raw !== "") {
+					out[key] = raw;
+				} else if (type === "number" && typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+					out[key] = raw;
+				} else {
+					out[key] = fallback;
+				}
+			}
+			return { value: out };
+		}
+	},
+	shape: CONFIG_FIELDS,
+	defaults: CONFIG_DEFAULTS
+};
+
+/** Resolve config with defaults applied. */
+function resolveConfig(raw) {
+	const value = raw ?? {};
+	return {
+		balanceBaseURL: typeof value.balanceBaseURL === "string" && value.balanceBaseURL !== ""
+			? value.balanceBaseURL
+			: Config.defaults.balanceBaseURL,
+		balanceApiKeyEnv: typeof value.balanceApiKeyEnv === "string" && value.balanceApiKeyEnv !== ""
+			? value.balanceApiKeyEnv
+			: Config.defaults.balanceApiKeyEnv,
+		requestTimeoutMs: typeof value.requestTimeoutMs === "number" && value.requestTimeoutMs > 0
+			? value.requestTimeoutMs
+			: Config.defaults.requestTimeoutMs,
+		modelId: typeof value.modelId === "string" && value.modelId !== ""
+			? value.modelId
+			: Config.defaults.modelId
+	};
+}
+
+/** Write a JSON response with a status code. */
+function writeJson(res, status, body) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": Buffer.byteLength(payload)
+	});
+	res.end(payload);
+}
+
+/** Whether the request comes from the loopback interface. */
+function isLoopbackRequest(req) {
+	const address = req.socket?.remoteAddress ?? "";
+	return address === "::1"
+		|| address === "::ffff:127.0.0.1"
+		|| address === "127.0.0.1"
+		|| address === "localhost"
+		|| address.startsWith("::ffff:127.");
+}
+
+/** Guard helper: loopback fence + method check. */
+function guard(req, res, method) {
+	if (!isLoopbackRequest(req)) {
+		writeJson(res, 403, { error: "forbidden: loopback-only" });
+		return false;
+	}
+	if ((req.method ?? "GET") !== method) {
+		writeJson(res, 405, { error: `method not allowed: ${req.method}` });
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Resolve the DeepSeek API key through the host credentials service.
+ * Falls back to the launch environment, then process env. Returns undefined
+ * when absent everywhere.
+ */
+async function resolveApiKey(ctx, config) {
+	try {
+		const credentials = ctx.get("credentials");
+		if (credentials !== void 0) {
+			const hit = await credentials.resolve(config.balanceApiKeyEnv);
+			if (hit !== void 0 && hit.value !== void 0 && hit.value !== "") return hit.value;
+		}
+	} catch (error) {
+		ctx.logger?.warn?.("[dsh-balance-widget] credentials resolve failed: %s", error instanceof Error ? error.message : String(error));
+	}
+	try {
+		const environment = ctx.get("launchEnvironment");
+		if (environment !== void 0) {
+			const entry = environment.get(config.balanceApiKeyEnv);
+			if (entry !== void 0 && entry.value.length > 0) return entry.value;
+		}
+	} catch {
+		/* fall through to process env */
+	}
+	const ambient = process.env[config.balanceApiKeyEnv];
+	if (ambient !== void 0 && ambient !== "") return ambient;
+	return void 0;
+}
+
+/**
+ * Query the official DeepSeek /user/balance endpoint.
+ * @returns { ok: true, ...payload } | { ok: false, error }
+ */
+async function fetchBalance(ctx, config) {
+	let apiKey;
+	try {
+		apiKey = await resolveApiKey(ctx, config);
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	}
+	if (apiKey === void 0) {
+		return {
+			ok: false,
+			error: `no API key for ${config.balanceApiKeyEnv}; store it through the credentials service or export it in the launching environment`
+		};
+	}
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), config.requestTimeoutMs);
+	try {
+		const response = await fetch(`${config.balanceBaseURL}/user/balance`, {
+			headers: { authorization: `Bearer ${apiKey}` },
+			signal: controller.signal
+		});
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			return { ok: false, error: `balance endpoint responded ${response.status}: ${text.slice(0, 200)}` };
+		}
+		const payload = await response.json();
+		return { ok: true, ...payload };
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** Build the route table for the balance widget. */
+function makeRoutes(ctx, config) {
+	return [
+		{
+			kind: "exact",
+			path: API.balance,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				const result = await fetchBalance(ctx, config);
+				if (result.ok) {
+					writeJson(res, 200, { ...result, modelId: config.modelId });
+				} else {
+					writeJson(res, 502, { error: result.error, modelId: config.modelId });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: API.cost,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				// Cost is priced client-side from the tokenUsage projection; this
+				// route exists as the canonical ask point for future server pricing.
+				writeJson(res, 200, { ok: true, note: "cost is priced client-side from tokenUsage projection" });
+			}
+		}
+	];
+}
+
+/** 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));
+	ctx.effect(() => () => {
+		for (const dispose of disposers) dispose();
+	}, "dsh-balance-widget: routes");
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "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.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "keywords": [
+    "deepseek",
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "balance",
+    "cost",
+    "token",
+    "web-ui"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LL-cmyk-so/dsh-balance-widget.git"
+  },
+  "author": "YOUR_NAME <YOUR_EMAIL>"
+}