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,也更可控。

背景:为什么不靠截图
过去一年,Computer Use 的主流做法是让多模态模型看截图、输出点击坐标。好处是通用,坏处也很明显:每看一次屏幕都要花不少图像 token,坐标一偏就点错,界面一变脚本就碎,而且鼠标被 Agent 占着,人没法同时干活。
agent-desktop 选了另一条路。官方 FAQ 写得很直接:核心流程读的是原生无障碍树,并给可交互元素分配 ref,"点击按钮、输入文字、查看菜单、切换窗口都不需要截图或像素匹配"。截图仍然保留为一个独立命令,需要时再用。
它同时继承了 agent-browser 的思路:工具只负责"看"和"动",不内置任何模型。官方文档强调,它"不是一个 Agent",没有 GUI,也没有交互式提示,每个命令打印一个 JSON 信封然后退出,观察、操作、验证的循环留在调用它的 Agent 里。
要点:快照、ref 和四步循环
按官方文档,标准用法是四步:
- 映射:
snapshot --skeleton -i --compact先拿一份浅层骨架; - 下钻:
snapshot --root @<快照id>:e1只展开需要的区域,复杂应用(比如 Slack)不用一次把整棵树塞进上下文; - 操作:
click @<快照id>:e11之类,按 ref 点击、输入、勾选、滚动; - 验证:
wait --element ... --predicate value --value 7再读一次,确认界面真的变了。

几个值得注意的设计:
- 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 一个光标、后台并行"听起来很爽,但真要放到生产环境,权限隔离和操作审计还得自己补上。



