跳到正文

Vercel 开源 agent-desktop:让编程 Agent 读无障碍树操作桌面应用,不再靠截图猜坐标

Vercel Labs 于 10 月 31 日正式发布开源工具 agent-desktop:通过 macOS、Windows、Linux 的无障碍树把桌面应用变成带 ref 的 JSON,让 Claude Code、Codex、Cursor 等编程 Agent 在后台按 ref 操作并验证。本文梳理它的四步循环、设计要点、适用边界、平台要求和上手方法。

小杜

约 5 分钟读完更新于

Vercel 开源 agent-desktop:让编程 Agent 读无障碍树操作桌面应用,不再靠截图猜坐标

10 月 31 日早上(东京时间 8:48 和 9:15),Vercel Labs 的 Lahfir 和 Chris Tate 先后在 X 上正式发布了 agent-desktop。一句话介绍:它是 agent-browser 的"整台电脑版",让 Claude Code、Codex、Cursor 这类编程 Agent 可以操作 macOS、Windows、Linux 上的桌面应用。和常见的截图 + 猜坐标式 Computer Use 不同,它读的是操作系统的无障碍树(accessibility tree),把每个能点的元素变成一个稳定的 ref,Agent 按 ref 操作,再读一次确认结果。对在做桌面端自动化测试、RPA 或者本地 Agent 的工程师来说,这条路线更省 token,也更可控。

官方演示:多个 Agent 同时在一台 Mac 上操作备忘录、提醒事项和计算器(截图来自 Chris Tate 发布的演示视频)

背景:为什么不靠截图

过去一年,Computer Use 的主流做法是让多模态模型看截图、输出点击坐标。好处是通用,坏处也很明显:每看一次屏幕都要花不少图像 token,坐标一偏就点错,界面一变脚本就碎,而且鼠标被 Agent 占着,人没法同时干活。

agent-desktop 选了另一条路。官方 FAQ 写得很直接:核心流程读的是原生无障碍树,并给可交互元素分配 ref,"点击按钮、输入文字、查看菜单、切换窗口都不需要截图或像素匹配"。截图仍然保留为一个独立命令,需要时再用。

它同时继承了 agent-browser 的思路:工具只负责"看"和"动",不内置任何模型。官方文档强调,它"不是一个 Agent",没有 GUI,也没有交互式提示,每个命令打印一个 JSON 信封然后退出,观察、操作、验证的循环留在调用它的 Agent 里。

要点:快照、ref 和四步循环

按官方文档,标准用法是四步:

  1. 映射:snapshot --skeleton -i --compact 先拿一份浅层骨架;
  2. 下钻:snapshot --root @<快照id>:e1 只展开需要的区域,复杂应用(比如 Slack)不用一次把整棵树塞进上下文;
  3. 操作:click @<快照id>:e11 之类,按 ref 点击、输入、勾选、滚动;
  4. 验证:wait --element ... --predicate value --value 7 再读一次,确认界面真的变了。

agent-desktop 的工作循环与分层结构(整理自官方文档,xiaodu.blog 制图)

几个值得注意的设计:

  • ref 属于某一次快照。裸的 @e8 会被拒绝;界面变了,操作会返回 STALE_REF 或 AMBIGUOUS_TARGET,Agent 必须重新快照。这避免了"按旧编号点到新按钮"这种最难查的 bug。
  • 默认无头(headless)。ref 操作走无障碍 API,不移动鼠标、不抢焦点,所以 Agent 可以在后台跑,你照常用电脑;多个 Agent 也能各自操作。需要真实鼠标键盘输入时才加 --headed。
  • 错误可重试性写在返回里。每个错误都带 code、disposition 和建议,README 要求只有 error.disposition.retry 为 safe 时才重试。
  • 命令规模:README 列出 60 个命令名,其中 56 个可用;key-down、key-up、mouse-down、mouse-up 这四个在有守护进程能可靠释放按键之前会直接拒绝执行。

