第26章 计算机操作（Computer Use）

计算机操作 通过无障碍树、截图和安全 UI 操作，让 Agent 驱动本地桌面应用。Orca Computer CLI 允许 Agent 检查和控制原生桌面应用——包括列出运行中的应用、读取无障碍树、点击控件、设置值、输入文本、滚动以及截图。当任务需要操作系统或第三方应用，而非终端或内置浏览器时，应使用此功能。

首次设置 检查运行时和权限： orca status --json orca computer permissions --json orca computer capabilities --json 如果权限报告缺失项，请在系统设置中授予 Orca Computer Use 无障碍（在 macOS 上还需屏幕录制）权限，然后重新运行 permissions --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 元素索引的作用域仅限于最新的 get-app-state 结果，且可能是稀疏的。在 --json 输出中，请从 result.snapshot.treeText 读取树结构。不要根据 elementCount 随意捏造索引。在重用索引之前，若发生导航、焦点变更、滚动或应用重新渲染，请先刷新状态。

多窗口应用 orca computer list-windows --app com.microsoft.edgemac --json orca computer get-app-state --app com.microsoft.edgemac --window-id --json orca computer click --app com.microsoft.edgemac --window-id --element-index 12 --json 当列出的 id 不为 none 时，优先使用稳定的 --window-id；否则使用 --window-index。

选择应用 优先使用 list-apps 返回的 Bundle ID： orca computer get-app-state --app com.microsoft.edgemac --json 在名称无歧义时，应用名称也可用（--app Spotify）。仅当 Bundle ID 和名称都冲突时，才使用 --app pid:。

可用操作 orca computer click --app --element-index --json orca computer set-value --app --element-index --value "text" --json orca computer type-text --app --text "text" --json orca computer press-key --app --key Return --json orca computer hotkey --app --key CmdOrCtrl+A --json orca computer paste-text --app --text "text" --json orca computer scroll --app --element-index --direction down --json orca computer drag --app --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json orca computer perform-secondary-action --app --element-index --action --json 优先使用语义化操作（click、set-value、perform-secondary-action），而非原始的 type-text 或 press-key——它们直接定位无障碍元素，且在键盘输入无法处理的焦点变更中表现更稳健。