桌面 Agent 缺的不是视觉:Vercel 开源 agent-desktop,用无障碍树 ref 替代截图坐标

作者:深蓝AI日期:2026/11/4

11 月 3 日的 GitHub Trending 榜首换成了一个 Rust 项目:vercel-labs/agent-desktop。仓库 11 月 3 日中午还在推代码,累计 11874 星,npm 上的 agent-desktop 包上周下载量 20713。它的自我介绍只有一句话:让 AI agent 通过操作系统无障碍树去读写桌面应用。

截图加视觉模型早就能够点按钮,所以这句话本身不算新鲜。真正值得拆开看的是它把「看」和「点」拆成了两个独立且可验证的步骤,并且把每一步失败的原因写进了 JSON 契约。这决定了它能不能被无人值守的流水线直接调用,而不是只能在演示视频里跑一遍就结束。

桌面上没有 DOM,只有一棵无障碍树

网页 agent 的日子好过,因为有 DOM。一个按钮有 id、有 class、有可读文本,选择器写错会立刻报找不到元素,错误信息直接指到出错的那一行。桌面应用没有这套东西,窗口里的控件活在进程内存里,外部进程拿不到句柄之外的东西。

于是只剩两条路。一条是截图交给视觉模型判断坐标,另一条是读操作系统自己暴露的无障碍树。前者通用,代价是脆;后者覆盖面窄,但每个元素自带语义。agent-desktop 走的是后者,分别对接 macOS 的 Accessibility API、Windows 的 UI Automation 和 Linux 的 AT-SPI。

无障碍树的核心好处是定位依据不是像素。窗口换了主题、DPI 从 100% 调到 150%、系统切成深色模式,树的层级和节点名字不会跟着变,一个 ref 仍然指向同一个按钮。截图方案在这些变化下需要重新校准,校准一旦失效,整条流水线就停在等待坐标超时上,而且日志里只剩一句超时,看不出究竟是界面变了还是模型看错了。

这也是为什么它的文档反复强调 ref 属于某一次快照。快照是一次真实观测的结果,不是一份可以长期缓存的元素地图。UI 变了,旧的 ref 立即失效,工具会明确告诉你失效,而不是猜一个位置点下去。这个差别在长时间运行的批处理里非常关键,因为缓存坐标的做法会在界面更新后的某个清晨静默失败,而缓存 ref 的做法会当场报错。

一条 snapshot 命令换回一张 ref 清单

核心命令是 snapshot,最常用的形态是只列可交互元素。加上 -i 参数后,返回的 JSON 里每个可操作节点都带 role、name、ref_id 和 available_actions 四项。ref_id 形如 @s8f3k2p9:e8,前面的短串是这次快照的编号,后面是节点序号,两者绑定在一起,单写后半段会被拒绝。

信封结构固定为 version、ok、command 三个顶层字段,成功时数据落在 data 里,失败时落在 error 里。当前契约版本是 2.6。一次典型的返回里,data 会给出 app 名、窗口 id、窗口标题、snapshot_id、ref_count 和一个 complete 布尔值。

complete 这个字段在 2.2 版本才出现,意义不小。旧版遇到超大窗口会直接抛 TIMEOUT 且不给任何树,调用方只能靠加大预算硬试。新版改成返回 ok 为 true、complete 为 false、truncated 为 true,附上已经观测到的树和 nodes_observed 计数,被截断的父节点各自带 subtree_truncated 标记,读者可以沿着根一路走到每一处边界。调用方只要读 complete 就能判断手里这棵树是不是完整的,不用再从超时错误里反推。

窗口多的场景不会替你选。同一应用开了多个窗口时,快照返回 AMBIGUOUS_TARGET,候选窗口 id 放在 error.details 里,需要显式传 window-id 指定一个。对密集应用,官方建议先用 skeleton 加 compact 拿到一张骨架图,再用 root 参数从一个节点往下钻。root 下钻是替换已有快照里的 ref,不是新建快照,所以观测不完整时它仍然返回 TIMEOUT,不会给你半棵树。这条区别很容易被忽略,写循环的时候要按不同语义处理:第一次快照不完整可以加大预算重来,下钻不完整只能退回上一层重新选节点。另一种常见浪费是把骨架图当成最终结果直接拿去点,骨架里的节点往往没有 available_actions,点了会被判动作不可用,白白多一轮快照。

