前言¶
DeepSeek Harness (DSH) 的核心理念是「一切皆插件」。在使用 DSH 进行智能体编排或日常开发时，跟踪 Token 消耗、计算成本以及诊断性能异常是常见需求。dsh-usage-board 是一个为此场景设计的客户端插件，旨在提供实时的用量监控与成本核算。
这是什么¶
dsh-usage-board 是一个专为 DSH 设计的用量与成本可视化看板插件，由 zhm20001 维护。它解决了在长时间运行或复杂调用链中难以直观查看资源消耗的问题，通过可视化界面将数据呈现出来。
核心功能¶
该插件具备以下核心能力：
- 实时监控：实时捕获会话内的 Token 消耗、Step 耗时和异常指标。
- 历史回溯：支持冷启动增量回溯历史全量会话。
- 关系分析：按 Sub-agent DAG 调用关系进行树状归集与反向明细穿透。
- 零依赖架构：基于 Node.js 22.5+ 原生
node:sqlite构建，无运行时依赖。 - CQRS 架构：采用 CQRS 架构，以 DSH 会话文件为只读真相源，以 SQLite 数据库为可重建只读视图。
- 双层读模型：支持暖/热双层读模型，利用 SQLite 和内存快照提升读取性能。
- 成本洞察：支持 DeepSeek 官方余额透传与实时额度预测，并包含夜间/阶梯价反事实节约计算。
- UI 挂载：三处无缝 UI 挂载，分别位于会话页 Tab、侧栏入口和全屏仪表盘。
安装与启用¶
启用该插件需要满足环境要求并执行安装命令。
-
环境准备
确保安装了 Node.js >= 22.5.0。 -
注册插件
在插件目录下执行以下命令将插件注册至 DSH Web Profile：
dsh plugin --profile web add "$(pwd)"
- 启动宿主
启动 DSH Web 宿主：
dsh --profile web --port 3099
启动后访问 `http://127.0.0.1:3099` 即可使用该功能。首次启动会进行冷启动回溯，扫描全部历史会话。
配置与数据¶
插件在运行时需要关注配置项与数据存储路径。
余额查询配置¶
若需查看 DeepSeek 官方余额与实时额度预测，需配置 API Key：
* 方式一：在 DSH 的「设置 → 模型」中填入 DEEPSEEK_API_KEY。
* 方式二：在 ~/.dsh/.credentials.yaml 中写入 Key（权限需设置为 0600）。
注：余额查询是本插件唯一的外网请求，其余处理均在本地执行。未配置 Key 时余额卡片仅展示占位符，不影响本地统计功能。
数据存储路径¶
插件维护两处关键数据路径：
* 真相源：~/.dsh/sessions/<projectKey>/<sessionId>/session.jsonl.zstd。这是 DSH 原始会话文件，只读，不可删除。
* 投影库：~/.dsh/data/usage.sqlite。这是插件维护的 SQLite 索引与聚合库，可安全重建。
使用与 API¶
插件提供了查询接口，可用于嵌入式开发或脚本化操作。
查询接口¶
通过 createEngine 创建引擎实例后，可调用以下查询接口：
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)
// 其他查询...
结语¶
dsh-usage-board 通过零依赖架构和 CQRS 设计，为 DSH 用户提供了轻量级且可靠的用量监控方案。对于需要精细化控制成本和诊断性能的开发者，这是一个实用的工具。
- 插件主页：https://github.com/zhm20001/dsh-usage-board
- 生态目录：https://www.skillhub.cn/plugins/zhm20001/dsh-usage-board
