不截图、不猜坐标：Vercel 让 agent 直接读懂桌面 UI

agent 操作电脑这件事，眼下主流方案是截图加坐标：看屏幕、猜按钮位置、点下去、再截图确认。Vercel Labs 的 agent-desktop 走了另一条路：直接从操作系统的无障碍树里读应用的真实 UI 结构，每个可操作的元素拿到一个稳定引用，动作打在引用上而不是像素上。Rust 写的，Apache-2.0 协议，CLI 和 C 库双形态，覆盖 macOS、Windows、Linux。仓库今年 2 月创建，如今 5.6 千星，今天还在提交。它和之前写过的 agent-browser 是同门：浏览器一台戏，桌面一台戏。

一、核心循环：快照、引用、再快照

工作流三步：snapshot 返回 JSON，每个可操作元素带一个引用；agent 对引用执行动作；再次 snapshot 验证结果。全程没有像素匹配，循环逻辑留在你自己的 agent 里。

引用机制的设计很严谨：引用属于它诞生的那次快照，裸引用会被 INVALID_ARGS 拒绝；UI 变化之后旧引用打过去，拿到的是 STALE_REF 或 AMBIGUOUS_TARGET，而不是静默点错地方——重新快照、拿新引用再动手。macOS 上还有个防呆细节：每次快照命名空间复用一个私有命令宿主，保留原生无障碍对象，已删除的行不会悄悄解析到同标识符的存活行；宿主闲置 15 分钟自动退出。多窗口歧义时错误详情里列出候选窗口 id，传 --window-id 即可。

默认无头运行：引用动作走无障碍 API，不移动指针、不抢焦点，你可以在旁边干自己的事；要物理输入得显式加 --headed 旗标。

二、56 条命令与「何时该重试」

命令面按组分：观察类有 snapshot、find、screenshot；引用动作类覆盖 click、type、set-value、toggle、check、expand、scroll 这些高频操作；再加键盘鼠标、应用与窗口管理、通知、剪贴板、等待和会话追踪，总共 60 个命令名、56 条可用——按键按住那四条要等守护进程支持才会放行。

对 agent 最友好的是输出契约：每条命令打印一个 JSON 信封，ok 加 data 或 error；错误自带代码、处置建议，还有一个关键字段 disposition.retry——只有它标为 safe 时才允许重试。这一条把 agent 自动化里最常见的病根「失败了就盲目重试」堵在了协议层。密集应用的策略也给了：先用 --skeleton 拿骨架地图，再对单个区域下钻。

npm 月下载约三千，装法是 npm install -g agent-desktop，二进制和平台助手都打进包里。二进制自带与版本匹配的文档，agent-desktop skills get desktop 和 platform 分别讲循环规则和平台差异；一条 npx skills add 就能把技能装进 agent 框架，或者往 AGENTS.md 里贴一段使用约定。除 CLI 外还发 libagent_desktop_ffi 动态库，程序内用 ctypes 就能调，省去每条命令起一次进程。

三、跨平台现状与隐私提醒

macOS 需要授权辅助功能权限，一条 permissions --guide 引导完成；Windows 在与终端相同的完整性级别下无需额外授权；Linux 走 AT-SPI，X11 和 Wayland 的能力各有细则（Wayland 截图走 portal，剪贴板要装 wl-clipboard）。

隐私一条写得很显眼：快照、剪贴板读取、截图和调试产物可能包含桌面上的私密内容，别放进公开日志或上传；可选的 JEV 助手会把屏幕描述发给配置的模型服务商，它和原生 CLI 是分开的。

和截图派比，无障碍树方案的优势是稳定、可验证、重试安全；代价是依赖应用的辅助功能实现质量，个别自绘 UI 的覆盖会打折。两条路线与其说谁替代谁，不如说互补：读得懂结构就用结构，读不了再退回视觉。Vercel 这套把结构化那条路修到了协议级，值得做桌面 agent 的人认真看。