pi-usage

English | 简体中文

一个 pi 扩展：查看各订阅账号的余额与用量窗口——footer 状态行常显当前账号，/usage 卡片查看全部明细。查询方法参考 CodexBar，凭据直接复用 pi 统一存储的 auth.json，不读取任何第三方凭据文件。

0.3.0

• 新增 Kimi Coding、MiniMax（全球/CN）、Moonshot AI（全球/CN）、OpenCode Go、Vercel AI Gateway 适配器。
• OpenRouter 改用 /api/v1/key，Workspace API key 读取 key 限额和 usage，不再把 /credits 错当账户钱包余额。
• 修复 Claude extra usage：Anthropic 返回的是美分，并补充 Opus/Sonnet 等可选窗口。
• 增强 Codex、GitHub Copilot、DeepSeek 响应解析。
• 暂未实现 x.ai consumer billing、Fireworks 组织账单和 Baseten 组织账单。

效果

footer 状态行（默认模式）跟随当前模型，显示其额度窗口、本次会话消耗和 7 天迷你趋势：

Codex 5h 13% used · weekly 2% used · session 10.0k tok $0.020 · 7d ▁▁▁▁▁█▂ 66k

/usage 向会话流打印一张卡片（自定义条目渲染——非弹窗、不抢焦点）：

 Usage · 02:15

 ● Codex (Plus)
   5h      ░░░░░░░░░░   0% used · resets in 4h 54m
   weekly  ░░░░░░░░░░   2% used · resets in 6d 17h
 ○ GLM
   Balance ¥21.46  recharged ¥118.00 · spent ¥96.54
 ○ DeepSeek
   Balance ¥38.48
 Last 30 days ────────────────────────────
 tokens ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▂▆███ 66k
   gpt-5.6-luna  █████████████████░░░ 70%  34k
   gpt-5.6-terra █████░░░░░░░░░░░░░░░ 21%  10k

仪表盘默认打开 Charts 视图（盲文时间序列）；v 循环 Charts → Heatmap → Insights → Table。四个视图各举一例：

趋势仪表盘

按键：v 切视图 · ←→ 切周期（7d / 30d / 90d / all）· m 切 tokens ↔ cost · g 切换按厂商 / 按项目分组（明细表）· ↑↓ + enter 展开厂商行（明细表）· esc 关闭。

Charts —— 按模型分组的盲文时间序列 + 模型分布。同一模型 id 由不同厂商提供时保持独立并标注 (厂商)：

 Usage trends   [Charts]  Heatmap  Insights  Table     7d  [30d]  90d  all
 Total 66k tok · Cost $0.04 · Peak 39k (9/13) · Streak 2d
   39k ┤                                              ⢸⡄
       │                                              ⣿⠘⡄
       │                                              ⡇⡇⢸
       │                                             ⢸⠇⢣⡎
   17k ┤                                             ⢸ ⢸⠃
       │                                             ⡏ ⢸⡆
       │                                             ⡇⢀⡇⢇
     0 └⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣸⣔⣱⠑⢼
        08-14                08-29                09-13
 ● Total  ● gpt-5.6-luna  ● gpt-5.6-terra  ● deepseek-flash
 Models · 30d
   gpt-5.6-luna (openai-codex) █████████████████░░░ 52%  34k
   gpt-5.6-terra (relay)    █████░░░░░░░░░░░░░░░ 24%  16k
   deepseek-flash              ██░░░░░░░░░░░░░░░░░░  7%  4.5k
 m metric · ←→ period · v view · g group · esc close

Heatmap —— 12 周活动日历 + 连续天数：

 Activity · 12 weeks                Streak 2d
  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  █  ░
  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ▒  █
  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
 ░ none  ▒ light  ▓ mid  █ heavy
 Peak 39k tokens on 9/13 · Total 66k

Table —— 厂商→模型明细条目；enter 展开某厂商的模型明细：

 Provider / Model     Sessions  Msgs  Cost  Tokens  ↑In   ↓Out  Cache
 ▾ openai-codex               2    16 $0.04    44k   39k   5.3k   150k
    gpt-5.6-terra             1     2 $0.02    10k   10k     53   9.7k
    gpt-5.6-luna              1    14 $0.01    34k   29k   5.2k   140k
 ▸ deepseek                   1     8 $0.003   4.5k   3.2k   1.2k    16k
 ▸ relay                   1     4      -    17k   16k   1.1k    12k
 ─────────────────────────────────────────────────────────────────────
 Total                        4    28 $0.04    66k   58k   7.6k   177k
 Tokens = Input + Output + CacheWrite · ↑In = Input + CacheWrite

