Introduction

DeepSeek Harness (DSH) uses a plugin-based architecture, allowing developers to customize workflows through extensions. In the Web profile, developers need to monitor API Key account usage in real time. Traditional command-line output is not intuitive enough, and the dsh-balance-view plugin solves this problem by mounting a persistent panel above the input box.

Plugin Positioning

dsh-balance-view is a DeepSeek Harness plugin developed by the maintainer luhaifeng666 and classified under “network tools.” It aims to address the need for developers to frequently check account balances, providing an intuitive balance display through a persistent panel and real-time update mechanisms.

Core Features

This plugin mainly provides the following capabilities:

  1. Balance Query: Query the account balance associated with the current DeepSeek API Key.
  2. Persistent Panel: Display balance information above the input box without obscuring the conversation content.
  3. Real-time Updates: Support multiple refresh trigger mechanisms to keep the data as close to real time as possible:
    • On Mount: Query once when the panel first appears.
    • After Turn Completion: Automatically refresh after each conversation turn ends.
    • Periodic Polling: Fallback refresh every 5 minutes while the panel is visible.
    • Manual Refresh: Provide a ⟳ button on the right side of the panel for users to refresh at any time.
  4. Command Support: Support entering the /balance command to view the balance.

Installation and Enablement

Installing the plugin requires using DSH’s command-line tools. Make sure you have installed DSH and configured your profile.

# 从 npm 安装（推荐）
dsh plugin --profile web add dsh-balance-view

# 或从 GitHub 安装
dsh plugin --profile web add github:luhaifeng666/dsh-balance-plugin

# 或从本地目录安装
dsh plugin --profile web add ./dsh-balance

After installation, restart the dsh process to activate the plugin. You can also replace the --profile argument with another profile name (e.g., desktop).

Usage

After installation and restart, the plugin automatically loads a panel above the input box.

  • View Balance: Type /balance and press Enter to display current balance information in the conversation flow.
  • Manual Refresh: Click the ⟳ icon on the right side of the panel. When the icon is spinning, refreshing is in progress; after completion, the latest balance is displayed.
  • Close Panel: Click the × icon on the right side of the panel to manually close it.

Implementation and Design

The plugin is implemented on both the Host side and the Client side:

  • Host Side (index.js): Registers the /balance command, reads the DEEPSEEK_API_KEY from the credential service, requests the https://api.deepseek.com/user/balance endpoint, and returns the result as command text. The Host side does not write to the session log and does not register projections.
  • Client Side (client.js): Injects a panel component into the conversation.input.dock slot. The balance data is stored in the component’s local state. Both automatic and manual refreshes trigger a Host query via ctx.remote.commands.execute(sessionId, "/balance").

Design Note: Why Not Write to the Session Log

The original plugin attempted to write balance changes to the session log (session.append("balance/change", ...)). This would cause DSH’s default-enabled session-persistence-jsonl persistence layer to error when restoring a session, because balance/change is a custom event not included in the known event table. In addition, frequent polling and refreshes would severely pollute the session log.

This plugin instead uses a “command returns text + panel local state” pattern: the balance is queried only once and is not written to the session log. The tradeoff is that automatic refreshes appear in the conversation flow as /balance command nodes, but they do not enter the model context or affect the KV cache.

Applicable Scenarios and Notes

This plugin is suitable for all users who use DeepSeek Harness for development or conversation, especially in scenarios requiring precise control of API consumption.

Notes:
* The plugin runs with the permissions of the current dsh process; please ensure the installation source is trusted.
* Because it does not write to the session log, if the panel is not refreshed after being closed and reopened, the displayed balance may not reflect the latest charges (relying on turn-end or polling refresh mechanisms).

Conclusion

dsh-balance-view provides DSH users with a convenient way to monitor balances through a persistent panel and reasonable refresh strategies. For more details or to submit an Issue, visit the GitHub repository.