dsh-usage-board
> DeepSeek Harness (DSH / Cordis) 的全功能用量监控、成本核算与诊断大盘插件。
简体中文 | English
📖 简介
dsh-usage-board 是专为 DSH (DeepSeek Harness) 设计的用量与成本可视化看板插件。
插件能实时捕获会话内的 Token 消耗、Step 耗时和异常指标，支持冷启动增量回溯历史全量会话，并按 Sub-agent DAG 调用关系进行树状归集与反向明细穿透。
📸 界面预览
插件通过宿主 Slot 系统在三处无缝挂载 UI（前端为轻量无状态设计 lib/client.js）：侧边栏底部的 Usage Board 按钮一键唤出全屏大盘，会话详情页自带 Usage Tab 查看单会话账单。
会话页 "Usage" Tab —— 单会话账单与诊断
树级聚合 KPI（输入 / 输出 = 思考 + 正文 / 缓存命中 / 成本）、Token 五桶构成 × 峰谷金额（零桶自动隐藏）、模型占比、请求效率与逐步明细。悬停行内 ? 可查看该桶峰 / 谷两档实付单价与金额对照（谷价 = 峰价 × ½）：
全屏大盘 (Overlay) —— 总览
总量 / 成本 / 缓存命中率 KPI，DeepSeek 官方余额与烧钱速率预测（含夜间/阶梯价反事实节约），84 天用量热力图与 24 小时峰谷剖面。
全屏大盘 (Overlay) —— 会话归集与 Turns 明细
最近会话树状归集、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 接口：
- 方式一：在 DSH 的「设置 → 模型」中填入
DEEPSEEK_API_KEY。 - 方式二：写入
~/.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 开源。
