dsh-strength-meter

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# ⚡ dsh-strength-meter — Model Usage Stats for DSH Web

> **dsh-strength-meter**: a model token-usage statistics plugin for the DeepSeek Harness Web UI — a full "Usage stats" page in Settings (metric cards, per-model donut, activity heatmap, daily trend). All data comes from your local session logs; nothing is uploaded.

| Language | Link |
| --- | --- |
| English | This document |
| 中文 | [README.zh.md](README.zh.md) |

---

## Table of Contents

- [If you are a human, read this](#if-you-are-a-human-read-this)
  - [What this plugin does](#what-this-plugin-does)
  - [Manual install](#manual-install)
  - [Let an AI deploy it for you](#let-an-ai-deploy-it-for-you)
- [If you are an AI, read this](#if-you-are-an-ai-read-this)
  - [Deployment](#deployment)
  - [Architecture](#architecture)
  - [Debugging](#debugging)
  - [Operating / extending](#operating--extending)
- [License](#license)

---

## If you are a human, read this

### What this plugin does

The plugin adds a full **"Usage stats" page** under Settings → Usage stats, presented in the following blocks:

**Block 1 — six metric cards** (overview at the top)

![Metric cards](docs/screenshots/metrics2.png)

- **Tokens used**: total token consumption in the selected range;
- **Sessions**: sessions active in the range;
- **Messages**: total messages in the range;
- **Active days**: days with any activity in the range;
- **Current streak**: consecutive active days up to today (GitHub-style);
- **Top model**: the model that consumed the most tokens in the range, with its share (%).

The header offers a **time-range switch** (Last 7 days / Last 30 days) and a **Refresh** button (forces a fresh recomputation, bypassing the cache).

**Block 2 — Model usage** (per-model totals)

![Model usage](docs/screenshots/model-usage2.png)

- A **donut** of the total token consumption in the range;
- A legend on the right: model name, tokens and share (%). Same-named models across providers are merged into one row.

**Block 3 — Activity heatmap**

![Activity heatmap](docs/screenshots/heatmap2.png)

- A **15-week × 7-day** matrix in GitHub-contribution style;
- Cell shade scales against the highest-token day in history: ≥75% darkest, ≥50% next, ≥25% mid, >0 light blue, no activity blank (legend "Less → More").

**Block 4 — Daily token trend**

![Daily trend](docs/screenshots/trend2.png)

- A bar chart of tokens per day within the selected range (hover for the exact value), with auto-labeled date ticks.

Statistics are computed from your **local persisted session logs** (`~/.dsh/sessions`) — nothing is uploaded.

### Manual install

**Prerequisites** (all must hold):

1. A working DSH Web (`dsh web`) reachable at `http://127.0.0.1:3080`;
2. You can locate the DSH data dir: `%USERPROFILE%\.dsh` on Windows, `~/.dsh` elsewhere (written as `~/.dsh` below);
3. Network access to this repository (or a local copy).

**Option A — one-command install (recommended, no npm, no build)**

> In mainland China, use the Gitee mirror instead: `https://gitee.com/chill109/dsh-strength-meter` (swap the repo URL in the commands below).

Windows (PowerShell):

```powershell
powershell -ExecutionPolicy Bypass -Command "Invoke-WebRequest 'https://github.com/chou109/dsh-strength-meter/raw/main/install.ps1' -OutFile install.ps1; .\install.ps1"
```

macOS / Linux / WSL (bash):

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/chou109/dsh-strength-meter/main/install.sh)
```

The installer does three things (idempotent — safe to re-run):

1. puts the source into `~/.dsh/plugins/dsh-strength-meter` (zip download or git clone);
2. creates a junction (Windows) / symlink (macOS·Linux) in `~/.dsh/profiles/node_modules`;
3. registers the `dsh-strength-meter` entry in `~/.dsh/profiles/web/cordis.patch.yml`.

**Option B — manual, three steps** (offline environments / to understand the wiring)

1. **Get the source**: `git clone https://github.com/chou109/dsh-strength-meter.git` (or download the zip) anywhere, e.g. `~/.dsh/plugins/dsh-strength-meter`;
2. **Link it** (the loader resolves plugins from `~/.dsh/profiles`):
   ```powershell
   # Windows (junction, no admin rights)
   New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-strength-meter" -Target "$env:USERPROFILE\.dsh\plugins\dsh-strength-meter"
   ```
   ```bash
   # macOS / Linux (symlink)
   ln -s ~/.dsh/plugins/dsh-strength-meter ~/.dsh/profiles/node_modules/dsh-strength-meter
   ```
3. **Register**: append to `~/.dsh/profiles/web/cordis.patch.yml`:
   ```yaml
   - insert:
       - id: dsh-strength-meter
         name: 'dsh-strength-meter'
   ```

**Last step: restart the dsh web process** — a page refresh is not enough for a *newly added* plugin (the plugin set is snapshotted at boot; an already-open tab keeps its old boot manifest):

```bash
# Ctrl+C the running dsh web, then run it again
dsh web
```

**Verify the install** (in order, after the restart):

1. Settings → **Usage stats**: the navigation entry appears and the page renders (six metric cards, donut, heatmap, trend);
2. Browser DevTools → Network: `/plugins/dsh-strength-meter/client.js` and `/plugins/dsh-strength-meter/usage.json` both return 200.

If any check fails, see the "[If you are an AI, read this](#if-you-are-an-ai-read-this)" debugging table, or send the screenshot to the AI that deploys it for you.

### Let an AI deploy it for you

Paste this prompt to your AI assistant (Gitee mirror is faster in mainland China):

> Please deploy the dsh-strength-meter plugin from https://github.com/chou109/dsh-strength-meter.git (or the Gitee mirror, faster in mainland China: https://gitee.com/chill109/dsh-strength-meter.git) to my DeepSeek Harness web profile. Follow the "If you are an AI, read this" section of the README strictly.

---

## If you are an AI, read this

### Deployment

**1. Get the source**

```bash
git clone https://github.com/chou109/dsh-strength-meter.git ~/.dsh/plugins/dsh-strength-meter
# or use the installer (zip + symlink + registration in one shot)
bash <(curl -fsSL https://raw.githubusercontent.com/chou109/dsh-strength-meter/main/install.sh)
```

**2. Link it into the profile's node_modules** (the loader resolves plugins from `~/.dsh/profiles`)

```bash
# Windows (junction, no admin rights)
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-strength-meter" -Target "$env:USERPROFILE\.dsh\plugins\dsh-strength-meter"
# macOS / Linux (symlink)
ln -s ~/.dsh/plugins/dsh-strength-meter ~/.dsh/profiles/node_modules/dsh-strength-meter
```

**3. Register the plugin** (append to `~/.dsh/profiles/web/cordis.patch.yml`, idempotent)

```yaml
- insert:
    - id: dsh-strength-meter
      name: 'dsh-strength-meter'
```

**4. Restart dsh web.** The cordis plugin set is snapshotted at startup (per client-modules: "plugin-set changes take effect on restart"); HMR only refreshes bundle *content* of already-registered plugins.

**5. Verify**

- `GET http://127.0.0.1:3080/plugins/dsh-strength-meter/client.js` → 200, body starts with `window.__ModuleLoader__.load({`;
- `GET http://127.0.0.1:3080/plugins/dsh-strength-meter/usage.json?days=30&force=1` → JSON with `total / models[] / sessions / messages / activeDays / streak / topModel / byDay[] / heatmap[] / days`;
- `window.__DSH_BOOT__.entries` on the page contains `{ id: "dsh-strength-meter", ... }`.

### Architecture

One cordis plugin, two faces:

```
dsh-strength-meter/
├── lib/index.js      # Host face (Node): usage aggregation + web route
├── lib/fold.js       # Pure fold (unit-testable): event log → per-model / per-day stats
├── lib/client.js     # Client face (browser), pre-built, committed to the repo
├── src/client/*.tsx  # Client sources (esbuild build, see scripts/build.mjs)
├── scripts/build.mjs # Self-contained build: esbuild(cjs) + __ModuleLoader__ wrapper
├── install.ps1 / install.sh
└── tests/            # fold unit tests + host/bundle smoke tests
```

**Host face (`lib/index.js`)**

- Depends on `webServer` + `sessions` (declared in the entry `inject` list, the platform convention); registers an **exact** route `/plugins/dsh-strength-meter/usage.json` (exact routes win over client-modules' `/plugins` prefix route, so no conflict).
- Data sources, best-effort:
  - `ctx.sessionPersistence` (full history, optional): `listSnapshots()` returns `{ header, revision }` (the id lives on `header.id`) → cold sessions are cached by `revision`, only changed logs are re-folded;
  - `ctx.sessions` (fallback): live sessions only.
- Fold rules (`lib/fold.js`, aligned with token-meter semantics):
  - `request/header` `data.header.config.{provider,model}` decides billing for subsequent samples (recorded at sample time, positionally correct);
  - usage samples: `assistant/chunk` with `chunk.type === "usage"`, or the `usage` field of `assistant/message`; a message sample for the same `(turn, step)` **replaces** the chunk sample;
  - sum = input + cacheRead + cacheWrite + output; aggregated per model and per day (local timezone).
- Query params: `days=7|30` scopes totals at the **sample level** (old data never leaks into the window); `force=1` bypasses the 15 s TTL cache.
- Metrics: tokens / sessions / messages / activeDays / streak (full history) / topModel (with share %) / byDay[] / heatmap[] (15 weeks × 7 days, shade scaled against the peak token day).
- The payload carries a `debug` block (live/persisted counts and errors) for diagnostics.

**Client face (`src/client/`)**

- Entry `inject: ['slots','locale','sessions']`, one slot registration:
  - `settings.section` (root scope) → `StatsSection`: the full "Usage stats" page (metrics, donut, heatmap, trend), nav label from the `nav.stats` key.
- Same-named models across providers are merged into one row before rendering; shares are recomputed.

**Bundle contract** (mandatory, or the page boot fails)

```js
window.__ModuleLoader__.load({ id: "dsh-strength-meter", factory: (require) => { /* CJS */ return module.exports } })
```

- The artifact must be **pre-built** (the repo ships `lib/client.js`; installs never build);
- Externals are limited to `react`, `react/jsx-runtime` and `@deepseek-ai/*` (resolved by the ModuleLoader's seed/static/factory tables); never bundle platform code;
- `package.json` needs `exports["./client"]` and the `dsh.client` declaration (copy from this repo's `package.json`);
- The bundle's ModuleLoader id is read from `package.json`'s `name` by the build script, so renames cannot desync it.

### Debugging

| Symptom | Check |
| --- | --- |
| No "Usage stats" entry in Settings | Inspect `window.__DSH_BOOT__` — if `dsh-strength-meter` is absent: not restarted, or not registered in `cordis.patch.yml`. If present: look at Network for `/plugins/dsh-strength-meter/client.js` (should be 200). |
| Page blank / all metrics zero | Read the `debug` block of `usage.json`: are `live`/`persisted` zero? What's in `errors`? If `sessions:0`, the host is probably running pre-fix code (old payloads lack the new fields). |
| `usage.json` 404 | Host face didn't start: check the dsh log for errors around `dsh-strength-meter: usage route`; confirm `webServer`/`sessions` exist (they always do in the web profile). |
| Heatmap fully blank | Confirm `usage.json`'s `heatmap` array is non-empty with some nonzero `level`s; hard-refresh the page (Ctrl+Shift+R) to load the new bundle. |
| White screen after editing the bundle | Rebuilt `lib/client.js` yourself? Run `pnpm install` then `node scripts/build.mjs`, or restore the committed artifact. |

**Rebuilding the client (after touching `src/client`)**

```bash
cd dsh-strength-meter
pnpm install        # first time only (renames/moves can break pnpm junctions — reinstall once)
node scripts/build.mjs
# writes lib/client.js (+ source map, handy for browser debugging)
```

Changing a *registered* plugin's bundle does **not** need a restart — a page refresh suffices (client-modules re-injects by content hash). If a `pnpm run dev:web` watcher is running on this machine, updates are hot. **Host-side (`lib/`) changes do require a dsh web restart.**

**Tests**

```bash
node tests/fold.test.mjs      # fold / window / heatmap unit tests (zero deps)
node tests/host.smoke.mjs     # route + usage.json smoke
node tests/bundle.smoke.mjs   # bundle-contract smoke (mocks __ModuleLoader__)
```

### Operating / extending

- **Copy**: `src/client/locales.ts` (Chinese is the key-set source of truth; `en` must match the key set).
- **New stat dimensions**: extend the fold in `lib/fold.js` (event types come from the `dsh-session` log vocabulary), then render in `StatsSection`; keep the verification field list in this README in sync.
- **Heatmap bucketing**: `levelOf` in `lib/fold.js` (currently 4 token-relative buckets against the historical peak day).
- **New slots**: add another `ctx.slots.inject(...)` registration in `src/client/index.ts`; component props are `{ t, ...injectedFace }`.
- **No uploads**: aggregation happens only on this machine (the Host face reads `~/.dsh/sessions`).

## License

MIT — see [LICENSE](LICENSE).