automating-mac-apps

Name: automating-mac-apps
Author: spillwavesolutions

github.com/spillwavesolutions生产力48138 次安装10 周前更新

代码仓库

关于 automating-mac-apps

这是一份使用 Apple Events、AppleScript、JXA 及 Python 方案自动化 macOS 应用的参考技能，涵盖应用探索、权限准备、脚本验证和方案选择。

主要功能

01AppleScript 与 JXA 指南
02PyXA 和 PyObjC 替代方案
03自动化权限预热流程
04验证与安全检查清单
05UI 脚本回退模式

适用场景

01为 macOS 应用选择自动化语言
02首次运行前准备权限
03构建命令行或管道自动化
04将 AppleScript 工作流迁移到 PyXA

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/spillwavesolutions/automating-mac-apps-plugin --skill automating-mac-apps

安装后在 Claude Code 中输入/automating-mac-apps确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

applescript-asobjc.md

applescript-basics.md

applescript-guide.md

applescript-performance.md

applescript-timeouts.md

applescript-to-pyxa-conversion.md

basics.md

calendar-notes.md

chrome.md

ci-cd-tcc.md

cookbook.md

dictionary-strategies.md

finder.md

helpers.js

keynote.md

mail.md

meeting-automation-playbook.md

pages.md

pyxa-basics.md

pyxa-core-api-reference.md

recipes.md

safari.md

security-prompts.md

shell-environment.md

tooling-vscode.md

translation-checklist.md

ui-scripting-inspector.md

whos-batching.md

scripts/

request_automation_permissions.py

request_automation_permissions.sh

详细介绍

自动化 macOS 应用（Apple Events、AppleScript、JXA）

技术状态

JXA 和 AppleScript 已过时（最近一次重大更新：2015—2016 年）。现代替代方案：

PyXA：活跃的 Python 自动化方案（见下方安装说明）
Shortcuts App：可视化工作流构建工具
Swift/Objective-C：适用于生产环境的自动化方案

macOS Sequoia 15 注意事项

请在目标 macOS 上测试脚本，原因如下：

更严格的 TCC 权限
增强的 Apple Events 安全性
沙盒改进

核心概念（请采用这一思维模型）

Apple Events：macOS 自动化底层的进程间通信（IPC）传输机制。
AppleScript：Apple Events 的原始 DSL（领域专用语言）；最适合探索、查看字典和快速原型开发。
JXA（JavaScript for Automation）：Apple Events 层的 JavaScript 绑定；最适合数据处理、JSON 和可维护的逻辑。
ObjC Bridge：通过 JavaScript 访问 Objective-C 框架（Foundation、AppKit），以使用超出应用字典范围的高级 macOS 功能。

何时使用哪种方案

使用 AppleScript 进行探索、查看字典、UI 脚本编写和快速的一次性操作。
使用 JXA 实现稳健的逻辑、JSON 管道、与 Python/Node 集成，以及长期运行的自动化。
混合模式（推荐）：使用 AppleScript 探索，在生产环境中使用 JXA 实现。

何时使用此技能

作为特定应用技能（Calendar、Notes、Mail、Keynote、Excel、Reminders）的基础。
首次运行自动化前，运行自动化预热脚本，以显示 macOS 权限提示。
将其用作权限、Shell 集成和 UI 脚本回退方案的基础参考。

工作流（默认）

使用 Script Editor 确定目标应用和字典。
构建原型，实现一条可用的最简命令。
- 示例：tell application "Finder" to get name of first item in desktop
根据上述规则选择语言。
完善：添加错误处理、超时和权限检查。
- JXA：try { ... } catch (e) { console.log('Error:', e.message); }
- AppleScript：try ... on error errMsg ... end try
验证：运行只读命令并检查输出。
- 示例：osascript -e 'tell application "Finder" to get name of home'
- 确认：输出符合预期（例如，用户主文件夹名称）
通过 osascript 集成到命令行或管道中。
仅当字典缺失或不完整时，才使用 UI 脚本回退方案。
- UI 脚本示例：tell application "System Events" to click button 1 of window 1 of process "App"
- JXA 示例：Application('System Events').processes.byName('App').windows[0].buttons[0].click()

验证清单

已授予自动化/辅助功能权限（System Settings > Privacy & Security）
应用正在运行：Application("App").running() 返回 true
操作前已检查状态（例如，文件夹是否存在）
使用了字典方法（而非 UI 脚本）
已为 UI 操作添加延迟/重试
只读测试命令执行成功
输出符合预期值

自动化权限预热

首次运行自动化前或 macOS 更新后使用，以显示权限提示：
- 一次处理所有应用：skills/automating-mac-apps/scripts/request_automation_permissions.sh（或 .py）。
- 针对单个应用：skills/automating-<app>/scripts/set_up_<app>_automation.{sh,py}（calendar、notes、mail、keynote、excel、reminders）。
- Voice Memos（无字典）：运行 skills/automating-voice-memos/scripts/set_up_voice_memos_automation.sh，以激活应用并检查数据路径；启用辅助功能权限，并考虑授予完全磁盘访问权限。
请在计划用于自动化的同一主机上运行（Terminal 或 Python），以便正确的应用获得自动化授权。
每个脚本都会运行只读 AppleScript 调用（列出账户/日历/文件夹等），以请求 Terminal/Python 的控制权限；出现提示时点击“Allow”。

JXA 的现代 Python 替代方案

PyXA（Python for macOS Automation）——新项目的首选方案：

PyXA 功能

持续开发中（v0.2.3+），采用现代 Python 语法
应用自动化：Safari、Calendar、Reminders、Mail、Music
UI 脚本编写、剪贴板、通知、AppleScript 集成
方法链式调用：app.lists().reminders().title()