动作认 ref,不认坐标

拿到 ref 之后,动作命令的写法很直白:click 接一个 ref,type 接文本,set-value 直接改值。ref 必须带快照前缀,单独写 @e8 会被判 INVALID_ARGS 拒绝,这条规则防的是跨快照误用。

真正需要提前想清楚的是三种失败态。STALE_REF 表示这个 ref 在当前的 RefMap 里找不到,说明页面或窗口已经变了,恢复策略是重新快照再拿新 ref。AMBIGUOUS_TARGET 表示目标不唯一,多窗口场景常见。第三个不是错误而是结果状态:动作交付成功但没有验证,返回值里 delivery 为 delivered_unverified,同时 verification_scope 为 unavailable。文档说得很清楚,这种情况只说明动作发出去了,不证明应用层真的落库,所以不能拿它当成功依据往下跑。

默认是 headless 行为。ref 动作全部走无障碍 API,不移动鼠标指针,也不抢窗口焦点。要物理输入必须显式加 --headed。对后台跑批的任务,这一点比速度重要得多,因为抢焦点会打断用户正在做的事,而无人值守的第一原则就是不打扰。

维度截图加视觉模型无障碍树 ref
定位依据像素坐标与图像特征节点的 role 与 name
分辨率或主题变化需要重新校准结构不变,ref 仍有效
是否抢焦点常需真实指针移动默认不移动指针不抢焦点
失败信息常常只给出坐标超时带错误码与重试建议
覆盖范围任意可见画面只覆盖暴露无障碍语义的控件

表格最后一列那句话是这套方案的天花板。自绘画布、游戏画面、远程桌面里的内容,无障碍树里没有对应节点,ref 无从生成,这条路直接走不通。选型时先问一句:要操作的那个应用,它的控件有没有语义。

信封里的 disposition 决定该不该重试

这套工具最省事的设计是把「能不能重试」做成了机器可读字段,而不是留给人去猜。每个错误都带 disposition 对象,里面两个值:delivery 和 retry。delivery 有五种取值,unknown、not_delivered、delivery_uncertain、delivered_unverified、delivered_verified。retry 有三种,unknown、safe、unsafe。

规则是推导出来的,不是拍出来的。delivery 为 not_delivered 时 retry 一定是 safe,其余非 unknown 的取值一律 unsafe。unknown 意味着这次调用什么也没证明出来,比如一个可能已经落地的操作超时了,这种情况按不安全处理,因为重试可能造成重复提交。

所以正确的调用方代码里只该有一行判断:只有 error.disposition.retry 等于 safe 时才自动重试,其余分支读 error.code 和 message 走人工或换策略。recovery 对象只在 retry 为 safe 时出现,里面给出策略名和是否需要新快照,TIMEOUT 与 APP_UNRESPONSIVE 还会带 retry_after_ms,可以直接拿来做退避间隔。

2.4 版本又补了一层。set-value、type、clear、check、uncheck、toggle、expand、collapse 这些有状态的动作用一次交付后就校验后置条件,发现矛盾直接报错,details.kind 标为 post_action_verification。这一条针对的是最阴的一类事故:动作返回成功,界面看着变了,实际状态没改,于是后续每一步都基于错的前提往下跑,最后失败的位置离真正的根因差了十几个步骤。校验失败时工具不会替你重试,它把矛盾摆出来,因为此时再点一次很可能把错误状态放大。读这个错误时先看 details.kind,再决定是重新快照核对界面真实状态,还是回滚到上一步的业务动作。把这套约定接进流水线之后,重试逻辑就从「失败就重试三次」变成了「按错误码决定重试或停机」,后者的好处是可以事后统计哪类错误最多,而不是只留下一个笼统的失败率。

三个平台的权限账不一样

Windows 最省事,不需要任何授权,前提是目标应用和终端的完整性级别一致。管理员权限运行的应用可以被读取,但只有同样提权的 agent 才能往里输入。这个差异在混合权限环境里会表现为「看得到点不动」,不是权限没给对,而是级别不匹配,排查时要先看两个进程的完整性级别。

