Computer Use

computer 让专家直接操作你的桌面：原生应用、游戏、任何没有 DOM 的界面。它是最底层的交互工具，也是最需要理解约束才用得好的一个。

激活条件

profy-computer 是 user_selectable: true 且 requires: { desktop_connected: true }。两个条件缺一不可——必须在插件面板勾选，且必须运行 Profy 桌面端。云端沙盒里这个插件不会激活。

元素寻址：优先 token，不要坐标

这是用好 computer 的关键，也是最容易踩坑的地方。cua-driver 0.17 的寻址规则很严：

方式	能否使用	要求
`element_token`	推荐	必须同时带 `pid`
`element_index` + `snapshot_id`	可用	必须是同一次 `get_window_state` 返回的这两个值，且带 `pid` + `window_id`
裸 `element_index`	被拒绝	报 `snapshot_id_required`
`x, y` 坐标	可用，最后手段	依赖分辨率和窗口位置

token 会过期：对同一个窗口再做一次 get_window_state，上一批 token 全部失效，报 stale_element_token。正确反应是重新取一次快照再重试，而不是换成坐标。

标准工作流

list_apps 或 get_accessibility_tree  → 找到目标应用的 pid
list_windows(pid=...)                → 找到 window_id
get_window_state(pid=..., window_id=...) → 拿到 snapshot_id + elements[]（含 element_token）
click / type / keypress / set_value  → 用 element_token + pid 操作
get_window_state 再来一次            → 验证结果（同时刷新 token）

第 5 步不是可选的——像素级操作没有返回值告诉你「点中了没有」，只有重新快照才能确认。

18 个 action

观察

action	参数	说明
`screenshot`	无参数=全屏；`pid`+`window_id`=单窗口	返回图片文件路径
`get_window_state`	`pid`、`window_id`（都必填）	无障碍树 + 截图；可选 `include_screenshot`（默认 true）、`max_elements`、`query`
`get_accessibility_tree`	—	轻量桌面总览：运行中的应用与可见窗口
`list_windows`	可选 `pid`	列出窗口
`list_apps`	—	运行中与已安装的应用，带状态标记
`cursor_position`	—	当前光标位置
`check_permissions`	—	报告「辅助功能」与「屏幕录制」两项系统权限状态

操作

action	参数	说明
`click`	`element_token`+`pid`（推荐）/ `element_index`+`snapshot_id`+`pid`+`window_id` / `x`,`y`	可选 `button`、`count`、`modifier`
`double_click`	同 click	独立 action，不要给 click 传 `double_click:true`
`type`	`text`、`pid`；`element_token` 定位	逐字符输入
`set_value`	`pid`、`value` + `element_token`	直接设值，比逐字符输入快且不受输入法干扰
`keypress`	`keys`（如 `["cmd","c"]`）、`pid`、`window_id`	见下方「后台按键」
`invoke_menu`	`path`（如 `["File","New Window"]`）、`pid`、`window_id`	走无障碍菜单，不抢焦点、不回落像素
`scroll`	`direction`、`amount`、`pid`、`window_id`	`element_token` 可定位到具体元素
`drag`	`from_x`、`from_y`、`to_x`、`to_y`、`pid`、`window_id`	注意参数名是 `from_`/`to_`
`launch_app`	`bundle_id` 或 `app_name`	后台启动，不抢前台
`bring_to_front`	`pid`（必填）	0.17 不接受 `bundle_id`，先用 `list_apps` 拿 pid
`wait`	`duration_ms`（默认 1000，上限 30000）	等 UI 稳定
`move`	—	已硬禁用，见下

幻影光标：move 被硬禁用

调用 move 会直接拿到这条错误：

Error: 'move' action is disabled — Profy uses phantom cursor mode
(real system cursor is never moved). Use element_index-based click
with pid + window_id instead.

这是设计，不是缺陷。Profy 采用幻影光标模式：

无障碍寻址的 click 通过 AX API 派发事件，压根不碰光标
像素坐标的 click 在驱动层做保存/恢复，点完光标回原位

所以专家操作桌面时你可以继续用电脑，两边互不抢夺光标。

后台按键与它的已知盲区

