dsh-balance-pill

🌐 中文

> A DeepSeek balance floating pill for DeepSeek Harness (DSH): 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.

 <!-- Uncomment after publishing to npm:  -->

📸 Screenshots

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)

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

Option 2: install from npm (after publishing)

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

> 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

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 — a wallpaper plugin for the DSH web GUI: upload a custom wallpaper, tune transparency, fill the whole background.

License

[MIT](LICENSE)