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

34Star2Fork0Issue0Watching

为 DSH Web 提供彩色用量看板：自动记录每次响应的 token 用量，按会话/天/模型聚合并展示 14 天趋势、模型分布、会话排行与按 DeepSeek 定价的费用估算，数据落地本地 ~/.dsh/usage.json。

分类🖥️ 界面增强⚙️ 任务与自动化
CAPTAIN1275CAPTAIN1275
·CAPTAIN1275/dsh-ui-web.git
语言
TypeScript
License
Apache-2.0
分支
main
dsh-plugindsh-plugin-marketdsh-plugins

安装

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

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

为 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 Web0.1.0-rc.6peerDependencies 钉在 ^0.1.0-rc.6（含 @deepseek-ai/dsh-client-connection、@deepseek-ai/dsh-host-webserver），cordis patch ui-usage-dashboard 需被 host 解析
React18.2.0客户端卡片、看板浮层、侧边栏 DOM 注入均依赖 React 18
平台跨平台（macOS / Windows / Linux）运行时不限操作系统；看板只渲染在 Web 宿主，持久化文件走 host 侧 ~/.dsh 目录
原生模块无全部逻辑在 TypeScript / React 内完成，二维码用纯浏览器 qrcode-generator 实现，无 node-gyp 依赖
Node未声明包内无 engines 字段，但运行时需要 Node 内置 node:fs、node:os、node:http 模块

安装方式

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。

配置项

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

行为取值来源
录制静默阈值（每轮响应结束判定）2 秒src/client/UsageRecorder.tsx:36（SETTLE_MS = 2000）
模型轮询间隔（拉取当前会话模型名）5 秒src/client/index.ts:95（window.setInterval(..., 5000)）
看板回看天数14 天src/index.ts:304（recentDays(store, 14)）

设置页 "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），不会让整条记录被丢弃
返回插件目录