pi-glm-usage

English | 简体中文

非官方项目。 与智谱 AI / Z.ai 无关联。数据来自 GLM Coding Plan 的用量监控端点—— 该端点未经官方文档化（实现参考了智谱官方工具中的调用方式），可能随时变更或失效。

在 pi coding agent 底部状态栏显示 GLM Coding Plan （国内版 / 国际版）配额用量，提供阈值提醒和 /glm-usage 用量报告。

GLM 5h 34%↻1h40m·W 2%

用法

状态栏

活动模型的供应商为 zai-coding-cn 或 zai 时显示；切换到其他供应商即清除。

GLM 5h ███░░░░░ 34% ↻2h 40m · W ░░░░░░░░ 2%

元素	含义
███░░░░░	该段的 8 格用量条；已用格按阈值颜色显示，空格为暗色
5h / W / M	5 小时滚动 token 窗口 / 周配额 / MCP 月度配额；最多显示两段（先 5h，再 W 或 M）
34%	该窗口已用百分比（整数，0–100）
↻2h 40m	距下一次重置的剩余时间，只标在最先重置的那段上；每 30 秒在本地重算，不发网络请求；7 天内显示星期和时间（↻Sat 05:00），更远显示日期（↻Sep06）
≈2.0h	按当前消耗速率预计的配额耗尽时间（来自持久化快照；仅在耗尽会早于重置时显示）
~	显示值为过期数据：上次刷新失败，保留旧值
颜色	绿 < 50%，黄 50–79%，红 ≥ 80%

阈值提醒

用量越过 80% 或 95% 时提醒一次，同一配额窗口、同一档位不重复提醒：

GLM 5h 配额已用 85%（越过 80%）

用量在阈值附近来回波动时不会重复提示；用量回落 20 个百分点以上后，再次越过阈值会重新提示。 提醒状态写入会话文件，重启后仍生效。

/glm-usage

打开覆盖层，显示全部配额段，以及近 24 小时按模型、按工具的用量明细。 明细端点已在国内版套餐上验证；国际版端点未验证，请求失败时报告退回仅含配额：

GLM Coding Plan — max
  5h window   34% used   resets in 2h 40m
  Weekly      2% used   resets in Sat 05:00
  MCP         1% used   resets in Sep06

Model usage (last 24h):
  GLM-5.3  31436935
  GLM-4.7  296701

（示例取自英文界面。中文界面对应显示为：5小时窗口、周配额、"2h 40m 后重置"等，见下文"界面语言"。）

/glm-usage --json 输出原始合并数据（配额快照、查询窗口、明细数组）， 仅支持 TUI 与 print 模式。

消耗速率与耗尽估计

每次成功获取后，扩展把用量快照追加到 ~/.pi/agent/pi-glm-usage-quota-snapshots.jsonl。消耗速率（每小时百分点）由 同一窗口内最近的三个及以上快照估计；当按该速率配额会在窗口重置之前耗尽时， 状态栏追加 ≈2.0h——另一种情况由 ↻ 倒计时覆盖。文件在达到 1000 行时压缩为 最新的 500 条，不会无限增长。

刷新行为

激活时和执行 /glm-usage 时各请求一次；每轮对话结束后，每 180 秒最多请求一次 （任一 token 窗口用量 ≥ 80% 后缩短为 60 秒）。收到 429 或 5xx 时按 Retry-After 退避； 连续两次凭据校验失败后熔断，不再请求，直到下次切换模型或执行 /glm-usage。 pi -p 无头模式不发任何请求。

安装

npm（会被 pi 包目录 收录）：

pi install npm:@zhaoji-wang/pi-glm-usage

或从 git 安装：

pi install git:github.com/frederick-wang/pi-glm-usage

密钥配置

密钥解析顺序与 pi 一致：

1. ~/.pi/agent/auth.json（或 $PI_CODING_AGENT_DIR/auth.json）——国内版写入 "zai-coding-cn": { "type": "api_key", "key": "…" }，国际版写入 "zai": { … }；
2. 否则读取环境变量 ZAI_CODING_CN_API_KEY / ZAI_API_KEY。

两者同时存在且取值不同时，警告一次，然后使用 auth.json 中的 key（与 pi 的优先级一致）。 auth.json 存在但无法解析时，给出明确错误，不会静默改用环境变量里其他账号的凭据。

界面语言

状态栏本身为语言中立的符号。提示、报告与错误指引遵循 PI_GLM_USAGE_LANG（zh 或 en）； 未设置时读取进程 locale——用户显式设置的中文 locale 视为需要中文；再否则为英文。 --json 的输出字段固定为英文，供脚本读取。

为什么有这个包

npm 上还有一个同名的 pi-glm-usage （无 scope，另一作者维护）。对比（截至 2026-08-27，本包 0.1.1，pi-glm-usage 0.1.2）：

	@zhaoji-wang/pi-glm-usage	pi-glm-usage
国内版端点（open.bigmodel.cn）	支持	不支持
国际版端点（api.z.ai）	支持	支持
切换供应商时清除状态栏	会	不会（始终显示）
详细报告命令	有（/glm-usage、--json）	无
阈值提醒	有	无
退避 / 认证熔断	有	固定 60 秒重试
界面消息语言	中/英（PI_GLM_USAGE_LANG 或 locale；状态栏语言中立）	仅英文
密钥来源	auth.json → 环境变量，冲突时警告	仅 auth.json 的 zai
pi peer 依赖	@earendil-works/pi-coding-agent	改名前的旧包名
公开的单元测试	有	无

若 pi-glm-usage 增加国内版支持，此表将更新或移除。

隐私

不采集任何数据。API key 只在本地读取，仅用于请求套餐自身的监控端点 （open.bigmodel.cn / api.z.ai）。提醒去重状态保存在本地 pi 会话文件中。

限制

• Node 内置 fetch 不读取 HTTPS_PROXY 代理设置。pi 本身能通过代理正常使用时，本扩展的请求仍走直连，状态栏因此可能一直显示过期数据。
• 监控端点没有官方文档。百分比语义在国内版套餐上实测验证过：已用百分比，取值 0–100。 未知单元代码在状态栏中忽略，在报告中按编号原样显示。

开发

本仓库使用 pnpm（版本见 package.json 的 packageManager 字段）。本地开发需要 Node ≥ 23.6（直接运行 TypeScript），CI 使用 Node 24。

pnpm install
pnpm run typecheck
pnpm test
pnpm run live-check  # 读取本机密钥并请求一次真实用量

许可

MIT 许可证，全文见 LICENSE。