During the development or use of DeepSeek Harness (DSH), frequently switching tabs or manually accessing the console to check API balance increases operational cost. dsh-balance-whale is a client plugin that provides a floating widget directly in the bottom-right corner of the DSH Web interface, used to display the remaining DeepSeek API quota in real time.

This is a lightweight component maintained by chenpengye. It does not depend on any external image resources, renders a whale girl icon with hand-drawn SVG, and provides real-time balance status feedback. The core value of the plugin is to integrate balance queries into the local development environment while ensuring API Key security through its architectural design.

Core Features

  1. Floating display and status feedback: Displays the whale girl icon and current balance in the bottom-right corner. A status dot appears next to the icon: green means balance is available, orange means no balance.
  2. Interactive detail card: Clicking the icon expands a card showing availability status, total balance for each currency, top-up details, granted details, last updated time, and a manual refresh button.
  3. Automatic refresh and caching: Requests the latest data automatically every 60 seconds. A 30-second cache is maintained on the Host process side to prevent frequent calls to the official API from triggering rate limiting.
  4. Security mechanisms: The API Key is read only from the credentials store in the Host process and is never transmitted to the browser. The query endpoint listens only for local loopback requests and refuses non-local access. Error messages are categorized and do not expose the raw response body from upstream APIs.

Installation and Enablement

This plugin is a Cordis bundle and has not been published to npm, so it must be installed from source.

  1. Clone the repository and build it:
    git clone https://github.com/chenpengye/dsh-balance-whale.git
    cd dsh-balance-whale
    pnpm install && pnpm build
  1. Register the plugin in the Web configuration directory:
    cd ~/.dsh/profiles/web
    pnpm add /absolute/path/to/dsh-balance-whale -w
  1. Add the plugin ID to cordis.patch.yml:
    - insert:
        - id: dsh-balance-whale
          name: dsh-balance-whale
  1. Restart dsh web (or trigger HMR hot reloading) and hard refresh the browser page.

Typical Usage

No additional configuration is required. The plugin automatically reuses the DEEPSEEK_API_KEY saved in the DSH credentials store (the Key configured in “Settings -> Models”). After installation, the whale girl icon appears in the bottom-right corner.

Applicable Scenarios and Notes

It is suitable for developers who need to monitor API quotas quickly during local development and value privacy. The plugin runs with the permissions of the current DSH process, and the Key never leaves the local machine. Under the default configuration, the query route refuses non-loopback requests. It is recommended to review the source code and license before installation.

This plugin provides DSH users with a convenient and secure entry point for balance monitoring through local polling and safe Key management. The project code is hosted on GitHub and follows the MIT license.