@andy8647/pi-balance1.1.0
Pi extension that displays provider account balance in the status bar.
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
pi 编码助手的 AI 提供商余额实时显示扩展
在 pi 状态栏中一键查看你的 API 额度余额
截图中的余额段由 pi-starline 渲染 —— Starship 风格的 pi powerline 状态栏。
上：Kimi Code 5h/7d 配额 · 下：DeepSeek 余额
📋 功能特性
pi-balance 是 pi 编码代理 的一款扩展，能够自动获取并在 pi 状态栏中实时显示你的 AI 提供商 API 额度余额。
说明：本仓库是 DragonYH/pi-balance 的 fork，原扩展的全部功劳归 @DragonYH。本 fork 以
@andy8647/pi-balance发布，并新增了：
- Kimi 编码套餐支持 —— 5 小时限速窗口与 7 天配额显示（通过
/usages接口），以及 booster 钱包余额- DeepSeek 多币种余额的稳定识别（
balance_infos）- 零构建打包 —— 直接发布 TypeScript 源码（pi 原生加载
.ts扩展），安装时无需编译
- ✅ 自动识别当前使用的模型提供商
- ✅ 事件驱动刷新 —— 每次对话结束后自动更新余额；pill 只显示数字，增减（▲▼）在气泡里
- ✅ 切换即更新—— 切换模型或提供商时立即刷新
- ✅ 多提供商支持 —— DeepSeek、Moonshot/Kimi、OpenRouter、Sub2Api、OpenAI Codex 及兼容 API
- ✅ 余额接口零配置 —— 支持的余额接口可复用模型 headers
- ✅ 优雅降级 —— 无法获取余额时自动隐藏，不干扰使用
- ✅ 国际化支持 —— 简体中文与英文，支持
/balance lang <zh-CN|en>切换
📦 安装
方式一：从 npm 安装（推荐）
pi install npm:@andy8647/pi-balance
方式二：从 GitHub 安装
pi install git:github.com/Andy8647/pi-balance
方式三：本地开发安装
git clone https://github.com/Andy8647/pi-balance.git
cd pi-balance
npm install
pi install ./
验证安装
重启 pi。连接到一个支持的提供商后，你将在状态栏中看到余额指示器。
🔌 支持的提供商
| 提供商 | 余额接口 | 显示内容 |
|---|---|---|
| DeepSeek | /user/balance |
¥（人民币）余额 |
| Moonshot / Kimi | /v1/users/me/balance |
¥（人民币）可用余额 |
| Sub2Api | /usage |
$（美元）剩余额度 |
| 兼容 API | /usage、/v1/usage |
$（美元）剩余额度 |
| OpenAI Codex | ChatGPT Codex usage API / codex app-server |
5 小时用量剩余；7 天窗口、重置倒计时与重置卡次数在 bubble 里 |
| OpenRouter | /v1/credits |
$（美元）剩余额度 |
扩展会根据你当前的模型配置自动检测所使用的提供商 —— 无需手动设置。
🚀 使用
安装完成后，pi-balance 会完全自动地工作：
- 会话启动时 —— 立即获取余额
- 切换模型时 —— 刷新新提供商的余额
- 每次对话后（
agent_end）—— 刷新余额并记下变化（▲▼），留给气泡显示
余额会显示在 pi 终端底部的状态栏中：
DeepSeek: ¥49.87
如果扩展无法确定你的余额（例如不支持的提供商或网络问题），状态栏条目会优雅隐藏。
/balance 命令
使用 /balance 打开交互式配置菜单，可以：
- 查看当前已配置 provider 的支持状态
- 展开/折叠 provider，切换显示开关和额外选项
- 在主菜单中直接开关 Sub2Api 子 provider（内联展开，带自动探测）
- 开启或关闭 Codex CLI 回退模式
- 立即刷新当前状态栏
也可以直接使用命令参数：
/balance status
/balance refresh
/balance enable deepseek
/balance disable moonshot
/balance toggle codex
/balance toggle openrouter
/balance toggle sub2api
/balance sub2api # 打开 Sub2Api 子 provider 菜单
/balance sub2api rescan # 重新扫描 Sub2Api provider
/balance lang zh-CN # 切换至简体中文
/balance lang en # 切换至英文
配置说明
- Provider 显示开关 会由
/balance菜单保存，并在下一次刷新时生效。 - 自定义 Sub2Api provider 会从 pi 模型配置中自动探测，并可在主菜单或
/balance sub2api中逐个开启或关闭。修改模型配置后，可使用/balance sub2api rescan重新扫描。 - OpenAI Codex 用量 仅在当前模型 provider 为
openai-codex时显示。扩展会优先复用 pi 的 Codex 订阅认证 headers，并可在可用时回退到codex app-server --listen stdio://；CLI 回退可在/balance菜单中开关。 - 菜单使用智能缓存：展开/折叠 provider 时不会触发任何异步计算，体验即时流畅。
- 网络请求会快速超时；获取失败时状态栏会自动隐藏，不会打断当前会话。
- 装了 pi-starline 时，点余额 pill 会弹出气泡：当前余额（DeepSeek 还会拆出赠送和充值各多少）、和上次相比的变化、多久前更新，以及 Refresh 和 Open /balance 两个操作。没装 pi-starline 时一切照旧。
🧠 工作原理
┌─────────────────────────────────────────────────────────────┐
│ pi 编码代理 │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ [聊天界面] │ │
│ │ │ │
│ ├───────────────────────────────────────────────────────┤ │
│ │ 状态栏: DeepSeek: ¥49.87 ◉ 已连接 │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 扩展: pi-balance ────────────────────────────────────┐ │
│ │ session_start ──► fetchBalance() ──► setStatus() │ │
│ │ model_select ──► fetchBalance() ──► setStatus() │ │
│ │ agent_end ────► refreshBalance(showDelta) │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
事件处理
session_start—— 会话开始时获取余额model_select—— 切换模型/提供商时重新获取agent_end—— 每次对话结束后刷新余额，并记录气泡里显示的增减（▲▼）session_shutdown—— 清理并清除状态
🏗️ 项目结构
pi-balance/
├── src/
│ ├── index.ts # 组装入口，命令注册，生命周期
│ ├── types.ts # 类型定义和常量
│ ├── config.ts # 配置加载/持久化/开关
│ ├── utils.ts # 工具函数（fetch、JSON 解析等）
│ ├── menu.ts # 动态菜单构建与缓存
│ ├── starline-pill.ts # 装了 pi-starline 时让 pill 可点击
│ └── providers/
│ ├── types.ts # BalanceProvider 接口定义
│ ├── registry.ts # Provider 单例注册表
│ ├── deepseek.ts # DeepSeek provider
│ ├── moonshot.ts # Moonshot/Kimi provider
│ ├── openrouter.ts # OpenRouter provider
│ ├── sub2api.ts # Sub2Api + 自动探测
│ └── codex.ts # OpenAI Codex + CLI 回退
│ └── i18n/
│ ├── index.ts # t() 翻译函数与语言检测
│ ├── zh-CN.ts # 中文翻译
│ └── en.ts # 英文翻译
├── tests/
│ └── index.test.ts
├── LICENSE # MIT 许可证
├── README.md # 英文文档
├── README.zh-CN.md # 中文文档
├── package.json # Node.js 与 pi 包清单
└── tsconfig.json # TypeScript 配置
🛠️ 开发者指南
类型检查
npm run typecheck
测试
npm test
发布前检查清单
本项目通过 GitHub Actions 在推送版本 tag 时发布。
发布前请检查 npm 包内容：
npm pack --dry-run
然后创建并推送与 package.json 版本一致的 tag：
git tag vX.Y.Z
git push origin vX.Y.Z
推送 tag 前，请在 npm 为该包配置 Trusted Publishing：
- Publisher：GitHub Actions
- Owner：
Andy8647 - Repository：
pi-balance - Workflow：
publish.yml - Environment：
npm-publish
添加新的提供商
扩展采用可插拔的 provider 架构。要为新提供商添加支持，请在 src/providers/ 中创建一个实现 BalanceProvider 接口的模块，然后在 src/index.ts 中导入它即可触发自动注册：
// src/providers/yourprovider.ts
import type { BalanceProvider } from "./types.js";
import { registry } from "./registry.js";
import type {
BalanceResult,
BalanceConfig,
FetchContext,
ProviderSupport,
} from "../types.js";
import { getJson } from "../utils.js";
export const yourProvider: BalanceProvider = {
key: "yourprovider",
definition: {
key: "yourprovider",
label: "YourProvider",
color: "#FFD700",
},
shouldTry(model, baseUrl) {
return baseUrl.includes("yourprovider.com");
},
async fetchBalance(
ctx: FetchContext,
signal?: AbortSignal,
): Promise<BalanceResult | undefined> {
const data = await getJson(`${ctx.baseUrl}/your/endpoint`, ctx.headers, signal);
const amount = data?.credits_remaining;
return typeof amount === "number" ? { amount, unit: "¥" } : undefined;
},
async getSupport(
ctx: ExtensionContext,
config: BalanceConfig,
): Promise<ProviderSupport> {
return {
provider: this.definition,
configured: true,
details: ["已配置"],
};
},
};
registry.register(yourProvider);
然后在 src/index.ts 中添加一行导入：
import "./providers/yourprovider.js";
完成！provider 会自动注册、出现在 /balance 菜单中并参与余额获取。无需其他代码修改。
📄 许可证
为 pi 编码代理 生态构建
Fork 自 DragonYH/pi-balance · 原扩展作者 @DragonYH
