dsh-balance-plugin

✨ Features

Charts use Miyu's chart / heat palettes (blue / gold / rose / purple + blue-purple heat scale) and auto-adapt to dark / light themes.

🖼 Screenshots

Screenshot	Description
	Three icon entries on the right of the input toolbar (💰 Wallet / 📊 Usage / 🧩 Plugins) plus a persistent balance bar below
	Balance monitoring panel: balance table, low-balance alerts, account config, thresholds & refresh interval, top-up entry
	Usage page top: range switcher, stat tiles, live performance metric bar, GitHub-style usage calendar
	Usage page bottom: trend bar chart, model consumption details, call record details
	Third-party plugin manager: stat badges, plugin list, "Open Directory" action

📥 Install

Prerequisites

• DeepSeek Harness installed and running
• (Optional) DeepSeek API Key — get one at platform.deepseek.com; if DEEPSEEK_API_KEY is already configured on this machine, the plugin auto-reads it at startup — no manual input required

One-click install (recommended)

# Installs automatically (install deps → write compose patch → prompt restart)
curl -fsSL https://raw.githubusercontent.com/Francis-Xavier-code/dsh-balance-plugin/main/install.sh | bash

Restart DeepSeek Harness after installation — three icon buttons appear on the right of the input box. Use DSH_PROFILE=<name> to target another profile.

Manual install (equivalent)

# 1. Install the dependency (use the github: source, not the bare package name — a third party owns a same-named package on npm)
dsh plugin --profile web add github:Francis-Xavier-code/dsh-balance-plugin

# 2. Append the plugin line to ~/.dsh/cordis.patch.yml (skip if already present)
- insert:
    - id: dsh-balance-plugin
      name: 'dsh-balance-plugin'

# 3. Restart DeepSeek Harness

⚙️ Configuration

Click the wallet icon (💰) on the right of the input toolbar to open the "Balance Monitor" panel:

🔒 Key security: API Keys are kept only in the plugin process memory on your machine and are never uploaded to any third party; the UI only shows masked values.

🎮 Usage

All panels are centered overlays: click the backdrop or "✕ Close" to exit.

🗑 Uninstall

# One-click uninstall (removes dependency + cleans the compose patch)
curl -fsSL https://raw.githubusercontent.com/Francis-Xavier-code/dsh-balance-plugin/main/uninstall.sh | bash

Manual equivalent:

dsh plugin --profile web rm dsh-balance-plugin
# and remove the corresponding two lines from ~/.dsh/cordis.patch.yml

Restart DeepSeek Harness after uninstalling.

🏗 Architecture

Host (Node.js process)
├─ Balance query: shell runs curl → api.deepseek.com/user/balance (Bearer auth)
├─ Usage aggregation: real-time session/event listening + 90-day history scan (deduped by seq)
├─ Third-party plugins: clientModules.graph() + clientPath() + open -R to locate
├─ RPC routes: /bmon/api/get-state · refresh · recharge · set-config ·
│              get-usage · list-plugins · open-plugin-dir
└─ Model tool: query_api_quota

Client (browser)
├─ Entry: 3 SVG icon buttons on the right of the input toolbar
├─ Overlays: self-rendered fixed panels inside the component (no overlay slot dependency)
└─ Charts: Miyu chart/heat palettes, dark/light adaptive

❓ FAQ

Q: Will the plugin still be there after a restart? A: Yes — static plugins are installed persistently and survive restarts. Manually configured account keys reset (the auto-read DEEPSEEK_API_KEY account needs no reconfiguration and restores automatically after restart).

Q: I can't see the entry button at the bottom of the sidebar? A: The DSH sidebar bottom slot is exclusively occupied by the official Cordis panel plugin. This plugin's entry is fixed on the right of the input toolbar and does not depend on that slot.

Q: Will my Key leak? A: No. Keys are kept only in the plugin process memory on your machine and the UI only shows masked values; neither the source code nor the README contains any secrets.

Q: Balance query fails? A: Check the error hint in the panel: no Key configured (API Key not configured), missing environment variable (Environment variable xxx not set), invalid Key (401 error message), and handle accordingly.

Q: No historical usage data? A: The plugin scans session events from the last 90 days at startup; "avg first token" only counts streaming data captured in real time after the plugin is running.

Q: Why not use dsh plugin add dsh-balance-plugin? A: A third party owns a same-named package on npm (dsh-balance-plugin@0.1.0), so the bare name would install the wrong one. Use the one-click script or the github: source (see Install).

💬 QQ Community

📄 License

MIT © 2026 Black Cat (Francis-Xavier-code)