多供应商额度监控marisa-4219/deepseek-harness-quota-monitor

deepseek-harness-quota-monitor

DeepSeek Harness 多供应商额度监控插件。侧边栏实时卡片 + 「设置 → 插件」可视化配置，支持余额型（主动查询供应商 API）与限额型（本地滑动窗口计量）两类额度模型。

本版本适配 DSH 0.1.5-rc.1 起的插件接口：设置命名空间走 ctx.settings.installSection，/api 端点注册在 @deepseek-ai/dsh-client-connection 的精确 Fetch 路由上，配置卡片注册到「设置 → 插件 → 配置」的 settings.plugin.item。

特性

- 余额型：主动查询供应商余额/用量 API（地址 + API Key 引用 + JS 解析器），如 DeepSeek 官方 GET /user/balance
- 限额型：本地滑动窗口用量统计（5h / 7d / 1m 等，按 llm/stream 瀑布采集真实 token 用量，持久化到 $DSH_HOME/storages/quota-monitor-usage.jsonl），对照配额上限显示剩余
- 今日已用：自然日桶，跨重启保留；主数字含缓存（输入 + 输出 + 缓存读），附输入/输出/缓存分项与缓存命中率（3 位小数）
- 翻转卡片：点击今日已用区翻转 3D 卡片，查看输入/输出/缓存三线小时折线图（平滑曲线、峰值标注）
- 自动发现：有确定预设的官方供应商（DeepSeek、OpenCode GO 等）自动进入监控；无预设的自建网关不自动发现，需手动添加
- 逐个启用/禁用：自动发现与手动配置的每个供应商都可单独暂停/恢复监控（即时生效，配置保留）
- 预设一键添加：deepseek-official / opencode-go / new-api / sub2api 等整体方案，选中即填好 kind/url/解析器
- 金额按供应商实报：供应商在 usage 里返回价格才显示金额（无价格表、不推断），按模型明细展示
- 限流事件：模型请求被 429 限流时记录 retry-after，随快照返回
- 主题适配：明/暗色均使用产品 token，暗色下更贴近页面背景

UI 两处：侧边栏设置按钮上方的圆角卡片（sidebar.footer.action，点击刷新，5 分钟自动轮询）、「设置 → 插件 → 配置」中的额度监控卡片（settings.plugin.item，按设置命名空间 quota-monitor 分发）。

安装

从 npm registry 安装（推荐）：

dsh plugin --profile web add deepseek-harness-quota-monitor
然后重启 dsh web 服务

dsh plugin 会把参数转发给 pnpm，包名会从 npm registry 拉取。若本机 pnpm 不在 PATH 导致失败，可用 corepack 手动安装（效果相同，之后需手动把包名追加进 profile package.json 的 dsh.profile.bundles）：

corepack pnpm --dir "$DSH_HOME/profiles/web" add deepseek-harness-quota-monitor

开发模式（本地目录安装，改动即时生效）：

dsh plugin --profile web add

安装后 profile 的 package.json 应形如：

{
"dependencies": { "deepseek-harness-quota-monitor": "link:" },
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"deepseek-harness-quota-monitor"   // ← 必须在这一层里，否则插件不会被挂载
],
"patchReload": "live"
}
}
}

只安装了 node_modules 而 dsh.profile.bundles 里没有这个名字时，插件不会加载（bundle 层列表就是挂载清单）。这一条是升级后「插件失效」的常见原因之一。

快速开始（零配置）

不配置任何东西时：当前默认供应商（agent-default-model）如果是 deepseek-official，自动用内置余额解析器查询（key 取 DEEPSEEK_API_KEY 凭据引用）；其他已注册供应商自动走本地窗口计量（默认窗口 5h / 7d / 1m，无配额上限时只显示用量文本）。

配置

设置页「设置 → 插件 → 配置 → 额度监控」，或 profile 的 cordis.patch.yml，同一套 schema：

- insert:
- id: quota-monitor
name: deepseek-harness-quota-monitor
config:
refreshMs: 300000          # 小组件轮询间隔（毫秒）
cacheTtlMs: 60000          # 余额查询缓存
lowBalanceThreshold: 20    # 全局低额阈值
showTodayUsed: true
windows:                   # 全局默认窗口（限额型）
- { label: 5h, seconds: 18000 }
- { label: 7d, seconds: 604800 }
- { label: 1m, seconds: 2592000 }
providers:
opencode-go:
kind: windows
windows:
- { label: 5h, seconds: 18000, limitTokens: 100000 }
- { label: 7d, seconds: 604800, limitTokens: 1000000 }
行必须放在 insert: 块里（新行都是新增，不是覆盖）。插件自身 bundle 的 cordis.patch.yml 只插入不带 config 的空行，配置由设置页写入 $DSH_HOME/settings.yaml 的 quota-monitor 段。

每个供应商的字段

