Introduction¶

DeepSeek Harness (DSH) is a plugin-based agent development framework. In everyday use, monitoring the official API balance and token consumption is a must-have requirement. Existing solutions often require additional background processes or cross-origin calls, which is not lightweight enough. This plugin integrates natively into the sidebar, reads DSH session logs directly to aggregate token usage data, and queries the official balance in real time.

What Is This?¶

This is a lightweight DSH sidebar plugin maintained by lurejewel and licensed under the MIT License. It does not rely on a standalone daemon or database, and fully leverages DSH’s existing installation environment and credential service. Its main features are displaying the official DeepSeek balance and token usage history based on local session logs.

Core Features¶

This plugin includes the following core capabilities:

1. Official balance lookup: Uses DSH’s existing DEEPSEEK_API_KEY to send a request directly to api.deepseek.com/user/balance. The API key is never stored in the browser; all calls are completed on the server side.
2. Token usage history: Scans log files under the $DSH_HOME/sessions directory, aggregates input, output, and cached token data by day, and supports displaying today’s total, the daily average, and the cache hit rate.
3. Sidebar integration: Registers a trigger at the bottom of the left sidebar. When expanded, it displays a label; when collapsed, it displays an icon. Clicking it displays the data in a modal dialog.
4. One-click top up: Provides a “Top up” button next to the refresh button. Clicking it opens the official billing page directly.
5. Zero footprint: No daemon, no extra configuration, and no database. All data comes from the current DSH installation.

Installation and Enablement¶

Before installing, ensure that the environment meets the following version requirements:

Run the following command to install the plugin:

dsh plugin --profile web add dsh-usage-plugin

After installation, restart the dsh web process for the change to take effect. Then, hard refresh the browser with Cmd/Ctrl + Shift + R to see the usage icon at the bottom of the left sidebar.

Typical Usage¶

The plugin interacts with the backend API through the sidebar panel.

Sidebar Operations¶

• Refresh: Click the icon or the refresh button to fetch the latest data. Use the fresh=1 parameter to bypass the short-term result cache.
• Top up: Click the top-up button to navigate to the official top-up page.

API Endpoints¶

The plugin exposes two HTTP endpoints, sharing process-level token authentication with DSH’s other /api endpoints:

• Query balance:

    GET /api/dsh-usage/balance

• Query stats:

    GET /api/dsh-usage/stats?days=N

where `N` is the number of days to query, defaulting to 7 and limited to a range from 1 to 90.

Use Cases and Notes¶

This plugin is suitable for DSH users who need to check their balance and token consumption frequently while developing or using DSH.

Notes:
1. Data source security: Balance queries are performed on the server side, so the key is not exposed to the frontend. Token history only reads local logs and does not involve third-party network calls.
2. Performance optimization: Session log scanning runs in a Worker thread, so it does not block DSH Web server’s main event loop, preventing health checks from incorrectly reporting the service as down.
3. Version compatibility: Requires DeepSeek Harness version >= 0.1.0-rc.7.

Conclusion¶

By using a native sidebar, this plugin addresses the pain points of balance lookup and historical token statistics while maintaining a lightweight, zero-configuration design. See the plugin repository for the source code and installation details.