yancf666/dsh-usage-panel

dsh-usage-panel

简体中文 · English

一个为 DSH 打造的本地用量观测插件。
它会在 Web 侧边栏加入精简的 Token / 余额卡片，点击后打开响应式仪表盘，集中查看趋势、
缓存效率、供应商状态和调用明细。

版本
Node
协议

DSH 用量观测台面板

主要功能

- 侧边栏常驻今日 Token 与主要余额，随时一眼查看。
- 支持 1 小时、24 小时、今天、7 天、30 天以及指定日期。
- Token 趋势按输入、缓存读取和输出三层展示，并提供总量折线、平均线、峰值、最近非零值和
更合理的刻度；缓存写入继续计入输入总量和导出数据，但不再单独占用面板指标。
- 提供上一时段对比、缓存命中率、会话/模型/提供商数量、调用次数和平均用量。
- 可搜索的模型/提供商排行，以及支持全量搜索、展开和分页的调用明细。
- 按当前时间范围完整导出 CSV 或 JSON。
- 支持 DeepSeek 官方余额、OpenAI 风格网关累计消耗，以及自定义 JSON 余额源。
- 余额并行查询，支持超时、瞬时错误重试、单飞缓存、后台更新和上次成功值兜底。
- 60 天持久化账本与历史会话日志回填，重启不丢数、不重复计数。
- 自适应浅色/深色主题和窄屏，无需前端构建步骤。

环境要求

- 带 Web profile 和 webServer 服务的 DSH。
- Node.js 22 或更高版本。推荐 Node.js 24+，因为它可以解码历史 .jsonl.zstd
会话日志；较旧的受支持版本仍能统计实时事件并恢复插件账本。

从 GitHub 安装

进入同时包含 node_modules/ 和 web/ 的 DSH profile 根目录：

~~~sh
cd ~/.dsh/profiles
npm install github:yancf666/dsh-usage-panel
~~~

在 profile patch（通常是 ~/.dsh/profiles/web/cordis.patch.yml）中挂载插件：

~~~yaml
- insert:
- id: usage-panel
name: 'dsh-usage-panel'
inject: [webServer]
config: {}
~~~

重启 dsh web，侧边栏底部就会出现用量卡片。

升级到最新版：

~~~sh
cd ~/.dsh/profiles
npm install github:yancf666/dsh-usage-panel#main
~~~

配置

所有配置项均可省略：

~~~yaml
- insert:
- id: usage-panel
name: 'dsh-usage-panel'
inject: [webServer]
config:
DeepSeek 官方余额
balanceKeyEnv: DEEPSEEK_API_KEY
balanceUrl: https://api.deepseek.com/user/balance

稳定性
balanceCacheMs: 300000
balanceTimeoutMs: 15000
balanceRetries: 1

自定义 JSON 余额 / 累计消耗接口
balanceSources:
- id: team-credit
label: 团队额度
url: https://gateway.example.com/api/balance
keyEnv: TEAM_GATEWAY_KEY
valuePath: data.balance
currency: CNY
scale: 1
kind: balance
~~~

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| balanceKeyEnv | DEEPSEEK_API_KEY | DeepSeek Key 的环境变量或 .credentials.yaml 键名。 |
| balanceUrl | DeepSeek 官方接口 | 覆盖官方余额接口。 |
| balanceCacheMs | 300000 | 成功结果缓存时间，限制为 5 秒到 1 小时。 |
| balanceTimeoutMs | 15000 | 单次请求超时，限制为 1 到 30 秒。 |
| balanceRetries | 1 | 超时、HTTP 408/429、5xx 的重试次数，最多 2 次。 |
| balanceSources | [] | 额外的 Bearer 鉴权 JSON 接口。 |

每个自定义余额源支持 id、label、url、keyEnv、valuePath（点路径）、currency、
scale 和 kind: balance / usage。

插件还会读取 ~/.dsh/settings.yaml 中的供应商。对于 OpenAI 风格网关，会尝试
BASE_URL/dashboard/billing/usage；许多网关只在这里开放累计消耗，剩余额度仍需登录
网关网页查看。

数据与安全

- API Key 只在 DSH Host 端读取，永远不会返回浏览器。
- 无法识别的供应商响应只报告字段结构，不会把响应值复制到错误信息中。
- 统计与导出路由默认只接受环回 Host；DSH 明确绑定 0.0.0.0 时，也允许本机自己的
局域网地址。
- 用量账本只保存在 ~/.dsh/storages/usage-panel.json。
- CSV / JSON 导出包含会话标识，分享前请先检查文件内容。

HTTP API

~~~text
GET /usage-panel/summary?range=1h|24h|today|7d|30d
GET /usage-panel/summary?date=YYYY-MM-DD
GET /usage-panel/summary?...&eventPage=1&eventSize=30
GET /usage-panel/summary?...&q=模型或会话
GET /usage-panel/summary?...&refreshBalance=1

GET /usage-panel/export?range=today&format=csv
GET /usage-panel/export?date=YYYY-MM-DD&format=json
~~~

开发与验证

~~~sh
npm install
npm test
npm run check
npm pack --dry-run
~~~

Host 模块位于 lib/index.js，浏览器模块位于 lib/client.js。浏览器端是手写 React
factory bundle，因此不需要 bundler。

开源协议

MIT