Introduction

DeepSeek Harness (DSH) is a plugin-based platform. Developers usually check Agent Plan usage for Volcano Ark through the local CLI tool arkcli. This plugin adds a usage card to the bottom of the left sidebar in the DSH Web UI, retrieves data directly from the local arkcli, and displays usage, avoiding frequent terminal switching.

Plugin Overview

  • Name: dsh-ark-plan-usage
  • Maintainer: Barry-Liu-001
  • License: MIT
  • Core functionality: real-time 5-hour/weekly/monthly usage display in the sidebar, expand/collapse support (Orbit mode), color coding, and one-click re-login.

Prerequisites

Before installation, ensure the following conditions are met:

  1. DSH version: 0.1.1-rc.x (Web profile).
  2. arkcli status: arkcli installed and logged in (arkcli auth status returns logged_in: true).
  3. Subscription access: the current DSH profile has an Agent Plan subscription.

Installation and Enablement

Install via the DSH plugin management command:

dsh plugin --profile web add github:Barry-Liu-001/dsh_ark_plan_usage

After installation, restart DSH Web (dsh web). The usage card will appear at the bottom of the left sidebar.

Features

  1. Real-time display: The card shows the 5-hour usage progress bar, percentage, used/total amount, and reset time, with small weekly/monthly usage progress bars below.
  2. Orbit mode:
    - Expanded: Shows complete information (icon, progress bar, data).
    - Collapsed: Shows only a small hexagonal icon and percentage; hovering displays the complete information.
  3. Color coding:
    - Green: < 50%
    - Yellow: 50% - 80%
    - Red: ≥ 80%
    (thresholds are unified for the main bar, weekly/monthly bars, and icon)
  4. Data caching: The server uses a 5-minute in-memory cache, aligned with the arkcli call cadence. Click the card to force refresh. If retrieval fails, the previous data is retained and marked as stale.
  5. SSO credential handling: When SSO credentials expire, the card’s error area displays a “Re-login” button. Clicking it makes the host automatically run arkcli auth login volc-sso to open a browser for authorization. After authorization completes, the data is refreshed automatically.

How It Works

The plugin inserts a Node service (arkPlanUsage Typert Remote) into the Loader tree via cordis.patch.yml. The browser calls this service over RPC.

The data fetch flow is as follows:

  1. The sidebar card in the browser calls ctx.remote.arkPlanUsage.getUsage().
  2. The Node-side ArkPlanUsageService checks the cache:
    - If the cache is valid (< 5 minutes), it returns directly.
    - If the cache is expired, it executes arkcli usage balance --type plan --format json (20-second timeout).
  3. It parses the JSON and returns the result.

Error-handling scenarios include arkcli not found, SSO expiration, invocation timeout, and so on. All of them present corresponding UI prompts or action entries.

Configuration and Development

Environment Variables

If arkcli is not in a default path (/opt/homebrew/bin/arkcli, /usr/local/bin/arkcli, ~/.local/bin/arkcli, /usr/bin/arkcli), specify it with an environment variable:

export ARK_PLAN_USAGE_ARKCLI=/path/to/arkcli
# or
export ARKCLI_BIN=/path/to/arkcli

Development Mode

The plugin has no build step and relies on DSH host capabilities.

If installing from local source (dsh plugin --profile web add /path/to/dsh-ark-plan-usage), add a symbolic link to resolve Node module resolution issues:

mkdir -p node_modules
ln -sfn ~/.dsh/profiles/node_modules/@deepseek-ai node_modules/@deepseek-ai

Refresh the browser after modifying client.js; modifying index.js or cordis.patch.yml requires restarting dsh web.

Uninstall

dsh plugin --profile web remove dsh-ark-plan-usage

Summary

This plugin embeds a visualization card in the DSH sidebar, addressing the need for developers to frequently interact with the terminal to check Agent Plan usage. It has zero build, zero runtime dependencies, and integrated SSO credential management, making it suitable for developers who need real-time quota monitoring in a Web interface.