pi-check-agent-quota

在 pi TUI 中显示 AI provider 的配额、余额和最近几轮对话消耗，并可按实时配额选择 provider/model。

English | 中文说明

支持的 provider

Provider	显示
MiniMax (minimax, minimax-cn)	5h / 7d 使用率
Kimi API (moonshotai, moonshotai-cn)	余额
Kimi For Coding (kimi-coding)	5h / 7d 使用率
Z.AI / GLM (zai)	余额
Z.AI Coding Plan (zai-coding-cn)	使用率
DeepSeek (deepseek)	余额
OpenRouter (openrouter)	余额
OpenCode Go (opencode-go)	5h / 7d / mo 使用率
OpenAI Codex (openai-codex，ChatGPT Plus/Pro OAuth 登录)	5h / 周使用率、套餐标识

其他 provider 不查询，Widget 显示 --。opencode-go 使用 pi 已有的 OPENCODE_API_KEY。openai-codex 复用 pi /login openai-codex 的 OAuth 凭据（access token，由 pi 自动续期）；普通 OpenAI API key 无法查询 ChatGPT 订阅限额。kimi-coding 同时支持 pi /login kimi-coding 的 OAuth 订阅和普通 KIMI_API_KEY。/login 是 pi 内置命令，不是本扩展注册的命令；本扩展只读取 pi 已解析的凭据，不实现或保存登录流程。

安装

pi install npm:pi-check-agent-quota

API key 复用 pi 已有的 provider 认证，无需额外配置。

认证命令（pi 内置）

下面的命令属于 pi，不是本扩展注册的命令；使用 OAuth 配额 provider 时需要先执行：

/login kimi-coding       # 登录 Kimi For Coding OAuth
/login openai-codex      # 登录 ChatGPT Plus/Pro Codex OAuth

• 按 pi 显示的浏览器/设备码流程完成登录；
• 凭据由 pi 自己保存和自动续期；
• 登录后切换到对应 provider/model，本扩展只读取 pi 已解析的 access credential；
• 本扩展不注册 /login，不接收登录密钥，也不持久化 OAuth token。

显示

颜色与状态

• 配额颜色：低用量绿色、接近上限黄色、超限红色；消耗差值紫色。
• 上一轮消耗：余额 (¥-0.20)、桶型 (-20%)；回升为正，无变化不带符号。
• 状态标注：
  • 对话进行中 → (使用中)
  • 抓取失败 → (失败)
  • 跨 provider 切换 → (变更)
• 余额告警：低于阈值（默认 10，可用 /aqset <红> <黄> <余额告警> 调整；环境变量 PI_QUOTA_BALANCE_ALERT 仍可作为初始值）时数字标红。

余量预估（ETA）

状态栏右侧显示 2分钟前 · 预计可用：N轮/2h15m：

• 消耗速率：按窗口优先级取最短可用窗口（5h → used → 7d → mo）。5h/used 的增量是真实单轮消耗；7d/mo 为滑动窗口，仅在无更小窗口时作为回退。
• 瓶颈桶：各桶轮数 = 各自剩余量 ÷ 统一速率，取最先耗尽的瓶颈。7d/mo 先重置则不构成约束。
• 隐藏条件：样本不足、任一桶已耗尽、或请求失败时隐藏。
• 特殊显示：
  • 近期无消耗 → 近x轮0消耗（余额型和桶型都支持）
  • 超过 365 轮 → 365+轮
  • 剩余 ≤5 轮或 ≤30 分钟 → 数字标红
