MacPilot Automation
这是一个用于自动化 macOS 的技能，依赖 macpilot CLI 工具。MacPilot 提供 100 多个命令，覆盖鼠标、键盘、应用、窗口、UI、剪贴板、对话框、shell 与系统控制，所有命令均支持 --json 以输出结构化结果。
用途
当用户提出以下需求时使用本技能：自动化 macOS 任务（打开应用、点击按钮、输入文字、导航菜单）；以编程方式控制鼠标和键盘；通过辅助功能 API 与正在运行的应用交互；将多个自动化步骤串联成工作流；运行 shell 命令或与终端交互；管理剪贴板、通知、音频、显示设置。
前置条件
MacPilot 必须安装在 /Applications/MacPilot.app，并在 /usr/local/bin/macpilot 或 ~/bin/macpilot 创建符号链接。该应用需要在“系统设置 > 隐私与安全性 > 辅助功能”中授予辅助功能权限。
核心命令参考
鼠标控制
macpilot click <x> <y> # 在坐标处左键单击 macpilot doubleclick <x> <y> # 双击 macpilot rightclick <x> <y> # 右键单击 macpilot move <x> <y> # 移动光标 macpilot drag <x1> <y1> <x2> <y2> # 从一点拖拽到另一点 macpilot scroll <up|down|left|right> [amount] # 滚动（默认：3） macpilot mouse-position --json # 获取当前光标位置
键盘控制
macpilot keyboard type "Hello World" # 输入文字 macpilot keyboard key cmd+c # 按下快捷键 macpilot keyboard key enter # 按下单个按键 macpilot chain "type:hello" "key:tab" "type:world" # 串联动作
修饰键：cmd、shift、alt、ctrl、fn 特殊键：enter、tab、space、escape、delete、f1-f12、up、down、left、right
应用管理
macpilot app open "Safari" # 打开/启动应用 macpilot app focus "Safari" # 将应用置于前台 macpilot app frontmost --json # 获取最前台应用 macpilot app list --json # 列出运行中的应用 macpilot app quit "Safari" # 退出应用 macpilot app quit "Safari" --force # 强制退出应用 macpilot app hide "Safari" # 隐藏应用
菜单交互
macpilot menu click File Open --app Safari # 点击菜单项 macpilot menu list --app Safari --json # 列出所有菜单 macpilot menu list --app Safari --menu File # 列出指定菜单
剪贴板
macpilot clipboard get --json # 读取剪贴板文本 macpilot clipboard set "text" # 设置剪贴板文本 macpilot clipboard image photo.png # 复制图像到剪贴板 macpilot clipboard info --json # 内容类型、大小、预览 macpilot clipboard types --json # 列出所有 UTI 类型 macpilot clipboard clear --json # 清空剪贴板 macpilot clipboard paste --json # 模拟 Cmd+V macpilot clipboard copy file.txt --json # 复制文件到剪贴板 macpilot clipboard save /tmp/out.png # 保存剪贴板内容到文件
剪贴板历史（后台守护进程，最多 50 项）
macpilot clipboard history start --json # 开始跟踪 macpilot clipboard history stop --json # 停止跟踪 macpilot clipboard history list --json # 显示历史 macpilot clipboard history search "text" # 搜索历史 macpilot clipboard history clear --json # 删除历史
Shell 命令
macpilot shell run "ls -la" # 运行命令并获取输出 macpilot shell interactive "top" # 在终端中打开 macpilot shell type "git status" # 在当前终端中输入 macpilot shell paste "long command here" # 通过剪贴板粘贴
系统控制
macpilot audio volume get --json # 获取音量（0-100） macpilot audio volume set 50 # 设置音量 macpilot audio volume mute # 静音 macpilot display brightness set 75 # 设置亮度 macpilot appearance dark # 深色模式 macpilot appearance light # 浅色模式 macpilot notification send "Title" "Body" # 发送系统通知 macpilot notification list --json # 列出可见通知 macpilot notification click --title "match" # 按标题点击通知 macpilot notification dismiss --json # 关闭顶部通知 macpilot notification dismiss --all # 关闭所有通知 macpilot system info --json # 系统信息 macpilot network wifi-name --json # Wi-Fi 名称 macpilot network ip --json # IP 地址
等待与同步
macpilot wait seconds 2 # 休眠 2 秒 macpilot wait element "Save" --app TextEdit # 等待 UI 元素 macpilot wait window "Untitled" --timeout 10 # 等待窗口 macpilot watch events --duration 5 --json # 监控事件
空间与程序坞
macpilot space list --json # 列出空间 macpilot space switch right # 切换空间 macpilot dock hide # 自动隐藏程序坞 macpilot dock show # 始终显示程序坞
关键模式
交互前先聚焦应用：在点击、输入或菜单操作之前，必须先执行 macpilot app focus "AppName"。聚焦后的第一次点击可能被窗口激活消耗——先点击应用内容区域，再点击目标。
使用 --json 以便解析：当需要以编程方式解析输出时，始终添加 --json。
使用 ui find-text 获取坐标：当需要点击特定元素时，先用 macpilot ui find-text "label" --app AppName --json 找到其坐标，再在返回位置点击。
用 chain 处理复杂序列：对于多步键盘工作流，使用 macpilot chain 而非多个独立命令。
优先用 AX 设值而非键盘输入：当焦点不确定时，通过 macpilot ui set-value 设置文本字段值比键盘输入更可靠。
等待元素：在可能与尚未出现的 UI 元素交互前，使用 macpilot wait element。
示例工作流
在 Safari 中打开 URL
macpilot app open Safari macpilot wait window Safari --timeout 5 macpilot app focus Safari macpilot keyboard key cmd+l macpilot keyboard type "https://example.com" macpilot keyboard key enter
从一个应用复制文本到另一个应用
macpilot app focus "TextEdit" macpilot keyboard key cmd+a macpilot keyboard key cmd+c macpilot app focus "Notes" macpilot keyboard key cmd+v
在 TextEdit 中新建文件
macpilot app open TextEdit macpilot wait window TextEdit --timeout 5 macpilot keyboard type "Hello from MacPilot!" macpilot keyboard key cmd+s macpilot wait seconds 1 macpilot dialog navigate "/Users/me/Desktop" macpilot dialog set-field "myfile.txt" macpilot dialog click-button "Save"