配额舰队 Simple-With-Us/CodeCaps

CodeCaps

一款 macOS 菜单栏应用，用来查看受支持 AI 套餐的用量与配额窗口。你还可以自己跑一个采集器，在多台 Mac 之间共享可用的读数。

下载 CodeCaps → · 来自 Simple With Us

为什么做这个

CodeCaps 从这台 Mac 上已经登录的受支持 AI 应用和命令行工具里读取可用的用量与配额窗口——不需要往 CodeCaps 里填任何服务商的 API key。可选的推送和拉取连接，能把其他配置好的 Mac 的读数汇总到一个 Glance 弹窗里。

CodeCaps 让本地读数一直显示在菜单栏。如果你跑了采集器，还能把多台 Mac 汇到一个视图里。

显示什么

CodeCaps 有两个界面，内容互不重复。

Glance 是菜单栏弹窗——两秒钟扫一眼用的。每个平台一行，短配额窗口和长配额窗口并排显示：一个标签（5h、7d、1m）、一条用量条、剩余百分比，以及重置倒计时。名称旁边有个双格开关，在 From Mac 和 From Fleet 之间切换，一次只显示一组，并且会记住你的选择，下次启动依然生效；选 From Fleet 时，行会按上报来源分组，每组带一条标题带。标题栏右侧的 All 铃铛会为所有服务商打开重置提醒；关掉它，每行左侧会出现一个浅色铃铛，可以逐个挑选服务商。倒计时只显示最大的两个单位（4d 2h、2h 42m）；把鼠标悬上去，能看到完整数值和重置时间。如果某行的窗口比它的两条计量条多，展开后只显示剩下的窗口，用同样的列排成更多计量条。除了这些开关、Refresh、Settings 和 Open CodeCaps，其余都是只读。

Console 是一个可调整大小的窗口，侧边栏分成 Quotas 和 Settings：Quotas 是全平台总览，加上带搜索的单平台下钻视图；Settings 里是下面五个页面。

平台的主数字怎么选

一个平台可能带不止一个配额窗口，所以每个界面各有各的规则，决定哪个数字打头：

- 折叠的行（Glance 里的行，或 Console 里的卡片）显示最接近上限的新鲜窗口——剩余百分比最低的那个——并配上该窗口自己的重置倒计时。
- 菜单栏有自己的选择器（Menu Bar → Displayed Quota）：Lowest active quota（默认，取高于 0% 里最低的百分比）、Lowest quota（直接取最低百分比，包含 0%），或者按名称固定某一个窗口。
- Console 的 Next Reset 磁贴显示所有平台上所有新鲜窗口里最早的重置时间——不限于哪个窗口接近上限。
Antigravity 出售两个独立的模型池，显示为两行：Gemini（彩色 Gemini 星标）和 Third-Party（同一星标，单色）。把它们合并显示时，一旦 Third-Party 的每周额度用尽，就会立刻显示「Antigravity 0%」，而此时 Gemini 还剩大部分额度。只要某个池的每周窗口归零，它的 5 小时百分比就不再显示——显示为 n/a，而不是一个在当周重置前毫无意义的数字。

重置闹钟

重置闹钟是一种通知，声音在 Settings → Alerts & Alarms 里选择，触发时机是某个配额窗口进入新周期：

- 服务商的最大窗口——每周或每月那个——每次重置都会响铃，哪怕用量从未接近上限，这样你就知道新的一周或一个月开始了。
- 较小的窗口——5 小时那个——只有在刚刚结束的周期里触顶、或达到上限的 20% 以内时，重置才会响铃。

每次重置只响一次。它背后的状态在每次刷新时都会保存，所以 CodeCaps 关闭期间、或更新期间发生的重置，仍会在下次读取时响铃；已经响过的则不会重复。From Mac 和 From Fleet 两行都会响铃，按服务商区分；同一次重置被两边同时报告时只响一次。

服务商

| 服务商 | 读取内容 | 来源 |
| Claude | 配额窗口（5 小时、每周） | ~/.claude/.credentials.json，或 Claude Code-credentials 钥匙串条目 |
| Codex | 速率限制窗口 | ~/.codex/auth.json |
| Antigravity / Gemini | 池化的 Gemini 和 Third-Party 配额，两行（见上） | antigravity-usage 命令行，外加一次到 Antigravity 自带语言服务器的 RPC |
| Cursor | 包含套餐的用量 | Cursor.app 的本地会话数据库（state.vscdb） |
| Grok CLI | 账单/额度，经由 Grok 的命令行代理 | ~/.grok/auth.json |
| Grok Bot | 每周用量，经由 Cursor 的仪表盘服务 | 同一个 Cursor 会话数据库，不同的端点 |
| MiniMax | 按模型和每周的剩余配额 | ~/.mmx/config.json |
| DeepSeek | 不支持 | 基于余额，而非基于窗口。没有本地读取器；拉取到的窗口也会被过滤掉——永远不会出现在任何地方。 |