• 布局：窄窗口自动换行，拖拉窗口自动重算贴边；时间精确到分（2h15m），≥24h 换算成天（3d4h）。
• 刷新时间：有 ETA 时，2分钟前 ·（en: 2m ago ·）显示在「预计可用」前；没有 ETA 时只显示 2分钟前（en: 2m ago），表示当前配额快照抓取于 2 分钟前。定义：age = 当前时间 − 该 provider 最近一次成功抓取时间（抓取由会话启动、切换模型、每轮结算、/aqcheck 触发；会话恢复时可能来自磁盘缓存，会如实显示如 5小时前）。闲置时每分钟自动重算；age 与 ETA 独立，ETA 不可用时（窗口耗尽/窄窗/样本不足）仍显示；抓取失败后也显示最近一次成功快照的 age。
• 自动刷新（可选，默认关闭）：用 /aqauto 5 开启（每 5 分钟）、/aqauto 0 关闭、/aqauto 查看。开启后 pi 挂着不用也会按间隔自动抓取（纯监控用途，无需对话）；手动 /aqcheck 和每轮结算照常工作，并会推迟下一次自动抓取。设置与阈值一样持久化；环境变量 PI_QUOTA_AUTO_REFRESH_MINUTES 仍可作为初始值。

命令

命令	用法	说明
/aqcheck	/aqcheck	强制刷新并显示当前 provider 的实时配额
/aq10	/aq10	显示最近 10 条已结算轮次的消耗汇总
/aqlang	/aqlang zh|en	切换界面语言（默认中文）
/aqset	/aqset [红 黄 余额] | reset	查看/设置显示阈值
/aqauto	/aqauto [分钟]	查看/设置挂机自动抓取，0 关闭
/aqpick	/aqpick	现场刷新配额并按 provider 选择模型

/aqcheck — 强制刷新

用法：

/aqcheck

• 不需要参数（多余文本会被忽略），始终请求当前 provider 的实时配额，不依赖缓存；
• 使用当前 provider 配置的 API key 或 pi 管理的 OAuth 凭据；
• 成功后更新 Widget、age 和 ETA，但单独执行 /aqcheck 不会创建消耗记录；
• 同 provider 已有请求在途时会等待并复用该请求；同 provider 在 1 秒内重复执行会防抖；
• 没有当前 provider 时提示警告；未支持或未配置 provider 保持 --/限额不可用。

/aq10 — 近期消耗汇总

用法：

/aq10

• 不需要参数（多余文本会被忽略），也不会触发网络请求；
• 显示当前 provider 最近成功结算的对话轮次，最多 10 条；
• 配额型 provider 显示各窗口的百分比消耗，余额型 provider 显示货币消耗；
• 跨 provider 或失败轮次不计入消耗；余额增加/不变不会作为余额消耗显示；
• 没有可用记录时提示暂无消耗记录。

示例：

minimax-cn 近2轮消耗 5h 23% / 7d 11%
opencode-go 近5轮消耗 5h 15% / 7d 10% / mo 5%
openrouter 近5轮消耗 $0.69

/aqlang — 切换界面语言

用法：

/aqlang zh
/aqlang en

• 只接受 zh 或 en（不区分大小写，会忽略首尾空格）；
• 立即切换 Widget 标签、状态、ETA、通知和命令描述；
• 语言选择写入本地缓存，下次会话自动恢复；
• 其他值、缺少参数或多余参数都会拒绝并提示用法。

/aqset — 显示阈值

一行三个数字，顺序固定：红 / 黄 / 余额告警。

• 第 1 个数：使用率 ≥ 此百分比变红
• 第 2 个数：使用率 ≥ 此百分比变黄
• 第 3 个数：余额 ≤ 此值标红（货币单位）

/aqset               # 查看当前阈值（同样格式输出，改数字重发即可）
/aqset 80 40 10      # 默认：使用率 ≥80% 红、≥40% 黄、余额 ≤10 标红
/aqset 60 30 20      # 更敏感：更早变黄变红，余额告警提高
/aqset reset         # 恢复默认

规则：

• 红线必须大于黄线，否则拒绝并提示用法；
• 非法输入（个数不对、非数字、越界）拒绝且不保存；
• 设置立即生效并跨会话持久化（存在本地缓存文件里）；
• 旧环境变量 PI_QUOTA_PCT_YELLOW / PI_QUOTA_PCT_RED / PI_QUOTA_BALANCE_ALERT 仍可作为初始值。

/aqpick — 按实时配额选择模型

用法：

/aqpick

