前言¶
DeepSeek Harness (DSH) 的插件系统允许对核心功能进行扩展。在智能体开发或日常使用中，追踪 Token 消耗、查看模型活跃度是常见需求。dsh-usage-stats 是一个面向 DSH 官方桌面版的「使用统计」插件，它在设置页新增了专门的统计分区，提供五格终身摘要、GitHub 风格热力图及趋势折线等可视化功能。该插件的数据全部在本地落盘，不涉及网络上传，且不引入额外的运行时依赖。
核心功能¶
该插件主要提供以下可视化与数据功能：
- 五格终身摘要条：展示累计 Token 数、单日峰值 Token 数、最长聊天时长、当前连续天数以及最长连续天数。
- Token 活动热力图：呈现 52 周的 Token 活动情况，支持每日、每周/累计三档视图切换。
- 趋势折线：提供今日、近 7 日、近 30 日三种时间维度的趋势折线图，支持按模型查看。
- 模型用量环形图：显示选定时间范围内各模型的 Token 占比。
- 历史会话回填：插件启动时会自动扫描并回填历史会话数据；用户也可在页脚手动点击「回填历史」按钮触发。
- 本地 JSONL 落盘：数据以 JSONL 格式保存在本地，作为唯一真源。
- 零上传与零依赖：不向远程服务器发送任何数据，且无需执行
npm install。
安装与启用¶
安装该插件需要使用 DSH 的插件管理命令。确保宿主环境满足要求：DSH 版本 0.2.0-rc.2 及以上，宿主 Node.js 版本 >= 22.15。
使用 GitHub tag tarball 渠道安装（推荐）：
dsh plugin --profile desktop add https://github.com/axuan-1314/dsh-usage-stats/archive/refs/tags/v0.2.0.tar.gz
安装后，插件会自动生效，并在设置页增加「使用统计」分区。若使用 web 或 headless profile，需将命令中的 --profile desktop 替换为对应 profile 名称。
数据与配置¶
数据位置¶
所有统计数据均存储在本地文件系统，不上传。默认路径为 ~/.dsh/usage-stats/。数据包括按月轮转的 JSONL 流水文件（records-YYYY-MM.jsonl）和日聚合缓存文件等。
配置项¶
插件支持以下配置键（通常在配置文件中设置）：
enabled：是否启用插件，默认为true。storageRoot：自定义数据存储根目录。sessionsRoot：自定义会话文件路径。
典型用法¶
安装并重启 DSH 后，可在设置页「使用统计」分区查看数据。若需通过 API 直接获取数据，可访问以下接口：
- 获取摘要：
GET /api/dsh-usage-stats/summary - 查看热力图：
GET /api/dsh-usage-stats/heatmap?days= - 查看趋势：
GET /api/dsh-usage-stats/trend?days=1|7|30 - 查看模型用量：
GET /api/dsh-usage-stats/models?days=7|30
对于历史数据，若插件未自动完成回填，可点击页脚的「回填历史」按钮。该操作采用 202 受理制，会在后台分片执行，不会冻结界面。
适用场景与注意事项¶
适用场景¶
该插件适合需要详细监控 Token 消耗成本、分析使用习惯以及管理多模型使用场景的开发者。
注意事项¶
- 单写者锁：若同时开启两个 DSH 实例，后加载的实例将降级为只读镜像，仅展示数据而不进行采集和回填。
- 内存状态：Live 折叠槽数据存储在内存中，进程重启后会丢失。
- 版本要求：请确保 DSH 版本不低于 0.2.0-rc.2，宿主 Node.js 版本不低于 22.15，否则无法正常工作。
总结¶
dsh-usage-stats 插件通过本地采集和回填机制，为 DSH 提供了一套轻量级的用量统计方案。它不需要复杂的依赖配置，数据完全可控，适合作为开发者监控和优化智能体成本的基础工具。
