dsh-usage-hud
DSH（DeepSeek Harness）用量悬浮面板 — 右下角常驻多 Tab HUD：实时 token、会话记录、今日汇总、历史统计、使用热力图、24 小时曲线，外加按模型估算的费用。
A always-on usage HUD for DeepSeek Harness: live tokens, session records, daily totals, history, GitHub-style heatmap, 24-hour curve, and per-model cost estimation — docked in the bottom-right corner of the Web GUI.
✨ 功能
面板固定在 Web GUI 右下角（可折叠），六个 Tab：
| Tab | 内容 |
|---|
| 实时 | 当前会话累计 token 四项（输入未命中缓存 / 缓存命中 / 缓存写入 / 输出）、上下文压力条（>80% 告警变色）、上下文构成（system / tools / messages 三色分栏）、费用估算 |
| 会话 | 全部会话记录（自动登记，含子代理标记），按最近活动倒序；展开看详情：创建时间、轮次/请求数、平均每轮用量、分项 token、分模型用量、费用 |
| 今日 | 今日汇总卡片（token 总量、请求数、会话数、估算费用）+ 24h 分布迷你条 |
| 历史 | 按月汇总 + 按日明细 + 全部总量与总费用 |
| 热力图 | 类 GitHub 贡献图；默认近 1 年，可切 1 周 / 1 月 / 半年 / 1 年 / 全部；悬停看当日明细（token / 请求 / 费用） |
| 24h | 0–23 时用量柱状图，峰值小时高亮；前后翻日；点击热力图某天自动联动查看该日曲线 |
特性：
- 重启不丢数据 — 历史统计从 DSH 持久化会话日志（JSONL）重算，无需插件自建数据库
- 统计与官方口径一致 — 聚合采用
@deepseek-ai/dsh-token-meter 相同的折叠规则（同 turn/step 用量样本替换而非累加），费用按每请求实际模型逐笔估算
- 零 npm 依赖 — Host 半为纯 JS（手动 typert 注册 + duck-typed Remote 绑定），Client 半为自包含
__ModuleLoader__ bundle
- 只读、本地 — 不写任何会话数据、不联网上报
📦 安装
需要 DSH ≥ 对应 web profile（含 dsh plugin 命令）与 pnpm：
dsh plugin --profile web add dsh-usage-hud
然后重启 dsh web，面板自动出现（无需会话内 define / 审批）。
升级：
dsh plugin --profile web update dsh-usage-hud
卸载：
dsh plugin --profile web remove dsh-usage-hud
本地开发（link 模式，改源码即生效）：
git clone https://github.com/ksk2023/dsh-usage-hud.git
cd dsh-usage-hud
dsh plugin --profile web add .
🔧 工作原理
┌─ Client（浏览器）─────────────────┐ ┌─ Host（DSH 进程）──────────────────┐
│ shell.overlay 悬浮面板（6 Tab） │ RPC │ usagePanel Remote 服务 │
│ 实时 Tab ← sessions 投影 │ ───▶ │ summary() 跨会话/按日/按模型聚合 │
│ 其余 Tab ← usagePanel/summary │/api │ hourly(date) 指定日小时曲线 │
│ ← usagePanel/hourly │ │ 数据源：sessionQuery 重放持久日志 │
└───────────────────────────────────┘ └───────────────────────────────────┘
- 实时数据：读取官方
token-meter 投影（tokenUsage / contextPressure / contextBreakdown）
- 历史数据：Host 半经
sessionQuery.readSession() 重放全部会话日志，折叠出与会话内 tokenUsage 完全一致的累计值，再按本地日期 / 小时 / 模型分桶
- 通信：静态 Remote 通道（
connection.rpc.call('/api', 'usagePanel/*')），Host 侧手动 ctx.typert.register() + duck-typed typertRemote 绑定（typert-loader 文档保留的手写路径，codec 全部 src-json）
- 费用估算：内置 DeepSeek 官方定价表（2025-09，美元 / 1M tokens）；未收录模型显示
—，可在 lib/client.js 顶部 PRICING 中自行补充
仓库结构：
lib/client.js 浏览器半（__ModuleLoader__ bundle）
lib-host/index.js Host 半（聚合 + Remote 服务）
cordis.patch.yml profile 组合行（dsh.plugin add 自动挂载）
src/usage-panel/ 开发源与工具（动态版原型、离线验证脚本）
docs/ 设计文档与生态调研
📊 数据口径说明
- token 四桶与 DSH 官方
tokenUsage 投影一致：输入未命中缓存、输入缓存命中、缓存写入、输出（推理 tokens 计入输出）
- 「上下文构成」为启发式估算（system / tools / messages），三数之和不等于总量属正常
- 费用为估算值（面板底部有「非账单」提示），以模型提供商实际账单为准
🙏 相关项目
dsh-usage-panel（AlfredChaos）— 同领域的设置页版消耗统计（KPI + 热力图 + 模型图表）；本插件是悬浮 HUD 形态的独立实现，两者可共存
License
MIT