• 不接受参数；每次执行都会现场刷新候选 provider，不使用旧快照作为选择依据；
• 候选来自 pi 当前允许选择的模型范围；只查询并显示已认证且受本扩展支持的 provider；
• 候选 provider 会同时发起现场查询，每个 provider 只尝试一次；总等待上限为 10 秒，抓取失败、超时或未认证的 provider 不进入列表；未选中的候选配额只保留在当次内存中，不写入本地缓存；
• 百分比型 provider 显示各窗口的已用百分比和重置倒计时，余额型 provider 显示余额；
• 当前 provider 固定置顶，其余按显示名称排序；先选择 provider，再选择该 provider 下的模型；若只有一个可选模型则直接切换；
• Esc 取消时不改变模型；切换失败时保留当前模型；
• 切换通过 pi 官方 pi.setModel() 完成，不修改认证配置，不自动发送消息，也不触发模型请求；
• 与 pi 原生 /model 一样，跨 provider 切换后，下一轮对话上下文会由 pi 正常发送给新 provider。

/aqauto — 挂机自动抓取

默认关闭；开启后即使不对话，也按设定间隔自动抓取配额：

/aqauto               # 查看当前状态（如：自动抓取：每 5 分钟一次）
/aqauto 4             # 开启，每 4 分钟
/aqauto 30            # 最大间隔
/aqauto 0             # 关闭

规则：

• 间隔只接受整数，范围 0–30 分钟：0 = 关闭，1–30 = 开启并设置分钟间隔；on、off、小数、负数、多参数和超过 30 的值直接拒绝；
• 立即生效并跨会话持久化（与 /aqset 一样存在本地缓存文件里）；
• 防抖：1 秒内重复同一命令忽略；任何一次抓取（手动 /aqcheck、每轮结算、会话启动）都会推迟下一次自动抓取；同 provider 在途请求合并不重复；
• /aqset reset 会连自动抓取一起重置回环境变量初始值（或关闭）；
• 旧环境变量 PI_QUOTA_AUTO_REFRESH_MINUTES 仍可作为初始值（超过 30 钳制到 30）。

/aq10 示例

minimax-cn 近2轮消耗 5h 23% / 7d 11%
opencode-go 近5轮消耗 5h 15% / 7d 10% / mo 5%
openrouter 近5轮消耗 $0.69

从旧版本迁移缓存（老用户须知）

v0.1.2 起，缓存文件从 ~/.pi/agent/pi-check-agent-quota.json 迁移到了 ~/.pi/agent/pi-check-agent-quota/quota-cache.json。

不迁移也能正常使用——插件会在新位置从头开始累计，只是 /aq10 的历史消耗记录会清空。

如果想保留历史记录，手动搬移即可：

mkdir -p ~/.pi/agent/pi-check-agent-quota
mv ~/.pi/agent/pi-check-agent-quota.json ~/.pi/agent/pi-check-agent-quota/quota-cache.json

确认新位置能正常读写后，旧文件即可删除（上面的 mv 已完成移动）。

Migration is optional — the plugin works fine without it; it will simply start fresh, and your /aq10 consumption history will be reset. To keep your history, move the file manually using the commands above.

隐私

• 只向对应 provider 的配额接口发送该 provider 的凭据（API key 或 OAuth access token，后者由 pi 管理与续期，本扩展不落盘、不日志）；
• 不读取、不上传 prompt、回复、文件或对话内容；不保存 API key 和完整响应；无遥测；
• 本地缓存位于 ~/.pi/agent/pi-check-agent-quota/quota-cache.json，仅当前用户可读写；
• 自定义 baseUrl 仅允许 HTTPS（本机回环可用 HTTP），请求不跟随重定向；配置后，配额凭据只发送到该配置地址而不会再发送到默认官方域名，因此请仅使用你信任的地址；
• 默认只在用户可见事件时抓取（会话启动、切换模型、每轮结算、/aqcheck）；若通过 /aqauto 开启自动刷新，pi 打开期间会按该间隔在后台自动抓取；执行 /aqpick 时会现场查询当前可选、已认证且受支持的 provider；
• /aqpick 使用 pi 官方模型对象和 pi.setModel()，不会自行构造模型请求；未选中的候选配额不落盘；跨 provider 切换后的下一轮上下文发送行为与 pi 原生 /model 一致。

License

MIT