👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
定向查找(macOS)
知道控件的文案或角色时,可以直接查找,不用先截图或读取整棵 AX 树。应用需要已经运行,查询不会启动、激活或抬升窗口。
在持久 MCP 会话或 ocu repl 中:
var safari = await cua.getApp("Safari", { initialState: false });
var result = await safari.query({ text: "Compose", role: "button", exact: true });
nodeRepl.write(result);
确认结果后,可以在同一会话里操作索引:
if (!result.truncated && result.matches.length === 1) {
await safari.click(result.matches[0].index);
}
getApp() 默认仍会读取初始状态。加上 initialState: false 才会跳过。
CLI 也可以单独查看查询结果:
ocu call query --args '{"app":"Safari","text":"Compose","role":"button","exact":true}'
不同 CLI 调用不能共享索引。索引只在当前 native 会话有效,120 秒后过期,最多保留 5000 个;重置或结束会话后需要重新查询。操作前会重新检查应用进程、窗口、控件和当前位置,验证失败时不会使用旧坐标。
参数与结果
text 和 role 至少填一个。同时填写时,两者都要匹配。文字不区分大小写,匹配 title、description 或 value;角色可以写 button 或 AXButton。
| JS 参数 | native 参数 | 默认值 | 含义 |
|---|---|---|---|
text |
text |
无 | 查找文案,最多 1000 个 UTF-16 编码单元 |
role |
role |
无 | AX 角色,最多 1000 个 UTF-16 编码单元 |
exact |
exact |
false |
完整文字匹配;不开则按子串匹配,精确匹配失败不会自动放宽 |
limit |
limit |
20 |
最多返回多少项,正整数,上限 100 |
maxNodes |
max_nodes |
500 |
最多遍历多少个节点,正整数,上限 5000 |
windowId |
window_id |
当前窗口 | 指定应用的窗口 ID,范围 1–4294967295 |
返回对象包含 matches、truncated、stop_reason、visited_nodes、window_id 和生效的 limit / max_nodes。每项包含 index 及可读取的角色、文案、值、标识、窗口内坐标、动作。
truncated: true 表示查询不完整,即使 matches 是空数组,也不能认定控件不存在。stop_reason 为 limit、max_nodes、timeout、ax_error 或 text_limit;完整搜索为 complete。长文字只搜索开头的有界片段,输出文案最多 1000 字符。达到结果上限时,也会保守标记不完整。
遍历采用 2 秒协作式截止时间,并限制每次 AX 调用的等待时间;正在执行的系统调用不能被这个截止时间强行中断。查询依赖应用暴露的 AX 控件,不保证找到未渲染的列表行或窗口外的控件。Windows / Linux 暂不支持。