Preface

When developing agents in a DSH environment, monitoring API plan usage is part of daily operations. OpenCode Go plan usage usually has to be queried manually via interfaces, with little intuitive UI feedback. This plugin integrates a real-time usage ring and query tools into the DSH Web UI input toolbar, addressing the need to monitor usage during a conversation, see the reset countdown, and actively query the remaining balance.

Plugin Overview

dsh-opencode-go-usage is a DeepSeek Harness (DSH) Web GUI plugin maintained by qknc-bot and categorized under admin-security. It focuses on OpenCode Go plan usage monitoring, providing a visual interface and Agent tool capabilities.

Core Features

  1. Usage ring in the toolbar: A 5-hour rolling window usage ring is permanently shown in the input toolbar. The ring displays the used percentage and changes color automatically based on thresholds (green, orange, red). It refreshes automatically every 30 seconds, and hovering over it shows details.
  2. Expanded card details: Click the white card next to the ring to expand it and view progress bars, percentages, and reset countdowns for the 5-hour / weekly / monthly windows.
  3. Agent tool integration: The opencode_go_usage tool is registered, allowing the model to query the balance directly during a conversation without leaving the chat window.
  4. Security mechanisms: The API Key is resolved through a DSH credential reference (OPENCODE_GO_API_KEY) and is retained only in the host process; the browser never receives it. The proxy route is limited to loopback-only, preventing Key leakage when a deployment is exposed on a LAN.
  5. Zero SDK dependencies: The plugin has no runtime dependency on @deepseek-ai/* packages. It supports git vendoring or directory installation and is ready to use out of the box.

Installation and Enablement

Installing from GitHub is recommended. Replace <ref> with a specific commit SHA to ensure reproducibility.

dsh plugin --profile web add github:qknc-bot/dsh-opencode-go-usage#<ref>

If installing from a local directory, note that the file: protocol cannot resolve paths containing spaces or Chinese characters. The source code should be placed under a pure ASCII path:

dsh plugin --profile web add file:C:/path/to/dsh-opencode-go-usage

After installation, restart dsh web. A 5h ring appearing on the left side of the input toolbar indicates that the plugin is active.

Notes:
* If the initial git installation is blocked by pnpm’s allowBuilds, add allowBuilds: dsh-opencode-go-usage: true to the profile’s pnpm-workspace.yaml.
* When upgrading from an older version, it is recommended to uninstall first and then re-add it, avoiding residual conflicts in package.json.

Configuration

The plugin configuration is located in the profile’s cordis.patch.yml (generated automatically during installation). The following fields can be overridden:

- id: opencode-go-usage
  name: dsh-opencode-go-usage
  config:
    baseUrl: https://opencode.ai/zen/go   # 上游网关基址，自动拼接 /v1/usage
    timeoutMs: 15000                      # 上游请求超时（毫秒）
    refreshSeconds: 30                    # 圆环自动刷新间隔（秒）
    warnPercent: 60                       # 5h 窗口达到该百分比后变橙
    dangerPercent: 85                     # 达到该百分比后变红
    announceToAgent: true                 # 是否向 agent 公告插件能力

API Key resolution depends on the DSH credential reference OPENCODE_GO_API_KEY, so no additional configuration is usually required.

Typical Usage

  1. UI interaction: Hover over the 5h ring in the input toolbar to view an overview. Click it to expand the card and view detailed progress and reset times for the 5-hour / weekly / monthly dimensions.
  2. Conversation query: Invoke the tool directly within the conversation. The model can automatically recognize keywords such as “balance”, “usage”, and “quota”, and then call the opencode_go_usage tool to return the current usage status.

Precautions

  • Unpublished API: The usage API is not publicly documented by OpenCode, and its response structure may evolve as opencode changes. The parsing logic includes defensive handling; non-200 or non-JSON responses are displayed as friendly notifications instead of causing a crash.
  • Quota display: Plan limits (such as $12 / $30 / $60) are shown for reference only. The API does not return monetary data.
  • Upgrade note: When upgrading from an older version, be sure to uninstall first and then re-add it.

Summary

This plugin provides DSH users with a visual entry point for usage monitoring and grants Agents the ability to query usage. Its zero-dependency design reduces integration cost, while host-process isolation helps ensure Key security. It is suitable for developers who need to monitor OpenCode Go plan remaining capacity continuously during development.

Directory Page | GitHub Repository