该技能用于在 Supaterm 终端中操作原生 macOS 应用或浏览器页面。
用途
当你需要从 Supaterm 终端控制真实的 macOS 应用窗口或浏览器页面内容时使用此技能。它通过 sp computer-use 命令行接口完成权限检查、应用启动、窗口发现、快照捕获与元素级操作。
主要能力
- 权限与发现:检查权限(
sp computer-use permissions --json)、按 bundle-id 启动应用、列出应用与窗口。 - 窗口快照:对指定 pid 与 window 执行快照,支持 som 模式并输出图片,也可用
--query过滤返回元素。 - 元素操作:基于最新快照的 elementIndex 执行点击(press)、输入文本、按键、滚动、设置值等操作。
- 浏览器页面操作:使用 page 子命令获取页面文本、查询 DOM 属性、执行 JavaScript,并可启用 JavaScript Apple Events。
- Electron 应用:启动时可通过
--electron-debugging-port开启渲染器调试端口以访问 DOM。
使用方式
先执行权限、启动与目标发现命令,例如:
sp computer-use permissions --json sp computer-use launch --bundle-id com.apple.TextEdit --json sp computer-use apps --json sp computer-use windows --app TextEdit --on-screen-only --json
操作前先捕获窗口快照:
sp computer-use snapshot --pid 123 --window 456 --mode som --image-out /tmp/window.png --json sp computer-use snapshot --pid 123 --window 456 --query save --json
优先使用最新快照中的 elementIndex 执行操作:
sp computer-use click --pid 123 --window 456 --element 7 --action press --json sp computer-use type --pid 123 --window 456 --element 8 "hello" --json sp computer-use key --pid 123 --window 456 --element 8 return --json sp computer-use scroll --pid 123 --window 456 --element 10 --direction down --unit page --json sp computer-use set-value --pid 123 --window 456 --element 9 "new value" --json
浏览器页面内容应使用 page 命令,而不是从原生 AX 元素推断 DOM 状态:
sp computer-use launch --bundle-id com.google.Chrome --url https://example.com --new-instance --json sp computer-use windows --app com.google.Chrome --json sp computer-use page enable-javascript-apple-events --browser chrome --json sp computer-use page enable-javascript-apple-events --browser safari --json sp computer-use page get-text --pid 123 --window 456 --json sp computer-use page query-dom --pid 123 --window 456 --selector a --attribute href --json sp computer-use page execute-javascript --pid 123 --window 456 '(() => document.title)()' --json
需要 DOM 访问的 Electron 应用,启动时开启渲染器调试端口:
sp computer-use launch --bundle-id com.example.ElectronApp --electron-debugging-port 9222 --json
当点击响应返回 popup 警告时,对弹出按钮使用 set-value。若元素点击返回 action_failed,重新快照,仅在截图显示目标仍需像素点击时使用坐标重试。每次操作后重新运行快照,检查变化的元素状态或截图。
规则
- Supaterm 应用必须正在运行。
- 使用
--element前必须对目标窗口运行快照。 --query只过滤返回的元素,不会重新编号缓存索引。- 仅在没有可用元素时使用坐标。
- 浏览器导航使用
launch --url,不要通过 AX 设置地址栏。 - 若浏览器提示必须启用来自 Apple Events 的 JavaScript,应停止并通知用户,不要在设置启用前反复重试 JavaScript 或 Safari select 回退命令。
- 除非用户指定位置,
--image-out路径保持在 /tmp 下。 - 若缺少权限,告知用户打开 Supaterm 设置 > Computer Use。
参考文档
- 权限:references/permissions.md
- 应用与窗口:references/apps-and-windows.md
- 快照与元素:references/snapshot-and-elements.md
- 操作:references/actions.md