agent-desktop 读的是无障碍树,不是截图

每一个靠截图工作的电脑操作智能体,都在跑同一套昂贵的循环。给屏幕拍张照。让视觉模型回答按钮在哪。把答案换算成像素坐标。点击。再拍一张照,看看有没有发生什么。
它确实能用,跟 OCR 能用是一个意思:效果惊人,却从来没有可靠到可以放着不管。各种失败方式都指向同一件事,界面的照片是界面的有损表示。
Vercel Labs 发布的 agent-desktop 走的是另一条路,它目前约有 23,300 颗星,过去一周新增约 5,400 颗。它不看屏幕,而是读取目标应用的无障碍树并输出 JSON,为每个可操作元素附一个引用。智能体对引用执行点击或输入,再读一次界面确认结果,然后重复。

这个循环活在你的智能体里。二进制文件里没有模型。
安装与第一次接触
这个包走 npm 全局安装:
npm install -g agent-desktop
agent-desktop status
`status` 会报告平台、权限和可用的界面范围。把它当第一条命令是合适的,因为电脑操作卡在权限这一步的次数,远多于卡在逻辑上。在 macOS 上,下一条命令是 `agent-desktop permissions --guide`,它会带你走完辅助功能授权。macOS 和 Linux 上也可以用 Homebrew。Bun、Yarn 和 pnpm 装的是同一个包;内置 x64 与 ARM64 的原生二进制。
三条命令的循环长这样:
agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i
`-i` 参数把快照限制在可交互元素上。点击用的是某一次特定快照里的引用。第二次快照不是可有可无的例行公事,你靠它才知道这次点击是否真的产生了你以为的效果。
几个关键的设计决定
在拿它搭任何东西之前,有四个选择值得先弄明白。
引用属于它所在的那次快照。单独写一个 `@e8` 会被拒绝,返回 `INVALID_ARGS`。如果界面在观察与动作之间发生变化,动作会返回 `STALE_REF` 或 `AMBIGUOUS_TARGET`,正确的应对是重新取一次快照,用新快照里的引用。这比多数自动化工具都严格,也消掉了一整类无声的误点。
元素密集的应用有分两步的查看路径。以 Slack 这类应用为例,文档里的做法是先用 `snapshot --skeleton --app Slack -i --compact` 把整体画成地图,再用 `snapshot --root @s8f3k2p9:e3 -i --compact` 钻进某一块。没有这一步,一个复杂应用的完整树对智能体来说是太多 JSON。
默认是无头的。基于引用的动作走无障碍 API,不移动指针,也不抢焦点,所以智能体干活时机器仍然可用。全局的 `--headed` 参数会切到物理输入,应用会检测真实事件时你需要它,其他情况不需要。
机密可以不进进程参数。`type`、`set-value` 和 `clipboard-set` 支持 `--stdin`,从管道读文本。命令行参数在进程列表里是可见的,这决定了一个密码会不会出现在 `ps` 的输出里。README 的建议是把涉及机密的步骤拆成单独命令,因为批量传进去的 JSON 文本会再次出现在参数列表里。
还有一条 PowerShell 脚注,能替某个人省下一小时:每个引用都要加引号,因为单独的 `@token` 是展开运算符。
平台层到底是什么
CLI 之下是一个 C 库,两者之下是同一个核心。每个二进制都为某一个操作系统编译,与该系统的无障碍 API 对话:macOS 上是 AX API,Windows 上是 UI Automation,Linux 上是 AT-SPI。核心只通过一个 `PlatformAdapter` trait 接触操作系统,所以同一份代码能在三套差异很大的无障碍模型之上给出同一种 JSON 信封。
这个架构也解释了它的上限。它只能对无障碍树暴露出来的东西动手。自己把界面画在画布上、什么都不暴露的应用,它会看不见,或者几乎看不见,适配器写得再好也一样。靠截图的智能体能处理这些应用,靠引用的不能。这笔交易是用做得好应用的准确率,换对做得差应用的覆盖。
一个具体的对比
设想一个小任务,截图智能体处理得很糟:在桌面文件管理器里给十二个文件改名。
截图智能体看一眼窗口,认出十二个文件名的位置,产出十二组坐标。它点第一个,选中文字,输入新名字,回车,等列表重新排序。此后每一个坐标都过期了,因为列表顺序变了。它只能每改一次名就重新观察一遍,也就是十二次视觉调用,十二次点错行的机会。
基于引用的做法只观察一次。快照返回窗口的树,每一行带一个引用,另附一个快照 id。每次改名是对某个特定引用的动作,每次动作之后智能体重读这棵树,确认新名字出现了。如果列表重新排序,原快照里的引用会过期,工具会明确说出来,这正是你想要的行为:一个快速、明白的失败,而不是对错误文件的一次无声操作。
可靠性的差别来自结构在哪里被算出来。前一种情况里,模型从像素重建一份文件列表,偶尔会错。后一种情况里,操作系统报告它本来就维护着的文件列表,基本不会错。
那条安全提醒不是套话
README 里有一段警告,值得原样引用而不是转述:快照、剪贴板读取、截图、命令输出和调试产物都可能包含私人桌面内容,应当避免进入公开日志和上传。
这是真实的危险,也是新的危险。靠截图的智能体泄露的是像素。靠树的智能体泄露的是结构化文本,这种文本更容易被索引、被搜索、被误提交。如果你为了调试记录智能体的执行轨迹,你记录的就是当时屏幕上的内容,格式还是 grep 能搜到的那种。
会越来越有用的部分
Vercel Labs 已经交付了两个这样的工具:面向网页的 agent-browser,面向本地应用的 agent-desktop,都用 Rust 写,都在同一周上了趋势榜。它们共享的模式是拒绝让模型去做操作系统已经做过的工作。
这里真正有用的想法就在这一点上,比任何一条具体命令都重要。视觉模型读截图,是在推断一个无障碍树里本来就存在的结构,并为这次推断付出延迟、token 和错误率。读树不花什么钱,返回的东西智能体还能验证。
最终进入生产的智能体,不会是最会看的那些。会是那些不再需要看的。
相关文章
ByteDance 的 SeedRealtime 每秒只取两帧,再自己决定什么时候开口
豆包 Seed-Realtime-1.0 把摄像头画面、屏幕画面和语音合成一个全双工会话,每秒最多推两帧。有意思的决定是帧率、主动说话,以及默认就开着的审核回复。
Cicada 直接听会议的系统音频,会议室里没有机器人
Cicada 是 Mac、Windows、Linux 和 Android 上的免费应用,从系统音频里写出双语字幕和结构化会议笔记。按住一个键,你能用自己克隆出来的声音,把回复用另一种语言说出去。整个过程里没有机器人加入通话。
一台 server、一个 AI 主播:夜间直播背后的代码
open-yoki 是一个每晚在 Binance Square 直播的 AI 主播的生产代码,人格、声音和跟钱有关的功能都拿掉了。headless Chrome 画帧,ffmpeg 推 RTMP,一个 Markdown 文件夹决定她的情绪和要发的东西。
Pinky 让 agent 开你的手机,并且一直按住发送键,直到你点允许
Pinky 把任意 MCP agent 接到真的 iPhone 或 Android 手机上,审批放在自己的网关里执行,不写成 prompt。银行类应用对 agent 不可见,密码框碰不到,Android 13 上 agent 还能拿到一块隐藏的第二屏。