dsh-balance-pie
> English · 中文
A DSH plugin · balance monitor / real spending / history heatmap
A plugin for DeepSeek Harness (DSH). It shows a draggable floating pie chart in the DSH web UI with the daily initial balance, real per-project spending and remaining balance; collapses to a sidebar bar; and ships a monthly history heatmap with a per-day spending table.
✨ Features
- 🥧 Draggable floating pie: today's initial / real spending / remaining at a glance
- 📊 Real spending: computed from actual balance decreases (top-ups/refunds handled automatically, survives restarts)
- 💰 Top-up detection + one-click recharge button (jumps to the official top-up page)
- 📅 History: GitHub-style monthly heatmap (days without records shown white) + per-day table (date / spend / remaining)
- 🗂 Local persistence: daily state + per-day JSONL logs (throttled writes, 90-day retention)
- 📐 Adaptive sidebar: horizontal bar when expanded, vertical bar + balance on the collapsed rail
- ⚙️ Settings hub「Balance」: parameters & history sub-pages, live-applied
- 🌐 i18n zh/en (auto-follows DSH language) with optional currency conversion for display
🚀 Quick Start
Prerequisites: DSH with a configured DeepSeek API key.
The repository ships a prebuilt bundle (lib/) and declares the dsh.bundle manifest — install it straight from GitHub, one line:
dsh plugin --profile web add github:f1yan9/dsh-balance-pie
Restart DSH web, then open the web UI — the floating pie appears bottom-right.
Uninstall:
dsh plugin --profile web remove dsh-balance-pie
> Manual install: clone the repo (or place the package folder into $DSH_HOME/profiles/node_modules/dsh-balance-pie/) and append an insert block to the profile's cordis.patch.yml; restart DSH web. Rebuilding from source: node build.mjs (esbuild is auto-detected).
📖 Usage
- Floating pie: drag to reposition; hover a slice for details; use — (minimize), ⚙ (settings), ↻ (refresh) and the recharge icon buttons.
- Sidebar: minimized state becomes a bar chart (horizontal when expanded, vertical + balance on the narrow rail); click it to expand the pie back.
- Settings（Balance）: the parameters sub-page holds all options (polling, currency, prices, history, language…); the history sub-page shows the heatmap and table.
⚙️ Configuration
Edit in the settings drawer（Balance section）, or via cordis.patch.yml in your DSH profile. Common options:
| Option | Description | Default |
|---|---|---|
pollIntervalMs |
Balance poll interval | 10000 ms |
pricesJson |
Per-model off-peak prices (per 1M tokens) | presets for deepseek-v4-flash |
peakMultiplier |
Peak-hour price multiplier | 2 |
language |
UI language (auto follows DSH) |
auto |
displayCurrency |
Display currency (converted) | auto (account currency) |
fxRatesJson |
CNY→target-currency rates JSON | {"USD":0.14,"EUR":0.13,"GBP":0.11,"JPY":20,"KRW":190} |
topUpUrl |
Recharge page URL | official top-up page |
🛠 Development
node build.mjs # rebuild lib/ (esbuild is auto-detected: HARNESS_ROOT → local pnpm store → npm i -D esbuild)
node test/run.mjs # typecheck → build → smoke → unit
📁 Data Storage
Plugin data lives under $DSH_HOME/dsh-balance-pie/:
daily-state.json— daily state (anchor, real spending, top-up baselines, today's top-up total)history/YYYY-MM-DD.jsonl— per-day history logs (90-day retention)
💱 Display conversion
Snapshot money fields (anchor/current/usedTotal/projects[].used/remaining/topUpToday) are converted by fxRatesJson into displayCurrency (auto = account currency, no conversion); language and displayCurrency ride the snapshot. The history route serves { records, fx: { displayCurrency, rate } } — records stay in the account currency, clients convert for display. topUpToday (Σ today's merged top-up/grant deltas) accrues, resets at midnight, and is restored on same-day restarts.
❓ FAQ
- Spending doesn't match the bill? Spending is real (balance decreases); per-project amounts are split by estimated usage — calibrate prices in settings if needed.
- Initial balance resets after restart? No — anchor and spending are persisted locally and restored on same-day restarts.
- Top-up not reflected? Top-ups are detected on the next poll (default 10 s); already-spent historical top-ups cannot be retro-fixed.
- Where is history stored?
$DSH_HOME/dsh-balance-pie/history/— remove the directory to clear all history.
📄 License
MIT
