@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 点）、本周逐日标注周一~~周日（英文 Mon~~Sun）、本月只标 1 日与每 5 日
模型分布	Token 份额排行（最大余数法保证占比合计 100.0%）与花费环图；无价格模型仅统计 Token 并在脚注注明。颜色遵循「用量越多颜色越深」：排行第 1 最深品牌蓝，逐级变浅
迷你指标	请求数、会话数、花费趋势 sparkline
工具调用	按调用次数的排行（默认前 5，可展开）
热力图	每日活跃度热图：与 TokenScope 同口径 —— 约 26 周、周日对齐开头，四等分色阶（f 帮我安装这个 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 级），跨设备同步与数据库后端属后续工作。

配置