额度计量条 Paprikas/dsh-usage-meter

dsh-usage-meter

DeepSeek Harness 的套餐与额度计量插件：侧边栏底部、头像下方多出一行，显示你的 Codex 速率限制窗口、Google Gemini（AI Pro）配额、OpenRouter 余额和 DeepSeek 钱包——悬停一下就能看到完整信息。

它专门回答那些 harness 从不展示配额的服商：

| 服务商 | 来源 | 显示内容 |
| OpenAI Codex | GET https://chatgpt.com/backend-api/wham/usage | 两个套餐窗口（5 小时和每周）的剩余份额、重置倒计时、套餐名称、额外限制重置次数，以及当前超出配额的模型 |
| Google Gemini (AI Pro) | POST https://daily-cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels | Gemini 模型（Flash 和 Pro）以及第三方订阅模型（Claude 和 GPT-OSS）的剩余配额百分比和重置倒计时 |
| OpenRouter | GET https://openrouter.ai/api/v1/credits | 预付余额占总量的比例 |
| DeepSeek | harness 自带的 deepseekAccount 服务 | 充值钱包和每个赠送的奖励钱包 |

harness 用同一份 OAuth 授权跟 Codex 后端通信，但只能从响应里得知配额失败——它从不询问还剩多少。答案藏在 Codex 后端自己的用量端点里，本插件用凭据服务已持有的访问 token 去调用它。

你会看到什么

侧边栏底部、Settings 正上方的一整行：

[openai] 95% [openrouter] $8.73 [deepseek] ¥1.27

- OpenAI 标记显示的是 Codex 五小时窗口剩余的份额——也就是真正会拦住你下一个请求的那个窗口。后端报告的是已用份额，所以这一行读的是补数：刚重置完它显示 95%，而不是 5%；
- OpenRouter 和 DeepSeek 标记带着各自的余额。这三个标记是 OpenAI、OpenRouter 和 DeepSeek 的 Simple Icons 路径——shell 自带的图标集里没有任何品牌字形，手绘一个 logo 猜测比真货更糟。它们是填充形状，而不是 shell 的描边轮廓，这也是所有品牌标记在任何地方的标准画法，并且它们取 currentColor，所以会跟随主题。三个都是同样的中性灰：图标只说明一个数字属于哪个服务商，而状态颜色——平静、警告、耗尽——留在面板的条形上，那里才是窗口本身绘制的地方；
- DeepSeek 的数字是余额：Platform 保留两种钱包，充值钱包是付费充值落进去的地方，赠送奖励钱包是另一种，很多账户只在其中一种里有钱。这一行显示第一个真正有余额的钱包，面板则按名称拆分两种——列出空的那个，才能告诉你手里的钱是赠送来的。
- 把侧边栏折叠成 rail 会保留圆环和百分比，去掉两个余额在 36 像素里放不下；
- 如果什么都没配置，这一行就不画——Settings 旁边空着一行配额，什么也说明不了。

悬停在这一行上会打开面板，里面什么都有，分成三组，每组一样大——每个服务商一组，标题相同、行也相同，谁也不比谁更突出：

- OpenAI Codex：按名字列出 5h 和 weekly，各自带进度条、剩余量，以及 Resets 10/01, 08:37 PM · in 2 d 22 h——先给墙上时钟的时刻，因为那才是你能拿来安排计划的，紧接着是距离现在还有多久；另外还有额外限额重置的次数，以及只有在真的发生时，才显示限额已触达；
- OpenRouter credits：总额度里还剩多少，以及已经花了多少；
- DeepSeek balance：每个钱包都用自己的名字列出，空的也算。

刷新控件只放在面板底部一次，挨着时间戳。没有套餐名，也没有彩色指示灯：这两样都给不了你能据以行动的信息，而且都会让某个服务商看起来像是面板的主角。

点击会把面板钉住不关，这样你就能把指针移开；按 Escape 或在外面点一下，它又会关上。

选择显示什么

插件列在 Plugins 面板的 Installed 分区里：打开它就进入插件的配置页（plugins.bundle.config）——数字以可读的大小显示，每个服务商一个开关，还有一个刷新控件。

你关掉的服务商根本不会被读取：宿主不再请求它，不再解析它的凭据，也不会为它报错。选择会经由宿主写入 ~/.dsh/usage-meter.json，所以重启后依然保留，侧边栏那一行会在切换时重画，而不是等下一次轮询。

如果你更想让某个服务商一开始就是关的，这一行的默认值在配置档补丁里：

