@nomxy/dsh-balance 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 siyin (dsh-balance)
+
+The host half of this package — `lib/index.js` and `lib/pricing.js` — is derived
+from `@dougen/dsh-deepseek-usage` (https://github.com/dougen/dsh-deepseek-usage),
+which is distributed under the MIT License:
+
+Copyright (c) 2026 dougen
+
+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.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# dsh-balance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DeepSeek Harness 侧边栏余额胶囊：把 **DeepSeek 官方账户余额** 和 **峰谷时段** 做成一个 20px 高的小胶囊，贴在侧栏页脚「名字那一行」的右侧，不占一整块地方。
+
+`¥56.10 · 谷 1d9h`
+
+- **余额**：来自 DeepSeek 官方 `GET /user/balance`，用 DSH 凭证服务里的 `DEEPSEEK_API_KEY`（不出本机）。
+- **峰谷**：官方高峰/空闲时段实时判断，橙色「峰」/ 绿色「谷」，后面跟距下次切换的倒计时（`2d15h` / `5h47m` / `23m`），每 15 秒刷新。
+- **当前档位单价**：鼠标悬停显示输入 / 输入缓存 / 输出单价（元 / 百万 tokens），以及余额是否可用。
+- **交互**：点击立即刷新；后台每 30 秒心跳一次；侧栏折叠成 36px 图标栏时自动隐藏，展开即回来。
+- **失败可见**：未配置 Key、余额接口超时或返回异常时胶囊显示 `—`，悬停能看到原因，不会编数字。
+
+## 安装
+
+```sh
+dsh plugin --profile <你的 profile> add @nomxy/dsh-balance
+```
+
+装完刷新页面或重启 `dsh web` 即生效。要求 DSH `>= 0.2.1`（`dsh.client` + `dsh.bundle` 清单）。
+
+## 配置
+
+无需配置。余额需要 DSH 里已经配好 DeepSeek 的 API Key：
+
+- 凭证引用：`DEEPSEEK_API_KEY`（与 `llm-deepseek` 同一引用）；
+- 想换网关地址时可用环境变量 `DEEPSEEK_BASE_URL`（注意：指向第三方网关时 API Key 会发给该地址）。
+
+## 隐私与安全
+
+- 插件只做两件事：读凭证、请求官方余额接口。不收集、不上报，没有遥测。
+- 宿主半只注册两条本机路由（`/api/dsh-balance`、`/api/dsh-balance/holidays`），且只接受 `Host` 为回环地址或本监听地址的请求（与 DSH 自身 `/api` 栅栏同一口径）；跨站标记与异源 `Origin` 一律拒绝。
+- 上游错误原文不会透出到界面（上游异常消息里可能带凭据片段）。
+
+## 已知限制
+
+- 只支持 DeepSeek 官方平台余额；第三方路由上的同名模型不适用官方峰谷定价，此时只显示余额。
+- 峰谷与节假日规则是内置表（`lib/pricing.js`），官方调整规则或放假日历时需要更新版本。
+- 胶囊是通过 DOM 挂载进侧栏名字行的（DSH 没有「名字后面」这个槽位），因此侧栏结构大改时需要跟着调整选择器 `div[class*="triggerRow"]`。
+
+## 来源与致谢
+
+宿主半（`lib/index.js`、`lib/pricing.js`：余额读取、峰谷与节假日规则、单价表）取自
+[@dougen/dsh-deepseek-usage](https://github.com/dougen/dsh-deepseek-usage)（MIT），仅把插件 id 与路由改名，并去掉了对 `@deepseek-ai/dsh-credentials` 的运行时依赖（`credentialRef` 是编译期 brand，运行时为恒等函数）。
+客户端半（`lib/client.js`）为本项目重写：不注册槽位，直接挂载紧凑胶囊。
+
+## License
+
+MIT，见 [LICENSE](./LICENSE)（包含上游 MIT 声明）。
+
+---
+
+## English
+
+A 20px balance chip for the DeepSeek Harness sidebar footer, sitting right of the name row: official DeepSeek balance plus the current peak/off-peak window with a countdown to the next switch, hover for the active model's unit prices, click to refresh. No telemetry; the host half only serves two loopback-only routes. Install with `dsh plugin --profile <profile> add @nomxy/dsh-balance`. Host half derived from `@dougen/dsh-deepseek-usage` (MIT).

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-balance — 本地插件：侧栏名字行里的 DeepSeek 余额胶囊。
+# Host 半注册 GET /api/dsh-balance（含 /holidays）；Client 半不占槽位，直接把胶囊挂进 triggerRow。
+- insert:
+    - id: balance-chip
+      name: '@nomxy/dsh-balance'

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96" role="img" aria-label="dsh-balance">
+  <rect x="4" y="26" width="88" height="44" rx="22" fill="#111827"/>
+  <text x="34" y="48" text-anchor="middle" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif" font-size="26" font-weight="700" fill="#f9fafb">¥</text>
+  <circle cx="66" cy="48" r="7" fill="#22c55e"/>
+</svg>

package/lib/client.js

@@ -0,0 +1,238 @@
+// dsh-balance — browser half.
+//
+// 不注册任何 sidebar 槽位：在侧边栏页脚"名字那一行"（triggerRow）里挂一个
+// 紧凑胶囊（¥余额 + 峰/谷时段 + 距下次切换倒计时），位于名字与右侧指示灯之间。
+// 每 30 秒以及点击时拉宿主路由 /api/dsh-balance（见 lib/index.js）。
+window.__ModuleLoader__.load({
+	id: "@nomxy/dsh-balance",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+		const USAGE_PATH = "/api/dsh-balance";
+		const POLL_MS = 30 * 1000;
+		const TICK_MS = 15 * 1000;
+		const CHIP_CLASS = "dsh-balance";
+
+		const CSS = `
+.${CHIP_CLASS}{display:inline-flex;align-items:center;gap:5px;height:20px;padding:0 7px;flex:none;
+box-sizing:border-box;border-radius:999px;border:1px solid var(--dsw-color-border,rgba(127,127,127,.3));
+background:transparent;cursor:pointer;white-space:nowrap;font-variant-numeric:tabular-nums;
+font:500 11.5px/18px var(--dsw-font-family,system-ui,-apple-system,"Segoe UI",sans-serif);
+color:var(--dsw-color-text-secondary,#6b7280);transition:background .15s ease,color .15s ease}
+.${CHIP_CLASS}:hover{background:var(--dsw-color-fill-hover,rgba(127,127,127,.14));color:var(--dsw-color-text,inherit)}
+.${CHIP_CLASS}[data-error="1"]{color:var(--dsw-color-danger,#dc2626);border-color:currentColor}
+.${CHIP_CLASS}__sep{opacity:.4;margin:0 1px}
+.${CHIP_CLASS}__phase{font-weight:600;letter-spacing:.2px}
+.${CHIP_CLASS}__phase[data-phase="peak"]{color:#d97706}
+.${CHIP_CLASS}__phase[data-phase="idle"]{color:#15803d}
+.${CHIP_CLASS}__phase[data-phase="none"]{display:none}
+.${CHIP_CLASS}__cd{opacity:.75;font-weight:500}
+div[class*="triggerRow"][class*="railRow"] .${CHIP_CLASS}{display:none}
+`;
+
+		let styleEl = null;
+		let chip = null;
+		let amountEl = null;
+		let phaseEl = null;
+		let countdownEl = null;
+		let sepEl = null;
+		let timer = null;
+		let ticker = null;
+		let observer = null;
+		let unmounted = false;
+		let fetchedAt = 0;
+		let state = { total: null, currency: "CNY", peak: null, tier: null, next: null, error: null };
+
+		function symbolOf(currency) {
+			if (currency === "CNY" || currency === "RMB") return "¥";
+			if (currency === "USD") return "$";
+			return "";
+		}
+
+		function amountText() {
+			if (state.error !== null) return "—";
+			if (state.total === null) return "…";
+			return symbolOf(state.currency) + state.total.toFixed(2);
+		}
+
+		function priceLine(tier) {
+			if (!tier || tier.known === false) return "";
+			const parts = [];
+			if (typeof tier.input === "number") parts.push("输入 " + tier.input);
+			if (typeof tier.cacheRead === "number") parts.push("缓存 " + tier.cacheRead);
+			if (typeof tier.output === "number") parts.push("输出 " + tier.output);
+			return parts.length === 0 ? "" : "元/百万 tokens：" + parts.join(" · ");
+		}
+
+		/** 距下次峰谷切换的剩余时间：`2d15h` / `5h47m` / `23m`。 */
+		function countdownText(ms) {
+			if (!(ms > 0)) return "";
+			const totalMinutes = Math.floor(ms / 60000);
+			const days = Math.floor(totalMinutes / 1440);
+			const hours = Math.floor((totalMinutes % 1440) / 60);
+			const minutes = totalMinutes % 60;
+			if (days > 0) return days + "d" + hours + "h";
+			if (hours > 0) return hours + "h" + (minutes > 0 ? minutes + "m" : "");
+			return minutes + "m";
+		}
+
+		/** 剩余的切换毫秒数：宿主给的是"发起请求那一刻"的毫秒，按本地流逝扣掉。 */
+		function remainingMs() {
+			if (state.next === null || typeof state.next.ms !== "number") return NaN;
+			const elapsed = fetchedAt === 0 ? 0 : Date.now() - fetchedAt;
+			return state.next.ms - elapsed;
+		}
+
+		function render() {
+			if (chip === null) return;
+			amountEl.textContent = amountText();
+			chip.dataset.error = state.error === null ? "0" : "1";
+			if (state.peak === null) {
+				phaseEl.dataset.phase = "none";
+				phaseEl.textContent = "";
+				sepEl.style.display = "none";
+				countdownEl.textContent = "";
+			} else {
+				phaseEl.dataset.phase = state.peak ? "peak" : "idle";
+				phaseEl.textContent = state.peak ? "峰" : "谷";
+				sepEl.style.display = "";
+				const remaining = remainingMs();
+				const text = countdownText(remaining);
+				countdownEl.textContent = text === "" ? "" : text;
+			}
+			const lines = [];
+			lines.push(state.error === null ? "DeepSeek 余额，点击刷新" : "余额读取失败：" + state.error);
+			if (state.peak !== null) {
+				const remaining = remainingMs();
+				const text = countdownText(remaining);
+				lines.push((state.peak ? "高峰时段" : "空闲时段") + (text === "" ? "" : "，距切换 " + text));
+			}
+			const prices = priceLine(state.tier);
+			if (prices !== "") lines.push(prices);
+			chip.title = lines.filter((line) => line !== "").join("\n");
+		}
+
+		async function load() {
+			try {
+				const response = await fetch(USAGE_PATH, { cache: "no-store", credentials: "same-origin" });
+				const body = await response.json().catch(() => null);
+				if (!response.ok || body === null || body.ok !== true) {
+					const message = body && Array.isArray(body.errors) && body.errors.length > 0 ? body.errors[0] : "HTTP " + response.status;
+					state = Object.assign({}, state, { error: String(message) });
+				} else {
+					const balance = body.balance || {};
+					const total = typeof balance.total === "number" && Number.isFinite(balance.total) ? balance.total : null;
+					fetchedAt = Date.now();
+					state = {
+						total,
+						currency: typeof balance.currency === "string" ? balance.currency : "CNY",
+						peak: typeof body.peak === "boolean" ? body.peak : null,
+						tier: body.tier || null,
+						next: body.next || null,
+						error: Array.isArray(body.errors) && body.errors.length > 0 ? String(body.errors[0]) : null,
+					};
+				}
+			} catch (error) {
+				state = Object.assign({}, state, { error: "余额接口无法连接" });
+			}
+			render();
+		}
+
+		function buildChip() {
+			const node = document.createElement("button");
+			node.type = "button";
+			node.className = CHIP_CLASS;
+			node.dataset.error = "0";
+			const amount = document.createElement("span");
+			amount.textContent = "…";
+			const sep = document.createElement("span");
+			sep.className = CHIP_CLASS + "__sep";
+			sep.textContent = "·";
+			const phase = document.createElement("span");
+			phase.className = CHIP_CLASS + "__phase";
+			phase.dataset.phase = "none";
+			const countdown = document.createElement("span");
+			countdown.className = CHIP_CLASS + "__cd";
+			node.appendChild(amount);
+			node.appendChild(sep);
+			node.appendChild(phase);
+			node.appendChild(countdown);
+			node.addEventListener("click", (event) => {
+				event.preventDefault();
+				event.stopPropagation();
+				load();
+			});
+			amountEl = amount;
+			sepEl = sep;
+			phaseEl = phase;
+			countdownEl = countdown;
+			return node;
+		}
+
+		/** 挂到"名字那一行"：紧跟名字按钮、位于连接/更新指示灯之前。 */
+		function ensureMounted() {
+			if (unmounted || chip === null) return;
+			const row = document.querySelector('div[class*="triggerRow"]');
+			if (row === null) return;
+			if (row.contains(chip)) return;
+			const anchor = row.children.length > 1 ? row.children[1] : null;
+			row.insertBefore(chip, anchor);
+			render();
+		}
+
+		function start() {
+			if (styleEl === null) {
+				styleEl = document.createElement("style");
+				styleEl.dataset.plugin = "dsh-balance";
+				styleEl.textContent = CSS;
+				document.head.appendChild(styleEl);
+			}
+			chip = buildChip();
+			ensureMounted();
+			load();
+			timer = setInterval(load, POLL_MS);
+			// 倒计时与峰谷文字每 15 秒重算一次，不必等下一次请求。
+			ticker = setInterval(render, TICK_MS);
+			let scheduled = false;
+			observer = new MutationObserver(() => {
+				if (scheduled) return;
+				scheduled = true;
+				setTimeout(() => {
+					scheduled = false;
+					ensureMounted();
+				}, 50);
+			});
+			observer.observe(document.documentElement, { childList: true, subtree: true });
+		}
+
+		function stop() {
+			unmounted = true;
+			if (observer !== null) observer.disconnect();
+			if (timer !== null) clearInterval(timer);
+			if (ticker !== null) clearInterval(ticker);
+			if (chip !== null) chip.remove();
+			if (styleEl !== null) styleEl.remove();
+			observer = null;
+			timer = null;
+			ticker = null;
+			chip = null;
+			styleEl = null;
+		}
+
+		const inject = [];
+
+		function apply(ctx) {
+			ctx.effect(() => {
+				start();
+				return () => stop();
+			}, "dsh-balance: sidebar chip");
+		}
+
+		exports.name = "@nomxy/dsh-balance";
+		exports.inject = inject;
+		exports.apply = apply;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,474 @@
+/**
+ * dsh-deepseek-usage — host half.
+ *
+ * 注册一个 HTTP 路由：
+ *
+ *   GET /api/deepseek-usage[?lang=zh|en]
+ *   GET /api/deepseek-usage/holidays
+ *
+ * 返回（JSON）：
+ *   {
+ *     ok: true,
+ *     balance: { isAvailable, total, currency },        // 官方余额接口（API Key）
+ *     tier: { input, cacheRead, cacheWrite, output, model, known },
+ *     next: { peak, at, ms },                           // 距下次峰谷切换（界面倒计时）
+ *     peak,                                             // 当前是否高峰
+ *     updatedAt, errors,
+ *     pricing: { via, requested, provider, used, known } // 【内部诊断】界面不消费
+ *   }
+ *
+ * 界面只使用 balance / tier / next / peak / errors：插件内部的取价路径属于诊断信息，
+ * 保留在响应里供排查与测试，但不出现在 UI 上。
+ * errors 只放"用户能理解且需要行动"的余额类失败，不含任何上游原文——上游错误消息
+ * 可能带着凭据片段（undici 会把非法的 Authorization 值写进异常消息），直接透出等于
+ * 把 Key 印在侧边栏上。
+ *
+ * `lang` 参数（zh 默认）只影响错误消息的语言；UI 其余文案由 client 端本地化。
+ *
+ * 单价数据源：lib/pricing.js 的内置 PRICE_TABLE（DeepSeek 官方峰谷定价快照）。
+ * 官方调价时随插件版本更新该表——不联网抓取、不读写本地价格配置文件。
+ * 只有官方路由（provider 见 pricing.js 的 OFFICIAL_PROVIDERS）上的官方模型才计价：
+ * 第三方路由上的 deepseek-* 同名模型按各自规则扣费，用官方表算出来的数字与账单无关。
+ *
+ * 数据源：余额来自 DeepSeek 官方 GET /user/balance（API Key 经凭证服务解析，
+ * 与 llm-deepseek 同一引用，不出本机）。本插件仅支持 DeepSeek 官方平台余额显示。
+ *
+ * 安全：路由只接受本机来源（见 isTrustedRequest）——与 DSH 自身的 /api 栅栏同一
+ * 口径：Host 必须是回环地址或本监听器绑定的地址，跨站请求标记与异源 Origin 一律拒绝。
+ * 另见 README 的"已知限制"：本机其它进程仍可直接访问该端口，这是本地工具的固有边界。
+ */
+// credentialRef() 只是编译期 string brand（运行时是恒等函数），这里用本地等价实现，
+// 不依赖 @deepseek-ai/dsh-credentials 的模块解析，插件完全自包含。
+const credentialRef = (value) => value;
+import {
+  DEFAULT_MODEL,
+  HOLIDAY_RANGES,
+  hasHolidayCoverage,
+  isPeak,
+  nextChange,
+  unitAt,
+} from "./pricing.js";
+
+const name = "@nomxy/dsh-balance";
+const inject = ["credentials", "webServer"];
+
+const PUBLIC_BASE_URL = "https://api.deepseek.com";
+/** 与 llm-deepseek 适配器对齐的环境变量覆盖。注意：指向第三方网关时 API Key 会发给该地址。 */
+const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
+const API_KEY_REF = credentialRef("DEEPSEEK_API_KEY");
+const BALANCE_PATH = "/user/balance";
+const ROUTE_PATH = "/api/dsh-balance";
+/** 放假日期路由（浏览器侧启动拉一次，保证两边同一份日期表）。 */
+const HOLIDAYS_PATH = "/api/dsh-balance/holidays";
+const TIMEOUT_MS = 15000;
+/** 余额响应体上限：网关返回异常大 body 时不让它占满内存。 */
+const MAX_BODY_BYTES = 64 * 1024;
+/**
+ * 余额快照缓存时长（毫秒）。客户端每 30s 心跳一次，多个标签页/多次点击会重复打
+ * 官方余额接口；缓存把这段时间内的重复请求合并成一次。
+ */
+const BALANCE_CACHE_MS = 10_000;
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+};
+
+/**
+ * 错误消息字典（zh/en）。只保留"余额为什么拿不到"这类用户能理解、且需要行动的
+ * 信息；不拼接任何上游原文或异常消息。
+ */
+const MESSAGES = {
+  zh: {
+    noKey: "未配置 DEEPSEEK_API_KEY",
+    badKey: "DEEPSEEK_API_KEY 含有非法字符",
+    balanceHttp: (status) => `余额接口 HTTP ${status}`,
+    balanceTimeout: "余额接口超时",
+    balanceNetwork: "余额接口无法连接",
+    balancePayload: "余额接口返回了无法解析的内容",
+    balanceEmpty: "余额接口没有返回余额",
+    balanceUnavailable: "账户当前不可用",
+    forbidden: "仅允许本机访问",
+    method: "仅支持 GET",
+    internal: "插件内部错误",
+  },
+  en: {
+    noKey: "DEEPSEEK_API_KEY is not configured",
+    badKey: "DEEPSEEK_API_KEY contains invalid characters",
+    balanceHttp: (status) => `Balance API HTTP ${status}`,
+    balanceTimeout: "Balance API timed out",
+    balanceNetwork: "Balance API is unreachable",
+    balancePayload: "Balance API returned an unreadable response",
+    balanceEmpty: "Balance API returned no balance",
+    balanceUnavailable: "The account is currently unavailable",
+    forbidden: "Local access only",
+    method: "GET only",
+    internal: "Internal plugin error",
+  },
+};
+
+/**
+ * 放假日期表未覆盖当前年份时告警一次（每天一次）。
+ *
+ * 在请求路径上检查，而不是只在启动时：进程跨年长跑时，下一年的节假日仍按工作日
+ * 计价，而这正是用户真正会看到错误价格的时段——只在启动时告警覆盖不到那一刻。
+ */
+let lastHolidayWarningDay = "";
+function warnHolidayCoverage(ctx) {
+  if (hasHolidayCoverage()) return;
+  const now = Date.now();
+  const day = new Date(now + 8 * 60 * 60 * 1000).toISOString().slice(0, 10);
+  if (day === lastHolidayWarningDay) return;
+  lastHolidayWarningDay = day;
+  const year = new Date(now + 8 * 60 * 60 * 1000).getUTCFullYear();
+  ctx.logger.warn(
+    `dsh-deepseek-usage: 内置放假日期表未覆盖 ${year} 年（仅收录到 ${HOLIDAY_RANGES.at(-1)?.[1] ?? "未知"}）`
+      + `，${year} 年法定节假日白天会被当作高峰时段：请按国务院办公厅通知更新 lib/pricing.js 的 HOLIDAY_RANGES`
+      + `（并同步 lib/client.js 的镜像表，并把 HOLIDAY_TABLE_THROUGH_YEAR 推到 ${year}）`,
+  );
+}
+
+function sendJson(res, status, body) {
+  // 已经发过响应头时再写一次会抛 ERR_HTTP_HEADERS_SENT，直接结束即可。
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  res.writeHead(status, JSON_HEADERS);
+  res.end(JSON.stringify(body));
+}
+
+function balanceUrl() {
+  const base = process.env[BASE_URL_ENV] ?? PUBLIC_BASE_URL;
+  return `${base.replace(/\/+$/, "")}${BALANCE_PATH}`;
+}
+
+/** 容忍字符串/数字，返回有限数或 NaN。 */
+function toFinite(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : NaN;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : NaN;
+  }
+  return NaN;
+}
+
+/**
+ * 请求头里的 Host 是否是"本机"。
+ *
+ * 接受：回环地址（127/8 任意地址、::1、localhost）、本监听器绑定的地址。
+ * 与 DSH 自己的 /api 栅栏同一口径（见 app.asar 的 isTrustedApiRequest）：只认回环
+ * 会让 `--host <局域网IP>` 与 `--trusted-host` 部署下插件永久 403。
+ */
+function isLocalHost(req, bindHost) {
+  const raw = req.headers.host;
+  if (typeof raw !== "string" || raw === "") return false;
+  const host = hostNameOf(raw);
+  if (host === null) return false;
+  if (host === "localhost" || host === "::1") return true;
+  if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) return true;
+  if (host === "::ffff:127.0.0.1") return true;
+  // 监听器绑定的地址（如 --host 10.0.0.7）同样是"自己"。
+  if (typeof bindHost === "string" && bindHost !== "") {
+    const bind = hostNameOf(bindHost);
+    if (bind !== null && bind !== "" && host === bind) return true;
+  }
+  return false;
+}
+
+/**
+ * 取 authority 里的主机名：小写、去掉端口与 IPv6 方括号。
+ * IPv6 不能按冒号切（`::1` 切出空串），所以先剥方括号再处理。
+ */
+function hostNameOf(authority) {
+  let host = authority.trim().toLowerCase();
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    if (end === -1) return null;
+    host = host.slice(1, end);
+    return host;
+  }
+  const idx = host.lastIndexOf(":");
+  if (idx !== -1 && host.indexOf(":") === idx) host = host.slice(0, idx);
+  return host === "" ? null : host;
+}
+
+/**
+ * 请求是否可以访问本插件的路由。
+ *
+ * 口径与 DSH 的 /api 栅栏一致：
+ *   1. Host 必须是本机（回环或监听器绑定地址）；
+ *   2. 浏览器标记为跨站的请求一律拒绝；
+ *   3. 带 Origin 时，Origin 必须与 Host 同一 authority。
+ * 这样任意网页都无法跨站读走余额，DNS rebinding（Host 变成攻击者域名）同样被挡下。
+ */
+function isTrustedRequest(req, bindHost) {
+  if (!isLocalHost(req, bindHost)) return false;
+  if (req.headers["sec-fetch-site"] === "cross-site") return false;
+  const origin = req.headers.origin;
+  if (typeof origin === "string" && origin !== "") {
+    let originHost;
+    try {
+      originHost = new URL(origin).host.toLowerCase();
+    } catch {
+      return false;
+    }
+    const host = String(req.headers.host ?? "").toLowerCase();
+    if (originHost !== host) return false;
+  }
+  return true;
+}
+
+/** 解析 ?lang= 参数。 */
+function resolveQuery(req) {
+  const url = req.url ?? "";
+  const q = url.indexOf("?");
+  const kv = q === -1 ? [] : url.slice(q + 1).split("&");
+  let lang = "zh";
+  for (const item of kv) {
+    if (item === "lang=en" || item === "lang=en-US" || item === "lang=en-GB") lang = "en";
+  }
+  return { lang };
+}
+
+/**
+ * API Key 是否能安全地放进 Authorization 头。
+ * 凭据存储允许任意文本（多行值也是合法输入），而非法字符会让 undici 把整个
+ * Authorization 值写进异常消息——那道消息会一路流到卡片上。
+ */
+function isUsableKey(value) {
+  if (typeof value !== "string") return false;
+  const key = value.trim();
+  if (key === "") return false;
+  // HTTP 头值只允许可见 ASCII（不含空格与控制字符）。
+  return /^[\x21-\x7e]+$/.test(key);
+}
+
+/** 余额响应体超限：与"无法解析"同一类问题。 */
+class BalancePayloadError extends Error {}
+
+/** 读取响应体，超过上限即视为失败。 */
+async function readBoundedText(response) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) throw new BalancePayloadError();
+  const text = await response.text();
+  // text.length 是 UTF-16 码元数；按字节算才不会让多字节内容绕过上限。
+  if (Buffer.byteLength(text, "utf8") > MAX_BODY_BYTES) throw new BalancePayloadError();
+  return text;
+}
+
+/**
+ * 取一次余额快照。
+ *
+ * @param key 已解析出的 API Key（调用方已做过形状校验）。
+ * @returns {{ ok: boolean, balance: object, code: string|null, status?: number }}
+ *   code 是失败分类（供 MESSAGES 选文案），成功时为 null。
+ */
+async function fetchBalance(ctx, lang, key) {
+  const balance = { isAvailable: null, total: null, currency: null };
+
+  let response;
+  let text;
+  try {
+    response = await fetch(balanceUrl(), {
+      headers: { Authorization: `Bearer ${key}`, Accept: "application/json" },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    text = await readBoundedText(response);
+  } catch (error) {
+    if (error instanceof BalancePayloadError) {
+      return { ok: false, balance, code: "balancePayload" };
+    }
+    const name = error instanceof Error ? error.name : "";
+    if (name === "TimeoutError" || name === "AbortError") {
+      return { ok: false, balance, code: "balanceTimeout" };
+    }
+    return { ok: false, balance, code: "balanceNetwork" };
+  }
+
+  if (!response.ok) return { ok: false, balance, code: "balanceHttp", status: response.status };
+
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return { ok: false, balance, code: "balancePayload" };
+  }
+
+  const infos = body && Array.isArray(body.balance_infos) ? body.balance_infos : [];
+  const first = infos[0] || {};
+  const total = toFinite(first.total_balance);
+  balance.isAvailable = body?.is_available !== false;
+  balance.currency = typeof first.currency === "string" ? first.currency : null;
+  // total 缺失或非法时保留 null，由调用方当成"没拿到余额"，不要写 NaN（JSON 会变成
+  // null，客户端 Number(null) 是 0，会把"读不到"显示成"余额 0 元"）。
+  balance.total = Number.isFinite(total) ? total : null;
+  if (balance.total === null) return { ok: false, balance, code: "balanceEmpty" };
+  if (balance.isAvailable === false) return { ok: false, balance, code: "balanceUnavailable" };
+  return { ok: true, balance, code: null };
+}
+
+/**
+ * 余额快照缓存：同一时间窗内多个请求（多标签页、点击、心跳）共用一次上游调用。
+ *
+ * 只缓存成功结果——失败必须立刻能被下一次请求重试。缓存与在途请求都按 Key 值
+ * 分桶：换了 Key 就不会命中旧 Key 的缓存，也不会复用旧 Key 的在途请求
+ * （否则会短暂显示上一个 Key 的余额）。
+ */
+const balanceCache = new Map();
+const balanceInFlight = new Map();
+
+/** 丢掉过期的缓存条目：换 Key 频繁时 Map 会一直长。 */
+function evictStaleCache(now) {
+  for (const [key, entry] of balanceCache) {
+    if (now - entry.at >= BALANCE_CACHE_MS) balanceCache.delete(key);
+  }
+}
+
+async function readBalanceCached(ctx, lang) {
+  const now = Date.now();
+  let key = "";
+  try {
+    const hit = await ctx.credentials.resolve(API_KEY_REF);
+    if (hit === void 0) return { ok: false, balance: { isAvailable: null, total: null, currency: null }, code: "noKey" };
+    key = typeof hit.value === "string" ? hit.value.trim() : "";
+  } catch {
+    return { ok: false, balance: { isAvailable: null, total: null, currency: null }, code: "balanceNetwork" };
+  }
+  if (!isUsableKey(key)) {
+    return { ok: false, balance: { isAvailable: null, total: null, currency: null }, code: "badKey" };
+  }
+  evictStaleCache(now);
+  const cached = balanceCache.get(key);
+  if (cached !== undefined && now - cached.at < BALANCE_CACHE_MS) return cached.value;
+  const pending = balanceInFlight.get(key);
+  if (pending !== undefined) return pending;
+  const request = fetchBalance(ctx, lang, key)
+    .then((value) => {
+      if (value.ok) balanceCache.set(key, { at: Date.now(), value });
+      return value;
+    })
+    .finally(() => {
+      balanceInFlight.delete(key);
+    });
+  balanceInFlight.set(key, request);
+  return request;
+}
+
+function apply(ctx) {
+  const bindHost = typeof ctx.webServer?.host === "string" ? ctx.webServer.host : "";
+
+  ctx.effect(
+    () => ctx.webServer.register({
+      kind: "exact",
+      path: HOLIDAYS_PATH,
+      handler: async (req, res) => {
+        if (req.method !== "GET" && req.method !== "HEAD") {
+          return sendJson(res, 405, { ok: false, error: "method", message: MESSAGES.zh.method });
+        }
+        if (!isTrustedRequest(req, bindHost)) {
+          return sendJson(res, 403, { ok: false, error: "forbidden", message: MESSAGES.zh.forbidden });
+        }
+        sendJson(res, 200, { ok: true, ranges: HOLIDAY_RANGES });
+      },
+    }),
+    "dsh-deepseek-usage: holidays route",
+  );
+
+  ctx.effect(
+    () => ctx.webServer.register({
+      kind: "exact",
+      path: ROUTE_PATH,
+      handler: async (req, res) => {
+        try {
+          if (req.method !== "GET" && req.method !== "HEAD") {
+            return sendJson(res, 405, { ok: false, error: "method", message: MESSAGES.zh.method });
+          }
+          // ---- 仅本机访问：拦截 DNS rebinding、跨站读取与局域网直连 ----
+          if (!isTrustedRequest(req, bindHost)) {
+            return sendJson(res, 403, { ok: false, error: "forbidden", message: MESSAGES.zh.forbidden });
+          }
+
+          const { lang } = resolveQuery(req);
+          const msg = MESSAGES[lang] || MESSAGES.zh;
+
+          // 放假日期表过期时告警（每天一次）。放在请求路径上，跨年长跑也能覆盖到。
+          try {
+            warnHolidayCoverage(ctx);
+          } catch { /* 告警失败不影响卡片 */ }
+
+          // ---- 当前模型当前档单价（展示用）----
+          let model = DEFAULT_MODEL;
+          let provider = "";
+          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;
+            if (selection && typeof selection.provider === "string") provider = selection.provider;
+          } catch {}
+          // 时刻在余额请求之后再取：请求耗时会跨过峰谷边界，先取会让 peak / 单价 /
+          // 倒计时三者互相矛盾（显示橙色高峰灯却给着空闲价）。
+          const now = Date.now();
+          const unit = unitAt(model, now, provider);
+
+          const errors = [];
+
+          // ---- 余额（官方接口，API Key）----
+          const snapshot = await readBalanceCached(ctx, lang);
+          const balance = snapshot.balance;
+          if (!snapshot.ok) {
+            const code = snapshot.code;
+            errors.push(
+              code === "balanceHttp"
+                ? msg.balanceHttp(snapshot.status)
+                : typeof msg[code] === "function"
+                  ? msg[code]()
+                  : msg[code] ?? msg.balanceNetwork,
+            );
+          }
+
+          // ---- 距下一次峰谷切换（界面用它在指示灯旁显示倒计时）----
+          const next = nextChange(now);
+
+          sendJson(res, 200, {
+            ok: true,
+            balance,
+            peak: isPeak(now),
+            //   peak = 切换后所处的时段，at = 切换时刻，ms = 剩余毫秒
+            next,
+            tier: {
+              input: unit.input,
+              cacheRead: unit.cacheRead,
+              cacheWrite: unit.cacheWrite,
+              output: unit.output,
+              model: unit.model,
+              known: unit.known,
+            },
+            // 【内部诊断】取价路径：界面不再展示（卡片去技术化），保留字段
+            // 供排查问题与回归测试使用。
+            pricing: {
+              via: unit.via,                        // exact | alias | fallback
+              requested: unit.requested,            // 当前启用的模型 id
+              provider: unit.provider,              // 当前路由的 provider id
+              used: unit.model,                     // 实际取价使用的模型 id
+              known: unit.known,                    // false = 不计价，界面隐藏单价
+            },
+            updatedAt: now,
+            errors,
+          });
+        } catch (error) {
+          ctx.logger.warn("dsh-deepseek-usage: request failed");
+          ctx.logger.warn(error);
+          sendJson(res, 502, {
+            ok: false,
+            error: "internal",
+            message: MESSAGES.zh.internal,
+          });
+        }
+      },
+    }),
+    "dsh-deepseek-usage: route",
+  );
+}
+
+export { name, inject, apply };

