FantasyStarry/dsh-token-stats

dsh-token-stats

按自然日统计 DeepSeek Harness（DSH）Web 的 LLM token 用量，按提供商 / 模型拆分，
持久化到磁盘，并在 Web GUI 的多个位置展示。

项目介绍页：docs/index.html（单文件 HTML，浏览器直接打开，含安装指引）

功能

- 统计口径：每次成功的模型调用计一次（来自会话事件 assistant/message 的
usage 与 message.source.{provider,model}，与 token-meter 同源）。
失败回合、被重试的尝试不计入。
- inputTokens（未缓存输入）、outputTokens、cacheReadTokens（缓存读）、
cacheWriteTokens（缓存写）、reasoningTokens（推理）
- 计费输入 ≈ inputTokens + cacheReadTokens + cacheWriteTokens
- 费用估算与官方余额（v0.10.0）：按模型参考价把 token 换算成人民币
（内置 DeepSeek 官方空闲时段价：deepseek-v4-flash / -vision-exp 未缓存输入 1.5 元、
缓存命中 0.05 元、输出 4.5 元每百万；deepseek-v4-pro 4.5/0.15/13.5；
高峰时段 ×2，故估算为“至少”值；deepseek-chat / -reasoner 旧参考价保留）。
键支持前缀匹配（deepseek-v4-flash-0731 / DeepSeek-V4-Flash-0731 均命中
deepseek-v4-flash），未匹配的模型费用显示 — 并计入「未计价」；
单价可在插件配置 prices 按模型覆盖（缺省 cacheWrite = 未缓存输入、
reasoning = 输出）。费用展示于：设置页概览/模型明细/7 天与 30 天逐日表、
热力图 tooltip、CSV（估算费用列）、宠物弹窗、/usage；
官方余额：GET /user/balance（DEEPSEEK_API_KEY 经 credentials 通道，
服务端 60s 缓存），设置页概览与 /usage 展示，未配置密钥时优雅隐藏；
- 按自然日（服务器本地时区 YYYY-MM-DD）聚合，历史保留 366 天（可配）。
- 启动重建（v0.1.1）：每次加载插件时把“今天”的统计从会话日志整体重算
（$DSH_HOME/sessions 下今天有写入的 zstd/jsonl 日志，完整解码全部 zstd 帧），
再叠加实时订阅的新事件。插件无论何时安装/重启/热重载，今天的数据都以日志为准，
不漏计、不重复计数。
- 四处展示（v0.2.0 起，数字用 k/m/b 缩写）：
1. 悬浮用量宠物（v0.6.0 / v0.7.0 / v0.8.0 / v0.9.0 打磨）（shell.overlay）：右下角一只圆滚滚的史莱姆
（纯 CSS/SVG 绘制，无图片资源）。v0.8.0 参考 Codex 桌宠（Boba / Desk Otter）设计语言：
角色描边 + 底部暗影 + 地面阴影落地、尺寸加大（64px）、hover 探头、双击逗宠物
（4 颗爱心依次飘起，最大一颗最后飞出 + 蹦跳 + 开心脸）。v0.9.0 赋予生命力：
情绪切换 180ms 弹入过渡、待机身体浮动 + 眼睛左顾右盼、工作态屏幕光标闪烁 +
加载点、晕眩双星对称环绕 + 身体摇摆；面板头部显示当前状态行（工作中/忙到冒汗/
转圈圈/打瞌睡/休息中/干完活啦，彩色圆点）。v0.9.1：身体径向渐变（高光→主体→暗边）、晕眩螺旋眼自旋（替代 X 眼，不再像“挂了”）、弹窗标题小史莱姆、空态打瞌睡史莱姆。情绪 = 实时工作状态 + 今日用量：
- 工作中（v0.7.0）：服务端把 activity（上次活动时刻 + 最近完成列表）
附带进 /token-stats/summary，客户端 2.5s 轮询；只要任何会话在活动
（turn/start、tool/call、assistant/chunk 等事件都会刷新活动时刻），
宠物就“专注盯小电脑”（表情 + 打字颠簸 + 白屏小电脑蓝色进度条动画 +
右上角脉冲点动画 + 扩散光环动画），悬停气泡显示「正在干活…」；
- 空闲：0 请求 → 打瞌睡、轻用量 → 休息眯眼、.csv；
- 深色主题（v0.9.5 回归验证）：热力图五档/空档格、悬浮卡片（深色走
--dsw-alias-bg-layer-2）、sparkline、日期导航、弹窗迷你热力图全部
深浅色自适应，Playwright 深色截图回归通过（ui8-dark.py，结束后还原主题）；
- 加载态：首屏/刷新时显示 shimmer 占位（v0.9.0）；
4. /usage 命令：对话中输入 /usage 直接查看今日用量（缩写 + 子代理对账行，
结果渲染为对话流节点；v0.9.6 起含「近 7 天趋势 ▁▂█▅▃▆█ 合计…」趋势条，v0.9.9 起
支持区间参数 /usage 7（汇总最近 N 天，非法参数回退今天，上限 366）；文案由纯函数 buildUsageText 生成（pnpm test 覆盖；服务端改动需重启 dsh web 生效）。
- 设置页“插件配置”表单（v0.4.0）：设置 → 插件 页出现 token-stats 卡片，
可修改 storagePath / keepDays，保存即实时生效（改路径会先把旧数据落盘，
再在新路径从日志重建今天）。统计面板本身在 设置 → 用量统计（插件页不展示
统计内容，那是独立的 settings 分区）。
- HTTP API（同源，供客户端插件使用）：
- GET /token-stats/summary?day=YYYY-MM-DD（默认今天；每模型带 cost/全天 unpriced）
- GET /token-stats/history?days=N（默认 7，上限 30）
- GET /token-stats/sessions?day=YYYY-MM-DD（v0.3.0：按会话明细，含子代理标记）
- GET /token-stats/balance（v0.10.0：官方余额，Bearer DEEPSEEK_API_KEY，
60s 缓存；未配置密钥 → { ok:false, error:"no-api-key" }）

