Andrew111888/dsh-plugin-balance

dsh-plugin-balance

A floating credit / quota widget for the DeepSeek Harness Web — plus DSH session token usage & cost stats.

English · 简体中文

English · 简体中文 README

---

✨ What it is

dsh-plugin-balance is a DSH (DeepSeek Harness) Web plugin that floats a small widget right above the input box. It shows:

• LLM account balance / quota for DeepSeek official, OpenCode Go, OpenAI, or any custom quota endpoint.
• OpenCode Go — the main window shows all three usage periods at a glance: 5h / weekly / monthly percentage badges (color-coded green → amber → red).
• DSH session token usage — how many tokens your DSH chats consumed, tracked per day / per month / in total, broken down by model, persisted to disk.
• Estimated cost — token usage priced with official DeepSeek (peak/off-peak), Kimi and GLM rates.

The widget is draggable, theme-aware (light/dark), and collapses into a slim pill that keeps a refresh button.

🖼 Preview

① Animation — hover to expand, move away to collapse (spring animation), see the interaction in action

② Usage detail — OpenCode Go 5h / weekly / monthly usage and reset times

③ Token usage stats — today / month / total + last-7-days chart + per-model breakdown + cost estimate

④ In-context — the floating widget above your chat

⑤ Balance type — auto-detects DeepSeek official balance vs plan usage (OpenCode Go)

Features

Area	What you get
Accounts	DeepSeek official (/user/balance), OpenCode Go (/usage via host proxy), OpenAI credit_grants, or a custom quota endpoint synced from the DSH model list
OpenCode Go display	5h / weekly / monthly percentage chips in the main row, clean percentages in the collapsed pill, reset times in the detail panel
Token usage	Today / This month / Total token counts, a last-7-days mini bar chart, and a per-model breakdown (input / output / cache-hit)
Cost estimate	≈¥ badges with official pricing — DeepSeek (peak/off-peak ×2, Beijing 9:00–12:00 & 14:00–18:00), Kimi (K2/K3) & GLM (4.x/5.x) at constant rates (USD official prices converted at ~7.2)
UX	Draggable, position persisted, click-outside collapses, theme-adaptive, refresh on the pill too

🚀 Install as a DSH plugin

The plugin is published to npm (dsh-plugin-balance) and ships a dsh.bundle manifest, so it installs with the standard DSH plugin command:

dsh plugin add dsh-plugin-balance           # default profile
# or explicitly the Web profile:
dsh plugin --profile web add dsh-plugin-balance

This resolves the npm package, writes the bundle entry, and enables the plugin. Restart dsh web (or reload) and refresh the browser page.

🛒 Install from the plugin market (listed on dsh-market)

The plugin is listed in the awesome-dsh-plugin catalog and available on dsh-market, the plugin market built into DSH Settings. With dsh-market installed, search for dsh-plugin-balance under Settings → Plugin Market and install / upgrade with one click:

dsh plugin --profile web add dshmarket

Manual install (by hand)

If you manage the profile yourself (offline, or no dsh CLI):

1. In your Web profile's package.json (e.g. ~/.dsh/profiles/web/package.json), add the dependency — from npm, a tarball URL, or a local path:

   "dependencies": {
     "dsh-plugin-balance": "^1.3.6"
   }
   

2. Enable it in cordis.patch.yml (the package ships the exact entry as cordis.patch.yml):

   - insert:
       - id: plugin-balance
         name: dsh-plugin-balance
   

3. Install & restart:

   cd ~/.dsh/profiles/web
   pnpm install
   # restart `dsh web`, then refresh the browser page
   

Requires the webServer and credentials services (provided by @deepseek-ai/dsh-web-app in the web profile). The host half needs credentials, webServer, llm, settings, and sessions.

⚙️ Usage

Click the switch button to open settings:

• DeepSeek official — leave the key blank to auto-use DSH's DEEPSEEK_API_KEY, or enter a key in the browser (stored in localStorage). A custom /user/balance base URL is supported.
• OpenCode Go — nothing to fill in; it auto-reads the DSH credential OPENCODE_GO_API_KEY (falls back to OPENCODE_API_KEY).
• Custom quota endpoint — pick a vendor from the DSH model list (auto-fills baseURL + apiKeyEnv), or fill the endpoint manually; credentials are resolved host-side, never sent to the browser.

Click the bar-chart button to open the TOKEN 使用量 panel (today / this month / total + 7-day chart + per-model breakdown + cost badges).

🧮 Token usage & cost

The host half listens to the DSH session event stream (session/event), folds each request's reported token usage (cache-miss input + cache write, cache hit, output) by day / month / model, and persists it to ~/.dsh/storages/dsh-plugin-balance-usage.json.

• Idempotent: a newer sample for the same turn:step replaces the earlier one; replaying logs after a reload / restart never double-counts.
• Model attribution follows each request's request/header, so sessions that switch models mid-flight stay in the right bucket.
• Served to the client at GET /api/dsh-plugin-balance/tokens.
• Cost uses official pricing for DeepSeek (peak/off-peak, CNY) and Kimi/GLM families (USD converted at ~7.2), priced by the moment each sample occurred (see the note in the UI). Unlisted models aren't priced.
• Store format is version 9: legacy data is no longer estimated — it is rebuilt exactly by replaying session events, including archived sessions from the on-disk logs.

📄 License

BSD-3-Clause