开源AI编程助手用量监控器MeterBar：SwiftUI实现零配置实时监控

1. 项目概述一个为AI编程助手打造的用量监控器如果你和我一样日常开发重度依赖像Claude Code、Cursor这类AI编程助手那你肯定也经历过那种“额度焦虑”——不知道今天还剩多少额度生怕在关键时刻突然被限流。每次都要打开终端敲命令或者去网页后台翻找既打断了思路也相当麻烦。MeterBar这个开源项目就是为了解决这个痛点而生的。它是一个纯粹的macOS菜单栏应用核心目标就一个把你所有AI编程助手的用量信息集中、实时地展示在屏幕右上角让你一目了然。简单来说它就像一个为AI编程工具量身定做的“流量监控仪表盘”。目前它原生支持三大主流工具Anthropic的Claude Code、OpenAI的Codex CLI也就是ChatGPT的官方命令行工具以及风头正劲的Cursor IDE。最让我欣赏的设计是它的“零配置”理念。它不会要求你输入任何新的API密钥而是巧妙地读取这些工具官方CLI登录后在你本地生成的认证文件比如OAuth令牌。这意味着只要你已经用claude login或codex login登录过MeterBar就能自动获取权限安全地帮你拉取用量数据。整个应用采用SwiftUI构建体积轻巧运行在macOS的App Sandbox沙盒环境中隐私和安全有保障。2. 核心设计思路与架构解析2.1 解决的核心痛点与设计哲学在深入代码之前理解MeterBar要解决什么问题至关重要。现代AI编程助手通常采用配额制比如Claude Code的“5小时会话时长7天总时长”或者Cursor的月度使用限制。开发者面临几个麻烦第一信息分散。每个工具都有自己的查询方式没有统一入口。第二查询过程繁琐。要么是命令行要么是网页无法实现“瞟一眼就知道”的便捷。第三缺乏预警。往往是用超了才发现影响工作流。MeterBar的设计哲学非常明确无感监控与极简呈现。它将自己定位为一个纯粹的“观察者”和“展示器”而非“控制器”。它不管理你的账户不存储你的密钥只做两件事1. 从可信的本地源官方CLI的缓存安全读取认证信息2. 定期向官方API请求用量数据并格式化展示。这种设计最大限度地减少了安全风险也降低了用户的使用门槛——你只需要像平常一样登录一次CLI剩下的就交给MeterBar。2.2 技术栈选型背后的考量项目选择了苹果生态最新的技术栈这并非盲目追新而是有着充分的实践理由SwiftUI Combine这是构建现代macOS菜单栏应用的黄金组合。SwiftUI的声明式语法让构建复杂的、状态驱动的UI如可折叠的卡片、动态进度条变得异常清晰。Combine框架则完美处理了异步数据流例如定时刷新、多个API请求的并发与合并。当从三个不同的服务获取数据时Combine的Publishers.Merge或Publishers.Zip可以优雅地处理这些异步操作并将结果统一推送给UI更新。macOS App Sandbox对于需要访问特定用户目录如~/.claude.ai/的应用沙盒机制是双刃剑。MeterBar通过声明精确的“文件访问”权限com.apple.security.files.user-selected.read-only和com.apple.security.files.bookmarks.app-scope在保障系统安全的前提下获得了读取这些特定路径的资格。这是开发类似工具时必须仔细处理的一环否则应用在发布后根本无法运行。原生网络与存储使用URLSession进行网络请求使用Core Data或简单的UserDefaults进行本地缓存如上次刷新时间、窗口状态确保了应用的性能和稳定性避免了引入第三方库可能带来的依赖冲突和包体积膨胀。2.3 数据流与模块化架构从代码结构看MeterBar采用了清晰的MVModel-View模式数据流是单向的数据层Model这是应用的核心。为每个支持的服务Claude、Codex、Cursor定义了独立的Provider协议和实现类。每个Provider负责三件事凭证发现在预定义的路径如~/.codex/auth.json查找并解析令牌。API交互构造带有认证头的HTTP请求调用对应的用量查询接口。数据解析将API返回的JSON映射为统一的内部UsageData模型包含用量、限额、重置时间等。视图层View由SwiftUI组件构成。主视图是一个MenuBarExtra点击后弹出包含多个ServiceCardView的窗口。每个卡片视图订阅对应的Provider提供的数据并根据用量百分比动态计算进度条宽度和颜色绿/黄/红。协调层ViewModel/Manager一个中央的UsageMonitor类或类似角色使用Combine定时器每隔15分钟触发一次所有Provider的数据获取任务并将结果聚合后分发给各个视图。这里还处理了错误状态如“未配置”、“网络错误”并提供了手动刷新按钮的触发逻辑。这种模块化设计的好处是扩展性极强。如果要新增对另一个AI服务比如GitHub Copilot的支持开发者基本上只需要做两件事实现一个新的Provider以及在UI列表中添加一个对应的卡片视图。核心的监控逻辑和UI框架完全复用。3. 核心功能深度解析与实操要点3.1 多服务凭证的自动发现机制这是MeterBar“零配置”魔法的关键。我们来看看它是如何在不询问用户密码的情况下获得访问权限的。Claude Code当你运行claude login时Anthropic的CLI工具会在~/.claude.ai/目录下创建一个包含OAuth刷新令牌的文件。MeterBar的Claude Provider会尝试读取这个目录。它并不是直接读取原始令牌文件更安全的方式是模拟CLI的行为使用系统钥匙串或该工具提供的特定令牌管理方式。在实际代码中可能需要解析config.json或调用CLI的某个内部命令来获取当前有效的访问令牌。Codex CLIOpenAI的Codex CLI将认证信息存储在~/.codex/auth.json中。这个JSON文件结构相对清晰通常包含access_token、refresh_token和expiry等字段。MeterBar的Codex Provider读取这个文件提取access_token并将其作为Bearer Token添加到请求头中用于调用OpenAI的用量查询接口。CursorCursor的情况比较特殊因为它是一个桌面IDE数据存储在本地SQLite数据库中。路径通常在~/Library/Application Support/Cursor/下。MeterBar需要获得沙盒权限来读取这个目录并执行SQL查询来获取月度使用数据。这里需要注意数据库 schema 可能随Cursor版本更新而变化因此代码中需要做一定的版本兼容性处理或提供明确的错误提示。注意这种自动发现机制依赖于这些工具CLI的默认行为和数据存储路径。如果未来某个工具改变了其认证文件的存储位置或格式MeterBar可能需要相应更新。这也是开源项目的一个优势社区可以快速响应这类变化。3.2 实时监控与状态可视化MeterBar的UI设计充分考虑了信息密度和可读性菜单栏图标通常显示一个聚合状态比如如果任一服务用量超过80%图标可能显示为橙色或红色圆点提供最高级别的警报。可折叠卡片这是UI的精华。默认折叠状态只显示服务名称和一个细长的水平进度条颜色代表状态。这让你在0.5秒内就能评估所有服务的“健康度”。点击卡片头部展开查看详情具体的使用量/限额数字、精确的百分比、配额重置的倒计时例如“3天12小时后重置”以及订阅类型如“Team”、“Pro”。颜色编码系统这是一个非常直观的反馈机制。绿色50%放心使用。黄色50%-80%需要开始留意考虑优化使用方式比如对非关键性的代码生成可以降低使用频率。红色80%危险区域应避免进行大型或复杂的生成任务优先使用本地智能补全或其他工具。实操心得这个颜色阈值是可以根据个人偏好调整的。比如如果你对某个服务依赖度极高可能希望把黄色预警线提前到40%。在MeterBar的代码中这些阈值很可能被定义为常量你可以通过修改源码并自行编译来定制。3.3 内置CLI工具的应用场景除了图形界面MeterBar还附带了一个命令行工具这个设计非常贴心拓宽了它的使用场景自动化脚本集成你可以写一个Shell脚本每天上午通过meterbar usage --json获取用量数据如果某个服务超过70%就自动发送一个通知到Slack或钉钉。无头服务器监控如果你在远程服务器也是macOS上使用Codex CLI进行一些自动化任务你可以通过CLI工具定期检查额度防止任务中途失败。快速查询对于习惯终端的开发者直接敲命令比用鼠标点开菜单栏更快。成本追踪meterbar cost命令可以统计近期的token消耗对于需要向公司报销或控制预算的团队非常有用。CLI工具的实现通常是主应用的一个Helper或者共享了核心的数据获取模块。通过Process或XPC与主应用通信获取数据后再格式化输出到标准输出。4. 从零到一的构建与部署实践4.1 开发环境搭建与项目初始化假设你是一名macOS开发者想基于MeterBar的思路为自己监控的工具定制一个类似应用或者想为MeterBar贡献代码以下是详细的起步指南首先确保你的环境符合要求# 检查系统版本 sw_vers -productVersion # 确保 13.0 (Ventura) # 检查Xcode命令行工具 xcode-select -p # 如果没有安装xcode-select --install # 克隆项目代码 git clone https://github.com/shipshitdev/meterbar.app.git cd meterbar.app打开项目最直接的方式是使用Xcodeopen MeterBar.xcodeproj或者如果你更喜欢纯命令行工作流也可以用xcodebuild# 解析项目依赖如果使用了Swift Package Manager xcodebuild -resolvePackageDependencies # 构建项目 xcodebuild -project MeterBar.xcodeproj -scheme MeterBar -configuration Release build项目成功打开后花点时间浏览一下主要目录结构MeterBar/主应用代码包含App入口、视图、ViewModel。MeterBarCore/或Shared/核心数据模型、网络管理器、Provider协议和实现。这里是业务的灵魂。MeterBarCLI/命令行工具靶子Target。Resources/图标、资产文件。MeterBar.entitlements沙盒权限配置文件务必仔细检查它决定了应用能访问哪些文件。4.2 关键代码模块剖析与定制让我们深入两个最关键的模块看看如何工作以及如何修改。1. Provider协议的实现示例以Codex为例在Swift中Provider通常会定义一个协议确保所有服务提供者都有相同的行为接口。protocol UsageProvider { var serviceName: String { get } var isConfigured: Bool { get } func fetchUsage() async throws - UsageData } struct UsageData { let used: Int let limit: Int let resetDate: Date? let subscriptionTier: String }CodexProvider会实现这个协议。它的fetchUsage方法大致会做以下几件事class CodexProvider: UsageProvider { private let authFileURL FileManager.default.homeDirectoryForCurrentUser .appendingPathComponent(.codex) .appendingPathComponent(auth.json) var isConfigured: Bool { // 检查认证文件是否存在且可读 FileManager.default.fileExists(atPath: authFileURL.path) } func fetchUsage() async throws - UsageData { guard let authData try? Data(contentsOf: authFileURL), let authJson try? JSONSerialization.jsonObject(with: authData) as? [String: Any], let accessToken authJson[access_token] as? String else { throw ProviderError.notConfigured } var request URLRequest(url: URL(string: https://chatgpt.com/backend-api/wham/usage)!) request.setValue(Bearer \(accessToken), forHTTPHeaderField: Authorization) let (data, _) try await URLSession.shared.data(for: request) let apiResponse try JSONDecoder().decode(CodexAPIResponse.self, from: data) // 将API响应映射为统一的UsageData return UsageData( used: apiResponse.current_usage, limit: apiResponse.usage_limit, resetDate: Date(timeIntervalSince1970: TimeInterval(apiResponse.reset_date)), subscriptionTier: apiResponse.plan_name ) } }2. 主监控循环与状态管理在SwiftUI中通常会用一个ObservableObject例如UsageMonitor来管理所有Provider的状态。MainActor class UsageMonitor: ObservableObject { Published var providers: [any UsageProvider] [] Published var lastUpdated: Date? Published var isLoading false private var timer: Timer? init() { self.providers [ClaudeProvider(), CodexProvider(), CursorProvider()] startMonitoring() } func startMonitoring(interval: TimeInterval 900) { // 默认15分钟 timer?.invalidate() fetchAllUsage() // 立即获取一次 timer Timer.scheduledTimer(withTimeInterval: interval, repeats: true) { [weak self] _ in self?.fetchAllUsage() } } func fetchAllUsage() { Task { isLoading true // 并发获取所有Provider的数据 await withTaskGroup(of: Void.self) { group in for provider in providers where provider.isConfigured { group.addTask { do { let usage try await provider.fetchUsage() // 更新对应Provider的Published状态触发UI更新 await self.updateUsage(for: provider, data: usage) } catch { // 处理错误例如更新为错误状态 await self.handleError(for: provider, error: error) } } } } lastUpdated Date() isLoading false } } }定制建议如果你想添加对新服务的支持比如GitHub Copilot你需要1. 研究Copilot CLI或API如何获取用量可能需要gh copilot status命令或调用GitHub API。2. 创建一个新的CopilotProvider类实现UsageProvider协议。3. 将这个Provider实例添加到UsageMonitor的providers数组中。4.3 打包、签名与分发开发完成后你需要将应用分发给用户。对于个人使用或小范围分享直接归档Archive导出即可。但对于正式分发尤其是通过Homebrew Cask有几个关键步骤代码签名与公证这是macOS应用分发的必经之路。你需要苹果开发者账号在Xcode的“Signing Capabilities”中配置Team和Bundle Identifier。构建Release版本后通过Xcode的“Distribute App”流程将应用上传到App Store Connect进行公证Notarization。公证成功后你会得到一个票据ticket它会被附加到应用上让Gatekeeper放行。创建Homebrew Cask这是MeterBar推荐的安装方式。Homebrew Cask本质上是一个描述如何下载和安装应用的Ruby公式。你需要将公证后的.app文件打包成.zip或.dmg。将安装包上传到一个稳定的托管服务如GitHub Releases。在你的Homebrew Tap仓库中创建一个Cask文件如meterbar.rb其中指定下载URL、校验和sha256、应用名称等信息。cask meterbar do version 1.0.0 sha256 abc123... # 替换为实际zip文件的sha256 url https://github.com/shipshitdev/meterbar.app/releases/download/v#{version}/MeterBar.zip name MeterBar desc Monitor AI coding assistant usage from the menu bar homepage https://github.com/shipshitdev/meterbar.app app MeterBar.app end用户就可以通过brew install --cask shipshitdev/tap/meterbar来安装了。处理沙盒权限这是最容易出错的地方。如果你的应用需要访问像~/Library/Application Support/Cursor/这样的特定路径必须在entitlements文件中声明。即使如此对于从网上下载的非App Store应用用户首次运行时可能仍会遇到权限阻拦。这就是为什么项目README中提到了xattr -cr命令它可以清除某些可能引起Gatekeeper警告的扩展属性。更规范的做法是确保应用经过苹果公证。5. 常见问题排查与实战经验分享在实际使用和开发类似工具的过程中你肯定会遇到一些坑。以下是我总结的一些典型问题及其解决方案。5.1 服务状态显示“未配置”或“无法读取”这是最常见的问题根本原因在于应用找不到或无法解析认证文件。检查步骤确认CLI已登录打开终端运行claude whoami或codex whoami如果该CLI支持确认你处于登录状态。检查文件路径与权限在终端中使用ls -la ~/.claude.ai/或cat ~/.codex/auth.json查看文件是否存在、内容是否正常。确保当前用户有读取权限。检查沙盒权限如果是从源码编译运行确保MeterBar.entitlements文件包含了必要的文件访问权限。如果是从网上下载的预编译版本尝试按照提示在首次运行时右键点击“打开”或在终端执行xattr -cr /Applications/MeterBar.app。查看应用日志在macOS的“控制台”App中筛选进程名为“MeterBar”的日志里面通常会有更详细的错误信息比如“文件读取错误”或“JSON解析失败”。一个典型陷阱某些CLI工具如早期版本的Codex可能会将令牌存储在macOS的钥匙串中而不是明文文件中。这时你的Provider需要调用Security框架的API如SecItemCopyMatching来从钥匙串中读取这需要不同的entitlementkeychain-access-groups并且处理起来更复杂。5.2 数据刷新不及时或显示异常手动刷新无效首先点击菜单栏的刷新按钮。如果无效检查网络连接。这些用量API通常需要稳定的网络环境。自动刷新失败MeterBar的定时器可能在系统休眠或应用进入后台时被暂停。一个更健壮的实现是使用Timer.publish(every:on:in:)配合.autoconnect()并监听应用生命周期事件scenePhase在应用回到前台时强制刷新一次。数据显示为0或NaN这通常是API响应格式发生变化导致的。每个AI服务的API都不是完全稳定的。你需要使用像curl或Postman的工具手动模拟MeterBar的请求查看原始API返回了什么。# 例如获取Codex的令牌后手动调用令牌已脱敏 curl -H Authorization: Bearer sk-xxx https://chatgpt.com/backend-api/wham/usage对比返回的JSON结构和Provider代码中的Decodable模型如CodexAPIResponse是否匹配。很可能多了一层嵌套或者字段名变了。更新你的数据模型并考虑在代码中添加更灵活的解析逻辑或版本检测。5.3 扩展支持其他AI服务如果你想为MeterBar添加对另一个工具如GitHub Copilot的支持可以遵循以下路径调研阶段目标工具是否有官方CLI(gh copilot)CLI如何认证(gh auth login)认证信息存储在哪里可能是~/.config/gh/hosts.yml或GitHub CLI的缓存如何查询用量(gh copilot status命令的输出或者是否存在一个未公开的REST API实现阶段在项目中创建CopilotProvider.swift。实现UsageProvider协议。在fetchUsage()方法中你可能需要解析gh的配置文件获取令牌。或者更简单但脆弱的方式用Process执行gh copilot status命令然后解析其标准输出字符串提取用量信息。这种方式依赖于命令输出的格式稳定性。将新的Provider添加到UsageMonitor的提供商列表中。设计并添加对应的CopilotServiceCardView。测试与贡献充分测试你的Provider在各种状态下的表现未登录、已登录、额度用尽等。如果项目活跃可以向原仓库提交Pull Request。记得编写清晰的文档说明你的新增功能。5.4 性能与资源占用优化作为一个常驻菜单栏的应用资源占用必须极低。网络请求优化不要同时发起所有API请求可以使用TaskGroup进行有限的并发控制如最多同时2个并为每个请求设置合理的超时时间如10秒。数据缓存在UserDefaults或一个小型的Core Data/SQLite数据库中缓存上一次成功获取的数据。这样即使网络暂时不可用UI也能显示最近的数据而不是一片空白。定时刷新时可以先显示缓存数据然后静默更新。CPU/内存使用Instruments工具监控应用在后台定时唤醒和刷新时的CPU和内存峰值。确保没有内存泄漏Combine的订阅在适当时候取消。菜单栏应用的内存占用最好能长期稳定在50MB以下。开发这样一款工具最深的体会是“细节决定体验”。一个准确的进度条颜色、一个清晰的重置倒计时、一个安静稳定的后台刷新机制这些看似微小的点共同构成了用户“无感”却又离不开的体验。它不应该是一个需要你经常操心、调试的东西而应该像呼吸一样自然存在只在需要时给你关键信息。MeterBar在这个方向上做了一个非常棒的示范它的开源代码也为想要进入macOS实用工具开发领域的开发者提供了绝佳的学习范本。