huantian1223/dsh-token-stats

dsh-token-stats

DeepSeek Harness（DSH）的 Token 用量统计插件。直接解析 DSH 会话日志（session.jsonl.zstd）中的真实 provider usage 数据，在 Web GUI 内提供完整的用量统计：累计/今日/峰值 Token、最长聊天时长、连续使用天数，以及 12 个月的活动热力图（每日/每周/累计），并按模型、工作区拆分明细。

Token 使用统计

功能

统计卡片（6 张，3×2 布局）

页面顶部以 3 列 × 2 行对称展示六项核心指标，窄屏自动降为 2 列：

| 卡片 | 含义 |
|---|---|
| 累计 Token 数 | 输入 + 输出 + 缓存读取 + 缓存写入 的全量累计 |
| 今日 Token | 今天截至当前的用量，副标题含调用次数与占累计比例 |
| 峰值 Token 数 | 单个会话的最高消耗，标注发生日期 |
| 最长聊天时长 | 单次连续会话的最长时长（会话按 30 分钟无活动切分） |
| 当前连续天数 | 从今天（或昨天）往前连续有使用的天数 |
| 最长连续天数 | 历史最长连续使用记录 |

「活跃日」定义：当天有任何 token 消耗即算活跃。

Token 活动热力图

GitHub 风格的 7 行日历网格（周一至周日），滚动 12 个月窗口，两个维度可自由组合：

- 三种视图：
- 每日：每个格子 = 当天用量
- 每周：每个格子 = 所在周的合计（整列 7 格同色，一眼看出"这一周有活动"）
- 累计：每个格子 = 截至当天的累计值（左暗右亮，形成递增渐变）
- 时间范围：12个月 / 3个月 / 30天 切换，默认 3 个月（数据稀疏时日历不至于大片空白）
- 悬停预览：气泡显示「8月13日 使用了 6391.7万个 Token（58 次调用）」，空格子显示「无使用」
- 点击下钻：在每日视图点击任意日期格子，弹出当日明细弹窗——列出当天各会话的 Token 与调用次数，显示会话标题（一眼认出是哪个会话），重复标题的多个会话自动合并并标注 ×N，超过 10 条自动分页；弹窗打开时可点其他日期直接切换
- 导出 CSV：一键导出当前范围的按日数据（日期 / Token / 调用次数），带 UTF-8 BOM，Excel 打开不乱码

消耗构成

输入 / 输出 / 缓存读取 / 缓存写入 / 推理 五项明细，完整精确数字（千分位），不做万/亿简写——查具体数值时一目了然。（缓存读取为 DeepSeek 前缀缓存命中，通常占比极高但计费远低于输入。）

按模型 / 工作区

各模型、各工作区的消耗排名，完整精确数字；可一眼看出消耗集中在哪个模型、哪个项目目录。

会话头部实时角标

对话界面标题栏右侧常驻两个胶囊：

- 本会话 X：当前会话已用 Token，10 秒轮询刷新；点击弹出本会话明细（总计/输入/输出/缓存/推理 + 按模型拆分 + 会话标题），底部可一键打开完整统计
- ¥余额：DeepSeek 账户余额，用量驱动近实时刷新；点击即强制刷新余额并打开独立余额弹窗

DeepSeek 账户余额

余额共三处显示，语义各归其位：

1. 角标余额胶囊：会话标题栏右侧，随时可见
2. 独立余额弹窗：点击胶囊打开——大金额 + 可用状态、充值/赠送明细、数据来源与更新时间；底部两个动作：「查看用量」（新标签打开 DeepSeek 开放平台用量页 platform.deepseek.com/usage）与「刷新余额」
3. 完整统计页余额面板：热力图下方通栏，含刷新按钮

刷新行为：点击刷新走 ?force=1 强制查询 DeepSeek 开放平台（/user/balance），按钮带「刷新中…」反馈；余额近实时——每当有新的 token 消耗（本会话用量推进或累计总额变化）会自动刷新一次余额（5 秒节流），空闲时以 60 秒轮询兜底；请求失败时回退到上次缓存值，不闪断。API Key 通过 DSH 凭证服务解析，仅在 host 进程内使用，绝不下发浏览器。