PyXA 安装 {#pyxa-installation}

# Install PyXA
pip install mac-pyxa

# Or with pip3 explicitly
pip3 install mac-pyxa

# Requirements:
# - Python 3.10+ (check with: python3 --version)
# - macOS 12+ (Monterey or later recommended)
# - PyObjC is installed automatically as a dependency

# Verify installation
python3 -c "import PyXA; print(f'PyXA {PyXA.__version__} installed successfully')"

注意： 此插件中所有展示 PyXA 示例的应用专用技能都假设已安装 PyXA。安装方法请参阅本节。

PyXA 示例（Safari 自动化）

import PyXA

# Launch Safari and navigate
safari = PyXA.Safari()
safari.activate()
safari.open_location("https://example.com")

# Get current tab URL
current_url = safari.current_tab.url
print(f"Current URL: {current_url}")

PyXA 示例（Reminders）

import PyXA

reminders = PyXA.Reminders()
work_list = reminders.lists().by_name("Work")

# Add new reminder
new_reminder = work_list.reminders().push({
    "name": "Review PyXA documentation",
    "body": "Explore modern macOS automation options"
})

PyXA 官方资源：

文档：https://skaplanofficial.github.io/PyXA/
GitHub：https://github.com/SKaplanOfficial/PyXA
社区：活跃的 Discord 和 GitHub 讨论区

PyObjC（Python-Objective-C 桥接） - 用于 macOS 底层集成：

PyObjC 功能

直接访问框架：AppKit、Foundation 和所有 macOS 框架
Apple Events：通过 Scripting Bridge 发送 Apple Events
脚本执行：从 Python 运行 AppleScript 或 JXA
系统 API：直接访问 CalendarStore、AddressBook、SystemEvents

安装

pip install pyobjc
# Installs bridges for major frameworks

PyObjC 示例（执行 AppleScript）

from Foundation import NSAppleScript

# Execute AppleScript from Python
script_source = '''
tell application "Safari"
    return URL of current tab
end tell
'''

script = NSAppleScript.alloc().initWithSource_(script_source)
result, error = script.executeAndReturnError_(None)

if error:
    print(f"Error: {error}")
else:
    print(f"Current Safari URL: {result.stringValue()}")

PyObjC 示例（通过 Scripting Bridge 控制应用）

from ScriptingBridge import SBApplication

# Control Mail app
mail = SBApplication.applicationWithBundleIdentifier_("com.apple.Mail")
inbox = mail.inboxes()[0]  # Access first inbox

# Get unread message count
unread_count = inbox.unreadCount()
print(f"Unread messages: {unread_count}")

PyObjC 官方资源：

文档：https://pyobjc.readthedocs.io
示例：GitHub 上有大量包含代码示例的代码库

JXA 状态

JXA 自 2016 年以来没有更新。新项目尽可能使用 PyXA。

不适用场景

跨平台自动化（网页自动化请使用 Selenium/Playwright）
完整 UI 测试（请使用 XCUITest 或 Appium）
禁止 Automation/Accessibility 权限的环境
非 macOS 平台
简单的 shell 脚本任务（直接使用 Bash）

安全最佳实践

权限管理：

仅请求最低限度的必要权限，以降低安全风险
在生产脚本中使用代码签名（Developer ID 证书）
安全存储凭据（使用 Keychain，不要将凭据硬编码）
验证所有输入，以防止注入攻击

Apple 官方安全指南：

输出要求

示例应简洁且可运行。
JSON 输出：对于 CLI 管道，请在 JXA 中使用 JSON.stringify(result)。
- 示例：console.log(JSON.stringify({files: files, count: files.length}))
退出代码：确保 osascript 成功时退出代码为 0，失败时为非零值。

加载内容

第 1 层：基础内容（从这里开始）

JXA 语法与模式：automating-mac-apps/references/basics.md
AppleScript 基础：automating-mac-apps/references/applescript-basics.md
配方集（常用示例）：automating-mac-apps/references/recipes.md

第 2 层：高级与生产环境

JXA 配方集（精简版）：automating-mac-apps/references/cookbook.md
性能模式：automating-mac-apps/references/applescript-performance.md
CI/CD 与权限：automating-mac-apps/references/ci-cd-tcc.md
Shell 环境：automating-mac-apps/references/shell-environment.md
UI 脚本检查器：automating-mac-apps/references/ui-scripting-inspector.md

第 3 级：专业与参考

PyXA 核心 API 参考（完整的类／方法文档）：automating-mac-apps/references/pyxa-core-api-reference.md
PyXA 基础知识：automating-mac-apps/references/pyxa-basics.md（现代 Python 自动化基础）
AppleScript → PyXA 转换：automating-mac-apps/references/applescript-to-pyxa-conversion.md（附示例的迁移指南）
转换检查清单（AppleScript → JXA）：automating-mac-apps/references/translation-checklist.md（附示例和注意事项的全面指南）
JXA 辅助工具库：automating-mac-apps/references/helpers.js
whose 批处理模式：automating-mac-apps/references/whos-batching.md
字典策略：automating-mac-apps/references/dictionary-strategies.md
ASObjC 辅助工具：automating-mac-apps/references/applescript-asobjc.md

相关技能：

web-browser-automation：完整的浏览器自动化指南（Chrome、Edge、Brave、Arc）

支持 Markdown

登录后评论

基本信息

作者: spillwavesolutions
仓库: spillwavesolutions/automating-mac-apps-plugin
分类: 生产力
安装次数: 138
GitHub Stars: 48

报告问题