dsh-sonar

Readme

# dsh-sonar

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

A compact, draggable deep-sea usage dashboard for the DeepSeek Harness Web UI.

![dsh-sonar dashboard in DeepSeek Harness](docs/assets/dsh-sonar-dashboard.png)

`dsh-sonar` adds a Fish-logo floating launcher without narrowing the conversation. Click the Fish to open a complete session dashboard; drag it anywhere in the viewport. The panel automatically chooses a direction where it fits, and `Escape` or another Fish click collapses it. While the model is answering, lightweight bubbles rise around the launcher.

The dashboard includes:

- a green / amber / red context-window gauge;
- an accounted-token donut for uncached input, cache read/write, output, and reasoning when the installed Harness exposes it;
- heuristic system prompt, tool schema, and conversation composition;
- turn, step, model time, tool time, cache hit rate, and cumulative tokens;
- exact DeepSeek `total_balance`, refreshed after each completed turn or manually.

The API key stays on the Host. The browser calls a same-origin `dsh-sonar` route that returns only `{ totalBalance }`; cross-site and non-IP/localhost Host requests are rejected, and responses are never cached.

## Install from GitHub

The repository commits its built `lib/` artifacts, so a Git install does not need to execute a build script:

```sh
dsh plugin --profile web add github:Howe829/dsh-sonar#v0.1.0
dsh --profile web
```

Pin a release tag for repeatable installations. Remove it with:

```sh
dsh plugin --profile web remove dsh-sonar
```

## Configuration

The bundle inserts one `dsh-sonar` row. Defaults use the managed `DEEPSEEK_API_KEY` credential and the public DeepSeek API:

```yaml
- id: dsh-sonar
  name: dsh-sonar
  config:
    apiKeyEnv: DEEPSEEK_API_KEY
    baseURL: https://api.deepseek.com
```

A later profile or home patch can replace this row. Harness patch configuration is row-replacing, so restate every field you want to keep.

## Development

```sh
pnpm install
pnpm run verify
pnpm pack --pack-destination .artifacts
```

The current stable dsh-sonar release is [`v0.1.0`](https://github.com/Howe829/dsh-sonar/releases/tag/v0.1.0). It is tested against the public DeepSeek Harness `0.1.0-rc.6` package family. DeepSeek Harness itself remains a developer preview, so future Harness releases may require compatibility updates.

## Privacy and model impact

This is a read-only UI plugin. It adds no tools, prompts, commands, durable session events, or model-visible context. It does not alter the request envelope or KV cache behavior.

## License

MIT