@dougen/dsh-deepseek-usage 0.3.1 → 0.4.0

package/README.md

@@ -1,21 +1,24 @@
 # @dougen/dsh-deepseek-usage
 
-DeepSeek 用量侧边栏插件（DeepSeek Harness Web UI）
+DeepSeek 余额侧边栏插件（DeepSeek Harness Web UI）
 
-## 简介
-
-在 DSH **网页界面**的侧边栏底部常驻显示你的 **DeepSeek 账号余额**（放大显示）与**当前模型档单价**卡片，并提供高峰/空闲计费时段指示灯。
+在 DSH **网页界面**的侧边栏底部常驻显示你的 **DeepSeek 账号余额**（放大显示）与**当前模型档单价**，并提供高峰/空闲计费时段指示灯。界面语言跟随 DSH 语言设置（自动检测浏览器语言，中文界面显示中文，其他语言显示英文）。
 
 ![DeepSeek 用量卡片](https://cdn.jsdelivr.net/npm/@dougen/dsh-deepseek-usage/screenshot.png)
 
 ## 功能
 
 - **余额**：`¥ 110.00` 大字显示（符号随账号币种自动切换：人民币 `¥` / 美元 `$`）
-- **档单价**：`→|1.5 ⚡0.05 |→4.5`（输入 / 输入缓存 / 输出，位于卡片右下角；随当前启用模型与峰谷时段自动切换）
+- **档单价**：`→|1.5 ⚡0.05 |→4.5`（输入 / 输入缓存 / 输出，位于卡片右下角；随当前启用模型与峰谷时段自动切换，**切换模型时立即同步**）
 - **峰谷指示灯**：卡片右上角，高峰（9:00–12:00、14:00–18:00 北京时间）橙色，空闲绿色
 - **自动刷新**：每 5 分钟一次；点击卡片任意位置立即刷新
+- **多语言**：界面文案跟随 DSH 语言（中文 / English）
 - 跟随应用明暗主题
 
+## 支持范围
+
+> ⚠️ 本插件**仅支持 DeepSeek 官方平台**的余额显示：余额来自 DeepSeek 官方 API `GET https://api.deepseek.com/user/balance`（使用 DSH 中已配置的 `DEEPSEEK_API_KEY`）。通过 `DEEPSEEK_BASE_URL` 指向第三方中转/代理时，余额接口可能不可用或返回异常，**不保证兼容**，请使用 DeepSeek 官方平台账号。
+
 ## 安装
 
 需要 DSH CLI，从 npm 安装：
@@ -50,6 +53,61 @@ dsh plugin --profile web add @dougen/dsh-deepseek-usage
 dsh plugin --profile web remove @dougen/dsh-deepseek-usage
 ```
 
+---
+
+# English
+
+A sidebar plugin for **DeepSeek Harness Web UI** that shows your **DeepSeek account balance** (large display) and the **current model's unit pricing**, with a peak/off-peak billing indicator. UI language follows the DSH locale (Chinese UI shows Chinese, other languages show English).
+
+![DeepSeek usage card](https://cdn.jsdelivr.net/npm/@dougen/dsh-deepseek-usage/screenshot.png)
+
+## Features
+
+- **Balance**: `¥ 110.00` large display (symbol follows account currency: `¥` CNY / `$` USD)
+- **Unit pricing**: `→|1.5 ⚡0.05 |→4.5` (input / input cache / output, bottom-right of the card; switches with the active model and peak/off-peak window — **updates instantly when you switch models**)
+- **Peak indicator**: top-right dot, orange during peak hours (9:00–12:00, 14:00–18:00 Beijing Time), green otherwise
+- **Auto refresh**: every 5 minutes; click the card to refresh instantly
+- **i18n**: UI copy follows the DSH locale (Chinese / English)
+- Follows the app light/dark theme
+
+## Supported scope
+
+> ⚠️ This plugin **only supports DeepSeek's official platform** balance display: balance comes from the official API `GET https://api.deepseek.com/user/balance` (using the `DEEPSEEK_API_KEY` configured in DSH). Pointing `DEEPSEEK_BASE_URL` at a third-party proxy/gateway may break or return unexpected results for the balance endpoint — **not guaranteed to be compatible**. Use an official DeepSeek platform account.
+
+## Install
+
+Requires the DSH CLI. Install from npm:
+
+```sh
+dsh plugin --profile web add @dougen/dsh-deepseek-usage
+```
+
+Restart the web app (`dsh web`), open http://127.0.0.1:3080 , and the usage card appears at the bottom of the sidebar (below the Cordis panel button).
+
+## Data sources
+
+| Data | Source |
+|---|---|
+| Balance | Official DeepSeek API `GET /user/balance` (uses `DEEPSEEK_API_KEY` configured in DSH) |
+| Unit pricing / peak window | Built-in price table (DeepSeek official peak/off-peak pricing snapshot, effective 2026-08-17) |
+
+Make sure `DEEPSEEK_API_KEY` is configured in DSH (Model settings page) before use.
+
+## FAQ
+
+**Balance shows "—"?**
+- `DEEPSEEK_API_KEY` is not configured — configure it in DSH settings and restart.
+- Network or API error — the error message is shown below the card.
+
+**Price differs from the official one?**
+- The unit price switches with the **active model** and the **peak/off-peak window**; if the active model is not in the built-in price table, `deepseek-chat` pricing is shown with a notice.
+
+## Uninstall
+
+```sh
+dsh plugin --profile web remove @dougen/dsh-deepseek-usage
+```
+
 ## License
 
 MIT

package/lib/client.js

@@ -20,6 +20,23 @@ window.__ModuleLoader__.load({
 		const POLL_MS = 5 * 60 * 1000;
 		const USAGE_PATH = "/api/deepseek-usage";
 
+		// ---- i18n（DSH locale 服务；zh 为兜底）----
+		const NS = "dsh-deepseek-usage";
+		const ZH = {
+			"price.input": "输入",
+			"price.cache": "输入缓存",
+			"price.output": "输出",
+			"peak.peak": "高峰时段",
+			"peak.off": "空闲时段",
+		};
+		const EN = {
+			"price.input": "Input",
+			"price.cache": "Input cache",
+			"price.output": "Output",
+			"peak.peak": "Peak hours",
+			"peak.off": "Off-peak hours",
+		};
+
 		// ---- helpers ---------------------------------------------------
 		function money(value) {
 			const n = Number(value);
@@ -71,14 +88,34 @@ window.__ModuleLoader__.load({
 
 		// ---- the widget -------------------------------------------------
 		function UsageCell(props) {
+			const ctx = props.ctx;
 			const wide = !!props.wide;
 			const [data, setData] = useState(null);
 			const [error, setError] = useState("");
 			const mounted = useRef(true);
+			const locale = ctx && ctx.locale;
+
+			// 订阅语言变化（DSH locale 服务；不可用时回退中文）。
+			const lcSnap = react.useSyncExternalStore(
+				(cb) => (locale && typeof locale.subscribe === "function" ? locale.subscribe(cb) : () => {}),
+				() => (locale && typeof locale.getSnapshot === "function" ? locale.getSnapshot() : { active: "zh", locales: [], revision: 0 }),
+			);
+			const lang = lcSnap && lcSnap.active === "en" ? "en" : "zh";
+			// locale.bind(ns) 返回绑定命名空间的翻译函数；不可用时回退中文词典。
+			const boundT = locale && typeof locale.bind === "function" ? locale.bind(NS) : null;
+			const t = (key) => {
+				try {
+					if (boundT) {
+						const v = boundT(key);
+						if (typeof v === "string" && v !== key) return v;
+					}
+				} catch (e) { /* 词典不可用，回退中文 */ }
+				return ZH[key] || key;
+			};
 
 			const load = useCallback(async () => {
 				try {
-					const res = await fetch(USAGE_PATH, { cache: "no-store" });
+					const res = await fetch(USAGE_PATH + "?lang=" + lang, { cache: "no-store" });
 					let body = null;
 					try {
 						body = await res.json();
@@ -93,17 +130,31 @@ window.__ModuleLoader__.load({
 					if (!mounted.current) return;
 					setError(e instanceof Error ? e.message : String(e));
 				}
-			}, []);
+			}, [lang]);
 
 			useEffect(() => {
 				mounted.current = true;
 				load();
 				const timer = setInterval(load, POLL_MS);
+				// 模型切换（写入 settings 触发 document-updated）时立即刷新，价格同步。
+				let off = null;
+				try {
+					if (ctx && ctx.remote && typeof ctx.remote.$on === "function") {
+						off = ctx.remote.$on("settings/document-updated", () => {
+							try { load(); } catch (e) { /* 忽略刷新错误 */ }
+						});
+					}
+				} catch (e) {
+					off = null;
+				}
 				return () => {
 					mounted.current = false;
 					clearInterval(timer);
+					try {
+						if (typeof off === "function") off();
+					} catch (e) { /* 忽略退订错误 */ }
 				};
-			}, [load]);
+			}, [load, ctx]);
 
 			const balance = data && data.balance ? data.balance : null;
 			const tier = data && data.tier ? data.tier : null;
@@ -117,7 +168,9 @@ window.__ModuleLoader__.load({
 				background: data && data.peak ? C.peak : C.idle,
 				boxShadow: "0 0 4px rgba(0,0,0,.3)",
 			};
-			const title = "DeepSeek 用量 · 点击刷新" + (errs.length ? " · " + errs.join("; ") : "");
+			const peakTitle = data && data.peak
+				? t("peak.peak") + (data.peakHours ? " " + data.peakHours : "")
+				: t("peak.off");
 
 			if (!wide) {
 				return h("div", {
@@ -136,13 +189,12 @@ window.__ModuleLoader__.load({
 						gap: 5,
 						userSelect: "none",
 					},
-					title,
 					onClick: load,
 				},
 					h("span", { style: { display: "inline-flex", alignItems: "baseline", gap: 3 } },
 						h("span", { style: { fontWeight: 700, fontSize: 13, color: C.label } }, symbol),
 						h("span", { style: { fontWeight: 700, fontSize: 13, color: C.label } }, money(balance && balance.total))),
-					h("span", { style: dot, title: data && data.peak ? "高峰时段" : "空闲时段" }));
+					h("span", { style: dot, title: peakTitle }));
 			}
 
 			const Price = (icon, label, value) =>
@@ -170,7 +222,6 @@ window.__ModuleLoader__.load({
 					fontSize: "12px",
 					lineHeight: "15px",
 				},
-				title,
 				onClick: load,
 			},
 				// 第一行：余额（24px，符号与数字 3px 间距）
@@ -179,24 +230,30 @@ window.__ModuleLoader__.load({
 					h("span", { style: { fontWeight: 700, fontSize: 24, color: C.label, lineHeight: "28px" } }, money(balance && balance.total))),
 				h("span", {
 					style: { position: "absolute", top: 8, right: 9, ...dot },
-					title: data && data.peak ? "高峰时段 " + (data.peakHours || "") : "空闲时段",
+					title: peakTitle,
 				}),
 				// 当前档单价：卡片右下角
 				h("span", {
 					style: { position: "absolute", right: 9, bottom: 4, display: "inline-flex", alignItems: "center", gap: 5 },
 				},
-					Price(h(IconIn, null), "输入", tier && tier.input),
-					Price(h(IconCache, null), "输入缓存", tier && tier.cacheRead),
-					Price(h(IconOut, null), "输出", tier && tier.output)),
+					Price(h(IconIn, null), t("price.input"), tier && tier.input),
+					Price(h(IconCache, null), t("price.cache"), tier && tier.cacheRead),
+					Price(h(IconOut, null), t("price.output"), tier && tier.output)),
 				errs.length
 					? h("div", { style: { color: C.err, fontSize: 10, whiteSpace: "pre-wrap" } }, errs.join(" | "))
 					: null);
 		}
 
 		// ---- client plugin body -----------------------------------------
-		const inject = ["slots"];
+		const inject = ["slots", "remote", "locale"];
 
 		function apply(ctx) {
+			// 注册 i18n 词典（DSH locale 服务；不可用时组件回退中文）。
+			try {
+				if (ctx.locale && typeof ctx.locale.register === "function") {
+					ctx.locale.register(NS, { zh: ZH, en: EN });
+				}
+			} catch (e) { /* 词典注册失败不影响卡片 */ }
 			// 注入本包样式：footerActions 换行（卡片独占一行）。
 			const tagId = "dsh-deepseek-usage";
 			if (typeof document !== "undefined" && document.querySelector(`style[data-plugin-css="${tagId}"]`) === null) {
@@ -208,7 +265,7 @@ window.__ModuleLoader__.load({
 			}
 			ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register(
 				{ name: "sidebar.footer.action", id: "dsh-usage", order: 100, label: "DeepSeek 用量" },
-				(props) => h(UsageCell, { wide: props.wide }),
+				(props) => h(UsageCell, { wide: props.wide, ctx }),
 			));
 		}
 

package/lib/index.js

@@ -3,7 +3,7 @@
  *
  * 注册一个 HTTP 路由：
  *
- *   GET /api/deepseek-usage
+ *   GET /api/deepseek-usage[?lang=zh|en]
  *
  * 返回（JSON）：
  *   {
@@ -14,9 +14,13 @@
  *     updatedAt, errors
  *   }
  *
+ * `lang` 参数（zh 默认）控制错误消息与峰谷文案的语言；UI 其余文案由
+ * client 端（DSH locale 服务）本地化。
+ *
  * 数据源：余额来自 DeepSeek 官方 GET /user/balance（API Key 经凭证服务解析，
  * 与 llm-deepseek 同一引用，不出本机）。单价与峰谷时段来自内置价格表
- * （lib/pricing.js，DeepSeek 官方峰谷定价快照）。
+ * （lib/pricing.js，DeepSeek 官方峰谷定价快照）。本插件仅支持 DeepSeek
+ * 官方平台余额显示。
  *
  * 安全：路由仅接受本机 Host（127.0.0.1 / localhost / ::1），拦截 DNS
  * rebinding 与 0.0.0.0 绑定下的局域网访问。
@@ -25,6 +29,7 @@ import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import {
   DEFAULT_MODEL,
   PEAK_HOURS_TEXT,
+  PEAK_HOURS_TEXT_EN,
   isPeak,
   unitAt,
 } from "./pricing.js";
@@ -45,6 +50,22 @@ const JSON_HEADERS = {
   "cache-control": "no-store",
 };
 
+/** 错误消息字典（zh/en）。 */
+const MESSAGES = {
+  zh: {
+    noKey: "未配置 DEEPSEEK_API_KEY",
+    balanceHttp: (status) => `余额接口 HTTP ${status}`,
+    balanceFail: (detail) => `余额获取失败: ${detail}`,
+    modelUnknown: (model) => `当前模型 ${model} 不在价格表，档单价按 deepseek-chat 展示`,
+  },
+  en: {
+    noKey: "DEEPSEEK_API_KEY is not configured",
+    balanceHttp: (status) => `Balance API HTTP ${status}`,
+    balanceFail: (detail) => `Failed to fetch balance: ${detail}`,
+    modelUnknown: (model) => `Model ${model} is not in the price table, showing deepseek-chat pricing`,
+  },
+};
+
 function sendJson(res, status, body) {
   res.writeHead(status, JSON_HEADERS);
   res.end(JSON.stringify(body));
@@ -81,6 +102,17 @@ function isLocalHost(req) {
   return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
 
+/** 解析 ?lang= 参数（zh 默认；仅识别 en 为英文，其余中文）。 */
+function resolveLang(req) {
+  const url = req.url ?? "";
+  const q = url.indexOf("?");
+  if (q === -1) return "zh";
+  for (const kv of url.slice(q + 1).split("&")) {
+    if (kv === "lang=en") return "en";
+  }
+  return "zh";
+}
+
 function apply(ctx) {
   ctx.effect(
     () => ctx.webServer.register({
@@ -93,6 +125,19 @@ function apply(ctx) {
             return sendJson(res, 403, { ok: false, error: "forbidden", message: "仅允许本机访问" });
           }
 
+          const lang = resolveLang(req);
+          const msg = MESSAGES[lang] || MESSAGES.zh;
+
+          // ---- 当前模型当前档单价（展示用）----
+          const now = Date.now();
+          let model = DEFAULT_MODEL;
+          try {
+            const adm = ctx.get("agentDefaultModel");
+            const selection = adm && typeof adm.currentSelection === "function" ? adm.currentSelection() : void 0;
+            if (selection && typeof selection.model === "string") model = selection.model;
+          } catch {}
+          const unit = unitAt(model, now);
+
           const errors = [];
 
           // ---- 余额（官方接口，API Key）----
@@ -100,7 +145,7 @@ function apply(ctx) {
           try {
             const hit = await ctx.credentials.resolve(API_KEY_REF);
             if (hit === void 0) {
-              errors.push("未配置 DEEPSEEK_API_KEY");
+              errors.push(msg.noKey);
             } else {
               const response = await fetch(balanceUrl(), {
                 headers: { Authorization: `Bearer ${hit.value}`, Accept: "application/json" },
@@ -108,7 +153,7 @@ function apply(ctx) {
               });
               const text = await response.text();
               if (!response.ok) {
-                errors.push(`余额接口 HTTP ${response.status}`);
+                errors.push(msg.balanceHttp(response.status));
               } else {
                 const body = JSON.parse(text);
                 const infos = body && Array.isArray(body.balance_infos) ? body.balance_infos : [];
@@ -121,25 +166,17 @@ function apply(ctx) {
               }
             }
           } catch (error) {
-            errors.push(`余额获取失败: ${error instanceof Error ? error.message : String(error)}`);
+            errors.push(msg.balanceFail(error instanceof Error ? error.message : String(error)));
           }
 
-          // ---- 当前模型当前档单价 + 峰谷（展示用）----
-          const now = Date.now();
-          let model = DEFAULT_MODEL;
-          try {
-            const adm = ctx.get("agentDefaultModel");
-            const selection = adm && typeof adm.currentSelection === "function" ? adm.currentSelection() : void 0;
-            if (selection && typeof selection.model === "string") model = selection.model;
-          } catch {}
-          const unit = unitAt(model, now);
-          if (!unit.known) errors.push(`当前模型 ${model} 不在价格表，档单价按 deepseek-chat 展示`);
+          // ---- 档单价提示（未知模型回退 chat 档）----
+          if (!unit.known) errors.push(msg.modelUnknown(model));
 
           sendJson(res, 200, {
             ok: true,
             balance,
             peak: isPeak(now),
-            peakHours: PEAK_HOURS_TEXT,
+            peakHours: lang === "en" ? PEAK_HOURS_TEXT_EN : PEAK_HOURS_TEXT,
             tier: {
               input: unit.input,
               cacheRead: unit.cacheRead,

package/lib/pricing.js

@@ -29,8 +29,10 @@ export const DEFAULT_MODEL = 'deepseek-v4-flash';
 
 /** 高峰时段窗口（北京时间，含起点不含终点）。 */
 export const PEAK_WINDOWS = [[9, 12], [14, 18]];
-/** 高峰时段展示文案。 */
+/** 高峰时段展示文案（中文）。 */
 export const PEAK_HOURS_TEXT = '9:00–12:00、14:00–18:00（北京时间）';
+/** 高峰时段展示文案（英文）。 */
+export const PEAK_HOURS_TEXT_EN = '9:00–12:00, 14:00–18:00 (Beijing Time)';
 
 /** 某时刻的北京时间小时（0–23）。 */
 export function shanghaiHour(ms) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dougen/dsh-deepseek-usage",
-  "version": "0.3.1",
-  "description": "DeepSeek 用量侧边栏插件：余额（官方 API）、当前档单价与峰谷时段指示灯。",
+  "version": "0.4.0",
+  "description": "DeepSeek 余额侧边栏插件：余额（官方 API）、当前档单价与峰谷时段指示灯，支持中/英文界面。",
   "type": "module",
   "main": "lib/index.js",
   "files": [