pi-ai-usage — AI 额度监控插件

给 pi coding agent 用的额度/限流监控扩展，一条命令看清 Claude、GPT (Codex)、Grok (xAI)、CodeBuddy、Antigravity、DeepSeek 六个账号还剩多少。

Claude       5h          ███▏·   31% 2h30m   Antigravity  gemini week ████▉ ~100% 3d5h
             week        ████▉   87% 5d13h                gemini 5h   █████  100% 4h58m
GPT          week        █████  100% 6d6h                 cgpt week   █████  100% 6d23h
Grok         week        ███▊·   65% 1d15h                cgpt 5h     █████  100% 4h58m
                                              DeepSeek     balance            ¥10.28
CodeBuddy    cycle       ██▍··   48% 3d11h

百分比一律是剩余额度（你真正要看的数）：绿=充裕、黄=偏紧、红=快没了、灰=几乎没动过。终端够宽自动排两列，窄了自动变一列。

功能

• 常驻面板：编辑器上方的两列网格（上图），每次刷新自动更新；TUI 用主题配色，RPC/Zed 下自动降级为纯文本行。
• 6 种进度条样式：/quota style 预览，/quota style <名称> 一键切换并写入配置。
• /quota 命令（别名 /ai-usage）：全量报告、单个提供商、强制刷新、JSON 输出、本地账本、配置自检。
• 状态栏（默认关，statusLine.enabled: true 开启）：底部单行显示当前模型所属账号的剩余百分比。
• 阈值提醒：某个额度池剩余量跌破 25% / 10%（对应 thresholds 的 75/90 已用阈值）时弹一次通知，回升后重新武装。
• ai_usage 工具：模型自己可以调用，用于「哪个账号还有额度、该切到哪个模型」这类决策。
• 本地用量账本：记录每次请求的 token 与费用，在没有官方接口（或未配 CodeBuddy Cookie）时兜底，也可与官方数字互相印证。

各提供商的数据来源

提供商	来源	说明
Claude	GET api.anthropic.com/api/oauth/usage	Claude Code 自身 /usage 用的接口，需订阅版 OAuth 令牌（sk-ant-oat…）。纯 API Key 没有套餐窗口，会被忽略。
GPT	GET chatgpt.com/backend-api/wham/usage	返回套餐、滚动限流窗口与额外积分，需要 access token + chatgpt-account-id。
Grok	GET cli-chat-proxy.grok.com/v1/billing?format=credits	和官方 Grok CLI /usage 同一套 SuperGrok 周额度池，用 ~/.grok/auth.json 的 OIDC 令牌。没有 CLI 登录时回落 x-ratelimit-* 响应头 / 1-token 探针（那是 API 限流桶，不是套餐）。
Antigravity	POST cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary	Gemini 池 / Claude+GPT 池的 5 小时与每周额度。
DeepSeek	GET api.deepseek.com/user/balance	按量计费，看余额与赠金。
CodeBuddy	POST www.codebuddy.cn/billing/meter/get-enterprise-user-usage	控制台 /profile/usage 用的接口，返回当前计费周期已用 credits、总额度与重置时间。用浏览器会话 Cookie 鉴权（见下），没配 Cookie 时回落到本地账本。

凭证解析顺序：先问 pi 的 model registry（它会在锁内自动刷新过期的 OAuth 令牌），再回落到各家 CLI 自己的凭证文件（~/.claude/.credentials.json、~/.codex/auth.json、~/.grok/auth.json）。插件只读不写凭证，令牌过期时会直接提示去 /login，不会绕过 pi 私自刷新。

CodeBuddy 会话 Cookie

CodeBuddy CLI 的令牌不落盘，能读到额度的只有控制台自己那套 Cookie 鉴权。登录 https://www.codebuddy.cn/profile/usage，在 DevTools 里复制该请求的 Cookie 请求头（至少要有 session 和 session_2），四选一放进去：

# 1. 环境变量（优先级最高）
export CODEBUDDY_COOKIE='session=…; session_2=…'

# 2. 丢进数据目录，零配置生效
printf '%s' 'session=…; session_2=…' > ~/.pi/agent/ai-usage/codebuddy.cookie

// 3. 自定义路径      4. 直接写配置（明文，最不推荐）
{ "codebuddy": { "cookieFile": "~/.secrets/codebuddy.cookie", "cookie": null } }

只粘贴 session 的值（不带 session= 前缀）也认，会自动补全。/quota config 只显示「已配置 / 未配置」，不会回显 Cookie 内容。

企业 ID 会自动从 GET /console/accounts 查出来（同一个 Cookie），多企业账号可用 codebuddy.enterpriseId 钉死。个人版账号没有对应接口，会自动退回本地账本。

两个坑：请求必须带浏览器 User-Agent，否则网关直接 401（插件已内置）；Cookie 过期后会显示「未登录」，重新复制一份即可。

