agent-desktop 拆解:不靠截图,agent 怎么操作桌面应用
vercel-labs/agent-desktop 是一个 Rust 写的 CLI 和 C 库。8257 stars、581 forks、Apache-2.0,2026 年 2 月 19 日建仓,10 月 30 日发布 1.0.2。它干的事一句话说完:让 agent 通过操作系统的无障碍树观察并操作桌面应用,用带快照前缀的 ref 代替鼠标坐标。
这篇文章不讨论"computer use 是不是未来",只拆它怎么把"点一个按钮"拆成可校验、可重试、失败能解释的工程流程。看得懂这套流程,你就能判断它在什么场景下比截图方案强,在什么场景下根本用不了。
如果你正在给 agent 接桌面能力,或者被截图方案的坐标漂移折磨过,这篇可以直接当设计参考。
本文提纲
- 它是什么:一个工具,不是一个 agent
- 为什么是树不是像素:截图路线的三个死结
- 怎么用:装完之后的第一个循环
- 总体架构:core 不认平台,平台在编译期被选中
- 核心机制一:ref 是证据,不是句柄
- 核心机制二:动作之前的七项预检
- 核心机制三:delivery 与"能不能重试"
- 快照预算:超时之后返回半棵树,而不是报错
- 三平台适配:同一控件在三个系统里不叫同一个名字
- 给 agent 的接口:错误里带恢复策略
- 四个真正的创新点
- 横向比较
- 成本、边界与风险
- 参考文档与链接
它是什么:一个工具,不是一个 agent
仓库自己的 AGENTS.md 第一段就把定位钉死了:
agent-desktop is a tool that AI agents invoke, not an agent. It is a Rust CLI and C library that reads native accessibility trees and returns structured JSON with ref-based element ids. The observe-act loop lives in the calling agent. It never embeds an LLM and has no GUI or interactive prompt.
拆开是四条边界:
- 不内嵌模型。它不发 prompt,不做意图理解,不判断"下一步该点哪"。
- 没有 GUI,也没有交互式提示。所有输入来自命令行参数或 JSON,所有输出是一个 JSON envelope。
- 不自动化网页。README 直接写"use agent-browser",网页交给同实验室的另一个项目。
- 看不到没有无障碍树的 UI。Canvas 画布、游戏、自绘控件,它没有观察手段。
最后一条是硬边界,也是理解整个项目的起点:它的能力上限由操作系统暴露的无障碍 API 决定,不由它自己决定。
装完之后有 60 个命令名,其中 56 个可用。剩下四个 key-down、key-up、mouse-down、mouse-up 会拒绝执行,理由是"until a daemon can release a held key or button"。按下和抬起必须成对,没有守护进程兜底释放,按下就是一个能把用户键盘卡住的 bug,所以宁可先不开放。这个细节很能说明项目的取舍:宁可功能缺失,也不提供一个会留下脏状态的接口。
热度和实际使用有个明显的落差。8257 stars,但 npm 上 agent-desktop 最近一个月下载量是 2941 次(统计窗口 2026-09-30 到 10-29)。star 是"这个思路值得看",下载量才是"真的有人接进流程"。两个数字差三倍,说明它目前更像一个被广泛阅读的架构样本,而不是被广泛部署的生产工具。
为什么是树不是像素:截图路线的三个死结
截图加视觉模型的路线很直观:截一张图,让模型看图,输出坐标,点下去。它对所有应用一视同仁,不需要应用配合。但它有三个工程死结,而且都不是"模型再强一点"能解决的。
第一,坐标会漂。 窗口移动、DPI 变化、列表滚动、字体渲染差异、系统主题切换,任何一个都能让昨天算出来的 (412, 286) 落到别的控件上。截图的坐标系是像素,而像素不是身份。
第二,像素里没有身份。 一个对话框里有三个"确定"按钮,截图里它们是三块相似的矩形。模型只能靠位置描述"最下面那个"。如果布局变了,描述就失效了。更麻烦的是,你无法在事后证明"我点的确实是那个按钮",只能证明"我点了这个坐标"。
第三,重试无法判定。 点击之后界面没反应,可能是没点中,可能是点中了但应用在加载,也可能是点中了但操作被静默拒绝。截图方案没有稳定的读回手段,只能再截一张图让模型"看看有没有变化"。这个判断既贵又不确定,而 agent 恰恰最需要知道"这一步到底成没成"。
无障碍树换了一个信息源。它给的不是像素,是结构化节点:角色(button、textfield、checkbox)、名称、值、状态(enabled、checked、focused)、可用动作。这些东西本来就是操作系统为辅助技术准备的,天然带语义。
但树也有自己的坑,而且坑更深:树是活的,快照之后随时会变;原生句柄会被系统回收再分配;三个平台的控件分类并不平行。项目的方法论文档 CONCEPTS.md 里反复出现一句话的变体:a ref from an earlier observation is evidence, not a native handle。整篇文章后面要讲的机制,基本都是这句话的展开。
怎么用:装完之后的第一个循环
安装只有一条命令:
npm install -g agent-desktop
agent-desktop versionnpm 包里带 x64 和 ARM64 的原生二进制与平台辅助程序。macOS 需要授予辅助功能权限,agent-desktop permissions --guide 会引导;Windows 对与终端同完整性级别的应用不需要额外授权;Linux 需要图形会话和 at-spi2-core。
第一个循环就三步,官方 README 用 Finder 举例:
agent-desktop snapshot --app Finder -i # 每个可交互元素带一个 ref
agent-desktop click @s8f3k2p9:e8 # 用这个 ref 执行动作
agent-desktop snapshot --app Finder -i # 再观察一次,确认结果snapshot 的输出长这样(截断版):
{
"version": "2.5",
"ok": true,
"command": "snapshot",
"data": {
"app": "Finder",
"window": { "id": "w-204749", "title": "Downloads" },
"snapshot_id": "s8f3k2p9",
"ref_count": 59,
"complete": true,
"tree": {
"role": "window",
"name": "Downloads",
"children": [
{ "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }
]
}
}
}三条使用纪律必须记住,它们不是风格建议,是错误码的来源:
- ref 属于它出生的那个快照。 裸
@e8会直接返回INVALID_ARGS。界面一变,动作就返回STALE_REF或AMBIGUOUS_TARGET,必须重新快照换新 ref。 - 多窗口会歧义。 同一个应用开着两个窗口时,动作返回
AMBIGUOUS_TARGET,error.details里列出候选窗口 id,用--window-id指定。 - 密集应用先画地图再钻取。 先用
snapshot --skeleton --app Slack -i --compact拿浅层结构,再用snapshot --root @s8f3k2p9:e3 -i --compact钻进一个区域。一次拉全树对 agent 的上下文是灾难。
还有一个默认值值得单独说:ref 动作默认 headless。它走无障碍 API,不移动指针、不抢焦点、不合成键盘事件。要物理输入必须显式加全局 --headed。所以双击、三击、hover、drag 这些物理专属动作,在没有 --headed 时是直接失败关闭的,不会"尽力模拟一下"。
最后一个容易踩的坑在 Windows:PowerShell 里必须给每个 ref 加引号,写成 '@s8f3k2p9:e8',因为裸 @token 在 PowerShell 里是 splatting 操作符。这不是 agent-desktop 的设计问题,但足以让人排查半小时。
总体架构:core 不认平台,平台在编译期被选中
Cargo workspace 有六个成员:crates/core、crates/macos、crates/windows、crates/linux、crates/ffi,加上二进制入口 src。
flowchart TB
A["Agent loop
observe, act, verify"] -->|"one JSON envelope per call"| B["agent-desktop CLI (Rust)"]
B --> C["dispatch / command policy / batch"]
C --> D["agent-desktop-core
PlatformAdapter trait"]
D --> E1["macOS adapter
AX API"]
D --> E2["Windows adapter
UI Automation"]
D --> E3["Linux adapter
AT-SPI"]
B --> F["agent-desktop-ffi
C ABI cdylib"]
F --> D
D --> G["state root ~/.agent-desktop
sessions, refmaps, traces"]
D --> H["snapshot JSON
tree plus qualified refs"]
classDef red fill:#FF6B6B,color:#000000
classDef teal fill:#4ECDC4,color:#000000
classDef blue fill:#45B7D1,color:#000000
classDef sage fill:#96CEB4,color:#000000
classDef yellow fill:#FFEAA7,color:#000000
classDef plum fill:#DDA0DD,color:#000000
classDef mint fill:#98D8C8,color:#000000
class A,B red
class C,D teal
class E1,E2,E3 blue
class F,G sage
class H yellow
linkStyle default stroke:#764ba2依赖方向是单向的,而且 CI 会强制:
- core 定义
PlatformAdaptertrait 和全部共享类型,平台 crate 实现它。 - core 永不 import 平台 crate,平台 crate 之间也永不互相 import。 CI 跑
cargo tree -p agent-desktop-core,只要输出里出现平台 crate 就失败。 - 只有两个东西把平台接到 core 上:二进制
src/和 FFI crate。 - 平台在编译期选:
build_adapter()里用#[cfg(target_os)],依赖在src/Cargo.toml里按 target 声明。不是在运行时判断后cfg掉一段代码。
这套结构带来一个很实际的好处:core 可以在任何 OS 上交叉编译和跑测试,因为它的依赖里没有 Win32、没有 AppKit、没有 AT-SPI。代价是平台差异必须被抽象成 core 能理解的词,这个抽象做得好不好,直接决定了三个平台的行为能不能对齐。
项目用几条很硬的规则维持这个结构:
- 单个手写
.rs文件不超过 400 行,由scripts/check-rust-file-size.sh在 pre-commit 和 CI 里检查。 - 架构脚本会先植入违规样本再扫描。
scripts/check-architecture.sh在扫描前故意制造每一条规则的违反项,如果某条规则没检测出来,脚本自己就失败。这解决了一个常见问题:规则写了三年,重构之后早就失效了,但没人知道。 - release profile 是
opt-level = "z"、LTO、panic = "abort"、strip,但 core 和平台 crate 单独降到opt-level = 3,FFI 用继承 release 的release-ffiprofile 把 panic 改回 unwind(C ABI 不允许 unwind 穿边界)。 - CLI release 二进制超过 15 MB 直接让 CI 失败。
这些数字放在一起看,能看出一个清晰的取向:这不是一个"先把功能堆上去"的实验项目,它从第一天就在为分发和长期维护付成本。
核心机制一:ref 是证据,不是句柄
这是整个项目最值得读的部分。
snapshot 返回的 @s8f3k2p9:e8 不是指针,也不是控件 id。它是一个带注解的观察记录:这个元素在这一次观察里,处在什么位置、叫什么名字、是什么角色、属于哪个进程、有哪些稳定特征。这些信息被写进 RefMap 持久化,动作执行时再拿出来,去活的界面里重新找一个匹配项。
这一步叫 strict ref resolution,规则非常简单粗暴:
- 零个匹配,返回
STALE_REF。 - 两个或更多匹配,返回
AMBIGUOUS_TARGET。 - 绝不"猜一个最像的"。
重新识别的顺序是分级的(graded resolution):
- 先走存储的位置路径;
- 路径不行,退到有界宽搜;
- 候选先用原生 id 确认,再用角色相关的稳定文本确认;
- 只有完全没有有效身份的 ref,才允许用唯一几何位置兜底。
第 3 条里"角色相关"和"稳定"两个限定词都很关键。输入框里的当前文本是易变的,不能当身份;但一个按钮的标签是稳定的,可以。这条策略由 core 统一持有,macOS、Windows、Linux、CLI、FFI 共享同一套语义,避免每个适配器自己发明一套"像不像"的判断。
第 4 条的几何兜底被刻意做得很窄:只有 ref 没有任何有效身份、并且存了 bounds 时才启用,而且必须唯一命中。Windows 和 Linux 还额外要求存储的 bounds 面积为正,因为离屏和虚拟化元素会塌缩成共享的退化矩形,这种矩形在结构上就不可能唯一。项目文档里给这个 case 编了号(A17-7),说明它是被真实 bug 逼出来的补丁,不是设计时的假设。
窗口身份还有一层更细的保护。操作系统会回收窗口句柄:一个窗口销毁后,同一个句柄可能被分配给新窗口。只拿句柄当身份,就会在窗口反复创建销毁之后把动作打到错误的窗口上。所以窗口身份是句柄加进程代际令牌:
- Windows:HWND 加进程创建时间;
- macOS:窗口号加进程启动时间;
- Linux:X11 client id 加带 boot-id 的进程启动时间。
回收的句柄如果进程代际对不上,就 fails closed,而不是解析到新占用者。文档还补了一句很工程的话:句柄的有效性可能在观察和动作之间任何时刻失效,只在开始时检查一次,只能证明"当时有效"。所以检查必须在每次写入前重复,动作的成功判定本身也要带身份限定,否则一个晚发生的回收会让"成功"落在错误的资源上。
flowchart LR
S["snapshot
allocate @snap:eN"] --> R["strict resolve
re-identify live element"]
R -->|zero match| E1["STALE_REF"]
R -->|two or more| E2["AMBIGUOUS_TARGET"]
R --> P["preflight
visible, stable, enabled"]
P -->|blocked| E3["POLICY_DENIED or TIMEOUT"]
P --> D["dispatch
semantic or physical"]
D --> V["verify
delivery disposition"]
V -->|stale| S
classDef red fill:#FF6B6B,color:#000000
classDef teal fill:#4ECDC4,color:#000000
classDef blue fill:#45B7D1,color:#000000
classDef sage fill:#96CEB4,color:#000000
classDef yellow fill:#FFEAA7,color:#000000
classDef plum fill:#DDA0DD,color:#000000
class S,R,P,D,V teal
class E1,E2,E3 red
class V yellow
linkStyle default stroke:#764ba2核心机制二:动作之前的七项预检
解析到元素之后,不能立刻点。core 会先跑一组 actionability 检查,项目里叫 actionability battery:
- 可见(visible)
- 稳定(stable,位置不再变化)
- 可用(enabled)
- 支持这个动作(supported action)
- 策略允许(policy)
- 可编辑(editable,写操作才需要)
- 能收到事件(receiving events)
这七项被分成两类,处理方式完全不同:
- 瞬时检查(可见、稳定、可用、遮挡)会被轮询,给元素一个自我恢复的机会。
- 终态检查(支持动作、策略、可编辑)直接快速失败,不浪费时间等一个不会变的条件。
轮询的默认预算是 5000ms,type 会按文本长度每字符加 30ms。--timeout-ms 0 可以关掉等待,回到"立即执行一次"的旧行为。
"能收到事件"这一项有个很容易做错的细节。battery 的检查是从元素 bounds 取五个候选点(中心加四个象限),任意一个能到达目标就算通过。但指针管线在真正派发时只检查一个点,也就是光标将要移动到的那个坐标。这两个问题的形状不一样:前者问"这个元素是否可达",后者问"这个具体坐标会不会被挡住"。一个部分被遮挡的控件可以通过 battery,然后在单点检查上失败。文档明确说这两种 hit-test 不能混为一谈。
遮挡判断本身是三态的:ReachesTarget、InterceptedBy { role, name, bounds }、Unknown。
Unknown时 fail open,让动作继续。理由是"没有证据不能变成假失败",真正的裁判是派发结果。InterceptedBy需要正面证据:要么平台 hit-test 在约定的窗口归因下给出结论,要么命中属于另一个窗口时有两个意见一致。证据不足时不能凭空发明一个遮挡者。
这套设计里有一句我很喜欢的判断:预检不是为了让动作更可能成功,而是为了让失败更可解释。预检失败必须说清楚是哪一项没过,并且保留重试安全性。这直接引出下一节的 delivery。
核心机制三:delivery 与"能不能重试"
大多数自动化工具的动作返回是一个布尔值。agent-desktop 返回的是一个 disposition 对象:
{
"action": "drag",
"disposition": { "delivery": "delivered_unverified", "retry": "unsafe" },
"steps": [ { "label": "pointer_drag", "outcome": "succeeded", "mechanism": "physical_synthetic" } ],
"target": { "kind": "drag", "from": { "x": 10, "y": 20 }, "to": { "x": 80, "y": 20 } }
}delivery 有五种取值:unknown、not_delivered、delivery_uncertain、delivered_unverified、delivered_verified。retry 由 delivery 推导,规则只有一条:只有 not_delivered 是 safe,其余全部 unsafe。
为什么这么严?因为重复点击可能提交两次,重复输入可能打出两行字,重复 toggle 会把自己撤销掉。agent 最危险的行为不是"不会做",而是"以为没做,又做了一遍"。
JSON 契约的 2.5 版做了一次很值得说的破坏性清理:删掉了 clicked、moved、scrolled、hovered、dragged、resized、minimized、maximized、restored、closed、cleared 这些恒真的成功标志,而且不留兼容别名。改动说明写得非常直白:
A flag that every successful call carried proved nothing about the operation.
一个每次成功都为 true 的字段,不携带任何信息,但它会让调用方以为自己在验证。删掉它,逼调用方去读 disposition 和 verification_scope。
这套语义不是拍脑袋定的,Linux 适配器的实测记录给出了最硬的证据。docs/solutions/runtime-errors/ 里有一篇标题就叫《An AT-SPI write that returns success has not changed anything》,在 GTK3、GTK4、Qt 6、Firefox、Chromium 上实测出的结论是:
- 成功但没效果:一个已销毁的 GTK3 控件对
DoAction、SetTextContents、InsertText、Properties.Set都返回成功,而GetState是两个零字;Gecko 对几乎所有 input 的SetTextContents和InsertText都返回true,但什么都没改;GTK3 和 Qt 的只读字段会静默接受写入,Qt 在这条路径上根本不检查READ_ONLY。 - 失败但效果落地:一个被停止的应用对所有写入返回
NoReply,调用方超时;进程收到SIGCONT之后,总线把排队的调用投递下去,每一条写入都生效了。 - 错误名不能说明对象是否还在:
UnknownMethod、UnknownObject、UnknownInterface在不同 toolkit 下含义重叠,必须再读一次GetRole来确认对象是活着还是没了。
于是写入路径被改成:先拒绝已知不可写的节点(READ_ONLY 置位或 EDITABLE 未置位),读一次旧值,写,再读一次新值。
- 新值等于请求值:
Matched,结果带verified。 - 新值等于旧值:
write_ignored,返回ACTION_FAILED,details.cause = "write_ignored",delivery是not_delivered。 - 读不到或值不对:
delivered_unverified。 - 密码字段不做回读,因此永远拿不到
verified,并且写入的文本会在错误信息里被替换成[withheld]。
最反直觉的一条是密码字段的识别。GTK 的 secure text 靠原始角色号 40 识别,因为这个角色报出来的名字是 text box,不是 password。而 GTK4 的密码输入框角色号是 61,既没有 secure 标记也没有可见性关闭的信号,GetText 会直接返回明文。所以文档明确写:GTK4 角色 61 的字段回读结果不能拷进 envelope。
这段代码只有在 Linux 桌面真跑过几十个应用才写得出来。它也是"为什么这个项目值得读"的最好答案:它不是把三个平台的 API 包一层,而是把三个平台说谎的方式一条条测出来,再写进契约。
快照预算:超时之后返回半棵树,而不是报错
无障碍树可以非常大。一个 Slack 窗口的节点数轻松过千,Electron 应用还会在中间塞进成串的匿名容器。
早期版本在快照超预算时返回 TIMEOUT 错误,什么树都不给。2.2 版把契约改了:超预算时返回 ok: true、complete: false,带上已经观察到的树、truncated: true、nodes_observed,以及每个被截断节点的 subtree_truncated: true。调用方可以从根一路走到每个边界,知道哪里被砍了。
为什么这个改动重要?因为 agent 处理一个完整但巨大的树,和处理一个明确标注"这部分没看完"的树,是完全不同的两种任务。前者要自己猜预算,后者可以只针对缺失区域重新观察。文档说得很清楚:消费者必须读 data.complete 来判断树是否完整,TIMEOUT 不再表示树太大。
但 --root 钻取不允许部分观测。原因是钻取会替换已有快照里的 ref,如果新观察不完整,替换就会摧毁它无法重新分配的子树。所以钻取超预算仍然返回 TIMEOUT,而不是半棵树加一个坑。
还有一个很聪明的优化:跳过 web wrapper 的逻辑深度。Chromium/Electron/WebView 会在内容外面套一串匿名容器(UIA 的 Group、Custom、Pane,AX 的 group,AT-SPI 的 panel、section、filler)。这些容器没有名字、没有值、没有开发者 id,唯一的动作是滚动到可见。它们消耗原始深度,但不消耗逻辑深度。跳过之后,同一个密集 web 应用在默认深度预算下能看到的可及内容,差距是一个数量级。
Windows 上的这个跳过是有门控的:只在检测到 Chromium 来源(根窗口类名 Chrome_WidgetWin_1)时启用。因为同样的"空容器"判定如果无差别套用,会把原生控件栈里大量合法的匿名容器一起跳过。macOS 和 Linux 则对所有应用套用同一个空判定。
这就是"三平台适配"的真实成本:同一个优化,在一个平台上需要额外的来源检测才安全,在另外两个平台上不需要。
三平台适配:同一控件在三个系统里不叫同一个名字
项目在 core 里定义了一套封闭的词汇表,适配器只能往里映射,不能发明新词。三个来源分别是 macOS 的 AXRole 加 subrole、Windows UIA 的 ControlType 加可用 pattern、Linux AT-SPI 的角色号。
问题在于,三套分类不是平行的。文档举了两个很具体的例子。
例一:Tab。 UIA 的 Tab 是容器,TabItem 才是页签选择器。这跟 ARIA 的命名正好相反。如果按名字直译,Windows 上的标签页会整体错位。
例二:toggle button。 同一个逻辑控件,三个平台给出三种合法的映射结果:
- macOS:
role: button加state: pressed,因为 macOS 保持控件角色为 button,把开关值读成 pressed。 - Windows:任何声明支持 toggle 的
Button都会在状态解析前被重分类为role: switch加state: checked。 - Linux:toggle button 报
checked,pressed只留给 push button。
文档对这件事的评论很克制:这不是三个适配器里谁的 bug,而是"两个正确的角色映射在这里相遇"的结果。但它对 agent 的影响是真实的:同一段操作逻辑,在三个平台上要判断的字段不一样。
Windows 仍然会产出 pressed,但只在一个 button 的 LegacyIAccessibleState 带 pressed 位时(比如一个不支持 toggle 的工具栏开关)。这种例外必须写进文档,否则调用方永远猜不到。
平台能力也不是齐平的。Linux 支持是 1.0.0 才正式发布的,要求 glibc 2.35 以上,走 AT-SPI;X11 和 Wayland 的能力又不一样(鼠标输入基本是 X11 专属,Wayland 下截图要走 portal 或 wl-clipboard)。macOS 和 Windows 的能力覆盖最全,Linux 的窗口控制、鼠标输入和系统托盘则受 X11 与 Wayland 的分裂限制,README 里有多处标注为仅 X11 或仅 GNOME。
还有一个安全细节值得单独提:close-app 有一个受保护进程列表,防止 agent 把用户桌面会话关掉。匹配是精确匹配(macOS 匹配进程名或 bundle id 的某个点分段,Windows 匹配完整镜像名),不是子串匹配,所以名字里恰好包含受保护词的应用仍然可以关。拒绝时的错误码是 INVALID_ARGS 加 disposition.delivery: "not_delivered",不是 PERM_DENIED。理由很准确:这个进程不是"你没权限关",它根本不是一个可关闭的目标。
给 agent 的接口:错误里带恢复策略
agent-desktop 的每个命令输出一个 JSON envelope,成功是 ok: true 加 data,失败是 ok: false 加 error。错误对象里除了 code 和 message,还有三样东西:
suggestion:给人看的下一步建议;recovery.strategy:给程序看的恢复策略,只在disposition.retry是safe时出现;details:结构化上下文,比如候选窗口 id、请求值和实际值。
一个典型的 STALE_REF:
{
"ok": false,
"error": {
"code": "STALE_REF",
"message": "@s8f3k2p9:e7 not found in current RefMap",
"suggestion": "Re-run a snapshot to obtain fresh refs, then retry with the new ref",
"recovery": {
"strategy": "refresh_snapshot_then_retry_original",
"retryable": true,
"requires_fresh_snapshot": true
},
"disposition": { "delivery": "not_delivered", "retry": "safe" }
}
}这个设计解决的是 agent 场景里一个很具体的问题:模型读一段自然语言错误,经常理解偏。把恢复策略做成枚举字段,调用方就可以写确定性代码,不用让模型去猜"这个错能不能重试"。
第二个接口设计是技能文档编译进二进制。agent-desktop skills get desktop 打印的是 skills/agent-desktop/SKILL.md 的内容,skills get platform 打印当前 OS 的差异表,skills get ffi 打印 C ABI 的入口、内存所有权和线程规则。文档跟二进制同版本发布,不会出现"网上教程是 0.11,装的是 1.0.2"的漂移。
仓库里还有 src/cli/doc_literal_drift_tests.rs,专门检查 README 和 AGENTS.md 里的命令数量有没有跟代码对上。改命令数量忘了改文档,测试会挂。
第三个是 batch。它不是一个第二套调度器,而是把 JSON 数组反序列化成同一个 Commands 枚举,跑同一套 CommandPolicy 预检,再调用同一个 dispatch()。这个约束写在 AGENTS.md 里,目的是防止批处理和单条命令的行为分叉。
第四个是 FFI。每次发布都会带 libagent_desktop_ffi(macOS 的 .dylib、Linux 的 .so、Windows 的 .dll),Python、Swift、Go、Ruby、Node、C 都可以在进程内调用,不用每条命令 fork 一次。README 的例子是:
import ctypes
lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
lib.ad_adapter_create.restype = ctypes.c_void_p
lib.ad_adapter_destroy.argtypes = [ctypes.c_void_p]
assert lib.ad_init(6) == 0 # header 的 AD_ABI_VERSION_MAJOR 要匹配
adapter = lib.ad_adapter_create()
lib.ad_adapter_destroy(adapter)ad_init(6) 里的 6 是 ABI 大版本。C ABI 的结构体布局被 pin 住,有专门的 c_abi_layout 测试;release-ffi profile 把 panic 从 abort 改成 unwind,避免 Rust panic 穿到 C 栈上。这些都是绑定库容易被忽略、但一升级就炸的地方。
四个真正的创新点
这个项目功能很多,但机制层面的新东西只有四个。其余都是工程实现。
一、三态证据,永不塌缩成布尔。 适配器读到的每个属性都是 Known、Absent、Unknown 之一。Absent 是一个答案(问过了,没有),Unknown 是没有答案(读失败,或者读回来的东西不可信)。两者不能合并,因为合并之后,"我没读到"会被当成"确定没有"。文档里有一句很精准的警告:把三态压成 bool 的便捷函数只在肯定位置安全,一旦被取反就 fail open,因为取反会把"我不知道"悄悄改写成"确定不是"。
二、ref 是可校验的身份证据,不是句柄。 快照给 ref 分配身份,动作时严格重识别,零匹配和多匹配都失败关闭,几何只做最后兜底。没有这套东西,快照就只是一次性的坐标表。
三、delivery disposition 把"有没有送到"变成可编程字段。 五种取值,重试安全性由它推导,而不是由错误码猜。再配合 2.5 版删掉恒真成功字段,调用方被迫面对真实的不确定性。
四、文档随二进制分发,错误里带恢复策略。 技能文档编译进二进制,版本天然对齐;错误对象给出枚举化的恢复策略,让 agent 可以写确定性重试逻辑。这两个设计都很便宜,但大部分 agent 工具没做。
横向比较
| agent-desktop | agent-browser | 截图 + 视觉模型 | 传统桌面自动化库 | |
|---|---|---|---|---|
| 观察源 | 系统无障碍树 | 浏览器 DOM / CDP | 像素截图 | 各自平台的 API |
| 覆盖范围 | macOS / Windows / Linux 桌面应用 | 网页 | 任意可见界面 | 通常单平台 |
| 是否内嵌模型 | 否 | 否 | 是 | 否 |
| 元素身份 | 快照 ref + 严格重识别 | 选择器 | 坐标或视觉描述 | 原生句柄 |
| 失败语义 | delivery + retry 枚举 | 错误码 | 通常无 | 异常或布尔 |
| 典型弱项 | 无树的 UI、canvas | 桌面应用 | 漂移、贵、不可复现 | 没有 agent 契约 |
同实验室的 agent-browser 已经有 45222 stars、3101 forks,比 agent-desktop 高一个量级。两个项目的分工写在 README 里:网页用 agent-browser,桌面用 agent-desktop。这不是竞争关系,而是把"浏览器有 DOM"和"桌面有无障碍树"这两种结构化的观察源分别吃透。
跟截图加视觉模型的路线比,agent-desktop 的优势是快、便宜、可复现:一次 snapshot 就是一次本地 API 调用,不需要把屏幕截图发给模型,也不需要模型输出坐标。代价是覆盖面:没有无障碍树的应用它完全看不见,而截图方案至少能"看到"。
跟 AppleScript、AXSwift、FlaUI、AT-SPI 绑定这类传统库比,它做的不是"再包一层 API",而是补上了 agent 需要的三样东西:带身份的元素引用、可判定的动作结果、机器可读的恢复策略。传统库假设调用方是人写的确定性脚本;agent-desktop 假设调用方是一个会犯错、需要重试、必须知道自己错在哪的模型。
仓库里有一篇 solution 文档标题是《Build desktop actions as an observe-resolve-preflight-dispatch contract》,文件名里带 playwright-grade-desktop-reliability。这个类比很准确:Playwright 的价值不在于"能点浏览器",而在于自动等待、可重试断言和清晰的失败原因。agent-desktop 想把同一档可靠性搬到桌面上。
成本、边界与风险
权限是硬门槛。 macOS 必须给辅助功能权限,否则 PERM_DENIED。Linux 需要图形会话和 at-spi2-core,无头服务器上跑不了。Windows 对同完整性级别的应用不需要授权,但跨提权边界仍然会挡。
Electron 和 Chromium 需要额外一步。 macOS 适配器会先问应用根节点 AXManualAccessibility 是否可写,读当前值,最多设置一次,然后在请求的绝对截止时间内等它变成 ready。原因是 Electron 官方文档说这个属性可以让原生辅助软件提前暴露 Chromium 的无障碍树,但当前实现只在完整模式下报 true,所以"设置成功"不等于"已经可用"。不支持这个属性的原生应用会被原样放过。
headless 有明确的能力缺口。 双击、三击、hover、drag 是物理专属,没有 --headed 就失败关闭。skill 文档里有一句很重的提醒:永远不要为了从 headless 失败中恢复而切到 headed。这不是同一条路径的降级,而是换了一种会移动用户鼠标、抢用户焦点的执行方式。
隐私要自己负责。 快照树、窗口标题、剪贴板、通知、截图、命令结果都可能包含用户的桌面内容。调试 HTML 会嵌入截图和无障碍数据,session trace 即使结构化字段脱敏,也可能保留原始证据。原生 CLI 不需要远程模型服务,但仓库里可选的 JEV helper 会把目标和屏幕描述发给配置的模型提供方,需要 TYPESAFE_API_KEY,而且它明确不在安装包里,只在克隆仓库后可用。
生态还在早期。 8257 stars 对 2941 次月下载,113 个 open issue,说明它被读得多、用得少。Vercel Labs 的项目通常允许探索,不承诺长期 API 稳定;envelope 从 2.4 到 2.5 就是一次破坏性改动,C ABI 大版本已经走到 6,升级要重新编译绑定。
版本耦合是设计选择,不是缺陷。 技能文档编译进二进制,意味着你装哪个版本,agent 读到的就是哪个版本的规则。好处是不会文档漂移,坏处是你不能单独升级文档,也不能跨版本复用旧教程里的命令。
参考文档与链接
- vercel-labs/agent-desktop — 仓库主入口
- README — 安装、快速开始、命令分组、平台支持矩阵
- CONCEPTS.md — ref、快照、窗口身份、三态证据的完整词汇表
- AGENTS.md — 依赖倒置、目录约束、新增命令的七步清单
- JSON 输出契约 — envelope、错误码、disposition、2.4 与 2.5 迁移说明
- FAQ — 定位、ref 系统、隐私边界
- agent 侧 skill — observe-act-verify 循环、refs、headless 纪律
- Linux 写入实测 — GTK/Qt/Gecko/Chromium 的成功与失败反例
- 可靠性契约 — observe-resolve-preflight-dispatch 四段式
- 测量与引用规范 — probe 记录与文档引用必须对得上
- 定位解析基准 — 合成 Chromium 树上的 p50/p95 对比方法
- Electron 无障碍说明 —
AXManualAccessibility的官方来源 - agent-browser — 同实验室的浏览器自动化项目
- npm 包 — 版本与月度下载数据
- 文档站 — 在线文档入口
你会把桌面操作交给 agent,还是觉得"看不见屏幕就不敢放手"?评论区聊聊你的边界。
作者: itech001 来源: 公众号:AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top
本文首发于 AI 人工智能时代,转载请注明出处。