@wenqi_bian/dsh-dashboard

Readme

# DSH Dashboard

Per-session statistics for DeepSeek Harness: token usage, timing, tool and skill activity.

Adds a Statistics tab to the conversation view. The numbers update live as the session progresses.

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

## Compatibility

Supports DeepSeek Harness `v0.1.2-alpha.1` through `v0.1.3-alpha.2` (npm `alpha` dist-tag): the client half targets the `conversation.view` slot, the `tokenUsage` / `sessionStats` projections, the chat snapshot's `legacy.nodes` timeline and the `turn-tail` turn data — verified present and field-identical across the `dsh-v0.1.2-alpha.1` through `dsh-v0.1.2-alpha.5` tags, re-verified at `dsh-v0.1.2-rc.1` (the rc.1 tree diff against alpha.5 is a repo-wide `package.json` version bump only: zero non-`package.json` files and zero non-version lines changed, so the plugin-consumed contract surface is byte-identical), and re-verified at `dsh-v0.1.3-alpha.2`. The re-verification covers: `tool-result` node fields (`time`, `call.name`/`argsRaw`, `callTime`, `isError`), the `turn-tail` business data keys (`tokenUsage`, `ttftMs`, `tokensPerSecond`), the `sessionStats` / `tokenUsage` projection keys, and the built-in view entries (`chat` at order 0, `trajectory` at order 10 — the `statistics` entry at order 20 does not collide). 0.1.3 changed the streaming event generation (`assistant/attempt` + `assistant/live-chunk` replace `assistant/chunk` and the `chunkrow/*` rows) and the projection sampling point, but every field this plugin reads is unchanged. Peer dependencies use the `^0.1.2-alpha.1 || ^0.1.3-alpha.1` range: a bare `^0.1.2-alpha.1` does not match `0.1.3-alpha.2`, because npm's prerelease rule only matches a prerelease whose major.minor.patch has a comparator inside the range.

Not supported: `0.1.1-rc.2` and earlier — that generation runs the pre-`useChat` client-runtime contract, so the tool and skill tables would silently stay empty.

Compatibility risk to track: the chat snapshot's `legacy` slice is the host's compatibility projection; the shipped `StatsLine` still consumes it through 0.1.3-alpha.2 (re-verified), but re-check it on every harness upgrade.

## Install

Releases are version-aligned with the harness: each version is built for, and named after, the matching `@deepseek-ai/dsh` release.

### From npm

Pick the dist-tag that matches your harness:

1. **npm `alpha`** (`0.1.3-alpha.2`) — compatible with dsh v0.1.3-alpha.1 ~ alpha.2, and with the whole `v0.1.2-alpha.1` ~ `v0.1.2-rc.1` range (the contract surface it reads is unchanged):
   ```bash
   dsh plugin --profile web add @wenqi_bian/dsh-dashboard@alpha
   ```
2. **npm `latest`** (`0.1.2-rc.1`, kept in sync with `next`) — conservative channel for dsh v0.1.2-alpha.1 ~ rc.1:
   ```bash
   dsh plugin --profile web add @wenqi_bian/dsh-dashboard
   # equivalent: dsh plugin --profile web add @wenqi_bian/dsh-dashboard@next
   ```

The previous generation `0.1.1-rc.2` no longer backs any dist-tag; install the exact version if you still need it, but it is not compatible with current harnesses (see Compatibility).

The npm package ships the prebuilt host and client bundles, so no build step is needed on install.

### From source

The source version — `0.1.3-alpha.2`, compatible with the harness source at the `dsh-v0.1.2-alpha.1` through `dsh-v0.1.3-alpha.2` tags (rc.1 equals alpha.5 apart from version numbers; 0.1.3-alpha.2 keeps every field this plugin reads) — is what the GitHub Release `v0.1.3-alpha.2` ships. Install it from source for local development:

```bash
dsh plugin --profile web add .
```

Run it from the repo root; it links the plugin into the web profile that `$DSH_HOME` points at. Rebuild after any code change with `pnpm run bundle` (see Quickstart).

## Quickstart

```bash
pnpm run bundle                    # emit lib/index.js (host) + lib/client.js (browser)
dsh plugin --profile web add .
# restart dsh web, open a conversation, pick the Statistics view
```

The tab appears beside Chat / Trajectory and reads everything on the client from the session's `tokenUsage` / `sessionStats` projections and the conversation snapshot.

## What it shows

- Token layer: input (fresh + cache read), output tokens, cache hit rate.
- Timing: LLM time, tool time, first-token latency, decode rate. The per-turn TTFT curve is drawn only while a session streams; after a reload that card falls back to the durable session average (harness 0.1.3 keeps the first-token timestamp in a client-only event).
- Tool activity: per-tool calls, fails, total and average duration, drawn as proportional segments with a four-color cycle.
- Skills: which `skill` tools were invoked, as chips.
- Insights: tool success rate, think/tool time split, tokens per turn, input:output ratio.
- Locale follows the DSH host (zh / en).

## Data source

Stats are derived on the client from the conversation snapshot's `tool-result` nodes and the built-in `sessionStats` / `tokenUsage` projections, the same source the shipped composer `StatsLine` uses. Every harness-owned name and type the client half touches — the slot name, the projection keys, the `turn-tail` data key, node kinds, and the theme/DOM variables its styles borrow — lives in `src/client/contract.ts`, so a harness upgrade has one file to check. There is no host `@Remote` call, because `@Remote` is not generated for a runtime-loaded out-of-repo plugin. The workspace cross-session aggregate is not implemented.

## License

MIT.