cua-control 是一组面向 Cua 沙箱(处于本机模式时则面向 localhost)的控制原语,用于模拟鼠标、键盘与滚动操作。当需要操作屏幕坐标时,应先调用 cua_screenshot 获取当前画面,不要凭猜测确定像素位置。
坐标以目标显示屏左上角为原点的像素值;默认沙箱分辨率为 1024x768(XGA),与 Anthropic 推荐的 computer-use 分辨率一致,macOS 上的 Retina/HiDPI 缩放由 Cua 内部处理。
cua_click 支持左、右、中键及多次点击,例如 cua_click({ x: 320, y: 180 })、cua_click({ x: 320, y: 180, button: "right" })、cua_click({ x: 320, y: 180, clicks: 2 })。
cua_type 逐字符输入,例如 cua_type({ text: "hello world" }),文本中的换行会作为 Return 输入。
cua_key 可按下单个组合键或一组按键序列,例如 cua_key({ keys: "Return" })、cua_key({ keys: "ctrl+s" })、cua_key({ keys: ["cmd+space", "Return"] })。常用键名包括 Return、Escape、Tab、BackSpace、Delete、方向键、Page_Up、Page_Down、Home、End、F1 至 F12,以及 ctrl+a、ctrl+c、ctrl+v、cmd+s(macOS)、super+l(Linux)等组合。
cua_scroll 使用 dx/dy 滚轮增量,dy 为负表示向下滚动,dx 为正表示向右,示例包括 cua_scroll({ x: 400, y: 300, dy: -5 })、cua_scroll({ x: 400, y: 300, dy: 5 })、cua_scroll({ x: 400, y: 300, dx: 3 });scrollX/scrollY 仍作为别名被接受。
推荐流程:先 cua_screenshot 观察状态,找到目标的 x、y,再执行点击或输入,随后再次截图验证,循环进行。每次改变状态的操作之后都应重新截图,因为模型对屏幕的内部记忆在点击或输入后并不可靠。除上述内容外,其他功能暂未提供。