macOS 的门槛是辅助功能权限,截图另需屏幕录制,操作通知中心还要给 System Events 自动化权限。permissions 子命令可以只读地报告当前状态,加 request 才会发起请求,加 guide 会直接打开系统设置的对应页面。装完第一件事应该是跑一次 permissions,而不是等动作失败再逐个排查。

Linux 的前提是跑在用户图形会话里,并且装了 at-spi2-core。纯 TTY 或 SSH 会话看不到任何应用,因为没有那个会话的总线、显示和运行时环境。官方给的主目标很明确:Ubuntu 24.04 加 GNOME 46,glibc 地板 2.35。Ubuntu 22.04 的 ATK 桥接在 Action.GetActions 上会直接崩,属于已知不兼容,不是配置能修好的问题。

还有一个容易踩的坑是二进制签名。发布包没有签名,从浏览器下载会触发 SmartScreen 提示,杀毒软件可能直接隔离,全新装的 Windows 11 上 Smart App Control 会拦下来。走 npm 安装不触发这一套,所以 Windows 上优先 npm 而不是手动下载压缩包。如果确实要用压缩包,可以用 gh attestation verify 核对来源,因为发布页的校验和只能证明文件没损坏,证明不了它来自这个仓库。

接进自己的循环:从 CLI 到 FFI

安装和第一轮验证只需要几条命令。注意 npm 12 默认屏蔽安装脚本,被屏蔽时包会退回 Node 启动器,每次调用多出约 125 毫秒,用 install-scripts approve 或 --allow-scripts 放行后才是原生二进制的约 21 毫秒。这个差距在批量任务里会累积成分钟级差别。

1npm install -g agent-desktop
2agent-desktop version
3agent-desktop permissions
4agent-desktop snapshot --app Finder -i
5agent-desktop click @s8f3k2p9:e8
6agent-desktop snapshot --app Finder -i
7

PowerShell 用户要把每个 ref 用引号包住,因为裸写的 @ 开头标记会被当成变量展开运算符,命令会被解析成完全不同的东西。这是官方文档单独拎出来讲的一条,Windows 上第一次跑就撞的概率很高,而且报错信息完全不指向真正的原因。

二进制自带文档是这套工具另一个实用设计:skills get desktop 讲循环、ref、验证和重试规则,skills get platform 讲当前操作系统上的能力差异,skills get ffi 讲语言绑定的入口、内存归属和线程规则。文档跟着二进制版本走,不会出现照着网页上的旧示例写出跑不通的代码,这一点比很多只在 README 里写用法的项目要靠谱。

要在进程内调用而不是每条命令起一次子进程,可以走发布包里带的 libagent_desktop_ffi。以 Python 为例,用 ctypes 加载库,调用 ad_init 并核对返回值,再创建 adapter 句柄:

1import ctypes
2lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
3lib.ad_adapter_create.restype = ctypes.c_void_p
4lib.ad_adapter_destroy.argtypes = [ctypes.c_void_p]
5assert lib.ad_init(7) == 0
6adapter = lib.ad_adapter_create()
7lib.ad_adapter_destroy(adapter)
8

那段 assert 校验的是 ABI 主版本号,头文件里的 AD_ABI_VERSION_MAJOR 必须和库匹配,否则后面所有调用都是未定义行为,可能不报错但结果全错。命令总数是 60 个,其中 56 个可直接用,剩下四个 key-down、key-up、mouse-down、mouse-up 在守护进程能释放被按住的键或按钮之前拒绝运行。这个限制是有意为之,防止一次崩溃把系统留在按键卡死的状态。

它替代不了什么

第一件事是隐私。快照内容、剪贴板读取、截图、命令输出和调试产物都可能带着私人桌面内容,官方文档专门提醒不要把它们放进公开日志或上传。可选的 JEV helper 会把屏幕描述发给你配置的模型服务商,那是独立组件,不是原生 CLI 的一部分,接不接要单独判断,不能因为装了 CLI 就默认同意了这件事。

