dsh-balance-bubble

A Cordis plugin for the DSH (DeepSeek Harness) web interface that floats a translucent, glass-styled bubble in the top-right corner showing your DeepSeek account balance, refreshed automatically.

The bubble is freely draggable, always stays inside the window (and repositions proportionally when you resize it), can be hidden behind a sidebar toggle, turns red and re-appears when your balance runs low, and adapts to dark mode.

Features

• Live balance — the host queries the official https://api.deepseek.com/user/balance endpoint and exposes it as GET /dsh-balance; the bubble refreshes every 20 seconds. Hover for a breakdown of topped-up / granted balance and the last update time.
• Liquid-glass look — a translucent light-blue circle with backdrop blur, a glossy top highlight, and soft inner shadows.
• Freely draggable — grab it and move it anywhere; the position is clamped to the window and scales proportionally with window size changes.
• Hide / show — a small ✕ on the bubble hides it; a 余额 toggle in the sidebar footer (above the Cordis plugin entry) brings it back. Both stay in sync.
• Low-balance alert — turns red with a pulsing ring when the balance drops below the threshold (default 5 CNY), and auto-shows even while hidden.
• Dark-mode aware — listens to the theme/change event; in dark themes the bubble brightens and the text turns white.

Sidebar toggle

When the bubble is hidden, bring it back with the 余额 button at the bottom of the sidebar, directly above the Cordis plugin entry. In the wide sidebar it shows a ¥ icon next to the 余额 label; in the collapsed rail it shrinks to the icon alone. The button mirrors the bubble's state — it turns gray while the bubble is hidden — and the two always stay in sync.

Screenshots

Light mode	Dark mode

Installation

Requires the DSH web profile (dsh web) and a configured DeepSeek API key (DEEPSEEK_API_KEY, set in Settings → Models).

1. Install the package into the web profile:

   dsh plugin --profile web add dsh-balance-bubble
   # or manually:
   cd ~/.dsh/profiles/web && pnpm add dsh-balance-bubble

2. Mount it. The package carries its own patch (dsh.bundle.patch → cordis.patch.yml), so adding dsh-balance-bubble to the profile's dsh.profile.bundles is enough — or insert the row manually:

   - insert:
       - id: dsh-balance-bubble
         name: 'dsh-balance-bubble'

3. Restart DSH. The bubble and the sidebar toggle load automatically on every start.

Configuration

No user-facing settings are exposed yet. The low-balance threshold is hard-coded at 5 CNY in lib/client.js — edit totalBalance < 5 to change it.

The API key is read from the DSH credentials service (DEEPSEEK_API_KEY, the same one the Models page writes); the plugin never stores the key itself.

How it works

• Host half (lib/index.js) — resolves the key via ctx.credentials, calls the official balance endpoint with native fetch (30-second cache), and registers the GET /dsh-balance route on ctx.webServer. The path deliberately avoids the /api prefix used by the built-in transport.
• Browser half (lib/client.js) — registers the bubble into shell.overlay and the toggle into sidebar.footer.action (order -1, above the Cordis plugin entry), polls the route every 20 seconds, and renders with React.

Known Limitations and Deferred Work

• Threshold is hard-coded — no settings namespace yet; exposing the threshold (and other options) through the DSH settings UI is planned.
• Dragged position resets on reload — the position lives in component state; persistence across reloads is deferred.
• Web profile only — targets the DSH web interface; no TUI surface.

中文说明

一个面向 DSH（DeepSeek Harness） Web 界面的 Cordis 插件：在界面右上角悬浮一个半透明玻璃质感的气泡，实时显示你的 DeepSeek 账户余额，并自动刷新。

气泡可自由拖动、始终保持在窗口范围内（窗口缩放时按比例跟随），可通过侧边栏开关隐藏/显示，余额不足时变红并自动重新出现，且适配暗色主题。

功能

• 余额实时显示 — Host 半边请求官方接口 https://api.deepseek.com/user/balance，以 GET /dsh-balance 暴露给浏览器半边；气泡每 20 秒刷新。悬停可查看充值余额 / 赠送余额明细与更新时间。
• 液态玻璃外观 — 半透明浅蓝圆形、背景毛玻璃模糊、顶部光泽高光与柔和内阴影。
• 自由拖动 — 按住即可移动；位置限制在窗口内，窗口缩放时按比例跟随。
• 隐藏 / 显示 — 气泡右上角 ✕ 可隐藏；侧边栏底部「余额」开关（位于 cordis 插件条目上方）可重新显示，两者状态同步。
• 余额不足告警 — 余额低于阈值（默认 5 CNY）时气泡变红并脉冲提示，隐藏状态下也会自动重新显示。
• 暗色模式适配 — 监听 theme/change 事件；暗色主题下气泡更亮、文字变白。

侧边栏开关

气泡隐藏后，可通过侧边栏底部的 「余额」按钮重新显示——它位于 cordis 插件条目正上方。宽侧边栏下显示 ¥ 图标加「余额」文字；收起为窄栏时仅剩图标。按钮与气泡状态实时同步：气泡隐藏时按钮变灰。

截图

浅色模式	深色模式

安装

需要 DSH web profile（dsh web）且已配置 DeepSeek API Key（DEEPSEEK_API_KEY，在「设置 → 模型」中填写）。

1. 安装到 web profile：

   dsh plugin --profile web add dsh-balance-bubble
   # 或手动：
   cd ~/.dsh/profiles/web && pnpm add dsh-balance-bubble

2. 挂载插件：本包自带补丁（dsh.bundle.patch → cordis.patch.yml），把 dsh-balance-bubble 加入 profile 的 dsh.profile.bundles 即可自动生效；也可以手动插入：

   - insert:
       - id: dsh-balance-bubble
         name: 'dsh-balance-bubble'

3. 重启 DSH，气泡与侧边栏开关每次启动自动加载。

配置

目前暂未开放用户可配置项。低余额阈值固定为 5 CNY，如需修改请编辑 lib/client.js 中的 totalBalance < 5。

API Key 通过 DSH 的 credentials 服务读取（DEEPSEEK_API_KEY，与「设置 → 模型」页面写入的同一个引用），插件本身不存储密钥。

工作原理

• Host 半边（lib/index.js）— 通过 ctx.credentials 解析密钥，用 Node 原生 fetch 请求官方余额接口（30 秒缓存），并在 ctx.webServer 注册 GET /dsh-balance 路由（路径刻意避开系统传输层占用的 /api 前缀）。
• 浏览器半边（lib/client.js）— 向 shell.overlay 注册气泡、向 sidebar.footer.action 注册开关（order: -1，位于 cordis 插件条目上方），每 20 秒轮询路由，用 React 渲染。

已知限制与后续计划

• 阈值为硬编码 — 尚未注册设置命名空间；计划后续在 DSH 设置界面开放阈值等选项。
• 拖动位置刷新后重置 — 位置保存在组件状态中；跨刷新持久化暂未实现。
• 仅面向 Web 界面 — 无 TUI 适配。