zh667/TokenLedger
123Last commit Aug 15, 2026
TokenLedger DSH plugin
TokenLedger tracks token usage and cost for DeepSeek Harness Web GUI, attributing each request to the relay site that served it. It automatically discovers relay sites from the host's provider configuration, requiring no manual setup. The plugin provides a dashboard panel and command-line interface for viewing usage, balances, and diagnostics.
How to install the TokenLedger DSH plugin
dsh plugin --profile web add "github:zh667/TokenLedgerCopying does not run this command. Review the repository and version before installing the TokenLedger DSH plugin.
TokenLedger DSH plugin data source
TokenLedger DSH plugin snapshot date: Aug 16, 2026
discovered
What the TokenLedger DSH plugin can do
- Attribution of token usage to relay sites (by baseURL origin)
- Zero-configuration discovery of relay sites from provider settings
- Balance queries for DeepSeek official, New API, Sub2API, Moonshot, Kimi, Zhipu GLM, Z.ai, and OpenRouter
- Usage analysis with today/this month/cumulative windows, drill-down by site/model, cache hit rate, and yearly heatmap
- Cost estimation with time-segmented rate tables, bucket pricing, and peak/off-peak periods
- CSV/JSON export, index health diagnostics, and explicit unknown attribution rows
Where the TokenLedger DSH plugin fits
- Track token usage and costs across multiple relay sites in a single Harness instance
- Identify which relay site is consuming the most tokens and associated costs
- Diagnose unaccounted usage chunks and index health issues
- Export usage data for billing or auditing purposes
- Monitor balance for multiple provider accounts without leaving the Harness dashboard
Who the TokenLedger DSH plugin is for
- Users of DeepSeek Harness Web GUI who manage multiple relay sites
- Administrators needing to allocate costs per relay site or per model
- Developers integrating token accounting into custom workflows via the library API
TokenLedger DSH plugin limitations
- Only works with the `web` profile of DeepSeek Harness (requires `dsh >= 0.1.0-rc.6`)
- Balance query for OpenRouter requires a Management Key, not a regular API key
- New API provider treats each API key as a separate quota account (no aggregation)
- Rate tables for cost estimation must be manually configured; unconfigured models show dashes
TokenLedger DSH plugin: from the repository README
Quoted from the zh667/TokenLedger README, the upstream source of the TokenLedger DSH plugin. Copyright remains with the original authors.
把 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 Token 用量算清楚，并归属到**实际服务这次请求的中转站**——不用配置，不用凭据。 Token-usage accounting for the DeepSeek Harness Web GUI (`dsh web`), attributed to the relay site that served each request. Zero configuration.  > 展示图使用演示数据与本机模拟中转站；面板上的每个数字都由真实代码路径算出，只是数据是造的。插件不会把 API Key 或上游原始响应发送到浏览器。 ## 一眼看懂 / At a glance | | 能力 | 说明 | | --- | --- | --- | | 🎯 | **中转站归属** | 按 provider 的 `baseURL` 归一化 origin 分组——同一站的多把 key 合成一行，站名就是域名，不是你自己起的路由别名 | | 🔍 | **零配置发现** | 从宿主的 provider 配置里读出中转站，不用你再填一遍。只读 `baseURL`，绝不碰旁边的凭据 | | 💳 | **余额** | DeepSeek 官方、New API、Sub2API，每个账户一把普通 key 即可；不限额度的 key 报"已用"而不是假余额 | | 📊 | **用量分析** | 今日/本月/累计三窗口、按站点/模型下钻、缓存命中率、一年活跃度热力图（悬停看当天模型构成） | | 🧮 | **费用估算** | 生效日期分段的费率表、分桶计价、峰谷时段；未定价的模型显示破折号而不是 0 | | 🗂 | **导出与诊断** | CSV / JSON 导出，索引健康度，归因不上的行数单独列出 | | 🔒 | **只读回环** | 两个端点仅接受回环 GET，且在 peer socket 地址上设防；从不读取提示词、工具参数或响应内容 | ## 快速安装 / Quick start 需要 DeepSeek Harness `web` profile（`@deepseek-ai/dsh >= 0.1.0-rc.6`）。 ```bash dsh plugin --profile web add "github:zh667/TokenLedger" ``` 重启已经在跑的 `dsh web`，浏览器硬刷新。侧边栏底部会出现「用量账本」入口。 升级或卸载： ```bash dsh plugin --profile web update dsh
Read the full READMERepository license: MIT
TokenLedger DSH plugin questions
How do I install TokenLedger?
Run `dsh plugin --profile web add "github:zh667/TokenLedger"` in your terminal. Make sure you have DeepSeek Harness `web` profile installed (requires `@deepseek-ai/dsh >= 0.1.0-rc.6`). Then restart your running `dsh web` process and hard-refresh the browser. The 'Usage Ledger' entry will appear in the sidebar.
Do I need to configure anything after installation?
No, TokenLedger works out of the box with zero configuration. It automatically discovers relay sites from your Harness provider settings. The only exception is balance queries for OpenRouter, which require a Management Key (not a regular API key). If you want to override relay discovery or add custom rate tables, you can edit your `settings.yaml` file.
Which relay sites and providers are supported for balance queries?
TokenLedger supports balance queries for DeepSeek official, New API (and its forks like One API, VoAPI), Sub2API, Moonshot/Kimi, Zhipu GLM/Z.ai, and OpenRouter. For most providers, only a regular API key is needed. OpenRouter requires a Management Key. The provider type is automatically detected from the baseURL fingerprint.
How does TokenLedger handle failed requests that still consumed tokens?
TokenLedger correctly accounts for tokens consumed even when the request fails. It tracks usage from `assistant/chunk` events (which contain usage data) and ensures that if a request fails after reporting usage, the tokens are still attributed. This prevents systematic undercounting.
Can I export usage data from TokenLedger?
Yes, you can export usage data in CSV or JSON format using the command `/tokenledger export csv <days>` or `/tokenledger export json <days>`. The export includes all usage data for the specified time period. Additionally, you can run diagnostics with `/tokenledger diagnostics` and reindex with `/tokenledger reindex` if needed.