@ruoyang/dsh-plugin-deepseek-balance 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ruoyang
+
+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,159 @@
+# @ruoyang/dsh-plugin-deepseek-balance
+
+A floating badge in the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI
+showing the remaining balance of the `DEEPSEEK_API_KEY` credential the harness itself uses for model
+calls.
+
+> 中文说明见下方 [中文](#中文)。
+
+## What it does
+
+| Part | Behaviour |
+| --- | --- |
+| Status dot | green = balance available, amber = account cannot call the API, grey = querying, red = query failed |
+| Badge text | total balance in the primary currency, e.g. `¥4.94` |
+| Hover panel | per-currency totals, granted vs topped-up split, whether the account is callable, and the query time |
+| Interaction | click to refresh, drag to reposition, automatic refresh every 60 seconds |
+
+The badge itself is a pill pinned to the lower-right corner; drag it anywhere and it stays there for
+the session.
+
+## Requirements
+
+- A DeepSeek Harness installation with the **Web** surface (`dsh web`).
+- `DEEPSEEK_API_KEY` configured — via the launching environment, a `.env` file, or
+  **Settings → Models**. The plugin resolves it per query through the credentials seam, so a key you
+  rotate takes effect on the next refresh with no restart.
+- Node.js **>= 18.17** on the host (the host half uses global `fetch` and `AbortSignal.timeout`).
+
+The package deliberately declares **no `peerDependencies`** on `@deepseek-ai/dsh-*`, so it installs
+across harness versions instead of being pinned to one. It also has **no runtime dependencies** and
+no install scripts.
+
+## Install
+
+Using the `dsh` CLI:
+
+```sh
+dsh plugin --profile web add @ruoyang/dsh-plugin-deepseek-balance
+```
+
+In the Web UI: **Settings → Plugins**, then install by the package name above.
+
+Through an agent session, the equivalent is the `plugin_manager` tool with
+`action: install_bundle` and that package name as `target`.
+
+A new bundle activates immediately; if the badge does not appear, reload the page once so the
+browser picks up the new client module.
+
+## Uninstall
+
+```sh
+dsh plugin --profile web remove @ruoyang/dsh-plugin-deepseek-balance
+```
+
+## How it works
+
+One bundle, two halves, mounted by a single Loader row:
+
+| File | Role |
+| --- | --- |
+| `cordis.patch.yml` | inserts the row `deepseek-balance` |
+| `index.js` | Host half: serves `GET /deepseek-balance/api` |
+| `client.js` | Client half: a lazy module-system factory that registers into the `shell.overlay` slot |
+
+**Your key never reaches the browser.** The host half reads it through `ctx.credentials` and calls
+`https://api.deepseek.com/user/balance` itself; the browser half only fetches the same-origin JSON
+snapshot the host produces. Failures come back as `{ "ok": false, "code": …, "message": … }` with the
+error's `cause` chain flattened into `message`, so a transport problem is diagnosable without logs.
+
+The plugin declares no settings and no `Config` schema — there is nothing to configure.
+
+## Troubleshooting
+
+```sh
+curl http://127.0.0.1:3080/deepseek-balance/api            # the JSON snapshot the badge renders
+curl "http://127.0.0.1:3080/deepseek-balance/api?force=1"  # bypass the host half's 20s cache
+```
+
+| Response | Meaning |
+| --- | --- |
+| `{"ok":true,…}` | working |
+| `{"ok":false,"code":"NO_KEY"}` | no `DEEPSEEK_API_KEY` is configured |
+| `{"ok":false,"code":"HTTP_401"}` | the key is rejected by DeepSeek |
+| `{"ok":false,"code":"TRANSPORT"}` | the host could not reach `api.deepseek.com` |
+
+A 404 on that path means the row did not mount — check that the bundle is enabled in
+**Settings → Plugins**.
+
+## Known limitations
+
+- Visible badge text is currently Chinese only; it does not yet go through the Client locale service,
+  so an English UI still shows Chinese labels in the hover panel.
+- The badge position resets on page reload; it is not persisted.
+
+## 中文
+
+在 DeepSeek Harness 的 Web 界面右下角悬浮显示**当前 `DEEPSEEK_API_KEY` 的剩余余额**。
+
+**它做什么**：状态点（绿=有余额 / 黄=账号不可调用 / 灰=查询中 / 红=查询失败）、胶囊显示主币种
+总余额、悬停展开各币种总余额与赠金/充值拆分、点击刷新、按住拖动、每 60 秒自动刷新。
+
+**要求**：带 Web 界面的 Harness（`dsh web`）；已配置 `DEEPSEEK_API_KEY`（环境变量、`.env` 或
+设置里的 Models 页均可，插件每次查询都重新解析，换密钥不用重启）；宿主机 Node ≥ 18.17。
+
+**安装**：
+
+```sh
+dsh plugin --profile web add @ruoyang/dsh-plugin-deepseek-balance
+```
+
+或在 Web 界面 **设置 → 插件** 里按包名安装。装好后如果徽标没出现，刷新一次页面。
+
+**卸载**：`dsh plugin --profile web remove @ruoyang/dsh-plugin-deepseek-balance`
+
+**密钥安全**：密钥全程留在宿主机侧，由宿主半经 `ctx.credentials` 读出后直接请求
+`api.deepseek.com`；浏览器半只读同源的 JSON 快照，**密钥不会进入浏览器**。
+
+**排查**：
+
+```sh
+curl http://127.0.0.1:3080/deepseek-balance/api            # 徽标渲染用的 JSON
+curl "http://127.0.0.1:3080/deepseek-balance/api?force=1"  # 绕过宿主半 20 秒缓存
+```
+
+返回 `NO_KEY` = 没配密钥，`HTTP_401` = 密钥被拒，`TRANSPORT` = 宿主机连不上
+`api.deepseek.com`；404 = 行没挂上，去 **设置 → 插件** 看是否启用。
+
+**已知限制**：徽标内的可见文字目前是硬编码中文，还没接 Client locale 服务，所以英文界面下悬停
+面板仍是中文；徽标位置刷新页面后重置。
+
+## Releasing (maintainer)
+
+The default registry on a machine set up for fast Chinese installs is
+`registry.npmmirror.com` — a **read-only mirror**. It serves installs but accepts no publishes, so a
+bare `npm publish` fails with `ENEEDAUTH` against it. Pass the official registry explicitly:
+
+```sh
+cd dsh-plugins/deepseek-balance
+npm login   --registry=https://registry.npmjs.org/
+npm whoami  --registry=https://registry.npmjs.org/   # must print the owner of the @ruoyang scope
+npm publish --registry=https://registry.npmjs.org/
+```
+
+Why the flag and not just `.npmrc`: npm resolves config as
+`cli > env > project > user > global`, and a shell that inherited `npm_config_registry` (npx exports
+it, so any shell started by an npx-launched `dsh` carries it) overrides every file. `npm config ls`
+shows it as `registry = "…" ; overridden by env`. The project `.npmrc` here is a convenience for
+clean shells; the flag is what always works.
+
+A scoped package can only be published by the account that owns the scope, so `npm whoami` must
+match `@ruoyang` — either that is your npm username, or `ruoyang` is an org you belong to.
+
+For a new release, bump `version` in `package.json` first: npm refuses to republish an existing
+version, and a re-`npm pack` at the same version silently overwrites the local tarball while the
+already-installed copy keeps the old bytes.
+
+## License
+
+[MIT](./LICENSE)

package/client.js

@@ -0,0 +1,265 @@
+/**
+ * Browser half of the DeepSeek balance badge.
+ *
+ * One occupant of the frame-wide `shell.overlay` slot (`@deepseek-ai/dsh-client-ui-layout`
+ * declares it): a draggable pill showing the remaining balance of the credential
+ * the harness itself uses for model calls. The host half owns the credential and
+ * the upstream request; this half only reads the JSON snapshot it serves.
+ *
+ * Hand-written in the client module system's lazy-CJS factory format, so no
+ * build step is involved. `id` must equal the package name. React comes from the
+ * browser module table via `require`.
+ *
+ * The factory itself stays side-effect free: the stylesheet, the interval and the
+ * slot registration are all created inside `apply` and owned by that fiber.
+ */
+window.__ModuleLoader__.load({
+  id: '@ruoyang/dsh-plugin-deepseek-balance',
+  factory(require) {
+    const React = require('react')
+
+    /** Snapshot route served by this package's host half. */
+    const API_PATH = '/deepseek-balance/api'
+    /** Auto-refresh cadence, matching the host half's own cache window. */
+    const REFRESH_MS = 60000
+    /** Display symbol per reported currency; anything else is shown with its code. */
+    const SYMBOLS = { CNY: '¥', USD: '$' }
+    /** Id of the one style node this fiber owns. */
+    const STYLE_ID = 'dsh-balance-styles'
+
+    const CSS = [
+      '.dsh-balance-root{position:fixed;z-index:60;pointer-events:auto;user-select:none;',
+      'font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI","Microsoft YaHei",sans-serif;',
+      'font-size:12px;line-height:1.45;}',
+      '.dsh-balance-pill{display:flex;align-items:center;gap:6px;padding:6px 11px;border-radius:999px;',
+      'background:var(--dsw-alias-bg-overlay,rgba(24,24,27,.94));',
+      'color:var(--dsw-alias-label-primary,#fafafa);',
+      'border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.16));',
+      'box-shadow:0 6px 20px rgba(0,0,0,.28);cursor:grab;touch-action:none;backdrop-filter:blur(8px);}',
+      '.dsh-balance-pill:active{cursor:grabbing;}',
+      '.dsh-balance-dot{width:7px;height:7px;border-radius:50%;flex:none;',
+      'background:var(--dsw-alias-label-secondary,#a1a1aa);}',
+      '.dsh-balance-tone-ok .dsh-balance-dot{background:var(--dsw-alias-state-success-primary,#22c55e);}',
+      '.dsh-balance-tone-warn .dsh-balance-dot{background:var(--dsw-alias-state-warn-primary,#f59e0b);}',
+      '.dsh-balance-tone-error .dsh-balance-dot{background:var(--dsw-alias-state-error-primary,#ef4444);}',
+      '.dsh-balance-label{font-weight:600;font-variant-numeric:tabular-nums;letter-spacing:.01em;white-space:nowrap;}',
+      '.dsh-balance-spin{opacity:.65;animation:dsh-balance-spin .9s linear infinite;}',
+      '@keyframes dsh-balance-spin{to{transform:rotate(360deg)}}',
+      '.dsh-balance-panel{display:none;margin-bottom:8px;padding:10px 12px;min-width:190px;border-radius:12px;',
+      'background:var(--dsw-alias-bg-overlay,rgba(24,24,27,.96));',
+      'color:var(--dsw-alias-label-primary,#fafafa);',
+      'border:1px solid var(--dsw-alias-border-l1,rgba(255,255,255,.12));',
+      'box-shadow:0 10px 30px rgba(0,0,0,.32);backdrop-filter:blur(10px);}',
+      '.dsh-balance-root:hover .dsh-balance-panel{display:block;}',
+      '.dsh-balance-row{display:flex;justify-content:space-between;gap:16px;padding:2px 0;}',
+      '.dsh-balance-key{color:var(--dsw-alias-label-secondary,#a1a1aa);white-space:pre;}',
+      '.dsh-balance-val{font-variant-numeric:tabular-nums;white-space:nowrap;}',
+      '.dsh-balance-err{color:var(--dsw-alias-state-error-primary,#ef4444);max-width:230px;',
+      'white-space:normal;word-break:break-word;text-align:right;}',
+      '.dsh-balance-hint{margin-top:7px;padding-top:6px;font-size:11px;',
+      'border-top:1px solid var(--dsw-alias-border-l1,rgba(255,255,255,.1));',
+      'color:var(--dsw-alias-label-secondary,#a1a1aa);}',
+    ].join('')
+
+    /**
+     * Read one snapshot from this package's host half.
+     *
+     * The host half answers structured failures with HTTP 200, so a rejected
+     * promise here means the route itself was unreachable.
+     *
+     * @param force - bypass the host half's cache.
+     * @returns the snapshot payload.
+     */
+    function requestSnapshot(force) {
+      return fetch(API_PATH + (force === true ? '?force=1' : ''), { headers: { accept: 'application/json' } })
+        .then((response) => response.json())
+    }
+
+    /** Render a thrown value as one short line. */
+    function describe(error) {
+      return String(error !== null && typeof error === 'object' && 'message' in error ? error.message : error)
+    }
+
+    /** Display symbol for a reported currency. */
+    function symbolOf(currency) {
+      return SYMBOLS[currency] !== undefined ? SYMBOLS[currency] : currency + ' '
+    }
+
+    /** `HH:MM:SS` for a snapshot timestamp. */
+    function formatTime(ms) {
+      const date = new Date(ms)
+      const pad = (value) => (value < 10 ? '0' + String(value) : String(value))
+      return pad(date.getHours()) + ':' + pad(date.getMinutes()) + ':' + pad(date.getSeconds())
+    }
+
+    /** One key/value line of the hover panel. */
+    function row(key, value, extraClass) {
+      return React.createElement(
+        'div',
+        { className: 'dsh-balance-row', key },
+        React.createElement('span', { className: 'dsh-balance-key' }, key),
+        React.createElement(
+          'span',
+          { className: 'dsh-balance-val' + (extraClass === undefined ? '' : ' ' + extraClass) },
+          value,
+        ),
+      )
+    }
+
+    /**
+     * Build the hover panel: one block per reported currency, then availability
+     * and freshness. The failure branch names the credential so a missing key is
+     * obvious without opening logs.
+     */
+    function panelRows(data, failure, phase) {
+      const rows = []
+      if (data !== null) {
+        if (data.infos.length === 0) {
+          rows.push(row('余额', '无数据'))
+        } else {
+          for (const info of data.infos) {
+            const symbol = symbolOf(info.currency)
+            rows.push(row(info.currency + ' 总余额', symbol + info.total))
+            rows.push(row('  赠金 / 充值', symbol + info.granted + ' / ' + symbol + info.toppedUp))
+          }
+        }
+        rows.push(row('可调用', data.isAvailable === true ? '是' : '否'))
+        rows.push(row('更新于', formatTime(data.at)))
+      } else if (phase === 'loading') {
+        rows.push(row('状态', '查询中 …'))
+        rows.push(row('凭据', 'DEEPSEEK_API_KEY'))
+      } else {
+        rows.push(row('错误', failure === null ? '余额暂不可用' : failure, 'dsh-balance-err'))
+        rows.push(row('凭据', 'DEEPSEEK_API_KEY'))
+      }
+      rows.push(React.createElement('div', { className: 'dsh-balance-hint', key: 'hint' },
+        '点击刷新 · 按住拖动可移动位置'))
+      return rows
+    }
+
+    return {
+      inject: ['slots', 'timer'],
+      apply(ctx) {
+        ctx.effect(() => {
+          if (document.getElementById(STYLE_ID) === null) {
+            const node = document.createElement('style')
+            node.id = STYLE_ID
+            node.textContent = CSS
+            document.head.append(node)
+          }
+          return () => { document.getElementById(STYLE_ID)?.remove() }
+        }, 'deepseek-balance: styles')
+
+        // Defined inside apply so the component closes over this fiber's context
+        // and can own its own interval. One mount per client run keeps the
+        // component identity stable across re-renders.
+        function BalanceBadge() {
+          const [snapshot, setSnapshot] = React.useState({ phase: 'loading' })
+          const [busy, setBusy] = React.useState(false)
+          const [position, setPosition] = React.useState({ right: 22, bottom: 22 })
+          const drag = React.useRef(null)
+
+          React.useEffect(() => {
+            let alive = true
+            const pull = (force) => {
+              requestSnapshot(force).then(
+                (data) => { if (alive) setSnapshot({ phase: 'ready', data }) },
+                (error) => { if (alive) setSnapshot({ phase: 'error', message: describe(error) }) },
+              )
+            }
+            pull(false)
+            const stop = ctx.interval(() => { pull(true) }, REFRESH_MS)
+            return () => { alive = false; stop() }
+          }, [])
+
+          const refresh = () => {
+            setBusy(true)
+            requestSnapshot(true)
+              .then(
+                (data) => setSnapshot({ phase: 'ready', data }),
+                (error) => setSnapshot({ phase: 'error', message: describe(error) }),
+              )
+              .then(() => setBusy(false))
+          }
+
+          const onPointerDown = (event) => {
+            if (event.button !== 0) return
+            try { event.currentTarget.setPointerCapture(event.pointerId) } catch (error) { /* still draggable */ }
+            drag.current = {
+              x: event.clientX,
+              y: event.clientY,
+              right: position.right,
+              bottom: position.bottom,
+            }
+          }
+
+          const onPointerMove = (event) => {
+            const started = drag.current
+            if (started === null) return
+            let right = started.right - (event.clientX - started.x)
+            let bottom = started.bottom - (event.clientY - started.y)
+            right = Math.max(4, Math.min(right, window.innerWidth - 60))
+            bottom = Math.max(4, Math.min(bottom, window.innerHeight - 32))
+            setPosition({ right, bottom })
+          }
+
+          const onPointerUp = (event) => {
+            const started = drag.current
+            drag.current = null
+            try { event.currentTarget.releasePointerCapture(event.pointerId) } catch (error) { /* nothing captured */ }
+            if (started === null) return
+            const moved = Math.abs(event.clientX - started.x) + Math.abs(event.clientY - started.y)
+            if (moved < 5) refresh()
+          }
+
+          const data = snapshot.phase === 'ready' && snapshot.data !== null && snapshot.data.ok === true
+            ? snapshot.data
+            : null
+          const failure = snapshot.phase === 'error'
+            ? snapshot.message
+            : (snapshot.phase === 'ready' && snapshot.data !== null && snapshot.data.ok !== true
+                ? snapshot.data.message
+                : null)
+
+          let tone = 'idle'
+          let label = '余额 …'
+          if (snapshot.phase === 'error' || failure !== null) {
+            tone = 'error'
+            label = '余额不可用'
+          } else if (data !== null) {
+            tone = data.isAvailable === true ? 'ok' : 'warn'
+            label = symbolOf(data.currency) + data.total
+          }
+
+          return React.createElement(
+            'div',
+            {
+              className: 'dsh-balance-root dsh-balance-tone-' + tone,
+              style: { right: position.right + 'px', bottom: position.bottom + 'px' },
+            },
+            React.createElement('div', { className: 'dsh-balance-panel' }, panelRows(data, failure, snapshot.phase)),
+            React.createElement(
+              'div',
+              {
+                className: 'dsh-balance-pill',
+                title: 'DeepSeek 余额 · 点击刷新 · 拖动移动',
+                onPointerDown,
+                onPointerMove,
+                onPointerUp,
+                onPointerCancel: onPointerUp,
+              },
+              React.createElement('span', { className: 'dsh-balance-dot' }),
+              React.createElement('span', { className: 'dsh-balance-label' }, label),
+              busy ? React.createElement('span', { className: 'dsh-balance-spin' }, '↻') : null,
+            ),
+          )
+        }
+
+        ctx.effect(() => ctx.slots.inject('shell.overlay', () => ctx.slots.register(
+          { name: 'shell.overlay', id: 'deepseek-balance', order: 200 },
+          BalanceBadge,
+        )), 'deepseek-balance: overlay badge')
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# deepseek-balance: a floating badge showing the remaining balance of the
+# DEEPSEEK_API_KEY credential the harness itself uses for model calls.
+#
+# The Host half (index.js) serves GET /deepseek-balance/api; the Client half
+# (client.js, declared through dsh.client) registers the badge into the
+# frame-wide shell.overlay slot. Both halves belong to this one row.
+- insert:
+    - id: deepseek-balance
+      name: '@ruoyang/dsh-plugin-deepseek-balance'

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="DeepSeek balance">
+  <circle cx="32" cy="32" r="27" fill="#4D6BFE"/>
+  <g fill="none" stroke="#fff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M22 19 L32 30 L42 19"/>
+    <path d="M32 30 L32 47"/>
+    <path d="M22 34 L42 34"/>
+    <path d="M22 41 L42 41"/>
+  </g>
+</svg>

package/index.js

@@ -0,0 +1,249 @@
+/**
+ * DeepSeek balance badge — host half.
+ *
+ * Serves one JSON route the package's browser half polls: the remaining balance
+ * of the credential the harness already uses for its own model calls
+ * (`DEEPSEEK_API_KEY`, resolved through the credentials seam on every query, so
+ * a rotated key reaches the next refresh with no restart).
+ *
+ * The browser half is a `dsh.client` bundle this package declares, so the client
+ * module system loads and serves it; this half owns only the data.
+ *
+ * @module @local/deepseek-balance
+ */
+
+/** Credential reference resolved per query; the same key the model route uses. */
+const KEY_REF = 'DEEPSEEK_API_KEY'
+/** Official balance endpoint: GET /user/balance. */
+const BALANCE_URL = 'https://api.deepseek.com/user/balance'
+/** Route the badge polls. */
+const API_PATH = '/deepseek-balance/api'
+/** Serve one cached snapshot for this long before paying for another request. */
+const CACHE_MS = 20000
+/** Per-attempt upstream bound. */
+const TIMEOUT_MS = 20000
+/** Attempts per query: one retry covers the transient transport blips seen here. */
+const ATTEMPTS = 2
+/** Backoff between attempts, owned by the cordis timer so it dies with the fiber. */
+const RETRY_DELAY_MS = 400
+
+/** The host capabilities this plugin needs before it can serve anything. */
+export const inject = ['webServer', 'timer']
+
+/**
+ * Register the balance route.
+ *
+ * `credentials` is read optionally and degrades to a structured error the badge
+ * renders, never a stuck row.
+ *
+ * @param ctx - the plugin's Cordis context.
+ */
+export function apply(ctx) {
+  let cached = null
+  let inflight = null
+
+  /**
+   * Resolve the API key through the credentials seam.
+   *
+   * Resolution is per call by design: it layers the launching environment, the
+   * provider-managed store and `.env` files, so a key saved or rotated at
+   * runtime is picked up by the next query.
+   *
+   * @returns the key, or undefined when nothing is configured.
+   */
+  async function resolveKey() {
+    const credentials = ctx.get('credentials')
+    if (credentials === undefined) return undefined
+    try {
+      const resolved = await credentials.resolve(KEY_REF)
+      if (resolved === undefined || resolved === null) return undefined
+      const value = resolved.value
+      return typeof value === 'string' && value.length > 0 ? value : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  /**
+   * Flatten a thrown value and its `cause` chain into one line.
+   *
+   * Node's fetch reports a bare "fetch failed"; the actionable part (ECONNRESET,
+   * ENOTFOUND, a TLS error) only ever appears on `cause`, so a message that
+   * stops at the top level is undiagnosable.
+   *
+   * @param error - the thrown value.
+   * @returns a short single-line description.
+   */
+  function messageOf(error) {
+    const parts = []
+    let cursor = error
+    while (cursor !== null && cursor !== undefined && parts.length < 4) {
+      if (typeof cursor === 'object' && typeof cursor.message === 'string') {
+        parts.push(cursor.message + (typeof cursor.code === 'string' ? ' [' + cursor.code + ']' : ''))
+        cursor = cursor.cause
+      } else {
+        parts.push(String(cursor))
+        break
+      }
+    }
+    return (parts.length === 0 ? String(error) : parts.join(' <- ')).slice(0, 400)
+  }
+
+  /** Project one `balance_infos[]` entry onto the four scalars the badge shows. */
+  function readInfo(item) {
+    const text = (value) => (typeof value === 'string' ? value : String(value))
+    return {
+      currency: typeof item.currency === 'string' ? item.currency : '?',
+      total: text(item.total_balance),
+      granted: text(item.granted_balance),
+      toppedUp: text(item.topped_up_balance),
+    }
+  }
+
+  /**
+   * Build the owned JSON snapshot from the upstream body.
+   *
+   * CNY is the primary display currency when present, which is what a DeepSeek
+   * Platform account is normally denominated in; USD accounts fall back to the
+   * first reported entry.
+   *
+   * @param data - parsed `/user/balance` body.
+   * @returns the badge payload.
+   */
+  function shape(data) {
+    const infos = []
+    if (Array.isArray(data.balance_infos)) {
+      for (const item of data.balance_infos) {
+        if (item === null || typeof item !== 'object') continue
+        infos.push(readInfo(item))
+      }
+    }
+    let primary = null
+    for (const info of infos) if (info.currency === 'CNY') primary = info
+    if (primary === null && infos.length > 0) primary = infos[0]
+    const base = primary === null
+      ? { currency: 'CNY', total: '0.00', granted: '0.00', toppedUp: '0.00' }
+      : primary
+    return {
+      ok: true,
+      isAvailable: data.is_available === true,
+      currency: base.currency,
+      total: base.total,
+      granted: base.granted,
+      toppedUp: base.toppedUp,
+      infos,
+      at: Date.now(),
+    }
+  }
+
+  /**
+   * One upstream attempt.
+   *
+   * Never throws: every outcome is a payload plus whether another attempt could
+   * plausibly help (a transport failure, or a 5xx).
+   *
+   * @param key - the resolved API key.
+   * @returns the payload and its retryability.
+   */
+  async function attempt(key) {
+    let response
+    try {
+      response = await fetch(BALANCE_URL, {
+        headers: { authorization: 'Bearer ' + key, accept: 'application/json' },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      })
+    } catch (error) {
+      return { retryable: true, payload: { ok: false, code: 'TRANSPORT', message: messageOf(error), at: Date.now() } }
+    }
+
+    const body = await response.text()
+    if (response.status !== 200) {
+      return {
+        retryable: response.status >= 500,
+        payload: { ok: false, code: 'HTTP_' + String(response.status), message: body.slice(0, 300), at: Date.now() },
+      }
+    }
+    let data
+    try {
+      data = JSON.parse(body)
+    } catch {
+      return { retryable: false, payload: { ok: false, code: 'BAD_JSON', message: '余额响应不是合法 JSON', at: Date.now() } }
+    }
+    return { retryable: false, payload: shape(data) }
+  }
+
+  /**
+   * Query the official endpoint, retrying a retryable failure once.
+   *
+   * @returns the badge payload.
+   */
+  async function runQuery() {
+    const key = await resolveKey()
+    if (key === undefined) {
+      return { ok: false, code: 'NO_KEY', message: '未找到 ' + KEY_REF + ' 凭据，请先在 Models 页配置密钥', at: Date.now() }
+    }
+    let outcome = await attempt(key)
+    for (let done = 1; done < ATTEMPTS && outcome.retryable; done += 1) {
+      await ctx.timeout(RETRY_DELAY_MS)
+      outcome = await attempt(key)
+    }
+    return outcome.payload
+  }
+
+  /**
+   * Query with a short cache and single-flight collapse.
+   *
+   * Several open tabs polling at once, or one tab polling while a manual
+   * refresh is in flight, share one upstream request.
+   *
+   * @param force - bypass the cache (the badge's manual refresh).
+   * @returns the badge payload.
+   */
+  async function query(force) {
+    const now = Date.now()
+    if (force !== true && cached !== null && now - cached.at < CACHE_MS) return cached.value
+    if (inflight !== null) return inflight
+    const pending = (async () => {
+      try {
+        return await runQuery()
+      } catch (error) {
+        return { ok: false, code: 'UNEXPECTED', message: messageOf(error), at: Date.now() }
+      }
+    })()
+    inflight = pending
+    let value
+    try {
+      value = await pending
+    } finally {
+      if (inflight === pending) inflight = null
+    }
+    cached = { at: Date.now(), value }
+    return value
+  }
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: API_PATH,
+    handler: async (req, res) => {
+      let force = false
+      try {
+        force = new URL(req.url ?? API_PATH, 'http://localhost').searchParams.get('force') === '1'
+      } catch {
+        // a malformed query string simply means "not forced"
+      }
+      let value
+      try {
+        value = await query(force)
+      } catch (error) {
+        value = { ok: false, code: 'UNEXPECTED', message: messageOf(error), at: Date.now() }
+      }
+      const body = JSON.stringify(value)
+      res.writeHead(200, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        'content-length': Buffer.byteLength(body),
+      })
+      res.end(body)
+    },
+  }), 'deepseek-balance: balance api')
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DeepSeek Balance Badge",
+    "description": "A floating badge showing the remaining balance of your DEEPSEEK_API_KEY, refreshed every minute."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DeepSeek 余额徽标",
+    "description": "悬浮显示当前 DEEPSEEK_API_KEY 的剩余余额，每分钟自动刷新。"
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ruoyang/dsh-plugin-deepseek-balance",
+  "version": "1.0.0",
+  "description": "Floating DeepSeek API balance badge for the DeepSeek Harness Web UI, backed by the harness's own DEEPSEEK_API_KEY credential",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "deepseek",
+    "dsh",
+    "dsh-plugin",
+    "harness",
+    "balance",
+    "cordis"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "icon": "./icon.svg",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "icon.svg",
+    "locale/*.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout"
+      ]
+    }
+  }
+}