dsh-usage-board
Usage & cost dashboard plugin for DSH (DeepSeek Harness): per-session token metrics, 84-day heatmap, balance burn-down, and detail table with CSV export.
The plugin will be installed here. Keep web if you are unsure.
npx -y @deepseek-ai/dsh plugin --profile web add github:zhm20001/dsh-usage-board#3b897ea91c31e2f4b236cbe70738d070d8512755
Usage Board is published as dsh-usage-board and currently resolves to version 0.1.0. The Hub verifies its manifest and preserves the exact installation source for reproducible installs.
DSH（DeepSeek Harness / Cordis）的用量·成本·诊断面板插件：实时采集 token/耗时/错误指标，冷启动回溯全部历史会话，按 Sub-agent DAG 聚合，需要时按指针回查原文。
node:sqlite。npm install # 只装 devDependencies（typescript 与 @types/node）
npm test # node --test，全量测试（无网络、无外部进程）
npm run typecheck
作为库嵌入（结构化 HostContext，无需真实 Cordis 运行时）：
import { createEngine } from './src/index.ts'
const engine = createEngine(ctx, { dbPath, sessionsRoot })
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() // 逆序清理，幂等
第二阶段在查询之上加预处理层：
daily_rollups / session_rollups，按脏分区从 turns 整段重算；金额永不落库，由价目表现算。get() 拿到渲染就绪的全部汇总——KPI 总账、84 天热力图、24 小时峰谷剖面、byModel、最近会话、异常计数、计价信息（含 nextSwitchEpochMs 与反事实省额）、余额块。data_revision；UI 携带旧 revision 轮询，无新数据时端点应答 body 级 unchanged，不触发重渲染。注入 ctx.webServer 时自动注册端点（回环 same-origin 限定；未注入时引擎作为库完整可用）：
| 端点 | 语义 |
|---|---|
GET /api/usage-dashboard/snapshot?rev=N | rev 命中 → {unchanged:true, revision}；否则全量主帧（含 snapshotVersion） |
GET /api/usage-dashboard/snapshot?refresh=1 | 余额透传：旁路 TTL 强制出网一次，必答全量新余额块 |
GET /api/usage-dashboard/turns?limit=N&format=csv | 最近 turn 详情帧（垃圾值/<1 回默认 500、>500 钳到 500）；行含 toolMs（按 step 聚合工具时长，无调用为 null）与 delegationDepth（子代理深度）；format=csv 出 CSV（列序 = JSON 字段序） |
GET /api/usage-dashboard/turns?session_id=&root_session_id= | 按会话过滤（可选，可同给 = 交集）：session_id 精确匹配该会话、root_session_id 匹配整棵会话树；垃圾值视同缺省 → 全库最近 N 条 |
浏览器半（src/client/ → lib/client.js）经宿主 slot 系统挂载，只消费上表端点，不碰文件系统与 SQLite：
conversation.view —— 会话页 "Usage" Tab（该会话树根聚合：KPI、五桶构成、模型占比、step 耗时瀑布）；sidebar.footer.action —— 侧栏底栏图标按钮，开合大盘；shell.overlay —— 全屏大盘（余额卡 + 可烧天数、异常与反事实、84 天热力图、byModel、24 小时剖面、最近会话、详情表 + Export CSV）。src/client/store/，纯函数、node --test 直测）：手动刷新、无自动轮询——快照 ?rev= 条件请求（unchanged 应答不重渲染），?refresh=1 强制余额出网；turns 懒加载（?limit=&session_id=&root_session_id=，CSV 同端点）；投影形选择器把真实帧投影成组件消费形状。npm run build # tsdown 双产物：lib/index.js（node 半）+ lib/client.js（浏览器半）
npm run dev # tsdown --watch（配合宿主 client-hmr 热替换）
dsh plugin --profile web add "$(pwd)" # 安装到 web profile（pnpm link + bundle 清单登记）
dsh --profile web --port 3099 # 起宿主；UI 打开 http://127.0.0.1:3099
src/client/** → watch 重编 lib/client.js → 宿主 stat-poll 触发 clientModules.rebuilt → SSE 推浏览器热替换；生产态 dsh web 按 rev（bundle sha256 前 12 位）服务 /plugins/<id>/client.js?rev=，内容变更即换址免缓存。大盘的余额卡读取 DeepSeek 官方 GET /user/balance，key 复用宿主凭证：在「设置 → 模型」里配置 DEEPSEEK_API_KEY，或写入 ~/.dsh/.credentials.yaml（文件权限须 0600，顶层 DEEPSEEK_API_KEY: <key>）。未配置时余额块显示占位态，其余功能不受影响（引擎中唯一出网组件就是余额服务，其余一切纯本地）。
| 内容 | 路径 |
|---|---|
| 投影库（Read Model） | ~/.dsh/data/usage.sqlite（0600，WAL） |
| 真相源（Write Model，只读） | ~/.dsh/sessions/<projectKey>/<sessionId>/session.jsonl.zstd |
投影库可随时删除（先停用插件，再 rm ~/.dsh/data/usage.sqlite*）。下次启动 backfill 会重扫全部历史会话重建投影；正在进行的活会话由事件总线继续增量补齐。Write Model 永远不要删。