dsh-token-watch
A DeepSeek Harness plugin that watches every session's token
usage and pops a whale-styled desktop alert when a threshold is crossed — a small white
speech bubble with a dark-navy outline and the whale mascot, in the corner of your screen.
It rides the host's own session/event stream, so there is no log tailing, no startup script
and no second process to keep alive. Every workspace, every new session, is covered
automatically.
Windows only for the desktop alert. On other platforms the plugin still logs and keeps
running; it just skips the popup.
What it watches
| Rule | Default | Meaning |
|---|
singleCost | ¥0.30 | a single message costs more than this |
singleTokens | 300,000 | a single message carries more than this many tokens |
win5mCost | ¥1.00 | spend in the last 5 minutes |
win1hCost | ¥3.00 | spend in the last hour |
win10mMsgs | 12 | assistant messages in the last 10 minutes (runaway tool loops) |
cacheRatio | 98% | cacheRead / total above this, for messages ≥ 500k tokens |
The same rule alerts at most once every cooldownMs (default 10 minutes), so a busy loop
does not turn into a notification storm.
Cost is an estimate: prices are USD per 1M tokens from the host's
providers/data/deepseek.json, converted with usdCny. It is not a bill.
Install
Client (Electron app): 插件 → + 添加插件, paste the package name (or a local directory
path while developing), install, then 立即启用.
CLI profiles can use the normal plugin command:
dsh plugin --profile web add dsh-token-watch
The desktop profile is owned by the Electron app and refuses the CLI
(profile "desktop" is managed exclusively by the Electron application), so use the UI there.
Fresh releases: npm needs a few minutes to propagate a brand-new package to its CDN.
Until then pnpm add fails with ERR_PNPM_FETCH_404 ... .tgz even though the metadata page
already renders. The China mirror (registry.npmmirror.com) syncs later still — pick
npm 官方源 in the install dialog, wait a few minutes, then retry.
Do not uninstall a link: install while keeping it as your working copy. The client's
plugin manager deletes the linked directory when the plugin is removed. Recover it from the
published tarball (npm pack dsh-token-watch) or from git.
Configure
Thresholds and behaviour are plugin config, set in your profile's cordis.patch.yml:
- id: dsh-token-watch
name: dsh-token-watch
config:
notify: true
usdCny: 7.2
thresholds:
singleCost: 0.3
singleTokens: 300000
win5mCost: 1.0
win1hCost: 3.0
win10mMsgs: 12
cacheRatio: 0.98
cacheMinTokens: 500000
cooldownMs: 600000
# Extra or overridden prices, USD per 1M tokens:
# prices:
# my-model: { input: 0.3, output: 1.2, cacheRead: 0.006 }
| Option | Default | Notes |
|---|
enabled | true | set to false to load the plugin but do nothing |
notify | true | false keeps logging only |
restoreState | true | restore today's totals from state.json on reload |
usdCny | 7.2 | exchange rate for the estimate |
logDir | $DSH_HOME/logs/token-watch | one file per day |
prices | built-in table | per-model overrides / additions |
Unknown models are counted for tokens and message rate but cost nothing, so the estimate
never silently invents a price.
Why there is no historical replay
The session logs are multi-frame zstd. The Node bundled with the Electron host (24.21) only
decodes the first frame, so replaying them from inside the plugin would silently undercount.
The plugin persists a small state.json and restores today's totals from it instead; a fresh
install starts counting from zero at load time.
Output
- Log:
~/.dsh/logs/token-watch/token-watch-YYYY-MM-DD.log, one line per message plus a
minute heartbeat. Same format as the standalone token-watch.mjs this plugin replaces.
- State:
~/.dsh/token-watch/state.json — today's totals, so a host restart does not reset
the daily counter.
- Desktop alert:
assets/notify.ps1, a borderless WPF window (white bubble, #2A3A6B outline,
circular whale avatar). It falls back to a WinRT toast, then to a tray balloon.
Clicking the bubble opens today's log in Notepad. It closes itself after 10 seconds.
Self-test
npm run selftest
Drives the plugin with a fake context and one synthetic expensive message, so you can see the
alert immediately without waiting for a real threshold. It uses a temporary DSH_HOME, so your
real log and totals are untouched — the popup is real.
Notes
- The plugin reads only
usage numbers from session events; it never stores message text.
- It lives inside the host process, so it only runs while DeepSeek Harness is running.
If you also want monitoring with the app closed, keep the standalone daemon instead.
assets/notify.ps1 must stay UTF-8 with BOM — PowerShell 5.1 reads a BOM-less file as GBK
and mangles the Chinese strings.
License
MIT
