# dsh-balance-pill

[🌐 中文](./README.md)

> A **DeepSeek balance floating pill** for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness): a draggable, collapsible frosted-glass widget pinned bottom-right that shows your official API account balance in real time — and **reuses the harness's `DEEPSEEK_API_KEY` automatically** when you haven't configured a key of its own.

[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
<!-- Uncomment after publishing to npm:
[![npm version](https://img.shields.io/npm/v/dsh-balance-pill)](https://www.npmjs.com/package/dsh-balance-pill)
-->

## 📸 Screenshots

| Pill (default, out of the way) | Expanded |
| --- | --- |
| ![pill](./screenshots/pill.png) | ![card](./screenshots/card.png) |

## Why

While using DSH you constantly want a quick glance at your DeepSeek balance, but switching to the website is annoying. This plugin turns the balance into a small always-on pill in the bottom-right corner: glance at it to see how much is left, click it for details, drag it wherever feels right.

## Features

- **Live balance**: queries the official API `GET /user/balance` and shows total balance, availability, and top-up / granted breakdown (¥ for CNY, $ for USD).
- **Auto key reuse**: prefers a key saved inside the plugin; otherwise **read-only** falls back to the harness's `DEEPSEEK_API_KEY` (never writes to or clears it).
- **Isolated credential**: a key you type in the plugin is stored under `DSH_BALANCE_PILL_KEY`, separate from the harness's own model key.
- **Collapsible pill**: collapsed by default into a small bottom-right pill (status dot + balance); click to expand, keeping the conversation area clear.
- **Draggable**: both the pill and the card can be dragged anywhere; position persists across expand / collapse.
- **Auto refresh**: re-queries every 5 minutes, with manual refresh available.
- **Frosted glass**: 16px background blur + translucent background, auto light/dark via `prefers-color-scheme`.
- **i18n**: UI text follows the DSH language setting (Chinese / English; falls back to Chinese).
- **Cross-platform**: the Host resolves the local `curl` via `resolveExecutable("curl")` (no hardcoded `curl.exe`).
- **Secure**: all HTTP routes accept loopback (127.0.0.1 / ::1) requests only.

## Quick Start

**Option 1: install straight from GitHub (no npm needed)**

```bash
dsh plugin --profile web add github:zypchloe-del/dsh-balance-pill
```

**Option 2: install from npm (after publishing)**

```bash
dsh plugin --profile web add dsh-balance-pill
```

After installing, refresh the page and the pill appears in the bottom-right corner:

- If DSH already has DeepSeek configured (`DEEPSEEK_API_KEY`) → the balance shows immediately;
- Otherwise click the pill to expand → click **⚙** → enter your API key → Save.

> `<profile>`: use `desktop` for the desktop app, `web` for the web GUI; omitting `--profile` targets the default profile.

## Configure API Key

| Method | Description |
| --- | --- |
| Auto reuse (recommended) | Auto-detected when DSH already has `DEEPSEEK_API_KEY` (env var or credential file) — nothing to fill in |
| Fill in the widget | Expand → ⚙ → enter key → Save, stored under `DSH_BALANCE_PILL_KEY` in `~/.dsh/.credentials.yaml` |

> A key saved in the plugin takes priority over the harness key; "Clear" only removes the plugin's own key, never the harness key.

## Uninstall

```bash
dsh plugin --profile web remove dsh-balance-pill
```

## Structure

```
dsh-balance-pill/
├── lib/
│   ├── index.js    # Host: /api/dsh-balance-pill/* routes (balance query, key status/save/clear)
│   └── client.js   # Client: pill + card UI, drag, collapse, auto refresh, i18n, frosted glass
├── cordis.patch.yml  # bundle patch (entry id: dsh-balance-pill)
├── package.json
├── README.md / README.en.md
└── LICENSE
```

## Implementation Notes

- **Host** (`lib/index.js`): dependency-free ESM; registers loopback-only routes via `webServer`, calls the official API through `subprocess` + local `curl`, and resolves keys through `credentials` (own ref → harness ref fallback).
- **Client** (`lib/client.js`): mounted via `window.__ModuleLoader__.load`, attached to a low-level `document.body` container (z-index 2) instead of `shell.overlay` to stay compatible with different host overlay stacking; UI text is registered/bound through the `locale` service.
- Official balance response (`/user/balance`):
  ```json
  { "is_available": true, "balance_infos": [{ "currency": "CNY", "total_balance": "110.00", "granted_balance": "10.00", "topped_up_balance": "100.00" }] }
  ```

## FAQ

**Q: Will my key leak?**
No. The key is stored only locally in `~/.dsh/.credentials.yaml`; balance queries go only to the official DeepSeek API; HTTP routes accept loopback requests only.

**Q: Does it conflict with the harness's own key?**
No. The plugin prefers its own `DSH_BALANCE_PILL_KEY`, only read-only reuses the harness key when that is empty, and never writes back to or clears the latter.

**Q: How do I pin a position?**
Drag it where you want and release; the position is kept for the current session (across expand / collapse).

## Related

- [dsh-wallpaper](https://github.com/zypchloe-del/dsh-wallpaper) — a wallpaper plugin for the DSH web GUI: upload a custom wallpaper, tune transparency, fill the whole background.

## License

[MIT](LICENSE)