computer-use

计算机使用

通过 orca computer 使用此技能进行桌面 UI 操作。当请求的目标是网站或 Web 应用时，操作包含该页面的桌面浏览器应用/窗口。

前置条件

• 优先使用 orca computer ...；在 Linux 上，如果 orca 不可用，则使用 orca-ide computer ...。在此 Orca 工作树中，仅在测试本地开发运行时使用 ./config/scripts/orca-dev computer ...。
• 优先使用 --json。截图字节从 JSON 中省略，并写入 screenshot.path。
• 除非用户明确要求，否则不要提交表单、发送消息、购买物品、删除数据、更改账户设置或泄露秘密。
• 如果应用包含敏感内容，仅读取用户请求的内容。

orca status --json
orca computer capabilities --json

核心循环

orca computer list-apps --json
orca computer get-app-state --app com.spotify.client --json
orca computer click --app com.spotify.client --element-index 42 --json

使用每个操作返回的最新状态来确定下一个元素索引。元素索引是树中显示的数字标签；当嘈杂部分被省略时，它们可能稀疏，因此切勿从 elementCount 或“可见元素”推断有效索引。元素索引是短暂的，在延迟、导航、焦点变化、滚动、窗口变化或应用重新渲染后会失效。

应用选择器

优先使用 list-apps 中的 bundle ID；当名称明确时也可接受。仅当 bundle ID 或名称匹配不明确时使用 pid:<number>。

orca computer get-app-state --app com.microsoft.edgemac --json
orca computer get-app-state --app Spotify --json
orca computer get-app-state --app pid:12345 --json

对于具有多个窗口或标题不明确的应用，先运行 list-windows。当列出的 id 不是 none 时，优先使用 --window-id <id>；否则使用 --window-index <n>。选择窗口后，将相同的选择器传递给 get-app-state 和后续操作，直到目标窗口发生变化。

命令

orca computer permissions --json
orca computer capabilities --json
orca computer list-apps --json
orca computer list-windows --app <app> --json
orca computer get-app-state --app <app> --json
orca computer get-app-state --app <app> --restore-window --json
orca computer click --app <app> --element-index <index> --json
orca computer click --app <app> --x 100 --y 100 --json
orca computer perform-secondary-action --app <app> --element-index <index> --action <name> --json
orca computer set-value --app <app> --element-index <index> --value "text" --json
orca computer type-text --app <app> --text "text" --json
orca computer press-key --app <app> --key Return --json
orca computer hotkey --app <app> --key CmdOrCtrl+A --json
orca computer paste-text --app <app> --text "text" --json
orca computer scroll --app <app> (--element-index <index> | --x <x> --y <y>) --direction down --json
orca computer drag --app <app> --from-element-index <index> --to-element-index <index> --json
orca computer drag --app <app> --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json

仅在不需要像素时使用 --no-screenshot。对敏感文本使用 --text-stdin 或 --value-stdin，以便负载不会进入 shell 历史记录。在 Linux 和 Windows 上，操作负载仍会通过短暂的本地操作文件传递，因此除非用户明确要求，否则避免发送秘密：

printf '%s' "$TEXT" | orca computer set-value --app <app> --element-index <index> --value-stdin --json

操作规则

• 优先使用语义操作：可编辑字段使用 set-value，控件使用 click，仅对列出的操作名称使用 perform-secondary-action。
• 在任何更改 UI 的操作之后，使用返回的状态或重新运行 get-app-state，然后再选择下一个元素索引。
• 仅在聚焦字段并确认应用有焦点文本接收器后使用 type-text；合成键盘传递报告为未验证，因此在假设文本已输入之前检查返回的状态。
• 对于单个/导航键（如 Return、Escape、Tab 和方向键）使用 press-key。仅对单个修饰键和弦加一个键（如 CmdOrCtrl+A 或 CmdOrCtrl+Shift+P）使用 hotkey；跨平台组合键优先使用 CmdOrCtrl+...。
• 某些操作在后台应用中有效，但这取决于应用。如果成功未更改 UI，则刷新状态并选择更语义化的操作或恢复/聚焦窗口。
• 对于暴露值的文本字段，优先使用 set-value；当提供者可以读取刷新后的值时，它可以报告已验证的值写入。
• 坐标是窗口局部的；使用来自同一目标窗口的最新截图/状态的坐标。

截图

get-app-state 返回树和截图。使用树获取索引/操作，使用截图进行视觉确认；捕获失败通常意味着窗口隐藏、最小化、屏幕外或权限被阻止。

