Introduction

When developing agents with DeepSeek Harness (DSH), API account balance is a continuously consumed resource. Manually checking the balance usually requires logging into the web console, which interrupts the development workflow. The dsh-balance-guard plugin addresses this issue by embedding the balance status directly into the top-right corner of the session header in the Web interface through a Host-side proxy and Client-side rendering.

Plugin Overview

This plugin is maintained by bunipai and is licensed under MIT. It reads the same credentials as llm-deepseek (default DEEPSEEK_API_KEY), calls the official DeepSeek API to retrieve balance information, and displays it in real time in the interface.

Core Features

  • Interface integration: Displays a balance capsule in the top-right corner of the session header in the Web interface.
  • Automatic refresh: The client polls every 30 seconds by default; clicking the capsule refreshes it immediately; it also refreshes when the page becomes visible again.
  • Detailed information: Hovering shows the total amount, grants, recharge details, and update time.
  • Low balance warning: When the balance is ≤ the threshold (default ¥5), the capsule turns orange and displays ⚠, the page title is prefixed with “⚠ Low Balance”, and a system notification is shown.
  • Notification rules: A low balance event is alerted only once; if a recharge raises the balance above the threshold and it later drops below again, the alert is triggered again.
  • First authorization: The first click on the capsule requests system notification permission.

Installation and Activation

Use the official install command:

dsh plugin --profile web add dsh-balance-guard

After installation, a running web process will hot-load patch changes, and refreshing the page will show the balance capsule.

Configuration

Add the plugin line configuration to profile cordis.patch.yml with supported custom parameters:

- insert:
    - id: plugin-balance
      name: dsh-balance-guard
      config:
        apiKeyEnv: DEEPSEEK_API_KEY
        baseURL: https://api.deepseek.com
        pollIntervalMs: 30000
        cacheMs: 15000
        timeoutMs: 10000
        lowBalanceThreshold: 5
        lowBalanceCurrency: CNY

You can also override some configuration items (such as pollIntervalMs and lowBalanceThreshold) in the plugin-balance: section of $DSH_HOME/settings.yaml.

Notes

  • The plugin runs with the permissions of the current dsh process, so make sure the server can read the correct credentials.
  • Error codes include: no-api-key, invalid-api-key, api-error, transport-error, and bad-response.