dsh-billing-badge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-13
+
+First public release.
+
+### Added
+
+- A pill in the composer statistics row, appended after the native cache-hit reading.
+  It shows a season dot (amber for peak, green for off-peak), the season name, and the
+  countdown to the next flip.
+- A panel on click, styled with the native dialog tokens: billing season, next switch
+  with the Beijing wall clock, current Beijing time, account balance with its currency,
+  the granted and topped-up split, a warning row when the API reports the balance as
+  insufficient for calls, and a refresh button.
+- A read-only host route, `GET /plugins/billing-badge/balance`, which resolves the API
+  key through the DSH credentials seam, caches a reading for 60 seconds, and dedupes
+  concurrent reads. It requires the `x-dsh-billing-badge: 1` header and rejects a
+  cross-origin `Origin`.
+- The season rule as a tested module: peak is Beijing time, Monday to Friday,
+  09:00-12:00 and 14:00-18:00, everything else including the whole weekend is off-peak
+  at half price. The next switch is computed by comparing each candidate boundary with
+  the instant before it, so only a real state flip counts.
+- 30 tests covering the season rule, a countdown invariant across nine days, bundle
+  and source sync, the host route and its guards, and the panel rows.
+
+### Fixed
+
+- `is_available` is a top-level field of the balance response, a sibling of
+  `balance_infos`, not a member of the entry. Reading it from the entry made the flag
+  false for every account. The regression test pins the documented location.
+
+MIT.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Vega
+
+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

