xxvk/dsh-cost-crystal

A cost & usage crystal ball for the DeepSeek Harness web GUI — balance, real-time rate, peak/off-peak billing, and a 🔮 next-message cost forecast, all timezone-aware.

中文说明见 README_CN.md。

Screenshot

Features

• 🔮 Next-message cost forecast — estimates the token usage and cost of your next message from the current conversation context and historical usage; re-prices instantly when you switch models
• Balance card — CNY/USD balance with data-freshness hints («just now / Ns ago»); click to refresh instantly
• Real-time rate — the breathing dot and shimmer light up within 2s of token consumption, showing live tok/s
• Peak/off-peak billing — status badge, countdown to the next rate switch, and a last-24h spend estimate
• Plug & play — zero runtime dependencies, dark/light theme aware, API key stays on the Host

Installation

Requires the DeepSeek Harness web profile (@deepseek-ai/dsh).

# Option 1 (recommended): npm package
dsh plugin --profile web add dsh-cost-crystal

# Option 2: from GitHub
dsh plugin --profile web add "github:xxvk/dsh-cost-crystal"

# Option 3: local development
dsh plugin --profile web add /path/to/dsh-cost-crystal

Then restart dsh web and hard-refresh the browser. The package declares dsh.bundle, so dsh plugin mounts it into the profile's bundle layer automatically — no manual config.

Pricing & Timezone

• Pricing engine implements the official DeepSeek policy timeline: model-aware unit prices, peak/off-peak/flat buckets, dual currency (CNY/USD).
• Peak (deepseek-v4-flash etc.): hit $0.014 / miss $0.44 / output $1.32 per M tokens; off-peak at half price. Windows 01:00–04:00 and 06:00–10:00 UTC.
• Windows are defined in UTC; state/price judged in UTC; display uses the browser's local timezone.
• Spend/cost covers local Harness sessions only; display conversion uses a fixed rate of 7.1.
• ⚠️ All spend/cost figures are local-log estimates and may differ from the official bill.

VL models (multi-model stats)

dsh-cost-crystal buckets usage per model automatically from session logs, so mixed DeepSeek + vision-language (VL) usage shows side by side on the card. When more than one model is present, a summary line (deepseek 12.5M · ¥36.6 qwen3-vl 1.2M · ¥3.2) appears, and the ▼ button next to the source label cycles through your configured models.

To use a VL model (e.g. Alibaba qwen3-vl-flash), configure it as a DSH provider — for example via the dsh-vision-router plugin (provider vision-http, model aliyun/qwen3-vl-flash, DASHSCOPE_API_KEY in ~/.dsh/.credentials.yaml). dsh-cost-crystal needs no extra config: it reads whatever models the session log records.

Roadmap

• v0.1.0 (now): balance card + real-time rate + peak/off-peak + countdown + 24h spend + 🔮 next-message forecast
• v0.2.0 (planned): VL model statistics — model-switch button + per-model cost/token buckets
• v0.3.0 (planned): forecast deepening — weighted window, budget burn-down, peak hints, top requests

See ROADMAP.md and TODO.md.

Development

npm install           # only typescript devDependency
npm run build         # generate injected-script templates + tsc → lib/
npm test              # build + all tests + line rules (TDD gate)
npm run build:profile # generate local hot-reload profile plugin (dev)

Architecture: Host logic (src/index.ts / src/pricing.ts / src/usage.ts) is TypeScript; injected scripts are plain-JS sources (src/scripts/card.inline.js + card-fmt.inline.js + card-render.inline.js) escaped into generated src/card-script.ts by scripts/build-scripts.mjs (generated files: never hand-edit).

Testing (TDD gate)

Every code change must pass to be "done":

npm test    # = tsc build + node --test (all tests) + check-lines

• Node built-in node:test, zero runtime deps; CI (.github/workflows/test.yml) runs on push/PR
• Line rules: src/test ideal ≤200 / hard cap 300; generated lib/ exempt. See CONTRIBUTING.md

License

Apache-2.0