以上任何一项都不会要求你手动输入凭据——每个读取器都复用命令行已经创建的会话或文件。

CodeCaps 通过 macOS 自带的 security 工具读取 Claude Code 保存的登录信息，所以全新安装无需任何设置，也绝不会自己弹出钥匙串面板。Claude 行上的 Allow Access To Claude Code 按钮（Console → Settings → Sources & Fleet）只有在 macOS 明确拒绝该读取时才会出现；按下它，然后在 macOS 弹出的面板里选择 Always Allow。在负载很重的 Mac 上，Claude 行可能短暂显示「temporarily unavailable」，下次刷新就会恢复。CodeCaps 只读取 Claude Code 保存的登录信息：从不写入、重新授权或删除它。

Fleet Push And Pull

两者默认都关闭，在 Console → Settings → Sources & Fleet 里配置。

推送格式 —— 有两种，推送时选择。生产者 id 是 codecaps（保留 agent-bar 作为可识别的旧别名，实现无缝向后兼容）。

usage_monitor_v2 —— 每个配额窗口一个事件：

{
"schemaVersion": 2,
"producerId": "codecaps",
"producerInstanceId": "Jay's MacBook Pro",
"events": [
{
"eventId": "subq:anthropic:5h-window:2026-09-17T14:00:00Z:2026-09-17T14:41:00Z",
"provider": "anthropic",
"service": "codecaps",
"label": "5h",
"metricType": "quota",
"billingMode": "actual",
"confidence": "actual",
"limit": 100,
"credits": 62.0,
"occurredAt": "2026-09-17T14:41:00Z",
"metadata": {
"bucketId": "5h-window",
"isExhausted": false,
"remainingUnknown": false,
"scale": "percent_0_100",
"source": "codecaps",
"usedPercent": 38.0
},
"tier": "Max 20x"
}
]
}

generic_webhook —— 更简单的外层结构：

{
"format": "codecaps-quotas",
"version": 1,
"generatedAt": "2026-09-17T14:41:00Z",
"machine": "Jay's MacBook Pro",
"count": 1,
"windows": [
{
"id": "anthropic:5h",
"provider": "anthropic",
"label": "5h",
"status": "available",
"isExhausted": false,
"remainingPercent": 62.0,
"resetAt": "2026-09-17T17:53:00Z",
"window": "5h",
"plan": "Max 20x",
"occurredAt": "2026-09-17T14:41:00Z"
}
]
}

拉取。 CodeCaps 读回服务器聚合的窗口（generatedAt、windows[]、可选的 providerGroups[]），作为 Fleet 行。窗口归属哪台机器，取决于它携带的 source/sourceApp —— 目前还没有机器标识字段，所以无法区分的 Mac 会显示为同一个 fleet 来源。

端点规则。 任何主机都要求 HTTPS；只有回环地址（localhost、127.0.0.1、::1）允许明文 HTTP。URL 里带内嵌凭据、查询字符串或片段，一律拒绝。

Token 存储。 Ingest Token 和 Read Token 是仅有的两个密钥，都存进 macOS Keychain，不写配置文件。

BotFleet 本地交接

不依赖任何服务器，CodeCaps 会把一份不含凭据的本地快照写到：

~/Library/Application Support/Usage Monitor/quota-windows.json

供其他本地消费者使用（例如 BotFleet 的 Usage Monitor）。format 是 usage-monitor-local-quotas，version 是 1，同时还有 producer（"codecaps"）、generatedAt、windows 数组，以及可选的 issues 映射 —— 不含服务器 URL、账号标识或 token；写入前会先检查错误字符串里有没有像凭据的内容。文件以 0600 权限写入 0700 目录，通过原子重命名完成。

安装

Homebrew

brew install --cask jaywedgeworth22/tap/codecaps

下载从最新版本下载已签名并公证的 CodeCaps.dmg。

更新

CodeCaps 会自己更新。合并到 main 的每一次改动都会变成一个已签名、已公证的版本；已安装的副本每小时检查一次，在后台下载，并在 CodeCaps 下次不在前台时安装。等不及的话，可以在「设置 ▸ 关于」里点 Check For Updates…。它的工作原理，以及如何回滚某个版本：见 docs/AUTO-UPDATE.md。

从源码构建

要求：macOS 14+，Apple 芯片或 Intel，Xcode Command Line Tools，Swift 5.9+ 工具链。

git clone https://github.com/jaywedgeworth22/codecaps.git
cd codecaps
script/build_and_run.sh # build, install to ~/Applications, and relaunch

其他模式：--install（同上，但不重新启动）；--dev（用单独的 .dev 标识符构建到 dist/，与已安装副本并排启动；--dev-stop 退出它并删除 dist/）；--package（通用 Release 版本，压缩进 dist/，附带一个 SHA-256 文件）；--release（先 --package，再对 app 公证并装订票据，然后构建、签名、公证并装订 dist/CodeCaps.dmg）；--build-only（只生成 dist/CodeCaps.app）。

