内容
# quotabot
[](https://github.com/blisspixel/quotabot/actions/workflows/ci.yml)
[](LICENSE)
**适用于 AI 编程订阅的 quota 计划的 htop。**
查看您在所有 AI 编程订阅中剩余的 quota，集中在一个地方，并将下一个请求路由到有预算的订阅，从而减少与 quota 相关的停顿，避免未使用的 quota 被浪费。
> 仍在早期开发中（0.x）。核心功能已经实现，每天都在使用；预计在 1.0 版本之前会有变化。请参阅 [ROADMAP.md](ROADMAP.md)。
quotabot 做两件事：
1. **显示剩余 quota**：对于您付费的滚动窗口订阅，如 Claude（Pro/Max）、Codex（OpenAI）、Antigravity / Gemini（Google）和 Grok（xAI）。它还会显示支持的**本地 LLM 运行环境**（Ollama、LM Studio、Lemonade）是否已安装或加载，以及对冷启动本地模型的硬件适配估计。
2. **推荐下一个请求的路由**：`quotabot suggest`（以及 MCP 上的相同逻辑）根据置信度加权的使用时间，优先考虑具有预算的订阅，并对即将过期的 quota 提供适度提升，以避免浪费。同时，当订阅额度不足时，它会 fallback 到可达的本地模型，使 AI 工具和代理可以跨账户路由，而不是从耗尽的短窗口中猜测。
它重用您的工具已经存储的令牌，因此大多数提供商无需设置。Claude 和 Codex 使用账户范围的元数据端点，而 Antigravity 读取签入的 IDE 或一次性 quotabot 登录，Grok 可以通过一次性 quotabot 登录保持活动。
<p align="center">
<img src="docs/quotabot-demo.gif" alt="quotabot demo showing the widget, compact strip, 90-day analytics, and top dashboard" width="620">
</p>
<p align="center"><sub>演示模式：桌面小工具、紧凑条、90 天分析视图和 <code>quotabot top</code>。</sub></p>
主要特点：
- **跨平台**：Windows、macOS 和 Linux 上只有一个代码库。
- **易用且美观**：一个小型的无边框小工具，跟随系统亮/暗主题，支持每种配置文件的主题，包括高对比度的黑客模式，固定在顶部或任务栏，折叠成一个小的状态条。
- **有用的分析，无监控**：深入了解您自己的使用模式（分布、可靠性、趋势、平滑和重置感知的最佳运行时间）。输出包含 quota 和路由元数据，但不包含任何提示、代码、模型输出或用户内容。
- **零使用令牌**：quotabot 不进行模型或推理调用，因此其 quota 和路由操作从不消耗使用令牌。
- **顾问，而不是代理**：quotabot 建议下一个请求的路由；您的工具和代理进行调用。它保持在您的请求路径之外，因此无需路由新的内容，也无需信任您的流量 - 只需一个内容盲的元数据信号，帮助您使用您已经付费的订阅。
- **本地优先，您的数据归您所有**：无需 quotabot 账户、托管服务或遥测。令牌、历史、缓存、首选项、配置文件和租约保留在您的机器上。一些实时适配器将凭证和 quota 元数据发送到提供者的元数据端点；Antigravity 还可以执行其提供者要求的账户注册步骤，然后读取 quota。外部警报 webhook 仅限于循环回路，除非您明确允许外部主机。没有路径发送提示、代码、模型输出或其他用户内容。
## 它显示什么
每个提供商都是一张卡片，显示一个滚动窗口的条形图（例如 5 小时和每周窗口）：绿色表示健康，黄色表示紧张，红色表示耗尽，并带有重置倒计时。较长的窗口覆盖较短的窗口，因此如果每周上限已耗尽，则卡片将折叠为单个“每周耗尽 - 2 天后重置”的行，而不是显示一个绿色 5 小时条形图，您无法使用。本地运行时没有 quota，因此它们的卡片报告已安装和加载的模型，并作为路由 fallback。冷启动本地模型根据当前 RAM 和最大 GPU 容量进行保守的元数据评估。它从不加载模型或运行吞吐量探测，并且由于运行时可以分割内存，因此保持建议。
当提供商提供可兑换的离周期重置（Codex 的重置积分）时，quotabot 会在卡片上、 `doctor` 和 `top` 中明确标记，并在桌面应用中通知您一次，以便在窗口耗尽时提供继续工作的方式，而不仅仅是倒计时。
如果新的提供商读取与上一次受信任读取相矛盾，quotabot 不会用拒绝的值替换受信任的缓存。桌面和 `doctor` 显示 **提供商漂移**，并将上一次受信任的 quota 标记为过期。路由将该提供商排除在选择之外，测量的分析不会记录新的样本，直到干净的读取建立恢复。 `quotabot verify` 命名失败的漂移检查，以便可以将数字与提供商自己的使用情况视图进行比较。
## 提供商状态
| 提供商 | 来源 | 实时使用 |
| --- | --- | --- |
| Claude | 账户范围的 OAuth 使用端点；新鲜的 Claude 代码令牌或 quotabot 授权 | 是，认证时 |
| Codex | ChatGPT 使用端点；本地会话 fallback | 是；本地 fallback 标记此机器 |
| Antigravity | Google Cloud Code API（Gemini），令牌重用和刷新 | 是，签入账户；本地 fallback 标记此机器 |
| Grok | gRPC-web 计费端点，令牌从 CLI 重新使用 | 是，新鲜时 |
| Cursor | 本地积分/状态；被动检测免费/Pro | 机会主义 |
| Windsurf | 本地 `cachedPlanInfo`（每天/每周 Cascade quota） | 机会主义 |
| Kiro | 本地积分/状态（CLI+IDE）；被动检测 | 机会主义 |
| Ollama / LM Studio / Lemonade | 本地服务器；已安装和加载的模型 | 运行时 |
| NVIDIA NIM | `NVIDIA_API_KEY` 或 `nvapi` + 安全 `/v1/models` 发现 | 免费试用可用；数字 quota 未知 |
| 手动条目 | 用户输入的限制，已使用计数和重置任何工具 | 自我报告 |
## 安装
**macOS / Linux**
```bash
curl -fsSL https://raw.githubusercontent.com/blisspixel/quotabot/main/install.sh | bash
```
**Windows（PowerShell）**
```powershell
irm https://raw.githubusercontent.com/blisspixel/quotabot/main/install.ps1 | iex
```
这些便捷命令信任 GitHub 通过 TLS 交付的引导脚本；然后下载的发行版存档会进行校验和验证。有关检查-运行前路径和源验证，请参阅 [docs/SETUP.md](docs/SETUP.md#inspect-before-running-the-installer)。
重启终端，然后运行 `quotabot doctor`。当其主机应用具有当前凭证时，Claude 和 Codex 应该立即读取。完整的启动指南，包括空闲机器授权：[docs/SETUP.md](docs/SETUP.md)。
## 在空闲机器上保持提供商活跃
Claude 和 Codex 通常在主机应用维护有效令牌时无需 quotabot 登录。空闲机器可以使用本地 quotabot 拥有的授权。Grok 和 Antigravity 仍然需要设置指南中描述的本地账户发现。无需云项目设置：
```bash
quotabot login claude # 打开浏览器；粘贴它显示的代码
quotabot login codex # 打开浏览器；环路捕获
quotabot login grok # 设备代码流程
quotabot login antigravity # 打开浏览器；使用您想要的账户登录
quotabot doctor # 确认它读取实时
```
## 适用于工具和代理的路由
```bash
quotabot suggest # 平衡提供商推荐
quotabot suggest --local-first # 优先考虑可达的本地运行时
quotabot suggest --task=hard # 一个具体的模型，用于提供的需求
quotabot models # 当前注册表条目，可用性，预算，功能
quotabot watch # 在低绑定窗口上发出警报并命名下一个路由
quotabot verify # 测试一个实时读取以检查真实行为
```
默认设置是刻意的：
| 意图 | 命令 | 默认排序和预算 |
| --- | --- | --- |
| 选择提供商 | `quotabot suggest` | 测量的订阅优先，可达的本地 fallback |
| 优先考虑本地执行 | `quotabot suggest --local-first` | 可达的本地运行时在订阅之前 |
| 选择模型 | `quotabot suggest --task=hard` | 可用的优先；本地运行时，已加载，较轻的提供商层级，然后是余量 |
| 筛选到本地运行时分类 | `quotabot suggest --task=hard --budget=local` | 支持的本地运行时适配器报告的条目；排除 Ollama 云卸载（`-cloud`）模型 |
| 限制 quota 计划和运行时类别 | `quotabot suggest --task=hard --budget=quota` | 测量的包含 quota 加本地运行时条目；排除编目手动和付费 API 类别 |
Ollama 可以通过其本地守护进程（`-cloud` 后缀，例如 `qwen3-coder:480b-cloud`）卸载云模型到 ollama.com，而不是在设备上运行。quotabot 检测后缀，标记模型 `cloud_offloaded`，并将其排除在 `--budget=local` 和免费预算之外，因此 Ollama 云模型永远不会满足仅限本地或免费的策略；它仅在 `--budget=any` 下列出。
`--use-expiring-quota` 仅适用于模型建议，让测量的包含 quota 在本地历史预测有意义的 quota 即将过期时优先于本地。 `--exclude=A,B` 避免提供商进行一次读取。 `--prefer=A,B` 指定提供商偏好，仅重新排序已经可行的候选者（可用且高于舒适阈值），因此它永远不会恢复不可用或已耗尽的路由；偏好也按配置文件保存为 `preference_order`。高级功能、配置文件、帐户、警报、成本策略、报告、校准和源命令在 [docs/USAGE.md](docs/USAGE.md) 中有文档记录。
提供商路由 JSON 还包括一个内容盲的 `quotabot.receipt.v1` 决策收据。它记录快照源和年龄、绑定池、支出分类、原始和调整后的余量、每个路由调整、获胜者的资格、每个替代者的拒绝原因和 fail-soft fallback。其确定性决策 ID 让操作员在 CLI、MCP、HTTP、桌面和 LiteLLM 之间关联相同的决策，而无需记录提示、源文件、模型响应、凭证或异常。
对于代理集成，请使用 [AGENTS.md](AGENTS.md) 中描述的 MCP 服务器。它通过 stdio 或选择加入的环路 HTTP 提供实时和缓存决策、模型过滤器、资源和过期本地预留，并带有可用的 bearer auth。一个较小的纯环路 JSON 端点适用于不支持 MCP 的客户端。对于执行交接，[LiteLLM 示例](integrations/litellm/) 使用 quotabot 的建议进行显式环路身份验证和无惊喜支出类别。 Python 和 TypeScript MCP 示例位于 [integrations/mcp_clients/](integrations/mcp_clients/)。
## 项目布局
```
quotabot/
app/ Flutter桌面应用程序（Windows, macOS, Linux）
collector/ Dart软件包：适配器、标准化模型、身份验证、命令行界面、MCP服务器
integrations/ LiteLLM代理插件和MCP客户端代码片段
docs/ 设置、使用、信任、架构、策略和参考
tools/ 打包、图标和开发者帮助脚本
```
应用程序和收集器都是用Dart编写的；应用程序直接导入收集器。
使用 [文档索引](docs/README.md) 来查找设置、使用、信任和集成指南。
有关产品方向，请参见 [docs/PRODUCT-STRATEGY.md](docs/PRODUCT-STRATEGY.md)；
有关设计和内部实现，请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
安全问题应通过 [SECURITY.md](SECURITY.md) 私密报告。
开发和验证指南在 [CONTRIBUTING.md](CONTRIBUTING.md) 中。
## 免责声明和服务条款
quotabot是一个独立的、非官方的工具。它 **不隶属于、不被任何公司认可或赞助** OpenAI、Anthropic、xAI、Google、Amazon、Cursor、Codeium/Windsurf 或任何其他提供商。所有产品名称、徽标和商标均为其各自所有者的财产，仅在此用于识别正在显示其配额的服务。
quotabot仅生成配额和路由元数据。它优先使用本地状态，对于某些提供商，会进行有界限的身份验证调用到该提供商自己的配额或模型列表端点。Antigravity集合还可以执行提供商所需的帐户注册请求，使其配额端点可用。正常操作可以读取凭证材料并写入本地缓存、历史记录、首选项、授予、手动条目和租约；凭证值永远不会包含在输出中。它不进行模型或推理调用，不发送提示、代码、模型输出或其他用户内容。除非用户明确启用了该主机，否则数据保留在本地， 仅发送提供商元数据请求和警报元数据到外部Webhook：
- **您单独负责确保您的使用符合您连接到的每个提供商的服务条款和可接受的使用政策。**
读取本地状态、重用存储的令牌或自动路由可能受到特定提供商的条款限制；请审查它们并停止使用quotabot与任何提供商的条款冲突的帐户。
- 配额数字是尽力而为的，可能不完整、延迟或错误。不要依赖它们进行计费或合规；请与官方仪表板进行验证。
- quotabot在您的用户配置目录下存储您创建的任何登录令牌。请像保护其他凭证存储一样保护该目录。
在 [Apache License 2.0](LICENSE) 下提供“AS IS”，不提供任何保证。使用quotabot即表示您接受这些条款；如果您不同意，请不要使用它。