截图

| 设置页「用量统计」（浅色） | 活跃热力图 + 悬浮卡片（深色） |
| --- | --- |
| 设置页用量统计 | 活跃热力图 |

悬浮用量宠物与弹窗（迷你热力图 / 情绪状态）：

宠物弹窗

安装

从 GitHub 安装（推荐，锁定版本标签）：

dsh plugin --profile web add "github:FantasyStarry/dsh-token-stats#v0.4.0"

本地源码安装（开发调试）：

1. 安装进 web profile（file: 引用源码目录）
dsh plugin --profile web add "file:C:/path/to/dsh-token-stats"

2. 在 $DSH_HOME/profiles/web/cordis.patch.yml 中激活：
- insert:
- id: token-stats
name: dsh-token-stats

3. 重启 dsh web（服务端插件代码变更需要重启加载；浏览器刷新页面加载客户端插件）

开发迭代注意：本机 profile 的 nodeLinker: hoisted（pnpm v11）会把 file:
依赖拷贝进 node_modules，并非符号链接。改代码后需要重新
dsh plugin --profile web add "file:..." 或手动把 lib/ 同步到
node_modules/dsh-token-stats/lib/：客户端 bundle（client.js）是每次请求实时
读文件的，同步后刷新浏览器即生效；服务端（index.js）需要重启 dsh web。

升级插件：改代码 → 提交推送 → 打新标签（如 v0.2.0）→
dsh plugin --profile web add "github:FantasyStarry/dsh-token-stats#v0.4.0" → 重启 dsh web。

注意（v0.1.0 已知问题，v0.1.1 修复）：DSH 会话日志（session.jsonl.zstd）是
多帧 zstd 容器——每批事件追加一个独立压缩帧。v0.1.0 的回填用
zstdDecompressSync 解整个文件只能得到第一帧（通常是 session 头），导致启动回填
实际读到 0 条 usage：插件加载之前发生的调用全部漏计（实测漏掉约 3/4 的用量）。
v0.1.1 改为按帧完整解码 + 每次加载重建今天，数据与日志完全一致。

配置

cordis.patch.yml 行支持 config：

- insert:
- id: token-stats
name: dsh-token-stats
config:
storagePath: C:/path/to/token-stats.json   # 默认 $DSH_HOME/storages/token-stats.json
keepDays: 366                              # 历史保留天数
按模型单价表（元/百万 token，可选；键支持前缀匹配，覆盖内置参考价）
prices:
deepseek-v4-flash: { input: 1.5, cacheRead: 0.05, output: 4.5 }  # 缺省 cacheWrite=input、reasoning=output
my-provider/other-model: { input: 3, output: 6 }