第二件事是覆盖面。它只处理有语义的控件,自绘界面和游戏画面不在射程内。浏览器里做自动化,Playwright 那种按 DOM 选择器操作的方式仍然更精确,因为 DOM 比无障碍树信息量大得多,能读属性、能拦截请求、能等到具体网络事件。两套东西不是替代关系,是按场景分工。

第三件事是节奏。这套工具把一次操作拆成观察、动作、再观察三步,每次观察都是一次真实快照。对单人手工调试的脚本,这比一次性点完所有按钮要慢;对需要留下可审计轨迹的自动化任务,这三步就是它的价值所在。慢下来的部分正是可以被验证的部分,也是事后能复盘的部分。

放在 2026 年 11 月的这个时间点看,agent-desktop 的意义不在它多快,而在于它把桌面操作从「看得见就点得到」改成了「有语义才点得到,点完能证明」。前面那半句限制了适用范围,后面那半句决定了它能不能进生产流水线。


参考文档


《桌面 Agent 缺的不是视觉:Vercel 开源 agent-desktop,用无障碍树 ref 替代截图坐标》 是转载文章,点击查看原文。


相关推荐


盲盒源码系统小程序V6MAX底层架构解析,PHP+Uniapp高性能商用底座发布
济南壹软网络科技有限公司2026/10/27

盲盒项目在流量爆发期很容易遇到并发卡顿、数据错乱、多端适配不一致等难题,很多市面上的盲盒源码仅仅堆砌玩法功能,忽略底层架构的稳定性,平台上线后频繁出现故障,直接造成用户流失。盲盒源码系统小程序V6MAX作为成熟的盲盒开源源码方案,依托Uniapp前端搭配PHP后端的稳定架构,完善底层引擎设计,同时支持APP盲盒源码打包与盲盒定制开发,为长期稳定运营筑牢根基,经营的潮玩平台。 一、前后端分离模块化架构,业务模块解耦便于迭代扩展 整套系统采用标准前后端分离设计,前端页面、交互逻辑、后端业务计算、


将手机变成 ToDesk 的“安全钥匙”:主设备设置与远程解锁指南
JoyCong19982026/10/19

Hello大家,在使用各类远程控制应用时,很多人虽然给连接设备额外设置了复杂密码,但可能仍忽略了一个关键问题:一旦连接信息透露过,那后续有人发起远程连接,自己是否真的能第一时间知道呐?         对此,ToDesk特设有二次验证保护这项至关重要的安全功能,它意味着,启用后所有与目标设备的连接都需要经过【主设备】的同意才可建立。它就是为这份“知情权”而准备,是多加的一把安全钥匙,将常用的手机\平板移动设备按步骤设置后,每一次连接、登录等信息会被及时推送到其中。它并不是代替账号密码,只是在关


RAG、记忆、上下文,这几个东西到底怎么串起来?
杨杨杨大侠2026/10/17

聊到 RAG 的时候,我先问了一句: 查资料,给模型提供依据? 这句话我能听懂。接着又聊到知识库、向量数据库、工具调用、长期记忆,我就有点绕了。 查个资料,要这么多东西吗?它们的能力是不是有些重复?模型到底是自己去查,还是程序查好了直接传给它? 后来还是拿一次完整的对话来看,才容易理解:用户说了一句话,程序做了什么,模型收到了什么,然后又发生了什么。 1. 先说 RAG,它就是怎么查资料、怎么用资料 假设你在公司做一个 AI 助手。公司有自己的产品手册、操作文档,还有一些内部规定。 这些资料


PHP Monolog 日志实战详解:级别、Handler、Processor 与 Symfony 配置
唐青枫2026/10/9

PHP Monolog 日志实战详解:级别、Handler、Processor 与 Symfony 配置 程序运行出错时,日志往往是还原现场最直接的线索。只用 echo 或 var_dump() 排查,开发时勉强够用,到了线上就很难按级别筛选、按请求追踪,也不适合把告警发到不同地方。 Monolog 是 PHP 生态里常用的日志库,实现了 PSR-3 日志接口。它能把日志写入文件、PHP 错误日志、Syslog 或其他服务,也能给日志补充请求 ID、用户 ID、内存用量等上下文。 这篇文章从一段


PHP 8.3 写 C 扩展踩坑实录:从 phpize 到 zval,一篇跑通
游鹄君2026/9/30

