@gomeen/pi-usage-bar

中文文档
0.1.11发布于 2026/11/11MITES Module零依赖构建来源已验证近 30 天下载 2802

Subscription plan usage bars for the Pi coding agent: Codex, Claude, ZAI, MiniMax quota windows with reset countdowns, DeepSeek and relay balances, and official reset announcements. Styled after claude-code-usage-bar.

原始使用文档
文档目录8 节
  1. 功能
  2. 支持的套餐
  3. 安装
  4. 配置
  5. 安全
  6. 开发
  7. 致谢
  8. 许可

pi-usage-bar

English · 简体中文

Pi 编码智能体的订阅套餐用量条——配额窗口、重置倒计时、中转站余额、官方重置公告,样式对齐 claude-code-usage-bar。

功能

  • footer 用量条:当前模型对应套餐的两个配额窗口(会话 + 周窗),每格渐变 bar + ⏰ 重置倒计时
  • 输入框角标:git 分支与上下文用量(main · 60.8%)嵌入输入框顶边框右侧,当前模型名右对齐在用量条第一行——替代 pi 自带 footer 的路径/统计行,整个 footer 只剩两行
  • 四种 look:aurora 块条(默认)、aurora 细线、ring(◔ 14% 5h · resets 1h07m)、classic 电池条——全部可实时切换
  • 中转站余额:one-api/new-api 系中转(或提供 /v1/usage 的 Sub2API 系站点)的自定义 provider 自动探测计费端点,显示剩余金额($200.00)
  • WorkBuddy 积分:支持 /v1/balance-summary 的网关直接用现有 API Key 查询,显示 2098.71 credits,不加货币符号,也不推算额度百分比。
  • DeepSeek 余额:deepseek provider 显示账户剩余预付余额(¥110.00),货币符号按 API 返回值显示
  • Kimi / Moonshot 余额:moonshotai / moonshotai-cn provider——或 baseUrl 在 api.moonshot.ai / api.moonshot.cn 上的任意自定义 id(自动检测,无需手动映射)——显示开放平台账户可用余额,货币按所在站点币种显示
  • 下次官方重置预告:Codex 套餐接入 codex-resets.com,仅在站点发布了将来重置预告时显示(↻ Reset announced · in 1h10m),不再回显已经发生过的重置
  • /usage 单一入口查看套餐详情或进入 Appearance / Display / Advanced,修改直接作用于实际用量条,--usage 一行 JSON 冒烟测试

支持的套餐

套餐Pi provider id认证
OpenAI Codex (ChatGPT)openai、openai-codexChatGPT 订阅 OAuth —— 用量查询需要 openai-codex("OpenAI Codex")登录:openai 的 ChatGPT 直用令牌无法访问 backend-api 用量端点。/login → OpenAI Codex 登一次即可。
Anthropic ClaudeanthropicClaude Pro/Max OAuth
ZAI Coding Plan(国际/国内)zai、zai-coding-cnAPI key
MiniMax Token Plan(国际/国内)minimax、minimax-cnAPI key
DeepSeek(预付余额)deepseekAPI key
Kimi / Moonshot 开放平台(预付余额)moonshotai(国际)、moonshotai-cn(国内)、baseUrl 在 api.moonshot.ai / api.moonshot.cn 上的自定义 idAPI key
WorkBuddy 积分余额(/v1/balance-summary)任意自定义 provider id网关 API key
中转站(one-api/new-api 系、Sub2API 系 /v1/usage)任意自定义 provider idAPI key

自定义 provider(代理、cc-switch 条目)会自动探测中转计费端点——先试 one-api/new-api 的 dashboard 端点族,再试 WorkBuddy 的 {site}/v1/balance-summary,最后回退到 Sub2API 风格的 {site}/v1/usage;也可以用 providerMap 显式映射到某个套餐。baseUrl 位于第一方 Kimi host(api.moonshot.ai / api.moonshot.cn)的自定义 id 会自动检测并常驻显示。

安装

pi install npm:@gomeen/pi-usage-bar

重启 Pi(或 /reload)。套餐认证走 Pi 的 /login——扩展通过 Pi 的 provider API 解析凭据,从不直接读 auth.json。

配置

