In the DSH (DeepSeek Harness) ecosystem, everything is a plugin. For developers, real-time visibility into token consumption and cost is a daily development necessity. Existing official bills are often delayed or nested too deeply to be checked quickly. The dsh-usage-footer plugin aims to provide a lightweight monitoring entry point for the DSH Web interface, condensing usage statistics, cost estimation, and peak/off-peak period information into a floating panel in the lower-right corner.

Plugin Overview

This is a usage and cost monitoring plugin designed for the DeepSeek Harness Web interface. The plugin provides a coin-style floating button in the lower-right corner of the page. Hovering or clicking it opens the usage panel, allowing you to view account balance, peak/off-peak periods, current-session token statistics, today’s estimated spend, and comparisons between the local ledger and official data. It also provides a one-click toggle in settings. Maintained by 1514100951, licensed under MIT.

Core Features

  • Floating Button and Status Indicator: A coin badge button appears in the lower-right corner of the page. The outer ring and corner indicator color show the current period: green for idle, amber for peak (with a breathing animation), and red for balance query failure.
  • Hover Popover: Mouse hover triggers the popover, which appears after a 120 ms delay, with a 260 ms close grace period. Content includes:
    • Account Balance: From the official API GET https://api.deepseek.com/user/balance, refreshed every 60 seconds, including a breakdown of top-up and gifted credit.
    • Peak/Off-Peak Periods: Determined in real time based on Beijing time, displaying a 24-hour peak/off-peak bar (peak periods are 9:00-12:00 / 14:00-18:00).
    • Current Session Usage: Cumulative tokens are shown as four bar items: input (uncached), cache hits, cache writes, and output.
    • Local Ledger: Records today’s/this month’s token usage and amount based on DeepSeek’s official price list; only records usage after the plugin is enabled.
    • Official Comparison: After configuring DEEPSEEK_PLATFORM_TOKEN, displays the local ledger and the platform.deepseek.com official summary side by side.
    • Today’s Estimated Spend: Estimated from balance snapshot deltas; intended only as a fallback.
    • Local Today’s Usage: Accumulated after session deduplication; not official billing data.
    • This Month’s Usage/Cost: Preferentially displays the official platform summary; otherwise displays the local ledger summary.
  • Settings Toggle: In DSH’s “Settings → General”, a “Usage and Cost Bar” toggle is provided and takes effect immediately. After it is turned off, polling stops and { disabled: true } is returned.
  • Visual Adaptation: The panel uses a frosted glass effect, leverages the host’s --dsw-* design tokens, and automatically adapts to light/dark themes.

Installation and Prerequisites

Environment Requirements

  • DSH Version: >=0.1.0-rc.8 <0.2.0
  • Node.js Version: >=20 <27

Installation Command

dsh plugin --profile web add github:1514100951/dsh-usage-footer

After installation, restart the process and run dsh web.

Prerequisite Credentials

  • Required: DEEPSEEK_API_KEY is used to retrieve account balance data.
  • Optional: DEEPSEEK_PLATFORM_TOKEN is used to retrieve official platform summary data for comparison with the local ledger.

Feature Descriptions and Limitations

  • Local Ledger Storage: Local ledger data is persisted to $DSH_HOME/storages/usage-footer-ledger.json, but only records usage after the plugin is enabled and does not retroactively track history.
  • Spend Estimation Logic: Today’s estimated spend uses the “first balance snapshot queried on the day minus the current balance” method; it is only a fallback and may be affected by top-ups, gifted credits, and balance settlement delays.
  • Local Statistics: Local today’s usage is unofficial data, stored in localStorage (key name: dsh-usage-footer.today.v1), reset every day, and accumulated after session deduplication.
  • Security and Network Limitations: The GET /usage-status endpoint is bound only to 127.0.0.1, loopback is validated in the route, and LAN access is rejected. The plugin only accesses api.deepseek.com and, optionally, platform.deepseek.com.

The plugin registers via Bundle Patch and does not replace, shadow, or disable any official component.