@chi-hong22/dsh-plan-spend
A usage popup for the DSH Web GUI: one "Usage" chip in the frame-wide overlay
opens a panel showing the plan spend of the configured providers.
What it shows
| Provider | Source | Rendered |
|---|
| DeepSeek official | the DeepSeek account sign-in: the host half asks ctx.deepseekAccount.resolveToken for the grant and calls GET https://api.deepseek.com/user/balance with x-dsh-auth-token; falls back to the same endpoint with DEEPSEEK_API_KEY | recharge balance (server precision kept), the topped-up split on the fallback card, the sufficiency flag, which route the number came from, and the peak / off-peak window with its next switch |
| OpenCode Go | GET https://opencode.ai/zen/go/v1/usage | 5-hour / 7-day / monthly used percentage, progress bar, reset countdown |
赠金 (granted credit) is not shown. It is promotional and short-lived, so it
is not plan balance: the API-key card does not map granted_balance, and the
account card reads the recharge wallet (topped_up_balance) alone.
Known limitation: the OpenCode Go usage endpoint returns percentages and
reset instants only — no used/limit amounts. That column is therefore
percent-only; the exact dollar figures live in the OpenCode console.
Peak and off-peak (DeepSeek official)
DeepSeek bills two rates, and off-peak is half the peak price, so the DeepSeek
card carries one more row: whether the current moment is peak or off-peak, and
how long until the next switch.
There is no endpoint that reports the current window — the rule lives in a
footnote on the pricing page — so this row derives it client-side from the
published rule:
- Peak: Monday–Friday
09:00–12:00 and 14:00–18:00 Beijing time (UTC
01:00–04:00 and 06:00–10:00), excluding Chinese public holidays.
- Everything else is off-peak:
12:00–14:00, the night, all weekend, and
public holidays in full.
How the derivation is pinned down:
- Weekends are always off-peak, so a make-up workday that lands on a Saturday
or Sunday needs no extra modelling — the weekend rule already calls it off-peak.
- The holiday set is therefore the whole published State Council arrangement
(including workdays folded into a holiday, such as 2 January for New Year), not
just the 11 statutory days; otherwise peak would reappear mid-holiday.
- Lookups use UTC date keys: every peak window lies inside UTC
00:00–16:00
and everything outside a window is off-peak, so a UTC-date lookup and a
Beijing-date lookup agree.
- The windows are half-open:
04:00:00 sharp is already off-peak.
The holiday table needs upkeep
The table is UM_CHINA_PUBLIC_HOLIDAYS_UTC in client.body.js (33 days for
2026, from State Council notice 国办发明电〔2025〕7 号); the years it covers are
listed in UM_HOLIDAY_YEARS. Each fourth quarter, once the State Council
publishes the next year's arrangement, append that year's date keys and the year
itself.
When the table does not cover the current year the card says so outright — the
holiday table does not cover that year, add the data — because in that state
every weekday statutory holiday would be scored as peak, and a wrong number
stated silently is worse than a missing one declared. A covered year shows no
notice at all.
Install
dsh plugin --profile <profile> add github:Chi-hong22/dsh-plan-spend
The desktop profile is owned by the Electron application: the CLI refuses it
with profile "desktop" is managed exclusively by the Electron application.
Install through the GUI plugin page instead.
Verify the mount:
dsh --profile <profile> --dump-config | grep usage-meter
Configuration
The plugin has no config. It decides which providers to show from whether their
credential is configured; the reference names live in the ADAPTERS table in
index.js:
| Provider | Credential ref (POSIX environment name) |
|---|
| DeepSeek official | DEEPSEEK_API_KEY |
| OpenCode Go | OPENCODEGO_API_KEY |
Credentials resolve through ctx.credentials.resolve(); the source precedence
is documented by @deepseek-ai/dsh-credentials-local (launch environment →
stored file → project .env → harness home .env). An unconfigured provider
issues no request and renders as "no credential configured; skipped".
The API-key row is the fallback. The DeepSeek card is normally read in this
half from the signed-in DeepSeek account: ctx.deepseekAccount.resolveToken
hands out the stored grant for the configured inference origin
(https://api.deepseek.com), and that token goes to the same /user/balance
endpoint as x-dsh-auth-token. No API key is needed, and the grant never
reaches the browser. When the account cannot answer (signed out, no account
provider in this composition, or the query failed) the API-key card stands in
and names its own route; a failed account query is reported on that fallback
card, so "signed out" and "the query broke" stay distinguishable.
The account service's own balance query is deliberately not used: it goes to
platform.deepseek.com, whose WAF answers non-browser clients with HTTP 429,
so it reports a failed balance instead of a number.
A failed or missing API-key read also reports the effective credential's
source layer and whether this surface could write it
(ctx.credentials.describe), because "I saved a key and it still unauthorised"
is almost always a read-only launch-environment value winning over the stored
one.
Adding a provider = one row in ADAPTERS plus one reader function.
Placement and sizing
The plugin registers two seats:
sidebar.footer.action (id usage-meter): the trigger. That seat is the
sidebar's own action row and hands each entry { wide }, so the button
follows the collapse/expand rail by itself (icon-only when wide === false).shell.overlay (id usage-meter): the panel. The frame-wide layer sits
outside every column, so the panel renders beside the sidebar instead of
being clipped by the sidebar's overflow: hidden.
Placement: the panel measures the frame-level column that holds the button
(by climbing the DOM to the frame's direct child, never by hashed class name),
anchors its left edge 10px past that column's right edge and its bottom at the
button's bottom, then grows upward. A sidebar width change re-measures.
One deviation worth knowing: sidebar.settings (the account row) is a
single seat already owned by the shipped account/settings UI, so taking it
would shadow that UI (replaceRisk: shadows-shipped-ui). .footArea is a
column with footerActions above settingsArea, so the button lands in the
row above the account row rather than at its right in the same row.
Button styling mirrors the shipped account launcher — padding: 6px,
border-radius: 12px, gap: 8px, font-size: 14px/22px, row margin 4px -2px,
hover --dsw-alias-interactive-bg-hover; the glyph is 32×32, the avatar's own
box; in the rail it becomes a centred 40×40 icon.
Alignment with the account row is measured, not assumed: on mount the row
takes the sibling account row, finds its first button, then that button's first
sized child (the avatar) and the next sized sibling (its label), and converts
both left edges into this row's padding-left and the label's margin-left.
Whatever inset that row actually uses, this one follows; with no account row the
stylesheet defaults stand. The rail opts out and keeps its own centred box.
Dismissal: the trigger again, the panel's ×, Esc, or a press anywhere
outside the panel all close it.
Resizing: the grip sits in the panel's top-right corner — the one
farthest from the button — dragging right grows the width and dragging up grows
the height. The size is stored under usage-meter.size and is bounded by the
panel minimum and the overlay bounds.
To return to the default size, clear usage-meter.size. After editing the
source run npm run build to regenerate client.js; that file is a build
artifact — do not edit it directly.
The browser picks up a new client.js only after a page refresh: replacing
package code is not part of DSH's ordinary start/stop sync.
The client half must export inject
The plugin object returned by client.body.js carries inject: ['slots', 'locale']
so Cordis withholds apply until both services are provided. Without it
ctx.get('locale') can read undefined and t silently degrades to echoing
the key — the UI then shows button.label, panel.title, window.rolling
while the data and layout stay perfectly correct, which reads like an unrelated
bug. Every shipped client half (dsh-client-ui-sidebar, dsh-client-ui-cordis)
exports inject; do the same.
The host half likewise reads the account service through ctx.get instead of
declaring it in inject: a composition that mounts no account provider must
still mount the meter, with the API-key card in charge.
Security boundary
- API keys are used in the host half only and never reach the browser; the
browser reads same-origin JSON.
GET /usage-meter/snapshot is a named route on the harness web server with
no additional authentication. When the web server binds 0.0.0.0, anyone
on the same network can read the balance and quota numbers (never the keys).
Loopback-only use is unaffected.
Layout
index.js host half: credential resolution + both upstream calls + 30s cache + route
client.body.js client half source (bare function body, no imports/JSX)
client.js build artifact, generated by scripts/build-client.mjs
cordis.patch.yml bundle patch: inserts one row into a profile
scripts/build-client.mjs
scripts/probe-sources.ps1 one-shot probe: verify both upstreams without the plugin
tests/client-ui.test.mjs trigger/placement/resize + account-route card tests (npm test)
tests/host-snapshot.test.mjs host route payload tests (npm test)
License
MIT
