pi-usager

Pi Agent 的用量与计费状态栏 —— 实时显示每轮 / 会话费用、token 与缓存命中率， 以及 GLM / DeepSeek 账户余额。

Usage & billing HUD for Pi Agent — real-time cost, token & cache stats, and multi-provider balance.

pi-usager 不维护任何价格数据。所有单价来自 @foolsecret/pi-pricer 的共享价表 （~/.pi/model-pricing.json），改一处即全生态生效。

---

安装

pi extension add @foolsecret/pi-pricer   # 价格数据源，需单独安装
pi extension add @foolsecret/pi-usager
/price                                   # 建议：核对价格与你的实际付费一致

pi-pricer 声明为可选 peer 依赖，不会自动安装。未安装时用量统计照常，但费用显示 价格未知， 并在首次对话时提示。

版本要求：需 pi-pricer ≥ 0.15.0（Schema v5）。旧版价表（version ≠ 5）会被 pi-pricer 忽略， pi-usager 会提示「内置默认价」而非假装你的配置已生效。

状态栏

~/projects/pi-usager@main +3-5 • my-session   auto∙normal∙deep   💰¥2.12 🦦
↑130.9k ↓24.5k R1.34M CH89.4%·95.1% ¥0.0078/¥0.24·工作日高峰  5.9%/1.00M   glm-5.3-flash • high

字段	含义
~/projects/pi-usager@main	工作目录 + git 分支（+N 已暂存 / -M 未暂存）
• my-session	会话名（空间不足时最先省略）
auto∙normal∙deep	pi-prompt 三轴状态（仅装了 pi-prompt 时出现）
↑ / ↓ / R	累计输入 / 输出 / 缓存命中 token
CH89.4%·95.1%	缓存命中率（本次 · 会话平均），分档着色
¥0.0078/¥0.24	此次回答 / 会话累计预估费用（免费模型显示 FREE）
·工作日高峰	当前命中的计价方案（别名优先），来自 pi-pricer
5.9%/1.00M	上下文使用率 / 模型窗口
glm-5.3-flash • high	模型名 + 思考深度
💰¥2.12	账户余额
🦦 / 🕸️	命中兜底价 / 时段价规则

余额颜色分档：低于告急线（默认 ¥0.50）红 → 低于提醒线（默认 ¥1.00）黄 → 其余主题蓝； 阈值在 /usage config 调整。单行布局把 prompt 状态移到第二行，横向更省空间。

命令

命令	说明
/usage	余额 + 会话用量总览
/usage session	用量与费用明细
/usage balance	立即校准余额
/usage status	开关状态栏余额显示
/usage peak	当前方案结构：方案 / 规则 / 命中链
/usage config	配置：厂商凭证 / 校准间隔 / HUD 开关 / 布局 / 余额颜色 / 查看配置

配置存于 ~/.pi/pi-usager.json（含凭证与余额缓存，勿分享或提交）。 修改价格请用 pi-pricer 的 /price，pi-usager 不提供计价配置入口。

余额机制

余额分两层：

层	来源	说明
校准层（权威）	服务端返回值	会话启动、定时器（默认 5 分钟）、/usage balance 时写入并持久化
估算层（过渡）	每轮实际 token × 当前单价	仅存内存，供两次校准之间显示

显示值 = 上次校准值 − 会话内估算扣减（不钳零；负数为透支预警）。 欠费判定以服务端信号为准：DeepSeek HTTP 402 直接判定；GLM 429 下含多种业务码， 需经余额查询二次确认。任何一次成功对话或查询后自动解除欠费态。

费用为本地估算，非平台账单；GLM 余额接口为控制台端点，可能随平台更新失效。

调试

PI_USAGER_DEBUG=1 pi    # stderr 输出校准 / 扣减 / 翻页 / 欠费 / 价表加载日志

厂商支持

厂商	用量	费用	余额	欠费检测
GLM	✅	由 pi-pricer 定价	✅	✅ 429 + 余额二次确认
DeepSeek	✅	由 pi-pricer 定价	✅	✅ 402
其他	✅	需在 pi-pricer 配置	—	—

兼容性

• 需 pi-pricer ≥ 0.15.0（Schema v5）。
• 从 v1.x 升级：/usage config → 自定义计价 已移除，请在 pi-pricer 的 /price 面板重建等价规则。

License

AGPL-3.0-only。本项目为非官方社区项目，与智谱（Z.ai / BigModel）、DeepSeek 无关联。

---

English

pi-usager is a usage & billing HUD for Pi Agent. It renders live in the status bar: per-turn and cumulative cost estimates, token flow, cache hit rate, and GLM / DeepSeek account balance.

It holds no price data of its own — unit prices come from the shared price table provided by @foolsecret/pi-pricer. Install pi-pricer first (≥ 0.15.0), then pi-usager. Costs are local estimates, not invoices.