余额预警：当余额低于配置阈值（默认 ¥5，balanceWarnThreshold 可调，0 关闭）时——角标余额胶囊的圆点变红、余额弹窗与统计页面板的状态改为红色「余额不足」并提示充值，防止余额耗尽导致调用静默失败。

独立统计页

http://127.0.0.1:3080/token-stats：与 GUI 内完整统计同款的深色页面（不依赖 GUI 也能直接访问），15 秒自动刷新，热力图/余额/明细/导出/下钻功能齐全。

数据来源

所有数字均来自 DSH 会话日志中记录的真实 provider usage（inputTokens / outputTokens / cacheReadTokens / cacheWriteTokens / reasoningTokens），不估算、不抓包。插件在启动时回放历史会话日志，并通过 session/event 实时捕获新用量，30 秒增量复核。

数据存储于 $DSH_HOME/token-stats/usage.jsonl（$DSH_HOME 即 DSH 数据根目录，默认 ~/.dsh，也可通过 DSH_HOME 环境变量指定）。

配置

插件的可调参数通过 $DSH_HOME/token-stats/config.json 覆盖（默认值如下，缺省即用默认）：

{
"gapMs": 1800000,
"rescanIntervalMs": 30000,
"balanceCacheMs": 15000,
"windowMonths": 12,
"defaultRange": "3m",
"balanceWarnThreshold": 5
}

| 键 | 默认 | 说明 |
|---|---|---|
| gapMs | 1800000（30 分钟） | 会话切分为"单次连续聊天"的空闲阈值 |
| rescanIntervalMs | 30000（30 秒） | 会话日志增量复核周期 |
| balanceCacheMs | 15000（15 秒） | 余额查询缓存时长（配合用量驱动的准实时刷新） |
| windowMonths | 12 | 热力图完整时间窗口（月） |
| defaultRange | 3m | 热力图默认显示范围（12m/3m/30d） |
| balanceWarnThreshold | 5（¥） | 余额低于该值触发红色预警（0 关闭） |

修改后重启 DSH 生效；当前生效配置可在 GET /token-stats/api/config 查看。

测试

pnpm test

vitest 测试覆盖 zstd 多帧解码、日志解析、聚合统计、存储去重/合并、配置合并与余额服务（24 个用例，构造数据、不依赖真实日志）。

安装

插件通过 DSH 的 profile 插件机制安装（dsh plugin 管理，与 @liustack/modlens 同机制）：

1. 在 web profile 的 package.json 添加依赖并加入 bundles 列表：

// data/profiles/web/package.json
{
"dependencies": {
"dsh-token-stats": "link:../../路径/dsh-token-stats"   // 或 file: 或发布到 npm 后直接写版本号
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-token-stats"]
}
}
}

2. 在 profile 目录执行 pnpm install
3. 重启 DSH（退出 → 启动）

HTTP API

| 端点 | 说明 |
|---|---|
| GET /token-stats/api/stats | 完整统计快照（卡片/热力图/明细所需全部数据） |
| GET /token-stats/api/balance | DeepSeek 账户余额（15 分钟缓存，?force=1 强制刷新） |
| GET /token-stats/api/day?date=YYYY-MM-DD | 指定日期的按会话用量明细（热力图下钻） |
| GET /token-stats/api/session/ | 单个会话的用量摘要（角标/弹窗用） |
| GET /token-stats | 独立统计页（HTML） |

包结构

dsh-token-stats/
├── package.json          # dsh.bundle.patch（host 挂载）+ dsh.client（浏览器半）
├── cordis.patch.yml      # 插件装载配置
├── dsh/                  # host 半：日志扫描、聚合、HTTP 路由
│   ├── index.js          # apply(ctx)：启动回填 + 实时捕获 + 路由
│   ├── scan.js           # 会话日志扫描与 usage 抽取
│   ├── stats.js          # 聚合（累计/峰值/热力图/连续天数/今日/会话）
│   ├── zstd.js           # 多帧 zstd 解码（会话日志为逐帧追加压缩）
│   ├── store.js          # usage.jsonl 持久化与迁移
│   ├── home.js           # DSH 数据根目录解析
│   └── page.js           # 独立统计页
└── client/               # 浏览器半：设置页 + 会话角标 + 弹窗
└── bundle.js         # web shell loader 格式，手写无构建步骤

许可

MIT