zcode-usage-stats：DeepSeek Harness 的 Token 用量统计插件

插件简介¶

DeepSeek Harness（DSH）提供了会话管理能力，但通常缺乏对历史 Token 消耗的详细统计。zcode-usage-stats 插件通过扫描全历史会话，聚合每天、每小时以及每个模型的 Token 用量，并以趋势图、仪表盘和热力图的形式展示。

该插件由 qianxiao1213 维护，属于客户端插件。它解决了开发者查看历史资源消耗的需求，支持多种时间粒度的切换与数据可视化。

安装与启用¶

在安装前，请确保宿主环境满足以下依赖条件：
* @deepseek-ai/dsh 版本锁定为 >=0.1.0-rc.5
* 依赖 DSH 宿主提供的 sessionPersistence、webServer 服务
* 依赖客户端运行时的 @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-slots

执行以下命令安装：

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

安装完成后，重启 DSH 进程，在 设置 → 使用统计 路径下即可看到统计页面。

核心功能¶

该插件主要包含以下能力：

多种时间范围：支持今天、昨天、最近 7 天、最近 30 天、本月、上月，以及自定义区间。自定义区间支持年/月/日点选，且起止日期会自动校验防止倒序。
智能粒度切换：当选择今天、昨天或单日自定义时，趋势图横轴会自动从「天」切换为「小时」。
数据可视化：
- 多模型面积趋势图：采用 Catmull-Rom 平滑曲线，提供参考线吸附和数据点提示。图例支持点击显隐单系列。
- 模型用量仪表盘：环形占比展示，口径与趋势图统一。
- 活跃热力图：GitHub 风格，支持按窗口日折叠列，Hover 放大并显示提示。
主题与性能：
- 颜色与 DSH 主题联动（<body data-ds-dark-theme>）。
- 采用磁盘+内存双层缓存，支持后台刷新（SWR），保证首屏秒开。

使用指南¶

切换时间范围：在页面顶部点击预设的时间按钮（如“最近7天”），或点击“自定义”弹出日期选择卡片。
查看趋势：将鼠标悬停在趋势图上，可查看参考线联动的具体数据；点击图例可单独显示或隐藏某个模型的数据。
刷新数据：如果需要强制重新扫描全量会话，点击“刷新”按钮即可。

技术细节与数据口径¶

数据来源：
- Token 用量：以 assistant/message 事件携带的全量 usage 为准，并进行了去重处理。
- Turns 计数：以 step/end 事件按新 turn 计数。
- 模型归类：未知模型会被归并为 other。
缓存策略：采用后台刷新策略，过期后自动更新缓存，避免阻塞首屏渲染。

适用场景¶

适合需要精细化管理 DeepSeek 会话成本、分析不同模型使用频率的开发者或团队。通过热力图和趋势图，可以快速识别活跃时间段和模型偏好。