dsh-deepseek-balance: DSH Sidebar Balance and Billing Period Monitoring

Introduction¶

When developing or deploying agents using the DeepSeek API, monitoring the account balance in real time and knowing which stage of the billing cycle is currently active (peak/idle) can help with cost control. DeepSeek Harness (DSH) supports feature extension through plugins, and dsh-deepseek-balance is a Web sidebar plugin designed for this purpose.

Plugin Overview¶

This plugin is maintained by developer Jianwen-Xu under the MIT License. It is mounted in the DSH Web sidebar as a bundle, providing balance display, billing period detection, and countdown functionality.

Core Features¶

Balance and currency display: Shows total balance and currency unit; hover to view details of granted balance and topped-up balance.
Billing period detection: Calculates Beijing time locally. From Monday to Friday, 09:00–12:00 and 14:00–18:00 are peak periods, while all other times are idle periods (price is half of the peak price).
Countdown: The badge displays remaining time until the next period switch.
Status indication: Displays account status dot (green = normal, yellow = unavailable, red = read failure, blue = loading).
Adaptive layout: When the sidebar is collapsed, it displays as a single wallet icon with a status dot at the bottom-right; hover to show full information.

Installation and Activation¶

Use the official installation command to add the plugin to a specified profile:

dsh plugin --profile web add github:Jianwen-Xu/dsh-deepseek-balance

pnpm version note: If installing from GitHub with pnpm >= 10, the first add command may fail because build scripts for git dependencies are rejected by default. In this case, add the allowBuilds configuration to the profile’s pnpm-workspace.yaml:

allowBuilds:
  dsh-deepseek-balance: true

Configuration and Usage¶

The plugin resolves API keys by priority:
1. Credentials service ctx.credentials.resolve('DEEPSEEK_API_KEY') (recommended; can be saved on the Web Models settings page or written to ~/.dsh/.credentials.yaml).
2. Process environment variable DEEPSEEK_API_KEY.

If the API key is missing, the API returns {"ok":false,"code":"no-api-key"}, and the UI displays a red status dot.

API Description¶

The plugin provides a GET endpoint to query balance and status:

GET /deepseek-balance?refresh=1

Response example:

{
  "ok": true,
  "isAvailable": true,
  "display": { "currency": "CNY", "totalBalance": "17.49", "grantedBalance": "0.00", "toppedUpBalance": "17.49" },
  "peakHour": false,
  "peakLabel": "空闲",
  "nextLabel": "高峰",
  "nextSwitchAt": 1789347657403,
  "fetchedAt": 1789125085432
}

Notes¶

Local development: After locally checking out the source code, manually run pnpm build to generate the lib/ directory; otherwise, the installation will not take effect.
Timezone handling: Internally, the plugin shifts time by 8 hours before reading UTC fields, so the result is independent of host timezone and ensures accurate Beijing time.
Caching and refresh: API responses include the Cache-Control: no-store header; manual refresh requires appending ?refresh=1 to the URL.

Source Code and Directory¶

The plugin source code is available on GitHub: https://github.com/Jianwen-Xu/dsh-deepseek-balance.