Introduction¶
DeepSeek Harness (DSH) uses a plugin-based architecture and supports extending functionality through plugins. In local development or usage, aggregating global token consumption is a common requirement. The dsh-token-usage plugin is designed to address this issue. It scans local session logs, aggregates the historical total token consumption of all DSH sessions on the local machine, and provides multi-dimensional statistical views, solving the problem that statistics for a single session cannot reflect overall cost.
Core Features¶
The plugin provides the following core capabilities:
- Cross-session aggregation: Supports aggregating data across sessions, across workspaces, and across DSH homes.
- Accurate deduplication: Performs global deduplication based on
message.id, avoiding inflated data caused by session copies (such as v0/v3, resume/fork). - Multi-dimensional grouping: Supports grouping statistics by day, model, Provider, project, or session.
- Date range: Supports custom date ranges or quick options such as all/today/last 7 days/last 30 days.
- Provider quota: Supports statistics by provider (Provider) for quotas, with configuration for enable switch, quota value, and refresh date.
- Multiple outputs: Provides both HTTP API and command-line reports to retrieve data.
Installation and Activation¶
The plugin uses local installation. It is recommended to install it into the Desktop profile:
dsh plugin --profile desktop add /Users/d/Personal_Project/dsh-token-usage
After installation, restart DSH Desktop to apply the configuration.
Usage¶
1. Settings Page Configuration¶
After restarting, go to Settings → Token Statistics. On this page, you can configure the total card, statistics scope, grouping method, and provider quota statistics.
2. HTTP API¶
The plugin provides a local loopback API for secondary development or script calls. Common endpoints are as follows:
# 获取汇总数据（按天分组）
GET /dsh-token-usage/summary?range=all&groupBy=day
# 获取接入方额度信息
GET /dsh-token-usage/quota
The supported range parameters include all, today, 7d, 30d, month, and cycle; the groupBy parameter supports day, model, provider, project, and session.
3. Command-Line Reports¶
No DSH process is required. You can directly run the Node.js script to generate reports:
# 生成近30天报表
node scripts/report.mjs --range 30d
# 按指定维度分组
node scripts/report.mjs --group day,model,project
Technical Details and Notes¶
- Statistics basis: Only the
usagefield inassistant/messageis counted; duplicate reports fromassistant/chunkare ignored. compaction/summary are not counted by default. - Performance: The plugin scans faster through a caching mechanism; a full scan takes about 1.4s.
- Dependencies: The Host side depends only on built-in Node.js modules and does not import
@deepseek-ai/*; the Client side uses only React.
Overall, dsh-token-usage is a lightweight, statistics-focused DSH plugin, suitable for developers who need to accurately understand local token consumption. The plugin is under the MIT license, and its source code is hosted on GitHub. For more details, visit the plugin directory.