Insights —— 花费去向 + 值得注意的浪费模式：

 What's contributing to your cost?  30d
 Where it went
      $0.02  gpt-5.6-terra (openai-codex) drives 57% of your spend
          ~ routing some traffic to a cheaper model is the biggest cost lever
      73%  of processed tokens came from cache reads
      48%  of output is reasoning (thinking) tokens
          ~ lowering the thinking level on routine tasks cuts this hidden spend
 Worth attention
      $0.50   2 likely cache misses re-read the prompt at full price
          ~ pauses over 5 minutes and mid-session model switches invalidate the prompt cache

趋势数据聚合自 pi 的会话文件（<agentDir>/sessions/**/*.jsonl），带增量磁盘缓存；分叉会话副本自动去重。Token 口径 = input + output + cache 写入。

命令

| 命令 | 作用 | |---|---| | /trends | 打开交互式趋势仪表盘（图表/热力图/明细表/洞察）。等价于 /usage trends | | /usage | 向会话流打印用量卡片（余额 + 30 天摘要）。重复执行即刷新：5 分钟 TTL 内秒回，过期则重新拉取（15 秒超时）。卡片留存在会话里，/reload、恢复旧会话时自动重放 | | /usage trends | 打开交互式趋势仪表盘（Table / Charts / Heatmap / Insights；m 切指标，←→ 切周期，v 切视图，↑↓+enter 展开表格） | | /usage active\|all\|off | 立即切换 footer 状态行模式，并持久化到 usage.json（输入时有补全） | | pi --usage-status all | 指定本次运行的 footer 模式（覆盖 usage.json，不写回文件） |

优先级：/usage <mode>（会话内）> --usage-status（本次启动）> usage.json（持久）。

footer 状态行

| 模式 | 显示内容 | |---|---| | active（默认） | 当前模型对应账号的全部窗口 + 余额，末尾追加会话消耗。切换模型即时跟随 | | all | 全部账号压成一行——当前账号在前、正常亮度，其余置灰，消耗段固定在行尾 | | off | 整行隐藏 |

• 消耗段（session <tokens> tok）每轮对话结束即时更新（本地数据，与 pi footer 同口径）。真实费用仅在非零时追加（· $0.020）——订阅账号恒为 0，自动省略。
• 账号查询失败时显示红色的 账号名 !。

支持的账号

auth.json 里有凭据的自动识别，无需配置：

| auth.json key | 查询接口 | 显示内容 | |---|---|---| | openai-codex | GET chatgpt.com/backend-api/wham/usage | 5h/周/额外窗口、credits、花销控制 | | anthropic | GET api.anthropic.com/api/oauth/usage | Claude 5h/周/模型窗口和 extra usage 余额 | | github-copilot | GET github.com/copilot_internal/user | premium/chat 配额窗口、计划、重置日期 | | kimi-coding | GET api.kimi.com/coding/v1/usages | Coding Plan 配额窗口和 booster wallet | | minimax / minimax-cn | Token Plan 或账户余额接口 | 模型配额窗口或 USD/CNY 余额 | | moonshotai / moonshotai-cn | GET api.moonshot.{ai,cn}/v1/users/me/balance | USD/CNY 账户余额 | | openrouter | GET openrouter.ai/api/v1/key | API key 剩余额度和 usage 指标 | | opencode-go | GET opencode.ai/zen/go/v1/usage | rolling、周、月窗口 | | vercel-ai-gateway | GET ai-gateway.vercel.sh/v1/credits | 剩余 credits 和累计消费 | | zai | Z.AI 配额接口；无 coding plan 时回退 BigModel 余额接口 | 5h/周/MCP 窗口或人民币余额 | | deepseek | GET api.deepseek.com/user/balance | 多币种账户余额 | | 其他任意已配置厂商 | 自动探测（见下） | 网关余额或计划窗口 | | 任意自定义 provider | 配置驱动的通用适配器（见下） | 余额 / 窗口 |

自定义厂商的自动探测

pi 里没有专用适配器的厂商（例如通过 pi-provider-hub 或 models.json 配置的中转）， 会基于 registry 中的 baseUrl 和已存凭据自动探测：

