TomatoBar 完全指南:macOS 菜单栏番茄钟的安装、配置、自动化集成与状态机源码解析
TomatoBar 完全指南:macOS 菜单栏番茄钟的安装、配置、自动化集成与状态机源码解析
导读
TomatoBar 是一款运行在 macOS 菜单栏(Menu Bar)的番茄工作法(Pomodoro)计时器,项目自称"世界上最简洁的番茄钟"(world's neatest Pomodoro timer)。它以常驻菜单栏的小图标 + 弹出面板(Popover)形式提供可配置的工作/休息时长、可选音效、带操作按钮的通知以及全局快捷键。本文以仓库根目录 README.md 为主体,结合 TomatoBar 目录下的 Swift 源码,完整讲解其安装方式、面板配置项、状态机与定时器原理、事件日志与 tomatobar:// URL 自动化集成,帮助读者快速上手并理解其底层实现,进而将番茄钟数据接入自己的效率分析体系。
TomatoBar 是什么:核心特性一览
番茄工作法(Pomodoro Technique)是一种通过分段计时帮助学习与工作中保持专注的时间管理方法。TomatoBar 正是为此设计的菜单栏应用,核心特性包括:
- 可配置的工作与休息间隔:工作、短休息、长休息时长均可自定义,并支持设置"一组"包含的工作次数;
- 可选的提示音效:发条声(windup)、叮声(ding)、滴答声(ticking)三种声音,音量独立可调;
- 克制的可操作通知:通过系统通知告知休息开始/结束,休息开始通知附带"跳过"(Skip)操作按钮;
- 全局快捷键:一键开始/停止计时;
- 完全沙盒化:应用开启 App Sandbox,且不申请任何额外 entitlements。
应用本体是纯菜单栏程序(INFOPLIST_KEY_LSUIElement = YES,见 TomatoBar.xcodeproj/project.pbxproj),不占据 Dock 图标,所有交互都通过菜单栏图标和弹出面板完成。
安装:Homebrew Cask 与免隔离安装
从 README 可知,TomatoBar 有两种官方安装途径:直接从 Releases 页面下载最新版,或通过 Homebrew Cask 安装:
brew install --cask tomatobar
若应用无法启动,通常是因为 macOS 的 Gatekeeper 隔离(quarantine)属性阻止了未签名/未公证应用运行,此时改用免隔离标志安装:
brew install --cask --no-quarantine tomatobar
安装完成后,应用以菜单栏图标形式常驻(对应 TomatoBar/App.swift 中的 NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)),点击图标即可弹出主面板。
配置面板:间隔、设置与音效三块看板
点击菜单栏番茄图标后弹出的 Popover 面板(主视图实现在 TomatoBar/View.swift 的 TBPopoverView)顶部是开始/停止按钮,下方用分段控件(Segmented Picker)切换三个子面板:时长(Intervals)、设置(Settings)、声音(Sounds),底部还有"关于"(⌘ A)与"退出"(⌘ Q)两个按钮。
时长面板(IntervalsView)
时长面板使用四个 Stepper 分别调节以下参数,取值范围与默认值如下(默认值来自 TomatoBar/Timer.swift 的 @AppStorage 声明,取值范围来自 TomatoBar/View.swift):
| 配置项 | AppStorage 键 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|
| 工作时间 | workIntervalLength |
25(分钟) | 1–60 | 单个番茄工作周期时长 |
| 短休息时间 | shortRestIntervalLength |
5(分钟) | 1–60 | 每个工作周期后的短休息 |
| 长休息时间 | longRestIntervalLength |
15(分钟) | 1–60 | 完成一组工作后的长休息 |
| 一组中的工作次数 | workIntervalsInSet |
4(次) | 1–10 | 累计多少次工作后进入长休息 |
所有配置通过 @AppStorage 直接持久化到 UserDefaults,修改即时生效。注意一个"隐藏"偏好 overrunTimeLimit(默认 -60.0 秒,见 TomatoBar/Timer.swift),它用于应对机器睡眠导致的计时溢出,下文状态机部分会详细说明。
设置面板(SettingsView)
设置面板包含四个开关/录制控件(TomatoBar/View.swift):
- 快捷键(Shortcut):使用
KeyboardShortcuts.Recorder录制全局快捷键,对应KeyboardShortcuts.Name.startStopTimer(键名"startStopTimer",见 TomatoBar/View.swift); - 在休息后停止(Stop after break):对应
stopAfterBreak,开启后长休息结束不再自动进入下一轮工作,而是回到 idle 状态; - 在菜单栏中显示计时器(Show timer in menu bar):对应
showTimerInMenuBar,决定菜单栏图标旁是否显示剩余时间数字;切换时立即调用updateTimeLeft()刷新标题; - 登录时启动(Launch at login):绑定
LaunchAtLogin.observable,使用 LaunchAtLogin 库实现,并在 App 初始化时调用LaunchAtLogin.migrateIfNeeded()做迁移(TomatoBar/App.swift)。
声音面板(SoundsView)
声音面板(TomatoBar/View.swift)用三个滑杆分别调节三种音效的音量,每个滑杆范围为 0–2,双击滑杆可将音量复位为 1.0:
- 发条声(Windup):开始工作时播放一次,对应
windupVolume; - 叮声(Ding):工作周期结束(休息开始)时播放一次,对应
dingVolume; - 滴答声(Ticking):工作期间循环播放,休息开始后停止,对应
tickingVolume。
三种音效资源(windup.wav、ding.wav、ticking.wav)以 DataSet 形式存放在 TomatoBar/Assets.xcassets 中,由 TomatoBar/Player.swift 的 TBPlayer 通过 AVAudioPlayer(data:fileTypeHint:) 加载播放;其中滴答声设置 numberOfLoops = -1 实现无限循环,音量变更通过 didSet 实时下发到播放器。
底层原理:状态机驱动的计时核心
TomatoBar 的计时逻辑并非简单的倒计时,而是基于 SwiftState 库构建的有限状态机(FSM),定义见 TomatoBar/State.swift:
- 状态(States):
idle(空闲)、work(工作)、rest(休息); - 事件(Events):
startStop(开始/停止)、timerFired(计时结束)、skipRest(跳过休息)。
TomatoBar/Timer.swift 中注册了完整的状态转移规则,可以还原为如下状态图:
start/stop
+--------------+-------------+
| | |
| start/stop | timerFired |
V | | | |
+--------+ | +--------+ | +--------+
| idle |--->| work |--->| rest |
+--------+ +--------+ +--------+
A A | |
| | | |
| +--------+ |
| timerFired (!stopAfterBreak) |
| skipRest |
| |
+--------------------------------+
timerFired (stopAfterBreak)
关键转移规则:
idle => work、work => idle、rest => idle:由startStop事件触发(用户点开始/停止按钮、按全局快捷键或调用tomatobar://startStop);work => rest:由timerFired触发(工作周期自然结束);rest => idle/rest => work:由timerFired触发,具体走向取决于stopAfterBreak开关——开启则回到空闲,关闭则自动进入下一轮工作;rest => work:由skipRest触发(用户点击通知上的"跳过"按钮)。
每个转移都挂接了对应的副作用处理(TomatoBar/Timer.swift),例如进入工作状态时切换菜单栏图标为 work、播放发条声、启动滴答声并启动 25 分钟计时器(onWorkStart);工作结束播放叮声(onWorkFinish)并停止滴答声;进入休息状态时根据已连续完成的工作次数(consecutiveWorkIntervals)决定是短休息(5 分钟)还是长休息(15 分钟),并将图标切换为 shortRest 或 longRest(onRestStart)。
四种菜单栏图标 BarIconIdle / BarIconWork / BarIconShortRest / BarIconLongRest 的 imageset 位于 TomatoBar/Assets.xcassets,由 Icons/convert.sh 脚本基于 ImageMagick 自动生成(工作/短休/长休分别叠加 W、R、L 字母,共 1x–3x 三档尺寸)。
计时器的实现与睡眠容错
底层计时使用 DispatchSourceTimer(TomatoBar/Timer.swift):以 1 秒为周期、leeway: .never 严格调度,每次 tick 在主线程更新剩余时间字符串;剩余时间归零后,根据是否超过 overrunTimeLimit(默认 -60 秒)决定触发 timerFired 还是 startStop。这正是"隐藏偏好"的用途:机器睡眠期间系统可能错过多次 tick,若醒来时已经超时过久(超过 60 秒),就不再继续休息,而是直接停止计时回到空闲,避免睡眠唤醒后出现虚假的计时状态。
菜单栏显示的数字使用 NSFont.monospacedDigitSystemFont 等宽数字字体,避免倒计时跳动时菜单栏标题宽度抖动(TomatoBar/App.swift)。
与外部工具的集成:事件日志与 URL 控制
README 明确给出了两条自动化集成途径,非常适合把番茄钟数据接入个人效率分析工作流。
事件日志(Event log):JSON 状态流转记录
TomatoBar 会把所有状态转移以 JSON 格式追加写入:
~/Library/Containers/com.github.ivoronin.TomatoBar/Data/Library/Caches/TomatoBar.log
(该路径同时是应用沙盒容器内的 Caches 目录,与 TomatoBar/Log.swift 中基于 FileManager.urls(for: .cachesDirectory, in: .userDomainMask) 计算日志路径的逻辑一致。)
日志实现位于 TomatoBar/Log.swift,采用 JSONEncoder(sortedKeys 键排序、时间戳按 secondsSince1970 编码)逐行追加并 synchronize() 落盘,目前共有两类事件:
appstart:应用启动事件(字段type、timestamp);transition:状态转移事件(字段type、timestamp、event、fromState、toState),由TBLogEventTransition在任意状态变更时记录(TomatoBar/Log.swift、TomatoBar/Timer.swift)。
典型的一条 transition 记录大致形如:
{"event":"startStop","fromState":"idle","timestamp":1697000000,"toState":"work","type":"transition"}
你可以用任意 JSON 解析工具(如 jq、Python、R 等)按时间线聚合出每日专注/休息分布,进而与其他数据源(日历、代码提交记录等)做关联分析。
启动与停止计时:tomatobar:// URL 协议
TomatoBar 注册了自定义 URL Scheme tomatobar,支持从命令行或其他自动化工具(如 Alfred、Raycast、launchd 定时任务、脚本)启停计时器。README 给出的命令:
open tomatobar://startStop
该命令等价于点击一次开始/停止按钮:若当前空闲则开始工作,若正在工作/休息则停止并回到空闲。其实现链路如下:
- Scheme 注册:
tomatobar声明在 TomatoBar/Info.plist 的CFBundleURLTypes中(URL Name 为com.github.ivoronin.TomatoBar); - 事件接收:
TBTimer初始化时通过NSAppleEventManager注册kInternetEventClass/kAEGetURL处理器(TomatoBar/Timer.swift); - 命令分发:
handleGetURLEvent校验 scheme 为tomatobar(大小写不敏感),再按 host 分发——当前仅支持startstop,命中后调用startStop()向状态机发送.startStop事件(TomatoBar/Timer.swift)。
这意味着你可以把番茄钟嵌入任何脚本,例如配合 cron/launchd 到点自动开始一轮工作。
全局快捷键与通知动作
- 全局快捷键:通过
KeyboardShortcuts库(v2.4.0,见 Package.resolved)注册名为startStopTimer的快捷键,onKeyUp直接触发startStop(),与按钮、URL 走同一条状态机路径(TomatoBar/Timer.swift)。 - 可操作通知:
TBNotificationCenter(TomatoBar/Notifications.swift)基于UserNotifications框架,启动时申请.alert权限并注册两类通知类别:restStarted(附带"跳过 Skip"动作)与restFinished(无动作)。工作/休息切换时发送通知;用户点击"跳过"后,didReceive回调解析actionIdentifier并将skipRest动作转发给TBTimer,最终触发skipRest事件直接进入下一轮工作(TomatoBar/Timer.swift)。
沙盒与安全模型
README 强调 TomatoBar 完全沙盒化且无额外 entitlements。仓库中的 TomatoBar/TomatoBar.entitlements 证实了这一点——全部内容仅有一项:
<key>com.apple.security.app-sandbox</key>
<true/>
即只开启 App Sandbox,未声明网络、文件读写(用户可见目录)、硬件等任何特权;工程构建同时启用了 Hardened Runtime(ENABLE_HARDENED_RUNTIME = YES)。这是将日志路径限定在沙盒容器内、URL 控制不依赖任何系统权限的原因。
版本与许可说明
README 还包含两点补充信息:
- 旧版本:3.0 之前的 TomatoBar 版本支持 Touch Bar 集成以及早于 Big Sur 的 macOS 版本;当前版本面向现代 macOS(工程中 Target 的
MACOSX_DEPLOYMENT_TARGET = 11.0,项目级为 12.3,见 TomatoBar.xcodeproj/project.pbxproj),升级到 3.0 后这两项能力不再提供; - 许可:项目以 MIT 协议开源(见 LICENSE),内置计时音效(timer sounds)来自 buddhabeats 的授权;界面使用的番茄图标源自 icons8(见 Icons/README.md)。
小结
TomatoBar 用不到十个 Swift 源文件,就把"菜单栏番茄钟"这个场景打磨到了相当完整的程度:状态机把开始/停止/超时/跳过等事件统一收敛到三条状态与三个事件的转移矩阵中,@AppStorage 让所有偏好即时持久化,沙盒化保证安全边界,而 JSON 事件日志与 tomatobar:// URL 协议则让它成为一个可被脚本化、可被数据化的工作流节点。若你正在寻找一款可编程的 macOS 番茄钟,或想参考一个"小而美"的 SwiftUI 菜单栏应用范例,TomatoBar 仓库 值得深入阅读。