# @astrosheep/pi-quota 中文文档

规范地址：https://npmcn.com/package/%40astrosheep/pi-quota/

版本：0\.13\.2
npm 元数据更新时间：2026-10-28T06:19:32.802Z
中文译文更新时间：2026-11-07T01:25:55.702Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40astrosheep/pi-quota
原文对照：https://npmcn.com/package/%40astrosheep/pi-quota/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：195 kB，63 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-09-22T23:47:48.736Z
- 最新版本发布：2026-10-28T06:19:32.626Z
- 近 30 天下载量：2669（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

由 Codex, Kimi, OpenCode Go, 新阿庇, DeepSeek, Sub2API 和 YesCode 适配器组成配额栏

## 安装

```sh
npm install @astrosheep/pi-quota
```

也可以使用：`pnpm add @astrosheep/pi-quota`、`yarn add @astrosheep/pi-quota`、`bun add @astrosheep/pi-quota`

## README

# @astroheep/pi-quota (英语)

Pi的契约配额状态: Codex, Kimi, OpenCode Go和DeepSeek在框外工作;新Api,Sub2API和YesCode使用明确的提供方绑定.

```bash
pi install npm:@astrosheep/pi-quota
```

安装或更改设置后重新装入 Pi 。 使用 `/usage` 以持续、无上下文的方式提供拥有配额数据的提供者的快照,包括目前的数据。 使用 `/usage --all` 检查供应商错误。 自动页脚投票从不添加聊天项目 .

## 显示什么

| 仁爱 | 页脚 | `/usage` |
| --- | --- | --- |
| 已知使用期限 | `5h [▆] 72% ↺ 2h15m` | 水平栏、剩余百分比、重置、可用的确切数额 |
| 钱包 | `Bal $12.34` | 与限额和开支分开 |
| 数额限制,没有规定期限 | `Key quota [▇] $85.00` | 剩余百分比加上准确的剩余/使用/上限 |
| 无限制限制 | `Key quota ∞` | 无限制,没有假钱或百分比 |
| 开支 | 未显示 | 今天的费用;终生时间保留在数据中,没有显示 |

百分比总是意味着 **剩余**,没有使用。 未知为 `[?] ?`; 过期的重设为 `↺ due` 并隐藏 Stale 百分比,直到下一个成功查询。 钱包余额永远不会变成百分比 。 历史开支不是配额.

页脚显示每个平衡,然后按适配器顺序限制,默认上限为2个——设置 `quotaUsage.footerWindows` 改为正整数或 `"all"` ——然后是 `+N` 对于它没有显示的限制,只针对目前的提供者。 共同限制比范围限制更可取,因此范围限制可以算入 `+N`。 。 。 . `/usage` 查询所有已配置的支持提供者,并显示按提供者分组的每个余额、限制和“今日”开支条目;它不打开模式,也不向模型发送信息。 捕捉时快照仍被冻结 瞬间查询失败(网络,超时,速率限制或服务出错)将最后一个成功值保存在页脚中. 一个暗淡 `?` 仅出现过一次该快照至少5分钟,并在成功刷新后消失。 没有缓存数据的失败, 或者 auth/ config/schema 错误, 则显示错误 . `/usage --all` 仍然报告查询失败.

## 配置提供者

在全局中添加约束 `~/.pi/agent/settings.json` 下级 `quotaUsage` (不是项目设置):

```json
{
  "quotaUsage": {
    "providers": {
      "my-sub2api": { "adapter": "sub2api" },
      "my-new-api": { "adapter": "new-api", "quotaPerUnit": 500000, "currency": "USD" },
      "deepseek": { "adapter": "deepseek" },
      "opencode-go-2": { "adapter": "opencode-go" },
      "yes-vg": { "adapter": "yescode", "username": "you@example.com", "password": "..." },
      "my-script": { "adapter": "exec", "command": ["my-quota-cli", "--json"], "label": "My Script" },
      "my-alias": { "adapter": "alias", "of": "my-sub2api" }
    }
  }
}
```

