Token 用量统计面板 Amer-CN/zcode-usage-stats

DeepSeek Harness（DSH）插件：ZCode 风格的 Token 用量统计面板

覆盖：全历史会话扫描 × 用量趋势 × 模型仪表盘 × 活跃热力图 × 深浅双主题

Typing SVG

一个装进 DSH 设置页的「Token 记账本」。扫描 ~/.dsh 下的全历史会话，把每一枚 token 按天、按小时、按模型算清楚：今天写了多少、哪个模型最费、哪天是巅峰。纯本地扫描、本地聚合、本地渲染——数据不出本机。

⚠️ 非官方社区插件，与 DeepSeek / ZCode 无关联。"zcode" 仅为致敬对象与包名沿用。

📸 界面预览

| ☀️ 浅色主题 | 🌙 深色主题 |

✨ 功能特性

| 模块 | 说明 |
| 📅 时间范围 | 今天 / 昨天 / 近 7 天 / 近 30 天 / 本月 / 上月 / 全部 / 自定义区间（起止自动校验防倒序） |
| 🔥 活跃分布 | 日历点阵热力图：一格一天，点面积 = 当日 Token（sqrt 换算）；每日 / 每周 / 累计三档分桶；峰值日虚线圈标注 |
| 📈 用量趋势 | 一条线一个模型，圆点 = 当期用量，峰值直接标数；悬停看各模型分项，图例可点击显隐 |
| 🍩 模型用量 | 刻度环仪表盘：100 刻 = 100%，每 10 刻一枚锚点；扇形命中区悬停查看模型明细；模型超过 6 个自动并「其他」防撞色 |
| 🧮 顶部指标 | 累计 Token / 单日峰值 / 最长会话时长 / 当前连续天数 / 最长连续天数 |
| ♿ 无障碍与体验 | WCAG AA 对比度（明暗双主题逐项核算）、prefers-reduced-motion 降级、透明命中层让小点也轻松悬停、深浅主题跟随 DSH |

📦 安装

前置：已安装 @deepseek-ai/dsh（及 DSH 插件命令依赖的 pnpm）。

dsh plugin --profile web add zcode-usage-stats

或从 GitHub 源安装：dsh plugin --profile web add github:Amer-CN/zcode-usage-stats。
0.1.2 起要求 DSH >= 0.2.1-rc.1。

国内镜像可能晚于 npm 官方源同步；若装到旧版，可临时把 npm_config_registry 指向 https://registry.npmjs.org/，或改用 GitHub 源。

安装后重启 DSH 进程，打开 设置 → 使用统计 即可看到统计页面。

通过插件市场「发现」安装（可选）

DSH 0.2.1 的「发现」市场是实验性功能，默认不启用、索引源为空。把本仓库的市场索引加入后，可以直接在「发现」里搜索安装：

1. 启用 DSH 的实验性插件市场（若你的版本提供「发现」标签页）
2. 插件 → 发现 → 添加索引源
3. 填入：

https://raw.githubusercontent.com/Amer-CN/zcode-usage-stats/main/plugin-market.json

4. 搜索 zcode-usage-stats 并安装

如果没有「发现」标签页，说明该实验性组合包未启用，直接使用上面的「添加插件」按包名安装即可。索引是第三方声明，实际安装版本由 npm 包 manifest 决定；本索引固定从 npm 官方源读取 0.1.2。

🚀 使用

- 顶部切换时间范围；「全部」显示自使用以来的所有数据。
- 趋势图悬停查看各模型分项，点击图例显隐对应模型。
- 「刷新」强制重新扫描全部会话。

⚙️ 工作原理

~/.dsh/sessions 会话日志（session[.vN].jsonl[.zstd]） │ ▼ 直接读取；多帧 zstd 逐帧解压按天 / 按小时 / 按模型聚合 ──► 内存 + 磁盘双层缓存（SWR） │ └─ 按会话文件 size+mtime 增量，只重读追加过的会话 ▼ GET /api/usage-stats（过宿主信任栅栏：Host/Origin + cookie） │ ▼ 设置页前端：手写 SVG 按实测容器宽度 1:1 出图

🎨 设计与实现

| 设计点 | 说明 |
| 图表 | 手写 SVG（日历点阵 / 发丝折线 / 刻度环），零运行时图表库依赖 |
| 配色 | 自研双轨色板：类目色 6 个跨色相承载模型身份，序数色单色相明度阶承载用量大小；两套主题均满足 WCAG AA，类目色两两色距核算保证一眼可分 |
| 排版 | 固定 px 字阶 + 4 的倍数间距阶梯；图表按 ResizeObserver 实测容器宽度 1:1 出图，不做等比缩放，字号真实可读 |
| 命中区 | 视觉元素不绑事件：热力图逐格透明矩形、刻度环整圈扇形 path，悬停不闪烁 |
| 服务端 | 直接读取会话日志并逐帧解压 zstd（Electron 自带 zstd 只解第一帧，故自行切帧）；按文件 size+mtime 增量，冷扫描 20–30s、增量刷新 <2s；内存 + 磁盘双层缓存，SWR 过期后台刷新 |
| 安全 | /api/usage-stats 自行通过宿主 connection.requestRejection 信任栅栏鉴权 |

🔢 数据口径