传递给 click、scroll 和 drag 的坐标是窗口局部的操作坐标。如果截图报告的 scale 不是 1，则在操作前转换视觉截图像素：

操作_x = 截图像素_x / 截图.scale
操作_y = 截图像素_y / 截图.scale

当可用时，优先使用树中的元素索引或元素框架。仅在检查最新截图比例和窗口大小后，使用从截图派生的原始坐标。

在 Linux 和 Windows 上，截图可能来自目标窗口边界的可见桌面区域。如果视觉像素重要，使用 --restore-window 以确保其他窗口不会覆盖目标区域；如果无法获取焦点，则信任树而非可能被遮挡的像素。

应用说明

浏览器：对于 Edge、Chrome、Safari 等浏览器窗口，直接设置地址/搜索字段，然后按 Return。不要假设原始输入进入了地址栏。当浏览器未处于最前面时，使用 --restore-window。大的标签栏可能只显示活动标签加上“非活动浏览器标签已省略”标记；将其视为有意的噪声减少，并在当前页面/地址栏上操作，除非用户要求管理标签。

对于浏览器托管的表单（如 Gmail 撰写），在每个字段操作后验证聚焦的 UI 元素。页面文本字段可以暴露无障碍操作而不移动 DOM 焦点；如果点击或 set-value 未更改焦点接收器，则从已知聚焦字段使用 Tab / Shift+Tab，或从最新截图使用窗口局部坐标。对于草稿正文，优先将 paste-text 粘贴到已验证的聚焦字段，然后在继续之前检查返回的状态。

orca computer get-app-state --app com.microsoft.edgemac --restore-window --json
orca computer set-value --app com.microsoft.edgemac --element-index <addressBarIndex> --value "test123" --json
orca computer press-key --app com.microsoft.edgemac --key Return --json

Spotify：在播放点击后刷新；UI 通常会异步变化。

Slack：无障碍树可能较浅，而截图包含有用信息。当请求时，读取可见的 Slack UI 是可以的；发送消息或触发工作流仍需明确权限。

错误

• app_not_found：运行 list-apps 并使用 bundle ID 重试。如果目标是 Web 应用（如 Gmail），选择包含它的桌面浏览器应用/窗口；不要直接重试 orca computer ... --app Gmail，因为 orca computer 应用选择器指的是桌面应用，而非网站名称。
• app_blocked：停止；目标被有意阻止使用 computer-use。
• window_not_found / window_stale：运行 list-windows，选择当前选择器，然后重新运行 get-app-state。
• window_not_focused：使用 --restore-window 重试一次；如果消息说已请求恢复，则停止重试恢复，并手动将应用置于前台或检查权限。对于可编辑字段，优先使用 set-value，然后在假设键盘输入有效之前进行检查。
• element_not_found：索引已过期；重新运行 get-app-state。
• unsupported_capability：提供者或桌面环境无法执行该操作；使用语义替代方案，或者如果消息指定了缺失的依赖项，则安装它。
• action_not_supported：检查元素列出的操作，并使用其中一个名称重试，或者在适当时使用 click/set-value。
• value_not_settable：元素无法接受直接值写入；聚焦它，并仅在返回状态可检查时使用键盘输入。
• element_not_clickable：元素没有可操作的框架；使用具有框架的父/子元素，或从最新截图选择窗口局部坐标。
• invalid_argument：修复命令标志；不要原样重试相同的命令。
• action_timeout：在重试之前检查当前状态，然后使用更简单的语义操作，或者如果观察速度慢则使用 --no-screenshot。
• screenshot_failed：如果树状态足够，使用 --no-screenshot；如果消息提到屏幕录制或截图权限，运行 orca computer permissions --id screenshots --json。
• accessibility_error：运行 orca computer capabilities --json；如果消息提到无障碍权限，运行 orca computer permissions --id accessibility --json。
• 空树或无截图：应用可能没有可见窗口、已最小化或需要权限。
• 权限错误：运行 orca computer permissions --json，或者当消息指定一个权限时运行 orca computer permissions --id accessibility --json / --id screenshots --json，使用设置 UI，然后重试。

下一步操作

确认 Orca 状态（除非已检查），然后运行 orca computer capabilities --json。对于网站或 Web 应用目标（如 Gmail），识别包含页面的桌面浏览器应用/窗口，然后使用 orca computer get-app-state --app <app> --json 获取该目标应用状态。