# dsh-api-usage-bar

[![CI](https://github.com/hurry060215-tech/dsh-api-usage-bar/actions/workflows/ci.yml/badge.svg)](https://github.com/hurry060215-tech/dsh-api-usage-bar/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/hurry060215-tech/dsh-api-usage-bar)](https://github.com/hurry060215-tech/dsh-api-usage-bar/releases/latest)

English | [简体中文](README.md)

A lightweight API token usage bar for the DeepSeek Harness Web UI. It displays complete-session usage as three segments: **cached input**, **uncached input**, and **output**, with compact values beside the track.

![DSH API usage bar](docs/screenshot.png)

## Features

- Reads the existing DSH `tokenUsage` session projection; it never calls the DeepSeek API.
- Reads no API key, polls no account balance, and writes no session-log event.
- Green is cache-read input, amber is uncached input, and blue is output.
- Hover text and the accessible label expose exact token totals for all three buckets.
- Responsive on desktop and narrow screens; narrow layouts hide the words but retain colors and values.
- UI only: no model tool, system prompt, or token overhead.

## Requirements

- DeepSeek Harness `>=0.1.5-alpha.1 <0.1.6-0`
- Web profile
- Node.js `^22.19.0` or `>=24`
- pnpm 10 (`dsh plugin` invokes it internally)

## Install

Run in PowerShell or a terminal:

```sh
npm install --global pnpm@10
pnpm --version
npx --yes @deepseek-ai/dsh@0.1.5-rc.1 plugin --profile web add https://github.com/hurry060215-tech/dsh-api-usage-bar/releases/download/v0.2.0/dsh-api-usage-bar-0.2.0.tgz
npx --yes @deepseek-ai/dsh@0.1.5-rc.1 web
```

Open the complete startup URL printed in the terminal (current DSH includes a temporary authentication parameter), or use the automatically opened browser. The bar appears below the composer after the first completed model request. The release includes prebuilt `lib/` output, so users do not need to clone or build the repository.

Version `0.2.0` has disposable Profile install/start/uninstall evidence for DSH `0.1.5-alpha.1`, `0.1.5-alpha.2`, and `0.1.5-rc.1`; see [compatibility evidence](docs/compatibility.md). For historical DSH `0.1.0-rc.6`, use plugin `0.1.1`. The screenshot above shows that historical UI.

This plugin is not published to npm. Do not use `add dsh-api-usage-bar`; the command above installs the prebuilt GitHub Release package directly.

### Port 3080 is already in use

If DSH is already running on port 3080, stop that process with `Ctrl+C` in its terminal and run the `web` command again so the newly installed plugin loads. If another application owns 3080, use:

```sh
npx --yes @deepseek-ai/dsh@0.1.5-rc.1 web --port 3091
```

Then open the complete port-3091 startup URL printed in the terminal.

Remove it with:

```sh
npx --yes @deepseek-ai/dsh@0.1.5-rc.1 plugin --profile web remove dsh-api-usage-bar
```

## Accounting

| Segment | DSH token projection fields |
| --- | --- |
| Cached input | `cacheReadTokens` |
| Uncached input | `uncachedInputTokens + cacheWriteTokens` |
| Output | `outputTokens` |

The three segments are normalized by their token total, so the track shows **usage composition**, not account quota or balance depletion. DeepSeek request usage reports prompt-cache hit and miss tokens, while the balance endpoint supplies no total-quota denominator; this plugin does not invent an “amount used” percentage.

## Development

```sh
pnpm install
pnpm run check       # typecheck + tests + build
pnpm pack            # produce an offline-installable tarball
```

Source layout:

- `src/index.ts`: inert Host plugin used for client-module discovery.
- `src/client/index.ts`: locale, stylesheet, and composer-dock registrations.
- `src/client/ApiUsageBar.tsx`: the track and compact legend.
- `src/client/usage.ts`: pure token bucketing and formatting.
- `cordis.patch.yml`: profile layer activated by `dsh.bundle`.

## Privacy and model experience

The plugin only reads the cumulative token projection already delivered to the browser. It makes no network request, holds no credential, writes no session event, and changes nothing sent to the model.

## License

[MIT](LICENSE)