# dsh-strength-meter —— DSH 0.2.x 模型使用统计

> 为 DeepSeek Harness 设置页提供本地 token 用量统计：指标卡、模型用量环形图、15 周活跃热力图、按天 token 趋势。全部数据通过当前 `sessionQuery` 服务从**本机会话日志**折叠得出，绝不上传。

> English: [README.md](README.md)

| 项目 | 说明 |
|---|---|
| 插件 | `dsh-strength-meter` 2.0.0 |
| 宿主 | DeepSeek Harness **0.2.1-rc.2**（桌面版或 `dsh web`） |
| 层级 | 宿主路由 + 设置页客户端分区 |
| 许可 | MIT |

## 相对 1.x 的变化

DSH 0.2 替换了旧的宿主会话接口。2.0 保持同样的 UI 与路由路径，只把数据来源换成现版本 API：

| 关注点 | 1.x | 2.0.0 |
|---|---|---|
| 活跃会话 | `ctx.sessions.list()` → `session.events` | `ctx.sessions.list()` 取 id，日志统一走 `sessionQuery` |
| 冷会话 | `sessionPersistence.listSnapshots()` / `inspect(id)` | `sessionQuery.readSession(id)`（优先实时、带重放校验） |
| 缓存键 | `listSnapshots` 的 revision | `sessionPersistence.list()` 的 revision（可选，没有也能折叠） |
| 客户端图标 | `@deepseek-ai/dsh-client-ui-primitives` | 本地 SVG（不再引用 primitives） |
| 注册 | `settings.section`（兼容） | `settings.section`（不变） |

折叠逻辑本身（`lib/fold.js`）没有变化，仍与持久化日志语义一致：`request/header` 记录模型，`assistant/message.usage` / `assistant/chunk` 记录 token，用户/助手消息驱动活跃日历。

## 安装

### 插件管理器（桌面版）

把本目录作为 bundle 安装，启用 `dsh-strength-meter`。

### 命令行

```bash
dsh plugin --profile <profile> add /absolute/path/to/dsh-strength-meter
```

### 手动

把包链接进 profile 的 `node_modules`，再在 `cordis.patch.yml` 追加：

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

刷新页面即可，不需要修改 Harness 任何文件。

## 使用

打开 **设置 → 使用统计**（位于内置分区之后）。可切换**最近 7 天 / 最近 30 天**，刷新按钮会绕过 15 秒响应缓存。首次读取会以 4 并发折叠整个语料；之后若持久化 revision 未变则复用折叠结果。

### 路由

`GET /plugins/dsh-strength-meter/usage.json?days=7|30&force=1`

返回 `total`、`models[]`、`sessions`、`messages`、`activeDays`、`streak`、`topModel`、`byDay[]`、`heatmap[][]`，以及含 `corpus`/`folded`/`cached`/`errors` 的 `debug`。

## 验证

```bash
npm test
# → 折叠测试、宿主冒烟测试、bundle 冒烟测试
```

实机检查：打开统计页，有历史数据的 profile 应显示非零指标，热力图应有 15 列。

## 限制

- **响应缓存** 15 秒，`force=1` 可绕过。
- **语料上限** 每次请求最多 400 个会话。
- **不依赖投影**：插件直接折叠原始日志，不注册 `sessionStats` 投影，因此在任何组合下都能工作。

## 许可证

MIT。