php扩展开发-使用 C 语言编写高性能 PHP 扩展的底层编译与调用(zval 与内存管理) 以字符串加解密为例 前提 ^ 是什么?——异或(XOR) C 里的 ^ 不是乘方,是按位异或:两个二进制位不同则 1,相同则 0 1 ^ 1 = 0 1 ^ 0 = 1 0 ^ 1 = 1 0 ^ 0 = 0 对一个字节操作时,就是 8 个 bit 逐位做这个运算。比如字符 ‘A’ 和 ‘k’: 'A' = 0x41 = 0 1 0 0 0 0 0 1 'k' = 0x6B = 0


600 元小主机怎么玩 macOS?从 U 盘、BIOS 到 UHD 630 加速和公网远程一次跑通
晨陌y2026/9/24

600 元小主机怎么玩 macOS?从 U 盘、BIOS 到 UHD 630 加速和公网远程一次跑通 前言 我一直觉得二手商用迷你主机最有意思的地方,不是“花几百块假装买到 Mac mini”,而是它给了我一块成本不高、出问题也敢继续折腾的实验平台。真正的 Mac mini 在稳定性、系统支持和整体体验上更省心,这台 HP ProDesk 600 G4 Desktop Mini 没必要去硬碰硬比较;但如果目的只是体验 macOS、录教程、做轻量桌面环境,或者顺手跑一些本地服务,那么 600


给若依加审批流,不用 Flowable
mldong2026/9/16

引言 若依是国内最流行的快速开发框架之一,GitHub 镜像 4 万多 star,几乎每个 Java 后台项目都从它起步。但它有个大家都知道的"缺口":官方免费版不内置审批流。 用若依的人,迟早要碰审批——请假、报销、合同、采购。怎么补? 这篇文章给一个不绕弯子的答案:别上 Flowable,用 jeeflow。后端一个依赖一个薄壳,前端一个宿主组件九个薄页,配一条菜单 SQL,半天跑通一个带工作台、发起、待办、审批、流程设计器的完整流程中心。 我把整个过程真机走了一遍(若依 3.9.2 mas


Elasticsearch 中的查询重写规则:通配符扫描速度提升 2.3 倍
Elasticsearch2026/9/8

作者:来自 Elastic Parker Timmins, Martijn Van Groningen 第二条规则使空字符串过滤器的速度提升了 1.6 倍。它直接从偏移数组中读取字符串长度,完全不会访问压缩后的字节。这两条规则都源于同一种习惯:运行真实查询,并寻找特殊情况。 想获得 Elastic 认证?了解下一期 Elasticsearch 工程师培训何时开课!你现在可以开始免费云试用,或者立即在你的本地机器上试用 Elastic。 Lucene 查询重写规则让 Elasticsearch


六语言引擎实现对比:同构背后的妥协与差异
mldong2026/8/31

系列定位:jeeflow 系列第 11 篇(第三季「多语言联邦」第 3 篇 · 季终) 平台:掘金(深度对比)/ 公众号(故事线) 素材版本:引擎 Java 1.8.19 / Go·Python·Node 1.8.21 / PHP 1.3.6 / Rust 1.0.6(2026-08-30 六语言同日发版) 一、先看今天发生的一件事 写这篇的时候(2026-08-30),jeeflow 刚完成一次六语言同步发版:


Linux + Docker + FastAPI 工程化实践指南
卷无止境2026/8/23

一套稳健的 FastAPI 工程,不是把 API、Redis 和 PostgreSQL 塞进同一个 Compose 文件就算完事。更合理的做法是把应用设计成无状态服务,数据库迁移、配置管理、健康检查和测试各自承担清晰职责;开发环境追求反馈速度,生产环境则强调镜像可复现、最小权限和可观测性。 下面给出一套可以直接落地的项目骨架。 一、推荐架构 开发环境可以使用 Docker Compose 编排所有依赖,代码通过挂载目录实现热更新。生产环境仍然使用相同镜像,但不再挂载源代码,也不启用 --relo

首页编辑器站点地图

本站内容在 CC BY-SA 4.0 协议下发布

Copyright © 2026 聚合阅读