dsh-ui-web/packages/dsh-usage-dashboard

一句话定位

为 DSH Web 提供一个彩色用量看板，自动记录每次模型响应的 token 用量并落地到 ~/.dsh/usage.json，按会话、按天、按模型聚合展示 14 天趋势柱状图、模型分布环形图与会话排行 Top 20，并按 DeepSeek 官方定价估算费用。

核心能力

• 自动采集 token 用量：在会话底栏挂一个不可见的录制席位，监听 token 用量投影流式增长，2 秒静默后把会话累计快照上报给宿主（不会把刷新前已存在的历史当成新增算入）
• 彩色统计看板：点击侧边栏入口弹出全屏浮层，渲染四张渐变卡片（累计 token / 调用次数 / 缓存命中 / 估算费用）并按 14 天、模型分布、会话排行三个维度展开
• 费用估算：按模型名匹配 DeepSeek 公开档位（v4-flash、v4-pro、reasoner、legacy），缓存命中单独走缓存档单价，避免双计费
• 会话快照替换语义：同会话在 host 侧只保留最新快照，多次上报以"增量"形式累加到天/模型/总计，刷新与切换会话都不会重复入账
• 局域网二维码入口：侧边栏"手机端查看"按钮调宿主接口枚举本机 IPv4，按 192.168 / 10 / 172.x 优先级排序，结合当前端口渲染二维码与可复制链接
• 检查更新入口：复用同一玻璃样式弹窗，调用宿主 /api/web-ui/version 显示当前与最新版本号
• 设置面板信息卡：在 Web UI 插件组的设置页挂一张纯说明卡片（无配置字段），介绍看板的记录位置与数据落点

技术实现

• 语言: TypeScript（peer 依赖 React 18.2，dsh.client.platform="web"）
• 关键依赖: @deepseek-ai/dsh-host-webserver（路由宿主）、@deepseek-ai/dsh-token-meter（token 用量投影类型）、@deepseek-ai/dsh-client-connection（拉取会话模型）、qrcode-generator（手机端查看二维码）
• 架构模式: Cordis 双向插件。Host 半体向 webServer 注入前缀路由 /api/usage/{record,lan,summary}，把聚合数据写回 ~/.dsh/usage.json；Client 半体在 conversation.composer.dock 槽挂不可见录制席位、用 DOM 注入的方式在 sidebar 插入三枚按钮，并在 web-ui.plugin.item 槽挂说明卡片
• 入口文件: 宿主侧 src/index.ts（导出 name/USAGE_API_PREFIX/apply 及聚合纯函数），客户端 src/client/index.ts；费用档位集中在 src/cost.ts，UI 渲染集中在 src/client/DashboardPanel.tsx 与 src/client/UsageEntry.tsx

适用场景

当你想知道"过去两周我都用了多少 token、哪些模型最费钱、哪几个会话跑得最猛"时，这个插件把所有数据按可视化图表呈现，本地存档、不上传服务端。适合对调用成本敏感的重度用户、需要在团队内对账的开发者，以及对模型速率/调用分布做长期回看的运维/PM。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-usage-dashboard

安装完成后重启 dsh web，宿主路由 /api/usage/{record,lan,summary} 才会被注册；侧边栏会自动多出"用量 / 手机端查看 / 检查更新"三枚按钮（与任务看板同源 DOM 注入模式，遇到 React 重渲染会自愈）。

可选：通过 DSH_HOME 环境变量改写持久化目录（例如 export DSH_HOME=/path/to/dir），数据将落到 $DSH_HOME/usage.json 而非默认 ~/.dsh/usage.json。

配置项

本插件无需额外配置。三个行为参数均在源码中固化：

设置页 "Web UI 插件" 组下挂的卡片为纯说明，不暴露任何开关或输入字段。

常见问题

Q: 安装后需要重启 DSH Web 吗？

