Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture, aiming to improve development efficiency through modular extensions. In agent development scenarios, developers often face two pain points: first, the lack of official usage/billing/log query APIs makes cost control difficult; second, frequent page switching is required to check the balance.

dsh-deepseek-console is a DeepSeek account console plugin built for DSH Web GUI. It syncs the balance via the official GET /user/balance API, listens for llm/stream events locally to record tokens and costs, and displays the data as a global floating ball in the bottom-right corner.

Core Features

The plugin provides the following capabilities:

  • Real-time balance monitoring: Connects directly to the official API, displays cash balance and bonus balance separately, and supports a 5-second cache and forced refresh.
  • Local usage statistics: Because no official usage API is provided, the plugin listens to local task streams and accumulates tokens, costs, and cache-hit metrics by task and by day.
  • Global floating HUD: A persistent, draggable floating ball in the bottom-right corner (● DS ¥xx.xx) displays the current task cost and balance summary in real time. Hover to expand details; click to open the console.
  • Budget and cost protection: Supports setting a daily hard spending limit (new calls are rejected when exceeded), budget alerts (annotated on the HUD), and cost protection (automatic fallback to lower-cost models when the limit is exceeded).
  • Financial projections: Estimates the remaining days of usable balance and the spending rate based on historical data.
  • Visualization charts: Provides SVG line charts showing spending trends (today/7 days/30 days) and the spending share by model.
  • Request logs and diagnostics: Unified request logs are stored in a local SQLite database and can be filtered by status and model; API health diagnostics are also provided (success rate/error classification).
  • Agent tool: Includes the built-in deepseek_usage_report tool, allowing the Agent to directly query balance and usage within a session.
  • Model management: Displays the official model list (context/price) and local enable/disable switches.
  • Security and isolation: The API Key is stored only in the local backend credential store; the browser only sees a masked string. The backend uses subprocess + curl to connect directly, with no third-party SDK dependencies.

Installation and Setup

Install the plugin via DSH CLI:

dsh plugin --profile web add @hzjjxc/dsh-deepseek-console

After installation, restart the dsh web process. The plugin loads automatically, a floating ball appears in the bottom-right corner, and a console entry is generated under Settings → DeepSeek.

Usage

  1. View balance and cost:
    • Move the mouse to the floating ball in the bottom-right corner to view the current balance, current task cost, and budget status.
    • Click the floating ball to open the console and view detailed spending trends and balance history on the Overview page.
  2. Configure budgets and limits:
    • Go to Settings → DeepSeek → Advanced Settings to configure the daily hard spending limit or budget alert threshold.
    • When the hard limit is enabled, new DeepSeek calls are rejected once the estimated daily cost reaches the limit.
  3. Agent session queries:
    • In an Agent session, directly ask about the balance or usage; the model will automatically call the deepseek_usage_report tool to return the results.

Technical Details and Security

  • Data sources: Balance data comes from the official API. Usage and cost data are fully generated by local statistics. Because the official APIs do not provide the corresponding endpoints, plugin data may differ slightly from official billing (e.g., pricing tiers).
  • Key security: The API Key is stored only in the host process credential store ~/.dsh/.credentials.yaml. All POST write operations (saving configuration, refreshing, etc.) validate the Origin header to prevent Key leakage through cross-site CSRF attacks.
  • Storage: Request logs are persisted in ~/.dsh/storages/deepseek_requests.db. Financial projections are hidden when there is insufficient data.

Summary

dsh-deepseek-console addresses the pain points of DeepSeek account management in DSH, integrating official balance queries with local usage statistics into a unified console and HUD. It helps developers achieve fine-grained cost control and monitoring.