dsh-token-usage — DSH Token 用量统计插件

在 DeepSeek Harness Web UI 的侧边栏底部（设置按钮旁）增加「Token 用量」入口， 打开一个统计面板，按 API（provider）、模型 和 日期 分类展示模型调用的 Token 消耗，并配有流畅的入场/更新动画（数字滚动、柱状图生长、环形图描边、 逐项 stagger），自动适配深色/浅色主题（复用 DSH 的 --dsw-* 设计令牌）。

界面预览

趋势图：输入 / 输出 / 缓存命中 / 成本曲线

每日用量热力图：近一年按天展示 Token 用量

模型汇总与最近请求：按模型统计，支持导出

模型价格配置：自动同步价格，支持手动覆盖

工作原理

• Node 端（lib/index.js）：监听 llm/stream waterfall 事件，捕获每次 模型调用的 usage chunk（输入 / 输出 / 缓存读 / 缓存写 / 推理 tokens）， 逐条追加持久化到 ~/.dsh/storages/token-stats/usage.jsonl，并通过 /token-stats/api/overview?days=5h|hour|7|month|30|90|year|custom&start=...&end=...&provider=xxx&model=xxx 提供聚合结果（时间序列 series、统计 totals、缓存命中率 cacheHitRate、筛选下拉选项 filterOptions）；另提供轻量 /token-stats/api/heatmap?days=364 接口供热力图使用，以及 /token-stats/api/export（流式 NDJSON 导出全部历史记录）和 /token-stats/api/clear（清空历史）。聚合为单趟扫描（50 万条记录每次请求 约 75–130ms，原实现约 300ms，且不再为每个模型累积临时记录数组）， 价格为按模型缓存查找。
• 浏览器端（lib/client.js）：注册 sidebar.footer.action 槽位 （id token-usage），点击后打开统计面板：
  • 6 张统计卡：总 Tokens、请求数、输入、输出（含推理提示）、总命中率、估算成本（USD） （DeepSeek 等多数 provider 不报告 cache 读写明细，故不单列缓存卡片）
  • 成本估算：按模型单价（$ / 100万 tokens，输入 / 输出 / 缓存读 / 缓存写）× 实际用量计算； 价格自动同步自 modelradar.cn（启动时拉取 + 每日刷新， 缓存于 prices-auto.json）。注意单位：modelradar 数据集按模型原生币种计价 （294 个模型里 183 个为 CNY），插件统一取数据集的 *PriceUsdPer1M 换算字段 存成 USD，CNY 来源的模型在面板中标注「自动·源CNY」；「$」按钮可查看自动匹配结果、 按名称搜索模型、手动覆盖或强制刷新；手动价格优先于自动价格，未定价模型会在成本卡上提示
  • 大趋势图：按「输入(深蓝) / 输出(琥珀) / 缓存命中(绿) / 成本(红)」四条纯线条平滑曲线（单调插值， 无过冲越界，背景色光环描边保证交叉处清晰），不加面积填充； token 曲线共用左侧 y 轴，成本曲线使用右侧 $ y 轴； 点击图例可隐藏/显示任意曲线（y 轴自动重定标，便于对比任意两条）； 支持区间切换（5小时 / 当日 / 近7天 / 当月 / 近30天 / 近90天 / 今年 / 自定义（最长30天））， x 轴按整段横轴均分，悬停显示十字线与明细；切换 API / 模型 / 日期范围时会平滑过渡曲线； 单数据点（如当日 0 点档）时绘制圆点而非隐形的零长度曲线
  • 每日用量热力图（GitHub Contribution 风格）：近一年（52 周）按天展示 Token 用量， 左侧带周几标识，蓝色越深表示当天用量越高，悬停可查看具体日期与用量； 跟随当前 API / 模型筛选
  • 模型汇总表：按模型展示请求数、输入、输出、缓存命中、缓存写、估算成本；点击行可筛选图表
  • 数据导出：最近请求卡片右上角的导出菜单支持 JSONL（全部历史记录，流式下载）、 JSON（当前视图）、CSV（最近请求）、CSV（模型汇总）， 以及两步确认的「清空全部历史」操作（清除内存窗口并截断 storage 文件）
  • 模型 / API 筛选：只查看指定模型或提供方的数据（统计卡与图表同步过滤）
  • 最近请求：最新 30 条调用记录（时间 / API / 模型 / tokens，悬停可查看用途与会话 ID）， 列表限高滚动
  • 每 15 秒自动刷新，也可手动刷新；标签页隐藏时暂停后台轮询，手动刷新不受影响

安装

方式一：npm 安装（推荐）

dsh plugin --profile web add @zerro223/dsh-token-usage

包声明了 dsh.bundle.patch，dsh plugin 会在 pnpm 安装后自动把它加入 profile 的 layer 栈（无需手动改 cordis.patch.yml）。重启 DSH Web 生效。 其他 profile（tui / headless）把 web 换成对应名字即可，数据共享同一份存储。

方式二：本地源码安装

1. 将 @zerro223/dsh-token-usage 目录复制到 profile 的 node_modules：

   C:\Users\<you>\.dsh\profiles\web\node_modules\@zerro223/dsh-token-usage\
   

2. 在 C:\Users\<you>\.dsh\profiles\web\cordis.patch.yml 中追加：

   - insert:
       - id: token-usage
         name: '@zerro223/dsh-token-usage'
   

3. 重启 DSH Web（dsh web），打开 http://127.0.0.1:3080。

方式三：本地目录 / Git 仓库安装

# 本地目录（file: 协议，绝对路径或相对路径均可）
dsh plugin --profile web add file:D:/path/to/dsh-token-usage

# GitHub 仓库（需要 allowBuilds 时按 pnpm 提示配置）
dsh plugin --profile web add github:zerro-223/dsh-token-usage

数据

• 存储位置：~/.dsh/storages/token-stats/usage.jsonl（每请求一行 JSON）。
• 内存上限：最近 50 万条记录（超出时丢弃最旧）。
• 文件超过 128MB 会自动压缩为最近 50 万条，避免磁盘无限增长；压缩前会先合并 磁盘上当前存在的最新记录（按行键去重），因此多个 profile 共享同一存储时 不会互相覆盖丢数据。
• profile 说明：插件依赖 webServer 服务（当前 cordis 版本不支持可选注入）， 因此记录与统计仅在有 web 服务的 profile（如 web）中激活；不同 profile 间 的存储文件仍在磁盘层面共享（压缩时合并、不丢数据）。
• 重试 / 重复请求：每次真实到达 provider 的调用都会记录（llm/stream 瀑布每次调用触发一次；llm-retry 的重试经由 agent loop 的 agent/request-error 重新发起请求，因此每次尝试都会计入）。
• 卸载插件不会删除历史数据；重新启用即恢复统计（「清空全部历史」除外）。

开发

• lib/index.js：node half（无第三方运行时依赖，仅 @deepseek-ai/dsh-home-paths）。
• lib/client.js：browser half（__ModuleLoader__.load 格式，依赖 react / @deepseek-ai/dsh-client-ui-primitives，无第三方图表库， 图表全部为手写 SVG / CSS 动画）。