dsh-usage-widget

Readme

# dsh-usage-widget

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that keeps a compact **usage widget inside the left sidebar** of the Web GUI:

- **DeepSeek account balance** — `GET https://api.deepseek.com/user/balance`
- **Kimi Code quota** — `GET https://api.kimi.com/coding/v1/usages` (5-hour window + weekly quota)

The panel is always visible in the sidebar footer, click to collapse/expand, auto-refreshes every 60 s, and offers a DeepSeek / Kimi toggle.

> Community plugin, not an official DeepSeek plugin.

## Install

Requires a DSH Web/Desktop profile (the plugin targets the browser client).

```bash
# from GitHub (repo ships prebuilt lib/, no build step needed)
dsh plugin --profile <name> add github:AHui-Lab/dsh-usage-widget

# once published to npm
dsh plugin --profile <name> add dsh-usage-widget

# if no global dsh CLI
npx --yes @deepseek-ai/dsh plugin --profile <name> add github:AHui-Lab/dsh-usage-widget
```

Restart DSH, then look at the bottom of the left sidebar for the "用量" entry.

## How the data flows

The browser cannot call `api.kimi.com` directly (its CORS preflight rejects the `Authorization` header), so the plugin keeps two data paths:

1. **Host route** `GET /usage-monitor/deepseek|kimi` (registered on the host webserver) proxies the upstream. It prefers the API key the client sends in the `Authorization` header, otherwise falls back to the DSH credentials service / env.
2. **Browser-direct fallback** (used when the host route is unreachable): fetch the upstream directly with a key the user stored in the panel. Works for DeepSeek (CORS allowed); Kimi is CORS-blocked in this mode.

## API keys

Keys are **per-machine** and never ship with the plugin:

- **Host route mode**: put `DEEPSEEK_API_KEY` / `KIMI_CODING_API_KEY` in `~/.dsh/.credentials.yaml` or the environment (host reads them).
- **Browser-direct fallback**: open the panel → gear icon → paste the DeepSeek API Key and the Kimi Code token. They are kept in the browser's `localStorage` only (key prefix `usage-monitor.key.*`) and sent only to the upstream API.

> Note: keys are intentionally **not** distributed with the plugin. Each machine configures its own.

## Layout

The widget registers into the `sidebar.footer.action` list slot and renders inline inside the sidebar column (full column width, no floating overlay, no overlap with the chat area). All styles are scoped under `data-plugin="dsh-usage-widget"`.

## Development / publishing notes

- Host entry: `lib/index.js` (registers the two `/usage-monitor/*` routes; `inject: ["webServer"]`).
- Client bundle: `lib/client.js` (ModuleLoader bundle; only `react` + `@deepseek-ai/dsh-client-ui-primitives` from the baseline).
- `lib/` is committed so both GitHub and npm installs need no build step.
- Environment overrides: `USAGE_MONITOR_DEEPSEEK_REF`, `USAGE_MONITOR_KIMI_REF`, `USAGE_MONITOR_DEEPSEEK_BASE`, `USAGE_MONITOR_KIMI_BASE`.

Verify before releasing:

```bash
npm run check
npm pack --dry-run --ignore-scripts
```

## License

[MIT](LICENSE)