pi-usage

English | 简体中文

一个 Pi Coding Agent 扩展，在 Pi 内部显示 AI 供应商用量与配额。

支持 Z.ai / GLM Coding Plan、DeepSeek 和 OpenRouter。仅在 Pi 中配置了对应供应商时才会出现；已配置但查询失败的仍会显示（标记 error/stale），未配置的完全隐藏。

关于 API 稳定性的诚实说明：本扩展会主动调用各供应商的用量查询接口。设计原则：只用官方公开文档接口，且多供应商架构——在 Pi 里配置了哪些供应商就显示哪些。

• DeepSeek（GET /user/balance）与 OpenRouter（GET /api/v1/key、GET /api/v1/credits）为官方公开文档接口——稳定，但字段仍可能演进。
• Z.ai 接口（model-usage、tool-usage、quota/limit）无官方文档：参照官方 glm-plan-usage 插件推导，可能随时变更。
• 暂不支持 OpenAI / Anthropic / Google Gemini：同类插件查订阅额度用的是无文档私有 API（从官方 CLI 逆向而来），随时可能失效或被封——本项目刻意不承担此风险；而各家 admin 用量 API 又需要组织级 admin key（不会用作对话 provider 的 key）。

接口失效时优雅降级（usage unavailable），不影响模型请求。

/usage
GLM/glm-5.3 (zai) — 5h 32% 2026-08-15 11:43:00 · MCP 18% 2026-08-27 09:43:00

/usage zai
+-------------------+--------------+-----+--------------+-------+---------------------+
|                                 GLM/glm-5.3                                         |
|                        refreshed 2026-08-15 09:43:00                                |
+-------------------+--------------+-----+--------------+-------+---------------------+
| Quota             | Usage        | Pct | Used         | Left  | Resets              |
+-------------------+--------------+-----+--------------+-------+---------------------+
| MCP monthly quota | [##--------] | 18% | 180 / 1000   | 820   | 2026-08-27 09:43:00 |
|   web-search      | [##--------] | 22% | 220 / 1000   | 780   | —                   |
| 5-hour quota      | [###-------] | 32% | 5000 / 28000 | 23000 | 2026-08-15 11:43:00 |
+-------------------+--------------+-----+--------------+-------+---------------------+

Models (* = current):
  * glm-5.3                  5000  (32%)
    glm-5.2                   800  (5%)

status line（始终每 2 分钟自动刷新）
GLM/glm-5.3 · 5h 32% · MCP 18%

/usage pin（固定在编辑器上方的 widget，自动刷新）
┌─ pinned above the editor ──────────────────────────────────────────┐
│ GLM/glm-5.3 (zai) — 5h 32% 2026-08-15 11:43:00 · MCP 18% …    │
└───────────────────────────────────────────────────────────────────────┘

安装

pi install npm:@imdlan/pi-usage

用 pi update --extensions 更新；用 pi remove npm:@imdlan/pi-usage 卸载。

需要 Node.js 20+，并在 Pi 中配置至少一个受支持的供应商：

• Z.ai / GLM Coding Plan — base URL 指向官方 Z.ai / GLM 端点，API key 解析到你的 GLM Coding Plan token。
• DeepSeek — base URL 指向 https://api.deepseek.com，普通 API key。
• OpenRouter — base URL 指向 https://openrouter.ai，普通 sk-or-v1-... key。

命令

| 命令 | 行为 | 自动刷新？ | | --- | --- | --- | | /usage | 所有供应商的用量摘要，含配额重置时间（本地时间）。 | ❌ 一次性快照 | | /usage zai | Z.ai 详细用量表：5 小时配额、MCP 月度配额（含分工具明细）、分模型用量。 | ❌ | | /usage deepseek | DeepSeek 按币种余额（CNY/USD），含赠送/充值明细。 | ❌ | | /usage openrouter | OpenRouter key 消费上限（已用/剩余/重置）+ 日/周/月花费 + 账户积分余额（USD）。 | ❌ | | /usage refresh | 强制从 API 拉取最新数据后渲染摘要。失败时保留最后一次有效快照。 | ❌ 仅渲染一次 | | /usage status | 状态栏内容、上次刷新时间、缓存状态。 | ❌ | | /usage pin | 将摘要 widget 固定在编辑器上方。pin on / pin off 显式设置；pin 切换。 | ✅ 约每 2 分钟 |

关键区别：普通 /usage 是静态快照。只有固定 widget（/usage pin）会保持最新，每个后台周期（约 2 分钟）从缓存重渲染（无额外 API 调用）。固定状态仅限当前会话。底部状态栏无论如何都始终自动刷新。

明细表格宽度自适应：窄终端依次省略可选列（Resets → Left → Used → Usage 进度条），绝不溢出。

当前模型指示

凡显示供应商名称处，均追加当前活跃模型 id，格式 Name/model（如 GLM/glm-5.3）—— 状态栏、摘要、固定 widget、明细表头。跟随 /model、循环切换（Ctrl+P）或会话恢复的模型切换。

安全与隐私

• 只读：仅查询用量。
• 不接触密钥：凭据通过 Pi 的 getProviderAuth 解析；绝不读取凭据文件或运行子进程。
• 网络严格受限：仅 HTTPS，host 白名单（api.z.ai、open.bigmodel.cn、dev.bigmodel.cn），拒绝重定向。
• 无遥测；输出全部脱敏。

开发

npm install
npm run typecheck   # strict tsc
npm test            # node:test via tsx

运行时零依赖（Node 内置 + Pi Extension API）。Pi 直接加载 TypeScript 入口，无需构建。

添加供应商：在 src/providers/<name>.ts 实现 UsageProvider（认证策略、白名单、脱敏规则），在 registry.ts 注册并在 index.ts 的 PROVIDER_HOSTS 登记，添加测试（401/403/429/5xx、超时、白名单、脱敏）。

Z.ai 适配器参照官方 glm-plan-usage 插件实现：端点从配置的 base URL origin 推导（model-usage、tool-usage、quota/limit）。解析逻辑隔离在 src/providers/zai.ts。

商标与免责声明

• 本项目与 Z.ai / 智谱、DeepSeek、OpenRouter 或任何其他供应商无隶属、无合作、未受其背书或赞助。各供应商名称与商标归其所有者所有，仅用于指明所查询的服务（指明性合理使用）。
• 用量查询均为只读，使用 Pi 已持有的用户本人账号凭证，低频固定频率（每 2 分钟一次）。遵守各供应商服务条款是用户自身的责任。
• Z.ai 适配器参照上游 glm-plan-usage 插件（Apache-2.0，智谱）的端点行为实现，本仓库不包含任何上游代码。

许可证

Apache-2.0. Copyright © 2026 imdlan.