dsh-balance-capsule

A small, refined floating capsule for DeepSeek Harness.

• Shows the logged-in DeepSeek account balance.
• A single lamp shows peak / off-peak pricing (red / green).
• Click to expand: latest turn cost, today, 7-day trend, recent ledger.
• Approval alert: an orange warning badge appears just left of the capsule and a two-hit bell cue plays when DSH asks for permission. The badge disappears when the request is resolved, and the warning repeats every 10 seconds while the request is still pending (repeat can be switched off).
• Completion marker: after a turn finishes, a green check badge appears in the same position, a short three-tone chime plays, and a small green chip slides in just below the capsule showing what this turn cost (e.g. 本轮消耗 ≈ xxx). Chip and badge both stay for 10 seconds; the chip has its own on/off switch under Settings → Completion.
• Warning and completion have independent on/off and volume settings. No custom audio upload is supported; both cues are synthesized with Web Audio (no system beep).
• Browsers may block audio until the page has received a user gesture. If that happens on the first cue, the badge still appears and a one-time toast asks you to click the capsule to enable sound.
• Holiday calendar keeps itself up to date, so the peak / off-peak split keeps working after 2026 without any manual step.
• Looks like part of the shell: the capsule docks to whichever edge you drag it to and stays docked when the window is resized (grow or shrink), and the expanded detail view and the settings view share one thin, translucent frosted panel over the page behind it.

Install

Desktop app. Open Plugins in DSH and use its local-tarball install entry, pointing it at dsh-balance-capsule-0.4.0.tgz. This is the only path for the app's own desktop profile: the CLI refuses it with profile "desktop" is managed exclusively by the Electron application. Restart DSH afterwards; the capsule is mounted in the shell.overlay slot.

CLI, for server installs and for profiles you manage yourself:

dsh plugin --profile web add ./dsh-balance-capsule-0.4.0.tgz

The CLI shells out to pnpm, so pnpm has to be on PATH; without it the command fails with 'pnpm' is not recognized.

dsh-balance-capsule-0.4.0.tgz is committed at the repository root (SHA-256 in SHA256SUMS.txt), so a clone installs without a build step.

Requirements

• DSH 0.2.1-rc.5 — the release this build is marked compatible with in package.json (dsh.compatibility.dshReleases).
• Node.js ^22.19.0 || >=24.0.0, only when you pack the plugin yourself; the desktop app brings its own runtime.
• A signed-in DeepSeek account. Without one the capsule still loads and reports signed-out; DSH_BALANCE_CAPSULE_MOCK=1 runs it against sample data instead.

Scope

The plugin reads the account balance through DSH's optional deepseekAccount service. It does not read DEEPSEEK_API_KEY, does not write DSH configuration, and does not send account data anywhere.

Per-turn cost is an estimate from token usage and the published CNY price table. It does not include Search/Fetch fees. The ledger is stored under:

<profile>/balance-capsule/ledger-<scope>.json

<profile> is the profile directory DSH reports through profileContext.dir, not a hard-coded path.

Holiday calendar

Chinese statutory holidays and the 调休 makeup workdays around them are announced once a year, so they cannot be hard-coded. The plugin stores one dataset per year:

<profile>/balance-capsule/calendar/<year>.json   # one file per year
<profile>/balance-capsule/calendar/policy.json   # auto-fetch switch + retry history

How it refreshes itself:

1. A seed for the current year ships inside the package, so a fresh install is correct offline.
2. In the last 10 days of December the plugin looks for the next year's schedule. If it is not published yet, it retries every 5 days until it is.
3. Sources are tried in order, and the first complete answer wins:
   • holiday-cn via jsDelivr (structured JSON, includes 调休 makeup workdays)
   • holiday-cn via GitHub raw
   • timor.tech holiday API
4. A payload is only accepted when it is for the requested year and looks complete (at least 10 rows, at least 5 days off). The 236-byte "not published yet" placeholder is rejected.
5. If every source fails, the previous data is kept and the check is retried later. Nothing is overwritten with a broken file.

Settings have an 自动获取 switch (turn the yearly check off entirely) and a 立即获取 button (force a check now). The panel also shows how many years are already stored and, if the last attempt failed, the reason.

Hovering (or keyboard-focusing) the 「节假日日历」 section title in Settings opens a small floating card explaining that the calendar decides the peak/off-peak date assignment: statutory holidays bill at the off-peak price, 调休 makeup workdays bill at the weekday peak/off-peak windows, and a missing year falls back to the plain weekday rule — so it directly affects how accurate the cost estimate is. The card is position: fixed, so the panel scroll box never clips it; it never occupies layout space of its own.

A year without data still works: the weekday rule is used and the panel footer shows · 日历待更新. Balance is always server-side, so the wallet number is never an estimate.

Settings

• Balance refresh: 15s / 30s / 60s.
• Low-balance threshold: off / ¥5 / ¥10 / ¥20.
• Warning cue: on/off, volume (0–100%, default 50%), repeat on/off (10 s cadence), preview.
• Completion cue: on/off, volume (0–100%, default 50%), preview (the preview plays the cue and shows the check badge plus the turn-cost chip, so both can be checked without waiting for a turn).
• Holiday calendar: auto fetch on/off, manual 立即获取.

Settings other than the calendar are stored in the DSH web origin's localStorage only.

Development

The repository is the plugin itself: plain ES modules, no bundler and no build step.

• lib/index.js — host half, a plain Cordis plugin.
• lib/client.js — browser half, registered through window.__ModuleLoader__.load({ id, factory }).
• lib/client.css — capsule, panel and settings styles.
• cordis.patch.yml — the bundle patch that mounts the host half and lets the web app load the client bundle.

npm pack   # rebuilds dsh-balance-capsule-0.4.0.tgz from these sources

The published tarball contains only lib/, cordis.patch.yml, README.md, LICENSE and package.json (see the files field). The tarball committed here was packed from these sources. Packing again reproduces every shipped file byte for byte, with two exceptions: this README (the release copy differs), and package.json (this listing carries repository, homepage, bugs and extra keywords that were added after 0.4.0 was packed).

License

MIT