@deepseek-ai/dsh-usage-dashboard

DeepSeek Harness 的用量仪表盘插件：在 Web GUI 的设置弹窗里以「用量」小节呈现，按「今日 / 本周 / 本月」展示 Token 总量、估算花费、缓存命中占比、按模型分布、工具调用排行与全年活跃热力图。交互语言参考 TokenScope（hero 计数动画、双色缓存拆分条、堆叠柱状图、费用环图、sparkline 与 GitHub 风格热力图），视觉完全遵循 dsh 设置面板的设计语言：IconDataOutline16 图标、模块卡片（layer-1 表面 + 细边框 + 圆角）、14/22 正文字号与 --dsw-* 主题 token，深浅主题自动适配。

插件是双面（dual-half）包：Node 侧聚合 session/event 事件流并注册 GET /api/usage-dashboard 路由；浏览器侧通过 settings.section 插槽注册面板。遵循 dsh 客户端插件规范（dsh.client 清单、window.__ModuleLoader__ 闭包产物、CSS Modules + --dsw-* 主题 token、slots.inject 声明期注入）。

国际化：全部文案与时间轴标签跟随 harness 的语言设置（设置 → 通用 → 语言）实时切换中文/英文——词典注册在 usage 命名空间，宿主只下发语言无关的时间键（YYYY-MM-DD / YYYY-MM-DDTHH），刻度与悬停标签由客户端按当前语言格式化。

功能

区域	内容
头条	本时段总 Token（计数动画）、环比涨跌、估算花费；时段切换器右侧提供截图按钮（TokenScope 同款：modern-screenshot 2x 光栅化整段面板，按当前主题底色导出 PNG 下载，截图按钮自身被过滤，toast 反馈）
缓存拆分	已缓存 / 新输入 双色占比条 + 命中率；蓝色系双色调（TokenScope 同构：深=已缓存、浅=其余）
趋势图	按小时（今日）/ 按天（本周、本月）的堆叠柱状图，悬停提示；横轴沿用 TokenScope 刻度约定：今日每 4 小时一个刻度（04/08/…，跳过 0 点）、本周逐日标注周一周日（英文 MonSun）、本月只标 1 日与每 5 日
模型分布	Token 份额排行（最大余数法保证占比合计 100.0%）与花费环图；无价格模型仅统计 Token 并在脚注注明。颜色遵循「用量越多颜色越深」：排行第 1 最深品牌蓝，逐级变浅
迷你指标	请求数、会话数、花费趋势 sparkline
工具调用	按调用次数的排行（默认前 5，可展开）
热力图	每日活跃度热图：与 TokenScope 同口径 —— 约 26 周、周日对齐开头，四等分色阶（f<0.25/0.5/0.75 分档），悬停提示与 Less/More 图例；月份标注与文案随语言切换

数据口径

• 来源：session/event 事件流。仅折叠 assistant/message 的最终 usage（流式 assistant/chunk 的 usage 采样是该步的预览，不重复计数）；无效 usage（缺失或非有限数的 input/output）跳过。
• 时间：按宿主进程本地时间落桶（天桶 + 最近 48 小时的小时桶），与用户看到的日历一致。本周为自然周（周一周日）、本月为自然月（1 日月末），环比基期为上一自然周/自然月，与 TokenScope 口径一致。
• 模型归属：每会话记录最近一次 request/header 的 config.model；无归属计入 unknown。
• 持久化：聚合每 30s 原子写入 $DSH_HOME/usage-dashboard.json（tmp+rename），启动时恢复，因此重启不丢历史。种子历史不触发事件，统计自插件挂载起累计。
• 保留：天桶保留 keepDays（默认 400 天，需覆盖热力图窗口）；小时桶保留 48 小时。热力图窗口固定为约 26 周（周日对齐，同 TokenScope）。

价格与成本估算

价格算法与 TokenScope 完全一致（移植自其 pricing.rs）：

