Introduction¶
DeepSeek Harness (DSH) uses a plugin-based architecture designed to improve development and debugging efficiency through modular extension. When using DSH to develop agents, accurately tracking API call costs and daily balance changes is essential. The dsh-balance-pie plugin provides visual balance monitoring and historical data recording, helping developers quickly locate abnormal consumption and avoid over-expenditure.
Plugin Introduction¶
This plugin is maintained by f1yan9 and is positioned as a client-side plugin for the DSH web interface. It displays daily initial balance, actual project consumption, and remaining balance through a draggable floating pie chart, and provides a GitHub-style historical heat map and daily table, enabling real-time balance monitoring and historical review.
Core Features¶
1. Floating Pie Chart and Interaction¶
The plugin displays a floating pie chart in the lower-right corner of the DSH web interface, intuitively showing data across three dimensions: “today’s initial balance”, “actual consumption”, and “remaining balance”.
* Interactive controls: Supports dragging the pie chart to adjust its position; hovering over a sector shows detailed data; a minimize button (—), settings button (⚙), refresh button (↻), and top-up icon button are provided.
* Sidebar adaptation: When the sidebar is collapsed, the component becomes a bar chart (horizontal bar chart when expanded, and vertical bar chart + balance in a narrow track); clicking the sidebar expands the pie chart.
2. Actual Consumption Calculation¶
The plugin calculates consumption directly based on actual balance reduction rather than simple estimation.
* Allocation logic: Consumption amounts are allocated to projects based on estimated usage.
* Automatic handling: Top-ups and refunds are automatically identified and included in calculations, ensuring the data reflects real account changes.
3. Top-up Detection and One-click Top-up¶
The plugin automatically detects top-up actions and updates the balance baseline after a top-up is detected. It also provides a one-click button to jump to the official top-up page for convenient user operation.
4. Historical Data Recording¶
The plugin provides complete consumption history functionality:
* Visualization: A GitHub-style monthly heat map; dates without records are displayed in white.
* Table: A detailed table displayed by date, including date, spending, and remaining balance.
5. Local Persistence¶
All state data is stored locally, including initial balance and total top-ups for the day. When DSH is restarted on the same day, this state is automatically restored.
Installation and Enabling¶
With DeepSeek Harness (DSH) installed and the API Key configured, use the following command to install the plugin:
dsh plugin --profile web add github:f1yan9/dsh-balance-pie
After installation, restart the DSH web interface and open the UI. The floating pie chart will appear in the lower-right corner. To uninstall, run:
dsh plugin --profile web remove dsh-balance-pie
Typical Usage¶
- Monitor balance: View the floating pie chart in the lower-right corner of the DSH web interface. Drag it to adjust its position, and hover over it to view details.
- View history: Click the settings icon (⚙) on the floating pie chart to enter the “Balance” settings center, then switch to the history page to view the heat map and table.
- Top up: When insufficient balance is detected or when topping up manually, click the top-up icon to jump directly to the official top-up page.
Configuration Parameters¶
The plugin can be configured through the “Balance” panel in the settings center or via the cordis.patch.yml file in the DSH Profile. Common parameters are as follows:
| Parameter | Description | Default |
|---|---|---|
pollIntervalMs |
Balance query interval | 10000 ms |
pricesJson |
Off-peak unit price for each model (per million tokens) | deepseek-v4-flash preset |
peakMultiplier |
Peak price multiplier | 2 |
language |
UI language (auto follows DSH automatically) |
auto |
displayCurrency |
Display currency (after conversion) | auto (account currency) |
fxRatesJson |
Exchange rate JSON from RMB to target currency | {"USD":0.14,"EUR":0.13,"GBP":0.11,"JPY":20,"KRW":190} |
topUpUrl |
Top-up page URL | Official top-up page |
Notes¶
- Consumption calculation: The plugin measures actual balance reduction; project amounts are allocated based on estimated usage. If consumption does not match the bill, calibrate prices in settings.
- Data recovery: Initial balance and current-day state are only persisted locally and can be restored after a same-day restart.
- Top-up delay: Top-up detection depends on the next polling cycle (default 10 seconds); historical top-ups already spent cannot be retroactively fixed.
- Data storage: Historical data is stored in the
$DSH_HOME/dsh-balance-pie/directory, including daily state files and JSONL log files with a 90-day retention period. - License: The plugin is open-sourced under the MIT License.
Summary¶
The dsh-balance-pie plugin uses visual pie charts and historical heat maps to provide DSH users with a clear balance monitoring solution. It supports actual consumption calculation, automatic top-up detection, and local persistence, making it suitable for users who need to manage API costs precisely during development.
For more details and source code, visit GitHub or see the community catalog.