CodexBar 完整技术演进史：从 0.1.0 到 0.58 的菜单栏用量监控架构解析
【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar
CodexBar 是一款无需登录即可展示 OpenAI Codex 与 Claude Code 用量统计的 macOS 菜单栏应用，同时提供跨平台的codexbarCLI。本文基于仓库 CHANGELOG.md 的完整记录（2025-11-16 的 0.1.0 至 2026-09 的 0.58.1），系统梳理其版本迭代脉络、核心功能模块（CLI、Usage & Spend、菜单栏布局、本地成本扫描、Provider 体系、插件引擎、iCloud 同步、Adaptive 刷新）的演进逻辑，并结合 Sources/CodexBarCLI/CLIEntry.swift 等源码说明实际实现。读完本文，你将理解 CodexBar 的架构分层、各版本的关键能力与设计取舍，并能直接上手其 CLI 与配置项。
项目定位：无需登录的用量监控
从 0.1.0 起，CodexBar 的核心承诺就非常明确：不做任何额外登录、不做浏览器爬取，直接从本地数据读取用量。0.1.0 只做三件事：读取 Codex CLI 会话日志中的token_count事件（5 小时窗口 + 周窗口及重置时间）、本地解码auth.json展示账号邮箱与套餐、绘制双条菜单栏图标（上条 5 小时、下条周用量）。全部日志解析在主线之外异步进行，并开启了严格并发编译标志。
这一"本地优先"的设计哲学贯穿整个项目：即使后来加入了 OpenAI Web、浏览器 Cookie 等数据源，所有读取都是只读的，且逐步引入了隐私脱敏（"Hide personal information"）与账号隔离机制。
版本演进脉络：三大阶段
通读 2568 行的 CHANGELOG，可以清晰看到 CodexBar 经历了三个阶段：
第一阶段（0.1.0 – 0.4.x，2025-11）：双 Provider 奠基
- 0.1.0：Codex 用量条、刷新频率、About 链接、签名/公证脚本。
- 0.3.0：通过 PTY 读取
codex /status获得 Credits 支持；登录窗口与 Cookie 复用。 - 0.4.0：加入 Claude Code 支持——专属 Claude 菜单/图标、双 Provider 双线菜单、
email/org/plan与 Sonnet 用量展示；首个 Preferences 窗口（General/About）。 - 0.5.x：默认刷新频率定为 5 分钟（可调 15 分钟）；Codex 默认走
codex app-serverRPC（PTY/status降级）；Claude 探测并行执行/usage与/status；新增状态页菜单项、Status API、Sparkle 更新。
这一阶段确立了菜单栏应用的骨架：PTY/RPC 探测、缓存降级（"cached credits stay visible on transient timeouts"）、进程组清理防泄漏、-s read-only -a untrusted沙箱化探测。
第二阶段（0.6 – 0.17，2025-12）：CLI 与 Provider 生态扩张
- 0.6.0：内置
codexbarCLI 诞生，提供usage命令与--format text|json、--status。 - 0.7.0：富菜单卡片（内联进度条 + 重置时间），即今天菜单形态的起点。
- 0.8.0：Homebrew 安装
brew install --cask steipete/tap/codexbar；5 小时滑动窗口会话配额通知。 - 0.9.0：可选 OpenAI Web 访问，复用已登录的 Safari/Chrome 会话展示 Code review remaining、用量明细与 Credits 历史——不存储任何凭据。
- 0.10–0.14：Gemini Provider、统一菜单栏图标 + Provider 切换器（Merge Icons）、Antigravity Provider。
- 0.15–0.16：新 Provider 批量落地：Droid (Factory)、Cursor、z.ai、Copilot；Intel Mac (x86_64) 支持；
codexbar cost命令（打印 Codex + Claude 本地成本，text/JSON）；Provider 品牌图标全面换用 SVG。 - 0.17：MiniMax Provider；Keychain 预检提示。
第三阶段（0.18 – 0.58，2026）：架构重写与平台级能力
这一阶段是工程量最密集的时期，每周都有发布。0.18 引入了用量数据源选择器（Codex/Claude 的 auto/web/cli/oauth）、Cookie 缓存、配置驱动的 Provider 设置与config validate/dump。0.38 把设置窗口重写为 System Settings 风格（侧边栏列全部 Provider）。0.45–0.54 期间菜单栏布局编辑器、条件令牌、Usage & Spend 仪表盘、插件引擎、Adaptive 刷新相继落地。0.55–0.58 则聚焦性能优化（扫描提速、缓存复用）与准确性修复。
CLI 命令体系：从单命令到完整工具链
0.6.0 只提供usage，如今codexbar已是一套完整的运维工具链。在 Sources/CodexBarCLI/CLIEntry.swift 中可以看到完整命令分派：
| 命令 | 用途 | 关键参数（来自 CLIHelp.swift） |
|---|---|---|
codexbar usage | 打印启用 Provider 的用量快照 | --format text\|json\|toon、--provider、--account、--all-accounts、--source auto\|web\|cli\|oauth\|api、--status |
codexbar cost | 读取 Claude/Codex 本地日志 + pi/OMP 会话的成本 | --breakdown（Claude 每日/模型明细）、--group-by project\|session、--days、--refresh、--provider-native-only |
codexbar cards | 响应式终端卡片网格 | --brief（紧凑表格）、--json-output |
codexbar dashboard | 输出 dashboard-v1 快照 JSON | --output <path>（原子写文件）、--identity redacted\|full、--timeout |
codexbar serve | localhost HTTP 服务，含内置自动刷新 Web 仪表盘 | --host、--port、--dashboard-token、--allow-plain-http、--refresh-interval |
codexbar sessions | 列出/聚焦本地 Codex、Claude Code、pi、OMP 会话 | --json-v2、sessions focus <id> |
codexbar config | 配置管理 | validate、dump（默认脱敏，--show-secrets还原）、set-api-key、providers、enable、disable |
codexbar hooks watch | 无头环境持续轮询并触发配额/状态变更 Hook | --interval（默认 300s，最小 60s）、--provider、JSON 输出 |
codexbar guard | 配额感知的自动化门禁 | 稳定退出码、显式窗口、JSON 输出、有界抓取 |
codexbar diagnose | 通用脱敏诊断导出 | 各 Provider 附特定元数据 |
codexbar plugins | 本地 JS/TS Provider 插件管理 | list、fetch <id>（需审批绑定） |
codexbar cache clear、codexbar cookie refresh | 缓存与 Cookie 运维 | Provider 作用域清理 |
几个值得注意的工程细节：
- TOON 输出（0.53.0 加入）：
--format toon输出 TOON v4.1 格式的 JSON，专为追求更省 token 的 Agent 消费设计。 - serve 安全：0.27.0 起拒绝非 loopback 的
Host头；0.48.0 加入--dashboard-token令牌门禁并禁止缓存敏感响应，--allow-plain-http需显式开启（0.44.0）。 - dashboard 快照：
--output通过临时文件 + fsync + rename 原子写入（0644），方便静态 webroot 发布。 - Linux 支持：0.37.0 起发布静态 musl 版 x86_64/aarch64 tarball；0.54.0 修复了
codexbar cost在 Linux 上的 SIGSEGV（Bundle.allBundles在 swift-corelibs-foundation 下崩溃，改为检查主可执行路径）。
Usage & Spend 仪表盘：成本溯源与覆盖度
0.44.0 引入了本地 Usage & Spend 视图，0.53.0 完成重建，成为成本可视化的核心模块：
- 成本溯源（cost provenance）与覆盖度计数：所有估算都被明确标注，部分合计显示其覆盖范围，"未定价的东西绝不能伪装成真实账单"（0.53.0）。
- Token 构成、每小时活动热力图、All-time 范围：7d/30d 之外提供 All time（基于 365 天本地历史 + Claude/Cursor 专属快照槽）。
- 自定义定价覆盖层（custom pricing overlay）：精确匹配的定价高于 models.dev 与内置费率，缺失字段保持未知、显式零费率视为免费（0.53.0）。
- OpenCodex 只读导入：可选用
usage.jsonl导入，SQLite 缓存隔离在 CodexBar 自己的缓存目录，且只读。 - 固定时区（pinned IANA day-bucketing timezone）：0.58.0 进一步加入每日账本（daily spend ledger）——按天查看 token、请求与消费，遵循所选时区，明确区分"金额未知"与"零用量"。
- Heatmap 提示框：0.56.5 优化为优先显示在悬停单元格上方，窄网格内不越界。
底层实现分散于多个模块：spend 数据发布在 UsageStore+SpendDashboardPublication.swift，本地扫描在 CostUsageScanExecutor.swift，模型聚合在 SpendDashboardModel.swift 与 SpendDashboardModel+ModelBreakdown.swift。
本地成本扫描：JSONL 解析的持续优化史
CodexBar 的成本计算不依赖 Node CLI，而是轻量扫描本地 JSONL 会话日志（0.12.0，受 ccusage 启发）。CHANGELOG 中这一模块的优化次数最多，是理解其架构的绝佳样本：
- 增量解析：只解析新增的
usage.jsonl条目而非每次重建整个缓存（0.55.1，35k 条日志场景下内存显著下降）。 - 定价一次化：0.55.0 用预解析的 models.dev 目录 + 自定义定价覆盖层，把每次
usage.jsonl条目定价一次，35k 条目日志的刷新从约 12 秒降到约 3 秒。 - 缓存复用：0.57.0 起跨启动复用兼容的成本报告，仅当历史、定价或报告语义变化时刷新。
- SQLite 存储：0.49.0 把成本历史迁入单一 SQLite store——任意语料规模下内存有界、追加速率线性、不再有刷新时的数百 MB JSON 解码。0.49.0 同时修复了"每次保存循环只在一个事务内写入，崩溃/被杀不会让会话行与旧日聚合不一致"的原子性问题。
- 扫描游标持久化：0.54.1 让 priority-turn trace 数据库扫描游标跨重启持久化，避免每次启动全量重扫
logs_2.sqlite（大库上可省数分钟全核 CPU）。 - fork 语义：0.21–0.29 持续修复 fork 会话的重复计数、子代理历史边界（0.58.0 排除显式子代理历史边界之前的继承记录）、父会话出现/变化/解析到不同文件时使 fork 缓存失效。
这一模块在源码中对应 CostUsageScanExecutor.swift、PiSessionCostScanner.swift 与 CodexLocalProjectUsageIndexer.swift。
Provider 生态：从 2 个到 58+ 个
CHANGELOG 记录了每个 Provider 的加入时间：Codex、Claude Code（0.4）、Gemini（0.10）、Antigravity（0.14）、Droid/Factory、Cursor、z.ai、Copilot（0.15）、OpenCode、Vertex AI、Kiro、Kimi、Kimi K2、Augment、Amp、Synthetic（0.18）、MiniMax（0.17）、Warp（0.18-beta.3）、Perplexity、OpenCode Go（0.20）、Mistral（0.23）、Windsurf、Codebuff（0.24）、Manus、MiMo、Qwen、Doubao、Command Code、StepFun、Crof、Venice、OpenAI API（0.25）、GroqCloud、LLM Proxy、Deepgram、ElevenLabs、Grok/xAI（0.27）、T3 Chat、Azure OpenAI（0.28）、Kilo、Ollama、OpenRouter（0.18/0.29）、Zed、Chutes、Poe（0.36）、LiteLLM（0.36）、Notion AI（0.47）、Qwen Cloud、ZoomMate、Alibaba Token Plan（0.46）、Fireworks、IBM Bob（0.49）、ZenMux、ClinePass、LongCat、Neuralwatt（0.44）、Sakana AI、ClawRouter、Wayfinder（0.42）、z.ai（0.18）……0.42.1 的网站更新确认总数已达 58。
每个 Provider 都有多种数据源模式，统称--source：
| 模式 | 说明 |
|---|---|
auto | 按优先级自动回退（如 Codex：OAuth/CLI → Web Cookie） |
web | 复用浏览器 Cookie 读取 Web 仪表盘 |
cli | 直接调用 CLI 二进制（codex app-serverRPC、claude /usage、kiro-cli、agy等） |
oauth | 读取本地 OAuth 凭据（Keychain / 凭据文件） |
api | API Key 直连（OpenAI Admin API、Anthropic Admin API 等） |
Provider 层在源码中的体现是 Sources/CodexBar/Providers 的 164 个 Swift 文件，以及 Sources/CodexBarCore/Providers 的 485 个文件；统一注册表在 ProviderRegistry.swift。
菜单栏与布局：从双条图标到条件令牌
菜单栏是 CodexBar 的门面，其演进路线清晰：
- 0.1–0.7：双条用量图标、Critter 像素图标（Claude 螃蟹、Codex 方块）。
- 0.10：合并图标模式 + Provider 切换器。
- 0.16：percent 模式（品牌图标 + 百分比标签）；0.45 加入 drag-and-drop 布局编辑器（identity/usage/reset/cost/spacing/stacked-line 令牌）。
- 0.54：条件令牌——命名、可复用的 if/then/else 规则，可基于任何可比较块（用量、重置时间、耗尽、pace、余额、成本）测试 1–4 个 AND/OR 子句，跨 23 个语言目录本地化。例如"session > 50% used且session 在 < 2h 内重置"或"剩余余额 >= 5"都可表达。
- 0.58：新增显式重置倒计时与时钟令牌（含条件分支）、Session/Weekly 百分比窗口选择、可见用量行选择（跨全菜单/紧凑菜单/设置预览/Overview 同步）。
- 0.47：Session/Weekly/Auto pace 令牌，渲染带符号 pace 增量（
+11%、-8%、0%）。
实现上，菜单栏逻辑分布在 StatusItemController+MenuBarLayout.swift、MenuBarLayoutEditor.swift 与 MenuBarLayoutConditionalEditor.swift。0.54 的条件求值基于 AdaptiveRefreshPolicyCore.swift 一类的可比较值抽象。
多账号与会话：claude-swap、Codex 工作区与 Agent Sessions
- claude-swap：0.38.1 接受基于只读
claude-swap --list --json的展示型多账号设计；0.40 可切换非活跃账号并立即刷新；0.47 加入紧凑多账号菜单（4+ 账号时活跃账号保留完整卡片，其余压缩为单行，健康目标加星标）。 - Codex 多账号：0.49 起按规范身份调和生活系统与托管账号，账号作用域的用量/历史/仪表盘状态各自独立；0.56.4 确保每个托管账号所选工作区在堆叠刷新、credits、历史、菜单行、对账与 System Account 提升中保持权威。
- Agent Sessions（0.42）：可选用以发现、列出并聚焦本地或 SSH 连接的 Codex/Claude Code 会话；0.56.5 显式强制 Tailscale CLI 模式以避免新版 Tailscale 上的应用二进制崩溃。
自适应刷新与节能
0.38.1 引入 2–30 分钟的自适应节奏（基于菜单使用、低功耗模式、热状态）；0.45 落地 Agent 感知的 Adaptive 模式（同意门槛 + 有界本地活动检测）；0.55 让 ChatGPT.app 内嵌 Codex 也能被识别并保持 5 分钟活跃节奏。0.47 加入默认关闭的全局 Low Power Mode（自动工作限 30 分钟一次，手动刷新始终即时）。核心策略在 AdaptiveRefreshPolicyCore.swift 与 UsageStore+AdaptiveRefresh.swift。
插件引擎：QuickJS 沙箱
0.48.0 引入本地 JavaScript/TypeScript Provider 插件（manifest 驱动的设置、通用菜单卡片、审批约束的网络/Cookie 访问、Sucrase 沙箱转译）。0.49.0 全面切换到 QuickJS 沙箱引擎：每个 QuickJS 上下文跑在专用 4 MiB 栈线程上，每次 JS 入口刷新栈边界并保留 3 MiB 原生余量，深层递归抛出干净的栈溢出错误而非崩溃。Apple 构建保留 JavaScriptCore 作为显式回滚引擎。相关实现见 Sources/CodexBarCore/Plugins。
iCloud 同步与 Keychain 治理
0.47.0 加入 opt-in iCloud 同步（默认关闭）：经 CloudKit 跨 Mac 同步 Provider 配置、精选偏好与逐设备用量快照；API Key/Cookie/Token 走端到端加密字段（独立 opt-out）；hooks 与机器本地路径永不同步；菜单可显示其他 Mac 的账号及最后已知用量（"via <Mac> · 1h ago"）。应用同时开始监视config.json，外部 CLI 编辑实时生效。0.49.0 修复了 CKSyncEngine 委托回调内同步等待导致的致命 CloudKit 断言崩溃。
Keychain 治理贯穿始终：非捆绑进程（dev 构建）改用进程本地缓存而非共享 keychain 项；测试进程全局禁用 keychain 交互；"Avoid Keychain prompts" 使用无提示策略；Claude OAuth 凭据在 Keychain 缓存以减少重复提示。
开发与工程实践
CHANGELOG 中"Development/Internal/Docs"条目揭示了仓库的工程规范：
- 测试：严格并发构建、Swift Testing 迁移、TaskLocal 作用域覆盖隔离、Keychain 测试禁真、120fps 屏录驱动的菜单闪烁自探针（
CODEXBAR_FLICKER_PROBE_DIR）、进程清理测试。 - CI：macOS/Linux 双平台门禁（ci_macos_test_gate.sh、ci_linux_musl_build_gate.sh）、Swift 测试分片（ci_swift_test_by_suite.py）。
- 发布：签名与公证（sign-and-notarize.sh）、Sparkle appcast（make_appcast.sh）、dSYM 路径校验（test_release_dsym_paths.sh）。
- 文档：docs/DEVELOPMENT.md、docs/DEVELOPMENT_SETUP.md 提供了本地构建与配置说明。
结论
从 0.1.0 的单文件日志扫描到 0.58 的多 Provider、多账号、插件化、Web 仪表盘与 Agent 友好 CLI，CodexBar 的 CHANGELOG 完整记录了一个 macOS 工具如何围绕"本地优先、无需登录、诚实定价"三个原则持续演进。对于想要理解其架构、复用其 CLI，或学习 Swift 菜单栏应用工程化的开发者，这份 CHANGELOG 与 Sources 目录中的源码是相互印证的一手材料。
【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
