dsh-usage-panel

简体中文 · English

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

主要功能

• 侧边栏常驻今日 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 根目录：

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

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

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

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

升级到最新版：

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

配置

所有配置项均可省略：

- 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

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

开发与验证

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

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

开源协议

MIT