数据文件

默认 $DSH_HOME/storages/token-stats.json（原子写入，防抖落盘）：

{
"days": {
"2026-08-14": {
"opencode-go": {
"deepseek-v4-flash": {
"requests": 29, "inputTokens": 8000, "outputTokens": 16000,
"cacheReadTokens": 6800000, "cacheWriteTokens": 0, "reasoningTokens": 0
}
}
}
}
}

结构

src/index.ts    服务端插件源码（TypeScript，strict）
src/client.ts   客户端插件源码（AMD bundle，window.__ModuleLoader__ 加载）
lib/index.js    tsc 编译产物（运行/发布用，改 src 后 pnpm build 重新生成）
lib/client.js   tsc 编译产物
tsconfig.json   strict 编译配置（ES2022 + ESNext 模块，输出 lib/）
test-standalone.mjs   服务端逻辑独立测试（pnpm test）
audit-sessions.mjs    会话日志审计工具：完整解码所有日志并与插件统计对比
verify-real.mjs       用真实日志验证重建逻辑（storage 指向临时文件，不碰真实数据）
verify-ui.py    Playwright 端到端验证（python verify-ui.py）
verify-pet.py   Playwright 用量宠物验证：情绪/气泡/面板/拖拽/开关 + 截图
（python verify-pet.py）
verify-live.py  Playwright 实时活动验证：路由注入 activity，验证工作脸/脉冲点/
完成提示/收工提示/休息表情（python verify-live.py）
ui4-shots.py     v0.9.1 UI 验证：宠物螺旋眼/渐变/弹窗小史莱姆 + 设置页 sparkline/命中率
去重/刷新旋转/对账条件化/空态史莱姆/移动端零溢出（python ui4-shots.py）
ui5-shots.py     v0.9.2 UI 验证：活跃热力图（真实 30 天 + mock 366 天全年：53 列/12 个月
标签/今天描边/图例/五档分布/自动滚到最右）（python ui5-shots.py）
ui6-shots.py     v0.9.3 UI 验证：热力图悬浮卡片（fixed 定位/内容断言）+ 宠物弹窗迷你
热力图（真实 30 天 + mock 210 天 ≈ 31 列）（python ui6-shots.py）
ui7-shots.py     v0.9.4 UI 验证：日期导航（‹ ›/回到今天/未来禁用/历史空态文案）+
CSV 下载（文件名/表头/行数断言）（python ui7-shots.py）
ui8-dark.py      v0.9.5 深色主题回归：热力图/悬浮卡片/sparkline/弹窗在深色下的
截图与计算样式断言，结束自动还原主题（python ui8-dark.py）
ui9-shots.py     v0.9.7 UI 验证：热力图格子点击跳转该天（chip/标题断言）+
会话 ID 点击复制（剪贴板内容/✓ 反馈断言）（python ui9-shots.py）
verify-cost-ui.py v0.10.0 UI 验证：mock 新服务端响应（带 cost/unpriced/余额），
断言概览估算费用与官方余额、模型/历史表「费用」列、宠物弹窗
估算费用、旧服务端无 cost 字段兼容、无页面错误
（python verify-cost-ui.py）
CHANGELOG.md     版本历史

开发流程：改 src/.ts → pnpm build（tsc 生成 lib/.js）→ 把 lib/ 同步到
profile 的 node_modules/dsh-token-stats/lib/ → 刷新浏览器（客户端）/ 重启
dsh web（服务端）。服务端插件对 @deepseek-ai/schemastery、@deepseek-ai/dsh-settings
使用动态 import + 优雅降级（解析不到时仅无配置表单）。

说明

- 数据源可靠性：assistant/message 事件在适配器上报时携带 usage
（DeepSeek 官方适配器与 pi-ai 适配器均上报）。未上报的调用不会计入。
- 重建只覆盖当前自然日；更早的天依赖插件当时在运行（实时计数），
插件没在运行期间发生的调用不会补计。
- 客户端插件无需重新构建 web 前端：宿主扫描带 dsh.client 字段的包并通过
/plugins//client.js 运行时提供。