前言¶
DeepSeek Harness（DSH）会在 $DSH_HOME/sessions/ 下为每个会话记录服务方上报的 token 用量，但那是按会话累计的字段，不能直接回答「今天花了多少」「近一周用了哪些模型」。若只靠现场扫描会话日志做折叠，还会遇到另一类问题：清理侧边栏、跑 dsh-session-cleanup 或手删会话目录，本质上是在删日志，历史用量会跟着掉下去，数字不适合用来做判断。
dsh-usage-stats 在 DSH 设置里提供按日历窗口的用量报告，并把每个会话折叠结果备份到本地台账；删除会话后，已计入的用量仍保留在统计里。下面介绍它的定位、安装方式与使用时要接受的口径边界。
这是什么¶
- 包名：
dsh-usage-stats（当前资料版本0.4.1） - 维护与分发：社区目录条目为 DPH-1121；README 中的源码与
github:安装规格指向仓库github.com/HaydenSmith1121/dsh-usage-stats - 分类：记忆（SkillHub 目录）
- 一句话：只读本会话的 JSONL 日志，折叠出与 DSH
tokenUsage投影一致的报告，并用只增不减的 per-session 台账兜底「删会话不删用量」
插件不持有 API Key、不联系 provider、不改模型路由；除 $DSH_HOME/storages/dsh-usage-stats/ 下的台账外，不写其它 DSH 数据。
核心功能¶
界面里看什么¶
在 Harness 设置中打开用量页后，可按 Today / 近 7 天 / 近 30 天 / 全部 查看：
- 总 token 数，以及服务方上报的四个桶：未缓存输入、输出、缓存读取、缓存写入
- 缓存读占比（避免只看总数时误判）
- 该范围内的模型调用次数
页脚会写明：读到了多少个会话日志、多少个读失败、有多少已删除会话的用量来自台账，以及读到的会话日志格式代际（例如 v4 × 12；表头无法识别代际时标为「未标版本」）。范围是含端点的本地日历窗口且以今天结束，因此 7 天数字包含 1 天。
只增不减的台账（0.3.0 起）¶
每次扫描会把按会话折叠的结果备份到：
$DSH_HOME/storages/dsh-usage-stats/usage-ledger.json
规则简要如下：
| 规则 | 含义 |
|---|---|
| 只增不减 | 同一会话、同一 (天, 供应商, 模型) 格子，取台账与当前日志中的较大值；日志被压缩、截断或改写也不能把已计费数字降下来 |
| 从不删除 | 写入后只向上更新，无 TTL、无上限；要清空统计需自行删除该目录，下次扫描以当前在场日志为基线 |
后台约每 30 秒巡检一次，仅对 mtime/size 变化的日志重新折叠，不必打开设置页也会记账。台账损坏时原件可能被挪到 usage-ledger.json.corrupt.json；页面会根据台账状态说明「删会话是否仍保留用量」或台账不可用时的行为。
与 DSH 版本的适配¶
声明适配 dsh 0.1.6-alpha.1 ～ 0.2.1-rc.2（含桌面版 0.2.1-rc.2）。会话日志在磁盘上按代际识别（例如 0.1.6 写 v3、0.1.7 写 v4），升级后多代文件可并存，读数值最高的一代，与 harness 自身选择一致。逐条实测见仓库内 docs/compatibility.md。
折叠算法刻意对齐 @deepseek-ai/dsh-token-meter 的投影（同一步骤内最后一条 usage 样本胜出、重试开新槽、同时处理 assistant/message 与 assistant/attempt 等），避免与框架口径不一致。
安装与启用¶
方式 A（推荐）：安装插件市场面板 dsh-plugins-market，在左侧「插件市场」中安装本条目（市场规格即本仓库的 github: 源，不经中间产物仓库）。
方式 B（手动）：按你使用的 profile 执行（web 与桌面版 profile 不同，装错不会被加载）：
dsh plugin --profile web add github:HaydenSmith1121/dsh-usage-stats # dsh web
dsh plugin --profile desktop add github:HaydenSmith1121/dsh-usage-stats # 桌面版
不确定 profile 时，可查看 $DSH_HOME/profiles/ 下有哪些目录。仓库已提交 lib/ 构建产物，git 安装无需本地构建；也可用 npm run pack 打 tarball，将 add 参数换成 .tgz 绝对路径。
装完后重启（dsh web，或退出再打开桌面版）：设置页在客户端半加载；读日志并维护台账的路由在宿主半启动时注册，重启前页面会说明这一点。
卸载（不删台账文件）：
dsh plugin --profile web remove dsh-usage-stats
dsh plugin --profile desktop remove dsh-usage-stats
想清空统计：删除 $DSH_HOME/storages/dsh-usage-stats/ 后重启扫描逻辑即可。
与旧包
dsh-workbuddy-quota不要同时安装，否则可能出现两个 Token 用量设置页；本包为其继任者（改名并只保留用量统计）。
典型用法¶
本插件没有配置项（无 API Key、无环境变量、无设置表单）。$DSH_HOME 未设置时与 DSH 一致，默认 ~/.dsh。
典型流程：
- 按上文安装到正确的
web或desktopprofile 并重启 Harness。 - 在设置中打开 Token 用量相关页面，切换 Today / 7 天 / 30 天 / 全部查看汇总与四个桶。
- 需要核对可靠性时，看页脚：会话读数、台账保留的已删会话数、日志代际与台账状态（
ok/rebuilt/unavailable）。 - 若你经常清理会话，可依赖台账；若希望从零开始统计，在明确会丢失历史台账的前提下删除
storages/dsh-usage-stats/目录。
适用场景与注意¶
适合：在本机 Harness 上长期观察 token 花费、对比模型与缓存读写占比，并在清理会话后仍保留历史用量趋势。
权限与安全：插件以当前 dsh 进程权限读 $DSH_HOME/sessions/ 并写台账目录；安装前建议查看仓库源码与 MIT 许可证，确认符合你的环境策略。
诚实边界（README 已登记），使用时需知晓：
- 标题生成（
session/title-llm-request）消耗 token 但无 usage 样本，任何折叠都看不到，与 DSH 自身投影相同。 - 台账启用（0.3.0 首次运行）之前已删的会话无法恢复；删除后最后约 ≤30 秒内、尚未被巡检折叠的用量可能漏记（巡检间隔 30 秒）。
- fork 会话继承前缀不计费（0.4.0 起切点逻辑与 harness 对齐）；同一会话 id 出现在两个工作区目录时台账按 id 合并，报告相加，与 dsh 判为损坏的布局并存时结果可能不一致。
- 会话目录临时不可读时，页面会说明数字全部来自备份，且不会把在场会话误标为「已删除」。
社区插件目录（SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系；星标等元数据以目录页为准（当前线索为 1 star）。
链接¶
- 目录页：https://www.skillhub.cn/plugins/DPH-1121/dsh-usage-stats
- GitHub：https://github.com/DPH-1121/dsh-usage-stats（README 中
github:安装与源码说明使用github.com/HaydenSmith1121/dsh-usage-stats）