package/lib/pricing.js

@@ -0,0 +1,276 @@
+/**
+ * dsh-deepseek-usage — 定价表（元 / 百万 tokens）。
+ *
+ * 价格唯一来源：下方 PRICE_TABLE 内置表——DeepSeek 官方峰谷定价快照
+ * （2026-09-10 官方价格页）。官方调价时随插件版本更新本表。
+ *
+ * 模型改名（0.6.0 起）：官方会把模型改名并把旧名保留为别名（如
+ * deepseek-v4-flash / deepseek-v4-flash-vision-exp → deepseek-flash）。旧名若
+ * 落到内置表就会长期显示过期价且无从察觉，因此 MODEL_ALIASES 维护"旧名 → 现名"
+ * 的显式映射，unitAt() 的 via 字段标出来源，供排查，避免静默算错。
+ *
+ * 不做"同家族唯一匹配"（flash / pro / chat / reasoner）：家族词没有词边界，
+ * deepseek-v5-pro、deepseek-prompt-helper 都会命中 pro 并按上代价格计价；官方发布
+ * 下一代模型后，卡片会自信地显示旧价而不是隐藏。表里没有的模型一律 known=false。
+ *
+ * 只对 DeepSeek 官方路由 + 官方模型计价（isOfficialModel）：第三方供应商的模型、
+ * 路由器把供应商名当模型名上报的情况（codebuddy、workbuddy 的 deepseek-v4.1-flash）
+ * 一律 known=false，界面据此隐藏档单价与峰谷指示灯——官方价格表与峰谷时段对它们不成立。
+ *
+ * 峰谷（官方口径）：高峰时段为北京时间周一至周五（**不含中国法定节假日**）
+ * 9:00–12:00、14:00–18:00，其余（含整个周末、法定节假日全天、以及调休上班的
+ * 周末）为空闲时段；缓存写暂不计费（cacheWrite = 0）。
+ * 因此只有"落在工作日里的法定节假日"会改变判定结果——周末无论是否调休上班都
+ * 是空闲，见 HOLIDAY_RANGES。
+ *
+ * 本文件用于卡片"当前档单价"展示、峰谷指示灯，以及 nextChange() 给出的
+ * 「距下次峰谷切换倒计时」（卡片上显示为 `2d 15h` / `5h 47m` 这类英文单位时长）。
+ *
+ * 时区（0.1.7 起）：峰谷判定与"每日"边界均按北京时间（Asia/Shanghai，固定
+ * UTC+8，无夏令时）计算，不随服务器本地时区变化——在任何时区部署的 DSH 上
+ * 显示一致。
+ */
+
+/** 北京时间固定偏移（上海无夏令时）。 */
+export const SHANGHAI_OFFSET_MS = 8 * 60 * 60 * 1000;
+
+/**
+ * 价格表：input（缓存未命中）/ cacheRead（缓存命中）/ output 均为 [高峰, 空闲]
+ * 二元组；cacheWrite 为常量 0。官方改价时更新本表并发布新版本。
+ */
+const PRICE_TABLE = {
+  'deepseek-flash': { input: [2, 1], cacheRead: [0.04, 0.02], cacheWrite: 0, output: [8, 4] },
+  'deepseek-v4-pro': { input: [9, 4.5], cacheRead: [0.3, 0.15], cacheWrite: 0, output: [27, 13.5] },
+  'deepseek-chat': { input: [2, 2], cacheRead: [0.5, 0.5], cacheWrite: 0, output: [8, 8] },
+  'deepseek-reasoner': { input: [4, 4], cacheRead: [1, 1], cacheWrite: 0, output: [16, 16] },
+};
+
+/**
+ * 旧模型名 → 现模型名（官方改名后旧名仍可调用，且按现模型价格计费）。
+ * 见官方价格页脚注：deepseek-v4-flash / deepseek-v4-flash-vision-exp 由
+ * DeepSeek-V4.1-Flash 提供服务，按 Flash 价格计费。
+ */
+const MODEL_ALIASES = {
+  'deepseek-v4-flash': 'deepseek-flash',
+  'deepseek-v4-flash-vision-exp': 'deepseek-flash',
+};
+
+/** 默认模型（当 agentDefaultModel 不可用时的展示默认）。 */
+export const DEFAULT_MODEL = 'deepseek-flash';
+
+/**
+ * DeepSeek 官方模型路由的 provider id。官方有两条：API Key 路由
+ * （`@deepseek-ai/dsh-llm-deepseek-api-key`）与账号路由
+ * （`@deepseek-ai/dsh-llm-deepseek-account`）。
+ *
+ * 只按模型名前缀判官方是不够的：Qwen token-plan、NVIDIA、opencode、workbuddy 这些
+ * 第三方路由上都有 `deepseek-*` 同名模型，它们按各自的计价规则扣费。provider 缺失
+ * （旧宿主、路由未上报）时按"非官方"处理——宁可隐藏价格，也不显示一个与实际账单
+ * 无关的数字。
+ */
+export const OFFICIAL_PROVIDERS = ['deepseek-official', 'deepseek-account'];
+
+/** 高峰时段窗口（北京时间，含起点不含终点）。 */
+export const PEAK_WINDOWS = [[9, 12], [14, 18]];
+/** 官方口径：高峰仅限周一至周五（北京时间），周末整天为空闲时段。 */
+export const PEAK_WEEKDAYS_ONLY = true;
+
+/**
+ * 中国法定节假日放假日期（含起止，闭区间；北京时间的日历日）。
+ * 来源：国务院办公厅《关于 2026 年部分节假日安排的通知》（国办发明电〔2025〕7号）。
+ * 官方口径：法定节假日全天、调休上班的周末均为空闲时段——周末本来就空闲，所以
+ * 只需列"放假日期"，落在工作日里的那几天才会把判定从高峰翻成空闲。
+ * 下一年的安排通常在前一年 11 月发布，届时更新本表与 HOLIDAY_TABLE_THROUGH_YEAR；
+ * 当前年份未被覆盖时由 lib/index.js 告警（见 hasHolidayCoverage）。
+ */
+export const HOLIDAY_RANGES = [
+  ['2026-01-01', '2026-01-03'], // 元旦
+  ['2026-02-15', '2026-02-23'], // 春节
+  ['2026-04-04', '2026-04-06'], // 清明节
+  ['2026-05-01', '2026-05-05'], // 劳动节
+  ['2026-06-19', '2026-06-21'], // 端午节
+  ['2026-09-25', '2026-09-27'], // 中秋节
+  ['2026-10-01', '2026-10-07'], // 国庆节
+];
+
+/**
+ * 把 [起, 止] 闭区间展开成日期键集合（`yyyy-mm-dd`，O(1) 查表）。
+ *
+ * 非法日期（如 2027-02-30）会被 Date.parse 滚到 03-02，把一个不存在的日子变成
+ * 真的假日。这里先校验解析结果与输入一致，不一致就跳过该段。
+ */
+export function expandHolidayRanges(ranges) {
+  const set = new Set();
+  const DAY = 24 * 60 * 60 * 1000;
+  for (const [from, to] of ranges) {
+    if (typeof from !== 'string' || typeof to !== 'string') continue;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(from) || !/^\d{4}-\d{2}-\d{2}$/.test(to)) continue;
+    const start = Date.parse(`${from}T00:00:00Z`);
+    const end = Date.parse(`${to}T00:00:00Z`);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) continue;
+    // 解析结果必须与输入同一天，否则说明输入本身不是合法日期（已滚动到别的日子）。
+    if (new Date(start).toISOString().slice(0, 10) !== from) continue;
+    if (new Date(end).toISOString().slice(0, 10) !== to) continue;
+    for (let t = start; t <= end; t += DAY) set.add(new Date(t).toISOString().slice(0, 10));
+  }
+  return set;
+}
+
+const HOLIDAY_DAYS = expandHolidayRanges(HOLIDAY_RANGES);
+
+/** 某时刻的北京时间日期键（`yyyy-mm-dd`）。 */
+function beijingDateKey(ms) {
+  return new Date(ms + SHANGHAI_OFFSET_MS).toISOString().slice(0, 10);
+}
+
+/**
+ * 放假日期表覆盖到的年份（含）。
+ *
+ * 国务院办公厅通常在前一年 11 月发布次年安排，届时更新 HOLIDAY_RANGES 并把这个
+ * 常量 +1。不能用"表里有没有这一年的某一天"来判定覆盖：只补一条元旦记录就会让
+ * 判定通过，而春节、国庆仍然按工作日计价。
+ */
+export const HOLIDAY_TABLE_THROUGH_YEAR = 2026;
+
+/** 该时刻所在的北京时间年份是否已被放假日期表覆盖。 */
+export function hasHolidayCoverage(ms = Date.now()) {
+  const year = new Date(ms + SHANGHAI_OFFSET_MS).getUTCFullYear();
+  return year <= HOLIDAY_TABLE_THROUGH_YEAR;
+}
+
+/** 某时刻是否为高峰时段（按北京时间；法定节假日全天与周末恒为空闲）。
+ *
+ * `holidays` 可选：浏览器侧镜像无法 import 本模块，测试与宿主以外的调用方可以传入
+ * 自己的日期集合；缺省用内置表，保证 `isPeak(ms)` 的既有语义不变。
+ */
+export function isPeak(ms, holidays = HOLIDAY_DAYS) {
+  const now = Number.isFinite(ms) ? ms : Date.now();
+  if (holidays.has(beijingDateKey(now))) return false; // 法定节假日：全天空闲
+  const d = new Date(now + SHANGHAI_OFFSET_MS);
+  if (PEAK_WEEKDAYS_ONLY) {
+    const dow = d.getUTCDay(); // 0 = 周日
+    if (dow === 0 || dow === 6) return false;
+  }
+  const h = d.getUTCHours();
+  return PEAK_WINDOWS.some(([start, end]) => h >= start && h < end);
+}
+
+/**
+ * 可能的切换时刻（北京时间的整点）：高峰窗口的起止整点。
+ * 翻转只可能发生在这些整点上——窗口外的整点不改变 isPeak，工作日之外则整天不变。
+ */
+const BOUNDARY_HOURS = [...new Set(PEAK_WINDOWS.flat())].sort((a, b) => a - b);
+
+/**
+ * 距下一个计费时段边界的剩余时间（供卡片显示倒计时）。
+ *
+ * 与 isPeak 同源同口径（北京时间、工作日、PEAK_WINDOWS 半开区间），只是换一个视图：
+ * 返回「下一次 isPeak 结果发生翻转」的时刻。注意空闲时段里的下一次切换**不等于**下一个
+ * 整点：
+ *   · 12:00–14:00 午休 → 下一次切换是 14:00（高峰开始）；
+ *   · 周五 18:00 之后、整个周末 → 下一次切换是下周一 09:00（跨 2 天多）。
+ * 因此倒计时必须能显示「天」。
+ *
+ * 实现：候选时刻就是 BOUNDARY_HOURS 落在各天的那些整点，从今天起逐日枚举、取第一个
+ * 让 isPeak 翻转的，因此返回的是**精确**时刻。纯算术，无时区/日历依赖。
+ * （旧实现逐分钟探测，返回的 at 最多晚 59.75 秒，倒计时会因此多显示 1m 或
+ * 提前进入 switching。）
+ *
+ * 任何口径变更必须同时改 isPeak / PEAK_WINDOWS / PEAK_WEEKDAYS_ONLY / HOLIDAY_RANGES，
+ * 以及 lib/client.js 里为浏览器侧镜像的同名常量（那边无法 import 本模块）。
+ *
+ * @returns {{ peak: boolean, at: number, ms: number }} peak=切换后所处的时段，
+ *   at=切换发生的时刻（ms 时间戳，新时段在此刻生效），ms=剩余毫秒（不会为负）。
+ *   找不到切换点时返回 `at: null`——调用方据此判断"不知道"，不要把它当成"此刻"。
+ */
+export function nextChange(ms, holidays = HOLIDAY_DAYS) {
+  const now = Number.isFinite(ms) ? ms : Date.now();
+  const current = isPeak(now, holidays);
+  const DAY = 24 * 60 * 60 * 1000;
+  const hourMs = 60 * 60 * 1000;
+  // 北京时间的今天零点
+  const dayStart = Date.parse(`${beijingDateKey(now)}T00:00:00Z`) - SHANGHAI_OFFSET_MS;
+  // 上限 32 天：远超"长假最后一天 18:00 → 假期后第一个工作日 09:00"的最长空档
+  // （2026 年春节假期 9 天，空档 10.7 天）
+  for (let day = 0; day < 32; day += 1) {
+    const base = dayStart + day * DAY;
+    for (const hour of BOUNDARY_HOURS) {
+      const at = base + hour * hourMs;
+      if (at <= now) continue;
+      const peak = isPeak(at, holidays);
+      if (peak !== current) return { peak, at, ms: at - now };
+    }
+  }
+  // 理论上不可达（不变量：一个月内必有工作日整点边界）。返回 at:null 而不是 now，
+  // 否则调用方会显示 switching 并永久卡住。
+  return { peak: !current, at: null, ms: 0 };
+}
+
+/**
+ * 是否是 DeepSeek 官方路由上的官方模型（官方价格表与峰谷时段只对它们成立）。
+ *
+ * 两道条件缺一不可：
+ *   1. provider 是官方两条路由之一（见 OFFICIAL_PROVIDERS）。Qwen token-plan、
+ *      NVIDIA、opencode、workbuddy 这些第三方路由上都有 `deepseek-*` 同名模型，
+ *      它们按各自的计价规则扣费，用官方表算出来的数字与账单无关。
+ *   2. 模型名以 `deepseek-` / `deepseek.` 开头，排除同一路由下的其它模型。
+ *
+ * provider 缺失（旧宿主、路由未上报）时按非官方处理：宁可隐藏，也不显示错价。
+ */
+export function isOfficialModel(model, provider) {
+  if (typeof provider !== 'string' || !OFFICIAL_PROVIDERS.includes(provider.trim().toLowerCase())) return false;
+  return typeof model === 'string' && /^deepseek[-.]/i.test(model.trim());
+}
+
+const has = (obj, key) => !!obj && Object.prototype.hasOwnProperty.call(obj, key);
+
+/** 别名（旧名 → 现名）。 */
+function aliasOf(id) {
+  if (typeof id !== 'string' || id === '') return undefined;
+  return MODEL_ALIASES[id];
+}
+
+/** 在价格表里找模型：精确 → 别名。表里没有就是不知道，不做家族猜测。 */
+function lookupId(id) {
+  if (typeof id !== 'string' || id === '') return null;
+  const key = id.trim().toLowerCase();
+  if (has(PRICE_TABLE, key)) return { id: key, via: 'exact' };
+  const alias = aliasOf(key);
+  if (alias && has(PRICE_TABLE, alias)) return { id: alias, via: 'alias' };
+  return null;
+}
+
+/**
+ * 解析模型的计价条目：精确 → 别名 → chat 档兜底（known=false）。
+ * 非官方模型（见 isOfficialModel）不查表，直接按 known=false 返回，由调用方隐藏
+ * 档单价与峰谷指示灯。
+ * @returns {{ price: object, id: string, via: 'exact'|'alias'|'fallback', known: boolean }}
+ */
+function lookup(model, provider) {
+  const found = isOfficialModel(model, provider) ? lookupId(model) : null;
+  if (found) return { price: PRICE_TABLE[found.id], id: found.id, via: found.via, known: true };
+  return { price: PRICE_TABLE['deepseek-chat'], id: 'deepseek-chat', via: 'fallback', known: false };
+}
+
+/**
+ * 某模型在某一时刻的单位价格（元/百万 tokens）。
+ * 非官方模型与不在表里的官方模型都会走 chat 档兜底，但 known=false 会把这件事告诉
+ * 调用方：那份兜底价与它们的实际账单无关，界面应隐藏。
+ * via 说明取价路径（exact / alias / fallback），供排查与回归测试。
+ */
+export function unitAt(model, ms, provider, holidays = HOLIDAY_DAYS) {
+  const found = lookup(model, provider);
+  const p = found.price;
+  const tier = isPeak(ms, holidays) ? 0 : 1;
+  return {
+    input: p.input[tier],
+    cacheRead: p.cacheRead[tier],
+    cacheWrite: p.cacheWrite,
+    output: p.output[tier],
+    model: found.id,
+    requested: typeof model === 'string' ? model : '',
+    provider: typeof provider === 'string' ? provider : '',
+    known: found.known,
+    via: found.via,
+  };
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@nomxy/dsh-balance",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Compact DeepSeek balance + peak/off-peak chip in the sidebar name row. · 侧边栏名字旁的 DeepSeek 余额与峰谷小胶囊。",
+  "type": "module",
+  "license": "MIT",
+  "icon": "icon.svg",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "icon.svg"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "deepseek-harness",
+    "usage",
+    "balance",
+    "billing",
+    "sidebar",
+    "ui"
+  ],
+  "engines": {
+    "dsh": ">=0.2.1-rc.1"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  }
+}