# @gomeen/pi-usage-bar 中文文档

规范地址：https://npmcn.com/package/%40gomeen/pi-usage-bar/

版本：0\.1\.11
npm 元数据更新时间：2026-11-11T07:39:55.799Z
中文译文更新时间：2026-11-16T19:24:30.598Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gomeen/pi-usage-bar
原文对照：https://npmcn.com/package/%40gomeen/pi-usage-bar/?lang=original
项目主页：https://github.com/gomeen/pi-usage-bar#readme
源码仓库：https://github.com/gomeen/pi-usage-bar

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：236 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-ai \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-10-27T01:27:08.235Z
- 最新版本发布：2026-11-11T07:39:55.513Z
- 近 30 天下载量：2802（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Pi 编码代理的订阅计划使用栏: Codex, Claude, ZAI, 有重设倒计时的MiniMax配额窗口, DeepSeek和中继余额,以及官方重置公告. 以 Claude-code-usage-bar 为样式 .

## 安装

```sh
npm install @gomeen/pi-usage-bar
```

也可以使用：`pnpm add @gomeen/pi-usage-bar`、`yarn add @gomeen/pi-usage-bar`、`bun add @gomeen/pi-usage-bar`

## README

# pi-usage-bar

[English](https://npmcn.com/package/%40gomeen/pi-usage-bar/README.md) · [简体中文](https://npmcn.com/package/%40gomeen/pi-usage-bar/README.zh.md)

[Pi](https://github.com/earendil-works/pi) 编码智能体的订阅套餐用量条——配额窗口、重置倒计时、中转站余额、官方重置公告，样式对齐 [claude-code-usage-bar](https://github.com/leeguooooo/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](https://codex-resets.com/)，仅在站点发布了将来重置预告时显示（`↻ Reset announced · in 1h10m`），不再回显已经发生过的重置
-   **`/usage`** 单一入口查看套餐详情或进入 **Appearance / Display / Advanced**，修改直接作用于实际用量条，**`--usage`** 一行 JSON 冒烟测试

## 支持的套餐

| 套餐 | Pi provider id | 认证 |
| --- | --- | --- |
| OpenAI Codex (ChatGPT) | `openai`、`openai-codex` | ChatGPT 订阅 OAuth —— **用量查询需要 `openai-codex`（"OpenAI Codex"）登录**：`openai` 的 ChatGPT 直用令牌无法访问 backend-api 用量端点。`/login` → OpenAI Codex 登一次即可。 |
| Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
| ZAI Coding Plan（国际/国内） | `zai`、`zai-coding-cn` | API key |
| MiniMax Token Plan（国际/国内） | `minimax`、`minimax-cn` | API key |
| DeepSeek（预付余额） | `deepseek` | API key |
| Kimi / Moonshot 开放平台（预付余额） | `moonshotai`（国际）、`moonshotai-cn`（国内）、baseUrl 在 `api.moonshot.ai` / `api.moonshot.cn` 上的自定义 id | API key |
| WorkBuddy 积分余额（`/v1/balance-summary`） | 任意自定义 provider id | 网关 API key |
| 中转站（one-api/new-api 系、Sub2API 系 `/v1/usage`） | 任意自定义 provider id | API 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 会自动检测并常驻显示。

## 安装

```bash
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_width` | `12` | bar 格数 |
| `color_ok` / `color_warn` / `color_hot` | `""` | `#rrggbb` 覆盖 |
| `warning_threshold` / `critical_threshold` | `30` / `70` | 百分比 |
| `display.mode` | `"all"` | `active`（当前套餐）| `all`（全部已配置套餐） |
| `display.providers` | `[]` | `all` 模式的套餐过滤 |
| `display.compact_others` | `true` | 非当前套餐压缩为一行简报 |
| `providerMap` | `{}` | 自定义 id → 套餐，如 `{"cc-switch-zhipu-glm": "zai-cn"}` 或 `{"my-relay": {"type": "relay"}}` |
| `refresh_minutes` | `2` | 轮询间隔（分钟） |
| `show_resets` | `true` | 官方重置公告 |
| `show_reset_countdown` | `false` | 每个窗口的 `⏰` 重置倒计时 |
| `show_balance` | `true` | 余额探测（中转 + 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` 解析

## 开发

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

架构：一个深模块（`UsageSnapshot` 管线）+ 三条缝——数据（`src/providers/`）、渲染（`src/render/`，纯函数）、pi 适配（`src/pi/`）。见 [AGENTS.md](https://npmcn.com/package/%40gomeen/pi-usage-bar/AGENTS.md)。

## 致谢

本项目受三个 MIT 项目启发（借鉴思路，不搬代码）：

-   [hknet/pi-usage-bars](https://github.com/hknet/pi-usage-bars) —— 各家用量 API 的调研参考
-   [leeguooooo/claude-code-usage-bar](https://github.com/leeguooooo/claude-code-usage-bar) —— aurora 样式与配置词汇
-   [leeguooooo/codex-statebar](https://github.com/leeguooooo/codex-statebar) —— ring 样式与官方重置行

## 许可

[MIT](https://npmcn.com/package/%40gomeen/pi-usage-bar/LICENSE)

## 常见问题

### @gomeen/pi-usage-bar 是什么？

Pi 编码代理的订阅计划使用栏: Codex, Claude, ZAI, 有重设倒计时的MiniMax配额窗口, DeepSeek和中继余额,以及官方重置公告\. 以 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 和提交记录判断。