| 指标 | 口径 |
| Token 用量 | 以 assistant/message 事件携带的全量 usage 为准（input + output + cacheRead + cacheWrite）；流式 assistant/chunk 的 usage 不重复计 |
| Turns | 以 step/end 事件按新 turn 计数（覆盖 completed / failed / cancelled） |
| 模型归属 | 优先取消息自身 message.source.model（逐条准确），回退事件 data.model / request/context 当前模型，再回退 other |
| 活跃日 | 当天有 ≥1 条 usage 事件；连续天数按活跃日相邻日推算 |

🤝 兼容性

- 面向 DSH >= 0.2.1-rc.1（已在 0.2.1-rc.3 桌面版验证）；package.json 的 dsh.engines 会阻止不兼容版本加载。
- 依赖宿主提供的 webServer、connection 服务；会话数据直接读 $DSH_HOME/sessions（默认 ~/.dsh/sessions）。
- 会话日志支持 v0–v4 与 zstd / 明文；同一会话目录迁移残留的 v3+v4 会按版本去重，不会重复计数。
- 不再依赖旧版客户端包 @deepseek-ai/dsh-client-runtime / dsh-client-ui-slots。

🗂️ 仓库结构

目录树（点击展开）

zcode-usage-stats/
├── package.json # 插件清单（dsh 客户端注入声明） ├── cordis.patch.yml # DSH 补丁声明 ├── plugin-market.json # DSH「发现」市场索引（format 1） ├── LICENSE # MIT ├── README.md # 本文件 ├── assets/ │ ├── usage-stats.png # 浅色主题截图 │ └── usage-stats2.png # 深色主题截图 ├── build/ │ ├── body.js # 前端真源：界面 + 手写 SVG 图表 │ ├── panel.css # 前端真源：样式与配色变量 │ └── assemble.cjs # 合成脚本：body.js + panel.css → client.new.js ├── tests/ │ ├── acceptance.sh # 前端验收门禁：15 项检查（一条命令跑完） │ ├── harness.cjs # 渲染挂具：模拟容器宽度渲染出预览 HTML │ ├── assert.cjs # 几何断言：三张图的尺寸/可读性 │ ├── contrast.cjs # WCAG 对比度核算（明暗两套） │ ├── preset-conformance.cjs # custom 色板合规校验 │ ├── host-scan.cjs # 宿主侧回归：多帧 zstd / 增量 / 去重 / 超时续扫 │ └── preview-.html # 渲染产物（gitignore） └── lib/ ├── index.mjs # 宿主侧：读取会话日志 + 增量聚合 + 双层缓存 + API └── client.js # 前端合成产物（勿直接编辑，见「从源码构建」）

🛠️ 从源码构建

lib/client.js 是合成产物，请勿直接编辑。前端真源在 build/：

1. 编辑 build/body.js（界面 + 图表）与 build/panel.css（样式 + 配色变量）
2. 合成
node build/assemble.cjs

3. 用合成结果覆盖部署文件
cp build/client.new.js lib/client.js

4. 前端验收（15 项必须全过） bash tests/acceptance.sh

5. 宿主侧回归（Node 24 / Electron 运行时均可）
node tests/host-scan.cjs
验收脚本会按真实面板宽度渲染出预览 HTML（tests/preview-.html），并跑几何断言、WCAG 对比度与色板合规检查。默认读取本机 ~/.dsh 下的用量缓存；可用 USAGE_CACHE=/path/to/cache.json bash tests/acceptance.sh 指定其它缓存，缓存不可用时自动改用内置合成数据。

宿主侧改动需要重启 DSH 进程才会生效（前端 lib/client.js 是热更新，刷新页面即可）。tests/host-scan.cjs 用合成会话覆盖多帧 zstd、v3/v4 去重、增量重读、半帧容错与超时续扫。

发布新版本时记得同步 plugin-market.json 里对应版本的 version 与 publishTimestamp，否则「发现」市场仍会指向旧版本。

提 PR 请改 build/ 下的源文件，并在描述里附上 bash tests/acceptance.sh 的输出。

📜 版本历史

当前 v0.1.2（2026-10-30）· DSH 0.2.1 适配与性能修复

| 版本 | 内容 |
| v0.1.2 | 适配 DSH 0.2.1-rc.3：宿主侧改为直接读取会话日志并逐帧解压多帧 zstd（Electron 只解首帧会导致数据为空/超时），按文件 size+mtime 增量扫描；修复 1400+ 会话时 60s 超时只回传约 10% 数据、缓存停在旧日期的问题；模型归属改用 message.source.model；v3/v4 迁移残留去重；热力图改为分位分档并修正低档点色/最小半径，避免真实数据下热力图看起来全空；npm 0.1.2 发布并附 DSH「发现」市场索引 |
| v0.1.1 | 缓存目录跟随当前 profile（不再硬编码 profiles/web），读取旧路径做一次性迁移；补充 dsh.engines / 兼容性声明 |
| v0.1.0 | 初始开源版本：以 qianxiao1213/zcode-usage-stats 原版为基线，重写全部图表界面与配色（活跃分布 / 用量趋势 / 模型用量三图 + 自研双轨色板），补齐双主题截图与文档 |

🙏 许可与致谢

- 代码以 MIT License 发布，见 LICENSE。
- 上游致谢：基于 qianxiao1213/zcode-usage-stats 重构——图表界面与配色全部重写，数据聚合层在其基线上演进。
- 本插件为非官方社区项目，与 DeepSeek / ZCode 无关联。

Made by @Amer-CN

数据只在本机算，哪也不去。