用量热力图 RafaGonzalezDev/dsh-model-usage

dsh-model-usage

一个原生 DeepSeek Harness 插件，告诉你 token 都花在了哪里：一张每日用量日历热力图，外加按模型、按服务商的明细，数据来自配置档里的所有会话。

| 包名 | dsh-model-usage（本源仓库为 dsh-model-usage） |
| 版本 | 0.4.5 |
| Harness 兼容性 | >=0.2.0-rc.2 <0.3.0-0 |
| 协议 | MIT |

展示内容

- 年度总览合并视图：窗口数字、最常用模型的侧栏，以及铺满可用宽度的方形日格日历。月份标签在网格上方，不显示星期标签。鼠标悬停单元格，会在原生抬升的 bg-layer-3 表面上弹出当天详情，带深色阴影。
- 月度模型迷你图：每个模型 12 根柱子，而不是每日图表。
- 按服务商分组的明细：点击服务商行的任意位置，展开按模型拆分的详情（token、请求数、占比、输入、输出、缓存读取、最后使用日期）。每一行始终显示这些详情：没有简化视图，也没有开关。服务商行没有箭头；表格行使用左右内边距和圆角条带。
- 固定 12 个月视图（365 天），包含浏览器时区下的今天。没有时间范围选择器；总览和明细始终描述同一个窗口。
- 「Modelos más usados」上方的实时搜索：输入即可同时过滤日历、模型、表格和工作量汇总，匹配官方名称、模型 ID 或服务商，不区分大小写。没有「Filtrar actividad」下拉框，也没有服务商/模型标签选择器。
- 官方选择器名称，取自当前 DSH 模型目录（LlmModelInfo.name），找不到时回退到持久模型 ID。服务商/模型标识符保持不变。
- 推理工作量覆盖：记录的工作量等级和请求数，与推理 token 数分开统计。缺失的工作量是未知，不是默认值，也不是零。

仪表盘是主视图：从侧边栏底部的按钮打开，装了 dsh-chatgpt-plan 时就在 ChatGPT Plan 提示的正下方，点 Volver 回到对话。

统计方式

有两种持久事件类型携带服务商用量，两者都计入：

| 事件 | 服务商与模型 | 用量 |
| assistant/message | data.message.source.{provider,model} | data.usage |
| compaction/summary | data.provider、data.model | data.usage |

totalTokens 等于 inputTokens + outputTokens。缓存读取是输入的子集，推理 token 是输出的子集：两者都不计入任何总量，只有缓存读取保留自己的一列明细。没有报告用量的步骤仍计为请求。assistant/attempt、标题生成和网页搜索请求记录不携带用量，一律忽略。

工作量只来自最新 request/header 事件的 data.header.config.reasoningEffort，当它的服务商/模型与助手消息匹配时。不带 effort 的新 header 会清除该归属。压缩摘要不继承对话 effort。effort 请求计数之和就是已知覆盖范围；其余请求的 effort 未知。reasoningTokens 衡量的是输出 token，两个字段互不蕴含。

Remote 契约新增可选的 series[].name 和 seriesTotals[].reasoningEfforts: { effort: string; requests: number }[]。现有标识符、reasoning token 总数和 reasoningReported token 覆盖计数保持兼容。名称是当前目录标签，不是历史标签；缺失目录时保留模型 ID。Host 仍接受此前的范围契约以保持兼容，尽管这个仪表盘只请求 365 天。

聚合范围是整个配置档：每个工作区、每个子代理会话、每个项目。继承的 fork 历史按现有的按会话规则计数，不跨会话去重。会话日志记录 token，从不记录成本，因此不显示任何金额。

安装

构建包，然后通过 Harness 原生插件管理器在目标配置档中安装同一个 tarball。保留此前可用的 tarball 以便回滚。

nvm use
npm ci
npm run check
npm run pack:plugin

以上命令会在仓库根目录生成 dsh-model-usage-<version>.tgz。

Windows Desktop

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add "C:\path\to\dsh-model-usage-0.4.5.tgz"

macOS Desktop 和本地 Web

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" plugin --profile desktop add /absolute/path/dsh-model-usage-0.4.5.tgz
dsh plugin --profile web add /absolute/path/dsh-model-usage-0.4.5.tgz

desktop 配置档由 Electron 应用管理，因此要用应用的 restartHost 操作重新加载；之后刷新现有 UI。只改源码永远不会改变已安装的配置档。如果要让智能体驱动安装或无人值守安装，请遵循智能体安装手册。

这些数字从哪来

Host 会折叠 Harness 已经写入的持久会话日志，并按会话把结果缓存到 <profile>/.cache/dsh-model-usage/usage-v1.json。此版本使用缓存 schema 3；文件名不变。更新后的 Host 加载后，旧缓存会自动丢弃，并从会话日志重建。未变更的持久会话复用其缓存贡献；没有持久化签名的活动会话会重新读取。模型名称按每个快照从当前目录获取，不持久化到此缓存中。

升级时，重建 Host、生成的 Remote 契约和 Client，安装更新后的 tarball，然后重启 Host 并刷新现有 UI。只刷新浏览器无法激活新的 Host 字段或缓存 schema。
npm run verify:usage 会独立重算每一条持久化日志，再和缓存里的结果比对：

npm run verify:usage
npm run verify:usage -- --cache "C:\Users\you\.dsh\profiles\desktop\.cache\dsh-model-usage\usage-v1.json"

活跃会话，以及上次扫描之后才持久化的活动，都可能让两边出现差异，方向不限。诊断计数错误之前，先在一个空闲配置档上，把刷新过的缓存和持久化日志比对一遍。

开发

nvm use
npm ci
npm run check # build Host, generated RPC and Client, then run the suite
npm run typecheck # static types
npm run pack:plugin # emit the installable tarball in the repository root

测试套件跑在 Node 自带的类型剥离上，不用 loader，所以既不需要构建步骤，也不需要子进程。React 视图通过纯推导逻辑和实时 UI 来验证；Node 运行器解析不了 .tsx。

文档

审阅者需要的一切都在本 README 和源码里。面板文案本身以西班牙语发布。终端或桌面智能体的安装、验证与回滚步骤见智能体安装手册。

许可证

MIT。第三方声明转载于 THIRD_PARTY_NOTICES.md。