从MVVM到Provider注册表Claude Usage Tracker用量追踪架构深度解析完整指南【免费下载链接】Claude-Usage-TrackerNative macOS menu bar app for tracking Claude AI usage limits in real-time. Built with Swift/SwiftUI.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-Usage-TrackerClaude Usage Tracker是一款原生 macOS 菜单栏应用用 Swift/SwiftUI 构建能够实时追踪 Claude AI 用量限制5 小时会话窗口与每周限额并以多种图标风格呈现在菜单栏中。本文带你深度解析它的MVVM 架构与Provider 注册表设计看看一个看起来不大的菜单栏工具如何用清晰的工程结构支撑起多服务商Anthropic、OpenAI Codex扩展能力。 项目全景一个菜单栏 App 的核心能力对普通用户来说Claude Usage Tracker 解决的是一个问题额度还剩多少还剩多久重置。它把答案直接放在 macOS 菜单栏上 实时显示 5 小时会话窗口与每周用量百分比支持电量条、进度条、百分比、圆环等多种图标风格 多 Profile 管理支持 Anthropic 与 OpenAI Codex 双服务商 接近额度上限时推送通知附带用量历史图表与 CSV 导出 Notch HUD在刘海区域显示 Claude Code 实时会话状态上面这张图展示的就是它引以为傲的Navbar Icon Styles彩色与单色两种变体。图标渲染由 MenuBarIconRenderer.swift 完成——注意渲染逻辑被单独抽成一个 Renderer 文件而不是混在视图代码里这正是后文要讲的视图保持愚蠢原则的体现。️ MVVM 四层分工谁负责什么项目在 CONTRIBUTING.md 中明确声明遵循MVVMModel-View-ViewModel模式整个仓库的目录结构就是这张架构图层目录职责Model模型Claude Usage/Shared/Models/纯 Swift 数据结构零 UI 依赖View视图Claude Usage/Views/、Claude Usage/MenuBar/SwiftUI 视图只负责展示ViewModel视图模型MenuBarManager.swift业务逻辑与状态中枢Service服务Claude Usage/Shared/Services/API 请求、Keychain、通知等系统交互Model 层一个 Struct 统一所有服务商的数据所有服务商的用量最终都被映射到同一个结构体 ClaudeUsage.swift百分比 重置时间作为各服务商的最大公约数Token 数、计划类型、余额等字段则按需提供。这种统一数据契约是整套架构的基石——UI 永远只认识ClaudeUsage从不知道数据来自 Anthropic 还是 Codex。ViewModel 层MenuBarManager 是应用的心脏MenuBarManager.swift近 1900 行是整个应用的大脑。它作为ObservableObject对外暴露一组Published状态Published private(set) var usage: ClaudeUsage .empty Published private(set) var isRefreshing: Bool false Published private(set) var hasCredentialError: Bool false它还统一管理刷新定时器、多 Profile 切换、弹窗Popover生命周期、深色模式图标缓存等细节。而 App 的启动流程则由 AppDelegate.swift 编排隐藏 Dock 图标NSApp.setActivationPolicy(.accessory)、加载 Profile、决定是否弹出设置向导……入口文件 ClaudeUsageTrackerApp.swift 甚至只有十几行——因为这是纯菜单栏应用默认不创建任何窗口。View 层让视图保持愚蠢打开 PopoverContentView.swift 你会发现SwiftUI 视图通过属性包装器订阅 ViewModel 状态ObservedObject var manager: MenuBarManager StateObject private var profileManager ProfileManager.shared视图本身不做任何网络请求或业务判断只把manager.usage画出来。配合 SettingsView.swift 等设置界面形成了状态变化 → 自动刷新 UI的单向数据流。 Provider 注册表多服务商扩展的关键设计如果说 MVVM 解决的是代码怎么分层那么Provider 注册表ProviderRegistry解决的就是功能怎么扩展——这是整个架构中最精彩的设计。一个唯一的接缝ProviderRegistry.swift 的文件头注释写得很直白The single seam between the app and its usage providers.App 与其用量服务商之间的唯一接缝整个应用从不出现provider .anthropic这种硬编码判断。UI 和服务层只通过两个入口获取服务商相关信息descriptor(for:)—— 获取声明式的事实品牌名、Logo、状态页 URL、能力开关service(for:)—— 获取负责拉取用量的服务实例描述符 能力开关用数据代替 if-elseProviderDescriptor.swift 定义了ProviderCapabilities能力标志tokenCounts是否报告 Token 数、perModelBreakdown是否有分模型明细、consoleBilling是否有计费 API、cliAccountSync是否可同步本地 CLI 账号……以 Codex 为例它不报告 Token 数于是tokenCounts: false——菜单栏的 Token 指标自动隐藏CSV 导出自动省略 Token 列图标自动回退到百分比显示。所有这些隐藏行为都不需要写任何if provider .codex而是由数据驱动。协议契约UsageProviderService每个服务商都实现 UsageProviderService.swift 协议只需回答三个问题有没有凭证怎么拉取用量活动 Profile 是否允许更宽的认证链如 Anthropic 的 Keychain CLI 回退调用方永远依赖协议而非具体实现类——这是典型的面向接口编程 依赖倒置。服务商的具体实现按目录隔离AnthropicUsageProvider.swift 与 CodexUsageProvider.swift各自带独立的认证服务和 API 客户端。️ 这套架构对贡献者意味着什么docs/ADDING_A_PROVIDER.md 给出了新增加盟服务商的 10 步清单加一个枚举 case、建一个目录、注册一条描述符与一条服务、配好能力开关、补齐凭证 UI 与本地化……最关键的是文末那句承诺What you should NOT need to touchMenuBarManager、ProfileManager、PopoverContentView、SetupWizardView等核心文件无需修改。也就是说扩展是纯增量的additive——新增一个服务商就像插一块新板卡而不是给主板动手术。Codex 的实现Shared/Services/Providers/Codex/就是官方参考实现配套的 CodexProviderTests.swift 展示了 fixture 驱动的容错解码测试写法。 新手阅读源码的路径建议按这个顺序读能最快建立整体认知入口ClaudeUsageTrackerApp.swift → AppDelegate.swift理解菜单栏应用没有窗口这件事数据契约ClaudeUsage.swift → Provider.swift状态中枢MenuBarManager.swift重点看Published属性与 Combine 观察者注册表ProviderRegistry.swift → ProviderDescriptor.swift扩展规范docs/ADDING_A_PROVIDER.md动手前的必读清单存储层同样值得翻一翻DataStore.swift 负责 UserDefaults 持久化ProfileStore.swift 管理多 Profile而敏感凭证则交给 KeychainService.swift 安全保管——分层清晰各司其职。✅ 小结Claude Usage Tracker 的架构可以浓缩成三句话MVVM 分层Model 纯数据、View 纯展示、MenuBarManager 当状态中枢、Service 管系统交互统一数据契约所有服务商的用量都映射为ClaudeUsageUI 不感知来源Provider 注册表描述符声明是什么协议约定怎么取能力开关驱动显不显示让多服务商扩展成为纯增量操作对想学习 Swift/SwiftUI 工程实践的开发者来说这是一个小而美的范本没有重型框架只有清晰的分层、接口和约定。想深入了解项目背景与贡献流程可以参考 README.md 与 CONTRIBUTING.md。【免费下载链接】Claude-Usage-TrackerNative macOS menu bar app for tracking Claude AI usage limits in real-time. Built with Swift/SwiftUI.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-Usage-Tracker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考