| 字段 | 含义 |
|---|---|
| kind | balance（查询 API）或 windows（本地统计） |
| url | 余额/用量 API 地址（windows 型可留空） |
| apiKeyEnv | API Key 的凭据引用（环境变量名），值存于 credentials 域，不进配置 |
| parse | JS 解析器，三选一：builtin / source / file |
| windows | 该供应商的限额窗口列表 |
| lowBalanceThreshold | 该供应商的低额阈值（留空继承全局） |
| currency | 金额显示币种（CNY/USD/…，默认 CNY；预设已带：DeepSeek=CNY、OpenCode GO=USD） |
| auth | bearer（默认，自动加 Bearer  前缀）或 raw（原样发送，如 new-api 的 System Access Token） |
| headers | 附加请求头（如 new-api 的 New-Api-User） |
| platform | 多平台网关的平台选择（sub2api 等） |

统计严格按供应商隔离：每个供应商的窗口用量、今日已用只计该供应商的调用，互不混算；金额币种取该供应商配置的 currency。

供应商预设（一键添加）

设置页「添加供应商」下拉选择后，kind / url / apiKeyEnv / parse 整套填充，只需填 API Key：

| 预设 | 类型 | 内容 |
|---|---|---|
| deepseek-official | 余额 | DeepSeek 官方余额 API + deepseek-balance 解析器 |
| opencode-go | 限额 | OpenCode GO 用量 API（5h/7d/1m 百分比）+ opencode-go-usage 解析器 |
| new-api | 余额 | one-api 系网关 GET /api/user/self（System Access Token，无 Bearer + New-Api-User 头，quota ÷ 500000 = 美元）+ new-api-self 解析器；URL 和用户 id 改成你自己的 |
| sub2api | 余额 | 订阅配额网关 GET /v1/usage（Bearer）+ sub2api-usage 解析器（remaining/unit）；高级：平台配额窗口用 sub2api-platform-quotas（1d/7d/1m 美元限额，配 platform 字段选平台） |

预设目录由 host 的 /api/quota-monitor/presets 提供（设置页拉取，同时返回系统内已注册供应商列表），扩展预设只改 host 一处。

添加供应商（系统优先）

设置页「添加供应商」下拉优先列出系统内已注册的 LLM 供应商（ctx.llm.listProviders() + listConfigurableProviders()，如 deepseek-official、pi-ai），配置键名自动使用其路由 id——本地流量（瀑布按路由 id 打标）必然归入同名卡片，杜绝手写名字不一致。选中后有预设的自动套预设（如 DeepSeek 余额查询），没有的建空白限额条目（本地计量）。预设方案（如 opencode-go）和手动自定义名保留为兜底（外部订阅账号等）。

自动发现

自动发现只覆盖有确定预设的供应商（官方 API，如 deepseek-official、opencode-go）：它们自动进入监控列表并按预设查询。没有预设的供应商不会被自动发现——自建/自定义网关（如 sub2api 自建站）无法匹配查询配置、也无法判断余额/限额类型，需要时请手动添加。手动配置的 providers 总是叠加监控。可在全局设置关闭自动发现；也可在设置页对任意供应商单独禁用/启用（disabledProviders 配置，{ [id]: true }），禁用的供应商不监控但配置保留。

JS 解析器三种形态

1. 内置预设（设置页下拉选择）：

| 预设 | 适用 | 响应结构 |
|---|---|---|
| deepseek-balance | DeepSeek 官方余额 | { is_available, balance_infos: [{ currency, total_balance, granted_balance, topped_up_balance }] } |
| opencode-go-usage | OpenCode GO 订阅（5h/7d/1m 三窗口百分比） | { usage: { rolling\|weekly\|monthly: { percent, resetsAt } } } |
| generic-balance | 通用余额：balance_infos 数组或扁平 { balance\|total_balance\|total\|amount, currency }（可包在 data 下） | 自动识别两种形态 |
| generic-percent-windows | 通用百分比窗口：{ usage: { : { percent, resetsAt } } }，任意窗口键 | 键名直用为 label，秒数按 label 匹配配置窗口 |
| new-api-self | new-api 网关 /api/user/self | { data: { quota, used_quota } }，单位 ÷ 500000 = 美元 |
| sub2api-usage | sub2api /v1/usage | { remaining\|quota.remaining\|balance, unit\|quota.unit } |
| sub2api-platform-quotas | sub2api 平台配额 | { data: [{ platform, _limit_usd, _usage_usd }] }，配 platform 字段选平台 |
2. 粘贴代码：parse: { source: '(raw) => ({ kind: "balance", balance: { currency: raw.balance_infos[0].currency, total: raw.balance_infos[0].total_balance } })' } —— host 端 new Function 执行，输入为查询响应的 JSON。

3. 脚本文件：parse: { file: 'C:/quota/opencode-go.js' } —— 文件默认导出一个 (raw) => snapshotPart 函数（ESM 或 CJS 均可）。

解析器返回约定（返回快照片段，未提供的字段省略）：

// 余额型
{ kind: 'balance', balance: { currency: 'CNY', total: '110.00', granted: '10.00', toppedUp: '100.00', available: true } }
// 限额型（只补配额上限；已用量恒来自本地计量）
{ kind: 'windows', windows: [ { label: '5h', limitTokens: 100000 } ] }

