dsh-balance-plugin 0.1.0

package/LICENSE

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

package/PUBLISHING.md

@@ -0,0 +1,67 @@
+# Publishing dsh-balance-plugin
+
+Step-by-step release manual for the two official distribution channels (both are supported and can coexist).
+
+## Prerequisites
+
+- [npm](https://docs.npmjs.com/cli/) account, logged in: `npm whoami`
+- A GitHub account; the repository will be public.
+
+## 1. Create the GitHub repository
+
+1. On GitHub, **New repository** → name `dsh-balance-plugin`, public.
+2. **Do not** initialize with README/.gitignore (this repo already has them).
+3. Add the local remote and push:
+
+```sh
+cd ~/Documents/dsh-balance-plugin
+git remote add origin git@github.com:<you>/dsh-balance-plugin.git
+git push -u origin main
+```
+
+4. On the repository page: **About → Topics → add `dsh-plugin`** (the official discovery topic from DeepSeek Harness's README). Also consider `deepseek-harness`.
+
+## 2. Publish to npm
+
+```sh
+# from ~/Documents/dsh-balance-plugin
+pnpm run build && pnpm test     # gates
+npm version patch                # bumps to 0.1.1, creates the git tag
+pnpm pack                        # inspect the tarball contents
+npm publish                      # publishes prebuilt lib/ — users install with zero friction
+git push && git push --tags
+```
+
+npm is the **recommended** channel: users run `dsh plugin --profile <name> add dsh-balance-plugin` and get prebuilt code with no install-time build or permission prompt.
+
+## 3. GitHub installs (optional, automatic once the repo exists)
+
+Users can also install directly from GitHub. Two official caveats (from `docs/user/develop/basic/publish.md`):
+
+- Git installs fetch **source**, not build output — the package ships a self-contained `prepare` script (`node scripts/build.mjs`, no project references), which pnpm runs after install;
+- pnpm ≥ 10 refuses to run git dependencies' `prepare` until the user opts in via `allowBuilds` in the profile's `pnpm-workspace.yaml`. Document this in your README (already present).
+
+## 4. Versioning and release notes
+
+- Keep npm version and GitHub tag in sync (both come from `npm version`).
+- Create a GitHub Release per tag with the changelog; reference the npm version.
+- Semantic versioning: `patch` for fixes, `minor` for features, `major` for breaking changes.
+
+## 5. Verification checklist (official inspection points)
+
+```sh
+# fresh install from the tarball
+dsh plugin --profile demo add ./dsh-balance-plugin-0.1.0.tgz
+dsh --profile demo --dump-config     # expect "# == dsh-balance-plugin" layer
+# then in the web profile with a real credential: the readout renders
+```
+
+## 6. Local development loop
+
+```sh
+pnpm install
+pnpm run build     # lib/index.js (host) + lib/client.js (browser) + lib/balance-core.js
+pnpm test          # node:test unit tests (no framework)
+```
+
+To test changes live in a profile: `dsh plugin --profile web add ./` (links the local checkout), restart `dsh web`, hard-refresh the browser.

package/README.md

@@ -0,0 +1,122 @@
+# dsh-balance-plugin
+
+DeepSeek wallet balance at the sidebar foot — a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin.
+
+English | [中文](README.zh.md)
+
+Shows your DeepSeek account balance as a **card icon + amount** in the sidebar footer (beside Settings), tinted by how much is left. Refreshes when a conversation turn ends, on click, and on mount — no polling.
+
+![screenshot placeholder: sidebar foot showing `💳 ¥12.34` in green](docs/screenshot.png)
+
+## Features
+
+- **Status-tinted amount**: only the amount carries the color, the icon stays neutral —
+  - ≥ `lowBalanceThreshold` (default **2**): green
+  - above zero: amber
+  - zero or below: red
+- **Refresh on turn end**: the host pushes an SSE `refresh` event when any conversation turn ends — wallet spend settles with the turn.
+- **Click to refresh**; in-flight refreshes are deduped (a click or turn-end tick during a pending query is a no-op).
+- **Silent failure**: unconfigured credentials or a failed fetch render nothing — the readout is advisory and never surfaces an error.
+- **Original currencies**: balances are displayed as the provider reports them; no conversion, no summing.
+
+## Install
+
+Requires a DeepSeek account credential. The plugin resolves `DEEPSEEK_API_KEY` through the harness credential seam (`~/.dsh/.credentials.yaml` or the environment), exactly like the official DeepSeek adapter.
+
+### From npm (recommended)
+
+```sh
+dsh plugin --profile <name> add dsh-balance-plugin
+```
+
+### From GitHub
+
+```sh
+dsh plugin --profile <name> add github:<you>/dsh-balance-plugin#<commit-sha>
+```
+
+Git installs fetch source, so pnpm ≥ 10 refuses the install-time build until you allow it. Copy the exact package key pnpm prints into the profile's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  dsh-balance-plugin: true
+```
+
+then re-run the `add` command. Only install packages whose source you trust, and pin the commit.
+
+## Configuration
+
+The plugin ships with sensible defaults; override via the bundle's plugin row:
+
+```yaml
+# profile's cordis.patch.yml (or your home-level one)
+- id: balance
+  name: dsh-balance-plugin
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY      # credential reference, then the environment
+    baseURL: https://api.deepseek.com # provider base URL
+    timeoutMs: 12000                 # per-request timeout; abort maps to balance-timeout
+    lowBalanceThreshold: 2           # amount at or above which the tint reads healthy
+```
+
+## How it works
+
+| Half | What it does |
+|---|---|
+| **Host** (Node) | Registers `GET /dsh-balance` (the wallet readout as JSON) and `GET /dsh-balance/events` (an SSE stream). Listens on the harness's `session/event` broadcast and emits a `refresh` SSE event per `turn/end`. Resolves the credential **per request** through `ctx.credentials`, falling back to the environment — a changed key applies without a restart. |
+| **Client** (browser) | Registers the `sidebar.footer.action` slot entry (the shell's reserved seat beside Settings; on the collapsed rail it stacks above the settings icon). Fetches the readout on mount, on `refresh` SSE events, and on click, with an in-flight guard. The card icon is self-contained (no dependency on the shell's icon library). |
+
+Position and interaction follow the shell's own design: the `sidebar.footer.action` hole is the official extension point for "optional actions beside Settings".
+
+## Frequently asked questions
+
+**The balance looks stale right after a conversation ends.** Provider settlement lags the turn by tens of seconds. The turn-end refresh may briefly show the pre-settlement amount; clicking later shows the settled value. This matches the official DeepSeek client behavior — the readout is advisory.
+
+**Nothing renders.** No credential resolves (`unconfigured`) or the fetch failed — by design. Check `dsh --profile <name> --dump-config` for the plugin row, and that `DEEPSEEK_API_KEY` resolves through the credential seam or the environment.
+
+**How do I remove it?**
+
+```sh
+dsh plugin --profile <name> remove dsh-balance-plugin
+```
+
+This removes the dependency and the bundle layer together.
+
+## Development
+
+```
+src/
+  balance-core.ts   # pure query logic (credential resolution, HTTP, normalization)
+  index.ts          # host plugin: routes + SSE + turn-end listener
+  client.tsx        # browser plugin: the sidebar-foot action
+scripts/build.mjs   # esbuild: host ESM + browser __ModuleLoader__ bundle
+tests/              # node:test unit tests for balance-core
+```
+
+```sh
+pnpm install
+pnpm run build    # emits lib/index.js + lib/client.js
+pnpm test         # balance-core unit tests
+```
+
+Local install check (official verification points):
+
+```sh
+dsh plugin --profile demo add ./
+dsh --profile demo --dump-config   # expect a "# == dsh-balance-plugin" layer
+```
+
+## Release checklist
+
+Before publishing a new version:
+
+1. `pnpm run build` and `pnpm test` pass.
+2. Local install check above passes (`--dump-config` shows the layer; the web profile renders the readout with a real credential).
+3. Version bumped (`npm version patch/minor/major`); git tag matches.
+4. `pnpm pack` — inspect the tarball: it must contain `lib/`, `cordis.patch.yml`, `README.md` (and nothing else heavy).
+5. `npm publish` — publishes prebuilt code, so users install with zero friction.
+6. Push the tag; keep the GitHub release notes in sync with the npm version.
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,122 @@
+# dsh-balance-plugin
+
+侧边栏底部的 DeepSeek 钱包余额——一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件。
+
+[English](README.md) | 中文
+
+在侧边栏底部（设置按钮旁）以**信用卡图标 + 金额**显示你的 DeepSeek 账户余额，并按剩余额度着色。在对话结束时、点击时与挂载时刷新——无轮询。
+
+![截图占位：侧边栏底部显示绿色的 `💳 ¥12.34`](docs/screenshot.png)
+
+## 功能
+
+- **状态着色**：只有金额带颜色，图标保持中性——
+  - ≥ `lowBalanceThreshold`（默认 **2**）：绿色
+  - 大于零：黄色
+  - 零或以下：红色
+- **对话结束自动刷新**：宿主在任何对话轮次结束时推送 SSE `refresh` 事件——消耗随轮次结算。
+- **点击刷新**；在途刷新去重（查询进行中时点击或轮次结束触发均为 no-op）。
+- **失败静默**：凭证未配置或抓取失败时不渲染任何内容——读数仅供参考，绝不显示错误。
+- **原始币种**：余额按提供方报告显示；不换算、不加总。
+
+## 安装
+
+需要一个 DeepSeek 账户凭证。插件通过 harness 凭证接缝（`~/.dsh/.credentials.yaml` 或环境变量）解析 `DEEPSEEK_API_KEY`，与官方 DeepSeek 适配器一致。
+
+### 从 npm 安装（推荐）
+
+```sh
+dsh plugin --profile <名字> add dsh-balance-plugin
+```
+
+### 从 GitHub 安装
+
+```sh
+dsh plugin --profile <名字> add github:<你>/dsh-balance-plugin#<commit-sha>
+```
+
+Git 安装取到的是源码，pnpm ≥ 10 会拒绝安装时的构建，直到你允许：把 pnpm 打印的包键复制进 profile 的 `pnpm-workspace.yaml`：
+
+```yaml
+allowBuilds:
+  dsh-balance-plugin: true
+```
+
+然后重跑 `add`。只安装你信任源码的包，并钉住 commit。
+
+## 配置
+
+插件带合理默认值；可通过 bundle 的插件行覆盖：
+
+```yaml
+# profile 的 cordis.patch.yml（或 home 级）
+- id: balance
+  name: dsh-balance-plugin
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY      # 凭证引用，随后回退环境变量
+    baseURL: https://api.deepseek.com # 提供方基础 URL
+    timeoutMs: 12000                 # 每次请求超时；中止映射为 balance-timeout
+    lowBalanceThreshold: 2           # 读数视为健康的最低金额
+```
+
+## 工作原理
+
+| 半面 | 做什么 |
+|---|---|
+| **宿主**（Node） | 注册 `GET /dsh-balance`（钱包读数 JSON）与 `GET /dsh-balance/events`（SSE 流）。监听 harness 的 `session/event` 广播，每个 `turn/end` 推送 `refresh` 事件。**每次请求**经 `ctx.credentials` 解析凭证并回退环境变量——改 key 无需重启。 |
+| **客户端**（浏览器） | 注册 `sidebar.footer.action` 插槽条目（shell 预留的设置旁座位；收起 rail 时堆叠在设置图标上方）。在挂载时、`refresh` SSE 事件与点击时抓取读数，带 in-flight 守卫。信用卡图标自包含（不依赖 shell 的图标库）。 |
+
+位置与交互遵循 shell 自身设计：`sidebar.footer.action` 是"设置旁可选操作"的官方扩展点。
+
+## 常见问题
+
+**对话刚结束余额看起来是旧的。** 提供方结算滞后于轮次数十秒。轮次结束的刷新可能短暂显示结算前金额；稍后点击显示结算后数值。这与官方 DeepSeek 客户端行为一致——读数仅供参考。
+
+**什么都不显示。** 凭证未解析（`unconfigured`）或抓取失败——这是设计。用 `dsh --profile <名字> --dump-config` 检查插件行，确认 `DEEPSEEK_API_KEY` 能通过凭证接缝或环境变量解析。
+
+**如何卸载？**
+
+```sh
+dsh plugin --profile <名字> remove dsh-balance-plugin
+```
+
+该命令同时移除依赖与层。
+
+## 开发
+
+```
+src/
+  balance-core.ts   # 纯查询逻辑（凭证解析、HTTP、归一化）
+  index.ts          # 宿主插件：路由 + SSE + 轮次结束监听
+  client.tsx        # 浏览器插件：侧边栏底部操作
+scripts/build.mjs   # esbuild：宿主 ESM + 浏览器 __ModuleLoader__ bundle
+tests/              # balance-core 的 node:test 单元测试
+```
+
+```sh
+pnpm install
+pnpm run build    # 生成 lib/index.js + lib/client.js
+pnpm test         # balance-core 单元测试
+```
+
+本地安装检查（官方检验点）：
+
+```sh
+dsh plugin --profile demo add ./
+dsh --profile demo --dump-config   # 应出现 "# == dsh-balance-plugin" 层
+```
+
+## 发布检查清单
+
+发布新版本前：
+
+1. `pnpm run build` 与 `pnpm test` 通过。
+2. 上述本地安装检查通过（`--dump-config` 显示层；web profile 用真实凭证渲染读数）。
+3. 版本已提升（`npm version patch/minor/major`）；git tag 对应。
+4. `pnpm pack`——检查 tarball：必须包含 `lib/`、`cordis.patch.yml`、`README.md`（别无其他大文件）。
+5. `npm publish`——发布预构建代码，用户零摩擦安装。
+6. 推送 tag；GitHub release 说明与 npm 版本保持一致。
+
+## 许可
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: balance
+      name: dsh-balance-plugin

package/lib/balance-core.js

@@ -0,0 +1,97 @@
+// src/balance-core.ts
+function symbol(currency) {
+  switch (currency.toUpperCase()) {
+    case "CNY":
+    case "RMB":
+      return "\xA5";
+    case "USD":
+      return "$";
+    default:
+      return currency === "" ? "" : `${currency} `;
+  }
+}
+function normalizeCurrency(currency) {
+  switch (currency.toUpperCase().trim()) {
+    case "CNY":
+    case "RMB":
+    case "CNH":
+    case "\xA5":
+    case "\uFFE5":
+      return "CNY";
+    case "USD":
+    case "$":
+      return "USD";
+    default:
+      return "";
+  }
+}
+function primaryInfo(infos) {
+  if (infos.length === 0) return void 0;
+  return infos.find((info) => normalizeCurrency(info.currency) === "CNY") ?? infos[0];
+}
+function displayFor(infos) {
+  const pick = primaryInfo(infos);
+  if (pick === void 0) return "";
+  return `${symbol(pick.currency)}${pick.total.trim()}`;
+}
+function primaryTotal(infos) {
+  const pick = primaryInfo(infos);
+  if (pick === void 0) return 0;
+  const parsed = Number.parseFloat(pick.total);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+async function fetchBalance(credentials, env, config) {
+  const resolved = await credentials?.resolve(config.apiKeyEnv);
+  const apiKey = resolved?.value ?? env[config.apiKeyEnv];
+  if (!apiKey) {
+    return { status: "unconfigured" };
+  }
+  const timeout = AbortSignal.timeout(config.timeoutMs);
+  const url = `${config.baseURL.replace(/\/+$/, "")}/user/balance`;
+  try {
+    const response = await fetch(url, {
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${apiKey}`
+      },
+      signal: timeout
+    });
+    const body = await response.text();
+    if (!response.ok) {
+      return { status: "unavailable", reason: `balance-http-${String(response.status)}` };
+    }
+    const parsed = JSON.parse(body);
+    const infos = (parsed.balance_infos ?? []).map((info) => ({
+      currency: info.currency,
+      total: info.total_balance,
+      granted: info.granted_balance,
+      toppedUp: info.topped_up_balance
+    }));
+    if (infos.length === 0) {
+      return { status: "unavailable", reason: "balance-empty" };
+    }
+    return {
+      status: "ok",
+      available: parsed.is_available,
+      display: displayFor(infos),
+      total: primaryTotal(infos),
+      threshold: config.lowBalanceThreshold,
+      currencies: [...new Set(infos.map((info) => {
+        const normalized = normalizeCurrency(info.currency);
+        return normalized === "" ? info.currency.toUpperCase() : normalized;
+      }))].sort(),
+      infos
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return { status: "unavailable", reason: "balance-timeout" };
+    }
+    if (error instanceof SyntaxError) {
+      return { status: "unavailable", reason: "balance-decode" };
+    }
+    return { status: "unavailable", reason: "balance-network" };
+  }
+}
+export {
+  fetchBalance
+};