底层是 Rust 写的:core 定义 PlatformAdapter,三个平台分别对接 macOS 的 AX API、Windows 的 UI Automation、Linux 的 AT-SPI。除了 CLI,每个版本还带一个 C 库 libagent_desktop_ffi,可以在进程内调用,省掉每条命令启动一次 CLI 的开销。

对开发者意味着什么

最直接的用途是桌面应用的端到端测试。Lahfir 的发布帖第一条就是"用 Agent 端到端测试桌面应用"。以前写桌面 UI 自动化,要么维护脆弱的坐标脚本,要么为每个平台学一套框架;现在可以让编程 Agent 读 JSON 树、按 ref 操作、再验证,测试逻辑写成自然语言也能跑。

第二个是给本地 Agent 补上"手"。很多工作流卡在某个没有 API 的桌面软件上,比如内部工具、老系统、设置面板。agent-desktop 能把这些界面变成结构化数据,Agent 处理起来比看截图稳定得多。

不过边界也要说清楚:

  • 只能看到应用暴露的无障碍树。官方文档明确写了,不发布无障碍树的界面它看不到。自绘 UI、游戏、部分 Canvas 应用,大概率还得回到截图方案。
  • 网页不归它管。网页用 agent-browser;对你自己启动的 Chromium/Electron 应用,agent-desktop 会开一个 DevTools 端口,让 agent-browser 接进去处理网页内容。
  • 隐私。README 提醒,快照、剪贴板、截图和调试产物都可能包含桌面上的隐私内容,别放进公开日志或上传。

上手建议

安装很简单:

npm install -g agent-desktop
agent-desktop status                 # 看平台、权限和支持情况
agent-desktop skills get desktop     # Agent 先读这份使用指南

给 Claude Code、Codex 或 Cursor 装 skill:

npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

或者在 AGENTS.md 里加一句,让 Agent 首次使用前先跑 agent-desktop skills get desktop 和 agent-desktop skills get platform。

平台要求(来自官方文档):

  • macOS:13 及以上,Intel 或 Apple Silicon,需要给运行它的终端授予"辅助功能"权限,可以用 agent-desktop permissions --guide 引导;
  • Windows:Windows 10 1809 / Server 2019 及以上,x64 或 ARM64,操作与终端同一权限级别的应用无需额外授权;
  • Linux:Ubuntu 24.04 及以上(glibc 2.35 起),需要在图形会话里运行 AT-SPI 总线。

我的建议是先拿一个"扔了也不心疼"的应用练手,比如计算器或备忘录,把快照、下钻、操作、验证的循环跑通,再接到真正的工作流里。权限上,尽量在单独的用户或虚拟机里跑,别让 Agent 直接接触有敏感数据的应用。

补充一点时间线:GitHub Releases 显示 v1.0.0 早在 10 月 28 日就已发布(这一版加入了 Linux 支持),10 月 31 日凌晨又更新到 v1.0.2,而官方正式对外宣布是在 10 月 31 日早上。截至东京时间 10 月 31 日晚 9 点,仓库已有约 3,200 颗星,许可证是 Apache-2.0。

小杜点评

从算法工程师的角度看,agent-desktop 最有价值的不是"又一个 Computer Use",而是它把问题从"视觉定位"换成了"结构化检索"。截图方案每一步都在让模型做一次带噪声的视觉推理,误差会在长任务里累积;读无障碍树则是把界面变成一个可查询、可验证的状态,模型只需要做决策。这和我们做 Agent 时"能给结构化工具就别让模型猜"的经验完全一致。

它的天花板也很清楚:取决于各个应用的无障碍标注质量。标注好的原生应用会非常好用,标注差的应用就会让 Agent 两眼一抹黑。我比较看好的组合是"无障碍树为主、截图兜底",以及在 CI 里用它跑桌面端回归测试。另外,"每个 Agent 一个光标、后台并行"听起来很爽,但真要放到生产环境,权限隔离和操作审计还得自己补上。

参考来源

评论

正在确认登录状态…