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 或“Visible elements”推断有效索引。元素索引的有效时间很短，在延迟、导航、焦点变化、滚动、窗口变化或应用重新渲染后都会失效。

应用选择器

优先使用 list-apps 提供的捆绑包 ID；名称明确时也可使用名称。仅当捆绑包 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。仅在一个修饰键组合加一个按键时使用 hotkey，例如 CmdOrCtrl+A 或 CmdOrCtrl+Shift+P；跨平台组合优先使用 CmdOrCtrl+...。
• 某些操作可在后台应用中运行，但这取决于应用。如果操作成功却未更改 UI，请刷新状态，并选择更具语义性的操作，或恢复／聚焦窗口。
• 对于公开值的文本字段，优先使用 set-value；如果提供程序能够读取刷新后的值，它可以报告已验证的值写入。
• 坐标相对于窗口；请使用针对同一目标窗口的最新屏幕截图／状态中的坐标。

截图

get-app-state 会返回树和截图。使用树中的索引执行操作，并用截图进行视觉确认；捕获失败通常表示目标被隐藏、最小化、移出屏幕或受到权限限制。

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

action_x = screenshot_pixel_x / screenshot.scale
action_y = screenshot_pixel_y / screenshot.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 重试。如果目标是 Gmail 等 Web 应用，请选择包含该应用的桌面浏览器应用／窗口；不要原样重试 orca computer ... --app Gmail，因为 orca computer 的应用选择器指的是桌面应用，而非网站名称。
• app_blocked：停止操作；该目标已被有意禁止使用计算机。
• 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：该元素没有可操作的 frame；改用具有 frame 的父级／子级元素，或根据最新截图选择窗口内坐标。
• 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 / orca computer permissions --id screenshots --json，使用设置界面，然后重试。

下一步操作

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