Mac 使用

通过一个循环控制任何 macOS GUI 应用程序：截图 → 选取元素 → 点击 → 验证。

设置

平台：仅限 macOS（需要 Apple Vision 框架进行 OCR）

系统二进制文件（macOS 预装）：

• python3— 通过 Homebrew 安装 (brew install python)
• screencapture— macOS 内置工具

Python 包— 从技能目录安装：

pip3 install --break-system-packages -r {baseDir}/requirements.txt

工作原理

该截图命令会捕获一个窗口，使用Apple Vision OCR检测所有文本元素，在图像上绘制带编号的标注，并同时返回两者：

1. 标注图像位于/tmp/mac_use.png— 每个检测到的文本周围都有带编号的绿色框
2. 元素列表以 JSON 格式表示 —[{num: 1, text: "Submit", at: [500, 200]}, {num: 2, text: "Cancel", at: [600, 200]}, ...]其中at是中心点[x, y]在 1000x1000 的画布上（原点位于左上角）

通过调用 Bash（获取包含元素列表的 JSON）然后读取/tmp/mac_use.png（获取视觉信息）来接收两者。始终同时执行这两项操作以便能够将编号与你所见的内容进行交叉参考。

快速参考

# List all visible windows
python3 {baseDir}/scripts/mac_use.py list

# Screenshot + annotate (returns image + numbered element list)
python3 {baseDir}/scripts/mac_use.py screenshot <app> [--id N]

# Click element by number (primary click method)
python3 {baseDir}/scripts/mac_use.py clicknum <N>

# Click at canvas coordinates (fallback for unlabeled icons)
python3 {baseDir}/scripts/mac_use.py click --app <app> [--id N] <x> <y>

# Scroll inside a window
python3 {baseDir}/scripts/mac_use.py scroll --app <app> [--id N] <direction> <amount>

# Type text (uses clipboard paste — supports all languages)
python3 {baseDir}/scripts/mac_use.py type [--app <app>] "text here"

# Press key or combo
python3 {baseDir}/scripts/mac_use.py key [--app <app>] <combo>

工作流程

1. 打开目标应用程序，使用open -a "应用程序名称"（可选择提供URL或文件路径）
2. 等待加载完成：休眠2秒
3. 截图应用界面：

   python3 {baseDir}/scripts/mac_use.py screenshot <app> [--id N]
   

   这将返回包含文件（图像路径）和元素（带编号的文本列表）的JSON数据
4. 读取位于/tmp/mac_use.png的标注图像以直观查看编号元素
5. 决定要交互哪个元素：
   • 优先使用clicknum N——选择检测到的文本元素的编号
   • 备用方案click --app <应用名> x y——仅适用于无文本标签的图标（箭头、关闭按钮、购物车图标等），因此没有编号
6. 执行使用点击次数,类型,按键, 或滚动
7. 再次截图以验证结果
8. 从步骤3重复

命令

列表

显示所有可见的应用窗口。

python3 {baseDir}/scripts/mac_use.py list

返回JSON数组：[{"app":"Google Chrome","title":"Wikipedia","id":4527,"x":120,"y":80,"w":1200,"h":800}, ...]

截图

捕获一个窗口，通过OCR检测文本元素，用编号标记进行标注，并返回元素列表。目标窗口在捕获前会自动提升到最顶层，因此可以处理重叠窗口。

python3 {baseDir}/scripts/mac_use.py screenshot chrome
python3 {baseDir}/scripts/mac_use.py screenshot chrome --id 4527

• <应用>：模糊、不区分大小写的匹配（例如，"chrome" 匹配 "Google Chrome"）
• --id N针对特定窗口ID（当同一应用存在多个窗口时必须指定）
• 返回包含以下字段的JSON：
  • file：带标注的截图文件路径（/tmp/mac_use.png）
  • id、app、title、scale：窗口元数据
  • elements：由{num, text, at}组成的数组——即带编号的可点击文本元素，其中at表示[x, y]中心坐标，对应1000x1000画布坐标系（原点位于左上角）
• 若匹配到多个窗口，则返回窗口列表而非单个窗口——请选择其中一个窗口并使用--id
• 该图像为1000x1000像素，带有绿色边界框和蓝色数字徽章
• 元素映射已保存至/tmp/mac_use_elements.json用于点击编号

点击编号

点击上一张截图中带编号的元素。这是主要的点击方法。

python3 {baseDir}/scripts/mac_use.py clicknum 5
python3 {baseDir}/scripts/mac_use.py clicknum 12

