用量统计 iuuuuuuuu/dsh-usage-stats

dsh-usage-stats

DSH 插件：统计每天的 token 消耗与平均首字延迟，可按工作区与会话拆分。

数据全部来自本机会话日志（$DSH_HOME/sessions），只读，不写入任何既有文件。

功能

- 按天统计：未缓存输入 / 缓存读取 / 输出分列，另给总 token 与占比。
- 三层下钻：总览 → 按工作区 → 点进工作区看按会话明细。
- 平均首字（TTFT）：精确值，与 DSH 自带统计口径一致（见下）。
- 时间筛选：今天（默认）/ 近 7 天 / 近 30 天 / 自定义区间。
- 表头排序：任意指标列可点，升降序切换。
- 保留一个月：默认 30 天窗口，更早的会话不参与统计（日志本身不动）。
- 两个入口：设置里的「用量统计」一栏；可开关的侧边栏图标（打开独立全宽面板）。

安装

dsh plugin --profile <profile> add "file:<本目录绝对路径>"

也可以从 GitHub 安装：

dsh plugin --profile <profile> add "git+https://github.com/iuuuuuuuu/dsh-usage-stats.git"

装完刷新页面即可在「设置 → 用量统计」看到，侧边栏也会多一个柱状图图标。

口径

这些数字怎么算出来的，以及为什么这么算：

token 用量

取自每条 assistant/message 自带的 usage，四个 bucket 互不重叠：

| 列 | 字段 | 说明 |
| 未缓存输入 | inputTokens | 真正按输入价计费的部分 |
| 缓存读取 | cacheReadTokens | 命中缓存的部分，单价低得多 |
| 输出 | outputTokens | 生成的部分 |
| 缓存写入 | cacheWriteTokens | 已统计但默认不单列 |

「总 token」= 未缓存输入 + 缓存读取 + 输出。缓存读取单独成列而不是并入总量：实测本机它占总量 96%，混在一起会把真正影响花销的未缓存输入淡化掉。

按天归属

用每条事件自身的 time（毫秒）归属到本地日，因此跨天会话会被正确切开，而不是把整个会话算到某一天。

平均首字（TTFT）

精确值。DSH 把流式增量以「打包片段」写入会话日志（text-chunks / reasoning-chunks / tool-call-chunks，每条带 time0 与相邻间隔 dt[]），据此可精确重建每个增量片段的时刻，从而还原首字边界。

复原算法与宿主 assistantStreamFirstTokenTime 等价：

1. 从 time0 起累加 dt，得到每个片段的时刻；
2. 首个「非空片段」即首字（带 name 的工具调用 run 以其首成员为准）；
3. assistant/attempt 也要处理：重试时首个 attempt 给出的首字早于最终 message，漏掉它会让结果系统性偏大。

实测 185 个已完成会话与 DSH 自身记录的 ttftMs / ttftSteps 逐值完全一致。

会话去重

DSH 升级迁移会话格式时会把旧文件留下（session.jsonl.zstd 与 session.v3.jsonl.zstd 同 id 并存）。若两份都算，token 会重复计数——而虚高后的数字看起来完全正常，极难察觉。因此按会话 id 去重，保留格式版本更高的那份。

性能

冷启动要读全部历史日志（本机约 400 MB / 190 个会话，实测约 38 秒），因此：

- 插件启动后在后台预热，界面在此期间显示进度条，不会卡住；
- 扫描分片进行并让出事件循环，避免长时间独占宿主；
- 结果落盘缓存（$DSH_HOME/usage-stats/cache.json），之后按 (mtime, size) 增量——实测无变化时启动即可查询（约 0.05 秒）；
- 会话日志是仅追加的，已结束的会话可安全复用缓存。

数据与隐私

- 只读会话日志，不修改、不删除任何既有文件。
- 自己的缓存写在独立目录 $DSH_HOME/usage-stats/。
- 侧边栏开关是纯客户端偏好，存浏览器 localStorage，不写 settings.yaml。
- 不联网，不上报任何数据。

开发

node --test test/core.test.mjs # 数据核心（合成日志）
node --test test/host.test.mjs # 宿主半（状态机 / 路由 / 缓存）
node test/ttft.test.mjs # 首字复原 vs 宿主权威值（需本机有 DSH 数据）

test/real.test.mjs 与 test/plugin-live.test.mjs 依赖本机真实数据，用于把插件输出与独立复算、以及真实实例逐值比对。

限制

- 仅支持 zstd 格式的会话日志（DSH 默认）。compression: 'none' 的部署读不到。
- 缓存格式版本变化时需重扫一次（会自动丢弃旧缓存）。
- 统计窗口固定 30 天，暂不可配置。