package/lib/client.js

@@ -0,0 +1,132 @@
+window.__ModuleLoader__.load({ id: "dsh-balance-plugin", factory: (require) => {
+var module = { exports: {} }; var exports = module.exports;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.tsx
+var client_exports = {};
+__export(client_exports, {
+  BalanceAction: () => BalanceAction,
+  apply: () => apply,
+  inject: () => inject,
+  name: () => name
+});
+module.exports = __toCommonJS(client_exports);
+var import_react = require("react");
+var name = "dsh-balance-plugin";
+var inject = ["slots"];
+var BALANCE_ENDPOINT = "/dsh-balance";
+var EVENTS_ENDPOINT = "/dsh-balance/events";
+function CardIcon({ size }) {
+  return (0, import_react.createElement)(
+    "svg",
+    {
+      width: size,
+      height: size,
+      viewBox: "0 0 16 16",
+      fill: "none",
+      xmlns: "http://www.w3.org/2000/svg",
+      style: { flex: "none" }
+    },
+    (0, import_react.createElement)("rect", { x: 1.3, y: 3.2, width: 13.4, height: 9.6, rx: 1.8, stroke: "currentColor", strokeWidth: 1.2 }),
+    (0, import_react.createElement)("path", { d: "M1.3 6.2 H14.7", stroke: "currentColor", strokeWidth: 1.1 }),
+    (0, import_react.createElement)("path", { d: "M3.8 10.7 H8", stroke: "currentColor", strokeWidth: 1, strokeLinecap: "round" }),
+    (0, import_react.createElement)("path", { d: "M9.2 10.7 H12.2", stroke: "currentColor", strokeWidth: 1, strokeLinecap: "round" })
+  );
+}
+var styles = {
+  button: {
+    flex: "none",
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 6,
+    minWidth: 28,
+    height: 28,
+    border: "none",
+    borderRadius: 999,
+    padding: "0 6px",
+    background: "transparent",
+    cursor: "pointer",
+    color: "var(--dsw-alias-label-secondary, #6b7280)"
+  },
+  amount: {
+    overflow: "hidden",
+    whiteSpace: "nowrap",
+    textOverflow: "ellipsis",
+    fontSize: 17,
+    fontWeight: 700,
+    fontVariantNumeric: "tabular-nums",
+    lineHeight: 1
+  },
+  success: { color: "var(--dsw-alias-state-success-primary, #16a34a)" },
+  warning: { color: "var(--dsw-static-amber-600, #d97706)" },
+  danger: { color: "var(--dsw-alias-state-error-primary, #dc2626)" }
+};
+function toneOf(readout) {
+  if (readout.total >= readout.threshold) return "success";
+  if (readout.total > 0) return "warning";
+  return "danger";
+}
+function BalanceAction({ wide }) {
+  const [readout, setReadout] = (0, import_react.useState)(void 0);
+  const [turnEpoch, setTurnEpoch] = (0, import_react.useState)(0);
+  const inFlight = (0, import_react.useRef)(false);
+  const refresh = (0, import_react.useCallback)(() => {
+    if (inFlight.current) return;
+    inFlight.current = true;
+    fetch(BALANCE_ENDPOINT, { cache: "no-store" }).then((response) => response.json()).then(setReadout).catch(() => setReadout(void 0)).finally(() => {
+      inFlight.current = false;
+    });
+  }, []);
+  (0, import_react.useEffect)(() => {
+    refresh();
+  }, [refresh, turnEpoch]);
+  (0, import_react.useEffect)(() => {
+    const source = new EventSource(EVENTS_ENDPOINT);
+    source.addEventListener("refresh", () => {
+      setTurnEpoch((epoch) => epoch + 1);
+    });
+    return () => {
+      source.close();
+    };
+  }, []);
+  if (readout === void 0 || readout.status !== "ok") return null;
+  const tone = toneOf(readout);
+  const label = `\u4F59\u989D ${readout.display}`;
+  return (0, import_react.createElement)(
+    "button",
+    {
+      type: "button",
+      style: styles.button,
+      "aria-label": "\u5237\u65B0\u4F59\u989D",
+      title: wide ? label : void 0,
+      onClick: refresh
+    },
+    (0, import_react.createElement)(CardIcon, { size: wide ? 16 : 18 }),
+    wide ? (0, import_react.createElement)("span", { style: { ...styles.amount, ...styles[tone] } }, readout.display) : null
+  );
+}
+function apply(ctx) {
+  ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
+    name: "sidebar.footer.action",
+    id: "balance",
+    order: 0
+  }, BalanceAction));
+}
+return module.exports; } });

