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