示例：带用量 API 的限额型供应商

假设某供应商用量 API GET https://api.xxx.com/v1/usage 返回：

{ "limits": [ { "period": "5h", "limit": 100000 }, { "period": "7d", "limit": 1000000 } ] }

配置：

providers:
xxx:
kind: windows
url: https://api.xxx.com/v1/usage
apiKeyEnv: XXX_API_KEY
parse:
source: '(raw) => ({ kind: "windows", windows: raw.limits.map(w => ({ label: w.period, limitTokens: w.limit })) })'

侧边栏显示「5h 12k/100k · 7d 210k/1M」，进度条着色按 70%/90% 阈值。

快照模型

GET /api/quota-monitor 返回当前（默认）供应商与全部已配置供应商的快照数组：

{
provider: string,
kind: 'balance' | 'windows',
balance?: { currency, total, granted?, toppedUp?, available },
windows?: [{ label, seconds, limitTokens?, limitRequests?, percent?, resetsAt?, usedTokens, usedRequests }],
todayUsed?: { tokens, requests, cacheRatio?, cost?, byModel?, series? },  // DSH 本地自然日用量；cost 仅当供应商 usage 返回价格时存在；series 为 24 小时桶（t/i/o/c）供折线图
lastRateLimit?: { at, retryAfterMs },
fetchedAt: number,
error?: string                   // no-key | no-url | network | http- | bad-json | parse:
}

接口与适配要点

host 端点都挂在经认证的 /api 通道上——/api 前缀整体由 @deepseek-ai/dsh-client-connection 接管，先做 Host/Origin 信任检查与浏览器会话认证，再分发。因此插件端点用 ctx.connection.fetch.register 注册为精确 Fetch 路由：

| 路由 | 方法 | 作用 |
|---|---|---|
| /api/quota-monitor | GET | 快照数组，?provider= 只取一个 |
| /api/quota-monitor/presets | GET | 供应商预设 + 系统内已注册 LLM 供应商 |
| /api/quota-monitor/settings | GET | 只读的自动发现供应商列表（配置读写走 Remote，见下） |
| /api/quota-monitor/profile-provider | POST | 从 profile patch（base 层）移除供应商 |

配置读写不走自有端点，而走 DSH 自带的 Remote 设置通道：ctx.remote.settings.describe() 读、ctx.remote.settings.mutate(ns, ops, revision) 写（带 revision 冲突检测，过期写入被拒绝而不是覆盖）。API Key 同理走 ctx.remote.credentials.{describe,set,unset}，明文永不回传。

旧的 ctx.webServer.register({ path: '/api/...' }) 写法会被 connection 的 /api 前缀路由遮蔽并返回 401——这是升级后端点全部 401 的原因。

profile patch 的移除是逐字编辑：js-yaml 能读 !!js 表达式但不能写出该标签，整文件 load → dump 会把用户 patch 里的 !!js 表达式改写成普通映射。所以这里用 js-yaml 判断「这一行确实声明了该供应商」，再按缩进从原文删掉那一个条目的字节，其余行保持逐字不变；上游 providers: / config: 变空时一并清理，避免留下会解析成 null 的空键。

开发与测试

目录结构：

deepseek-harness-quota-monitor/
├── lib/
│   ├── index.js          # host 端：计量、查询、解析器、预设、设置与路由
│   ├── patch.js          # profile patch 的逐字编辑（无 harness 依赖，可单测）
│   └── client.js         # client 端：侧边栏 widget + 插件配置卡片（CJS bundle）
├── cordis.patch.yml      # 默认挂载条目
├── test/
│   ├── verify-quota-e2e.mjs      # host 端到端：设置命名空间注册、Fetch 路由、快照、瀑布计量、patch 移除
│   └── verify-patch-rewrite.mjs  # profile patch 逐字编辑（嵌套 insert / 裸行 / !!js 保留 / 幂等）
└── package.json

运行测试（无需网络与凭据，js-yaml 从 DSH 安装目录解析）：

cd test
node verify-quota-e2e.mjs
node verify-patch-rewrite.mjs

验证真实 DSH 挂载（隔离 home，不影响正在运行的 GUI）：

1. 复制一份 profile 清单到临时 home，bundles 里保留本插件
2. 用另一个端口启动，确认插件加载与端点可用
DSH_HOME= dsh --profile web --port 3199 --no-open
3. 浏览器打开打印出的带 token URL：侧边栏出现额度卡片
设置 → 插件 → 配置 出现「额度监控」卡片

已知边界

- 本地计量只统计经过 DSH 的请求（其他工具用同一 key 的用量不计入）
- 响应头级配额（x-ratelimit-*）目前拿不到（llm 抽象层不暴露），限流信息来自 429 错误
- 侧边栏折叠态只显示第一个（默认）供应商的紧迫信息
- 余额查询结果有 60s 缓存（cacheTtlMs），修改配置后最多 60s 内生效
- 配置卡片内的编辑是暂存式：改完点「保存」才写入；供应商启用/禁用与删除是即时写入

友情链接

- LINUX DO —— 技术社区

License

MIT