使用 **准确的 Pi 提供者 ID**. 询问内置的提供者和明确绑定的提供者;明确装订用相同的ID取代内置的适配器。 未知的密钥或适配器选项被拒绝 。 API 密钥出自 Pi 的提供者 auth,端点出自提供者所注册的模型; 不要将模型 API 密钥放入 `quotaUsage`。 。 。 .

| 适配器 | 终点 | 结果 |
| --- | --- | --- |
| `sub2api` | `{baseUrl}/usage` | 钱包、密钥配额、费率窗口或订阅日/周/月窗口; API-key Today/Lifetime 实际支出 |
| `new-api` | 账户 PAT `/api/user/self`,返回键入式计费/端点 | 账户余额+终生支出;密钥限制(无限或无限),没有发明续作 |
| `deepseek` | 公务 `/user/balance` | 所有报告的货币余额;无发明支出 |
| `opencode-go` | 公务 `https://opencode.ai/zen/go/v1/usage` | 5h/1w/30d 窗口,与内置窗口相同 `opencode-go` 适配器 |
| `yescode` | `co.yes.vg` 登录 会话 `/api/v1/auth/profile` + 键 `/api/v1/user/balance` | 单独订户/现收现付余额加范围订户限额 |
| `exec` | 运行 `command` 作为 argv(无外壳), 将 stdout 当作一个 `QuotaSnapshot` 贾森 | 不论指挥报告如何; `fetchedAt` 由适配器盖章,绝不由命令盖章 |
| `alias` | 无终点——出席大会的代表 `of` 约束(内置或明示) | 共享目标账户的配额; 一行折叠 `/usage` |