• 数据源：models.dev 公开目录（https://models.dev/api.json，USD/百万 token），24h 定时刷新，缓存原始 payload 到 $DSH_HOME/usage-pricing.json（离线用快照），目录解析零模型时拒绝写入缓存防止污染。Config.pricing 可按模型覆盖。
• 计价公式（四种 token 各按自己的单价，缺省即 0，不做输入价兜底）： cost = input×输入单价 + output×输出单价 + cacheWrite×缓存写单价 + cacheRead×缓存读单价
• 选价规则（目录中同一模型 id 出现在多个供应商名下）：按「官方供应商优先 → 含缓存价的条目优先 → 裸 id 优先」稳定排序后首写者胜（与 TokenScope 的 is_first_party/has_cache/bare 排序一致；官方映射含国际+国内双键，套餐键排除）；全零价格条目不作为计价来源。
• 匹配：精确 id → 裸 id 别名 → 规范化键（小写 + .→p 版本分隔统一，如 glm-5.1 ⇄ glm-5p1）。匹配不到只统计 Token、不计花费，UI 脚注列出。
• 所有金额标注「估算 (est.)」。与 TokenScope 的差异仅在兜底来源：TokenScope 另有 LiteLLM 补缺 + 内置快照，本插件当前只接 models.dev（DSH 常用模型均被覆盖；如需 LiteLLM 层可再加）。

安装

把仓库地址交给你的 DSH Agent，用一句话让它安装即可（无需手动软链或改配置）：

帮我安装这个 DSH 插件：https://github.com/HduSy/dsh-tokenscope

Agent 会完成克隆、依赖/构建（仓库已内置构建产物，通常可跳过）与挂载配置，装完刷新浏览器页面，进入「设置 → 用量」查看。配置为热生效，无需重启服务。

配置

Loader 行 config 字段，全部可选（Schemastery 校验）：

键	默认	说明
pricing	—	按模型覆盖价格（每 token 美元）：{ input, output, cacheRead?, cacheWrite? }，覆盖拉取目录
pricingUrl	https://models.dev/api.json	价格目录地址
pricingRefreshMs	86400000	拉取间隔；false 完全禁用网络（离线部署）
pricingCacheFile	usage-pricing.json	$DSH_HOME 下的价格缓存文件
keepDays	400	天桶保留天数（183–800；热力图窗口固定为 26 周）
flushIntervalMs	30000	聚合落盘间隔
snapshotFile	usage-dashboard.json	$DSH_HOME 下的聚合快照文件

HTTP 接口

• GET /api/usage-dashboard —— 完整快照（UsageSnapshot：day/week/month 三个 PeriodReport + 热力图 + 价格更新时间）。仅回环地址，cache-control: no-store，浏览器端每 5s 轮询。
• 路由以 prefix 注册在 ctx.webServer 上；最长前缀匹配使请求进入本插件而非 connection 的通用 /api 前缀，无需触碰 apiproxy 白名单。未组合 web server 的 profile（如 headless）仍会聚合与持久化。

架构

session/event ──► UsageTracker（天/小时桶聚合，纯内存）
                        │ serialize/restore
                        ▼
                 $DSH_HOME/usage-dashboard.json
                        │ snapshot(pricing)
                        ▼
GET /api/usage-dashboard ──► 浏览器 settings.section 面板（每 5s 轮询）
models.dev/api.json ──► PricingSource（24h 刷新 + 本地缓存 + Config 覆盖）

导出纪律：apply/inject/Config + 线类型（UsageSnapshot 等）；图表组件与聚合器均为包内实现。

开发

pnpm install
pnpm run typecheck   # tsc（src + tests）
pnpm run build       # tsc 发射 → tsdown（node lib + 浏览器闭包产物）
pnpm test            # vitest：聚合/价格/插件生命周期/路由/组件

依赖通过 file: 链接指向 dsh 仓库的包与 vendored cordis；产物 lib/client.js 是 window.__ModuleLoader__.load({ id, factory }) 闭包（CJS，CSS Modules 由 lightningcss 内联，platform 模块走冻结模块表）。

Model Experience

None, as the plugin reads the session firehose and renders a browser dashboard; it registers no tools, prompts, or events, and nothing it computes reaches a model request.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

• 统计自插件挂载起 —— 构造器种子历史不触发 session/event，安装前的历史用量不会回填；挂载后每个事件恰好触发一次，跨重启由持久化聚合衔接，无需 seq 去重。
• 价格目录的 tier 定价不解析 —— models.dev 中带 tiers / context_over_200k 阶梯价的条目只取扁平 input/output/cache_read/cache_write 字段；阶梯价模型按基础档估算。
• 模型匹配不做别名兜底 —— 仅精确 id + /、@ 后 slug 匹配，避免错算；错配模型只显示 Token 数。
• 估算非账单 —— 花费是公开目录价 × 精确 Token 数的等效价值，订阅/内部计费口径以实际账单为准。
• 轮询而非推送 —— 面板以 5s 轮询取数；会话级实时性足够，但毫秒级事件回放不在范围内。
• 单文件持久化 —— 聚合快照是整文件原子覆写；规模上限由 keepDays 约束（400 天约数 KB–MB 级），跨设备同步与数据库后端属后续工作。