文档 / CLI / 计算机使用
The orca computer CLI 允许 agent 检查并控制原生桌面应用——列出正在运行的应用、读取辅助功能树、点击控件、设置值、输入文本、滚动以及截取屏幕截图。当任务需要操作操作系统或第三方应用，而不是终端或内置浏览器时，请使用它。
Computer use 按平台提供原生辅助工具，并需要辅助功能（在 macOS 上还需要屏幕录制）权限。命令接口已足够稳定，可供技能基于其构建，但标志名称仍可能变化。
首次设置¶
检查运行时和权限：
如果 permissions 报告缺少任何权限，请在系统设置中为 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 <id> --json
orca computer click --app com.microsoft.edgemac --window-id <id> --element-index 12 --json
当列出的 id 不是 none 时，请优先使用稳定的 --window-id；否则使用 --window-index。
选择应用¶
优先使用 list-apps 返回的 bundle ID：
当应用名称无歧义时可以使用应用名称（--app Spotify）。仅当 bundle ID 和名称都冲突时，才使用 --app pid:<number>。
可用操作¶
orca computer click --app <app> --element-index <i> --json
orca computer set-value --app <app> --element-index <i> --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 <i> --direction down --json
orca computer drag --app <app> --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json
orca computer perform-secondary-action --app <app> --element-index <i> --action <name> --json
优先使用语义操作（click、set-value、perform-secondary-action），而不是原始的 type-text 或 press-key——它们直接针对辅助功能元素，并且不会像键盘输入那样因焦点变化而失效。
当辅助功能定位失败时，请谨慎回退到坐标：
orca computer click --app com.apple.Safari --x 120 --y 340 --json
orca computer drag --app <app> --from-element-index 3 --to-element-index 9 --json
敏感输入¶
通过 stdin 传递机密信息，以免其进入 shell 历史记录：
printf '%s' "$TEXT" | orca computer set-value \
--app com.apple.Safari --element-index 7 --value-stdin --json
--text-stdin 对 type-text 和 paste-text 的作用方式相同。
在 Linux 和 Windows 上，当辅助工具运行时，操作负载也会短暂通过本地操作文件传递。Stdin 可避免机密信息进入 shell 历史记录，但并不能对每个本地观察者隐藏它们；除非任务明确要求，否则避免发送机密信息。
屏幕截图¶
get-app-state 会返回辅助功能树，并且默认返回屏幕截图。使用 --json 时，图像字节会被写入磁盘，并在 screenshot.path 中返回路径，而不是嵌入在响应中。当不需要像素时，请传递 --no-screenshot（更快，负载更小）。传递 --restore-window 可在捕获前将隐藏或最小化的窗口恢复到可见状态。
从 agent 中使用¶
随附的 computer-use 技能将相同的命令接口与安全指南打包在一起。将其安装到 agent 的技能目录中：
有关技能如何被加载，请参阅 技能注册表与 MCP。
后续步骤¶
- Orca CLI 概览 — CLI 接口的其余部分（worktrees、terminal、browser）。
- 技能注册表与 MCP — 将此 CLI 分发给 agents。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 orca48/orca