--package 和 --release 会为 Apple 芯片和 Intel 构建同一个通用二进制文件，并用 lipo -archs 校验。CFBundleShortVersionString 取自仓库根目录的 VERSION 文件，所以发版只需改一处；CFBundleVersion 是提交数。--release 通过 AGENTBAR_NOTARY_PROFILE 指定的钥匙串配置档公证（默认 agentbar-notary），这个配置档你用 xcrun notarytool store-credentials 创建一次即可。

run 和 --install 只保留一份已安装副本，位于 ~/Applications/CodeCaps.app：任何其他 bundle，只要 release 标识符相同，无论是在常见安装位置还是本检出目录的 dist/ 里，都会被移到废纸篓并打印出来，包括仍名为 AgentBar.app 的副本。CODECAPS_PRUNE_DRY_RUN=1 只预览，不移动任何东西；CODECAPS_BUNDLE_ID 用不同的标识符构建，适合有多个检出目录的情况。

签名仍在演进——把它当作当前最佳实践，而不是固定契约。脚本在有 Developer ID Application 身份时用它签名（AGENTBAR_CODESIGN_IDENTITY，或你钥匙串里已有的第一个），找不到或签名超时就退回 ad-hoc（codesign --sign -）。这件事的影响不止 Gatekeeper：稳定的身份能让保存的 token（Sources & Fleet）在多次重新构建后依然可读；用 ad-hoc 的话，每次构建都会得到新身份，保存的 token 之后需要 Re-Authorize Saved Token。

Gatekeeper。 没有稳定身份时——--dev 永远如此——macOS 会拦截首次启动；右键选择「打开」，或执行 xattr -d com.apple.quarantine。--package 会为公证签名，但到此为止；--release 才是真正提交给 Apple 并装订票据的模式，发布的 dmg 打开时毫无警告，靠的就是它。
图标。 assets/ 里的母版是满幅正方形，始终如此。macOS 26 之前的版本不会给应用图标加遮罩，所以 script/make_icon.swift 在构建时推导出 macOS 形状——把母版画进 1024 画布上的 824x824 圆角矩形，再配上标准投影——.icns 就由它生成。母版文件只读不改。

设置

Console 的侧边栏有五个设置页。

- Menu Bar —— 图标显示在哪里（菜单栏、Dock，或两者都显示），外加它的 Displayed Quota 选择器（见上文）。
- Platforms —— 平台列表顺序，Glance、Console 和菜单栏共用。
- Sources & Fleet —— 三组：This Mac（读取器开关，每个平台一行状态）、Share This Mac（推送：Ingest Endpoint、Ingest Token、Payload Format、Save & Push Now）、Pull The Fleet（拉取：Quota Endpoint、Read Token、Save & Fetch Now）。两个 fleet 组还提供 Forget Token，另外只在已保存的 token 读不回来时，才提供 Re-Authorize Saved Token。
- Appearance —— Light、Dark 或 System；System 跟随你的 Mac 设置，也是默认值。
- About —— 版本、推送/拉取/本地读取器状态，以及项目页链接。

隐私

- 绝不索要服务商的 API key；每个命令行自己的凭据文件、Keychain 条目或会话数据库都按原样复用。
- 在你打开推送或拉取并自己填入 endpoint 之前，什么都不会离开这台 Mac；字段默认为空。
- Ingest Token 和 Read Token 是仅有的两个存储的密钥，都存在 Keychain 里。
- endpoint 按上文规则校验（HTTPS、仅限 loopback 的 HTTP、不允许内嵌凭据/查询/片段）。
- 本地交接文件只携带配额读数——不含 token、endpoint 或账号标识。

服务商标记

每个标记都是模板图像——只用它的轮廓，颜色取自标签。claude.svg、openai.svg、grok.svg、minimax.svg 和 gemini.svg 是 BotFleet 自己的资产（受其源许可证约束）；Antigravity 复用 Gemini 标记，Grok CLI/Grok Bot 复用 Grok 标记。cursor.svg 来自 Simple Icons，CC0 1.0；详情见 Sources/CodeCaps/Resources/ProviderMarks/README.md。

开发

swift build
swift test

同时从多个 checkout 构建时，参见上文的 AGENTBAR_BUNDLE_ID。

日志

构建和公证的输出写到 $TMPDIR/CodeCaps-build-<pid>.log（每次运行一个文件）。应用本身默认不写日志文件——菜单/弹出框的诊断信息看 Console.app →「CodeCaps」，更深入的内容用 log show --process CodeCaps --last 1h。

许可证

Apache License 2.0。

商标

服务商名称和标记归其所有者所有，仅用于标识相应服务。