用量成本看板 zhm20001/dsh-usage-board

dsh-usage-board

DeepSeek Harness (DSH / Cordis) 的全功能用量监控、成本核算与诊断大盘插件。

Node Version
License
[Zero Dependency]()

📖 简介

dsh-usage-board 是专为 DSH (DeepSeek Harness) 设计的用量与成本可视化看板插件。

插件能实时捕获会话内的 Token 消耗、Step 耗时和异常指标，支持冷启动增量回溯历史全量会话，并按 Sub-agent DAG 调用关系进行树状归集与反向明细穿透。

📸 界面预览

插件通过宿主 Slot 系统在三处无缝挂载 UI（前端为轻量无状态设计 lib/client.js）：侧边栏底部的 Usage Board 按钮一键唤出全屏大盘，会话详情页自带 Usage Tab 查看单会话账单。

会话页 "Usage" Tab —— 单会话账单与诊断

Session Usage Tab

树级聚合 KPI（输入 / 输出 = 思考 + 正文 / 缓存命中 / 成本）、Token 五桶构成 × 峰谷金额（零桶自动隐藏）、模型占比、请求效率与逐步明细。悬停行内 ? 可查看该桶峰 / 谷两档实付单价与金额对照（谷价 = 峰价 × ½）：

Peak/off-peak rate tooltip

全屏大盘 (Overlay) —— 总览

Dashboard overview

总量 / 成本 / 缓存命中率 KPI，DeepSeek 官方余额与烧钱速率预测（含夜间/阶梯价反事实节约），84 天用量热力图与 24 小时峰谷剖面。

全屏大盘 (Overlay) —— 会话归集与 Turns 明细

Dashboard turns table

最近会话树状归集、Turn × Step 级明细（TTFT / 耗时 / 五桶 Token / 峰谷金额），一键 CSV 导出。

挂载点一览

| 挂载 Slot | 位置 | 展示内容 |
| conversation.view | 会话详情页 "Usage" Tab | 当前会话树级聚合指标、Token 五桶构成 × 峰谷成本、模型占比、Step 级耗时瀑布 |
| sidebar.footer.action | 侧边栏底部操作区 | 大盘常驻快捷开闭图标 |
| shell.overlay | 全屏监控大盘 (Overlay) | 余额与可用天数、异常与反事实节约 KPI、84 天热力图、24 小时峰谷剖面、最近会话归集、Turns 明细表及 CSV 导出 |

✨ 核心特性

- ⚡ 零运行时依赖：基于 Node.js 22.5+ 原生 node:sqlite 构建，无任何 C++ 原生编译依赖及 Worker 进程负担。
- 🏛️ CQRS 架构：DSH 会话原文件作为只读真相源 (Write Model)，插件 SQLite 数据库作为可重建只读视图 (Read Model)，保障会话数据安全。
- 🚀 暖/热双层读模型：
- 暖层 (SQLite)：按脏分区增量汇总 daily_rollups / session_rollups，动态按最新价目表现算成本。
- 热层 (内存快照)：进程内不可变快照，单次请求下发渲染就绪的主帧；支持 rev 版本号协商，无变更秒回 unchanged。
- 🌲 Sub-agent DAG 聚合分析：支持多层子代理深度调用链聚合、Step 耗时瀑布图、Token 五桶构成分析。
- 💰 成本与余额洞察：支持 DeepSeek 官方余额透传、实时额度可用天数预测、夜间/阶梯价反事实节约计算。
- 🖥️ 三处无缝 UI 挂载：原生融入 DSH Web 控制台（会话页 Tab、侧边栏入口、全屏仪表盘）。

🚀 快速上手

1. 环境准备

- Node.js >= 22.5.0
- DSH (DeepSeek Harness)

2. 作为 DSH 插件启用

1. 克隆并构建（仓库不含 lib/ 产物，必须先构建）
git clone https://github.com/zhm20001/dsh-usage-board.git
cd dsh-usage-board
npm install
npm run build

2. 将插件注册至 DSH Web Profile
dsh plugin --profile web add "$(pwd)"

3. 启动 DSH Web 宿主
dsh --profile web --port 3099

启动后访问 http://127.0.0.1:3099 即可在界面中看到用量看板。首次启动会冷启动回溯扫描全部历史会话，之后增量跟进。

⚙️ 配置说明

余额查询配置

大盘的「账户余额」组件读取 DeepSeek 官方 GET /user/balance 接口：

1. 方式一：在 DSH 的「设置 → 模型」中填入 DEEPSEEK_API_KEY。
2. 方式二：写入 ~/.dsh/.credentials.yaml（权限需设置为 0600）： DEEPSEEK_API_KEY: sk-xxxxxxxxxxxxxxxxxxxxxxxx

注：未配置 Key 时余额卡片展示占位符，不影响其余本地统计功能。余额查询是本插件唯一的外网请求，其余处理均在纯本地执行。

数据与存储路径

| 类别 | 存储位置 | 说明 |
| 真相源 (Write Model) | ~/.dsh/sessions///session.jsonl.zstd | DSH 原始会话，只读 |
| 投影库 (Read Model) | ~/.dsh/data/usage.sqlite | 插件维护的 SQLite 索引与聚合库 |

💡 可安全重建：投影库可随时删除重建（建议先停用插件，再 rm ~/.dsh/data/usage.sqlite*）。下次启动 Backfill 会重扫全部历史会话重建投影；Write Model 永远不要删。

🔌 API & 嵌入式开发 (SDK)

HTTP API 端点

| 端点 | 方法 | 说明 |
| /api/usage-dashboard/snapshot?rev=N | GET | 获取大盘全量主帧。rev 命中当前版本时返回 {unchanged: true, revision} |
| /api/usage-dashboard/snapshot?refresh=1 | GET | 强制出网刷新一次 DeepSeek 实时余额 |
| /api/usage-dashboard/turns | GET | 检索 Turns 明细列表。参数：limit（默认 500、上限 500）、session_id、root_session_id（二者可同给取交集）、format=csv |

端点仅在注入 ctx.webServer 时注册（回环 same-origin 限定）；未注入时引擎作为库完整可用。

作为独立库调用

先 npm run build 产出 lib/，再以依赖方式引入本包（或直接指向 lib/index.js）：

import { createEngine } from 'dsh-usage-board'

// ctx 为结构化 HostContext，无需真实 Cordis 运行时 const engine = createEngine(ctx, { dbPath, sessionsRoot })

// 等待冷启动/增量 Backfill 就绪 await engine.ready

// 查询接口调用示例 const rollup = engine.query.getRollupBySession(rootSessionId) const heat = engine.query.getHeatmapData(12) const fails = engine.query.getTimelineAnomalies(100) const text = engine.query.loadTurnDetails({ sessionFilePath, turnIndex })

// 逆序平滑释放 await engine.dispose()

🛠️ 本地开发

构建 Node 端与 Client 端产物
npm run build

启动监听构建（配合 DSH 宿主的 Client HMR 热替换）
npm run dev

运行全量测试套件（基于 node --test，无外部依赖）
npm test

类型检查
npm run typecheck

📄 License

本项目基于 MIT License 开源。