Orca computer-use 实战指南用orca computer驱动桌面应用级 UI 检查与输入【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca本文基于仓库内 computer-use 技能指南 整理完整讲解 Orca 的 computer-use CLIorca computer命令族如何对可见的本地应用窗口做操作系统级别的检查与输入——包括解析可执行文件、读取可访问性树、点击/输入/拖拽动作、截图坐标换算、验证语义与全部错误码的处理方法并结合 src/cli/handlers/computer.ts、src/shared/computer-use-runtime-types.ts 等源码实现说明每条命令背后的 RPC 调用链与约束来源读完即可安全地在真实桌面环境中驱动 Chrome/Edge/Safari、Spotify、Slack 等应用。适用边界什么时候用 computer-useOrca 的计算机使用能力定位于桌面窗口层其分工边界在指南 frontmatter 中已经写得很明确应当使用orca computer任务需要读取或操作原生应用或运行在外部桌面浏览器窗口如 Chrome、Edge、Safari/应用 webview 中的页面且需要桌面级控制窗口恢复、焦点、窗口内坐标点击等不要使用Orca 内嵌浏览器或纯页面浏览器自动化。内嵌页面请用orca-cli技能外部页面请用 Playwright / CDP 这类页面自动化工具。从源码结构看这套命令由 CLI 处理器统一注册为computer前缀的子命令族COMPUTER_HANDLERS见 src/cli/handlers/computer.ts每个子命令最终都通过运行时客户端调用一个同名 RPC如computer.click→computer.click因此指南中所有示例都可加--json获得机器可解析的输出这也是 Agent 驱动调用时的首选模式。前置条件解析可执行文件与安全约束指南对用哪个可执行文件给出了只解析一次的固定优先级后续所有命令复用同一个选择若设置了环境变量ORCA_CLI_COMMAND使用其值Orca 为托管 WSL 会话导出该变量否则在暴露ORCA_DEV_REPO_ROOT的开发会话中使用orca-dev否则在Orca 托管终端之外的 Linux上使用orca-ide其余场景使用orca。其中第 3 条背后有一个真实的坑在未托管的 Linux 上绝不能先尝试裸orca因为它通常解析为 GNOME 的 Orca 屏幕阅读器/usr/bin/orca会在用户机器上意外启动语音播报。同时指南约定了一个文档记法示例中的ORCA是占位符即使示例点名了某种 shell 也是如此运行前直接替换为你选定的可执行文件不要创建名为ORCA的 shell 变量、更不要字面执行ORCA。未点名 shell 的代码块刻意保持 shell 中性同时适用于 POSIX shell、PowerShell 与 cmd.exe。安全红线同样前置除非用户明确要求不要 push、提交表单、发送消息、购买商品、删除数据、修改账户设置或暴露密钥若应用包含敏感内容只读取用户要求读取的部分若选定的可执行文件无法运行报告其确切错误并停止不要落回另一个可执行文件——那可能悄悄指向另一个 Orca 构建。确认环境就绪的最小二步ORCA status --json ORCA computer capabilities --jsoncomputer capabilities的--json输出对应运行时类型 ComputerProviderCapabilities包含provider、protocolVersion以及分组的supportsapps/windows/observation/actions/surfaces。其 pretty 输出由 formatComputerCapabilities 生成例如展示 Actions 中启用了哪些动作click, typeText, pressKey, ...。能力查询是判断当前平台/provider 能做哪些事的权威来源也是排错unsupported_capability的第一步。核心循环list-apps → get-app-state → 动作指南给出的核心工作循环只有三步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 计数推断合法索引索引是短命的。延迟、导航、焦点变化、滚动、窗口切换或应用重渲染之后索引即失效必须重新get-app-state。从类型定义可以印证这一设计的字段来源快照数据 ComputerSnapshotData 包含treeText可访问性树文本、elementCount仅计数、focusedElementId和truncation元数据。指南因此明确要求在--json输出中从result.snapshot.treeText读取可访问性树与动作索引elementCount只是一个计数不得用来推断索引。应用与窗口选择器应用选择器的优先级为优先使用list-apps给出的bundle ID如com.spotify.client、com.microsoft.edgemac名字在无歧义时可用如Spotify仅当 bundle ID 或名字匹配产生歧义时使用pid:number如pid:12345。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-windowsORCA computer list-windows --app app --json窗口选择规则当列表中给出的id不为none时优先--window-id id否则用--window-index n。一旦选定窗口在目标窗口变化前后续get-app-state与所有动作命令都应持续传递同一选择器避免动作落到别的窗口。这一约束在 CLI 侧有硬性校验--window-id与--window-index通过validateExclusiveWindowTarget保证互斥见 src/cli/handlers/computer-action-flags.ts同时传两者会得到invalid_argument。命令参考完整动作面指南给出的完整命令面如下ORCA均为上文选定的可执行文件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 click --app app --x 100 --y 100 --modifiers CmdOrCtrlShift --json ORCA computer click --app app --element-index index --mouse-button right --json ORCA computer click --app app --element-index index --mouse-button middle --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 CmdOrCtrlA --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结合源码可以补充几条参数约束的取值边界click 目标二选一--element-index与--x/--y坐标互斥由validateElementOrCoordinates强制--mouse-button接受左/中/右键等有限集合validateMouseButton--click-count为正整数keyboard 校验规则press-key只接受单个键如Return、Escape、Tab、箭头键特殊地接受hotkey只接受一组修饰键 恰好一个键如CmdOrCtrlA、CmdOrCtrlShiftPclick --modifiers只接受修饰键组合最多 4 个部分如CmdOrCtrl、CmdOrCtrlShift。这三条规则的白名单与报错提示集中在 src/shared/computer-use-key-spec.ts修饰键集合alt/cmd/command/control/ctrl/meta/option/shift/super/win跨平台组合推荐CmdOrCtrl...stdin 与直传互斥--text与--text-stdin、--value与--value-stdin不可同时给出--value允许空串而--text不允许见 getTextPayloadpermissions 的--id只接受accessibility或screenshots其他值直接报invalid_argumentsrc/cli/handlers/computer.ts#L220-L228。computer permissions的 pretty 输出还会说明权限设置流程只在 macOS 上需要其他平台直接提示无需设置通用观察开关--no-screenshot布尔开关跳过截图与--restore-window恢复/前置目标窗口适用于get-app-state与各动作命令getComputerObserveFlags。敏感文本stdin 传递与本地操作文件--text-stdin/--value-stdin的意义是让文本 payload不落 shell 历史。POSIX shell 示例printf %s $TEXT | ORCA computer set-value --app app --element-index index --value-stdin --jsonPowerShell / cmd.exe 应使用等价的 stdin 机制且同样避免历史暴露。注意 CLI 侧会显式拒绝 TTY stdinstdin payload requested but stdin is a TTY即必须真的有管道输入。一个重要的平台差异在 Linux 和 Windows 上动作 payload 仍然会经过一个短命的本地操作文件这是桌面脚本 provider 的投递机制可从 desktop-script-provider-test-harness.ts 中对operationFiles的模拟看到写操作文件→脚本读取的链路Linux 侧脚本为 native/computer-use-linux/runtime.pyWindows 侧为 native/computer-use-windows/runtime.ps1。因此指南给出保守建议除非用户明确要求避免经由 computer-use 发送密钥类内容。动作验证语义verified / unverified每个动作命令的 JSON 输出都携带验证元数据指南要求把provider 调用是否成功与动作是否被验证分开阅读。四个档位的完整定义验证状态含义verified变更后的值已被读回确认provider 能读到刷新后的值unverified (accessibility action unasserted)可访问性调用成功但没有做后置状态断言unverified (synthetic input)合成输入打进了虚空无法验证缺失验证元数据一律视为 unverified包括旧版运行时的响应源码层面这条缺失即 unverified的规则是显式实现的normalizeComputerActionResult 会在action.verification缺失时按动作路径回填unverified及原因——path: synthetic→synthetic_inputpath: clipboard→clipboard_pastepath: accessibility→accessibility_action_unasserted。ComputerActionMetadata 中还定义了更多unverified原因readback_unsupported、window_changed、value_mismatch、provider_unavailable以及verified时可携带的propertyfocusedText/selection/value与actualPreview。由此派生的动作选择规则优先语义化动作可编辑字段用set-value控件用clickperform-secondary-action只用于元素已列出的动作名任何改变 UI 的动作之后用返回的状态或重新get-app-state再决定下一个索引type-text只在已聚焦字段并确认应用存在聚焦的文本接收器之后使用——合成键盘投递报告为 unverified必须先检查返回状态再假设文本落地文本字段若暴露 value优先set-valueprovider 能读回刷新值时它会报告verified的值写入部分动作在后台应用上可行但因应用而异若成功却没有 UI 变化刷新状态、改用语义化动作或恢复/聚焦窗口。截图与坐标换算get-app-state与动作命令默认请求截图除非--no-screenshot成功的--json捕获通常保存在result.screenshot.path该路径缺失时使用内联 base64 的result.screenshot.datapretty 输出不落盘图片树tree用于索引/动作截图用于视觉确认捕获失败通常意味着窗口隐藏、最小化、离屏或被权限阻断。类型上ComputerScreenshotData 提供scale、width/height、path、dataOmitted、expiresAtscreenshotStatus则显式区分captured / skipped(no_screenshot_flag) / failed三态macOS 侧还带engine元数据screenCaptureKit/cgWindowList。坐标换算是实操重点传给click、scroll、drag的坐标是窗口局部动作坐标快照中coordinateSpace: window。若截图报告的scale不为1先换算再动作action_x screenshot_pixel_x / screenshot.scale action_y screenshot_pixel_y / screenshot.scale优先级上能用元素索引或树中的元素 frame就不用裸坐标必须用截图反推坐标时先核对最新截图的scale与窗口尺寸。平台差异在Linux 和 Windows上截图可能来自目标窗口边界对应的可见桌面区域——若另一个窗口覆盖了目标区域像素就是别人的。处理办法视觉像素重要时用--restore-window让目标窗口回到最前无法抢占焦点时信任树而不是可能被遮挡的像素。应用专项经验指南按应用沉淀了四类高频经验浏览器Edge / Chrome / Safari 等直接向地址栏/搜索框写入值然后按Return——不要假设裸打字会落到地址栏浏览器不在最前时使用--restore-window大标签条通常只显示活动标签加一个 inactive browser tabs omitted 标记这是刻意的降噪除非用户要求管理标签否则只在当前页面/地址栏操作。典型序列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浏览器内嵌表单如 Gmail 撰写每个字段动作后验证聚焦元素是否如预期变化。页面文本字段可能暴露可访问性动作但不移动 DOM 焦点若点击或set-value没有改变聚焦接收器从已知聚焦字段用Tab/ShiftTab移动或改用新鲜截图给出的窗口局部坐标。草稿正文优先paste-text写入已验证聚焦的字段再继续前检查返回状态。Spotify播放类点击后必须刷新状态UI 经常异步变化。Slack可访问性树可能很浅而截图里有信息量。按用户要求读取 Slack 可见 UI 是允许的但发送消息或触发工作流仍需要明确授权。错误码与处置手册指南的 Errors 一节是排错的核心资产逐条处置如下错误码处置app_not_found运行list-apps换用 bundle ID 重试。若目标是 Gmail 这类 web 应用选择承载它的桌面浏览器应用/窗口不要原样重试--app Gmail——computer-use 的选择器指桌面应用不指网站名app_blocked停止该应用被有意排除在 computer-use 之外window_not_found/window_stale运行list-windows选一个当前有效的选择器重新get-app-statewindow_not_focused用--restore-window重试一次若提示恢复已请求过停止重试手动前置应用或检查权限。可编辑字段优先set-value之后检查状态再假设键盘输入生效element_not_found索引已过期重新get-app-stateunsupported_capability当前 provider/桌面环境做不了该动作换语义化替代或按报错提示安装缺失依赖action_not_supported检查元素的已列出动作用其中之一重试或改用 click/set-valuevalue_not_settable元素不接受直接写值聚焦它后仅在返回状态可检查时使用键盘输入element_not_clickable元素没有可操作 frame改用带 frame 的父/子元素或从最新截图取窗口局部坐标invalid_argument修正命令参数不要原样重试action_timeout先检查当前状态再重试用更简单的语义动作或观察太慢时用--no-screenshotscreenshot_failed树状态够用就--no-screenshot若提示 Screen Recording/截图权限运行ORCA computer permissions --id screenshots --jsonaccessibility_error运行ORCA computer capabilities --json若提示 Accessibility 权限运行ORCA computer permissions --id accessibility --json空树或无截图应用可能没有可见窗口、最小化或缺权限权限错误通用运行ORCA computer permissions --json或按提示--id accessibility/--id screenshots通过设置 UI 授权后重试类型定义中还可看到完整错误码集合 COMPUTER_ERROR_CODES除上述各码外还包含provider_incompatible与permission_denied等遇到指南未逐条展开的码时建议同样按刷新状态 → 核对 capabilities → 再动作的顺序排查。起步建议与版本匹配的指南获取开始一个 computer-use 任务时的标准动作序列对应指南的 Next Action 一节若尚未确认先ORCA status --json必要时先ORCA open --json启动应用运行ORCA computer capabilities --json了解当前 provider 的能力面对外部浏览器目标如 Gmail先识别承载该页面的桌面浏览器应用/窗口用ORCA computer get-app-state --app app --json获取目标应用状态进入核心循环。最后一点值得写进工作流仓库中 skills/computer-use/SKILL.md 是一个发现型 stub它明确说明完整指南由orca二进制自身通过ORCA skills get computer-use下发——刻意不在文件中罗列子命令so it can never drift from the binary that will actually run your commands使其永远不会与实际执行命令的二进制发生漂移。本文对应的完整版即 skill-guides/computer-use.md与技能 stub 的 frontmattername: computer-use一一对应因此跨版本使用 Orca 时以所选二进制skills get的输出为准本文作为同一技能面的深度参考。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Orca computer-use 实战指南：用 `orca computer` 驱动桌面应用级 UI 检查与输入
Orca computer-use 实战指南用orca computer驱动桌面应用级 UI 检查与输入【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca本文基于仓库内 computer-use 技能指南 整理完整讲解 Orca 的 computer-use CLIorca computer命令族如何对可见的本地应用窗口做操作系统级别的检查与输入——包括解析可执行文件、读取可访问性树、点击/输入/拖拽动作、截图坐标换算、验证语义与全部错误码的处理方法并结合 src/cli/handlers/computer.ts、src/shared/computer-use-runtime-types.ts 等源码实现说明每条命令背后的 RPC 调用链与约束来源读完即可安全地在真实桌面环境中驱动 Chrome/Edge/Safari、Spotify、Slack 等应用。适用边界什么时候用 computer-useOrca 的计算机使用能力定位于桌面窗口层其分工边界在指南 frontmatter 中已经写得很明确应当使用orca computer任务需要读取或操作原生应用或运行在外部桌面浏览器窗口如 Chrome、Edge、Safari/应用 webview 中的页面且需要桌面级控制窗口恢复、焦点、窗口内坐标点击等不要使用Orca 内嵌浏览器或纯页面浏览器自动化。内嵌页面请用orca-cli技能外部页面请用 Playwright / CDP 这类页面自动化工具。从源码结构看这套命令由 CLI 处理器统一注册为computer前缀的子命令族COMPUTER_HANDLERS见 src/cli/handlers/computer.ts每个子命令最终都通过运行时客户端调用一个同名 RPC如computer.click→computer.click因此指南中所有示例都可加--json获得机器可解析的输出这也是 Agent 驱动调用时的首选模式。前置条件解析可执行文件与安全约束指南对用哪个可执行文件给出了只解析一次的固定优先级后续所有命令复用同一个选择若设置了环境变量ORCA_CLI_COMMAND使用其值Orca 为托管 WSL 会话导出该变量否则在暴露ORCA_DEV_REPO_ROOT的开发会话中使用orca-dev否则在Orca 托管终端之外的 Linux上使用orca-ide其余场景使用orca。其中第 3 条背后有一个真实的坑在未托管的 Linux 上绝不能先尝试裸orca因为它通常解析为 GNOME 的 Orca 屏幕阅读器/usr/bin/orca会在用户机器上意外启动语音播报。同时指南约定了一个文档记法示例中的ORCA是占位符即使示例点名了某种 shell 也是如此运行前直接替换为你选定的可执行文件不要创建名为ORCA的 shell 变量、更不要字面执行ORCA。未点名 shell 的代码块刻意保持 shell 中性同时适用于 POSIX shell、PowerShell 与 cmd.exe。安全红线同样前置除非用户明确要求不要 push、提交表单、发送消息、购买商品、删除数据、修改账户设置或暴露密钥若应用包含敏感内容只读取用户要求读取的部分若选定的可执行文件无法运行报告其确切错误并停止不要落回另一个可执行文件——那可能悄悄指向另一个 Orca 构建。确认环境就绪的最小二步ORCA status --json ORCA computer capabilities --jsoncomputer capabilities的--json输出对应运行时类型 ComputerProviderCapabilities包含provider、protocolVersion以及分组的supportsapps/windows/observation/actions/surfaces。其 pretty 输出由 formatComputerCapabilities 生成例如展示 Actions 中启用了哪些动作click, typeText, pressKey, ...。能力查询是判断当前平台/provider 能做哪些事的权威来源也是排错unsupported_capability的第一步。核心循环list-apps → get-app-state → 动作指南给出的核心工作循环只有三步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 计数推断合法索引索引是短命的。延迟、导航、焦点变化、滚动、窗口切换或应用重渲染之后索引即失效必须重新get-app-state。从类型定义可以印证这一设计的字段来源快照数据 ComputerSnapshotData 包含treeText可访问性树文本、elementCount仅计数、focusedElementId和truncation元数据。指南因此明确要求在--json输出中从result.snapshot.treeText读取可访问性树与动作索引elementCount只是一个计数不得用来推断索引。应用与窗口选择器应用选择器的优先级为优先使用list-apps给出的bundle ID如com.spotify.client、com.microsoft.edgemac名字在无歧义时可用如Spotify仅当 bundle ID 或名字匹配产生歧义时使用pid:number如pid:12345。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-windowsORCA computer list-windows --app app --json窗口选择规则当列表中给出的id不为none时优先--window-id id否则用--window-index n。一旦选定窗口在目标窗口变化前后续get-app-state与所有动作命令都应持续传递同一选择器避免动作落到别的窗口。这一约束在 CLI 侧有硬性校验--window-id与--window-index通过validateExclusiveWindowTarget保证互斥见 src/cli/handlers/computer-action-flags.ts同时传两者会得到invalid_argument。命令参考完整动作面指南给出的完整命令面如下ORCA均为上文选定的可执行文件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 click --app app --x 100 --y 100 --modifiers CmdOrCtrlShift --json ORCA computer click --app app --element-index index --mouse-button right --json ORCA computer click --app app --element-index index --mouse-button middle --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 CmdOrCtrlA --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结合源码可以补充几条参数约束的取值边界click 目标二选一--element-index与--x/--y坐标互斥由validateElementOrCoordinates强制--mouse-button接受左/中/右键等有限集合validateMouseButton--click-count为正整数keyboard 校验规则press-key只接受单个键如Return、Escape、Tab、箭头键特殊地接受hotkey只接受一组修饰键 恰好一个键如CmdOrCtrlA、CmdOrCtrlShiftPclick --modifiers只接受修饰键组合最多 4 个部分如CmdOrCtrl、CmdOrCtrlShift。这三条规则的白名单与报错提示集中在 src/shared/computer-use-key-spec.ts修饰键集合alt/cmd/command/control/ctrl/meta/option/shift/super/win跨平台组合推荐CmdOrCtrl...stdin 与直传互斥--text与--text-stdin、--value与--value-stdin不可同时给出--value允许空串而--text不允许见 getTextPayloadpermissions 的--id只接受accessibility或screenshots其他值直接报invalid_argumentsrc/cli/handlers/computer.ts#L220-L228。computer permissions的 pretty 输出还会说明权限设置流程只在 macOS 上需要其他平台直接提示无需设置通用观察开关--no-screenshot布尔开关跳过截图与--restore-window恢复/前置目标窗口适用于get-app-state与各动作命令getComputerObserveFlags。敏感文本stdin 传递与本地操作文件--text-stdin/--value-stdin的意义是让文本 payload不落 shell 历史。POSIX shell 示例printf %s $TEXT | ORCA computer set-value --app app --element-index index --value-stdin --jsonPowerShell / cmd.exe 应使用等价的 stdin 机制且同样避免历史暴露。注意 CLI 侧会显式拒绝 TTY stdinstdin payload requested but stdin is a TTY即必须真的有管道输入。一个重要的平台差异在 Linux 和 Windows 上动作 payload 仍然会经过一个短命的本地操作文件这是桌面脚本 provider 的投递机制可从 desktop-script-provider-test-harness.ts 中对operationFiles的模拟看到写操作文件→脚本读取的链路Linux 侧脚本为 native/computer-use-linux/runtime.pyWindows 侧为 native/computer-use-windows/runtime.ps1。因此指南给出保守建议除非用户明确要求避免经由 computer-use 发送密钥类内容。动作验证语义verified / unverified每个动作命令的 JSON 输出都携带验证元数据指南要求把provider 调用是否成功与动作是否被验证分开阅读。四个档位的完整定义验证状态含义verified变更后的值已被读回确认provider 能读到刷新后的值unverified (accessibility action unasserted)可访问性调用成功但没有做后置状态断言unverified (synthetic input)合成输入打进了虚空无法验证缺失验证元数据一律视为 unverified包括旧版运行时的响应源码层面这条缺失即 unverified的规则是显式实现的normalizeComputerActionResult 会在action.verification缺失时按动作路径回填unverified及原因——path: synthetic→synthetic_inputpath: clipboard→clipboard_pastepath: accessibility→accessibility_action_unasserted。ComputerActionMetadata 中还定义了更多unverified原因readback_unsupported、window_changed、value_mismatch、provider_unavailable以及verified时可携带的propertyfocusedText/selection/value与actualPreview。由此派生的动作选择规则优先语义化动作可编辑字段用set-value控件用clickperform-secondary-action只用于元素已列出的动作名任何改变 UI 的动作之后用返回的状态或重新get-app-state再决定下一个索引type-text只在已聚焦字段并确认应用存在聚焦的文本接收器之后使用——合成键盘投递报告为 unverified必须先检查返回状态再假设文本落地文本字段若暴露 value优先set-valueprovider 能读回刷新值时它会报告verified的值写入部分动作在后台应用上可行但因应用而异若成功却没有 UI 变化刷新状态、改用语义化动作或恢复/聚焦窗口。截图与坐标换算get-app-state与动作命令默认请求截图除非--no-screenshot成功的--json捕获通常保存在result.screenshot.path该路径缺失时使用内联 base64 的result.screenshot.datapretty 输出不落盘图片树tree用于索引/动作截图用于视觉确认捕获失败通常意味着窗口隐藏、最小化、离屏或被权限阻断。类型上ComputerScreenshotData 提供scale、width/height、path、dataOmitted、expiresAtscreenshotStatus则显式区分captured / skipped(no_screenshot_flag) / failed三态macOS 侧还带engine元数据screenCaptureKit/cgWindowList。坐标换算是实操重点传给click、scroll、drag的坐标是窗口局部动作坐标快照中coordinateSpace: window。若截图报告的scale不为1先换算再动作action_x screenshot_pixel_x / screenshot.scale action_y screenshot_pixel_y / screenshot.scale优先级上能用元素索引或树中的元素 frame就不用裸坐标必须用截图反推坐标时先核对最新截图的scale与窗口尺寸。平台差异在Linux 和 Windows上截图可能来自目标窗口边界对应的可见桌面区域——若另一个窗口覆盖了目标区域像素就是别人的。处理办法视觉像素重要时用--restore-window让目标窗口回到最前无法抢占焦点时信任树而不是可能被遮挡的像素。应用专项经验指南按应用沉淀了四类高频经验浏览器Edge / Chrome / Safari 等直接向地址栏/搜索框写入值然后按Return——不要假设裸打字会落到地址栏浏览器不在最前时使用--restore-window大标签条通常只显示活动标签加一个 inactive browser tabs omitted 标记这是刻意的降噪除非用户要求管理标签否则只在当前页面/地址栏操作。典型序列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浏览器内嵌表单如 Gmail 撰写每个字段动作后验证聚焦元素是否如预期变化。页面文本字段可能暴露可访问性动作但不移动 DOM 焦点若点击或set-value没有改变聚焦接收器从已知聚焦字段用Tab/ShiftTab移动或改用新鲜截图给出的窗口局部坐标。草稿正文优先paste-text写入已验证聚焦的字段再继续前检查返回状态。Spotify播放类点击后必须刷新状态UI 经常异步变化。Slack可访问性树可能很浅而截图里有信息量。按用户要求读取 Slack 可见 UI 是允许的但发送消息或触发工作流仍需要明确授权。错误码与处置手册指南的 Errors 一节是排错的核心资产逐条处置如下错误码处置app_not_found运行list-apps换用 bundle ID 重试。若目标是 Gmail 这类 web 应用选择承载它的桌面浏览器应用/窗口不要原样重试--app Gmail——computer-use 的选择器指桌面应用不指网站名app_blocked停止该应用被有意排除在 computer-use 之外window_not_found/window_stale运行list-windows选一个当前有效的选择器重新get-app-statewindow_not_focused用--restore-window重试一次若提示恢复已请求过停止重试手动前置应用或检查权限。可编辑字段优先set-value之后检查状态再假设键盘输入生效element_not_found索引已过期重新get-app-stateunsupported_capability当前 provider/桌面环境做不了该动作换语义化替代或按报错提示安装缺失依赖action_not_supported检查元素的已列出动作用其中之一重试或改用 click/set-valuevalue_not_settable元素不接受直接写值聚焦它后仅在返回状态可检查时使用键盘输入element_not_clickable元素没有可操作 frame改用带 frame 的父/子元素或从最新截图取窗口局部坐标invalid_argument修正命令参数不要原样重试action_timeout先检查当前状态再重试用更简单的语义动作或观察太慢时用--no-screenshotscreenshot_failed树状态够用就--no-screenshot若提示 Screen Recording/截图权限运行ORCA computer permissions --id screenshots --jsonaccessibility_error运行ORCA computer capabilities --json若提示 Accessibility 权限运行ORCA computer permissions --id accessibility --json空树或无截图应用可能没有可见窗口、最小化或缺权限权限错误通用运行ORCA computer permissions --json或按提示--id accessibility/--id screenshots通过设置 UI 授权后重试类型定义中还可看到完整错误码集合 COMPUTER_ERROR_CODES除上述各码外还包含provider_incompatible与permission_denied等遇到指南未逐条展开的码时建议同样按刷新状态 → 核对 capabilities → 再动作的顺序排查。起步建议与版本匹配的指南获取开始一个 computer-use 任务时的标准动作序列对应指南的 Next Action 一节若尚未确认先ORCA status --json必要时先ORCA open --json启动应用运行ORCA computer capabilities --json了解当前 provider 的能力面对外部浏览器目标如 Gmail先识别承载该页面的桌面浏览器应用/窗口用ORCA computer get-app-state --app app --json获取目标应用状态进入核心循环。最后一点值得写进工作流仓库中 skills/computer-use/SKILL.md 是一个发现型 stub它明确说明完整指南由orca二进制自身通过ORCA skills get computer-use下发——刻意不在文件中罗列子命令so it can never drift from the binary that will actually run your commands使其永远不会与实际执行命令的二进制发生漂移。本文对应的完整版即 skill-guides/computer-use.md与技能 stub 的 frontmattername: computer-use一一对应因此跨版本使用 Orca 时以所选二进制skills get的输出为准本文作为同一技能面的深度参考。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考