@@ -0,0 +1,161 @@
+# dsh-billing-badge
+
+Billing season and account balance for the DeepSeek Harness web GUI. A pill in the
+composer's statistics row, immediately after the native **Cache hit** reading, that
+opens a small panel with the full picture.
+
+```
+2288M tok · Cache hit 99.8% · ● Off-peak · 2h13m
+```
+
+## What it shows
+
+| Where | What |
+|---|---|
+| The pill | a coloured dot (amber for peak, green for off-peak), the season, and the time until it flips |
+| The panel (click) | billing season, next switch with the Beijing wall clock, current Beijing time, account balance with its currency, granted and topped-up split, and a refresh button |
+
+The season rule is the published one: peak is Beijing time, Monday to Friday,
+09:00-12:00 and 14:00-18:00. Everything else, including all of Saturday and Sunday,
+is off-peak at half price.
+
+## The balance
+
+The numbers come from the official `GET /user/balance` endpoint, and the three of them
+mean different things:
+
+```
+total_balance = granted_balance + topped_up_balance
+```
+
+- `total_balance`, shown as **Account balance**, is everything you can spend.
+- `granted_balance`, shown as **Granted**, is credit DeepSeek gave you. The endpoint
+  reports only the part that has not expired, so a lapsed grant disappears from this
+  row on its own.
+- `topped_up_balance`, shown as **Topped up**, is money you paid in.
+
+When the two upper rows are equal there is no grant on the account. `is_available`
+is a top-level field of the response and answers one question: is the balance enough
+for API calls. The panel adds a warning row when the answer is no, and stays quiet
+otherwise, because the flag is true for every funded account.
+
+The currency is taken from the response, never assumed: an account reporting USD is
+not labelled with a CNY sign.
+
+## Why another one
+
+Two community plugins cover parts of this, and both taught something:
+
+- [dsh-price-phase](https://github.com/lijunyu726/dsh-price-phase) shows the season.
+  Its countdown once pointed at Saturday 09:00 after Friday close, an event that does
+  not happen, and it centres its badge on a hashed CSS class, which collides with the
+  model chip when the model name is long. This plugin compares each candidate boundary
+  with the instant before it and only counts a real state flip, and its chip is an
+  ordinary flex child in the native statistics row.
+- [dsh-usage-monitor](https://github.com/liyiersan/dsh-usage-monitor) shows the
+  balance, but formats it as CNY whatever the API reports.
+
+This plugin deliberately does **not** do cost or token accounting.
+
+## Install
+
+```sh
+dsh plugin --profile web add github:devacc8/dsh-billing-badge
+```
+
+then restart `dsh web`. The package declares `dsh.bundle.patch`, so the host half is
+reconciled into the profile's bundle list automatically.
+
+Working on the plugin itself, install the checkout by path instead:
+
+```sh
+dsh plugin --profile web add link:/absolute/path/to/dsh-billing-badge
+```
+
+## Security
+
+A balance is a small surface, so it stays small:
+
+- the API key is resolved in the host through the DSH credentials seam
+  (`ctx.credentials.resolve('DEEPSEEK_API_KEY')`, environment fallback) and never
+  reaches the browser;
+- the single route requires the `x-dsh-billing-badge: 1` header and rejects a
+  cross-origin `Origin`, so a cross-site page cannot reach it;
+- nothing is written to disk, and no endpoint other than `api.deepseek.com` is
+  contacted;
+- a missing key, an HTTP error or a network failure all degrade to a state the panel
+  renders, never to a throw.
+
+## Development
+
+The season logic lives in `lib/season.js` as a plain ESM module so it can be tested
+directly. A browser bundle cannot import a sibling file (the loader resolves only
+platform seeds, materialized packages and registered factories, and a self-subpath
+`require` throws "missed the module table"), so `scripts/inline-season.mjs` copies the
+module into `lib/client.js` between two markers with `export ` stripped, and
+`test/client-sync.test.mjs` fails if the copy drifts.
+
+```sh
+npm test          # 30 tests: season rule, countdown invariant, host route, bundle
+npm run sync      # re-inline season.js into the bundle
+npm run check     # sync check plus a syntax check of both halves
+```
+
+The countdown has an invariant test rather than fixtures: every 13 minutes across nine
+days, the reported target must be in the future, must change the season, and the
+season must not change before it.
+
+## Layout
+
+```
+lib/season.js    season rule, countdown, formatting (source of truth, tested)
+lib/index.js     host half: the balance route
+lib/client.js    browser half: the pill and its panel, with season.js inlined
+cordis.patch.yml mounts the host half into the profile
+scripts/         the inliner
+test/            season, sync, host and bundle tests
+```
+
+GitHub Actions runs `npm test` and `npm run check` on Node 20 and 22.
+
+## 中文说明
+
+DeepSeek Harness 网页界面的计费时段与账户余额插件。它在输入框下方的统计行里、原生 **Cache hit** 之后加一个小胶囊，点击后展开一个小面板。
+
+```
+2288M tok · Cache hit 99.8% · ● Off-peak · 2h13m
+```
+
+- **胶囊**：一个圆点（高峰为琥珀色，非高峰为绿色）、当前时段，以及距离切换的倒计时。
+- **面板**（点击展开）：计费时段、下次切换时间与北京时间、当前北京时间、账户余额及其货币、赠送额度与充值额度的拆分，以及刷新按钮。
+
+计费时段采用官方公布的规则：高峰为北京时间周一至周五 09:00-12:00 与 14:00-18:00，其余时间（含整个周六与周日）均为非高峰，价格为半价。
+
+余额来自官方 `GET /user/balance` 接口，其中三个数字含义不同：
+
+```
+total_balance = granted_balance + topped_up_balance
+```
+
+- `total_balance`（Account balance）：可用总额。
+- `granted_balance`（Granted）：官方赠送的额度，接口只返回尚未过期的部分，过期的赠送额度会自动从这一行消失。
+- `topped_up_balance`（Topped up）：你自己充值的金额。
+
+前两行数值相等时，说明账户没有赠送额度。`is_available` 是响应顶层的字段，回答一个问题：余额是否足够调用接口。只有接口报告余额不足时，面板才会加一行警告；该字段对任何有余额的账户都是 true，因此平时不显示。货币一律取自接口返回值，不做假设：返回 USD 的账户不会被标上人民币符号。
+
+### 安装
+
+```sh
+dsh plugin --profile web add github:devacc8/dsh-billing-badge
+```
+
+然后重启 `dsh web`。包内声明了 `dsh.bundle.patch`，宿主部分会自动写入 profile 的 bundle 列表。
+
+### 安全
+
+- API key 只在宿主进程中通过 DSH credentials 接口读取（`ctx.credentials.resolve('DEEPSEEK_API_KEY')`，环境变量兜底），不会进入浏览器；
+- 唯一的路由要求请求头 `x-dsh-billing-badge: 1`，并拒绝跨站 `Origin`；
+- 不写任何文件，除 `api.deepseek.com` 外不访问其他地址；
+- 缺少 key、HTTP 错误或网络故障都会降级为面板可显示的状态，不会抛异常。
+
+MIT.

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-billing-badge bundle patch: mounts the host half into the profile's host
+# composition. Applied by `dsh plugin --profile web add <this package>`, which
+# reconciles the package into dsh.profile.bundles automatically.
+- insert:
+    - id: billing-badge
+      name: dsh-billing-badge

package/lib/client.js

@@ -0,0 +1,473 @@
+window.__ModuleLoader__.load({
+	id: "dsh-billing-badge",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		const react = require("react");
+
+		/**
+		 * dsh-billing-badge, browser half.
+		 *
+		 * Shows the current DeepSeek billing season and the account balance in the
+		 * composer's statistics row, immediately after the native "Cache hit" pill,
+		 * and opens a small panel with the full reading on click.
+		 *
+		 * The native row is a single component (`[data-composer-stats]`) rather than a
+		 * slot, and the composer container is a column, so a sibling in the slot would
+		 * land underneath instead of beside it. The slot registration below is
+		 * therefore a mount point only: it renders nothing and appends the chip into
+		 * the native row. The data attribute is deliberate, unlike the hashed class an
+		 * earlier community plugin centred itself on (which collided with the model
+		 * chip), and the chip is an ordinary flex child so it cannot overlap anything.
+		 */
+
+		// >>> billing-badge:season (generated from lib/season.js by scripts/inline-season.mjs) >>>
+		/**
+		 * Billing season logic for DeepSeek's time-of-day pricing.
+		 *
+		 * The rule is fixed and published: peak windows are Beijing time, Monday to
+		 * Friday, 09:00-12:00 and 14:00-18:00. Everything else, including all of
+		 * Saturday and Sunday, is off-peak and billed at half the peak price.
+		 *
+		 * Timezone handling: the rule is defined in Beijing time (UTC+8), so every
+		 * calculation shifts the instant by a fixed offset and reads the UTC fields.
+		 * Local timezones are never used for the decision, only for display.
+		 *
+		 * @module season
+		 */
+		
+		/** Beijing time is UTC+8. */
+		const BEIJING_OFFSET_MS = 8 * 60 * 60 * 1000;
+		
+		/** Peak windows in Beijing time, as [from, to) minutes after midnight. */
+		const PEAK_WINDOWS = [
+		  [9 * 60, 12 * 60],
+		  [14 * 60, 18 * 60],
+		];
+		
+		/** Candidate boundary minutes: midnight plus every window edge. */
+		const BOUNDARY_MINUTES = [0, 9 * 60, 12 * 60, 14 * 60, 18 * 60];
+		
+		/** Milliseconds in a day, for candidate generation. */
+		const DAY_MS = 24 * 60 * 60 * 1000;
+		
+		/**
+		 * Whether an instant falls in a peak window (Beijing time, Monday to Friday).
+		 *
+		 * Weekend days return false before any window is tested. Comparing only the
+		 * clock would report a peak window every Saturday and Sunday, six hours of
+		 * false peak per week, which is the mistake this module exists to avoid.
+		 *
+		 * @param {Date} [at] - Instant to test, defaults to now.
+		 * @returns {boolean} True when the instant is peak.
+		 */
+		function isPeak(at = new Date()) {
+		  const beijing = new Date(at.getTime() + BEIJING_OFFSET_MS);
+		  const day = beijing.getUTCDay();
+		  if (day === 0 || day === 6) return false;
+		  const minutes = beijing.getUTCHours() * 60 + beijing.getUTCMinutes();
+		  return PEAK_WINDOWS.some(([from, to]) => minutes >= from && minutes < to);
+		}
+		
+		/**
+		 * Beijing midnight of the day that contains an instant, as an absolute time.
+		 *
+		 * @param {number} timeMs - Instant in milliseconds.
+		 * @returns {number} The instant of Beijing midnight.
+		 */
+		function beijingMidnight(timeMs) {
+		  const beijing = new Date(timeMs + BEIJING_OFFSET_MS);
+		  return Date.UTC(beijing.getUTCFullYear(), beijing.getUTCMonth(), beijing.getUTCDate()) - BEIJING_OFFSET_MS;
+		}
+		
+		/**
+		 * The next instant at which the season actually flips.
+		 *
+		 * Candidate boundaries are generated for the next ten days, then each is
+		 * accepted only when the state one millisecond before it differs from the state
+		 * at it. That filter is the point: Friday 18:00 ends the peak week, but the
+		 * following boundary, Saturday 09:00, changes nothing because the whole weekend
+		 * is already off-peak. Reporting it would show a countdown to an event that
+		 * does not happen, so the honest answer is Monday 09:00.
+		 *
+		 * @param {Date} [at] - Instant to search from, defaults to now.
+		 * @returns {number|null} Absolute time of the flip, or null when none is found.
+		 */
+		function nextFlip(at = new Date()) {
+		  const from = at.getTime();
+		  const midnight = beijingMidnight(from);
+		  const candidates = [];
+		  for (let day = 0; day <= 10; day += 1) {
+		    const base = midnight + day * DAY_MS;
+		    for (const minutes of BOUNDARY_MINUTES) candidates.push(base + minutes * 60 * 1000);
+		  }
+		  candidates.sort((a, b) => a - b);
+		  for (const candidate of candidates) {
+		    if (candidate <= from) continue;
+		    if (isPeak(new Date(candidate)) !== isPeak(new Date(candidate - 1))) return candidate;
+		  }
+		  return null;
+		}
+		
+		/**
+		 * Remaining time until an instant, as a compact label.
+		 *
+		 * @param {number} ms - Milliseconds remaining.
+		 * @returns {string} `2h13m`, `45m` or `38s`.
+		 */
+		function formatCountdown(ms) {
+		  const total = Math.max(0, Math.floor(ms / 1000));
+		  const hours = Math.floor(total / 3600);
+		  const minutes = Math.floor((total % 3600) / 60);
+		  const seconds = total % 60;
+		  if (hours > 0) return `${hours}h${String(minutes).padStart(2, '0')}m`;
+		  if (minutes > 0) return `${minutes}m`;
+		  return `${seconds}s`;
+		}
+		
+		/**
+		 * Beijing wall clock of an instant, for the popover.
+		 *
+		 * @param {Date} [at] - Instant to describe, defaults to now.
+		 * @returns {{weekday: string, clock: string}} Weekday name and HH:MM.
+		 */
+		function beijingClock(at = new Date()) {
+		  const beijing = new Date(at.getTime() + BEIJING_OFFSET_MS);
+		  const weekdays = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+		  const hh = String(beijing.getUTCHours()).padStart(2, '0');
+		  const mm = String(beijing.getUTCMinutes()).padStart(2, '0');
+		  return { weekday: weekdays[beijing.getUTCDay()], clock: `${hh}:${mm}` };
+		}
+		
+		/**
+		 * Everything the chip and its popover need for one instant.
+		 *
+		 * @param {Date} [at] - Instant to describe, defaults to now.
+		 * @returns {object} Phase description.
+		 */
+		function describePhase(at = new Date()) {
+		  const peak = isPeak(at);
+		  const flip = nextFlip(at);
+		  const remaining = flip === null ? null : flip - at.getTime();
+		  const countdown = remaining === null ? '' : formatCountdown(remaining);
+		  const { weekday, clock } = beijingClock(at);
+		  const label = peak ? 'Peak' : 'Off-peak';
+		  const compact = peak ? 'Peak' : 'Off-peak';
+		  const nextLabel = peak ? 'Off-peak' : 'Peak';
+		  return {
+		    peak,
+		    label,
+		    compact,
+		    countdown,
+		    flipAt: flip,
+		    remainingMs: remaining,
+		    nextLabel,
+		    beijing: { weekday, clock },
+		    /** Single source of truth for the two state colors, used by chip and popover. */
+		    color: peak ? '#D9A24A' : '#57C07C',
+		    title: peak
+		      ? `Peak billing until ${countdown} from now (${nextLabel} after that). Beijing time ${weekday} ${clock}.`
+		      : `Off-peak billing, half price, for another ${countdown}. Beijing time ${weekday} ${clock}.`,
+		  };
+		}
+		// <<< billing-badge:season <<<
+
+		const NS = "billing-badge";
+		const CSS_TAG_ID = "dsh-billing-badge/core.css";
+		const HEADER = { "x-dsh-billing-badge": "1" };
+		const BALANCE_URL = "/plugins/billing-badge/balance";
+		const TICK_MS = 30 * 1000;
+		const NARROW = "(max-width: 760px)";
+
+		/** Styles copied from the native stats pill and panel so the chip reads as part of the row. */
+		const CSS = `
+.dsh-billing-badge {
+  box-sizing: border-box; max-width: 100%;
+  color: var(--dsw-alias-label-tertiary);
+  font: inherit; font-variant-numeric: tabular-nums; line-height: inherit;
+  white-space: nowrap; background: 0 0; border: none; border-radius: 24px;
+  align-items: center; gap: 6px; padding: 1px 8px; display: inline-flex;
+  cursor: pointer;
+}
+.dsh-billing-badge:hover, .dsh-billing-badge[aria-expanded="true"] {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-secondary);
+}
+.dsh-billing-dot { width: 7px; height: 7px; border-radius: 50%; flex: none; }
+.dsh-billing-muted { opacity: .6; }
+.dsh-billing-panel {
+  position: fixed; z-index: 1100; box-sizing: border-box;
+  background: var(--dsw-specific-menu);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
+  color: var(--dsw-alias-label-secondary);
+  border: 0; border-radius: 12px; padding: 16px;
+  font-size: 12px; line-height: 18px;
+  min-width: min(300px, 100vw - 24px); max-width: min(420px, 100vw - 24px);
+}
+.dsh-billing-head { display: flex; align-items: center; gap: 8px; margin-bottom: 10px; }
+.dsh-billing-title { font-weight: 500; color: var(--dsw-alias-label-primary); flex: 1; }
+.dsh-billing-refresh {
+  background: 0 0; border: none; padding: 0 2px; cursor: pointer;
+  color: var(--dsw-alias-label-tertiary); font: inherit;
+}
+.dsh-billing-refresh:hover { color: var(--dsw-alias-label-primary); }
+.dsh-billing-rows { margin: 0; display: grid; grid-template-columns: auto 1fr; gap: 4px 12px; }
+.dsh-billing-rows dt { color: var(--dsw-alias-label-secondary); }
+.dsh-billing-rows dd { margin: 0; color: var(--dsw-alias-label-primary); font-variant-numeric: tabular-nums; text-align: right; }
+.dsh-billing-note { margin-top: 10px; color: var(--dsw-alias-label-caption); }
+.dsh-billing-err { color: var(--dsw-alias-state-warn-label); }
+`;
+
+		/** Inject the stylesheet once per page. */
+		function injectCss() {
+			if (typeof document === "undefined") return;
+			if (document.querySelector('style[data-plugin-css="' + CSS_TAG_ID + '"]') !== null) return;
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "dsh-billing-badge";
+			tag.dataset.pluginCss = CSS_TAG_ID;
+			tag.textContent = CSS;
+			document.head.appendChild(tag);
+		}
+
+		/** Format a money amount the way the API reports it: own currency, own precision. */
+		function formatMoney(amount, currency) {
+			if (typeof amount !== "number" || !Number.isFinite(amount)) return "--";
+			const digits = amount >= 100 ? 2 : amount >= 1 ? 2 : 4;
+			const symbol = currency === "CNY" ? "\u00a5" : currency === "USD" ? "$" : currency === "EUR" ? "\u20ac" : "";
+			const text = amount.toFixed(digits).replace(/0+$/, "").replace(/\.$/, "");
+			return symbol === "" ? `${text} ${currency || ""}`.trim() : `${symbol}${text}`;
+		}
+
+		/** Read the balance through the plugin's own route. */
+		async function loadBalance(refresh) {
+			try {
+				const response = await fetch(BALANCE_URL + (refresh ? "?refresh=1" : ""), { headers: HEADER });
+				if (!response.ok) return { ok: false, state: "error", error: `HTTP ${response.status}` };
+				return await response.json();
+			} catch (err) {
+				return { ok: false, state: "error", error: String((err && err.message) || err) };
+			}
+		}
+
+		/** Build the panel body for one reading. */
+		function panelBody(balance) {
+			const phase = describePhase(new Date());
+			const flip = phase.flipAt === null ? null : new Date(phase.flipAt);
+			const rows = [
+				["Billing season", phase.peak ? "Peak" : "Off-peak (half price)"],
+				["Next switch", phase.countdown === "" ? "--" : `in ${phase.countdown}` + (flip === null ? "" : `, ${beijingClock(flip).weekday} ${beijingClock(flip).clock} Beijing`)],
+				["Beijing time", `${phase.beijing.weekday} ${phase.beijing.clock}`],
+			];
+			if (balance && balance.ok) {
+				rows.push(["Account balance", formatMoney(balance.total, balance.currency) + (balance.currency ? ` ${balance.currency}` : "")]);
+				rows.push(["Granted", formatMoney(balance.granted, balance.currency)]);
+				rows.push(["Topped up", formatMoney(balance.toppedUp, balance.currency)]);
+				// `is_available` is true for every funded account, so it earns a row
+				// only when the API says the balance is not enough for calls. A
+				// permanent "allowed" row would be furniture.
+				if (balance.isAvailable === false) {
+					rows.push(["API calls", "insufficient balance", "warn"]);
+				}
+			} else if (balance && balance.state === "no-credential") {
+				rows.push(["Account balance", "no API key configured"]);
+			} else if (balance) {
+				rows.push(["Account balance", "unavailable"]);
+			}
+			return rows;
+		}
+
+		/**
+		 * Mount the chip and its panel into the native statistics row.
+		 *
+		 * @param {HTMLElement} row - The `[data-composer-stats]` element.
+		 * @returns {() => void} Teardown.
+		 */
+		function mountChip(row) {
+			injectCss();
+
+			const chip = document.createElement("button");
+			chip.type = "button";
+			chip.className = "dsh-billing-badge";
+			chip.setAttribute("aria-haspopup", "dialog");
+			chip.setAttribute("aria-expanded", "false");
+
+			const dot = document.createElement("span");
+			dot.className = "dsh-billing-dot";
+			const label = document.createElement("span");
+			const count = document.createElement("span");
+			count.className = "dsh-billing-muted";
+			chip.append(dot, label, count);
+
+			let panel = null;
+			let balance = null;
+			let balanceLoaded = false;
+			let tick = 0;
+
+			const render = () => {
+				const phase = describePhase(new Date());
+				dot.style.background = phase.color;
+				label.textContent = phase.compact;
+				const narrow = typeof window !== "undefined" && window.matchMedia(NARROW).matches;
+				count.textContent = narrow || phase.countdown === "" ? "" : "\u00b7 " + phase.countdown;
+				chip.title = phase.title;
+				if (panel !== null) fillPanel();
+			};
+
+			const fillPanel = () => {
+				if (panel === null) return;
+				const body = panel.querySelector(".dsh-billing-rows");
+				const note = panel.querySelector(".dsh-billing-note");
+				body.replaceChildren();
+				for (const [key, value, tone] of panelBody(balance)) {
+					const dt = document.createElement("dt");
+					dt.textContent = key;
+					const dd = document.createElement("dd");
+					dd.textContent = value;
+					if (tone === "warn") dd.style.color = "var(--dsw-alias-state-warn-label)";
+					body.append(dt, dd);
+				}
+				note.textContent = balance && balance.ok === false && balance.error
+					? String(balance.error)
+					: "Prices are published in CNY per million tokens; the balance keeps the currency the API reports.";
+				note.classList.toggle("dsh-billing-err", Boolean(balance && balance.ok === false));
+			};
+
+			const placePanel = () => {
+				if (panel === null) return;
+				const rect = chip.getBoundingClientRect();
+				panel.style.visibility = "hidden";
+				panel.style.left = "0px";
+				panel.style.top = "0px";
+				const width = panel.offsetWidth;
+				const height = panel.offsetHeight;
+				const left = Math.min(Math.max(8, rect.left), Math.max(8, window.innerWidth - width - 8));
+				const above = rect.top - height - 8;
+				panel.style.left = `${left}px`;
+				panel.style.top = `${above >= 8 ? above : rect.bottom + 8}px`;
+				panel.style.visibility = "";
+			};
+
+			const onDocumentPointer = (event) => {
+				if (panel === null) return;
+				if (panel.contains(event.target) || chip.contains(event.target)) return;
+				closePanel();
+			};
+			const onKey = (event) => {
+				if (event.key === "Escape") closePanel();
+			};
+			const onViewport = () => closePanel();
+
+			function closePanel() {
+				if (panel === null) return;
+				panel.remove();
+				panel = null;
+				chip.setAttribute("aria-expanded", "false");
+				document.removeEventListener("pointerdown", onDocumentPointer, true);
+				document.removeEventListener("keydown", onKey, true);
+				window.removeEventListener("resize", onViewport);
+				window.removeEventListener("scroll", onViewport, true);
+			}
+
+			async function openPanel() {
+				if (panel !== null) return;
+				panel = document.createElement("div");
+				panel.className = "dsh-billing-panel";
+				panel.setAttribute("role", "dialog");
+				panel.setAttribute("aria-label", "Billing and balance");
+				panel.innerHTML =
+					'<div class="dsh-billing-head"><span class="dsh-billing-title">Billing and balance</span>' +
+					'<button class="dsh-billing-refresh" type="button">Refresh</button></div>' +
+					'<dl class="dsh-billing-rows"></dl>' +
+					'<div class="dsh-billing-note"></div>';
+				panel.querySelector(".dsh-billing-refresh").addEventListener("click", async () => {
+					balance = await loadBalance(true);
+					fillPanel();
+				});
+				document.body.appendChild(panel);
+				chip.setAttribute("aria-expanded", "true");
+				fillPanel();
+				placePanel();
+				document.addEventListener("pointerdown", onDocumentPointer, true);
+				document.addEventListener("keydown", onKey, true);
+				window.addEventListener("resize", onViewport);
+				window.addEventListener("scroll", onViewport, true);
+				if (!balanceLoaded) {
+					balanceLoaded = true;
+					balance = await loadBalance(false);
+					fillPanel();
+					placePanel();
+				}
+			}
+
+			chip.addEventListener("click", () => {
+				if (panel === null) void openPanel();
+				else closePanel();
+			});
+
+			render();
+			tick = window.setInterval(render, TICK_MS);
+
+			row.appendChild(chip);
+
+			return () => {
+				window.clearInterval(tick);
+				closePanel();
+				chip.remove();
+			};
+		}
+
+		/**
+		 * Renderless slot occupant: its only job is to keep the chip attached to the
+		 * native statistics row, re-attaching when React recreates that row.
+		 */
+		function BillingMount() {
+			react.useEffect(() => {
+				let teardown = null;
+				let scheduled = false;
+
+				const attach = () => {
+					if (teardown !== null && document.querySelector(".dsh-billing-badge") !== null) return;
+					const row = document.querySelector('[data-composer-stats="true"]');
+					if (row === null) return;
+					if (teardown !== null) teardown();
+					teardown = mountChip(row);
+				};
+
+				const schedule = () => {
+					if (scheduled) return;
+					scheduled = true;
+					window.requestAnimationFrame(() => {
+						scheduled = false;
+						attach();
+					});
+				};
+
+				attach();
+				const observer = new MutationObserver(schedule);
+				observer.observe(document.body, { childList: true, subtree: true });
+				return () => {
+					observer.disconnect();
+					if (teardown !== null) teardown();
+				};
+			}, []);
+			return null;
+		}
+
+		const inject = ["slots"];
+
+		function apply(ctx) {
+			ctx.slots.inject("conversation.composer.dock", () =>
+				ctx.slots.register(
+					{ name: "conversation.composer.dock", id: "billing-badge", order: 10 },
+					BillingMount,
+				),
+			);
+		}
+
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.__internal = { mountChip, panelBody };
+		return module.exports;
+	},
+});

package/lib/index.js

@@ -0,0 +1,159 @@
+/**
+ * dsh-billing-badge, host half.
+ *
+ * Serves the DeepSeek account balance to the chip. One read-only route:
+ *
+ *   GET /plugins/billing-badge/balance
+ *
+ * Design notes:
+ *  - The API key is resolved from the credentials seam and never leaves this
+ *    process. The browser receives balance numbers only.
+ *  - Nothing is written to disk and no other endpoint is touched.
+ *  - Requests carry a plugin header and a cross-origin caller is rejected. A
+ *    cross-origin page cannot set a custom header without a preflight the
+ *    server never grants, which is the same guard the file explorer uses.
+ *  - Every failure degrades to a state the chip can render, never to a throw.
+ *
+ * @module dsh-billing-badge
+ */
+
+export const name = 'billing-badge'
+
+/** Web server for the route, credentials for the API key. */
+export const inject = ['webServer', 'credentials']
+
+/** Balance endpoint, the only network destination of this plugin. */
+const BALANCE_ENDPOINT = 'https://api.deepseek.com/user/balance'
+
+/** Route path. */
+const ROUTE = '/plugins/billing-badge/balance'
+
+/** Header every request must carry. */
+const HEADER = 'x-dsh-billing-badge'
+
+/** How long a balance reading is reused. */
+const TTL_MS = 60_000
+
+/** Request timeout. */
+const TIMEOUT_MS = 15_000
+
+/**
+ * Shape one balance reading into the response the chip consumes.
+ *
+ * @param {object} parsed - Parsed API response.
+ * @returns {object} Response body.
+ */
+function readBalance(parsed) {
+  const info = Array.isArray(parsed?.balance_infos) ? parsed.balance_infos[0] : undefined
+  if (info === undefined) {
+    return { ok: false, state: 'empty', error: 'the balance response carried no balance_infos entry' }
+  }
+  return {
+    ok: true,
+    state: 'ok',
+    at: new Date().toISOString(),
+    // The API decides the currency. Never assume one: a USD account labelled
+    // with a CNY sign is worse than no number at all.
+    currency: String(info.currency ?? ''),
+    // `is_available` is a TOP-LEVEL field of the response, a sibling of
+    // `balance_infos`, not a member of the entry. Reading it off `info` always
+    // produced false, so the chip would have cried wolf forever.
+    isAvailable: parsed?.is_available === true,
+    total: Number(info.total_balance ?? 0),
+    granted: Number(info.granted_balance ?? 0),
+    toppedUp: Number(info.topped_up_balance ?? 0),
+  }
+}
+
+export function apply(ctx) {
+  let cached = null
+  let inflight = null
+
+  const message = (err) => String((err && err.message) || err)
+
+  const sameOrigin = (req) => {
+    const headers = req.headers ?? {}
+    const origin = headers.origin
+    if (origin === undefined) return true
+    try {
+      return new URL(origin).host === String(headers.host ?? '')
+    } catch {
+      return false
+    }
+  }
+
+  const send = (res, status, body) => {
+    res.writeHead(status, {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+    })
+    res.end(JSON.stringify(body))
+  }
+
+  /** Resolve the key through the credentials seam, then the process environment. */
+  const resolveKey = async () => {
+    try {
+      const resolved = await ctx.credentials?.resolve?.('DEEPSEEK_API_KEY')
+      if (resolved?.value) return resolved.value
+    } catch {
+      /* fall through to the environment */
+    }
+    return process.env.DEEPSEEK_API_KEY || undefined
+  }
+
+  const load = async () => {
+    const key = await resolveKey()
+    if (!key) return { ok: false, state: 'no-credential', error: 'DEEPSEEK_API_KEY is not configured' }
+    try {
+      const response = await fetch(BALANCE_ENDPOINT, {
+        headers: { authorization: `Bearer ${key}`, accept: 'application/json' },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      })
+      const text = await response.text()
+      if (!response.ok) {
+        return { ok: false, state: 'error', error: `HTTP ${response.status}: ${text.slice(0, 200)}` }
+      }
+      return readBalance(JSON.parse(text))
+    } catch (err) {
+      return { ok: false, state: 'error', error: message(err) }
+    }
+  }
+
+  const balance = async (force) => {
+    if (!force && cached !== null && Date.now() - Date.parse(cached.at) < TTL_MS) return cached
+    if (inflight !== null) return inflight
+    inflight = load()
+      .then((result) => {
+        cached = result.at === undefined ? { at: new Date().toISOString(), ...result } : result
+        return cached
+      })
+      .catch((err) => ({ ok: false, state: 'error', error: message(err) }))
+      .finally(() => {
+        inflight = null
+      })
+    return inflight
+  }
+
+  ctx.inject(['webServer'], (httpCtx) => {
+    httpCtx.effect(
+      () =>
+        httpCtx.webServer.register({
+          kind: 'exact',
+          path: ROUTE,
+          handler: async (req, res) => {
+            if (String((req.headers ?? {})[HEADER] ?? '') !== '1') {
+              send(res, 403, { ok: false, state: 'forbidden', error: 'missing plugin header' })
+              return
+            }
+            if (!sameOrigin(req)) {
+              send(res, 403, { ok: false, state: 'forbidden', error: 'cross-origin request rejected' })
+              return
+            }
+            const url = new URL(req.url ?? ROUTE, 'http://x')
+            send(res, 200, await balance(url.searchParams.get('refresh') === '1'))
+          },
+        }),
+      'billing-badge: balance route',
+    )
+  })
+}

package/lib/season.js

@@ -0,0 +1,148 @@
+/**
+ * Billing season logic for DeepSeek's time-of-day pricing.
+ *
+ * The rule is fixed and published: peak windows are Beijing time, Monday to
+ * Friday, 09:00-12:00 and 14:00-18:00. Everything else, including all of
+ * Saturday and Sunday, is off-peak and billed at half the peak price.
+ *
+ * Timezone handling: the rule is defined in Beijing time (UTC+8), so every
+ * calculation shifts the instant by a fixed offset and reads the UTC fields.
+ * Local timezones are never used for the decision, only for display.
+ *
+ * @module season
+ */
+
+/** Beijing time is UTC+8. */
+export const BEIJING_OFFSET_MS = 8 * 60 * 60 * 1000;
+
+/** Peak windows in Beijing time, as [from, to) minutes after midnight. */
+export const PEAK_WINDOWS = [
+  [9 * 60, 12 * 60],
+  [14 * 60, 18 * 60],
+];
+
+/** Candidate boundary minutes: midnight plus every window edge. */
+const BOUNDARY_MINUTES = [0, 9 * 60, 12 * 60, 14 * 60, 18 * 60];
+
+/** Milliseconds in a day, for candidate generation. */
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Whether an instant falls in a peak window (Beijing time, Monday to Friday).
+ *
+ * Weekend days return false before any window is tested. Comparing only the
+ * clock would report a peak window every Saturday and Sunday, six hours of
+ * false peak per week, which is the mistake this module exists to avoid.
+ *
+ * @param {Date} [at] - Instant to test, defaults to now.
+ * @returns {boolean} True when the instant is peak.
+ */
+export function isPeak(at = new Date()) {
+  const beijing = new Date(at.getTime() + BEIJING_OFFSET_MS);
+  const day = beijing.getUTCDay();
+  if (day === 0 || day === 6) return false;
+  const minutes = beijing.getUTCHours() * 60 + beijing.getUTCMinutes();
+  return PEAK_WINDOWS.some(([from, to]) => minutes >= from && minutes < to);
+}
+
+/**
+ * Beijing midnight of the day that contains an instant, as an absolute time.
+ *
+ * @param {number} timeMs - Instant in milliseconds.
+ * @returns {number} The instant of Beijing midnight.
+ */
+function beijingMidnight(timeMs) {
+  const beijing = new Date(timeMs + BEIJING_OFFSET_MS);
+  return Date.UTC(beijing.getUTCFullYear(), beijing.getUTCMonth(), beijing.getUTCDate()) - BEIJING_OFFSET_MS;
+}
+
+/**
+ * The next instant at which the season actually flips.
+ *
+ * Candidate boundaries are generated for the next ten days, then each is
+ * accepted only when the state one millisecond before it differs from the state
+ * at it. That filter is the point: Friday 18:00 ends the peak week, but the
+ * following boundary, Saturday 09:00, changes nothing because the whole weekend
+ * is already off-peak. Reporting it would show a countdown to an event that
+ * does not happen, so the honest answer is Monday 09:00.
+ *
+ * @param {Date} [at] - Instant to search from, defaults to now.
+ * @returns {number|null} Absolute time of the flip, or null when none is found.
+ */
+export function nextFlip(at = new Date()) {
+  const from = at.getTime();
+  const midnight = beijingMidnight(from);
+  const candidates = [];
+  for (let day = 0; day <= 10; day += 1) {
+    const base = midnight + day * DAY_MS;
+    for (const minutes of BOUNDARY_MINUTES) candidates.push(base + minutes * 60 * 1000);
+  }
+  candidates.sort((a, b) => a - b);
+  for (const candidate of candidates) {
+    if (candidate <= from) continue;
+    if (isPeak(new Date(candidate)) !== isPeak(new Date(candidate - 1))) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Remaining time until an instant, as a compact label.
+ *
+ * @param {number} ms - Milliseconds remaining.
+ * @returns {string} `2h13m`, `45m` or `38s`.
+ */
+export function formatCountdown(ms) {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = total % 60;
+  if (hours > 0) return `${hours}h${String(minutes).padStart(2, '0')}m`;
+  if (minutes > 0) return `${minutes}m`;
+  return `${seconds}s`;
+}
+
+/**
+ * Beijing wall clock of an instant, for the popover.
+ *
+ * @param {Date} [at] - Instant to describe, defaults to now.
+ * @returns {{weekday: string, clock: string}} Weekday name and HH:MM.
+ */
+export function beijingClock(at = new Date()) {
+  const beijing = new Date(at.getTime() + BEIJING_OFFSET_MS);
+  const weekdays = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+  const hh = String(beijing.getUTCHours()).padStart(2, '0');
+  const mm = String(beijing.getUTCMinutes()).padStart(2, '0');
+  return { weekday: weekdays[beijing.getUTCDay()], clock: `${hh}:${mm}` };
+}
+
+/**
+ * Everything the chip and its popover need for one instant.
+ *
+ * @param {Date} [at] - Instant to describe, defaults to now.
+ * @returns {object} Phase description.
+ */
+export function describePhase(at = new Date()) {
+  const peak = isPeak(at);
+  const flip = nextFlip(at);
+  const remaining = flip === null ? null : flip - at.getTime();
+  const countdown = remaining === null ? '' : formatCountdown(remaining);
+  const { weekday, clock } = beijingClock(at);
+  const label = peak ? 'Peak' : 'Off-peak';
+  const compact = peak ? 'Peak' : 'Off-peak';
+  const nextLabel = peak ? 'Off-peak' : 'Peak';
+  return {
+    peak,
+    label,
+    compact,
+    countdown,
+    flipAt: flip,
+    remainingMs: remaining,
+    nextLabel,
+    beijing: { weekday, clock },
+    /** Single source of truth for the two state colors, used by chip and popover. */
+    color: peak ? '#D9A24A' : '#57C07C',
+    title: peak
+      ? `Peak billing until ${countdown} from now (${nextLabel} after that). Beijing time ${weekday} ${clock}.`
+      : `Off-peak billing, half price, for another ${countdown}. Beijing time ${weekday} ${clock}.`,
+  };
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dsh-billing-badge",
+  "version": "0.1.0",
+  "description": "Billing season and account balance chip for the DeepSeek Harness web GUI composer: a native-looking pill after the cache-hit stat, with a panel on click. DeepSeek Harness 计费时段与余额插件",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "sync": "node scripts/inline-season.mjs",
+    "check": "node scripts/inline-season.mjs --check && node --check lib/client.js && node --check lib/index.js"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "billing",
+    "balance",
+    "off-peak",
+    "composer"
+  ],
+  "homepage": "https://github.com/devacc8/dsh-billing-badge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devacc8/dsh-billing-badge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devacc8/dsh-billing-badge/issues"
+  },
+  "author": "devacc8",
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
+      "platform": "web"
+    }
+  }
+}