捆绑 `opencode-go` 到第二个 OpenCode Go 账户: 注册为自己的 Pi 提供者 `models.json` 拥有自己的 `apiKey` (例如:. `opencode-go-2`然后把身份证绑在这里 内置 `opencode-go` 绑定是隐含的,不需要输入; 保留的ID `openai-codex`, (中文(简体) ), `kimi-coding` 财务报告和审定财务报表 `opencode-go` 不能反弹.

Sub2API 不接受额外的设置;它保存了部署子路径. 仅限利率的密钥不需要暴露出顶级货币(汇率为美元)。 未知的速率窗口持续时间和无效限制失败, 而不是发明出 1d 窗口 。 未加上限的订阅时间省略。 每周重播时使用所报内容 `weekly_window_start` 加上7天;每日/月重播仍然未知,因为这个端点没有提供相应的锚或服务器时区. 它的仪表板 `/api/v1/usage` 是一个单独的, JWT 认证的相接请求日志; 适配器使用 API 键 `/v1/usage` 换句话说.

对于新阿皮, `quotaPerUnit` 默认为 `500000`, (中文(简体) ), `currency` 改为 `USD`可选添加 `dashboardAccessToken` (控制台系统访问符)和 `dashboardUserId` (一些老叉子要求的正数ID)给供应商. 这个PAT是 **仅限** 设置中可选保密 。 账号端点优先;出错会回溯到按键本地计费和符号使用路径. 没有 PAT, API 键不能读取仪表板账户配额 。 有限的关键报告只有当 `total_granted` (b) 其限值保留了精确的用入/保留在 `amounts.limit: null` 和一个未知的百分比。 它永远不会变成钱包. `unlimited_quota` 和遗产账单的无限 哨兵变成无限 **限制**而不是无限的平衡 设置和服务器出错机构的值从未被登录 .

对于YesCode, `username` 是账户电子邮件和 `password` 账户密码; 两者都留在全局 `settings.json`,这是这个适配器的取舍。 YesCode 拒绝账户端点上的 API 密钥( “ 需要用户会话或 JWT ”) , 因此适配器日志通过 `/api/v1/auth/login`,将发行的cookie/JWT缓存到内存~23小时,并在认证失败时重新登录一次。 模型 `cr_` 密钥从不发送到账户的端点; 它只将提供者钉入到官员身上 `co.yes.vg` 源代码。 订阅和现收现付余额仍然分开;只有在账户实际设有这些上限时,才列出每日/每周限额。 仅保留明确报告的下一次重置; `last_*_reset` 没有确定未来的时间表.

Exec 在没有 shell 的情况下运行配置的 argv, 并将 stdout 描述为 JSON 对象, 并需要 `balances`, (中文(简体) ), `limits` 财务报告和审定财务报表 `spending` 数组——每个适配器产生的相同的计划,由控制器执行. 这是一个 **断开查询/执行合同迁移**页:1 `windows`, (中文(简体) ), `balance`, (中文(简体) ), `allowance` 财务报告和审定财务报表 `spend` 字段被拒绝,而不是转换. `fetchedAt` 由适配器盖章; 命令的值被忽略。 控制器将每个查询(10s default)绑定,在超时时杀死了孩子;非零出局,无法读取的JSON和超过256KB的输出会成为出错,命令输出永远不会被登录. 这孩子继承了皮的环境,所以在阴道中保守秘密,而不是在 `quotaUsage`。 。 。 .

将第二个提供者ID绑定在同一账户: `"of"` 名称真正的绑定,它可以是内置的或明确的适配器。 其别名从不自问——关于别名的会话显示目标在页脚上的配额,在目标的身份和证书下被询问,以及 `/usage` 将别名折叠到目标单行中,并随同折叠后的会话针(和 ). 异想天开 `of` 目标没有配置的别名显然失效而不是消失.

认证配额 URL 必须使用 HTTPS, 但本地部署的 HTTP 回放除外 。 URL用户信息,查询字符串,片段和HTTP重定向被拒绝;证书从不跟随重定向. 固定的官方终点拒绝自定义起源. 没有浏览器 cookie 刮取或认证发现 .

## 建筑

```text
Pi model/auth → adapter → QuotaSnapshot → controller → footer / /usage / state event
```

-   `src/query/`: 协议特定解析,认证解析,安全URL,被绑定的GET客户端,状态验证和控制器. 没有Pi/TUI进口.
-   `src/config.ts`:严格的全球供应商约束.
-   `src/bar/`:纯紧凑渲染和持续多供应商聊天卡.
-   `src/extension.ts` 财务报告和审定财务报表 `src/index.ts`: Pi生命周期和Auth桥.

`QuotaSnapshot` 保留三个独立的概念: `balances` (自有钱), `limits` (定期和非定期津贴) `spending` (已报告支出,不一定是钱包借项或限制消费)。 Pi 提供者只选择/宾入适配器;模型没有添加推断出的所有者/账户图. 自定义适配器可以传递到 `createQuotaExtension({ adapters: [...] })`; 见 `examples/custom-provider.ts`. 提供者的别名永远不会被推断出来.

扩展会公布结构状态( O) : `quota-bar:state:v2` 并保存使用卡 `quota-bar:usage:v2`;旧的合同事件/卡不迁移。 使用 `createQuotaExtension({ footer: false })` 在不使用此扩展页脚的情况下消耗它。 正常的查询会被节制,可以被取消,超时被限制,出错后被后退. `/usage` 强制查询每个已配置的辅助提供者,然后从默认视图中省略失败的结果。 切换提供者立即丢弃旧页脚值 .

## 快照计划

以下所有类型均以下列出口命名: `@astrosheep/pi-quota/query`数字 :

```ts
interface Balance {
  id: string;
  label: string;
  currency: string;
  remaining: number;
}
interface LimitAmounts {
  unit: string;
  limit: number | null;
  used: number;
  remaining: number;
}
interface UsageLimit {
  id: string;
  label: string;
  scope?: string;
  remainingPercent: number | null;
  resetAt: number | null;
  durationSeconds?: number;
  amounts?: LimitAmounts;
  unlimited?: true;
}
interface Spending {
  id: string;
  label: string;
  currency: string;
  amount: number;
  period: 'today' | 'lifetime';
}
interface QuotaSnapshot {
  balances: Balance[];
  limits: UsageLimit[];
  spending: Spending[];
  fetchedAt: number;
}
```

-   所有三个阵列都需要,每个阵列最多有64个条目。 只花费快照是有效的;全空快照不是有效的.
-   ID是非空白的,无控制字符串,最多64个字符,独一无二 **每一类别**它们是不透明的,保存得非常准确,从未从持续时间中衍生出来: `5h` 不同身份证的限制仍然不同。 标签/镜片/单元为终端安全进行消毒,被修剪并被限定为64个字符;空白值被拒.
-   货币是三字母大写代码. 平衡是有限的,包括零债务和负债务。 它们不能是无限的.
-   百分比是2004年的限值 `[0, 100]`永远 **剩余**· ; `null` 意为未知. 准确数额和提供者百分比在四舍五入或具体提供者核算后无需商定. `limit` 非阴性或 `null` (上限未报告); `used` (a) 非负性; `remaining` 有限且可能是负数。 金额单位可以是货币或计数,例如: `tokens`编号 :`requests`;计数格式不为钱.
-   无限制的使用 `unlimited: true`, (中文(简体) ), `remainingPercent: null`,没有 `amounts`。未知的盖 (`amounts.limit: null`已经 **没有** 意思是无限的.
-   `fetchedAt` 财务报告和审定财务报表 `resetAt` (一) 为划时代的毫秒; `resetAt` 阳性或 `null`提供的期限必须是正数。 时间/重置时间不明,不能证明没有续约. 没有假定固定/滚动分类或未来重设时间表.
-   支出数额是有限的,不是负数. `today` 表示 **提供者定义的天数**,没有推断出时区。 两个时期都保留在快照中,但页脚省略了支出和 `/usage` 只显示今天.

例如,执行命令可以发出此命令( 无) `fetchedAt` 所需:

```json
{
  "balances": [{ "id": "wallet", "label": "Balance", "currency": "USD", "remaining": 12.34 }],
  "limits": [{
    "id": "requests", "label": "Requests", "remainingPercent": 80, "resetAt": null,
    "amounts": { "unit": "requests", "limit": 100, "used": 20, "remaining": 80 }
  }],
  "spending": [{ "id": "today", "label": "Reported spend", "currency": "USD", "amount": 2.5, "period": "today" }]
}
```

## 独立查询层

非 Pi 消费者( 桥口、 插件、 脚本) 可以导入查询层, 而无需拉入 Pi 扩展名或其对等依赖性 :

```ts
import {
  AdapterRegistry, codexAdapter, createJsonClient, createPostJsonClient,
} from '@astrosheep/pi-quota/query';

const registry = new AdapterRegistry([codexAdapter]);
const snapshot = await registry.get('openai-codex')!.query({
  provider: 'openai-codex',
  signal: AbortSignal.timeout(10_000),
  now: () => Date.now(),
  getAuth: myAuthResolver,      // you supply credentials
  getJson: createJsonClient(),
  postJson: createPostJsonClient(),
});
```

子路径导出每个适配器, 注册/ 控制器, 选项校验器, HTTP/ exec pypution, 以及所有查询类型 。 同伴依赖是可选择的,因此仅为查询层安装就保持了光线.

## 发展

需要节点22.18和相容的Pi安装.

```bash
npm install --ignore-scripts
npm test
npm run typecheck
npm run build
npm run demo
```

## 常见问题

### @astrosheep/pi-quota 是什么？

由 Codex, Kimi, OpenCode Go, 新阿庇, DeepSeek, Sub2API 和 YesCode 适配器组成配额栏

### 如何安装 @astrosheep/pi-quota？

在项目目录运行 npm install @astrosheep/pi-quota，或使用 pnpm add / yarn add / bun add。

### @astrosheep/pi-quota 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @astrosheep/pi-quota 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @astrosheep/pi-quota 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @astrosheep/pi-quota 可以商用吗？

@astrosheep/pi-quota 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @astrosheep/pi-quota 的下载量有多少？

根据 npm 官方下载统计，@astrosheep/pi-quota 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,669 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @astrosheep/pi-quota 还在维护吗？

最新版本 0\.13\.2 发布于 2026/10/28（10 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/09/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。