• New API 网关：dashboard/billing/subscription + dashboard/billing/usage （可用时再加 /api/usage/token/）→ 剩余美元余额与 used/total 明细。
• Sub2API 网关：usage → 剩余余额。
• api.deepseek.com、MiniMax 各域名、open.bigmodel.cn / api.z.ai 按域名固定协议。

命中的协议在会话内固定；所有候选都拒绝（如 HTTP 404/401）时显示 "no balance endpoint detected"，且不会每次刷新都重复探测；瞬时网络错误会自动重试。 在 usage.json 里设 "autoDetect": false 可全局关闭，或 providers.<id>.enabled: false 单独隐藏。

凭据与安全

• OAuth token 经 pi 的 model registry 解析（getProviderAuth），临期自动刷新并写回 auth.json；registry 不认识的 provider 回退为直读 auth.json。
• API key 复用 pi 的插值规则（$ENV/${ENV}、$$/$! 转义、!command）。
• 用量接口均为未公开接口，可能随服务商改版失效；查询频率受 TTL 限制。

安装

pi install npm:@aaroncarry/pi-usage

也可以在 settings.json 的 packages 中手动添加。开发时若要直接加载当前本地仓库，请在仓库根目录执行：

pi install -l .

该命令会将本地包路径写入 .pi/settings.json。本仓库已经包含等效配置：

{
  "packages": [".."]
}

如果 Pi 询问是否信任项目，请允许，以便加载项目本地包。请先移除全局配置中的 pi-usage 条目，尤其是 git:github.com/aaroncarry/pi-usage 或 npm:@aaroncarry/pi-usage，避免旧版本与本地版本同时加载（例如：pi remove git:github.com/aaroncarry/pi-usage）。

配置

可选配置文件 <agentDir>/usage.json：

{
  "intervalMinutes": 5,
  "status": "active",
  "providers": {
    "zai": { "region": "cn", "label": "GLM" },
    "deepseek": { "enabled": false },
    "my-relay": {
      "label": "LingSuan",
      "custom": {
        "url": "https://relay.example/api/status",
        "headers": { "Authorization": "Bearer {token}" },
        "balancePath": "data.availableBalance",
        "currency": "CNY",
        "windowsPath": "data.limits",
        "windowFields": { "label": "name", "percent": "percentage", "resetsAt": "reset_at" }
      }
    }
  }
}

• intervalMinutes：后台刷新间隔（默认 5，最小 1）。
• status：active（默认）/ all / off。
• sparkline：设为 false 移除 footer 状态行的 7 天迷你趋势。
• autoDetect：设为 false 关闭对未知厂商的余额端点自动探测。
• providers.<id>.enabled: false：从状态行和卡片隐藏某账号。
• providers.<id>.label：显示名覆盖。
• providers.<id>.region：z.ai 区域 auto（默认）/global/cn。
• custom：通用适配器，接入任意 JSON 接口——headers 支持 $ENV 插值和 {token} 占位符（取该 provider 在 auth.json 里的凭据，若有）；balancePath/windowsPath 为 JSON 点路径（如 data.list[0].percent）。

开发

npm install --ignore-scripts
npm run typecheck
npm test

改完代码在 pi 里 /reload 即可生效（本地路径是原地引用）。

已知限制

• Kimi Coding、MiniMax、Moonshot、OpenCode Go 和 Vercel AI Gateway 使用各自专用接口；额度和账户余额保持分开解析，但服务端字段仍可能变化。MiniMax 会按 provider id 或 providers.<id>.region 选择全球/CN 接口。
• 暂不支持 x.ai consumer billing：pi 当前凭据注册表没有暴露其 OAuth 登录及 CLI proxy 身份流程，因此不会把 API key 或 prepaid 数值猜作订阅额度。
• DeepSeek 可能返回多种货币余额；主余额显示第一条有效货币，其他货币会列在备注中。
• Fireworks 和 Baseten 的组织级账单需要额外的账户发现及日期窗口处理，当前暂未加入。
• Claude 的 OAuth 用量接口未公开，且只有订阅 OAuth token 可以访问；API key 模式无法读取订阅窗口。
• 订阅账号（OAuth 登录）显示的 $ 是 pi 按模型目录单价估算的理论费用，并非真实扣费；真实消耗以服务端额度窗口为准。
• 状态行是 TUI 特性；/usage 卡片在任意模式下都会写入会话。