dsh-usage-board

Readme

# dsh-usage-board

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

[![Node Version](https://img.shields.io/badge/Node.js-%E2%89%A522.5-339933?logo=node.js)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Zero Dependency](https://img.shields.io/badge/runtime_deps-0-brightgreen.svg)]()

**简体中文** | [English](README.en.md)

---

## 📖 简介

`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](assets/session-usage-tab.png)

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

![Peak/off-peak rate tooltip](assets/session-usage-tooltip.png)

### 全屏大盘 (Overlay) —— 总览

![Dashboard overview](assets/dashboard-overlay.png)

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

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

![Dashboard turns table](assets/dashboard-turns-table.png)

最近会话树状归集、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 插件启用

```bash
# 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`）：
   ```yaml
   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`）：

```ts
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()
```

---

## 🛠️ 本地开发

```bash
# 构建 Node 端与 Client 端产物
npm run build

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

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

# 类型检查
npm run typecheck
```

---

## 📄 License

本项目基于 [MIT License](LICENSE) 开源。