- insert:
- id: usage-meter
name: 'dsh-usage-meter'
visible:
openrouter: false

把所有服务商都关掉，侧边栏那一行会直接隐藏——配置页上会说明这一点，你也就是在那里把某个重新打开。

这些数字从哪来

一切都从 harness 自己的凭据存储里读取——插件从不打开 ~/.codex/auth.json：

- Codex 的授权是 llm-pi-ai/openai-codex 这条凭据记录（任何以 /openai-codex 结尾的 owner 前缀都接受，所以改了名的 owner 也照样能解析）；
- 当存着的访问 token 过期——或者返回 401——插件会拿 refresh token 去 https://auth.openai.com/oauth/token 换，并把新的授权写回去，这样 harness 服务商也能看到；
- OpenRouter 的 key 就是 Models 设置页已经写好的那个 OPENROUTER_API_KEY 引用；
- DeepSeek 走 ctx.deepseekAccount，所以插件从不碰授权：登录状态和凭据刷新都由 harness 管。所有可能不可用的情况——没有账号服务、没人登录、空的余额读取失败时显示普通的「无内容可显示」，而真正出错的读取会如实上报。平台返回的 normal_wallets 和 bonus_wallets 是字符串，各自带一套小数语法；插件把两者都解析成数字，绝不会把读取失败变成余额为零。

平台收到的是发起请求的 UI，不是宿主进程：浏览器每次读取都会发送当前语言区域和相对 UTC 的东向偏移，因为它们会成为 x-client-locale 和 x-client-timezone-offset 请求头。

钱包余额的变化尺度是一笔消费，不是一分钟，所以最多每五分钟重读一次，而限流窗口每分钟刷新。强制刷新面板会绕过窗口缓存，但绕不过钱包自身的缓存。

接线

把包加入配置档的依赖和 bundle 列表：

// package.json
"dependencies": {
"dsh-usage-meter": "link:../dsh-usage-meter"
},
"dsh": {
"profile": {
"bundles": [
"dsh-usage-meter"
]
}
}

bundle 层会自动加载插件的 cordis.patch.yml。默认可见性也可以在配置档的 cordis.patch.yml 里覆盖：

- insert:
- id: usage-meter
name: 'dsh-usage-meter'
visible:
openrouter: false

端点

宿主在共享的 /api 通道上拥有两个精确的 Fetch 路由：

- POST /api/usage-meter/usage —— 快照，缓存 60s；{ force: true } 绕过窗口缓存
- POST /api/usage-meter/refresh —— 总是发出请求
- POST /api/usage-meter/preferences —— 写入服务商可见性，并返回完整的选择结果

快照长这样：

{
"codex": {
"plan": "plus",
"limitReached": true,
"windows": [
{ "key": "primary", "usedPercent": 100, "windowSeconds": 18000, "resetAt": 1790861660000 },
{ "key": "secondary", "usedPercent": 66, "windowSeconds": 604800, "resetAt": 1791110373000 }
],
"resetsAvailable": 4,
"credits": { "hasCredits": false, "unlimited": false, "balance": 0 },
"unreachableModels": ["gpt-6-astra"]
},
"openrouter": { "totalCredits": 60, "totalUsage": 51.272380757, "remaining": 8.727619243 },
"deepseek": {
"wallets": [{ "currency": "USD", "balance": 0 }],
"bonusWallets": [{ "currency": "USD", "balance": 0 }, { "currency": "CNY", "balance": 1.26760384 }]
},
"deepseekFetchedAt": 1790860490000,
"errors": { "codex": null, "openrouter": null, "deepseek": null },
"visible": { "codex": true, "openrouter": true, "deepseek": true },
"fetchedAt": 1790860490000
}

三个服务商在结构上互相独立，所以一个失败绝不会遮住其他服务商的数字：每个都在 errors 里有自己的条目。

状态与面包屑

~/.dsh/usage-meter.json 保存最后一次成功的快照——这样离线启动时仍能显示数字，而不是空行——以及激活面包屑 imported → applied → injected → registered，它们是从终端诊断配置档变更时，先看这里。

测试

node test/host.mjs # routes, protocol, normalization, refresh, cache, DeepSeek
node --import ./test/register.mjs test/client.mjs # rendering, rail variant, hover, pinning, gating, helpers

host 测试导入模块时会用临时的 DSH_HOME 和打桩的 globalThis.fetch，所以不会有任何数据离开本机。client 测试在 jsdom 里用真实的 React 和真实的 DSH 原语把随包发布的 loader bundle 跑起来，所以测的是随包发布的代码本身，而不是副本。