SuperAPI AI 工具集

supaterm-computer-use

通用与其它

查看项目

更新于 10-16 07:12

技能介绍

该技能用于在 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