Preface

During the development and debugging of DeepSeek Harness (DSH), having real-time visibility into your API account balance helps control costs or plan usage. The dsh-balance plugin addresses this need by persistently displaying the balance in the Web interface, providing a tool interface, and including an automatic refresh mechanism, making balance queries intuitive and efficient.

Plugin Introduction

dsh-balance is a DeepSeek API balance display plugin maintained by Yogioo. It persistently displays the account balance below the dsh web chat input box, provides a check_balance tool for models, and handles the API Key through the host process to ensure security.

Core Features

  1. Persistent Web UI Display
    Displays DeepSeek Balance: ¥xx.xx below the dsh web chat input box.
    Hover over the information to view gift and top-up details.
  2. Model Tool Integration
    The plugin registers a check_balance tool. Developers can simply tell the agent “check balance” to invoke it.
  3. Security and Automatic Refresh
    The API Key exists only in the host process; the browser does not access the key. The host process automatically refreshes balance data every 60 seconds.
  4. Automated Deployment
    Declares dsh.bundle, allowing installation and mounting with a single command without manually modifying configuration files.

Installation

Use the officially provided command to install. The installer automatically adds the plugin to the profile layer and mounts the patch.

dsh plugin --profile web add git+https://github.com/Yogioo/dsh-balance.git

After installation, restart dsh web and refresh the page to see the balance reading.

Typical Usage

  • View Balance: Check the real-time balance below the chat input box. Hover to see the breakdown of gifted and topped-up amounts.
  • Command Query: Interact directly with the agent by sending “check balance” or a similar instruction to trigger the check_balance tool.
  • Error Handling: If the query fails, the interface displays the reason for the error and automatically retries after 60 seconds.

Technical Details and Notes

  • Environment Requirements: Requires a dsh web deployment environment, and the host Node.js version must be ≥ 18.
  • Key Configuration: The DEEPSEEK_API_KEY environment variable must be configured, and the credentials service must correctly resolve this variable.
  • Refresh Mechanism: The host queries the balance through the official API every 60 seconds, and the client synchronously retrieves the cached data from the host.
  • Code Changes: Changes to host logic (such as lib/index.js) usually take effect immediately; changes to client logic (such as lib/client.js) require restarting dsh web.
  • Conflict Handling: For line id conflicts, the bundle patch and user patch are merged under the rule “when the same line id is used, the latter overrides,” allowing users to override default configurations.

Summary

The dsh-balance plugin provides dual support at both the UI and tool layers, solving the pain point that DSH developers frequently need to check their balance. It not only offers a visual balance reading but also uses persistent refreshing and automatic retry mechanisms to ensure the timeliness and stability of the information.

For more information and source code, refer to:
- GitHub Repository
- DSH Plugin Directory