前言¶
用 DeepSeek Harness（DSH）跑对话和智能体时，Token 消耗往往分散在多次调用、重试和缓存读写里。输入框旁虽有状态信息，但若要在更长的时间尺度上对照「今天每小时用了多少」「各模型各占多少」「缓存命中率是否稳定」，通常需要翻本地会话或依赖其他面板。社区插件 dsh-clear-usage（维护者 xgxx666）在 设置 → 用量统计 中集中展示已结算调用的真实 usage，并保留 DSH 原版输入框状态栏与详情弹窗，不替换输入框下方界面。
这是什么¶
dsh-clear-usage 是 DSH 的 Web 客户端 插件（package.json 中 dsh.client.platform 为 web），当前版本 0.1.0，许可证 MIT。它从 DSH 本地会话记录读取用量，只做统计与展示：显示 Token 与调用次数，不估算费用、不显示金额。插件仅注册设置页；输入框用量、速度和点击详情仍由 DSH 原版提供。
与目录中已有的 dsh-usage-panel 类似，两者都分析设置页里的本地历史用量，功能有部分重叠。本插件侧重 DSH 原生 缓存命中率、今天的小时活动 与 Token 构成（未缓存输入、缓存读取、输出、缓存写入），并保留原版输入框状态栏。
核心功能¶
用量统计入口¶
安装后打开 设置 → 用量统计，可查看 今天、本月、全部 以及 自定义日期范围 的用量。自定义范围需选择开始和结束日期后点击「查询」，包含首尾两天。
今天：24 小时柱状图与构成¶
「今天」页展示 24 小时用量柱状图。悬停或键盘聚焦可查看每小时的 Token 与调用次数；构成条展示未缓存输入、缓存读取、输出，有缓存写入时也会显示。小时分布按 本地时间的调用结算时刻 归档，不把跨小时调用的用量平均拆到多个小时。
本月、全部与自定义：热力图与模型分布¶
本月、全部和自定义范围使用 紧凑热力图；打开或切换时间范围时会自动定位到最近日期。悬停显示日期和简写 Token 数量的两行深色提示。
模型用量以居中的 圆环图 显示：圆心为总 Token，下方颜色图例展示各模型的用量、类型和占比。模型用量默认使用原模型名；在页面底部展开 「模型类型」 可设置显示名称。未选择类型的标签可点击跳转到该模型的本地/API 选项。类型与显示名称自动保存，仅影响筛选与展示；删除后从管理列表、模型用量列表和圆环图隐藏，圆环总量与占比按当前显示的模型重新计算。页面顶部历史总用量和活动图保留完整记录，不删除 DSH 模型配置或会话日志；可在 「已删除的模型」 里恢复。
数据口径与缓存命中率¶
Token 来自 已结算调用的真实 usage。重试单独累计；同一次调用的更新覆盖旧样本；思考 Token 已含在输出内，不重复加总。历史统计排除会话分支的继承前缀，防止重复计算。缓存未报告或记录不完整时会明确提示。
缓存命中率采用官方口径：
缓存读取 ÷（未缓存输入 + 缓存读取 + 缓存写入）
官方未提供缓存读取时按原生零值处理；插件不根据推理引擎的 KV 内存复用猜测缓存 Token。
本地和 API 模型都只显示 Token，不需要填写单价。
性能与刷新¶
首次读取历史时最多并行处理四个会话，并按会话版本复用已有统计。再次打开页面会立即显示本次应用运行中缓存的快照，同时后台更新并标记「正在更新用量」；读取失败时保留已有数据。切换模型类型、时间范围或日期在界面内立即筛选，不再重复扫描历史；点击刷新也可获取最新用量。
安装与启用¶
适用于 DSH 0.2.0-rc.2 及更高兼容版本的 Web profile。Node.js 运行范围与插件 engines 一致：^22.19.0 || >=24.0.0。
在终端执行 README 给出的安装命令：
dsh plugin --profile web add github:xgxx666/dsh-clear-usage
DSH 桌面版的插件页也可以选择本项目目录进行 本地安装（目录链接）。保留项目目录；移动或删除目录会影响 DSH 加载。本包不包含依赖安装脚本，不需要 API 密钥。
典型用法¶
- 按上文命令安装并确保使用 Web profile 的 DSH 版本满足要求。
- 打开 设置 → 用量统计，先看 今天 的小时柱状图与 Token 构成，对照缓存读写是否如预期。
- 切换到 本月 或 全部，用热力图浏览活动密度；悬停查看单日简写 Token。
- 需要固定区间时，在 自定义 中选择起止日期并点击「查询」。
- 在页面底部 「模型类型」 中为模型设置显示名称或类型，便于圆环图筛选；误删可在「已删除的模型」恢复。
模型分类保存在 $DSH_HOME/dsh-clear-usage/models.json。已有配置的旧字段保留以兼容历史版本，页面不再提供单价输入或金额显示。
适用场景与注意¶
适合谁： 希望在 DSH 内用统一口径查看本地 Token 消耗、缓存命中率、按小时与按模型分布，且不需要费用估算的 Web 端用户。
隐私与数据： 用量从 DSH 本地会话记录读取，消息正文不会离开 DSH。插件不读取凭据、不调用供应商 API，也不上传统计数据。
安全提醒： 插件以当前 DSH 进程的权限运行。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，DSH 生态遵循「一切皆插件」的扩展方式。
修改界面后通常可以热更新；修改宿主统计相关代码（如 index.js、lib/usage.js）后需要正常重启 DSH。开发者在插件目录可运行 npm test 与 npm run check 做基本检查。
小结¶
dsh-clear-usage 在设置页提供基于本地会话的真实 Token 统计、官方口径的缓存命中率，以及今天小时级活动与模型圆环图，且不改动输入框原版状态栏。若你已在用 DSH Web profile 且版本不低于 0.2.0-rc.2，可按官方命令安装后在设置中查看。