安装

# npm（推 vX.Y.Z tag 后由 GitHub Actions 发布）
pi install npm:pi-ai-usage

# 本地目录安装（开发中）
pi install /d/code/ai-usage

# 或在 ~/.pi/agent/settings.json 里加一行
{
  "extensions": ["D:/code/ai-usage"]
}

安装后重启 pi 或执行 /reload。

用法

/quota                 # 全部账号
/quota claude          # 只看某个账号（别名：anthropic gpt openai codex grok xai cb ag gemini ds）
/quota refresh         # 忽略缓存强制刷新
/quota -v              # 显示数据来源、读取时间、本地统计
/quota json            # 机器可读输出
/quota ledger          # 本地用量账本（按窗口 + 热门模型）
/quota config          # 当前配置与文件路径
/quota style [名称]     # 预览 / 切换进度条样式

进度条样式

/quota style 预览全部样式，/quota style dots 切换（写入全局配置）：

  eighths  █████  ███▌·  ██▎··  ▊····  ·····   半格方块，5 格 40 级精度（默认）
  shades   █████  ███▒░  ██▒░░  ▓░░░░  ░░░░░   深浅方块，经典 cli-progress 风格
  dots     ⣿⣿⣿⣿   ⣿⣿⣧·   ⣿⣧··   ⣇···   ····    盲文点阵，最紧凑
  line     ━━━━━━ ━━━━── ━━╸─── ━───── ──────  细线，低调不抢眼
  spark    █      ▆      ▄      ▂      ▁       单格刻度，只占 1 列
  none     —      —      —      —      —       不画条，只留百分比

默认 eighths 用半格方块做亚格填充：5 格就有 40 级精度，比 10 格整格条更短也更准。宽度可用 widget.barWidth 覆盖（默认 auto，跟随样式）。

没有引第三方进度条库，理由：progress-string 只有整格填充（18 行代码），cli-progress 是自己控制光标和定时器的有状态 stdout 渲染器、和 pi 的组件模型冲突，ink-progress-bar 只服务 Ink。这里复用的是它们（以及 tqdm/rich、sparkly）的字形词汇，实现是零依赖纯函数。

配置

全局 ~/.pi/agent/ai-usage.json，项目级 .pi/ai-usage.json（仅在受信任项目中生效，因为它能开启网络探针）。所有字段可选：

{
  "providers": {
    "claude": { "enabled": true },
    "codebuddy": { "enabled": false }
  },
  "cacheTtlSeconds": 120,          // 读数保鲜期
  "refreshIntervalMinutes": 10,    // 后台刷新间隔，0 关闭
  "thresholds": { "warn": 75, "critical": 90 },
  "widget": {
    "enabled": true,
    "placement": "aboveEditor",    // aboveEditor | belowEditor
    "columns": "auto",             // auto | 1 | 2
    "barStyle": "eighths",         // eighths | shades | dots | line | spark | none
    "barWidth": "auto"             // auto 或具体格数
  },
  "statusLine": { "enabled": false, "mode": "active" },  // active | all
  "notify": true,
  "grok": {
    "billing": true,               // 读 SuperGrok 周额度（需 Grok CLI 登录）
    "billingBaseUrl": "https://cli-chat-proxy.grok.com/v1",
    "probe": true,                 // 计费读不到时发 1-token 探针采集限流头
    "probeModel": "grok-4.6",
    "passiveMaxAgeMinutes": 20,    // 被动采集的响应头多久算新鲜
    "probeMinIntervalMinutes": 10  // 两次探针之间的最小间隔
  },
  "ledger": { "enabled": true, "retentionDays": 45 },
  "codebuddy": {
    "baseUrl": "https://www.codebuddy.cn",  // 国际站填 https://www.codebuddy.ai
    "cookie": null,                // 会话 Cookie，建议改用 cookieFile / 环境变量
    "cookieFile": null,            // 存放 Cookie 的文件路径，支持 ~
    "enterpriseId": null,          // 留空则自动从控制台查
    "dailyTokenLimit": null,       // 没有 Cookie 时，填上套餐额度让本地账本显示百分比
    "monthlyTokenLimit": null
  }
}

数据文件在 ~/.pi/agent/ai-usage/：cache.json（最近读数）、ledger.jsonl（用量账本，按 retentionDays 自动裁剪）、codebuddy.cookie（可选，CodeBuddy 会话 Cookie）。

开发

npm install
npm run typecheck
npm test                      # 纯逻辑单测
node scripts/smoke.ts         # 用本机真实凭证跑一遍全部适配器
pi -e ./src/index.ts -ne -p "/quota"

新增提供商：在 src/providers/ 加一个实现 QuotaProvider 的文件，注册进 src/providers/index.ts，并在 src/types.ts 的 PROVIDER_KEYS 里加上 key。