一眼掌握 AI 订阅余量、Token 活动与 API 消耗。
原生 macOS 菜单栏工具。数据留在本机，人看界面，调度器读 JSON。
OpenUsage Bar 把 AI 订阅额度、API 消耗、本地编码工具和每日 Token 活动统一到一个原生 SwiftUI 客户端里：菜单栏用于快速判断，详情页用于分析，CLI JSON 和本地只读 API 供调度平台读取。
真实 SwiftUI 界面，使用隔离的合成账本生成。未读取用户账本、Keychain 或真实额度。
当前公开预发布版：0.6.0 RC，用于自愿参加、无遥测的外部 Canary。当前合格外部机器仍为 0 / 5，30 天时钟为
not_started；实时状态见 Canary 跟踪 Issue #33。 支持 Apple Silicon Mac 与 macOS 15 或更高版本。暂未提供 Apple Developer ID 公证包；若 macOS 显示“已损坏”，按下方指引仅移除本 App 的下载隔离属性。
AI 工具越来越多，但用量信息分散在不同地方：
- Codex、Cursor、Kiro 这类订阅型工具关心剩余额度和重置周期。
- MiniMax、StepFun、OpenAI Organization 这类 Provider 关心套餐余量、账单和 API 消耗。
- Claude Code、OpenCode、Hermes、OpenClaw 等本地工具关心本地活动和 Token 历史。
- 自动调度平台需要结构化数据，而不是去解析 UI 文本。
OpenUsage Bar 的定位很明确：
菜单栏：给人看，快速判断今天还能不能继续跑。
详情页：给人分析，看每日 Token、模型趋势、额度历史和数据健康。
本地 API：给调度系统读，稳定 JSON，不依赖 UI 文案。
Keychain：放密钥；SQLite：放账本；日志：不放凭证。
flowchart LR
A[AI Provider 与本地工具] --> B[受限 Python Collector]
K[(macOS Keychain)] --> B
B --> D[(本地 SQLite 账本)]
D --> E[菜单栏快照]
D --> F[Usage Details]
D --> G[CLI JSON 与只读 API]
| 能力 | 说明 |
|---|---|
| 菜单栏总览 | Today Token、最紧急 Capacity、刷新状态和详情入口 |
| Usage Details | Activity、Capacity、API Spend、Local Tools、Providers、Data Health |
| 每日 Token 活动 | 日、周、月、年维度聚合；支持每日总量、模型堆叠趋势和年度方格热力图 |
| Provider Center | 添加、编辑、隐藏、恢复 Provider；支持多账号；凭证只写入 Keychain |
| 订阅额度 | Codex、Cursor、Kiro、MiniMax、StepFun 等可用时显示真实剩余容量 |
| API 消耗 | OpenAI Organization、Generic HTTPS Provider、Daily Token Feed 等结构化接入 |
| 调度接口 | Unix socket 本地只读 API、CLI JSON/JSONL、离线快速读取 |
| 隐私边界 | 不导出 API Key、Cookie、Session、Prompt、Response 或直接账号身份 |
下载 OpenUsage Bar v0.6.0 DMG（Apple Silicon）
- 打开下载的 DMG。
- 将 OpenUsage Bar 拖入 Applications。
- 从访达的“应用程序”打开 OpenUsage Bar。
- App 自动注册登录启动项和后台采集器，不需要打开终端。
如果 macOS 提示 “OpenUsage Bar 已损坏”，这是尚未公证的开源预发布包被添加了 下载隔离属性。确认 DMG 来自本仓库并已校验 SHA-256 后，在终端中只对该 App 执行：
xattr -dr com.apple.quarantine "/Applications/OpenUsage Bar.app"再从访达的“应用程序”打开。该命令只移除 OpenUsage Bar 的下载隔离属性；不要 全局关闭 Gatekeeper。DMG 根目录也附带同样的中英文安装说明。首次启动若提示后台访问，请在 系统设置 > 通用 > 登录项中允许 OpenUsage Bar。
首次打开后：
- 点击菜单栏里的 OpenUsage Bar。
- 进入 Open Usage Details 查看账本。
- 进入 Settings / Providers 添加或编辑 Provider。
- 后续通常只需查看菜单栏；登录后自动启动，采集器每五分钟刷新。
更多细节、SHA-256 校验和高级修复脚本见安装指南。
需要 Xcode 命令行工具、Swift Package Manager、Python 3.11 或更高版本。
scripts/bootstrap.sh
scripts/build_app.sh
scripts/install_app.sh构建流程会执行：
- Python 与 Swift 测试
- Provider catalog 一致性检查
- Python 与 Swift 关键模块覆盖率门禁
- 凭证与隐私扫描
- Release 构建与 nested helper 签名
- 安装事务、回滚备份和本地 API 健康检查
生成发布包：
scripts/package_release.shOpenUsage Bar.app
├─ 菜单栏状态宿主：轻量、常驻、只展示关键事实
├─ OpenUsage Activity.app：详情窗口，读取同一份 SQLite 账本
├─ OpenUsage Provider Settings.app：Provider 管理与受控 collector 命令
└─ LaunchAgents
├─ com.lune.openusagebar：原生菜单栏宿主
└─ com.lune.openusagebar.collector：后台采集与本地只读 API
本地数据位置：
| 数据 | 路径 |
|---|---|
| 活动账本 | ~/.local/state/openusage-bar/activity.sqlite3 |
| Unix socket | ~/.local/state/openusage-bar/openusage.sock |
| Provider 配置 | ~/.config/openusage-bar/providers.json |
| Provider 可见性 | ~/.config/openusage-bar/visibility.json |
| 日志 | ~/Library/Logs/OpenUsageBar.*.log |
| LaunchAgents | ~/Library/LaunchAgents/com.lune.openusagebar*.plist |
默认没有 TCP 监听。调度平台通过 mode 0700 的 socket 目录和 mode 0600 的 Unix socket 读取数据。
GET /v1/health
GET /v1/schema
GET /v1/schema.json
GET /v1/summary
GET /v1/snapshot
GET /v1/capabilities
GET /v1/providers
GET /v1/providers?providerIds=codex,minimax-primary
GET /v1/capacity
GET /v1/activity/daily?from=2026-07-01&to=2026-07-14
GET /v1/costs/daily?from=2026-07-01&to=2026-07-14
GET /v1/quotas/history
GET /v1/sources/status
GET /v1/changes?after=0&limit=100
/v1/capabilities 不只返回“是否有代码适配器”，还会按数据源声明
Detection、Token Activity、Subscription Capacity、API Spend、权威程度、
账号/模型作用域，以及 live_account、fixture、upstream_declared 或
unverified 验证等级。当前连接是否健康仍以 /v1/sources/status 为准；
两者不能混为一谈。
也可以通过签名的采集器启动器输出 JSON；它会先重建最小非秘密环境：
APP="/Applications/OpenUsage Bar.app"
[[ -d "$APP" ]] || APP="$HOME/Applications/OpenUsage Bar.app"
COLLECTOR="$APP/Contents/MacOS/OpenUsage Collector"
"$COLLECTOR" status --format json --offline
"$COLLECTOR" providers --format json --offline
"$COLLECTOR" usage --from 2026-07-01 --to 2026-07-14 --format jsonl --offline
"$COLLECTOR" doctor --format json --offline--offline 适合调度器低延迟读取。显式 --fresh 和菜单栏 Refresh 共用
160 秒交互尝试上限。支持精确 Provider 导出的 OpenUsage 会让 Cursor 使用
15 秒的独立采集边界；旧版 OpenUsage 继续使用最长 75 秒的全量 direct
fallback，完整 OpenUsage daily import 最长 60 秒。超时不会把未知额度写成
0，而是继续提供 last-good ledger 并报告刷新不可用。
OpenUsage Bar 是独立仓库和独立发布。OpenUsage.sh 是可选数据源，只通过受限 JSON 接入；它的 Go 内部实现、凭证和发布周期不会嵌入本项目。
- OpenUsage 0.23.0 catalog：覆盖 35 个上游 family。
- 内置增强：MiniMax、StepFun、Codex、Cursor、Kiro、OpenAI Organization、Generic HTTPS Provider、Custom Daily Token Feed。
- MiniMax：中国站与国际站账号严格隔离，订阅额度与中国站实验性延迟 billing feed 分离；国际站未验证的历史用量和当前日缺失都不会显示为 0。
- StepFun：支持中国站和国际站多账号。
- Generic HTTPS Provider：校验 endpoint、redirect、响应大小和 JSON path。
- Daily Token Feed：支持 range-aware HTTPS JSON、字段映射、分页和 Keychain 鉴权。
完整边界见 Provider support。
OpenUsage Bar 的安全模型是“凭证只进 Keychain，事实才进账本”：
- 不在 SQLite、JSON、JSONL、本地 API、UI 或日志中保存 API Key、Cookie、Session。
- 不采集 Prompt、Response 或直接账号身份。
- Provider 子进程使用最小 allowlist 环境和超时边界。
- 未知额度保持 Unknown，不伪装成 0。
- 隐藏 Provider 只影响展示，不删除凭证或历史账本。
安全问题请按 SECURITY.md 私密上报，不要公开提交含凭证的 issue。
临时停止：
launchctl bootout gui/$(id -u)/com.lune.openusagebar
launchctl bootout gui/$(id -u)/com.lune.openusagebar.collector卸载 App 与 LaunchAgents：
scripts/uninstall_app.sh连本地账本和配置一起删除：
scripts/uninstall_app.sh --purge-dataKeychain 项不会自动删除。只有确认没有其他本地安装在使用同一 service entry 后，才应该在 Keychain Access 中手动移除。
修改 adapter、账本字段、导出 API 或 Provider 能力前，请先读 CONTRIBUTING.md。核心原则：
- SwiftUI 只读展示，Python adapter 负责凭证与账本写入。
- 新 Provider 优先复用现有工具或官方数据源，无法复用再新增 adapter。
- 不新增第三方 UI、图表、数据库、状态管理或依赖注入包。
- 任何 Unknown 都不能被降级成 0。
OpenUsage Bar 使用 Apache License 2.0。运行时依赖和互操作边界见 THIRD_PARTY_NOTICES.md。