pi-openrouter-balance

English | 简体中文

非官方扩展。 与 OpenRouter 无任何关联。数据来自 OpenRouter API（/api/v1/key 与 /api/v1/credits），使用 pi 自身的凭据；这些接口不是公开文档化的契约，随时可能变化，本扩展也可能随时失效。

在 pi coding agent 的 footer 中展示 OpenRouter 账户余额与密钥用量，并提供完整的 /openrouter-balance 报告。

openrouter $149.70 ↓$0.42/h
openrouter $60.00 ███████░ 68% $6.80/$20 ↓$0.42/h   ← 密钥设了额度上限

安装

pi install npm:pi-openrouter-balance

或从 git 安装：

pi install git:github.com/frederick-wang/pi-openrouter-balance

需要在 pi 中登录 OpenRouter（/login 选择 OpenRouter，或设置 OPENROUTER_API_KEY）。

用法

Footer

当前模型的 provider 是 openrouter 时显示；换到其他 provider 自动清除。

元素	含义
$149.70	账户余额：充值 − 已用（可能为负；负数即 402 风险）
$60.00	同上；密钥设了额度上限时，进度条接在余额后面
███████░	8 格剩余进度条，仅在密钥设了额度上限时出现（剩余/上限）；没设上限不画条，不发明数据
68%	额度上限的剩余百分比
$6.80/$20	该密钥的剩余金额 / 上限金额
↓$0.42/h	消耗速率：基于余额历史估算的每小时花费（需要 ≥3 个、跨度 1 小时以上的样本；充值跳变会开启新窗口）。PI_OPENROUTER_BALANCE_RATE_MODE=key 可把 footer 切到密钥速率（形式相同）；默认账户速率
~	前缀：上次刷新失败，保留旧数字（标记陈旧，绝不当最新数据展示）
·免费 / ·free	当前模型 id 以 :free 结尾（免费模型状态看模型，不是看密钥）
颜色	进度条：剩余 ≥50% 绿，20–49% 黄，<20% 红

整行替换的状态文案：

状态	含义
n/a	正在加载或无数据
认证错误 / auth error	凭据被拒（会先重新解析一次再判定）
限流中 / rate limited	OpenRouter 返回 429；已安排重试
额度用尽 / no credits left	真实请求（或 credits 接口）返回 402；轮询不会停止

告警

每个状态转换一次：

触发	文案（中文）
余额 ≤ PI_OPENROUTER_BALANCE_WARN（默认 $20）	OpenRouter 余额 $18.20 已低于 $20。
余额 ≤ PI_OPENROUTER_BALANCE_ERROR（默认 $5）	OpenRouter 余额 $4.10 已低于 $5。
密钥设了上限时，同一阈值比剩余额度	OpenRouter 剩余额度 $6.80 已低于 $20。
任意请求（或 credits 接口）返回 402	OpenRouter 额度用尽。

回升即重新武装阈值（超过上次值即解除，带浮点容差）；任何回升都不叫"充值"。免费账户（从未购买）不触发低余额告警——阈值保护的是钱包，而免费账户钱包为零是常态；402 始终保持无条件。

/openrouter-balance

报告 overlay，各分区含义：

分区	含义
账户余额	账户级 充值 − 已用；明细行给出两个数字
额度上限	密钥级上限：剩余进度条 + 百分比 + 剩余/上限 + 重置节奏（daily/weekly/monthly，新值原样透传）；未设置时显示「未设置（不限额）」；绝不画假的 0% 条
密钥标签	服务端返回的密钥标签（它自己的脱敏形态）+ 付费账户（已购买额度）/ 免费账户（从未购买额度）
今日/本周/本月 (UTC)	服务端计算的周期用量；周从周一开始；明确标注 UTC（"今日"在北京时间 08:00 切换）
自带密钥（BYOK）	你自己上游密钥产生的花费；非零才显示
账户消耗速率	整个账户（全部密钥+网页）的每小时花费；与它旁边的钱包数字同口径
密钥消耗速率	这把密钥的每小时花费（用它的所有客户端合计；同样门槛 + 最小增量 ≥$0.01）；绝不暗示"只是 pi 的消耗"
余额可用时长	余额 ÷ 速率；两者齐备才显示
模型状态	仅当前模型 id 以 :free 结尾时出现：免费模型限额（20 次/分 · 50 次/日）只对免费账户给出数字；付费账户只给状态不给限额猜测
数据行	新鲜度 + 来源；(~) 表示陈旧

/openrouter-balance --json 输出稳定 schema（键名固定英文；不含凭据与指纹）——TUI 模式显示在 overlay，print 模式输出到 stdout，其他模式拒绝。

/openrouter-balance --refresh 跳过限流立即刷新。

命令在非 openrouter 模型下也能用；它不会把 footer 打开。

刷新

激活时与执行命令时抓取；每次回合稳定后至多 60 秒一次；openrouter 模型激活期间每 5 分钟心跳一次；429 遵循 Retry-After 并安排一次重试；401/403 先重新解析凭据一次再判定。若 /credits 被拒（服务端可能某天执行文档中的管理密钥规则），扩展自动降级为密钥级数据并附一行说明；瞬时失败保留上次余额。

认证与隐私

• 凭据只通过 pi 自身的 openrouter 认证解析（环境变量密钥或 OAuth 换发的密钥）；扩展从不读写凭据文件。
• 密钥/token 仅存在于请求内存中，错误信息一律脱敏。
• 持久化到 ~/.pi/agent/pi-openrouter-balance-snapshots.jsonl 的快照只含数字，按键控的是 OpenRouter 用户 id 的 HMAC 指纹——绝不含密钥或原始 id。
• 无遥测；除两个只读接口外无任何网络请求。

配置

• PI_OPENROUTER_BALANCE_LANG=zh|en — 界面语言（默认：跟随系统语言，再英文）。
• PI_OPENROUTER_BALANCE_WARN — 余额警告阈值（美元，默认 20）。
• PI_OPENROUTER_BALANCE_ERROR — 余额错误阈值（美元，默认 5）。
• PI_OPENROUTER_BALANCE_RATE_MODE=key|account|both|hidden — footer 显示哪种速率（默认 key；报告始终显示两套）。/openrouter-balance rate-mode 会把同一选择持久化到 ~/.pi/agent/pi-openrouter-balance-prefs.json；环境变量优先，命令执行时会明说。
• PI_CODING_AGENT_DIR — pi 配置目录（快照位置沿用 pi 自身约定）。

说明

• 消耗速率需要至少三个、跨度一小时以上的余额样本才会出现；算得诚实才显示。
• 进度条只为密钥额度上限绘制；没设上限时 footer 只显示数字，不发明比例。
• 密钥的 usage 计数是按密钥计的（新 key 可能是 0 而账户在持续花钱）——只做展示，绝不用于速率计算。