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.