@y2zyyr/dsh-token-usage-sidebar
面向 DeepSeek Harness 的持久化令牌使用量洞察，由可扩展且持久的 SQLite 账本提供支持。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:y2zyyr/dsh-token-usage-sidebar#dfa3847d9ab4208e694653e492fdba2f2f0e756f
Token Usage Sidebar 以 @y2zyyr/dsh-token-usage-sidebar 发布，当前版本为 1.1.6。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 简体中文
A community DeepSeek Harness (DSH) web-profile plugin that keeps provider-reported token usage locally. It provides both a persistent sidebar summary and a native Token Usage settings page.
TOKEN USAGE
Today …
Yesterday …
Total …
This is a community plugin, not an official DeepSeek plugin.
node:sqlite, WAL journal) instead
of a monolithic JSON root. A new invocation is one small row-level upsert, so write
latency stays effectively flat no matter how many historical records accumulate.Recommended package: @y2zyyr/dsh-token-usage-sidebar (published on the npm registry).
Install the plugin into the DSH web profile, then restart DSH:
dsh plugin --profile web add @y2zyyr/dsh-token-usage-sidebar
# Restart `dsh web` after installation.
dsh plugin accepts the scoped package name directly; the plugin is added to the
profile's bundle list and its loader entry keeps the stable id token-usage-sidebar.
You can also ask an agent that can access your DSH installation to install the npm
package @y2zyyr/dsh-token-usage-sidebar into the web profile (source: https://github.com/y2zyyr/dsh-token-usage-sidebar). Review
third-party source before authorizing an agent to install it. Pin a commit when your
workflow requires a reproducible dependency revision.
The package can be installed from npm directly:
npm install @y2zyyr/dsh-token-usage-sidebar
GitHub is the source repository (code, issues, release history, source inspection): https://github.com/y2zyyr/dsh-token-usage-sidebar
A direct GitHub install also keeps working
(dsh plugin --profile web add github:y2zyyr/dsh-token-usage-sidebar), but the npm
scoped package is the recommended distribution channel.
Update the installed plugin, then restart DSH:
dsh plugin --profile web update @y2zyyr/dsh-token-usage-sidebar
# Restart `dsh web` after updating.
The plugin is versioned on npm with semantic versions.
Removing the plugin does not reset its separately persisted local accounting data.
dsh plugin --profile web remove @y2zyyr/dsh-token-usage-sidebar
# Restart `dsh web` after removal.
Existing v1.1.0 installs keep their complete ledger. Switch the profile bundle from the old package name to the scoped one — the plugin keeps the same loader entry ID, exported plugin name, client module ID, and SQLite ledger path, so no data migration is needed:
dsh plugin --profile web remove dsh-token-usage-sidebar
dsh plugin --profile web add @y2zyyr/dsh-token-usage-sidebar
# Restart `dsh web` after the switch.
DSH/provider usage records
↓
historical and live collection
↓
deduplication
↓
persistent local accounting
↓
sidebar summary
The plugin uses provider/runtime-reported usage records rather than tokenizer estimates. Total is input + cache read + cache write + output; Reasoning is displayed as an output subdivision and is never added to Total a second time. It uses the final committed assistant message's message.source.provider and message.source.model when available.
All day-based ranges use the DSH host's local calendar days. Last 7 days includes today plus the previous six local days. The settings page receives aggregate results only; it never receives the individual invocation ledger.
Provider options are discovered from the aggregate data in the selected range and are matched exactly. A user whose ledger only contains my-company-api sees that name; an empty preset-provider option is never added. Different spellings remain separate, and there is no separate alias form to fill in. Any legacy alias table left by an older release is retained for storage compatibility but is not exposed in the settings UI.
The plugin also performs a narrow automatic discovery pass in the DSH
storages directory. It recognizes plugin-owned token record units, including
partitioned day ledgers from earlier local builds, and imports their invocation
details by the canonical sessionId:turn:step identity. Aggregate-only
summaries are used for verification and are never imported as extra calls.
Discovery is read-only against its sources and idempotent across restarts; it
does not scan the general filesystem or require a manually configured path.
v1.0.0/v1.0.1 performs one idempotent replay of recoverable persistent DSH session events to enrich existing calls with their exact buckets and model metadata. A previously recorded call is only enriched, or replaced by a higher-sequence final message: it is not added to lifetime usage again.
Some legacy calls may have a reliable All time total but no recoverable date, bucket, provider, or model. Those tokens remain included in All time and are explicitly shown as unclassified coverage. They are never invented into a date or model row.
History reporting is honest (v1.0.1). The plugin keeps two distinct signals:
Total's meaning: Lifetime Total is the deduplicated union of every authoritative usage record the plugin recovered from durable sources plus usage recorded after tracking began — it reflects what the plugin can recover, not a claim about the DSH account's full lifetime usage when not all history is provably recoverable.
On first startup after upgrading to v1.1, the plugin detects the v1.0.1 JSON ledger and:
.pre-v1.1-<timestamp>.bak
file in the same data directory.sum(records) == global).The migration is idempotent: a completed migration is a no-op on later restarts, and no records are duplicated. New usage recorded after cutover is exactly-once.
See docs/migrations/v1.0.1-to-v1.1.0.md for the full design.
Usage accounting stays local to the DSH runtime. The source repository does not receive, contain, or upload a user's token ledger. Runtime persistence is separate from the source code and release artifacts.
The plugin stores accounting metadata needed for reliable totals, such as deduplication identity, date bucket, and token totals. It does not persist prompts, assistant text, tool output, API keys, credentials, or conversation content as part of its ledger.
${DSH_HOME:-~/.dsh}/storages/dsh_token_usage_sidebar.sqlite, plus its WAL/shm
companions. The exact path respects the DSH_HOME environment variable when set.
It is never the source repo or the package install directory, so it survives
upgrades, re-installs, and restarts.sessionId:turn:step),
token bucket totals, provider/model labels, local dates, and accounting metadata.
It never stores prompts, assistant text, tool output, API keys, credentials, or
conversation content..pre-v1.1-<timestamp>.bak file in the same directory. The v1 source is never deleted.Current release: v1.1.6 (npm package @y2zyyr/dsh-token-usage-sidebar; source on GitHub).
Verified with DeepSeek Harness 0.1.0-rc.6 and its web profile, on a runtime whose
Node.js provides the built-in node:sqlite module (Node with node:sqlite).
No broader DSH-version or operating-system compatibility is claimed. Running against
later desktop builds (e.g. DSH Desktop 2.0.0 / Node 26) has been observed locally but
is not formally claimed.
sessionId:turn:step; the final
committed assistant/message.usage supersedes an earlier assistant/chunk sample, and
replays/duplicates never double-count (higher-seq wins).usage_records is authoritative; aggregate tables are a
derived, rebuildable cache. If an aggregate drifts, it is rebuilt from records.npm install
npm test
npm run build
npx tsc --noEmit # typecheck (v1.1 adds this gate)
npm test runs the accounting, historical-recovery, insights, durable SQLite, migration,
and property/equivalence tests. npm run build writes the shipped host and browser
bundles to lib/ and keeps the root-compatibility client.js byte-aligned. GitHub
Actions CI (.github/workflows/ci.yml) runs npm ci, npm test, npm run build, and
a git diff --exit-code so committed artifacts must always match source.