# dsh-token-stats

[English](README.md)

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的跨会话 Token 用量统计插件：设置面板内提供**按供应商与模型拆分的月度堆叠费用图**（美元），带月份导航、供应商/模型筛选和逐模型图例。

以 Harness 官方的可安装 **bundle** 插件格式独立分发——**无需改动核心仓库**。

## 功能

- **总览** — 带用量记录的会话数、四个 provider 用量桶（未缓存输入、缓存读、缓存写、输出）、总计 Token，以及按匹配价格表拆分的估算成本。
- **月度成本图** — 所显示月份按日堆叠的各模型费用柱状图：`<`/`>` 月份切换、供应商与模型筛选、固定两位小数的美元刻度网格线、配色图例。
- **按模型计价** — 用量按供应商/模型精确匹配价格表（内置示例行 `deepseek / deepseek-v4-flash`），未匹配的按默认表计价。价格在本版本中是固定常量，需要改价请调整 `src/client/usage-aggregate.ts` 里的 `DEFAULT_PRICES` / `DEFAULT_PRICE_TABLES` 后重新构建。
- **数据诚实** — 缓存投影早于按模型单元（或未部署这些单元）的会话记为"无模型数据"，按默认单价估算并给出明确提示。

## 原理

bundle 分两半：

- **宿主端**（`src/host/`）— 注册两个会话投影单元：`modelUsage`（按供应商/模型的会话总量）与 `modelDailyUsage`（按供应商/模型/UTC 日的单元），完全沿用 `@deepseek-ai/dsh-token-meter` 的注册模式。注册对已内置同版本单元的部署是幂等的（注册表按引用计数共享同 `stateVersion` 的 key），发布版与已含改动的源码 checkout 都能安全共存。
- **客户端**（`src/client/`）— 注册 `settings.section` 分区（"Token 用量"），读取 `session.list` 投影列（零日志加载）渲染面板；按日单元从 UTC 换算到本地日显示。

## 安装

前置：已安装 DeepSeek Harness（`dsh` CLI 或源码 checkout）。

### 从 npm（发布后）

```sh
dsh plugin --profile <name> add dsh-token-stats
dsh --profile <name> web
```

### 从本仓库

```sh
git clone https://github.com/qiushui0901/dsh-token-stats.git
cd dsh-token-stats
npm install && npm run build
dsh plugin --profile <name> add ./dsh-token-stats
dsh --profile <name> web
```

### 从 DeepSeek Harness 源码 checkout

```sh
pnpm dsh web --patch /path/to/dsh-token-stats/cordis.patch.yml
```

（需将 `dsh-token-stats` 链接进 checkout 的 `node_modules`，或安装进 checkout 启动的 profile。）

打开 `http://127.0.0.1:3080` → 设置 → **Token 用量**。

## 构建

```sh
npm install
npm run build
```

产出 `lib/host.js`（自包含 Node 入口）与 `lib/client.js`（经 `window.__ModuleLoader__.load` 注册的浏览器闭包工厂 bundle）。

## 已知限制

- **模型数据向前填充** — 在 `modelUsage`/`modelDailyUsage` 投影出现之前运行的会话，其投影缓存行重写前仍无模型数据，按默认单价估算。
- **按日分桶为 UTC 偏移近似** — 宿主端按 UTC 日折叠，客户端按时区偏移取整换算到本地日，日界附近的用量可能落在相邻本地日。
- **价格是常量** — 单价表内置在 bundle 中，无 UI 编辑器（按需移除）。

## License

MIT — 见 [LICENSE](LICENSE)。基于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（MIT）的插件系统构建。