A: 需要。宿主半体通过 ctx.inject(['webServer']) 注册路由，host 进程不重启就不会调起 apply；浏览器侧硬刷新只会重新挂录制席位与侧边栏 DOM，无法让 /api/usage/* 路由上线。

Q: 数据存在哪里？怎么清理？

A: 默认落在 ~/.dsh/usage.json。可通过 DSH_HOME 环境变量改写目录（process.env.DSH_HOME ?? join(homedir(), '.dsh')，src/index.ts:86）。删除该文件即完全清空历史；插件不会自动迁移或备份，下次重启会重新从空文件开始累计。

Q: 估算费用是按什么单价算的？准确吗？

A: 按模型名匹配 DeepSeek 官方公开档位：flash → v4-flash、reasoner / r1 → 推理档、pro / v4-pro → v4-pro、deepseek → 旧标准档，其余回退通用档（src/cost.ts:39-46）。属于看板展示用估算，并非计费依据；缓存命中单独走缓存档单价，输入 token 不包含缓存部分，不会与缓存档重复计算。

Q: 计费会不会把一次会话的 token 重复算多次？

A: 不会。客户端用会话累计快照替换语义上报：录制组件首次挂载只记录基准线不上报（src/client/UsageRecorder.tsx:106-110），后续只在 token 用量"真正增长"且 2 秒静默后才上报一次（flush 函数）。宿主对同会话只保留最新快照，按"新值减旧值"的增量写入天/模型/总计桶；遇到投影归零（例如刷新会话）会用 Math.max(0, ...) 钳住不减（src/index.ts:148-151）。

Q: 看板里"今日"对应哪个时区？

A: 本地时区。dayKey 用 Date.getFullYear/getMonth/getDate 拼出 YYYY-MM-DD（src/index.ts:90-95），所以跨过本地午夜 0 点之后才会出现新一天的柱状图；服务器时区与浏览器时区都不会影响聚合。

Q: 卸载后需要做什么吗？

A: 卸载插件并重启 dsh web 即可。宿主侧 dispose 会注销 /api/usage/* 路由，客户端 mountUsageEntry 返回的 disposer 会移除侧边栏三枚按钮并停止 MutationObserver。历史 JSON 文件不会被自动删除，留在原位置方便回看或人工备份。

Q: 侧边栏的"手机端查看"是怎么工作的？

A: 点击后调 /api/usage/lan 让宿主枚举本机所有非内部 IPv4，按"192.168 → 10. → 172.16-31 → 其他"四档优先级排序（src/index.ts:274-287），结合浏览器当前端口渲染二维码与可复制链接，方便手机在同一 Wi-Fi 下扫码访问。需要浏览器允许 navigator.clipboard.writeText 才能复制（不安全上下文会静默失败）。

Q: 支持 TUI、桌面端或移动端吗？

A: 暂不支持。客户端半体的 UI 全部基于 DSH Web 的 sidebar shell 与 composer dock 槽位，TUI、桌面端、移动端没有等价挂载位置；宿主侧 /api/usage/* 路由在非 Web 形态下也无 UI 渲染，但 host 侧持久化逻辑本身是平台无关的，仍会写 ~/.dsh/usage.json。

上手难度

入门 — 安装一行命令、重启 DSH Web 即可看到效果，所有行为参数均固化无需调整；只有想改持久化目录或对账单价时需要碰环境变量。

已知问题与限制

• 零配置但不可调：录制静默阈值、模型轮询间隔、看板回看天数均硬编码（2s / 5s / 14 天），未提供设置项；需要调整必须改源码后自构建
• 单步录制：录制组件只看当前会话的 tokenUsage 投影累计，不会区分同一会话里的多次往返；多会话并行时各自独立互不串扰，但同一会话切换模型后旧模型用量仍归在旧模型名上
• 会话标题回填：录制组件只在首次增长时把 currentTitle 当作会话标题写进快照（src/client/UsageRecorder.tsx:118-124），会话在客户端改名后下一轮响应才会刷新看板上的标题
• 估算单价滞后：费用档位表在 2026-08 由源码硬编码（src/cost.ts:18-27），DeepSeek 调价后需要改 cost.ts 并重新构建，看板上不会自动拉取官方最新价
• 二维码复制权限：手机端查看的"复制地址"按钮走 navigator.clipboard.writeText，浏览器在非 https / 非 localhost 下可能静默失败，但二维码和地址文本仍可见
• 模型名"unknown"：若宿主侧 /api/usage/record 上报的 model 字段缺失，规范化为字符串 unknown 并归入 byModel.unknown 桶（src/index.ts:244），不会让整条记录被丢弃