dsh-usage-display: Displaying Model Provider Balances and Usage in the DeepSeek Harness Web Interface

在智能体开发流程中，API 余额或套餐用量的监控容易被忽视，直到出现欠费或配额耗尽才影响业务。现有的控制台或配置文件查看方式不够直观。dsh-usage-display 插件在 Web 界面的会话头部直接展示厂商的余额或用量信息，解决了这一痛点。

What is this¶

This is a session header usage badge plugin, maintained by developer deluo. It fetches data from each provider’s official API through the host process and caches it. Browser-side rendering only reads local data. API keys always remain on the host side and are never sent to the browser.

The plugin has three built-in providers, organized with a multi-provider adapter architecture. Adding a new provider only requires implementing an adapter:

Core features¶

1. Session header usage badge: Displays the primary metric for the provider associated with the current model. Click to expand a detail panel; manual refresh is supported.
2. Configurable alert thresholds: When the balance falls below the threshold or quota usage exceeds the threshold, the badge status dot and progress bar are colored at two levels: warn (yellow) / critical (red).
3. Configurable progress visualization: Percentage-based metrics support three display modes in the badge and panel: text, ring, and bar (display.panelStyle). The badge can use auto to select automatically based on the metric type.
4. Settings page hot update: In Settings → Plugins → "Usage and Balance", display preferences and alert thresholds can be adjusted immediately. After saving, the host rebuilds the runtime and refetches data without a restart. Connection-related fields still go through cordis configuration.
5. Automatic data fetching: Data is fetched automatically after an actual model call occurs. turn/start and turn/end each trigger a full refresh; when switching models, only the newly selected provider is refreshed.
6. SSE notification and security: After the host refresh completes, it notifies the browser via SSE to reread the local cache. The browser never connects directly to provider APIs.
7. Fault isolation: Each provider has its own cache and fault isolation. A failure for one provider does not affect the others. On failure, the last successful value is retained and the update time is annotated.
8. Credential reference configuration: Credentials appear in configuration only as reference names. On each fetch, the dsh credential service resolves them in real time, so credential rotation takes effect on the next request.

Installation and enabling¶

Prerequisites include Node.js, pnpm, and dsh CLI ≥ 0.1.0-rc.6. If using pnpm ≥ 10, configure allowBuilds in the profile’s pnpm-workspace.yaml.

The installation command is:

dsh plugin --profile web add github:deluo/dsh-usage-display

After installation, find and configure the plugin in Settings → Plugins → "Usage and Balance" in the Web interface.

Typical usage¶

The default plugin configuration is in cordis.patch.yml. Users can override it in a profile-level or home-level cordis.patch.yml (the later applied layer replaces the entire line).

DeepSeek configuration example¶

dsh-usage-display:
  display:
    badgeStyle: 'auto'
    panelStyle: 'ring'
    showResetCountdown: true
  providers:
    deepseek:
      enabled: true
      routeIds: ['deepseek-official']
      apiKeyEnv: 'DEEPSEEK_API_KEY'
      baseURL: 'https://api.deepseek.com'
      badgeCurrency: 'CNY'
      warnBelow: 10
      criticalBelow: 5

MiniMax configuration example¶

    minimax:
      enabled: true
      routeIds: ['minimax', 'minimax-cn', 'minimaxi', 'minimax-coding-plan', 'minimax-token-plan']
      apiKeyEnv: 'MINIMAX_API_KEY'
      baseURL: 'https://api.minimaxi.com'
      badgeMetric: '5h'
      resetTimeStyle: 'countdown'
      warnAbovePercent: 80
      criticalAbovePercent: 90

Zhipu GLM configuration example¶

    zhipu:
      enabled: true
      routeIds: ['zai-coding-cn', 'zai-coding', 'zai', 'glm', 'zhipu', 'bigmodel', 'zhipuai']
      apiKeyEnv: 'ZHIPU_API_KEY'
      baseURL: 'https://open.bigmodel.cn'
      authStyle: 'raw'
      badgeMetric: '5h'
      resetTimeStyle: 'countdown'
      warnAbovePercent: 80
      criticalAbovePercent: 90

Display preferences configuration¶

  display:
    badgeStyle: 'auto' # auto | text | ring | bar
    panelStyle: 'ring' # text | ring | bar
    showResetCountdown: true

Applicable scenarios and notes¶

This plugin is suitable for developers who need to manage quotas and balances across multiple providers such as DeepSeek, MiniMax, and Zhipu GLM.

Note: The plugin runs with host process privileges. API keys are resolved by the host credential service and are not exposed to the browser. When installing from source on Windows, paths must use forward slashes (for example, D:/Code/...); backslashes will be parsed as invalid package names. Review the source code and license before installation.

Conclusion¶

dsh-usage-display provides an intuitive way to monitor provider balances and usage in the DSH Web interface. By separating host-side data fetching from browser-side rendering, this design helps protect API key security. For more details, see the GitHub repository or the plugin catalog.