dsh-token-stats

全局 Token 用量统计插件（DeepSeek Harness / DSH Web）。

从每一次 llm/stream 调用采集真实 usage（非估算），构建跨重启持久的 JSONL 账本，按供应商 / 模型 / 会话 / 日期聚合，提供估算费用（OpenRouter 实时价格）、缓存命中率、成功率、首字延迟等指标，并通过可拖动的悬浮按钮、居中大屏弹窗和模型工具 token_stats 展示。

运行截图

1. 设置页 · 全局统计

2. 右下角悬浮球 —— 实时展示 token 统计，支持「全局 / 当前会话」切换，可拖动

• 全局统计

• 当前会话统计（与会话底部官方统计对齐）

3. 展开明细 —— 大屏弹窗；右上角可手动从 OpenRouter 拉取最新模型价格并重算全部历史费用

功能特性

• 真实用量采集：waterfall 包装 llm/stream，记录每次成功调用的输入 / 输出 / 缓存读 / 缓存写 / 推理 tokens，失败与取消调用单独计数（成功率口径）
• 跨重启持久账本：每次调用逐条落盘（<profile>/data/token-stats/daily.jsonl），启动 / 热重载时从账本重建全部维度，数字只增不减
• 多维聚合：按供应商、模型、会话、日期（当月 / 近 31 天趋势）分布
• 费用估算：内置价格表 + 一键从 OpenRouter 拉取最新价格并重算历史费用（DSH_TOKEN_STATS_PRICES 环境变量可覆盖单价）
• 缓存命中率 / 成功率 / 平均耗时 / 首字延迟（TTFT）等指标
• 可拖动悬浮球：右下角 FAB，位置持久化，展开面板支持「全局 / 当前会话」切换
• 居中大屏弹窗：KPI 卡片、请求占比环形图、趋势、供应商 / 模型表格、近期调用明细（含单次缓存命中率、首字/耗时）
• 当前会话跟随：通过 DOM 探测 UI 选中的会话行（[role=treeitem][aria-selected=true]）+ host 会话目录标题匹配，自动跟随 UI 切换（执行中/暂停会话均可），失败时回退到最近活跃会话
• 模型工具：token_stats（支持可选 sessionId 参数），模型可直接查询统计
• 历史回扫：backfill-history.mjs 可从 ~/.dsh/sessions 的多帧 zstd 会话文件回扫插件安装前的调用（幂等，自动去重）

安装

方式一：官方 CLI（推荐）——从 GitHub 或 npm 安装：

dsh plugin --profile web add github:<owner>/dsh-token-stats
# 或
dsh plugin --profile web add dsh-token-stats

包内 cordis.patch.yml（dsh.bundle.patch 声明）会让 CLI 自动把 loader 行插入 profile，重启 Web GUI 生效。

方式二：手动放置——将包放入 profile 的 packages/ 目录（如 C:\Users\<you>\.dsh\profiles\web\packages\dsh-token-stats），并在 cordis.yml 的 loader 列表加入：

- id: token-stats
  name: dsh-token-stats

重启 Harness 即可。开发期也可用 dsh-super-injector 热注入（免重启）。

该包为纯 JavaScript，无 prepare 构建脚本，github: 安装无需 allowedBuilds 配置。

使用

• FAB 悬浮球（右下角）：点击展开面板，可拖动；面板右上角「⛶」打开居中大屏弹窗；「全局 | 当前会话」切换统计范围
• 设置页：设置 → Token 统计，包含同样的面板与大屏弹窗入口
• 大屏弹窗：「↻ 更新价格」从 OpenRouter 拉取最新模型价格并重算全部历史费用；KPI、环形图、趋势（当月/近31天）、表格、明细
• 模型工具：对话中调用 token_stats（{"sessionId": "..."} 可选）

配置

环境变量	说明
DSH_TOKEN_STATS_DIR	账本目录覆盖（默认 <profile>/data/token-stats/）
DSH_TOKEN_STATS_PRICES	价格覆盖 JSON：{"<model>": {"input":0.27,"cacheRead":0.07,"cacheWrite":0.27,"output":1.1}}（USD/1M tokens）

价格表默认值来自 OpenRouter 公开模型列表（查询日期见 lib/index.js 注释），可通过面板按钮或环境变量校正。

HTTP API

端点	说明
GET /token-stats/api/query	统计快照（?sessionId= 查单会话）
GET /token-stats/api/sessions	会话目录（id + 标题），供前端跟随 UI 会话
POST /token-stats/api/refresh-prices	从 OpenRouter 拉取最新价格并重算账本费用

所有端点校验 Origin（仅本机）、HEAD 不返回 body。

历史回扫（可选）

插件安装前的调用不会自动出现。可用回扫脚本从历史会话文件补录：

node backfill-history.mjs            # 正式导入（幂等）
node backfill-history.mjs --dry-run  # 预览
node backfill-history.mjs --force    # 强制重跑

仅补录「成功且带 usage」的调用；耗时 / 首字延迟无法回补；费用按当前价格表重算。导入前自动备份账本。

已知限制

• 浏览器端无「UI 当前会话 id」官方接口：当前会话跟随基于 DOM 探测 + 标题匹配，会话列表不可见或标题歧义时回退到最近活跃会话
• 会话维度的分布（供应商/模型/日期）基于保留窗口（最近 500 条）聚合，总量 totals 为完整账本
• 费用为估算值（按模型单价 × 用量），实际结算以你的网关/厂商账单为准
• 统计口径为真实 usage（计费口径：输入 = 未缓存 + 缓存读 + 缓存写），与 DSH 内置 token-meter 的估算口径不同

License

MIT

发布到社区

1. 推送到 GitHub 仓库
2. 给仓库打 dsh-plugin topic（GitHub → repo → About → Topics），即可被 dsh-plugin 生态 与社区插件市场（如 dsh-plugin-market）搜索发现
3. （可选）发布 npm：npm publish --access public
4. （可选）发 Release：npm pack 后把 dsh-token-stats-<version>.tgz 附到 GitHub Release