When developing agents in DeepSeek Harness (DSH), monitoring API consumption is part of daily operations. Developers typically need to switch to the official console or use external tools to check their balance. The dsh-api-balance plugin solves this problem directly by integrating balance queries into the DSH Web interface and also exposing them for model use.

This plugin is maintained by user neltharion11 under the MIT open-source license.

Core Features

The plugin includes three main parts:

  1. Web sidebar widget: Inserted into the sidebar.footer.action slot. When the sidebar is expanded, it displays the balance (using the first currency); when collapsed, it shows a wallet icon. Hovering displays details (top-up, bonus, update time), and clicking refreshes it. The widget polls every 20 seconds, with a 60-second cache on the host as a fallback to avoid high-frequency calls.
  2. api_balance tool: The model can call this tool during a conversation to retrieve detailed balance information (currency, total amount, top-up, bonus, update time).
  3. System prompt section: Automatically injects a description for the model, informing it that a balance widget and tool are available.

Environment Requirements

  • DeepSeek Harness: Uses the web profile.
  • Node.js: Version must be greater than or equal to 22.19.
  • API key: A valid DeepSeek API key is required.

Installation

The plugin depends on pnpm. Run the following command in your terminal:

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

dsh plugin installs the package into the profile and adds it to the dsh.profile.bundles list.

Method 2: Install from a Local Path

If you already have the source code locally, you can use a local path:

dsh plugin --profile web add file:F:\path\to\dsh-api-balance

Method 3: Manual Installation

If pnpm is not installed on the machine, please strictly follow these steps:

  1. Prepare the folder: Ensure the folder name exactly matches the package name, dsh-api-balance (after downloading the ZIP from GitHub and extracting it, the default name usually includes a -main suffix and must be renamed).
  2. Place the file: Copy the dsh-api-balance folder to %DSH_HOME%\profiles\node_modules\dsh-api-balance.
  3. Modify the configuration: Edit %DSH_HOME%\profiles\web\package.json.
    • Add the following to dependencies: "dsh-api-balance": "file:../node_modules/dsh-api-balance".
    • Add the following to dsh.profile.bundles: "dsh-api-balance".
  4. Verify: Run dsh --profile web --dump-config | findstr api-balance and confirm that the output includes - id: api-balance.

After installation, you must restart dsh web for changes to take effect.

Configuration

Override the plugin configuration through the profile’s cordis.patch.yml (with the line id api-balance):

- id: api-balance
  config:
    apiKeyEnv: DEEPSEEK_API_KEY   # 凭据引用名
    baseURL: https://api.deepseek.com
    timeoutMs: 15000              # 单次上游请求超时
    cacheMs: 60000                # 宿主缓存余额快照的时长
    enabled: true

Notes

  • Key security: The API key is used only in host memory for the Authorization: Bearer header and never appears in HTTP responses, tool results, or logs.
  • Dependencies: Except for Method 3, the installation process depends on pnpm.
  • When it takes effect: After installation, the DSH Web process must be restarted.

Summary

dsh-api-balance integrates API balance monitoring from external processes into the DSH ecosystem. Developers can check the balance without leaving their workflow, and models can query it autonomously as well. For more details, refer to the GitHub repository or the SkillHub plugin catalog.