keypress 默认 delivery_mode="background"，不抢焦点。代价是：原生应用的菜单快捷键（Cmd+N、Cmd+F 等）在后台可能被静默忽略——没有报错，只是什么都没发生。正确的处理顺序：

按完后 get_window_state 验证，发现没变化
用 delivery_mode="foreground" 重试一次（会抢焦点）
或者换 invoke_menu，它走无障碍菜单，既不抢焦点也不会被忽略

菜单类操作直接用 invoke_menu 是更好的默认选择。

自动像素回落

用 token 点击时如果无障碍层拒绝了，工具会自动做一次像素重试：重新取一次快照，按失败 token 里解析出的索引找到元素，点它的框中心。这个回落需要你同时传了 window_id——没传就直接返回原始错误，不做回落。所以即使用 token 定位，也建议把 window_id 一起带上。

失败与对策

报错	含义	怎么办
`snapshot_id_required`	只给了 `element_index`，没给 `snapshot_id`	改用 `element_token`，或把同次快照的 `snapshot_id` 一起带上
`stale_element_token`	token 属于上一次快照	重新 `get_window_state` 再重试，别退回坐标
`'move' action is disabled`	幻影光标模式硬禁用	用 `element_token` 的 click
按了快捷键但界面没反应	后台投递被原生应用忽略	`delivery_mode="foreground"` 重试一次，或改 `invoke_menu`
`bring_to_front` 不生效	传了 `bundle_id`，0.17 只认 `pid`	`list_apps` 拿 pid 再调
插件面板里看不到 Computer Use	没连桌面端	该插件 `requires: desktop_connected`，只在桌面端出现
权限相关的操作全部失败	系统权限没给	先 `check_permissions`，按结果去系统设置里开「辅助功能」和「屏幕录制」

执行链路

agent-runtime → sidecar stdio → Electron 主进程 → Desktop MCPServer
              → driver.ts translateCall → cua-driver (Rust)

screenshot 在 driver 层被翻译成 get_desktop_state（全屏）或 get_window_state（窗口）——cua-driver 里并没有独立的 screenshot 命令。底层驱动是 trycua/cua-driver-rs，版本在桌面端 platform.ts 里锁定为 0.17。本文所有寻址约束都是这个版本的行为。

与 chrome / browser 的分工

维度	`computer`	`chrome`	`browser`
目标	整个桌面	你自己的 Chrome（带登录态）	沙盒内的隔离浏览器（无登录态）
感知	截图 + 无障碍树	DOM snapshot + ref	ARIA snapshot
定位	element_token / 坐标	CSS 选择器 / ref	ARIA selector
前提	桌面端	桌面端或装了扩展的 Chrome	无（云端沙盒即可）
适合	原生应用、游戏、跨应用流程	需要你登录态的网站	公开网页调研

网页任务优先 chrome 或 browser——它们不依赖分辨率，稳定得多。computer 留给没有别的办法的场景。

继续阅读

Chrome

控制你自己的浏览器，带登录态

Browser

沙盒内的隔离浏览器

录制与回放

把一段桌面操作固化成可复用流程

工具全表

每个 action 的完整参数

开始使用

核心概念

使用指南

平台与账户

深入了解

Computer Use

激活条件

元素寻址：优先 token，不要坐标

标准工作流

18 个 action

观察

操作

幻影光标：move 被硬禁用

后台按键与它的已知盲区

自动像素回落

失败与对策

执行链路

与 chrome / browser 的分工

继续阅读

Chrome

Browser

录制与回放

工具全表

​激活条件

​元素寻址：优先 token，不要坐标

​标准工作流

​18 个 action

​观察

​操作

​幻影光标：move 被硬禁用

​后台按键与它的已知盲区

​自动像素回落

​失败与对策

​执行链路

​与 chrome / browser 的分工

​继续阅读

Chrome

Browser

录制与回放

工具全表

激活条件

元素寻址：优先 token，不要坐标

标准工作流

18 个 action

观察

操作

幻影光标：move 被硬禁用

后台按键与它的已知盲区

自动像素回落

失败与对策

执行链路

与 chrome / browser 的分工

继续阅读