有一段时间我特别想给自己的 macOS 工作流加一个“嘴替”说话就能把临时想到的事情写进 iCloud 提醒事项或者随手定一个二十分钟后的倒计时。市面上现成的语音助手不少但要么绑定了自家的生态要么只能在特定 App 里用想真正和系统级的提醒事项、通知中心联动几乎都得自己动手。于是就有了这个项目——一个跑在 macOS 上的语音助手智能体核心能力就两条写 iCloud 提醒事项、做分钟级倒计时。项目听起来不复杂真正动手才发现 macOS 的 TCC 隐私权限机制才是最绕不开的坎。如果一个程序不能拿到“提醒事项”和“自动化”的授权哪怕代码写得再漂亮系统也只会甩给你一句冷冰冰的拒绝。这篇文章我会把整个项目的设计思路、TCC 权限申请流程、AppleScript/JXA 的调用方式、语音识别与意图解析的落地细节都拆开讲一遍适合那些想在 macOS 上做本地智能体、又不想被权限机制劝退的开发者。如果你正准备做类似的事应该能少踩不少坑。1. 项目整体设计与思路拆解1.1 智能体的本质从语音输入到系统动作的闭环先说清楚这里的“智能体”到底是什么。它不是一个会聊天的 AI 机器人而是一条非常务实的自动化链路语音输入 → 语音识别成文字 → 意图解析 → 调用系统能力 → 返回结果。整条链路全部跑在本地不依赖云端智能体平台也不需要额外部署大型模型服务。我选择的架构是“Python 主控 AppleScript/JXA 桥接 系统级能力调用”后面会详细解释为什么这么组合。这个设计里最关键的一个决策是不让智能体直接去操作 iCloud 的后端接口而是通过系统自带 App 的能力间接实现。因为 iCloud 提醒事项的底层数据归 Reminders 应用管与其逆向协议或者折腾 EventKit不如直接让 Reminders 自己干活。这样既保证了数据一定同步到 iCloud又省掉了大量的鉴权和数据结构适配工作。智能体的“智能”体现在意图解析层而执行层尽量做薄这是整个项目能快速跑通的核心原因。另一个重要决策是交互方式。我没有选择“一直开着麦克风随时唤醒”的模式而是做了一个按键触发按住快捷键说话松手自动识别。这种设计有几个好处第一省电不需要音频流常驻第二隐私压力小系统只在按键期间采集声音第三TCC 的麦克风授权链路相对简单不需要处理复杂的后台音频会话。1.2 为什么不直接写 Swift/EventKit而选 AppleScript/JXA很多人会问macOS 上有 EventKit 框架可以写提醒事项直接写个 Swift 命令行工具不就完了为什么要绕一圈用 AppleScript/JXA有道理但实际做过一次就会明白EventKit 方案的坑在于权限提示和分发成本。EventKit 请求“提醒事项”权限时系统会绑定到你运行程序的宿主进程。如果我用 Swift 编译出一个命令行工具每次调试完换个目录编译TCC 就可能把这个新路径当成一个全新的程序重新弹窗授权、重新走一遍流程。而 AppleScript/JXA 方式下执行 osascript 的宿主进程通常是“终端”或某个固定的 App授权信息挂在宿主上只要一次授权后续反复改脚本都不受影响。对快速迭代来说这个体验差别非常大。JXA 还有一个隐藏优势可以直接调用 Objective-C 桥接接口。这意味着我可以在一个统一的技术栈里同时操作提醒事项、发送系统通知、甚至调用 Cocoa 的计时器能力不需要为每一个小功能都编译一个独立工具。我的项目里写提醒事项用 JXA弹通知用 JXA连倒计时结束后的语音播报也可以用 JXA 里的say整个执行层非常统一。1.3 分钟级倒计时的技术选型为什么不能直接 time.sleep倒计时功能看起来是最简单的但恰恰是陷阱最多的。最初的实现用的是 Python 的time.sleep(duration)逻辑上没有任何问题一跑就发现电脑锁屏一段时间后macOS 会自动让系统进入睡眠Python 进程也被挂起等你唤醒电脑时倒计时早就过了——它是“睡醒后”才意识到到点了而不是“到点时”提醒你。所以倒计时的核心不是睡眠等待而是“持续调度 唤醒补偿”。我最后的方案是主控进程计算出绝对截止时间戳deadline然后每 5 秒醒来检查一次当前时间到点立即触发提醒。配合caffeinate -i在倒计时期间阻止系统空闲睡眠保证唤醒检查是真实发生的。虽然这种做法会稍微增加耗电但分钟级倒计时本来就是短时任务值得用一点电量换可靠性。2. macOS TCC 权限机制详解与申请实操2.1 TCC 到底是什么TCCTransparency, Consent, and Control是 macOS 的隐私保护框架负责管理应用对敏感数据的访问授权。每一次你在“系统设置 → 隐私与安全性”里看到的各种权限项背后都是 TCC 在管理。它把敏感资源划分为不同服务类别比如提醒事项对应的是kTCCServiceReminders日历对应kTCCServiceCalendar自动化控制对应kTCCServiceAppleEvents麦克风对应kTCCServiceMicrophone。TCC 的决策结果记录在数据库中。用户级授权存在~/Library/Application Support/com.apple.TCC/TCC.db系统级授权存在/Library/Application Support/com.apple.TCC/TCC.db。这两个数据库受 SIP 保护普通用户无法直接编辑唯一的授权方式就是让系统弹窗、用户点击允许。这也意味着凡是涉及新功能接入必须提前规划好授权流程不能让用户跑到一半才发现某个权限没申请。我在做这个项目时最深的感受是TCC 不是一个可以“绕过去”的东西而是一个必须耐心“顺着来”的机制。你越是想跳过它越会在后续调试中被折磨。与其回避不如把授权当成项目的一个正式模块来设计。2.2 本项目涉及的四条 TCC 授权链路写提醒事项这个看似简单的动作实际牵扯到多条 TCC 授权链路很多人只盯着“提醒事项”权限结果忘了还有别的。第一条是 AppleEvents 授权。这是最容易漏的权限因为它的出现时机很隐蔽。只要你的 Python 进程通过osascript去控制 “Reminders” 应用系统就会认为你的进程在向另一个 App 发送 Apple 事件需要kTCCServiceAppleEvents授权。具体表现就是“系统设置 → 隐私与安全性 → 自动化”里会出现一个新的条目比如“终端想要控制‘提醒事项’”。如果不允许osascript 会报错Not authorized to send Apple events to Reminders。第二条是“提醒事项”数据访问授权对应kTCCServiceReminders。在 TCC 层面读和写提醒事项都会触发这个权限。有时候用户明明授权了却还是写不进去往往是因为授权给了错误的宿主进程下一节我会展开讲。第三条是“系统事件”辅助功能授权。如果倒计时结束后需要模拟按键、控制其他 App就会用到辅助功能权限。我这个项目只在极少数情况下需要所以把它作为可选链路处理了。第四条是麦克风权限。语音助手要收音就一定需要kTCCServiceMicrophone。由于我的设计是按下按键才录音这条链路的申请时机很明确用户体验也比较自然。2.3 授权到底会挂在谁身上一个隐蔽但致命的坑TCC 授权是绑定到“责任进程”的而这个责任进程未必是你以为的那个进程。我在实践中踩到过一个非常经典的坑在系统自带的“终端”里运行 Python 脚本Python 再去调用osascript控制 Reminders此时 TCC 系统会把这个请求关联到“终端”这个 App 上而不是 Python 解释器。所以用户去“自动化”面板里看到的授权条目是“终端想要控制‘提醒事项’”而不是 Python 脚本本身。但如果换成了 iTerm、VS Code、PyCharm 等不同的宿主TCC 又会分别建立新的授权条目。最折磨人的情况是在终端里授权好了换到 IDE 里运行又弹窗、又报错看起来像是代码不稳定其实是授权对象换了一个宿主。解决思路是在开发阶段固定使用同一个终端工具并且把这个约定写进项目的 README方便团队协作时对齐环境。申请授权的标准流程是这样的首次运行脚本 → 系统弹出“xxx想要访问提醒事项”或“xxx想要控制提醒事项”的对话框 → 用户点击“好” → 授权条目出现在“隐私与安全性”对应面板。如果弹窗没有出现可以用tccutil reset Reminders或tccutil reset AppleEvents重置对应服务的授权状态再重新触发。重置命令会清掉所有 App 对这个服务的授权记录代价是需要重新授权一遍调试阶段非常实用。注意千万不要用任何手段去直接修改 TCC.db 数据库文件尤其是系统级的数据库。轻则授权记录损坏重则导致系统隐私机制异常。所有权限操作都应该通过系统提供的弹窗和设置面板完成。3. 用 AppleScript/JXA 写入 iCloud 提醒事项3.1 写入提醒事项的两种姿势我试过两种调用方式传统 AppleScript 和 JXAJavaScript for Automation。传统 AppleScript 的好处是网上资料多随手一搜就能抄到缺点是处理动态字符串时转义问题让人抓狂。JXA 的语法对熟悉 JavaScript 的开发者友好得多对象模型也更清晰所以我最终选择了 JXA。用osascript -l JavaScript指定语言就可以执行 JXA 代码。创建一个提醒事项的核心片段像这样osascript -l JavaScript -e const Reminders Application(Reminders); const r Reminders.Reminder({ name: 给客户回电话 }); Reminders.defaultList.reminders.push(r); 这段代码创建了一个名为“给客户回电话”的提醒事项并放进了默认提醒事项列表。如果需要指定截止时间可以给Reminder对象加dueDate属性osascript -l JavaScript -e const Reminders Application(Reminders); const due new Date(2025-06-01T15:00:00); const r Reminders.Reminder({ name: 下午三点开会, dueDate: due }); Reminders.defaultList.reminders.push(r); 如果要在指定的提醒事项列表中创建而不是默认列表可以遍历现有的列表找到目标列表。比如有一个叫“工作”的列表可以这样写osascript -l JavaScript -e const Reminders Application(Reminders); const target Reminders.lists.byName(工作); const r Reminders.Reminder({ name: 整理周报 }); target.reminders.push(r); 3.2 让提醒事项真的落到 iCloud 账户这是我在联调时发现的一个隐蔽问题提醒事项应用里可能有多个账户比如 iCloud、Exchange、本机 On My Mac。AppleScript 写入的默认列表可能落在本机账户导致手机上看不到。要让数据真正跨设备同步必须在脚本层面确认目标列表属于 iCloud 账户。最靠谱的做法是给 iCloud 列表设置固定的唯一 ID 或者通过名字精确匹配。在“提醒事项”应用里把 iCloud 账户下的某个列表改成一个容易识别的名字比如“iCloud收件箱”或者直接使用默认的“提醒事项”列表然后脚本里去定位这个名字。还有一个小技巧可以先遍历所有列表打印每个列表所属的账户信息确认后再决定写入策略。osascript -l JavaScript -e const Reminders Application(Reminders); const lists Reminders.lists; for (let i 0; i lists.length; i) { console.log(lists[i].name() | 完成列表: lists[i].name()); } 从我的实践来看最简单稳定的方案是在提醒事项 App 里把 iCloud 账户的某个列表改名成固定英文标识比如inbox然后在脚本中用精确名称去查找。不要依赖“默认列表”这个抽象概念因为不同机器上的默认列表指向可能完全不同。3.3 自然语言日期解析方案语音转文字之后用户习惯说“明天下午三点提醒我开会”而不可能说“2025-06-02T15:00:00”。所以意图解析模块必须能处理自然语言日期这一步直接决定了整个助手智能体的体验。我用的方案是“正则模板 日期计算轮子”的组合。先处理固定短语映射今天、明天、后天、大后天、中午、下午、晚上、早上、几分钟后、半小时后。然后把口语时间转换为绝对时间戳。举个例子如果识别到“明天下午三点”代码逻辑是先拿到明天的日期再拼接上 15:00 的小时和分钟最后生成 Date 对象传给 JXA。下面是一个简化版from datetime import datetime, timedelta def parse_relative_time(text): now datetime.now() if 明天 in text: day_offset 1 elif 后天 in text: day_offset 2 else: day_offset 0 target_date (now timedelta(daysday_offset)).strftime(%Y-%m-%d) if 下午 in text: hour 15 elif 晚上 in text: hour 20 elif 中午 in text: hour 12 else: hour 9 return f{target_date}T{hour:02d}:00:00对于“二十分钟后”这种相对表达直接在当前时间上加对应分钟数def parse_relative_minutes(text): # 提取数字 import re match re.search(r(\d)\s*分钟, text) if match: return int(match.group(1)) return None这套组合在中文场景下已经覆盖了 90% 的日常需求而且完全不用依赖外部大模型。如果识别结果里有“提醒我”“记一下”“别忘了”这类动词短语就优先按提醒事项处理出现“倒计时”“计时器”“几分钟后叫我”则走倒计时分支。4. 分钟级倒计时后台调度与系统通知实现4.1 倒计时调度器的设计倒计时的核心模块是一个独立的后台调度器线程。它不承担语音识别、意图解析这些耗时工作唯一的职责就是盯着截止时间。我把它做成“轮询到期检查”模式而不是“一次性睡眠到点”模式就是为了应对 macOS 的休眠机制。调度器的大致结构是这样的主进程解析出“倒计时 20 分钟”的意图后计算出deadline now 20 * 60然后把 deadline 存进一个任务队列。调度器线程每 5 秒检查一次当前时间如果now deadline就把任务标记为到期交给通知模块处理。只要有任务未到期调度器就持续运行任务列表为空时整个助手进程进入空闲等待。Python 里的实现非常简洁import threading import time from datetime import datetime, timedelta class TimerScheduler: def __init__(self): self.tasks [] self.running True self.thread threading.Thread(targetself._loop, daemonTrue) self.thread.start() def add_task(self, seconds, message): deadline datetime.now() timedelta(secondsseconds) self.tasks.append({deadline: deadline, message: message}) def _loop(self): while self.running: now datetime.now() for task in self.tasks[:]: if now task[deadline]: self._fire(task) self.tasks.remove(task) time.sleep(5)4.2 用 JXA 弹系统通知和语音播报任务到期后需要立刻给用户一个明确反馈。我在 macOS 上优先选择displayNotification做弹窗通知再用say做语音播报。displayNotification是 JXA 的标准 additions 方法可以在通知中心生成一条真实的通知配合声音参数还能播放提示音。osascript -l JavaScript -e const app Application.currentApplication(); app.includeStandardAdditions true; app.displayNotification(20分钟到了该休息一下, { withTitle: 倒计时提醒, soundName: Glass }); 如果希望语音播报就把say加上osascript -l JavaScript -e const app Application.currentApplication(); app.includeStandardAdditions true; app.say(时间到该休息一下); 这里includeStandardAdditions true是必须的否则displayNotification和say都没有定义。顺便说一句say支持\chinese之类的语音参数但默认的 Ting-Ting 中文语音在较新系统上可能需要下载保底方案是用系统提示音代替语音播报。4.3 用 caffeinate 和 launchd 保证后台可靠运行倒计时期间最怕的是系统睡眠。虽然调度器是每 5 秒轮询但如果系统整体进入睡眠状态Python 进程根本不会被调度执行。解决办法是调用 macOS 自带的caffeinate命令阻止系统在没有活动时自动睡眠。在 Python 里启动一个子进程执行caffeinate -i可以让系统忽略空闲睡眠。倒计时任务全部结束后再把这个子进程终止。这样既保障了倒计时期间的可靠性又不会永久改变系统的电源策略。# 启动防睡眠 caffeinate -i # 所有倒计时任务结束后终止 pkill caffeinate如果希望整个助手进程在用户注销后仍然存活或者开机自动重启建议再配置一个 launchd 守护进程。创建一个~/Library/LaunchAgents/com.example.voiceassistant.plist配置KeepAlive为 trueRunAtLoad为 true这样只要用户登录助手进程就会一直活着异常退出后也会被系统自动拉起。launchd 是 macOS 后台任务的正统方案比往 Cron 里塞 shell 脚本靠谱得多。5. 完整实操从语音识别到动作执行的链路打通5.1 语音识别方案选本地 Whisper 而不是系统听写语音识别是整个链路里最依赖外部因素的一环。我一开始用的是 macOS 的 SFSpeechRecognizer系统自带、离线可用中文识别精度也还行。问题在于它的授权体系和模块封装比较繁琐而且识别质量受音频格式影响大调试成本不小。后面我切换到本地 Whisper 模型具体用了faster-whisper这个 Python 库模型文件放在本地。好处有几点完全离线不依赖苹果的识别服务支持多种语言中文识别很稳模型按需加载小模型在 Apple Silicon 上跑得很快。当然代价是首次下载模型需要一点时间但考虑到这是本地智能体项目数据不出本机是加分项。实际运行时我使用ffmpeg录制麦克风音频把按键按下到松开之间的音频保存为临时 WAV 文件再交给 Whisper 识别。整个过程大概两秒内能出结果完全够用。ffmpeg -f avfoundation -i :0 -t 5 /tmp/voice_input.wav如果你不想在 Python 里处理音频采集细节用 ffmpeg 的命令行封装是最快的捷径。5.2 意图解析器一个可扩展的关键词路由识别完成之后文字内容进入意图解析器。我的实现没有上大模型而是用一个轻量的关键词路由表。主要原因是我只需要处理固定的几种意图杀鸡不用牛刀而且纯本地规则更快、没有任何网络延迟。def parse_intent(text): if any(k in text for k in [提醒, 记一下, 别忘了, 待办]): return {intent: reminder, text: text} if any(k in text for k in [倒计时, 计时, 分钟后叫我, 提醒我]): return {intent: timer, text: text} return {intent: unknown, text: text}“提醒我二十分钟后喝水”这句话会被同时命中“提醒”和“提醒我”所以解析时需要加优先级倒计时相关短语优先于提醒事项如果没有时间短语就走提醒事项分支。更精细的做法是维护一个“时间表达”正则库先做时间抽取再结合动词判断意图这样能避开很多歧义。为了让用户知道助手听懂了每个意图处理完之后都会调用say播报一句确认比如“好的已经设置 20 分钟倒计时”。这个反馈设计非常关键它能让人直观感知到有没有识别错比看屏幕日志高效太多。5.3 端到端联调一个最小可用闭环把所有模块串起来之后整个闭环就是这样一个流程用户按住快捷键说话 → ffmpeg 录音成 WAV → faster-whisper 识别成文字 → Python 解析意图和时间 → 如果是提醒事项调用 JXA 写入 iCloud 提醒列表 → 如果是倒计时创建调度任务并启动 caffeinate → 到期弹通知和语音播报。我在联调时发现一个很容易忽略的细节osascript调用如果放在 Python 的subprocess里执行要确保工作目录稳定并且正确捕获环境变量。最简单的方式是始终使用绝对路径调用 osascript不要依赖~/.zshrc里的 PATH否则在 launchd 环境下容易莫名其妙找不到命令。端到端调试时建议先做“文本输入测试”也就是不经过语音识别环节直接给意图解析器传一段文字验证提醒事项和倒计时两条链路是否正常。文本链路稳定后再叠加语音识别模块。这样分阶段联调可以快速定位是“识别问题”还是“执行问题”。6. 常见问题与排查技巧实录6.1 高频问题速查表问题现象可能原因解决方案首次运行脚本不弹授权窗宿主进程已经被 TCC 拒绝过用tccutil reset Reminders和tccutil reset AppleEvents重置授权状态osascript 报 Not authorized to send Apple eventsAppleEvents 授权没给打开“系统设置 → 隐私与安全性 → 自动化”勾选对应终端允许控制 Reminders写入了提醒事项但手机不显示写入到了本机账户而不是 iCloud 账户检查 Reminders 列表归属改用 iCloud 账户下的固定列表名写入倒计时在锁屏后失效系统睡眠进程被挂起倒计时任务运行期间执行caffeinate -i阻止睡眠语音识别结果总是不对麦克风录音质量差或环境噪音大检查麦克风权限、录音增益尽量在安静环境说话launchd 启动后找不到脚本PATH 环境变量和终端不一致在 plist 中使用脚本绝对路径并在 shell 脚本中显式设置 PATH6.2 一步一步定位 TCC 问题的方法遇到 TCC 权限相关报错时最忌讳瞎猜。我的排查习惯是先看报错信息再查系统日志确认是哪个进程被拒。查看 TCC 日志的命令是log show --last 5m --predicate subsystem com.apple.TCC --info --debug日志里会明确记录哪个进程请求了哪个服务、最终决策是 allow 还是 deny。这个信息比任何猜测都准确。定位到是哪个进程被拒后再回到“系统设置 → 隐私与安全性”面板去检查对应条目有没有勾选。如果授权面板里根本没有对应条目通常是因为系统认为没有“有效请求”。这时候重置 TCC 服务状态再重新运行一次触发脚本弹窗就会出现。有个小技巧授权完记得完全退出终端重新打开因为 TCC 的授权结果不一定即时全局生效重启宿主进程是最快刷新方式。6.3 两个容易被忽略的小坑第一个坑是 Python 子进程继承 TCC 责任的边界。如果你的主进程是一个已授权的 App但脚本里又用subprocess调起了另一个解释器执行 osascript授权责任可能落在子进程的宿主上而不是主进程。保险起见尽量用同一个解释器进程直接执行所有 osascript 调用不要让两层 subprocess 嵌套。第二个坑是不同 macOS 版本的 TCC 弹窗文案差异。在较新的系统上“自动化”面板里的授权文案写得更隐蔽条目默认不展开容易被忽略。如果找不到授权入口直接把所有折叠的条目展开看一遍别只看第一屏。7. 写在最后的一点体会整个项目做下来最深的体会是 macOS 的 TCC 机制虽然繁琐但它的逻辑是一致的所有能影响其他 App 或敏感数据的操作都必须经过用户的明确同意。与其想着怎么钻空子不如把授权流程做成产品体验的一部分。第一次运行脚本时主动提示用户需要授权什么、去哪里授权、为什么要授权远比让用户面对一个系统弹窗一脸懵要好。另外一点是关于范围控制。这个项目的核心能力只有提醒事项和倒计时但我最初其实是想做一个通用语音助手什么都能干。幸好及时收敛了范围否则光是各种 TCC 权限的组合测试就足够让人崩溃。把一个小闭环打磨顺畅再慢慢扩展新能力才是做本地智能体最务实的路径。如果你也想在 macOS 上做类似的本地智能体我的建议是从一个最简单的提醒事项写入开始先把 TCC 授权的链路摸透再加上倒计时最后再接语音识别。这样一步步来每一步都有明确的成功标准排查问题时也能快速定位。这个项目我目前还在继续扩展下一步准备加日历查询和定时开关静音模式届时再和大家分享新的踩坑记录。