• N：来自上一个截图输出
• 读取保存的元素映射，激活窗口，并在元素中心位置点击
• 返回包含已点击编号、文本、画布坐标和绝对屏幕坐标的JSON

点击

使用画布坐标在指定位置点击。仅作备用方法——用于未标记的图标。

python3 {baseDir}/scripts/mac_use.py click --app chrome 500 300
python3 {baseDir}/scripts/mac_use.py click --app chrome --id 4527 500 300

• 坐标为画布位置（0-1000）从截图图像
• x=0 代表左侧，x=1000 代表右侧；y=0 代表顶部，y=1000 代表底部
• 仅在视觉OCR未检测到元素时使用（如图标按钮、图像等）

滚动

在应用程序窗口内滚动。

python3 {baseDir}/scripts/mac_use.py scroll --app chrome down 5
python3 {baseDir}/scripts/mac_use.py scroll --app notes up 10

• 方向：向上,向下,向左,向右
• 滚动量：滚动点击次数（3-5次为中等速度，10次以上为快速滚动）
• 滚动前将鼠标移动到窗口中心

输入

向当前聚焦的输入字段输入文本。

python3 {baseDir}/scripts/mac_use.py type --app chrome "hello world"
python3 {baseDir}/scripts/mac_use.py type --app chrome "你好世界"

• --app：先激活应用程序，确保按键进入正确的窗口
• 使用剪贴板粘贴（Cmd+V）以确保可靠的Unicode/中日韩文字支持
• 输入前务必先点击目标输入字段before typing

按键

按下一个单独的按键或组合键。

python3 {baseDir}/scripts/mac_use.py key --app chrome return
python3 {baseDir}/scripts/mac_use.py key --app chrome cmd+a
python3 {baseDir}/scripts/mac_use.py key --app chrome cmd+shift+s

• --app: 首先激活应用程序
• 常见按键：回车,制表符,退出,空格,删除,退格,上方向键,下方向键,左方向键,右方向键
• 修饰键：命令,控制,alt/opt,shift

重要规则

• 在首次与应用交互前，务必截图操作后，务必截图
• 以验证结果运行截图命令后，务必阅读截图图像
• 你需要元素列表和视觉信息两者优先使用
• clicknum而非click— 仅对无标签图标使用直接坐标输入前先点击
• — 确保正确的输入字段首先获得焦点多窗口
• ：如果遇到multiple_windows错误，请使用error, use列表查看所有窗口，然后传递--id
• 弹出窗口（如微信小程序面板）是拥有独立ID的独立窗口——使用列表来查找它们，并使用--id来定位它们
• 打开应用后等待：在open -a之后，截图前使用sleep 2-3 截图/点击前激活应用
• ：当目标应用可能被其他窗口遮挡时，在命令前添加osascript -e 'tell application "AppName" to activate' && sleep 1 不要通过此工具输入密码或机密信息 坐标系（用于备用
• 点击）via this tool

Coordinate System (for fallbackclick仅)

截图被渲染到一个1000x1000 的画布上：

• 原点 (0, 0)位于左上角x
• 从左向右递增 (0 = 左边缘, 1000 = 右边缘)y
• 从上向下递增 (0 = 上边缘, 1000 = 下边缘)应用窗口按比例缩放以适应画布（保持宽高比），居中显示，并带有深灰色填充
• 示例：在微信上使用美团点餐

Example: Order food on Meituan in WeChat

# 1. Open WeChat
open -a "WeChat"
sleep 3

# 2. Screenshot WeChat — find the mini program window
python3 {baseDir}/scripts/mac_use.py list
# → find the mini program window ID

# 3. Screenshot the mini program (annotated + element list)
python3 {baseDir}/scripts/mac_use.py screenshot 微信 --id 41266
# → returns: {"file": "/tmp/mac_use.png", "elements": [{num: 1, text: "搜索", at: [500, 200]}, ...]}
# → Read /tmp/mac_use.png to see annotated image

# 4. Click "搜索" (element #1)
python3 {baseDir}/scripts/mac_use.py clicknum 1

# 5. Type search query
python3 {baseDir}/scripts/mac_use.py type --app 微信 "炸鸡"

# 6. Press Enter
python3 {baseDir}/scripts/mac_use.py key --app 微信 return
sleep 2

# 7. Screenshot to see results
python3 {baseDir}/scripts/mac_use.py screenshot 微信 --id 41266
# → Read /tmp/mac_use.png, pick a restaurant by number

# 8. Click on a restaurant (e.g. element #5)
python3 {baseDir}/scripts/mac_use.py clicknum 5