dsh-token-usage

为 DeepSeek Harness（DSH）网页端提供 Token 用量统计：今日/本月/累计、总体与按 provider 两个口径、按日/provider/model 下钻、月历热图、缓存命中率、会话汇总与安全导出。入口位于设置页侧边栏（与"通用/模型/插件"并列的"Token 用量"导航项）。

基于 Ychris12138/dsh-usage-stats（MIT）裁剪实现：只保留 Token 统计，不含余额/订阅/费用/预算等任何计费能力。

功能

	能力
📊	总体 + 按 provider 分列的 Token 统计（四桶：input / output / cacheRead / cacheWrite）
🔥	月历热图（月份切换、日下钻 provider → model 两级明细）
🎯	Provider 过滤 chip：汇总卡片、热图、会话列表一键切换口径（零网络请求）
📦	安全导出：daily.csv / sessions.csv / export.json（仅聚合 Token，无任何敏感字段）
🔄	增量聚合：live 会话尾读 + 持久化日志 revision 跳过，后台每 5 分钟全量扫描

数据口径与可信度

• 数值来自 provider API 自报的 usage（与账单同源，经 DSH 宿主 mapUsage 归一化后落盘），本地不做任何估算。
• 同一 (turn, step) 的重复样本替换而非累加，不会重复计数。
• 已知口径边界：经中转的流量以中转自报为准；中断的流（未到 [DONE]）不计入；cacheWriteTokens 依赖 provider 上报（DeepSeek 官方 API 无此字段）；按本机时区日界聚合。详见 DESIGN.md §9。

安装

dsh plugin --profile web add "github:<org>/dsh-token-usage"   # 或本地路径
# 重启 dsh web，浏览器硬刷新

打开 DSH → 设置，侧边栏会出现"Token 用量"导航项。

升级 / 卸载：

dsh plugin --profile web update dsh-token-usage
dsh plugin --profile web remove dsh-token-usage

与 dsh-usage-stats 可以共存（缓存文件独立），但同时安装会有两份折叠开销，建议只保留其一。

配置

无需任何配置。插件不读取凭据（~/.dsh/.credentials.yaml）、不发起上游网络请求。

API（全部回环 + GET only）

Method	Path	响应
GET	/api/token-usage/usage	按日聚合 Token（含逐日 providers/models）、全期 provider 汇总、session 明细
GET	/api/token-usage/export/daily.csv	每日 × provider × model Token CSV
GET	/api/token-usage/export/sessions.csv	session 级 Token CSV
GET	/api/token-usage/export.json	版本化 JSON 导出

缓存：~/.dsh/storages/token-usage-cache.json（version 1，原子写入，只含聚合 Token 与折叠游标，无 prompt/回复/路径）。

开发与验证

npm run check   # 语法检查
npm test        # 离线测试（usage 折叠语义 / 导出投影 / 服务端安全边界 / bundle 结构）

测试完全离线、零依赖。目录结构：

lib/usage.js    纯函数折叠核心（可独立单测）
lib/index.js    服务端：4 端点 + 增量缓存 + 后台扫描
lib/export.js   secret-free 导出投影
lib/client.js   浏览器 bundle（__ModuleLoader__，settings.section 注册）

兼容性

• 需要 DSH web profile（@deepseek-ai/dsh >= 0.1.0-rc.6；在 0.2.0-rc.1 上开发验证）。
• 持久化与活跃会话读取按能力探测分支：list()/open(id,"read") 与旧版 listSnapshots()/readFrom() 均支持；live 会话同时支持 seq/snapshotEvents() 与旧版 events 数组。
• 设置页入口依赖宿主 settings.section 槽位（与官方"模型/插件"设置页同一机制）。

License

MIT。派生自 Ychris12138/dsh-usage-stats（MIT）。