Token 用量统计 IZRINO/dsh-token-stats

dsh-token-stats

English: DeepSeek Harness token usage statistics plugin — all sessions, hourly / daily / weekly / monthly aggregation, and a multi-series line chart for input, cache read, cache write, output, and total tokens.

中文：DeepSeek Harness 的 Token 用量统计插件 —— 统计全部会话，按小时 / 天 / 周 / 月聚合，折线图同时展示输入、缓存读、缓存写、输出和总 token。

DeepSeek Harness（DSH）的 Token 用量统计插件。在设置面板新增一个「Token 统计」页面，统计全部会话的模型调用 token 用量，提供小时 / 天 / 周 / 月四种粒度和自绘 SVG 折线图。

第一版范围：

- 只统计 token 与调用次数，不做费用统计；
- 全部会话，不按 workspace 过滤；
- 输入 / 输出 / 缓存读 / 缓存写 / 总数 / 调用次数 / 缓存命中率；
- 历史 session 自动 backfill，之后按 session 增量折叠；
- 数据只在本机，API 只接受 loopback 请求。

安装

需要 DSH web profile 和可用的 dsh plugin：

dsh plugin --profile web add <本目录的路径或 npm/GitHub 地址>

然后重启 dsh web，打开 设置 → Token 统计。

本地目录安装示例：

dsh plugin --profile web add /home/izrino/code/dsh-token-stats

配置

在 profile 的 cordis.patch.yml 中给 token-stats 行加 config（不要新增重复插件行）：

- insert:
- id: token-stats
name: dsh-token-stats
config:
timezone: Asia/Shanghai
weekStart: monday
retainDays: 365
dataDir: ''
inject:
- webServer
- sessions
- sessionPersistence

| 配置 | 默认值 | 说明 |
| enabled | true | 为 false 时插件不激活 |
| dataDir | '' | 缓存目录。空值使用 $DSH_HOME/storages/dsh-token-stats；相对路径基于 $DSH_HOME 解析；也接受绝对路径 |
| timezone | system | 天/周/月边界时区。system 表示宿主机时区，也可写 IANA 名称，例如 Asia/Shanghai、UTC |
| weekStart | monday | 周统计的起始日：monday 或 sunday |
| retainDays | 365 | 小时桶保留天数，7–3650 |

配置错误会在插件加载时拒绝启动，不会静默忽略。

架构

DSH session log（真源） │ │ session/event（实时） + sessionPersistence.readFrom（历史/增量） ▼ usage-fold.js：每个 session 一个折叠状态 │ usage chunk 与 assistant/message 同 (turn,step) 替换，不重复计数 ▼ cache.json：原子 JSON 快照，可随时删除重建 │ ▼ host API：/api/token-stats/summary|series|breakdown|health │ loopback-only + GET-only ▼ lib/client.js：settings.section「Token 统计」页面 + 多序列 SVG 折线图（输入/缓存读/缓存写/输出/总量，图例可开关；打开时每 60 秒自动刷新）

为什么从 session 事件采集，而不是监听 llm/stream

- session log 是持久化真源，可回放、可重启恢复；
- 历史会话可以在安装插件后 backfill；
- usage 的替换语义与官方 dsh-token-meter 对齐：同一 (turn, step) 先出现的流式 usage chunk 会被最终 assistant/message usage 替换，而不是累加。

指标口径

- inputTokens：未缓存输入；
- outputTokens：输出；
- cacheReadTokens / cacheWriteTokens：缓存读 / 缓存写；
- totalTokens = 上述四项之和，reasoning 不计入；
- calls：最终采用的 usage 样本数；
- cacheHitRate = cacheReadTokens / (inputTokens + cacheReadTokens + cacheWriteTokens)，无 prompt token 时为 null。

Host API

所有接口只接受来自 127.0.0.0/8 或 ::1 的 GET 请求。

| 接口 | 参数 | 返回 |
| /api/token-stats/series | granularity=hour\|day\|week\|month，metric，fromMs，toMs，可选 timezone | 折线图数据点，缺失周期补零 |
| /api/token-stats/summary | fromMs，toMs，可选 timezone | 范围汇总、调用数、缓存命中率、活跃天数 |
| /api/token-stats/breakdown | groupBy=model\|provider，fromMs，toMs，limit | 按模型/服务商分组的聚合行 |
| /api/token-stats/health | 无 | 时区、weekStart、已缓存 session 数 |

示例：

curl 'http://127.0.0.1:3080/api/token-stats/series?granularity=day&metric=totalTokens'

开发与测试

无需安装依赖：

npm test
npm run check

- lib/usage-fold.js：纯折叠与聚合逻辑；
- lib/cache-store.js：原子缓存读写；
- lib/index.js：host Cordis 插件 + HTTP API；
- lib/client.js：零构建步骤的浏览器 bundle（window.__ModuleLoader__.load），只从 DSH 客户端模块表 require react。

cache.json 是纯派生数据，删除后下次请求会从 session 日志重建。

已知边界

- /series 为控制折线图点数设有范围上限：小时 90 天、天 730 天、周 1825 天、月 3650 天；页面默认范围远小于上限。
- DSH 目前是 pre-release，插件契约随版本变化；本插件按当前 DSH 0.1.0-rc.x 的 settings.section、session/event、sessionPersistence 契约实现。
- 周/月/天按配置时区归桶；DST 地区的小时桶可能落在两个本地日期的边界上，按 UTC 小时的本地起始归属。
- 缓存只在 API 请求、实时事件防抖和 session/flush 时落盘。
- 设置页只显示汇总，不保存原始调用明细；后续要做逐调用导出需要新增明细表。