前言¶
在 DSH（DeepSeek Harness）里谈不上用量统计：插件跑了多少 token、最近哪天用得最勤、几种模型各自的占比，都得自己翻会话日志去翻。DSH 的理念是「一切皆插件」，这类缺口通常由社区插件来补。下面介绍 ailawu0409 维护的 dsh-usage-stats，它往 Settings 里加一个 Usage Statistics 分区，把本地会话的 token 汇总、活跃热力图、按模型的日趋势和模型占比一次给出。
需要先说明：这是社区插件，不是 DeepSeek 官方出品，未获 DeepSeek 背书；插件的目录页分类为 admin-security，GitHub 上星标数为 0，仓库创建于 2026-11-05。安装前建议先读源码与许可证（MIT）。
这是什么¶
dsh-usage-stats 是一个 DSH 插件，包版本 0.2.1，执行环境要求 Node.js 22 及以上，无第三方运行时依赖。它把统计结果渲染在 Settings → Usage Statistics（位于 Archived sessions 下方），数据全部来自本地会话日志，只读、不联网、不上传任何内容。
目标宿主版本为 DeepSeek Harness 0.2.2-rc.1。导航图标依赖 0.2.2 才引入的 settings.section.icon 插槽；更旧的宿主会直接回退到默认齿轮图标，不会报错。
核心功能¶
下面介绍的功能均可在 README 中核对。
-
概览指标（3 项）：总 token、单日峰值 token、最长一次会话时长。
-
Token 活跃热力图：GitHub 风格的按周网格，支持 Daily / Weekly / Cumulative 三种配色模式；悬停单元格显示日期、token 数与轮数，例如
Oct 27, 2026/506K tokens · 2 turns。单元格固定 11px，周数随面板宽度自适应（最多 53 周、最少 13 周），汇总区间的表述会写明实际范围，例如 “Active 2 days over the last 8 months”。 -
每日 token 趋势：平滑曲线按模型着色，可选 Last 7 days / Last 30 days；悬停出现竖向光标、高亮点以及当日的分模型明细。
-
模型用量：环形图配一份占比列表（前 5 个模型加 Other），悬停扇形显示该模型的 token 与占比。
-
其他：跟随宿主浅色/深色主题与官方字体，界面为中英双语，右下角有 Refresh 按钮；页面头部只保留标题（沿用宿主设置标题字号，16px）。刷新失败时保留原有数据，只在顶部显示一条可重试的横幅。
数据口径¶
这部分决定了数字为什么长这样，值得先看清楚。
- 总 token：每个
assistant/message的usage之和，优先取totalTokens，没有则用inputTokens + outputTokens。 - 峰值 token：单日用量的最大值，按本地时区的日历天计算。
- 最长会话：单个会话内
turn/start → turn/end时长之和的最大值，跨夜的空闲时间不计入。 - 轮数：按
turn/start的开始日归集，跨零点的轮次算在开头那一天。 - 热力图汇总：只统计网格实际绘制的区间，不包含窗口外的历史。
- 去重：fork 出的会话跳过继承的前缀（
seq < inheritedEventCount），不与父会话重复计数。 - 删除不减少历史：会话归档、移出存储或永久删除后，已经计入的用量仍保留在总量、峰值、热力图与模型占比里，页脚会标注 “N of the counted sessions are no longer listed”。这是有意设计，避免「删掉一条数字就变小」的反直觉行为。
- 失败保留：读取失败或处于
migration-required的会话不会让累计值回缩，沿用上一次结果；只有从未计数的会话被记为 skipped。失败会话冷却 5 分钟后才重试，不会每次扫描都重读。 - 会话数上限：最多统计 20,000 个会话，超出时页面会给出提示。
有一点要提醒：本插件的口径与 ZCode 不同。ZCode 的 computedTotalTokens 是 input + cache + output，本插件优先取 usage.totalTokens，其次 input + output，因此两者的数值可能不一致。另外 ZCode 默认保留 30 天原始用量明细，本插件保留终身总量，仅把「最近 400 天」的日粒度明细用于热力图和趋势图。
缓存与性能¶
-
每个会话的折叠结果缓存在
<profile>/plugin-state/usage-stats-cache.json；已删除会话的条目以retiredAt保留，所以删会话后缓存不会立即膨胀，只会缓慢增长。 -
后续扫描按持久化的
revision增量进行，只有发生变化的会话会重读；revision是 DSH 为派生缓存提供的官方变更标记。 -
插件启动 5 秒后预热一次缓存，因此正常打开页面时多为缓存命中。
-
缓存迁移自动完成：v2 缓存原地升级到 v3，不需要全量重读；只有更旧或未知版本的缓存会被丢弃重建。
-
想全部清零，删除上面那个缓存文件再刷新即可，插件会从仍然存在的会话日志里重建。
安装与启用¶
官方给出的安装命令如下：
dsh plugin --profile desktop add https://github.com/ailawu0409/dsh-usage-stats
也支持本地包路径或自己的分支地址，把 URL 替换掉即可：
dsh plugin --profile desktop add <package-path-or-repo-url>
本地开发时可以把包目录直接链接进 profile：
dsh plugin --profile desktop add /path/to/dsh-usage-stats
装完重启 DeepSeek Harness，进入 Settings → Usage Statistics。要使用插件自定义的导航图标，建议 DSH 0.2.2-rc.1 或更新版本；旧宿主回退默认齿轮图标。
典型用法¶
装好后一般不用再动配置，日常使用就两件事。
- 打开 Settings → Usage Statistics，看总 token、单日峰值和最长会话。
- 用右下角的 Refresh 按钮手动刷新；失败时顶部会出现可重试的横幅，已有数据不受影响。
如果数字看起来有问题，先按下面的顺序排查：确认缓存文件所在 profile 的路径正确 → 看页脚提示的 counted / no longer listed / skipped 会话数 → 删除缓存文件后刷新重建。注意「会话数 counted 大于当前存储的会话数」是正常现象，因为它包含了仍留在账上的已删除会话。
想从零开始（比如换机器后不想带上旧账），删除 <profile>/plugin-state/usage-stats-cache.json 再刷新，插件只从仍然存在的会话日志重建。
适用场景与注意¶
适合想回头看自己 token 开销分布、区分不同模型用量的本地 DSH 使用者，尤其是用多模型跑长链路、需要判断哪个模型占大头的场景。
几点需要留意：
- 插件以当前 DSH 进程的权限运行，安装前应自行检查源码与许可证（MIT），不要把它当作官方组件。
- 这是非官方插件，DSH 扩展 API 在不同版本间可能变化，升级宿主后需要重新验证。
- 删除会话不会让历史总量下降，如果需要真正的「当前状态」视图，这个插件给的不是。
- 统计上限 20,000 个会话；窄的面板上热力图减少周数而非缩放单元格，窄面板看不全一年。
- 「Last 7 days」趋势实际绘制 8 个点（今天加此前 7 天），与参考设计一致。
- DSH 0.2.2 新增了德语、西班牙语、法语、日语、葡萄牙语、俄语界面；本插件文案仍为中英双语，其他语言回退到英文。
目录页与源码¶
目录页：https://www.skillhub.cn/plugins/ailawu0409/dsh-usage-stats
源码：https://github.com/ailawu0409/dsh-usage-stats
需要说明的是，目录页是独立社区站点，与 DeepSeek / 幻方没有官方从属关系，不是官方应用商店。
