In the DeepSeek Harness (DSH) web interface, developers need a way to quickly confirm their API quota. The ds-balance plugin provides a lightweight solution by integrating balance information directly into the session header.

What It Is

ds-balance is a minimalist DeepSeek account balance widget maintained by JovanHE, designed specifically for the DeepSeek Harness (dsh) web GUI. It displays the current account balance through a compact capsule component and supports automatic refresh and detail viewing.

Core Features

  • Real-time display: Displays a balance capsule on the right side of the session header (e.g., DS CNY 3.65).
  • Automatic refresh: Refreshes the balance every 60 seconds by default.
  • Manual refresh: Click the capsule to refresh the data immediately.
  • Hover details: Hover to view the full breakdown of total balance, granted quota, and top-up details.
  • Security: When reading DEEPSEEK_API_KEY, it uses only DSH’s credential seam; the key is passed only in the child process environment and does not appear in the command line, source code, or browser.
  • Read-only and idempotent: Fetches data with a single HTTPS GET request and does not generate session events or log pollution.

Installation and Activation

Ensure DeepSeek Harness (dsh) is installed and the Web profile is configured. Run the following command to install the plugin:

dsh plugin --profile web add github:JovanHE/ds-balance

After installation, you must restart the dsh web process because the client plugin discovery mechanism runs only at process startup.

Typical Usage

The plugin requires no configuration. As long as DEEPSEEK_API_KEY is set in the DSH credential store (~/.dsh/.credentials.yaml) or environment variables, the widget appears in every session header.

  • Click the capsule to refresh it immediately.
  • Hover over the capsule to view details of the balance composition.
  • If the key is missing or the request fails, the capsule turns red and the hover tooltip shows the reason.

Security and Implementation Details

  • Key retrieval: The plugin reads DEEPSEEK_API_KEY from DSH’s credential seam.
  • Passing method: The key is passed only through a child-process environment variable and is never included in command-line arguments or source code.
  • Endpoint calls: It uses ctx.shell to call PowerShell’s Invoke-RestMethod to access DeepSeek’s balance endpoint. This addresses Windows sandbox limitations, because the fetch seam cannot carry the required Authorization header.
  • Bundle client adaptation: In a bundled client, the host and styles global variables are unavailable, so the plugin injects the stylesheet through document.

Summary

The ds-balance plugin meets the need for developers to check their DeepSeek balance by integrating it into the DSH interface header. It safeguards the API key and provides an intuitive interaction experience without requiring additional configuration.