dsh-secret-balance-widget

A floating plugin for DeepSeek Harness that shows your DeepSeek API balance and the current session's real token usage in a small, draggable, translucent chip.

The plugin reuses the harness' own data sources instead of reinventing them:

• Tokens are read straight from the harness' tokenUsage session projection produced by @deepseek-ai/dsh-token-meter — the exact source the built-in stats line under the input box uses. There is no re-tokenization and no custom tokenizer.
• Theme is the harness' own DSW CSS-variable token set, so Light / Dark are matched automatically.
• The API key is stored with the harness' credentials service (the same official secret store the Models page writes to) and is never returned to the browser or rendered.
• Network (the balance call) happens on the Host half and is exposed to the Client over the official Package-private JSON RPC (harness.handle / host.call).

1. What it is

A single Cordis plugin with two halves:

Features

• Minimized by default — shows only the current balance; no other stats.
• Expand for details — click to reveal API balance, current-session input and output tokens (formatted K / M).
• Real token data — from the tokenUsage projection (uncachedInputTokens + cacheReadTokens + cacheWriteTokens for input, outputTokens for output), the same source the built-in input stats line reads.
• Auto-refresh every 60 s plus a manual refresh button.
• Draggable — the chip moves freely by its own handle and stays inside the viewport.
• Smart panel direction — the expanded panel opens toward the side with more free space (never hard-coded), and is clamped to remain fully visible.
• Pin / outside-click-to-collapse — clicking outside collapses unless pinned; pinning keeps it open and is visually highlighted.
• Light / Dark adaptive through the harness' own theme tokens.

2. Installation

DeepSeek Harness loads plugins from its Cordis composition. This plugin is a Cordis plugin, so installation is two steps: get the package onto your install, and reference a row for it in your composition.

Step 1 — add the package as a dependency

In the directory of your DeepSeek Harness deployment's package.json:

npm install <this-repo-as-a-git-url>

or, from a local checkout of this repository:

npm install /path/to/dsh-secret-balance-widget

Step 2 — add a row to your cordis.yml

Open the composition file that lists your plugins (shipped plugins live in rows such as - name: '@deepseek-ai/dsh-token-meter') and add:

- name: 'dsh-secret-balance-widget'

The Host half needs the credentials and subprocess services and the curl executable. On a default Harness deployment these are provided by dsh-credentials-local, dsh-subprocess-local (both usually already composed) and a system curl (present on most platforms). If curl is missing on PATH, install it or point the deployment at one.

The plugin ships two source forms. src/host.js and src/client.js are verbatim Cordis plugin bodies — the exact format the Harness plugin authoring / dynamic loader consumes (each half is an async function body that returns a Cordis plugin). Running npm run build also emits identical lib/host.body.js and lib/client.body.js, plus lib/host.js / lib/client.js for loaders that expect a module. Both shapes are the same logic.

If you prefer to load it through the Harness GUI's plugin mechanism instead of a composed row, use the Host code = verbatim contents of src/host.js, Client code = verbatim contents of src/client.js, in the plugin authoring UI. After that, approve/run the plugin request.

Verify the client module

Client UI for composed @deepseek-ai/dsh-client-* packages is discovered from the dsh.client field in package.json. This package declares that field too. If your deployment scans dsh.client modules, rebuild/refresh the web bundle as your deployment requires so the new client module is picked up. The plugin does not fork or extend Harness Core — it only uses public slots/services.

3. Entering your API key

1. Click the floating chip to expand it.
2. If no key is set, click 设置 API Key, paste your DeepSeek API key (starts with sk-), and click 保存.
3. The balance is fetched immediately and every 60 s afterwards.

The key is saved through the harness' credentials service into the deployment's credential store (e.g. $DSH_HOME/.credentials.yaml, 0600). It is treated as an opaque secret: the client never receives it, and the credential reference used is DSH_BALANCE_API_KEY.

To replace it, open the panel again and re-save. To clear it, click 移除 Key in the expanded panel.

4. Upgrading

Upgrades are normal npm dependency bumps:

npm install <this-repo-as-a-git-url>@<new-tag-or-ref>

Then restart/rerun your Harness deployment so the row reloads. Your stored API key (kept in the credential store, not in the package) survives the upgrade.

5. Uninstalling

1. Remove the row from your cordis.yml:

   # - name: 'dsh-secret-balance-widget'   # delete or comment out

2. Remove the package dependency:

   npm uninstall dsh-secret-balance-widget

3. Restart/rerun the deployment. The widget disappears.

Your API key is not removed by uninstalling — it lives in the shared credential store. If you also want to remove it, clear the reference DSH_BALANCE_API_KEY from your credentials document, or reinstall and click 移除 Key first.

Development

npm install
npm run build       # emits lib/
npm run typecheck   # tsc --noEmit over src/
npm test            # node --test

src/util.js holds the framework-free pure helpers (token formatting, balance parsing, panel placement) and is unit-tested. src/host.js and src/client.js embed small inline copies of the same helpers so each half stays self-contained for the dynamic loader; keep them in sync with src/util.js.

License

MIT