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 接口：

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

   DEEPSEEK_API_KEY: sk-xxxxxxxxxxxxxxxxxxxxxxxx
   

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

数据与存储路径

类别	存储位置	说明
真相源 (Write Model)	~/.dsh/sessions/<projectKey>/<sessionId>/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 开源。