我给 Pi 写了个余额插件：Agent 跑一次，到底花了多少钱？

Pi New API Balance：把 New API 余额、结算补查和扣款差额直接放进终端页脚。

在 Pi 里跑完一轮 Agent，我经常会冒出一个很现实的问题：

刚才这一轮，到底花了多少钱？

以前想确认，只能切回 New API 控制台，刷新页面，再对照调用前后的余额。

偶尔做一次还好。用得频繁以后，这个动作很快就变成一种打断：终端里正在处理代码，浏览器里却还得开着余额页面。更麻烦的是，Agent 已经回复完，不等于上游账单也同步完成。你切过去太早，看到的可能还是旧余额。

所以我写了一个 Pi 扩展：Pi New API Balance。

它没有再造一个管理面板，只是在 Pi 原生页脚增加一项余额状态。Agent 工作、模型用量、上下文占用和 New API 余额，都留在同一个终端里。

项目目前版本为 1.0.1，已经发布到 npm，采用 MIT License。[1][2]

它解决的不是“查余额”，而是少一次上下文切换

New API 控制台本来就能查余额。

如果只看功能，给终端再加一个数字似乎没有多大意义。但实际使用中，问题不在于“有没有余额页面”，而在于余额页面和 Agent 工作流是分开的。

原来的路径是：

Pi 里运行 Agent→ 等待回复完成→ 切到浏览器→ 打开或刷新 New API 控制台→ 查看余额→ 切回终端

插件把它压缩成：

Pi 里运行 Agent→ 页脚自动更新余额

真正省下来的不是几次点击，而是你不需要离开正在工作的上下文。

这也是我没有把它做成独立桌面工具的原因。余额最有价值的时刻，就是 Agent 刚刚结束的那几秒。它应该出现在 Pi 里，而不是另一个窗口里。

一条命令安装

推荐直接从 npm 安装：

pi install npm:pi-newapi-balance

也可以安装 GitHub 仓库版本：

pi install git:github.com/zxbdzh/pi-newapi-balance

重启 Pi，或者在当前会话里执行：

/reload

视频里，我先运行 pi list，确认当前没有安装包，再执行 npm 安装命令。终端返回：

added 1 packageInstalled npm:pi-newapi-balance

图：真实录屏中的安装命令与成功输出。

当前包名、安装来源和版本信息都可以在项目仓库及 npm 页面核对。[1][2]

装好之后，Pi 会多出四个命令

启动 Pi 后，pi-newapi-balance 会出现在 [Extensions] 列表中。

输入 /newa，可以看到四个命令：

图：四个命令直接进入 Pi 的命令补全。

这里没有额外的 GUI，也没有后台管理页。配置、刷新、状态和退出，都沿用 Pi 现有的命令入口。

第一次使用：站点、账号、密码

首次运行：

/newapi-login

插件会依次询问：

1. New API 站点地址2. 账号3. 密码

密码不是普通文本框，而是掩码输入。

图：登录流程第 3/3 步，密码不会直接显示在终端中。

站点地址既可以填写根地址，也可以填写常见的 OpenAI API 地址：

https://newapi.example.comhttps://newapi.example.com/v1

插件会去掉末尾的 /v1 和多余斜杠，再访问 New API 管理端接口。[1]

登录成功后，Pi 会提示：

登录成功，余额已更新

页脚则从：

余额：未登录

变成实际余额。

图：视频演示中登录完成后的页脚状态。

这个变化看起来很小，但它决定了后面所有操作都不用离开 Pi。

真正麻烦的，是异步结算

如果插件只做“每五分钟查一次余额”，实现并不复杂。

真正需要处理的是：Agent 回复完成之后，上游账单什么时候更新？

Pi 提供了 agent_settled 事件。它表示这一轮 Agent 已经真正结束，不会继续自动重试、压缩或调用工具。

插件在这个时点立即刷新余额，随后继续安排三次补查：

agent_settled→ 立即查询→ 没检测到扣款：1 秒后补查→ 仍没检测到：3 秒后补查→ 仍没检测到：6 秒后补查

只要任意一次发现余额下降，就立即取消剩余补查：

余额下降→ 停止剩余补查→ 约 800ms 滚动到新余额→ 红色差额保留 3 秒

为什么要这样做？

因为“Agent 已经结束”和“New API 已经完成结算”不是同一个时刻。

只查一次，容易错过延迟到账的扣款。一直高频轮询，又没有必要。立即、1 秒、3 秒、6 秒这几个时间点，是在反馈速度和请求数量之间做的折中。[1]

还有一个细节：检测到扣款以后，后面的定时任务必须取消。否则页面已经显示了新余额，后台还在继续发请求，不仅浪费，也可能让刷新状态互相覆盖。

一次真实演示：Agent 回复后，差额出现在同一个页脚

视频里，我先登录并获得初始余额，然后向 Pi 输入：

你好！

Agent 返回：

你好！有什么需要我帮你处理的？

本轮结束后，插件捕捉到余额下降，页脚显示新余额，并在旁边给出红色差额。

图：真实录屏中，同一次 Agent 交互结束后的客户端扣款反馈。

