@dsh-external/dsh-quota-cards

Readme

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

# dsh-quota-cards

A DSH account-quota plugin. It keeps a resident Card at the **left end of the
composer** that follows the selected model and shows the matching account
readout — DeepSeek balance, or OpenCode Go remaining token usage over the
**5h (rolling) / weekly / monthly** windows — with a debounced manual refresh
button and interval-based auto refresh.

## Features

### Composer-left quota Card (`conversation.input.left`)

- **DeepSeek**: account balance (total, with granted/topped-up detail in the
  tooltip). Credential reference and refresh interval are configured in
  Settings.
- **OpenCode Go**: remaining token traffic for the **5h (rolling) / weekly /
  monthly** windows as percentages (tooltip carries the used share and reset
  time).
- **Follows the model**: each refresh re-resolves the current provider via the
  `session.models` RPC; providers whose id contains `deepseek` show the balance
  card, `opencode` providers show the usage card, anything else shows a muted
  placeholder. The model is re-checked on mount, after each finished turn
  (`running` flips), on connection reset, and on settings changes.
- **Manual refresh (debounced)**: a click refreshes immediately (bypassing the
  host cache); clicks inside the 2 s cooldown window, or while a request is
  in flight, are ignored.
- **Auto refresh**: every configured interval (1 / 5 / 10 / 30 / 60 min);
  the next tick is re-scheduled with the latest interval after each fetch.

### Settings → 额度查询

- **DeepSeek balance**: credential reference (default `DEEPSEEK_API_KEY`) +
  refresh interval, with a configured/missing badge.
- **OpenCode Go usage**: credential reference (default `OPENCODE_GO_API_KEY`) +
  refresh interval.
- Saves apply live; credential values never reach the browser.

## Data sources & security

- **DeepSeek**: `GET https://api.deepseek.com/user/balance` with
  `Authorization: Bearer <key>`.
- **OpenCode Go**: `GET https://opencode.ai/zen/go/v1/usage` with
  `Authorization: Bearer <key>` (the same Anthropic-compatible key used when
  `ANTHROPIC_BASE_URL` points at `opencode.ai/zen/go`).
- Keys are resolved host-side via `ctx.credentials.resolve()`; the browser only
  receives read-only fetched results. Settings writes require a same-origin
  POST.
- The host caches each provider's readout for its configured interval; manual
  refresh (`force=1`) bypasses the cache.

## Installation

Prerequisites: DSH installed (`dsh web` runs) and `pnpm` on PATH (`dsh plugin`
forwards to pnpm).

```powershell
# 1. Unzip to a folder, e.g. D:\plugins\dsh-quota-cards
# 2. Install into the web profile:
dsh plugin --profile web add file:D:/plugins/dsh-quota-cards
```

`dsh plugin add` runs pnpm and adds `@dsh-external/dsh-quota-cards` to the
profile's `dsh.profile.bundles`.

```powershell
# 3. Restart dsh web
# 4. Open Settings → 额度查询, confirm both credential references, and make
#    sure the keys exist (e.g. in .credentials.yaml or env):
#      DEEPSEEK_API_KEY: sk-xxxx
#      OPENCODE_GO_API_KEY: sk-yyyy
# 5. Back on the chat page, the quota Card sits at the left of the composer.
```

## Uninstall

```powershell
dsh plugin --profile web remove @dsh-external/dsh-quota-cards
# then restart dsh web
```

## Compatibility

- Host services: `settings`, `credentials`, `sessions`, `agentDefaultModel`,
  optional `webServer`; client services `slots`, `connection`; slots
  `conversation.input.left` and `settings.section` (declared by the shipped
  ui-conversation / ui-settings bundles).
- Provider matching is by provider id (`deepseek` → balance card, `opencode` →
  usage card); DeepSeek's official provider id is `deepseek-official` and the
  common OpenCode Go id is `opencode-go`.
- No third-party runtime deps of its own (schemastery and the `@deepseek-ai`
  packages are peerDependencies resolved from the profile).