DSH Cost Meter
DSH Cost Meter banner
English
·
简体中文
DSH Cost Meter is a DeepSeek conversation cost-tracking plugin for the DeepSeek Harness (DSH) Web GUI — price-snapshot-anchored per-turn cost (peak/off-peak aware), account balance, a cost view tab, per-message cost chips, and a header pill with live streaming estimates. Every step's cost, price band, and snapshot version are computed once from the pricebook snapshot effective at the usage event's own time and then never recomputed — a later price change never rewrites an already-written conversation row. Search is a standalone API billed per successful request, so the ledger also counts successful web_search calls and prices them at the official ¥5 / US$0.75 per 1,000 requests — free until 2026-11-01 00:00 Beijing, as the pricing page states. web_fetch uses the shipped local HTTP provider, which DeepSeek does not bill, so it stays free.
- Host half (
src/): DeepSeek GET /user/balance query, the persisted snapshot-anchored pricebook, the sessionCost projection plus the pricebook-free sessionCostIndex message index, subagent cost aggregation, and the trust-fenced /cost-meter route.
- Client half (
src/client/): composer-dock readout, Cost tab, per-reply chip, header pill, and the plugin configuration card — in Simplified Chinese and English.
Installation
The plugin is published on npm as @gamegeek-saikel/dsh-cost-meter and ships as an official DSH plugin bundle (both halves — host and browser — are mounted by a single cordis.patch.yml row).
Install it into a web profile with the official DSH CLI (via npx — no global installation needed):
npx @deepseek-ai/dsh plugin --profile web add @gamegeek-saikel/dsh-cost-meter
That installs the npm latest tag, which tracks the current DSH release line. This plugin publishes on the same three npm channels (latest, next, alpha) DSH itself uses, and a build only runs on the DSH line it was built for, so install the channel that matches your runtime:
| npm dist-tag | Tracks | Install command |
|---|
latest | the current DSH release line | dsh plugin --profile web add @gamegeek-saikel/dsh-cost-meter |
next | the upcoming DSH release line | dsh plugin --profile web add @gamegeek-saikel/dsh-cost-meter@next |
alpha | alpha builds | dsh plugin --profile web add @gamegeek-saikel/dsh-cost-meter@alpha |
npm dist-tag ls @deepseek-ai/dsh shows which DSH version serves each line, and npm view @gamegeek-saikel/dsh-cost-meter dist-tags shows which plugin version serves it. A DSH runtime refuses to load a bundle whose peer ranges reject it, so picking the wrong channel fails the install outright rather than half-loading the plugin.
Then start the harness:
npx @deepseek-ai/dsh web
If you have the DSH CLI installed globally, you can also use dsh instead of npx @deepseek-ai/dsh. To install into another profile, replace web with your profile name. Each published version declares and is verified against the DSH line its channel names above. The host half requires Node ^22.19.0 || >=24.0.0 and pnpm 11.7.0 for development.
Overview
Chat costs in DeepSeek pricing change over time (list prices, USD→CNY exchange, the 2026-08-17 peak/off-peak rollout, and the 2026-09-10 model rename to deepseek-flash with its V4.1-Flash price cut), and a conversation spans many turns with cache-hit, cache-miss, cache-write, and output token buckets. Naively recomputing costs at current prices makes history drift every time the price table changes.
Cost Meter solves this with an append-only pricebook: every price/fx/band-table change starts a new immutable PricebookSnapshot (monotonic version, effectiveAt), and each usage event anchors to the snapshot effective at its own time. The result is an immutable per-step cost ledger that only grows — it never mutates. Live streaming estimates are explicitly labeled 估算/estimate because they use current prices; they are replaced by the exact anchored value once the step settles.
Key Properties
| Property | Value |
|---|
| Cost anchoring | Append-only pricebook snapshots; step cost computed once at the event's own time |
| Price sources | Manual override > official pricing page > built-in fallback > OpenRouter (fallback only, USD→CNY) > none |
| Official page | Parses the current 2026-09-10 combined zh/en tables (the deepseek-flash / deepseek-v4-pro columns with OFF-PEAK/PEAK cells per bucket row, and the English UTC schedule) as well as the earlier combined and legacy split tables; the retired deepseek-v4-flash and deepseek-v4-flash-vision-exp ids have no column of their own and bill at the Flash price, exactly as the page states. The built-in list still anchors single when the page no longer carries a pre-rollout table |
| Peak pricing | 2026-08-17 00:00 Beijing rollout; peak windows apply Monday–Friday only and exclude Chinese public holidays (the zh and en pages may state different timezones; fallback 09:00–12:00 / 14:00–18:00 Beijing), so weekends, holidays, and all other hours are off-peak at half price |
| Cost formula | Uncached input + cache reads (hit rate) + cache writes (billed at uncached input rate) + output, per 1M tokens, CNY |
| Account balance | Official GET /user/balance, cached 60 s, single in-flight request, trust-fenced route |
| Subagent support | Enumerates the conversation's durable subagent tree through subagents.listDescendants (nested delegations, settled children, and cold subagent sessions included, with no depth cap); a ledger is read from the resident session's projection when available and otherwise cold-restored from the child's stored log (sessionQuery.readSession + sessionProjections.restore), so historical subagent spend is also counted after a host restart; falls back to a BFS over the live agent tree when neither service is mounted |
| Conversation total | Main session + every descendant subagent (any depth); subagent totals still render while the main session's own ledger is not materialized |
| UI surfaces | Composer dock · Cost tab · per-reply chip · header pill (live estimate) · plugin configuration page |
| Locale | Simplified Chinese (source) + English |
| Complexity | Fully synchronous fold; O(1) price lookups via in-memory mirror |
Usage
Once installed, the plugin contributes five browser surfaces (all text shown in Simplified Chinese by default):
| Surface | Slot | Description |
|---|
| Composer dock readout | conversation.composer.dock | Anchored session spend + account balance, refreshed every minute; hover for the category breakdown and snapshot info |
| Cost view tab | conversation.view | Whole-conversation totals (main + every subagent nesting level), category totals, the per-subagent list with its depth, and the per-reply anchored ledger |
| Per-reply cost chip | conversation.chat.assistant-actions | The anchored cost of one finalized reply as the row's own stat capsule — the same trigger + anchored dialog the shipped 用量 and 用时 capsules use (28px pill, hover fill, aria-expanded dialog above the trigger). It closes the row's stat run: after 用量 and 用时, before the timestamp, spaced by the row's own gap, and coloured by the band that priced it (green off-peak, red peak). The dialog lists the three billed categories, the band with its multiplier, the model, and the snapshot version; the slot hands over the message id, which the sessionCostIndex projection resolves to ledger coordinates (dash — when unpriced) |
| Header pill | conversation.session.header.utilities | Anchored total, or a live ≈ ¥x.xx (estimate) while streaming; click for the detail panel |
| Plugin configuration page | plugins.row.config | The cost-meter row's page under 设置 → 插件 (DSH 0.2.0 hosts a plugin's own configuration there, keyed <package>#<row id>): per-model overrides, OpenRouter aliases, extra rest days and working days for the holiday calendar, cache-read discount, FX mode, toggles, and manual refresh. The editable fields are the schema's volatile() ones — the deployment fields (endpoint, credential reference, refresh cadence, trusted hosts, history cap) stay hand-edited in the profile patch, which is exactly the split DSH's configuration projection can write |
The /cost-meter host route serves the balance snapshot, the pricebook view, and the subagent totals over GET, and applies manual refresh over POST ({"action":"refresh"}). Like the /api fence, the route only answers requests whose Host header names a loopback address or a declared trusted host — the DNS-rebinding-safe check.
Pricebook & Snapshot Anchoring
The pricebook (src/pricebook.ts) is the durable price source, persisted on the pricebook storage-domain global slot:
- Priority chain — per canonical model key (
provider/model, bare model, or the flash/pro pricing key for DeepSeek-family models): manual override > official page > built-in fallback > OpenRouter (fallback only, USD→CNY, cache reads at the configured discount) > none.
- Snapshot selection —
snapshotForTime picks the newest snapshot with effectiveAt <= event time (pre-install sessions anchor to the first snapshot once).
- Peak/off-peak — before the 2026-08-17 rollout all steps price at the single list price; after it, the band is chosen by the EVENT's own time against the schedule of the pricebook's own page (the zh and en pages each parse their own peak windows — the redesigned English page states UTC — falling back to Beijing 09:00–12:00 / 14:00–18:00, everything else off-peak). The official pages restrict peak windows to Monday–Friday and exclude Chinese public holidays, so Saturdays and Sundays are off-peak all day in the schedule's own timezone, and so is every holiday in full — judged on the Beijing calendar date even under the English page's UTC windows. The dates come from the State Council notices, transcribed in
src/holidays.ts (2026, per 国办发明电〔2025〕7号); a year no notice covers yet falls back to the plain Monday–Friday rule, and the settings page's rest-day/workday lists patch the gap without waiting for a release. The 调休 working weekends stay off-peak, because the pages say Monday–Friday; list them as working days to bill them at peak. When the combined page has no legacy single-price column, single keeps anchoring to the built-in historical list; a page that still carries a separate legacy table wins. Each step's band is anchored once at fold time, so the per-reply cards and chips always show the band that round was billed at — never the band of the moment you are looking.
- Immutable ledger — the
sessionCost projection (src/session-cost-projection.ts) folds request/header (model) and usage-carrying events into per-step rows; a second usage sample for the same (turn, step) replaces the first (same-step finalization, not a re-price), with O(1) incremental totals. The companion sessionCostIndex projection (src/session-cost-index.ts) maps each finalized assistant-message id to its ledger coordinates; it reads no pricebook and computes no cost, so folding it can never re-price a session.
Project Structure
src/
index.ts # Host entry: apply() wiring, balance, route, trust fence
types.ts # Wire/public vocabulary + projection-map merge
pricing.ts # Official pricing-page parser, peak pricing, Beijing bands
pricebook.ts # Append-only snapshots, priority chain, storage domain
session-cost-projection.ts # sessionCost projection (immutable per-step ledger)
session-cost-index.ts # sessionCostIndex: message id → ledger coordinates
holidays.ts # Chinese statutory-holiday calendar + its deployment overrides
subagent-cost.ts # Subagent cost aggregation (durable tree + live-registry fallback)
invariant.ts # Route-disposer symmetry invariant companion
client/ # Browser half: 5 slot components + math/format/locales
shared/
tsdown.client.ts # Shared tsdown preset (CSS Modules, module table, purity gate)
web-platform.ts # Browser platform module list
tests/ # Hermetic vitest suites (network stubbed)
cordis.patch.yml # Web-profile plugin row (mounts both halves)
Development
pnpm install
pnpm typecheck # tsc -b (src only)
pnpm test # vitest run (hermetic, network stubbed)
pnpm build # tsc -b && tsdown (lib/ + lib/client.js)
The test suites are fully offline: pricing-page HTML, OpenRouter models, and the FX endpoint are all stubbed. Tests cover the trust fence, balance parsing, the pricebook priority chain and snapshot selection, the immutable ledger fold (including same-step replacement, peak/off-peak band selection at the event time, and Search/Fetch request accounting through the official grace period), the subagent aggregation (nested and cold children, listing-failure fallback, and a multi-level chain over a real SessionStore plus projection registry), and the client surfaces (jsdom). .github/workflows/compat.yml runs the same build and suite on every push to main, next, or alpha (only the pushed channel), and a manual dispatch sweeps all three channels across the current npm DSH patches. There is no schedule.
Release channels
A v* tag push publishes through .github/workflows/publish.yml. The tag decides the npm dist-tag, and that choice matters beyond bookkeeping: the community market installs the bare package name — whatever latest names — into a visitor's runtime. DSH ships three release lines at once (@deepseek-ai/dsh names the current line under latest, the upcoming one under next, and the alpha line under alpha), and a plugin version only runs on the line its @deepseek-ai/dsh* peer ranges accept, so scripts/dist-tag.mjs reads those ranges against the registry's own DSH lines and picks the channel:
| Version | Channel |
|---|
accepts the DSH latest line | latest |
accepts the DSH next line (or carries a -next. suffix) | next |
carries an -alpha. prerelease suffix | alpha |
node scripts/dist-tag.mjs pairs prints that table for every published version; node scripts/dist-tag.mjs reconcile re-points each tag at the newest version supporting it, which also repairs a tag an earlier release process set wrong (.github/workflows/dist-tags.yml runs the same reconcile on demand).
Documentation
License
This repository (source, tests, README, and the DSH plugin bundle shape) is licensed under the MIT License — see LICENSE.
Copyright (c) 2026 Saikel-Orado-Liu aka GameGeek-Saikel