这张图能证明的是：客户端在 Agent 回复完成后显示了余额变化和扣款差额。

它不能单凭一张截图证明服务端完整账单链路。要做严格财务核对，仍然应以 New API 后台流水为准。

但对日常使用来说，这已经解决了最直接的问题：我不需要再切到浏览器，才能判断刚才这一轮是否已经结算。

为什么还要做滚动动画

终端页脚的信息很多：目录、Git 分支、Token、上下文占用、模型名称、余额。

如果余额从旧值瞬间变成新值，用户很可能根本注意不到。

所以插件没有直接替换数字，而是做了一个约 800ms 的滚动过程，并把差额单独染成红色，保留约 3 秒。[1]

这里的动画不是为了炫技，而是为了让变化被看见。

同时，动画只在余额实际下降时触发：

• none !important
  • 第一次加载余额，不触发；
• none !important
  • 余额增加，不触发；
• none !important
  • 刷新失败，不触发；
• none !important
  • 只有余额下降，才滚动并显示差额。

这样不会把每次普通刷新都做成视觉噪声。

状态查询、手动刷新和安全退出

自动刷新解决大部分场景，但有时还是需要人工确认。

运行：

/newapi-status

可以查看站点、登录状态、余额、最近更新时间和错误信息。

运行：

/newapi-refresh

可以立即发起一次余额刷新。

不再使用时，运行：

/newapi-logout

视频最后，Pi 明确返回：

已退出并清除本地凭据余额：未登录

这说明 /newapi-logout 已经把当前客户端恢复到未登录状态。严格来说，这仍然是 Pi 的状态反馈，不是磁盘取证，不能替代对文件系统的独立检查。

它并不兼容所有叫“New API”的站点

插件调用的是标准 New API 管理端接口：

POST /api/user/login?turnstile=GET /api/user/self

因此，目标站点需要：

• none !important
  • 允许账号密码登录；
• none !important
  • 登录响应中返回 Session Cookie；
• none !important
  • 用户信息接口仍保持兼容。

以下情况可能无法直接使用：

• none !important
  • 强制 Turnstile；
• none !important
  • SSO 登录；
• none !important
  • 二次验证；
• none !important
  • 修改过用户管理接口；
• none !important
  • 只兼容 OpenAI /v1，但管理端并不是标准 New API。

这里最容易误解的一点是：

OpenAI API 兼容，不等于 New API 管理端兼容。

模型调用能成功，不代表插件一定能用账号密码读取余额。[1]

余额单位不是实时汇率换算

插件按 New API 常见的默认规则，把 quota 除以 500000 后显示为 ¥。[1]

balance = quota / 500000

这只是显示单位换算，不是实时汇率换算，也不是支付平台的法币余额。

如果你的站点修改了额度比例，最终显示值也需要按站点规则理解。

安全边界：账号、密码和 Session 会保存在本机

默认配置文件位于：

~/.pi/agent/newapi-balance.json

其中会保存：

• none !important
  • Base URL；
• none !important
  • 账号；
• none !important
  • 密码；
• none !important
  • Session。

插件会尝试限制文件权限，并在退出时删除新旧配置和已知临时文件。但这些信息仍然以明文保存在本机。[1]

因此我的建议很直接：

1. none !important
   1. 只在可信设备上使用；
2. none !important
   2. 不要把配置文件提交到 Git；
3. none !important
   3. 远程站点尽量使用 HTTPS；
4. none !important
   4. 不要在公开录屏里展示密码库、真实账号和站点凭据；
5. none !important
   5. 不再使用时执行 /newapi-logout。

插件支持 http://，是为了本机开发和可信隔离网络。远程环境使用 HTTP，账号、密码和 Session 都可能在传输中被截获。

为什么它应该是 Pi 扩展，而不是独立应用

这次实现让我更确定一件事：很多小工具的价值，不在于功能有多复杂，而在于它插入了正确的位置。

如果把余额查询做成一个独立应用，我会得到：

又一个窗口又一次切换又一套状态

做成 Pi 扩展以后，它可以直接接入：

• none !important
  • Pi Package 安装与更新；
• none !important
  • 命令系统；
• none !important
  • 原生页脚；
• none !important
  • Agent 生命周期；
• none !important
  • Session 切换和关闭事件。

余额、Agent 调用和结算反馈因此留在同一条工作流里。

这个项目解决的不是一个大问题。

它只是消灭了一个每天可能重复很多次的小动作：切到控制台，看一眼余额，再切回来。

但工具真正好用，往往就是因为少了这种打断。

项目地址

npm 安装：

pi install npm:pi-newapi-balance

GitHub：

https://github.com/zxbdzh/pi-newapi-balance

当前版本：

1.0.1

License：

MIT

如果你也在 Pi 里使用 New API，可以直接安装试试。

余额进入页脚以后，Agent 跑完、是否已经结算、这次变化了多少，终于能在同一个地方看见。

Sources

[1] https://github.com/zxbdzh/pi-newapi-balance — Pi New API Balance GitHub[2] https://www.npmjs.com/package/pi-newapi-balance — pi-newapi-balance on npm

欢迎关注我的公众号【zxb的博客】！