dsh-balance-bubble

Readme

# dsh-balance-bubble

A Cordis plugin for the [DSH (DeepSeek Harness)](https://github.com/deepseek-ai/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 |
| --- | --- |
| ![Light mode - overall view](screenshots/light_mode_overallview.png) | ![Dark mode - overall view](screenshots/dark_mode_overallview.png) |
| ![Light mode - bubble close-up](screenshots/light_mode_bubble.png) | ![Dark mode - bubble close-up](screenshots/dark_mode_bubble.png) |

## 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:

   ```bash
   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:

   ```yaml
   - 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）](https://github.com/deepseek-ai/deepseek-harness) Web 界面的 Cordis 插件：在界面右上角悬浮一个半透明玻璃质感的气泡，实时显示你的 **DeepSeek 账户余额**，并自动刷新。

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

## 功能

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

## 侧边栏开关

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

## 截图

| 浅色模式 | 深色模式 |
| --- | --- |
| ![浅色-整体视图](screenshots/light_mode_overallview.png) | ![深色-整体视图](screenshots/dark_mode_overallview.png) |
| ![浅色-气泡特写](screenshots/light_mode_bubble.png) | ![深色-气泡特写](screenshots/dark_mode_bubble.png) |

## 安装

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

1. 安装到 web profile：

   ```bash
   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` 即可自动生效；也可以手动插入：

   ```yaml
   - 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 适配。