dsh-usage-info

Readme

# dsh-usage-info

DSH（DeepSeek Harness）Web 插件：在 **设置 → 插件** 下方新增一个 **用量信息** 页面，按 **今日 / 本月** 统计每个使用过的模型的 **API 请求次数** 和 **Tokens**。

> 只做本地统计：**不计算价格**、**不查询官方余额/账单**、**不发起任何上游网络请求**。数据全部来自 DSH 本机会话日志，重启不丢失。

## 这个项目是做什么的

DSH 官方没有直接的“用量信息”消费页面；本项目补上一张本地账本视图，回答两个问题：

- 今天 / 这个月一共调用了多少次模型 API？
- 每个模型（`厂商/模型`）各请求了多少次、用了多少 Tokens？

## 功能

- 在 **设置 → 插件** 下方新增 **用量信息** 导航项。
- 今日 / 本月两个时间视图。
- 按 `厂商/模型` 分组统计：
  - 请求次数
  - Tokens 输入（缓存命中）
  - Tokens 输入（缓存未命中）
  - Tokens 输出
- 同一厂商的模型排在一起；厂商顺序与模型列表一致，厂商内部模型按 A-Z 排序。
- 页面接口直接返回内存快照，打开快、不等待历史扫描。
- 服务端启动后自动从本地会话日志全量重建历史统计，之后仅增量同步，重复打开不重扫。
- 纯本地 JSON 持久化，不依赖数据库、不依赖第三方服务。

## 安装

### 方式一：GitHub 安装（推荐）

```bash
dsh plugin --profile web add "github:<你的GitHub用户名>/dsh-usage-info"
```

然后重启正在运行的 `dsh web`，刷新浏览器（建议 Ctrl+F5 硬刷新）。

### 方式二：手动 pnpm 安装

```bash
cd ~/.dsh/profiles/web
pnpm add "github:<你的GitHub用户名>/dsh-usage-info"
```

再编辑 `~/.dsh/profiles/web/package.json`，把 `"dsh-usage-info"` 加入 `dsh.profile.bundles` 数组：

```json
"dsh-usage-info"
```

然后：

```bash
pnpm install
# 重启 dsh web
```

### 方式三：本地源码安装（开发/体验）

```bash
cd ~/.dsh/profiles/web
pnpm add /path/to/dsh-usage-info
# 同样把 "dsh-usage-info" 加入 dsh.profile.bundles，再 pnpm install
```

## 使用

1. 重启 `dsh web`。
2. 打开 Web 界面，进入 **设置**。
3. 点击左侧导航中 **插件** 下方的 **用量信息**。
4. 在页面顶部切换 **本月 / 今日**。

## 统计口径

| DSH 会话事件 | 请求次数 | Tokens 来源 |
| --- | --- | --- |
| `assistant/message` | 计 1 次 | provider 上报的最终 usage |
| `compaction/summary` | 计 1 次 | provider 上报的最终 usage |
| `session/title-llm-request` | 计 1 次 | DSH 不持久化标题调用 usage，因此 Tokens 为 0 |

- `Tokens 输入（缓存命中）` ← `cacheReadTokens`
- `Tokens 输入（缓存未命中）` ← `inputTokens + cacheWriteTokens`
- `Tokens 输出` ← `outputTokens`
- 流式过程中先出现的 usage 样本会被同一步最终的 `assistant/message` usage 替换，不会重复累计。

## 数据与隐私

- 统计结果缓存于：`~/.dsh/storages/dsh-usage-info.json`
- 原始数据只读取 DSH 本机会话日志，不修改、不上传任何会话内容。
- 页面数据接口 `/api/dsh-usage-info/summary` 仅接受 `GET`，并校验请求来自本机回环地址。
- 删除缓存文件后，下次启动会从本机会话日志自动重建。

## 兼容性

- 需要 DSH 的 `web` profile（`@deepseek-ai/dsh >= 0.1.0-rc.6`）。
- 依赖 web profile 中自带的 `webServer`、`sessions`、`sessionPersistence` 服务。
- 无密钥要求，无第三方运行时依赖。

## 开发

```bash
npm run check
# 或
node --check lib/index.js
node --check lib/usage.js
node --check lib/client.js
```

## License

MIT