dsh-tokbook
DeepSeek Harness（DSH）的跨会话令牌使用记录。宿主端将提供商用量汇总到持久化账簿中；浏览器端通过侧边栏页脚按钮 + shell 覆盖层显示。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:a285292107s/dsh-tokbook#2955c0c65ada47ed43e68be491ba21e893b0c94fTokbook 以 dsh-tokbook 发布，当前版本为 0.1.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Doc meta · role: entry · language: en · status: current · last-reviewed: 2026-10-19 · supersedes: —
A cross-session token-usage ledger for DeepSeek Harness (DSH). The host half folds every billed model call into one row of a local, per-day JSONL ledger and aggregates it with costs; the browser half shows it from a four-tab overlay behind a sidebar-footer button, plus a 词元 / Tokens page that the conversation view ring gains for a single session.
| Light | Dark |
|---|---|
| The overview tab in the light skin | The overview tab in the dark skin |
All screenshots come from the preview bench, so the numbers are fixture data, not a real ledger.
The UI is in Chinese (zh-CN), built by and for a Chinese-speaking DSH user; labels and hints are not translated. Data is plain JSON / JSONL in a directory you choose.
Needs DSH (dsh --version) and pnpm 11 on your PATH.
dsh plugin --profile web add github:a285292107s/dsh-tokbook
web is the profile you install into — substitute your own. This package is a dsh.bundle package:
dsh.bundle.patch in package.json points at the bundled cordis.patch.yml, and DSH selects that layer
into the profile after a successful install. Its patch inserts the tokbook row, so do not add an
insert row by hand. The data directory defaults to $DSH_HOME/tokbook/ and collection starts with no
configuration; add a config: block only to change something (see Configuration), with an override
example in cordis.patch.example.yml.
Restart dsh web and refresh — the entry button appears at the bottom of the sidebar
(sidebar.footer.action).
The repo carries the built lib/, so installing runs no build script and needs no allowBuilds edit in
the profile's pnpm-workspace.yaml. Rebuild (pnpm build) and commit lib/ after changing src/ (see
Development). The peer-dependency warning about @deepseek-ai/cordis is expected — DSH provides cordis
and the plugin resolves that same instance. To install from a local checkout, use
dsh plugin --profile web add ..
Migrating from the old plain-plugin install: the profile's cordis.patch.yml may still carry a
hand-written insert row (id: tokbook). Remove it before selecting this bundle, or the profile ends
up with two tokbook rows that share one id.
The host listens to the persisted session/event stream and writes one JSONL row per billed model call
into the data directory (default $DSH_HOME/tokbook/, override with path). Two rules shape every number
it reports:
usage, a compaction summary, a scheduled
retry, or a turn that ended in an error. When the provider reported no usage the row still exists and
still counts as a request; it just adds nothing to the token buckets. Unknown is not zero — nothing
is estimated.pricing.json maps route → exact model string → one current price.
Amounts split into actual spend (metered) and subscription value (subscription — what you
avoided paying, not cash) and never merge into a single "cost".A price is a single current value, so an amount answers what the tokens I used recently would cost now, not what an invoice said. That is why money is reported only for windows of 30 days or less; the all-time view reports tokens only. Tokens are facts, prices are not.
| Usage detail, the overview's second section | Subscription quota |
|---|---|
| Usage detail | The subscription quota tab |
| Pricing | Method |
|---|---|
| The pricing tab | The method tab |
Prices can also come from models.dev, a public USD catalogue: 查价 / lookup fuzzy-searches the selected model name for a candidate to fill, and 从 models.dev 补价 / sync fills gaps on USD routes the ledger has billed. Only first-party entries are trusted, and a hand-written price is never overwritten.
The conversation view ring gains a 词元 / Tokens view (conversation.view) that opens one single
session up by turn and by step over its whole lifetime.
parentSession but not a subagent, per the host header's origin —
never counts. No direct child, no block.model / wait / generation / tools / tok per s table.(route, model) pairs.It is read-only against the ledger and config — its only write is a content width in the browser — and needs no live session: it reads ledger rows plus the session's log on disk. A shared probe reads the host's ledger generation every 3 seconds and refetches only when it changed, falling back to a 15-second poll elsewhere; nothing is sent while the page is in the background.
Known degradation: attributing rows to turns and steps needs the host's
sessionPersistence. Without it the numbers still arrive, but every non-compaction row lands in an "unknown turn" block and the charts and session-time block do not render at all. The subagent block needs it for lineage and is omitted entirely — "cannot tell whether there are children" is not "there are none". Timings are local wall-clock, not billed duration.
Every key under config: on the mount row is optional:
config:
path: D:/data/tokbook # default: $DSH_HOME/tokbook (or ~/.dsh/tokbook)
recordCompaction: true # default true — record compaction/summarize calls as rows
plans:
opencode-go: # keyed by provider route
enabled: false # a plan is used as soon as a usable API key exists, unless disabled
apiKey: '...' # literal key, checked first
apiKeyEnv: OPENCODE_GO_API_KEY # else a credential reference name; defaults to the route's own
A second patch targeting id: tokbook replaces that row's config wholesale, so restate every key
you want to keep.
The quota tab fetches with your key but never estimates locally, and the browser half never holds the key.
A key without an active subscription is not an error: a balance-only provider gets a balance card, and
one that reports window percentages without a plan (OpenCode Go answering 403 for a valid key) gets a
none card. Only an endpoint that actually answered derives a gate — a timeout or 5xx is unknown,
never "no subscription".
The dot on the sidebar button comes from the last successful snapshot and calls no provider API itself.
The data directory has one writer: startup writes an owner.json marker (pid and start time) and warns
instead of taking over when a live foreign process owns it, while a stale marker is taken over silently.
Run a second host on its own path. Deleting pricing.json keeps the ledger but prices every row as
unknown (¥0).
assistant/attempt — an attempt that ended without producing a visible message — is not projected, so a
failed attempt whose adapter reported usage only on the attempt stream is not recorded.docs/DESIGN.md §5.pricing.json is written by hand or filled from models.dev one candidate
at a time. Route aliasing and vendor grouping are not modelled.Source of truth is src/ — host in src/*.ts, browser in src/client/*.tsx; lib/ is the build output
committed to git so installs run no build script.
pnpm install
pnpm build # tsc emits types, then esbuild bundles host + client
pnpm typecheck # src/ only
pnpm test # smoke (pure logic) + selfcheck (ledger) + selfcheck:ui (UI static bans)
pnpm build is a product, not a check: run it when you want a src/ change to show up in a host or the
preview bench. pnpm ledger serves the same page against a real ledger directory, and without --ledger
it becomes the fixture bench these screenshots came from (?dark=1, ?tab=, ?view=tokens, ?quota=).
The Chinese README (README.zh.md) carries the src/ layout tree and the development
loop. The contracts that keep the numbers honest are in docs/CONTRACTS.md; the
reasoning behind the shape is in docs/DESIGN.md; the map starts at
docs/INDEX.md.