macos-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

macos-automation

macOS自动化

Purpose

用途

This skill automates tasks on macOS using tools like AppleScript, JXA, Shortcuts, Automator, osascript, System Events, and the accessibility API, enabling script-based control of apps and system functions.

本技能借助AppleScript、JXA、Shortcuts、Automator、osascript、System Events以及辅助功能API，实现macOS上的任务自动化，支持通过脚本控制应用程序和系统功能。

When to Use

适用场景

Automate repetitive workflows, such as file management or app interactions.
Integrate with macOS apps for custom behaviors, like triggering actions via keyboard shortcuts.
Script complex sequences involving multiple apps, e.g., when Shortcuts alone isn't sufficient.
Handle accessibility tasks, like UI element manipulation, when apps don't expose direct APIs.
Use for rapid prototyping of automations in environments like shell scripts or IDEs.

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

Key Capabilities

核心功能

Execute AppleScript via osascript for app control, e.g., manipulating Finder or Safari.
Run JXA (JavaScript for Automation) to interact with macOS APIs, supporting modern JavaScript syntax.
Create and invoke Shortcuts programmatically for quick actions, like sharing files.
Use Automator workflows as scripts, convertible to applications or services.
Leverage System Events for UI automation, including keyboard/mouse simulation via accessibility API.
Access macOS-specific APIs like NSAppleScript for embedding in Objective-C/Swift code.

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

Usage Patterns

使用模式

Run scripts from the command line using osascript; for example, pipe AppleScript code directly.
Embed JXA in Node.js environments by loading the JXA module and executing via
```
Application('Finder').activate()
```
.
Chain Shortcuts with other tools by exporting as URLs and invoking via
```
open
```
command.
Use Automator to build workflows, then save as .applescript files for osascript execution.
For accessibility, ensure "Accessibility" is enabled in System Preferences > Security & Privacy, then use System Events to target UI elements like
```
tell application "System Events" to click button "OK" of window "Main"
```
.
Always check for required permissions, such as Full Disk Access, before running scripts that access files.

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

Common Commands/API

常用命令/API

osascript CLI: Use
```
osascript -e 'tell application "Finder" to make new folder at desktop'
```
to create a folder; handle errors by checking the exit code.

JXA Example: In a JavaScript file, use

const app = Application('Safari'); app.activate(); app.documents[0].url = 'https://example.com';

to open and navigate a URL.

Shortcuts Integration: Run a shortcut via
```
shortcuts run "My Shortcut" -i '{"input": "text"}'
```
; pass inputs as JSON for parameterized execution.

Automator API: Convert workflows to AppleScript with

tell application "Automator" to run workflow "path/to/workflow"

System Events API: For UI automation, use

osascript -e 'tell application "System Events" to keystroke "a" using {command down}'

to simulate Command+A.

Config Formats: Store scripts in plain text files (.applescript) and invoke with
```
osascript path/to/script.applescript
```
; for JXA, use ES6 modules in .js files.

osascript命令行工具：使用
```
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模块。

Integration Notes

集成说明

Integrate with other tools by wrapping osascript calls in shell scripts; e.g., use
```
$ export APPLESCRIPT_PATH='/path/to/script'
```
and run via
```
osascript $APPLESCRIPT_PATH
```
.

For JXA, require the OSA module in Node.js:

npm install osa

and use

const OSA = require('osa'); OSA.runAppleScript('...')

If accessibility features are needed, set the env var
```
$ACCESSIBILITY_ENABLED=1
```
after granting permissions in System Preferences.
Auth/keys: For scripts accessing protected resources, use env vars like
```
$osascript_API_KEY
```
(though rare); more commonly, handle macOS permissions via
```
tccutil
```
CLI, e.g.,
```
tccutil reset AppleEvents com.example.app
```
to reset access.
Embed in larger apps by compiling AppleScript into bundles or using JXA in Electron apps for cross-tool integration.

通过在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
```
命令行工具管理macOS权限，例如
```
tccutil reset AppleEvents com.example.app
```
重置访问权限。
通过将AppleScript编译为包，或在Electron应用中使用JXA，将自动化功能嵌入到大型应用中，实现跨工具集成。

Error Handling

错误处理

Check osascript exit codes: If a script fails, capture with
```
osascript -e 'script' 2>&1
```
and parse stderr for messages like "Execution error: ...".

In JXA, wrap code in try-catch:

try { Application('Finder').activate(); } catch (e) { console.error(e.message); }

to handle app not found errors.

For Shortcuts, verify with
```
shortcuts run "Name" --wait-for-result
```
and check output for failures.
Use Automator's built-in logging by enabling in workflow settings, then review logs via Console app.
General pattern: Always run scripts with elevated privileges if needed, e.g., via
```
sudo osascript -e '...'
```
, and handle permission errors by prompting users to adjust settings.

检查osascript退出码：如果脚本执行失败，使用
```
osascript -e 'script' 2>&1
```
捕获错误，并解析stderr中的消息（如"Execution error: ..."）。

在JXA中，使用try-catch包裹代码：

try { Application('Finder').activate(); } catch (e) { console.error(e.message); }

，处理应用未找到等错误。

对于Shortcuts，使用
```
shortcuts run "Name" --wait-for-result
```
执行并检查输出是否失败。
在Automator工作流设置中启用内置日志，然后通过「控制台」应用查看日志。
通用模式：如有需要，始终使用提升权限运行脚本（例如
```
sudo osascript -e '...'
```
），并通过提示用户调整设置来处理权限错误。

Concrete Usage Examples

具体使用示例

Automate App Launch and Action: Use osascript to open Safari and load a page:
```
osascript -e 'tell application "Safari" to open location "https://example.com"' followed by 'tell application "Safari" to activate'
```
. This is useful for daily workflows; extend by adding error checks.

UI Automation with Shortcuts: Create a Shortcut to resize windows, then invoke via CLI:

shortcuts run "Resize Window" -i '{"app": "Finder", "width": 800}'

. Combine with JXA for dynamic inputs, e.g., in a script:

Application('Shortcuts').run('Resize Window', {input: JSON.stringify({app: 'Finder'})})

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

Graph Relationships

关联关系

Related to: macos cluster (direct parent), applescript skill (sub-skill for scripting), shortcuts skill (integrated tool), automation cluster (broader category).
Dependencies: Requires macos-os (base system), interacts with accessibility-api skill for UI tasks.

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