dsh-balance-pie

Readme

# dsh-balance-pie

> [English](./README.md) · [中文](./README.zh-CN.md)

**A DSH plugin · balance monitor / real spending / history heatmap**

[![DSH](https://img.shields.io/badge/DSH-Plugin-566efe)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#-license)

A plugin for [DeepSeek Harness](https://github.com/deepseek-ai/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:

```sh
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:

```sh
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

```sh
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