@9Epuuuu/dsh-api-balance

Readme

# @9Epuuuu/dsh-api-balance

English | [中文](README.zh.md)

DeepSeek account balance in the DSH Web composer stats line: an ambient readout, always visible above the input box, that shows the account balance and the per-session spend:

```text
余额 ¥128.50 · 本次会话用量 ¥3.25
```

The balance comes from the official DeepSeek `GET /user/balance` endpoint, fetched by the host half (which sidesteps browser CORS). The per-session spend uses the balance-difference method: the first balance read for a session is recorded as its starting balance, and spend is the drop from it, clamped to zero.

## What it does

- **Host half**: registers `GET /api/balance` (loopback-only), resolves the API key through DSH's `ctx.credentials` service, fetches and caches the DeepSeek balance for the configured interval, and registers the `api-balance` settings namespace.
- **Client half**: mounts a line in `conversation.composer.dock` (the built-in stats line above the input box) and a settings card in the Web UI plugin group.

## Installation

Install the family aggregate package `@linxin666/dsh-web-ui-all` (all plugins and skins in one) or this plugin alone:

```sh
# Recommended: install directly from npm
dsh plugin --profile web add @9Epuuuu/dsh-api-balance

# Or from the repository (development loop)
git clone https://github.com/9Epuuuu/dsh-api-balance.git
cd dsh-api-balance
pnpm install && pnpm build
dsh plugin --profile web add link:$(pwd)

```

Restart `dsh web`, set the API key credential reference in the plugin settings, and the balance line appears above the input box.

## Configuration

| Key | Type | Default | Meaning |
|---|---|---|---|
| `apiKeyEnv` | `string` | `''` | DSH credential reference to resolve the DeepSeek API key from, e.g. `DEEPSEEK_API_KEY` |
| `refreshIntervalSec` | `number` | `60` | Minimum seconds between balance fetches (also the browser poll cadence) |
| `enabled` | `boolean` | `true` | Master switch for the plugin (browser half + host route) |

## How per-session spend is computed

The account balance is global; the per-session spend is derived per `sessionId`:

1. On the first successful balance read for a session, the balance is persisted (in `localStorage`, keyed by session id) as that session's starting balance.
2. On every later poll, spend = `max(0, starting balance - current balance)`.
3. Refreshing the page keeps the baseline; switching sessions starts a fresh baseline.

## Export shape

A function/namespace plugin: `inject` / `Config` / `apply`, no default export. The DeepSeek adapter (`./deepseek-balance`) is a pure fetch-and-normalize helper.

## Model Experience

### Prompt and tool surface

#### What the model sees

Nothing. The plugin injects no prompt sections, registers no tools, and emits no `session` events of its own.

#### Token effect

Zero per request.

#### KV Cache effect

No system-prompt contribution, so no cache-stability effect.

## Known Limitations and Deferred Work

- **Account-level snapshot**: the balance is a provider-side snapshot with minute-level latency, not per-message billing precision.
- **Spend drift**: the balance-difference spend includes any other concurrent consumption (other sessions, tools) and clamps to zero across a top-up.
- **DeepSeek only**: the balance endpoint is DeepSeek-specific; other providers need their own adapter.