dsh-month-tokens
侧边栏计数器，用于统计一个日历月内提供商报告的令牌使用量：此 DSH home 加上 opencode，仅使用本地数据，并在每月 1 日 00:00 重置。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:greyhackintoch-dev/dsh-month-tokens#082b4ff03372c7b50d316b44847fecea66b0ffa4Month Tokens 以 dsh-month-tokens 发布，当前版本为 0.5.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A DeepSeek Harness plugin that puts one calendar month of token usage in the sidebar, directly above Settings. It counts this DSH home and opencode, reads only local data, and resets at 00:00 on the 1st.
┌──────────────────────────────┐
│ ▮▮ 本月消耗Token 3.61亿 │ ← this plugin
│ ⚙ Settings │
└──────────────────────────────┘
Click the row for the breakdown.
dsh plugin --profile web add github:greyhackintoch-dev/dsh-month-tokens
No build step, so there is no allowBuilds approval to answer. Restart
dsh web afterwards.
Prefer not to touch a terminal? Paste this into any DSH session:
Install the dsh-month-tokens plugin by running:
dsh plugin --profile web add github:greyhackintoch-dev/dsh-month-tokens
Then confirm dsh-month-tokens appears in ~/.dsh/profiles/web/package.json
under dsh.profile.bundles, and remind me to restart dsh web for it to take
effect.
The command writes outside the agent's workspace sandbox, so expect a single
approval prompt. dsh plugin reconciles the package into dsh.profile.bundles
by itself — the bundle declares dsh.bundle, so its cordis.patch.yml is
applied with no further configuration.
web profile)The browser half runs in a page with a real origin. Two consequences:
The official DSH Desktop app is not supported. dsh plugin refuses its
reserved profile outright:
$ dsh plugin --profile desktop add github:greyhackintoch-dev/dsh-month-tokens
error: profile "desktop" is managed exclusively by the Electron application
Installing it there by other means would not help either. The browser half
streams over a plain HTTP route (GET /token-ledger/stream), while the Electron
shell loads the frontend from file:// and carries every bit of DSH's own
client I/O through window.__DSH_TRANSPORT__ instead. Under file:// a relative
URL has no host to resolve against — the shell's own code detects this, since
location.origin is the string "null" — and nothing exposes the loopback port
to the renderer, so there is no absolute URL to fall back to.
Third-party desktop wrappers that embed the standard web profile do work. If the client is a BrowserWindow pointed at the local web GUI, it is an ordinary browser context, and the command above is all that is needed.
Most usage plugins show you a number. This one also tells you how much of the month it could not attribute, and refuses to invent the difference.
DSH ships no projection that buckets usage by day — every shipped unit is either
cumulative (tokenUsage) or a snapshot of the present (contextPressure,
contextBreakdown, sessionStats). A cumulative per-session figure cannot be
reconstructed into "how much of this happened after the 1st". So each session is
decided by the first rule that applies, and the rule used is reported:
| Rule | Condition | Result | Accuracy |
|---|---|---|---|
ledger | an optional per-day ledger covers the month | sum the days with this month's prefix | exact |
born | created at or after the 1st | its whole total | exact |
idle | created earlier, last user prompt before the 1st | 0 | exact |
split | created earlier and prompted this month | 0, and counted in unattributed | unknown |
A long-running session that spans the boundary lands in split, and that is
exactly the case where a naive counter silently reports too little. When any
session lands there, local.exact is false, local.unattributed says how
many, and the panel says so in the warning colour.
To resolve the remaining cases exactly, add a per-day activity projection. The
community dsh-context plugin contributes one named
contextActivity; when it is mounted, the ledger rule takes over
automatically and no session is left ambiguous. Measured on a real 79-session
home it covered 78 sessions exactly, the exception being a session checkpointed
before that plugin existed. This plugin has no dependency on it — it is an
optional upgrade, and everything works without it.
| Source | Where it comes from | Latency |
|---|---|---|
| This DSH home | per-session tokenUsage projections | live — pushed on every settled turn |
| opencode | its own SQLite database, read-only | a poll, up to ~1 minute behind |
Both are local. The plugin makes no HTTP request of any kind: opencode's calls never pass through DSH, so reading its database is the only way to see them.
opencode writes one row per assistant message into
~/.local/share/opencode/opencode.db, whose data JSON carries
tokens: { input, output, reasoning, cache: { read, write }, total }. The
columns line up with this ledger's vocabulary almost exactly:
| Ledger bucket | opencode field |
|---|---|
uncachedInputTokens | tokens.input — uncached; cache reads are separate |
cacheReadTokens | tokens.cache.read |
cacheWriteTokens | tokens.cache.write |
outputTokens | tokens.output + tokens.reasoning |
reasoning is the one translation: opencode reports it apart from output,
while DSH folds it in, so the two are summed to keep the rows comparable.
Rows are filtered by providerID (deepseek by default) and by
time_created >= 本月 1 日. The database is opened read-only and closed on every
poll — it is a third-party schema under active WAL writes, so holding a handle
buys nothing and risks a stale snapshot.
Requirements: Node 22.5+ for node:sqlite. On an older runtime the plugin
still runs; it reports that opencode cannot be read instead of quietly counting
zero.
Three limits worth knowing:
message.data is an opencode implementation detail that
any release can change. A schema that still queries but yields no token
fields is reported as drift, never as a smaller month.providerID: 'deepseek' names the provider, not the
credential. Same key in both tools → correct. Swap in a different DeepSeek
key in opencode and the two are silently merged.Override the location or the provider list in the plugin's entry:
- insert:
- id: token-ledger
name: 'dsh-month-tokens'
config:
opencodeDbPath: /custom/path/opencode.db
opencodeProviders: [deepseek]
DSH_TOKEN_LEDGER_OPENCODE_DB overrides the path when no config is given.
| Route | Body |
|---|---|
GET /token-ledger/stream | SSE; one ledger event per movement, plus : keep-alive every 25s |
GET /token-ledger/summary | the same payload as one JSON document |
{
"revision": 6,
"period": { "kind": "month", "key": "2026-09", "start": 1788192000000, "end": 1790294400000 },
"month": 361262338,
"totals": { "uncachedInputTokens": 3944544, "outputTokens": 2456933, "cacheReadTokens": 269710720, "cacheWriteTokens": 0 },
"local": { "total": 346169232, "month": 346169232, "monthSource": "mixed", "exact": true, "unattributed": 0 },
"tools": {
"opencode": { "state": "ok", "messages": 98, "fetchedAt": 1790231906819,
"totals": { "uncachedInputTokens": 1700628, "outputTokens": 77406, "cacheReadTokens": 13315072, "cacheWriteTokens": 0 } }
},
"sessions": { "counted": 79, "live": 2, "skippedSeeded": 0, "scannedAt": 1790229233573 }
}
month is the headline. totals is the all-time DSH bucket breakdown,
shown in the panel under a 本机历史累计（仅 DSH） caption. monthSource is
ledger, born, idle, mixed, or none; tools.opencode.state is
loading, ok, absent, drift, unavailable, or error.
curl -s http://127.0.0.1:3080/token-ledger/summary | python3 -m json.tool
The window is derived from the clock on every read:
start = 本月 1 日 00:00（本地时间）
end = 明天 00:00
There is no accumulated total and no reset job, so a process that slept through midnight on the 1st still reports the new month the moment it next looks, and no reset can be missed. A timer also fires at the boundary so an open panel turns over immediately rather than waiting for the next turn or rescan.
npm test # node test/host.test.mjs && node test/client.test.mjs
The suite is dependency-free, offline, and hermetic: it points the plugin at a path that cannot exist, so it can never read your real opencode database.
To mount a working copy instead of the installed package, insert it by absolute
path — dsh converts absolute paths inside insert rows to file URLs, and the
client-module scanner walks up from the entry file to the nearest
package.json:
- insert:
- id: token-ledger
name: /absolute/path/to/dsh-month-tokens/lib/index.js
Use either the bundle or the path insert, never both — the token-ledger id
would collide and the duplicate route registration would fail loudly.
Restart dsh web after editing the host half. Profiles with
patchReload: live recompose on a patch edit, but the host module is a plain
ESM import and stays in the module cache. The browser half is read from disk, so
a page refresh is enough for it.
lib/index.js — the host half. Folds DSH's projections, reads opencode, and
serves the two routes. No dependencies beyond Node builtins.client/client.js — the browser half, hand-bundled for the DSH client module
loader (window.__ModuleLoader__.load({ id, factory })). It requires only the
platform seed words react and react-dom, registers one entry into the
sidebar.footer.action list slot, opens one EventSource, and renders whole
values the host computed. No domain folding happens in the browser.Counts render in Chinese myriad units — 999, 2.95万, 2.77亿 — with the
exact integer on hover.
sessionPersistence.list() (a directory
walk plus a stat per session) and one in-memory cachedSnapshot per cold
session. No session log is ever read.COUNT/SUM over opencode's message table per minute.fetchedAt is deliberately excluded from the change comparison —
including it would bump the revision once a minute forever.The two routes answer without the dsh web launch-token exchange, because the
webserver's named-route table is not behind that guard. That is acceptable here:
the webserver binds to 127.0.0.1 by default, the payload is aggregate counts
rather than session content, and no access-control-allow-origin header is
sent, so a cross-origin page cannot read the body. If you deliberately expose
the GUI with networkExposure: 0.0.0.0, these two routes become reachable by
anyone who can reach the port.
The plugin reads exactly two things off disk: DSH's own session projections, and
opencode's message table. It never reads opencode's auth.json, never opens
that database for writing, and never puts a credential or a message body into a
payload or a log line — only counts.
MIT