package/lib/index.js

@@ -0,0 +1,171 @@
+// src/index.ts
+import Schema from "@deepseek-ai/schemastery";
+
+// src/balance-core.ts
+function symbol(currency) {
+  switch (currency.toUpperCase()) {
+    case "CNY":
+    case "RMB":
+      return "\xA5";
+    case "USD":
+      return "$";
+    default:
+      return currency === "" ? "" : `${currency} `;
+  }
+}
+function normalizeCurrency(currency) {
+  switch (currency.toUpperCase().trim()) {
+    case "CNY":
+    case "RMB":
+    case "CNH":
+    case "\xA5":
+    case "\uFFE5":
+      return "CNY";
+    case "USD":
+    case "$":
+      return "USD";
+    default:
+      return "";
+  }
+}
+function primaryInfo(infos) {
+  if (infos.length === 0) return void 0;
+  return infos.find((info) => normalizeCurrency(info.currency) === "CNY") ?? infos[0];
+}
+function displayFor(infos) {
+  const pick = primaryInfo(infos);
+  if (pick === void 0) return "";
+  return `${symbol(pick.currency)}${pick.total.trim()}`;
+}
+function primaryTotal(infos) {
+  const pick = primaryInfo(infos);
+  if (pick === void 0) return 0;
+  const parsed = Number.parseFloat(pick.total);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+async function fetchBalance(credentials, env, config) {
+  const resolved = await credentials?.resolve(config.apiKeyEnv);
+  const apiKey = resolved?.value ?? env[config.apiKeyEnv];
+  if (!apiKey) {
+    return { status: "unconfigured" };
+  }
+  const timeout = AbortSignal.timeout(config.timeoutMs);
+  const url = `${config.baseURL.replace(/\/+$/, "")}/user/balance`;
+  try {
+    const response = await fetch(url, {
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${apiKey}`
+      },
+      signal: timeout
+    });
+    const body = await response.text();
+    if (!response.ok) {
+      return { status: "unavailable", reason: `balance-http-${String(response.status)}` };
+    }
+    const parsed = JSON.parse(body);
+    const infos = (parsed.balance_infos ?? []).map((info) => ({
+      currency: info.currency,
+      total: info.total_balance,
+      granted: info.granted_balance,
+      toppedUp: info.topped_up_balance
+    }));
+    if (infos.length === 0) {
+      return { status: "unavailable", reason: "balance-empty" };
+    }
+    return {
+      status: "ok",
+      available: parsed.is_available,
+      display: displayFor(infos),
+      total: primaryTotal(infos),
+      threshold: config.lowBalanceThreshold,
+      currencies: [...new Set(infos.map((info) => {
+        const normalized = normalizeCurrency(info.currency);
+        return normalized === "" ? info.currency.toUpperCase() : normalized;
+      }))].sort(),
+      infos
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return { status: "unavailable", reason: "balance-timeout" };
+    }
+    if (error instanceof SyntaxError) {
+      return { status: "unavailable", reason: "balance-decode" };
+    }
+    return { status: "unavailable", reason: "balance-network" };
+  }
+}
+
+// src/index.ts
+var name = "dsh-balance-plugin";
+var inject = ["webServer"];
+var Config = Schema.object({
+  apiKeyEnv: Schema.string().default("DEEPSEEK_API_KEY"),
+  baseURL: Schema.string().default("https://api.deepseek.com"),
+  timeoutMs: Schema.natural().min(1).max(12e4).default(12e3),
+  lowBalanceThreshold: Schema.number().min(0).default(2)
+});
+function apply(ctx, config) {
+  const sseClients = /* @__PURE__ */ new Set();
+  const broadcastRefresh = () => {
+    for (const res of sseClients) {
+      try {
+        res.write("event: refresh\ndata: {}\n\n");
+      } catch {
+        sseClients.delete(res);
+      }
+    }
+  };
+  const unregisterBalance = ctx.webServer.register({
+    kind: "exact",
+    path: "/dsh-balance",
+    handler: async (_req, res) => {
+      const credentials = ctx.get("credentials");
+      const resolver = credentials === void 0 ? void 0 : { resolve: (ref) => credentials.resolve(ref) };
+      const readout = await fetchBalance(resolver, process.env, config);
+      const body = JSON.stringify(readout);
+      res.writeHead(200, {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+        "content-length": Buffer.byteLength(body)
+      });
+      res.end(body);
+    }
+  });
+  const unregisterEvents = ctx.webServer.register({
+    kind: "exact",
+    path: "/dsh-balance/events",
+    handler: (req, res) => {
+      res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive"
+      });
+      res.write(": connected\n\n");
+      sseClients.add(res);
+      req.on("close", () => {
+        sseClients.delete(res);
+      });
+    }
+  });
+  ctx.on("session/event", (_session, event) => {
+    if (event.type === "turn/end") broadcastRefresh();
+  });
+  return () => {
+    unregisterBalance();
+    unregisterEvents();
+    for (const res of sseClients) {
+      try {
+        res.end();
+      } catch {
+      }
+    }
+    sseClients.clear();
+  };
+}
+export {
+  Config,
+  apply,
+  inject,
+  name
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "dsh-balance-plugin",
+  "version": "0.1.0",
+  "description": "DeepSeek wallet-balance readout at the sidebar foot: card icon + amount, status-tinted, refreshed on turn end and on click",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "PUBLISHING.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepare": "node scripts/build.mjs",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "0.0.1-rc.5",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "0.0.1-rc.5",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/react": "^18.0.0",
+    "esbuild": "^0.25.0",
+    "react": "^18.0.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luokai-demo/dsh-plugins.git"
+  },
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "dsh-plugin",
+    "balance",
+    "wallet"
+  ]
+}