usage — 订阅配额实时可见，不再焦虑

简介

订阅制 coding agent（Kimi For Coding、SuperGrok 等）都有用量配额，但官方查看方式要么打开网页控制台，要么靠记忆。真到 429 报错才发现配额用完了，体验很差。@piex-dev/usage 把可获得的订阅状态直接放到 pi 状态栏：Kimi/Grok/Zhipu/MiniMax/Codex 显示百分比 + 重置倒计时，Copilot 显示订阅档位与限流状态，DeepSeek/OpenRouter 显示余额；切换模型自动切换数据源。全自动，零操作。

Usage: 5-Hour:21%🕙3h45 7-Day:26%🕙6d17h                     Kimi / Zhipu / MiniMax
Usage: 7-Day:32%🕙4d3h                                      Grok
Usage: Copilot Pro
Usage: 5H:21%🕙3h45 7D:26%🕙6d17h Credits:12                 OpenAI Codex（Plus/Pro/Team）
Usage: 今¥7.81 7d¥26.91 30d¥148.46 充值余额:¥50,560.02      DeepSeek
Usage: 余额:$37.50                                          OpenRouter

技术原理

数据源：各 provider 都有官方（部分未公开但稳定）的用量接口，直接返回配额、重置时间或余额——Kimi GET https://api.kimi.com/coding/v1/usages（周配额 limit/used/remaining/resetTime + 滚动窗口限制）；Grok GET https://cli-chat-proxy.grok.com/v1/billing?format=credits（周 credits 百分比 + 周期起止）；Codex（openai-codex）GET https://chatgpt.com/backend-api/wham/usage（ChatGPT 订阅额度：账号主/次窗口 + 分特性窗口 + credits + 订阅档位，reset_at 为 epoch 秒）。凭据：通过 ctx.modelRegistry.getProviderAuth(provider) 拿 token——pi 会在 OAuth token 过期时自动刷新并写回，扩展不碰 refresh 流程，也不落盘任何密钥。

DeepSeek 官方计费：余额走官方接口（user/balance，API key 认证，返回总额/充值/赠送）；按日消费接口（platform.deepseek.com/api/v0/usage/cost）只接受浏览器登录 token——配置 DEEPSEEK_PLATFORM_TOKEN（DevTools 任意 api/v0 请求的 Authorization 头）后展示官方计费：今天 / 7 天 / 30 天 + 每日明细。token 为登录态（几天到几周），失效时状态栏显示 token失效 并降级为仅余额；未配置只显示余额。

Zhipu / MiniMax / OpenRouter（迁移自 cc-switch）：三个适配器从 cc-switch 的用量/余额查询迁移而来。Zhipu（zai-coding-cn / zai）走 GET {open.bigmodel.cn|api.z.ai}/api/monitor/usage/quota/limit，API key 认证（不加 Bearer 前缀），返回 5 小时 + 周窗口已用百分比；MiniMax（minimax-cn / minimax）走 GET https://api.minimaxi.com|io/v1/api/openplatform/coding_plan/remains，返回剩余百分比（反转展示）；两者格式与 Kimi 一致。OpenRouter（openrouter）走 GET https://openrouter.ai/api/v1/credits，展示 credits 余额（total − usage），低于 $10 黄 / $2 红。cc-switch 中的 SiliconFlow / StepFun / Novita 余额与火山方舟 AK/SK 签名配额在 pi 没有对应 provider，未迁移。

Copilot 的能力边界：GitHub Copilot 没有公开的用量余额接口（billing 接口需要 copilot scope 的 OAuth app，Copilot API 无 usage 端点）。官方 token 接口（copilot_internal/v2/token）能给出的只有：订阅档位（sku）与限流配额（limited_user_quotas，仅被限流时非空）。因此 Copilot 适配器展示档位徽标（Copilot Pro / Copilot Free(OSS)），被限流时显示红色 limited + 重置倒计时——这是接口极限，没有百分比余额。限流探测 best-effort 只读 pi 的 auth.json 中 GitHub OAuth token（遵循 PI_CODING_AGENT_DIR），只用于请求官方 token 接口，不写入也不记录 token。

按模型门控显示：session_start / model_select 时检查 model.provider，只有注册了 adapter 的 provider 才展示配额，其它模型立即清除状态栏，避免无关噪音。实时刷新三层：事件驱动（每次 turn_end 后立即刷新，用完即见）、后台轮询（默认 300s，USAGE_POLL_SECONDS 可调）、本地倒计时（30s 一次重算，只重渲染不请求 API）。

使用说明

安装

pi install npm:@piex-dev/usage

仓库源码：extensions/usage

用法

零操作：选中 Kimi / Grok / 智谱 / MiniMax / Codex / OpenRouter / DeepSeek / Copilot 模型即自动展示，切走自动清除。也可手动刷新并查看详情：

/usage    # 手动刷新 + 显示详情（各窗口用量/重置时间、会员等级、SKU、余额明细、Codex 订阅档位/分特性窗口）

配置

验证

pi -e ./extensions/usage/src/usage.ts -p "say hi" --no-session

实现方案

包路径：extensions/usage，src/adapters.ts（数据源适配器）+ src/usage.ts（事件编排）约 440 行。适配器架构：adapters.ts 定义 QuotaAdapter 接口（providerIds + fetch），内置 kimiAdapter 与 xaiAdapter；usage.ts 负责 model_select/session_start 门控、turn_end 触发刷新、轮询与倒计时 ticker、/usage 命令。新增 provider 只需实现接口，事件接线零改动。

<窗口标签>:<用量百分比>%🕙<重置倒计时>
# 用量 ≥ 90% 红色、≥ 70% 黄色
# 倒计时：6d17h（天级）/ 3h45（小时级）/ 45m（分钟级）

关键细节：getProviderAuth 返回的 header 已含 Bearer 前缀，统一剥离后由 adapter 拼接，避免 Bearer Bearer 双前缀（xAI 严格拒绝）；Grok 匹配 xai / xai-oauth 两个 provider id，token 按序 fallback；Codex 的 reset_at 按 epoch 秒解析，缺失时回退 reset_after_seconds，两者都没有则不伪造重置时间；Codex 只允许官方 https://chatgpt.com model/auth origin，自定义代理直接拒绝，避免转发代理凭据；接口字段可能随官方改版变化，解析失败显示 <label>: offline 并在下轮自动重试，Grok 月度接口为 best-effort，失败不影响主展示。

设计参考

核心取舍：账户级配额优先于 session 级消耗（配额用尽才是硬中断），状态栏常驻优先于命令查询（可感知才可预防）。

迭代记录

路线图

版本记录