xinmo114514/dsh-usage-dashboard ↗★ 0
DSH web plugin: 设置页 Token 消耗仪表盘 —— 总/输入/输出 token 指标卡、近7天每日 + 近24小时逐时趋势图、按模型/会话分布；宿主半扫描会话日志（assistant/message usage 事件）并提供 GET /usage/api/dashboard
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:xinmo114514/dsh-usage-dashboard这是什么？ 一个为 DSH（DeepSeek Harness）Web 界面打造的 Cordis 插件。它把散落在 ~/.dsh/sessions/ 下的全部会话日志中的 token 用量聚合起来，在 设置 → Token 用量 分区呈现为一个完整的消耗仪表盘。
解决什么问题？ DSH 本身不提供全局的 token 消耗视图；想知道“近 7 天 / 今天 / 某个模型 / 某个会话花了多少 token”，只能翻原始日志。本插件把这些信息变成打开设置就能看到的图表。
核心亮点：
]
session.jsonl.zstd（多帧 zstd），不依赖解释器逐条重放，数据完整可审计--dsw-alias-* 设计令牌，明暗主题、窄屏布局自动适配
设置对话框中的「Token 用量」分区：指标卡 + 近 7 天每日堆叠柱状图 + 逐时双折线 + 按模型 / 按会话分布（数据为真实会话日志聚合）
仪表盘在 DSH Web 设置页中的实际位置：侧边栏底部齿轮 → 设置 → 左侧「Token 用量」
| 功能 | 说明 | 截图 |
|---|---|---|
| 🧮 核心指标卡 | 总消耗 / 输入 / 输出 / 缓存读取，附调用次数、会话数、占比、缓存写入、推理量、缓存命中率；数值按位数自动缩放字号，任何宽度下不截断 | dashboard.png |
| 📊 近 7 天每日消耗 | 输入 / 输出 / 缓存堆叠柱状图，悬停查看当日明细（总数、输入、输出、缓存、调用次数） | 同上 |
| ⏱️ 逐时消耗 | 输入 / 输出双折线图，支持 7 小时 / 24 小时窗口切换，悬停查看整点明细 | 同上 |
| 🤖 按模型分布 | 横向条形 + 占比（模型名取自 assistant/message 事件的 data.message.source.model），品牌色同色系透明度阶梯，排名靠长度表达 | 同上 |
| 💬 按会话分布 | 会话列表（标题 + 调用次数 + tokens + 占比），可「展开全部」查看所有会话 | 同上 |
| 🔔 状态反馈 | 扫描中脉冲徽标、缺失会话警告徽标（悬停显示原因）、手动刷新按钮、空状态 / 错误状态 | 同上 |
| 🌓 响应式布局 | 容器查询自适应：宽容器 4 列 → 常规 2 列 → 极窄 1 列指标卡，手机宽度不横向溢出 | 同上 |
仪表盘展示的每一个数字都可追溯到本机的会话日志文件。
~/.dsh/sessions/**/session.jsonl.zstd（DSH_HOME 可覆盖，默认 ~/.dsh），RAW zstd 直接解析（多帧用 zstd CLI 解压，Node 内置 zlib 只能解出首帧）；RAW 解码失败（如仍在写入的尾部帧）自动回退 sessionQuery.readSession / sessionPersistence.readFrom。assistant/message 事件的 data.usage.{inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens}；total = input + output + cacheRead + cacheWrite（不含 reasoning）。data.message.source.model（缺失时回退 data.model，再缺失记 unknown）。session/title 事件，缺省回退工作目录 basename，再缺省显示截断的会话 id。ctx.on('session/event') 监听新产生的用量事件，每个会话以 maxSeq 水位去重，与扫描结果幂等合并。插件分为两个“半”（与 DSH 插件惯例一致）：
┌──────────────────────────── host 半（Node，src/index.ts）───────────────────────────┐
│ cordis 注入：webServer · sessionQuery · sessionPersistence · timer │
│ ┌─────────────┐ RAW 直读 ┌──────────────┐ 五维折叠 ┌──────────────┐ │
│ │ 会话日志目录 │ ───────────▶ │ 扫描器（4 并发）│ ─────────▶ │ 内存聚合存储 │ │
│ │ ~/.dsh/sessions │ harness 兜底 │ 60s 自愈重扫 │ 实时事件折叠 │ totals/daily │ │
│ └─────────────┘ └──────────────┘ │ hourly/byModel│ │
│ │ /bySession │ │
│ GET /usage/api/dashboard（仅回环 Host 可访问）◀─────────────┘ │ │
└──────────────────────────────────────────────────────────────────────────────────────┘
│ HTTP（4s 轮询）
┌──────────────────────────── client 半（浏览器，src/client/index.tsx）─────────────────┐
│ slots.inject('settings.section') → 设置对话框左侧「Token 用量」（order 40） │
│ 指标卡 / SVG 图表 / 分布列表 —— 纯 createElement，无 JSX、无图表库依赖 │
└──────────────────────────────────────────────────────────────────────────────────────┘
export const inject = [...]），由插件自身声明。window.__ModuleLoader__.load({ id, factory }) 注册进 Web shell 的冻结模块表，运行时仅 require('react')。dsh-usage-widget 等插件的 /usage/api 前缀路由共存（webserver 优先匹配 exact 表）。| 依赖 | 版本 |
|---|---|
| Node.js | ≥ 20 |
| 包管理器 | pnpm（npm / yarn 亦可） |
| zstd CLI | 可选：缺失时 RAW 解压自动回退 harness 读取 |
| DSH Web 环境 | 已运行的 DSH Web 实例（默认 http://127.0.0.1:3080） |
# 1. 安装依赖
pnpm install
# 2. 构建（tsdown 双产物）
pnpm build # → lib/index.js（host 半，Node ESM）
# → lib/client.js（client 半，浏览器 CJS，带 sourcemap）
# 开发模式（监听文件变更自动重建）
pnpm watch
方式 A：patch 文件（持久化，重启后仍生效）
将本仓库 cordis.patch.yml 的内容合并进 DSH profile 的 cordis.patch.yml（并将本仓库目录 link 到 profile 的 node_modules 下，使 loader 能按 name 解析到包）：
# cordis.patch.yml
- insert:
- id: usage-dashboard
name: 'dsh-usage-dashboard'
方式 B：超级模组注入器（免重启热装配）
在 DSH 会话中调用注入器工具，运行时加载本插件（host 半 + client 半同时生效）：
dev_install_package {"dir": ""}
提示：
package.json的dsh.bundle.patch字段指向./cordis.patch.yml，构建产物files已包含lib/、src/、README.md、cordis.patch.yml，可直接作为 bundle 包分发。
http://127.0.0.1:3080Host 半暴露一个只读 JSON API，供仪表盘（及第三方工具）查询聚合结果：
GET /usage/api/dashboard?range=7d|30d|24h|all&hours=24&top=8
请求参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
range | string | 7d | 每日序列范围：7d / 30d / 24h / all（all 返回全部历史自然日） |
hours | number | 24 | 逐时序列小时数（1–168，自动夹取） |
top | number | 8 | 按会话分布返回条数（1–200，自动夹取） |
响应：{ "ok": true, "value": { ... } }；value 字段如下：
| 字段 | 说明 |
|---|---|
totals | 全量合计：input / output / cacheRead / cacheWrite / reasoning / total / calls |
daily | 按自然日零填充的序列（默认最近 7 天；range=all 返回全部） |
hourly | 按小时零填充的序列（默认最近 24 小时） |
byModel | 按模型聚合，total 降序 |
bySession | 按会话聚合（含 title / cwd / lastAt），total 降序，默认 top 8 |
scanning / scans / failed | 扫描状态、累计扫描轮数、最近一轮失败会话数 |
rawSessions / harnessSessions | 通过 RAW 日志 / harness 兜底折叠的会话数（审计用） |
foldedEvents / dedupSkipped | 已折叠的用量事件数、水位去重跳过数（审计用） |
lastError / scanError / lastScanAt | 最近失败详情、灾难级错误、最近扫描时间（诊断用） |
sessions / range / time | 已知会话总数、本次请求的 range、服务端时间戳 |
安全围栏：仅回环 Host（localhost / 127.x.x.x / ::1）可访问，非回环请求返回 403（防 DNS 重绑定 / 跨站探测）；非 GET 请求返回 405。
示例：
curl 'http://127.0.0.1:3080/usage/api/dashboard?range=7d&hours=24&top=8'
{
"ok": true,
"value": {
"totals": { "input": 7506973, "output": 2923767, "cacheRead": 605730560, "cacheWrite": 0, "reasoning": 0, "total": 616161300, "calls": 4144 },
"daily": [ { "t": 1786204800000, "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "reasoning": 0, "total": 0, "calls": 0 } ],
"hourly": [ { "t": 1786705200000, "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "reasoning": 0, "total": 0, "calls": 0 } ],
"byModel": [ { "model": "deepseek-v4-flash", "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "reasoning": 0, "total": 0, "calls": 0 } ],
"bySession": [ { "id": "", "title": "", "cwd": "", "lastAt": 1786783462748, "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "reasoning": 0, "total": 0, "calls": 0 } ],
"scanning": false, "scans": 1, "failed": 0,
"rawSessions": 78, "harnessSessions": 0,
"foldedEvents": 4144, "dedupSkipped": 20697,
"lastError": null, "scanError": null, "lastScanAt": 1786783462748,
"sessions": 78, "range": "7d", "time": 1786783496254
}
}
插件无用户可配置项（无需设置界面），以下为源码内置行为：
| 行为 | 值 | 位置 |
|---|---|---|
| 前端轮询间隔 | 4 秒（仅仪表盘分区挂载期间） | src/client/index.tsx |
| 自愈重扫周期 | 60 秒（防重入锁） | src/index.ts |
| 扫描并发 | 最多 4 个 worker | src/index.ts |
| 设置分区顺序 | order: 40（在“通用设置”0 与“远程访问”30 之后） | src/client/index.tsx |
| 会话分布默认条数 | top 8（可展开至 200） | src/index.ts、src/client/index.tsx |
/usage/api/dashboard 仅回环 Host 可访问，防 DNS 重绑定与跨站探测dsh-usage-dashboard/
├── src/
│ ├── index.ts # host 半：日志扫描 + 五维聚合 + /usage/api/dashboard
│ └── client/
│ └── index.tsx # client 半：设置页 section（settings.section 槽）+ SVG 图表
├── cordis.patch.yml # bundle 层 loader 条目（id: usage-dashboard）
├── tsdown.config.ts # 双产物构建配置（host ESM + browser CJS）
├── UI_AUDIT.md # 界面审计报告（布局 / 对比度 / 交互态）
├── UI_OPTIMIZATION_PLAN.md # UI 优化方案（设计基线 / 响应式验收目标）
├── docs/
│ └── images/
│ ├── dashboard.png # 仪表盘全览截图
│ └── dashboard-context.png # 仪表盘在设置页中的位置截图
├── lib/ # 构建产物（pnpm build 生成，勿手改）
└── package.json
pnpm add 一键安装Roadmap 为计划项，欢迎在 Issues 中提议或认领。
欢迎任何形式的贡献（bug 报告、功能建议、代码、文档）。流程如下：
git checkout -b feat/my-featuregit commit -m "feat: ..."（建议遵循 Conventional Commits）git push origin feat/my-feature开发提示：改动后运行 pnpm build 确认双产物构建通过；涉及 UI 的改动请同步更新 UI_AUDIT.md / UI_OPTIMIZATION_PLAN.md（如适用）。
Unlicense —— 公有领域（public domain）授权，最开放的自由许可之一：任何人可自由复制、修改、分发、商用，无需署名、无需保留版权声明，作者不提供任何担保。完整文本见 LICENSE。
Made with 💙 for the DSH community · 数据不出本机，用量尽在眼前