配置在 ~/.pi/agent/usage-bar.json(稀疏写入——只存非默认键)。可以直接改文件,也可以打开 /usage,直接选择 Appearance(外观)、Display(显示内容)或 Advanced(高级)。Enter/Space 切换值并立即保存。修改直接展示在实际用量条上,不再显示重复的 Preview 区域。Appearance → Bar style 用 ↑↓ 切换四种样式,每次切换立即保存并应用;Display 管理显示套餐、重置信息和余额;Advanced 包含刷新间隔和 Provider mapping 配置说明,结构化的 providerMap 条目仍在 JSON 文件中编辑。Esc 逐级返回,不撤销已保存的修改。中转站域名只缩短展示标签(api.4sapi.com → 4sapi),provider ID 与请求地址不变。

键默认含义
style"aurora"aurora | ring | classic
bar_glyph"block"block | thin(aurora 用)
theme"graphite"graphite | "pi"(跟随 pi 主题)
density"regular"compact | regular | cozy
bar_width12bar 格数
color_ok / color_warn / color_hot""#rrggbb 覆盖
warning_threshold / critical_threshold30 / 70百分比
display.mode"all"active(当前套餐)| all(全部已配置套餐)
display.providers[]all 模式的套餐过滤
display.compact_otherstrue非当前套餐压缩为一行简报
providerMap{}自定义 id → 套餐,如 {"cc-switch-zhipu-glm": "zai-cn"} 或 {"my-relay": {"type": "relay"}}
refresh_minutes2轮询间隔(分钟)
show_resetstrue官方重置公告
show_reset_countdownfalse每个窗口的 ⏰ 重置倒计时
show_balancetrue余额探测(中转 + DeepSeek + Kimi)
currency"$"中转余额货币符号;DeepSeek 和 Kimi 按 API/站点币种显示

第一方监控端点可用环境变量覆盖:PI_ZAI_USAGE_ENDPOINT、PI_ZAI_CODING_CN_USAGE_ENDPOINT、PI_MINIMAX_USAGE_ENDPOINT、PI_MINIMAX_CN_USAGE_ENDPOINT(含 legacy 变体)、PI_DEEPSEEK_USAGE_ENDPOINT、PI_KIMI_USAGE_ENDPOINT、PI_KIMI_CN_USAGE_ENDPOINT。provider token 会作为 Bearer 发送到所配置的端点——只覆盖你信任的端点。

安全

  • token 只发给第一方端点(或中转站自己的 host、用它自己的 key)
  • token 永不出现在日志、/usage、--usage 输出里
  • 从不读写 auth.json;凭据全部通过 Pi 的 modelRegistry 解析

开发

npm install
npm run check   # tsc --noEmit + biome + vitest

架构:一个深模块(UsageSnapshot 管线)+ 三条缝——数据(src/providers/)、渲染(src/render/,纯函数)、pi 适配(src/pi/)。见 AGENTS.md。

致谢

本项目受三个 MIT 项目启发(借鉴思路,不搬代码):

许可

MIT

版本与发布记录

@gomeen/pi-usage-bar 共发布 13 个版本,首次发布于 2026/10/27;过去 12 个月发布了 13 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.11latest2026/11/115 天前
0.1.102026/11/115 天前
0.1.92026/11/079 天前
0.1.82026/11/079 天前
0.1.72026/11/0214 天前
0.1.62026/11/0214 天前

关于 @gomeen/pi-usage-bar 的常见问题

@gomeen/pi-usage-bar 是什么?

Subscription plan usage bars for the Pi coding agent: Codex, Claude, ZAI, MiniMax quota windows with reset countdowns, DeepSeek and relay balances, and official reset announcements. Styled after claude-code-usage-bar.

如何安装 @gomeen/pi-usage-bar?

在项目目录运行 npm install @gomeen/pi-usage-bar,或使用 pnpm add / yarn add / bun add。

@gomeen/pi-usage-bar 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gomeen__pi-usage-bar 是否存在。

@gomeen/pi-usage-bar 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gomeen/pi-usage-bar 可以商用吗?

@gomeen/pi-usage-bar 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gomeen/pi-usage-bar 的下载量有多少?

根据 npm 官方下载统计,@gomeen/pi-usage-bar 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,802 次,日均约 93 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gomeen/pi-usage-bar 还在维护吗?

最新版本 0.1.11 发布于 2026/11/11(5 天前);至今共发布 13 个版本,其中过去 12 个月发布了 13 个;首次发布于 2026/10/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。