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 时落盘。
• 设置页只显示汇总，不保存原始调用明细；后续要做逐调用导出需要新增明细表。