用量统计 xgxx666/dsh-clear-usage

DSH Token 用量统计

在 DSH 设置中查看真实 Token 消耗、缓存命中、活动热力图和模型分布。仅显示用量，不估算费用。

dsh plugin --profile web add github:xgxx666/dsh-clear-usage

适用于 DSH 0.2.0-rc.2 及更高兼容版本的 Web profile。Node.js 运行范围与 DSH 宿主声明一致，依据是 deepseek-harness monorepo 根 package.json（已发布的 dsh 包本身不含 engines 字段）：^22.19.0 || >=24.0.0。

使用位置

- 输入框下方完全使用 DSH 原版状态栏及详情弹窗，插件不再替换这部分界面。
- 设置 → 用量统计：查看今天、本月、全部的用量，紧凑热力图和按模型分组的列表。
- 今天：显示 24 小时用量柱状图，悬停或键盘聚焦可查看每小时 token 和调用次数；构成条展示未缓存输入、缓存读取、输出，有缓存写入时也会显示。小时分布按本地时间的调用结算时刻归档，不把跨小时调用的用量平均拆分。
- 本插件与已有的 dsh-usage-panel 都分析设置页里的本地历史用量，有部分功能重叠。本插件侧重 DSH 原生缓存命中率、今天的小时活动和 Token 构成，并保留原版输入框状态栏与详情弹窗。
- 自定义：选择开始和结束日期后点击「查询」，包含首尾两天。
- 本月、全部和自定义范围使用热力图，打开或切换时间范围时自动定位到最近日期；悬停显示日期和简写 token 数量的两行深色提示。模型用量以居中的圆环图显示，圆心展示总 token，下方颜色图例显示各模型的用量、类型和占比。
- 模型用量默认使用原模型名；在页面底部展开「模型类型」可设置显示名称。未选择类型的标签可点击跳转到该模型的本地/API选项。类型和显示名称自动保存，仅影响筛选与展示。删除后从管理列表、模型用量列表和圆环图隐藏；圆环总量与占比按当前显示的模型重新计算。页面顶部历史总用量和活动图保留完整记录，不删除 DSH 模型配置或会话日志；可在「已删除的模型」里恢复。
- 本地和 API 模型都只显示 token，不显示金额，不需要填写单价。

数据口径

token 来自已结算调用的真实 usage。重试单独累计；同一次调用的更新覆盖旧样本；思考 token 已含在输出内，不重复加总。历史统计排除会话分支的继承前缀，防止重复计算。缓存未报告或记录不完整时明确提示。

插件只注册设置页。输入框用量、速度和点击详情均由 DSH 原版提供。

缓存命中率采用官方口径：缓存读取 ÷（未缓存输入 + 缓存读取 + 缓存写入）。官方未提供缓存读取时按原生零值处理；插件不根据推理引擎的 KV 内存复用猜测缓存 token。

首次读取历史时最多并行处理四个会话，并按会话版本复用已有统计。再次打开页面会立即显示本次应用运行中缓存的快照，同时后台更新并标记「正在更新用量」；读取失败时保留已有数据。切换模型类型、时间范围或日期在界面内立即筛选，不再重复扫描历史；点击刷新也可获取最新用量。

当前页面不显示金额，也不需要维护供应商单价。

开发检查

在本目录运行：

npm test
npm run check

本地安装

DSH 桌面版的插件页也可以选择本项目目录进行本地安装。本包不包含依赖安装脚本，不需要 API 密钥。

模型分类保存在 $DSH_HOME/dsh-clear-usage/models.json。已有配置的旧字段保留以兼容历史版本，但页面不再提供单价输入或金额显示。不读取密钥、不发送消息正文、不访问供应商接口。

隐私与数据

用量从 DSH 本地会话记录读取，消息正文不会离开 DSH。插件不读取凭据、不调用供应商 API，也不上传统计数据。模型分类设置保存在 $DSH_HOME/dsh-clear-usage/models.json。

从零认识这个项目

1. package.json：插件的名字、版本和安装声明。
2. cordis.patch.yml：告诉 DSH 加载这个插件。
3. index.js 与 lib/usage.js：读取、核对和统计用量。
4. client.js：设置页界面。

本地安装采用目录链接。保留本项目目录；移动或删除目录会影响 DSH 加载。修改界面后通常可以热更新，修改宿主统计代码后需要正常重启 DSH。