前言¶
在 DeepSeek Harness (DSH) 的开发流程中，监控模型调用的 Token 消耗、评估缓存命中率以及分析不同模型的用量分布是成本控制与性能优化的基础需求。通常这需要手动解析日志或依赖零散的计数器，缺乏一个统一、直观的仪表盘。dsh-plugin-usage-stats 插件通过直接读取 adapter 的 usage 数据，在 Web 界面提供了一份整页的用量统计报告。
插件简介¶
该插件由 fakeNihilist 维护，核心职责是回答“这些会话一共用了多少 token”这个问题。它不注册工具、不注入提示词、不修改请求，对模型完全不可见，不影响 prompt 与 KV 缓存。安装后，Web GUI 左侧栏会新增「用量统计」入口，主区域展示整页仪表盘。
核心功能¶
仪表盘仅包含两个交互控件：整页的「刷新」按钮，以及一组「7 天 / 30 天 / 全部」的时间范围切换。切换范围仅改变视图窗口，所有视图共享同一份载荷与统计口径。
- 概览卡片：显示当日 Token、累计 Token（含输入、输出、缓存读拆分）以及缓存命中率，并附带当日缓存率、当日与累计请求数。
- Token 活动：展示一年期的日热力图，采用 GitHub 风格的蓝色四级色阶。悬停任意格子可查看该日的全部指标。
- 每日 Token 趋势图：堆叠柱状图显示输入与输出，背景叠加浅黄色命中率柱（右轴 0–100%）。
- 模型用量：左侧为环图，右侧为图例（模型名、占比、Token 数）。悬停扇区或图例可查看占比、调用数与缓存率。
- 按模型明细表：按供应商分组，展示模型、调用数、未缓存输入、输出、缓存读、缓存率及合计。表头吸顶，内容可滚动。
数据特性：
* 无设置项：安装即用，无配置文件或需调参数。
* 无推断：所有数字直接取自 adapter 上报的 usage，不推断、不按字数折算、不补零。
* 悬停读数：热力图格子与趋势柱的 token 值一律缩写成 K/M/B 单位（如 698.9M），调用数与缓存率仍为完整数值。
安装与启用¶
通过 DSH 的包管理器安装插件：
dsh plugin add https://github.com/fakeNihilist/dsh-plugin-usage-stats
安装完成后，需重启 Host 进程以加载新代码，随后刷新 Web 界面即可在左侧栏看到「用量统计」入口。
典型用法¶
- 打开 Web GUI，在左侧栏点击「用量统计」。
- 点击主区域的「刷新」按钮更新数据。
- 使用顶部的「7 天 / 30 天 / 全部」按钮切换时间范围，视图同步更新。
- 悬停热力图格子、趋势柱或环图扇区查看详细数值（热力图与趋势使用独立窗口）。
适用场景与注意¶
该插件适合需要精细化监控 Token 消耗、评估缓存策略效果以及进行模型成本分摊的开发者。
注意事项：
* 时区：统计使用宿主本地时区，进程启动时固化偏移量。
* 子会话：子智能体会话的用量计入总量。
* 缓存写入：当前 DeepSeek adapter 上 cacheWriteTokens 恒为 0，明细表不再列出该列。
* 工作区：按会话的 cwd 分组，无 cwd 的会话以 session id 分组。
* 参数含义：days 参数是下限而非上限；「全部」等于语料自身的跨度（非建库以来全部）。
* 热力图：没有计费输入的日期不画柱。
* 主题兼容：浅色主题下的边框与说明文字由插件自己派生。
生态背景¶
DSH 理念是“一切皆插件”，社区目录与 DeepSeek 官方无从属关系。
