macos-automation

macos-automation

用途

此技能使用 AppleScript、JXA、Shortcuts、Automator、osascript、System Events 和辅助功能 API 等工具，在 macOS 上自动执行任务，从而通过脚本控制应用和系统功能。

适用场景

• 自动执行重复性工作流，例如文件管理或应用交互。
• 与 macOS 应用集成以实现自定义行为，例如通过键盘快捷键触发操作。
• 编写涉及多个应用的复杂操作序列脚本，例如仅靠 Shortcuts 无法满足需求时。
• 处理辅助功能任务，例如在应用未提供直接 API 时操作 UI 元素。
• 在 shell 脚本或 IDE 等环境中快速构建自动化原型。

主要功能

• 通过 osascript 执行 AppleScript 来控制应用，例如操作 Finder 或 Safari。
• 运行 JXA 以与 macOS API 交互，并支持现代 JavaScript 语法。
• 以编程方式创建和调用 Shortcuts，以执行共享文件等快速操作。
• 将 Automator 工作流用作脚本，并可将其转换为应用或服务。
• 利用 System Events 进行 UI 自动化，包括通过辅助功能 API 模拟键盘和鼠标操作。
• 访问 macOS 专属 API，例如在 Objective-C/Swift 代码中嵌入 NSAppleScript。

使用模式

• 使用 osascript 从命令行运行脚本；例如，直接通过管道传入 AppleScript 代码。
• 在 Node.js 环境中加载 JXA 模块，并通过 Application('Finder').activate() 执行，以嵌入 JXA。
• 将 Shortcuts 导出为 URL，并通过 open 命令调用，以便与其他工具串联。
• 使用 Automator 构建工作流，然后将其保存为 .applescript 文件，供 osascript 执行。
• 如需使用辅助功能，请确保在“系统偏好设置”>“安全性与隐私”中启用“辅助功能”，然后使用 System Events 定位 UI 元素，例如 tell application "System Events" to click button "OK" of window "Main"。
• 运行访问文件的脚本前，务必检查是否已授予所需权限，例如“完全磁盘访问权限”。

常用命令/API

• osascript CLI：使用 osascript -e 'tell application "Finder" to make new folder at desktop' 创建文件夹；通过检查退出代码来处理错误。
• JXA 示例：在 JavaScript 文件中，使用 const app = Application('Safari'); app.activate(); app.documents[0].url = 'https://example.com'; 打开并访问某个 URL。
• Shortcuts 集成：通过 shortcuts run "My Shortcut" -i '{"input": "text"}' 运行快捷指令；以 JSON 格式传递输入以执行参数化操作。
• Automator API：使用 tell application "Automator" to run workflow "path/to/workflow" 将工作流转换为 AppleScript。
• System Events API：进行 UI 自动化时，使用 osascript -e 'tell application "System Events" to keystroke "a" using {command down}' 模拟 Command+A。
• 配置格式：将脚本存储为纯文本文件（.applescript），并使用 osascript path/to/script.applescript 调用；对于 JXA，请在 .js 文件中使用 ES6 模块。

集成说明

• 通过在 shell 脚本中封装 osascript 调用来与其他工具集成；例如，使用 $ export APPLESCRIPT_PATH='/path/to/script'，然后通过 osascript $APPLESCRIPT_PATH 运行。
• 对于 JXA，在 Node.js 中引入 OSA 模块：npm install osa，然后使用 const OSA = require('osa'); OSA.runAppleScript('...')。
• 如果需要辅助功能，请在“系统偏好设置”中授予权限后设置环境变量 $ACCESSIBILITY_ENABLED=1。
• 身份验证/密钥：访问受保护资源的脚本可使用 $osascript_API_KEY 等环境变量（但这种情况很少见）；更常见的是通过 tccutil CLI 管理 macOS 权限，例如使用 tccutil reset AppleEvents com.example.app 重置访问权限。
• 可将 AppleScript 编译为应用包，或在 Electron 应用中使用 JXA，以嵌入更大型的应用并实现跨工具集成。

错误处理

• 检查 osascript 退出代码：如果脚本失败，请使用 osascript -e 'script' 2>&1 捕获输出，并解析标准错误中的消息，例如 "Execution error: ..."。
• 在 JXA 中使用 try-catch 包裹代码：try { Application('Finder').activate(); } catch (e) { console.error(e.message); }，以处理找不到应用的错误。
• 对于 Shortcuts，使用 shortcuts run "Name" --wait-for-result 验证，并检查输出中是否有失败信息。
• 在工作流设置中启用 Automator 的内置日志记录，然后通过 Console 应用查看日志。
• 通用模式：如有需要，始终使用提升的权限运行脚本，例如通过 sudo osascript -e '...'，并在遇到权限错误时提示用户调整设置。

具体用法示例

1. 自动打开应用并执行操作：使用 osascript 打开 Safari 并加载网页：osascript -e 'tell application "Safari" to open location "https://example.com"' followed by 'tell application "Safari" to activate'。这适用于日常工作流；可通过添加错误检查来扩展。
2. 使用 Shortcuts 自动化 UI：创建一个 Shortcut 来调整窗口大小，然后通过 CLI 调用：shortcuts run "Resize Window" -i '{"app": "Finder", "width": 800}'。结合 JXA 处理动态输入，例如在脚本中使用：Application('Shortcuts').run('Resize Window', {input: JSON.stringify({app: 'Finder'})})。

图关系

• 相关项：macos 集群（直接父级）、applescript 技能（用于脚本编写的子技能）、shortcuts 技能（集成工具）、automation 集群（更广泛的类别）。
• 依赖项：需要 macos-os（基础系统），并与用于 UI 任务的 accessibility-api 技能交互。