01 · 这件事

23,853 星,一个不靠截图的桌面 Agent CLI

它解决的是「agent 怎么看见桌面」,没有顺手解决「多个 agent 能不能同时动手」。

vercel-labs/agent-desktop 的仓库描述只有一句:Computer use for AI agents。它挂在 Vercel Labs 组织下,主页指向 agent-browser.dev/desktop,默认分支是 main。

2026-11-15 用 api.github.com 核对:23,853 星、1,776 fork、241 个未结条目,Apache-2.0,主语言 Rust,建于 2026-02-19,最近一次推送就在核对当天。

241 这个数要拆开看。单独查 search/issues 得到 87 个未结 issue 与 154 个未结 PR,相加正好。仓库接口的 open_issues_count 把两者合在一起,不等于 241 个 bug。

同组织的 agent-browser 管网页,这个仓库管桌面应用。FAQ 直接写明它不自动化网页,网页请用 agent-browser;文档域名相同,取数对象却从浏览器 DOM 换成了操作系统可访问性树。

身份字段先列成表。下面所有数字都来自同一份仓库接口与仓库内文件,不引用第三方榜单的估算值。

字段核对值
仓库 / 描述vercel-labs/agent-desktop · Computer use for AI agents
星标 / fork23,853 / 1,776
未结条目241(87 issue + 154 PR)
创建 / 最近推送2026-02-19 / 2026-11-15
许可 / 主语言Apache-2.0 / Rust
默认分支 / 主页main / agent-browser.dev/desktop

README 把能力收在一句话里:读应用的可访问性树、返回带 ref 的 JSON,循环留给调用方,仓库里没有模型。星标说明有人在看,命令表才说明它做了什么。

02 · 核心机制

snapshot → ref → 动作 → 再读,模型不在仓库里

它省的不是点击耗时,是每一轮观察要交给模型的画面。

README 写得直白:不截图、不做像素匹配,读应用的可访问性树并返回 JSON,每个可操作元素带一个 ref;agent 对 ref 点击或输入,再读一次界面确认结果,如此循环。

循环跑在调用方。README 原句是 has no model inside,工具形态是 CLI 加 C 库;每条命令打印一个 JSON envelope,精简快照示例里 version 是 2.6、ref_count 是 59。

CLI 与 C 库都走同一套 core,再经 PlatformAdapter 落到平台 crate。crates 目录下有 core、ffi、macos、windows、linux 五个,各自在编译期对应一个操作系统。

三个平台的系统要求与授权条件不一样,先按表确认,再谈命令。

平台系统要求无障碍 API授权与限制
macOS13 以上,Intel / Apple SiliconAX API需 Accessibility,截图另需 Screen Recording
Windows10 1809 以上,x64 / ARM64UI Automation同完整性级别免授权,二进制未签名
LinuxUbuntu 24.04 以上,glibc 2.35AT-SPI需 at-spi2-core 与用户图形会话

ref 属于生成它的那次快照。裸写 @e8 会被 INVALID_ARGS 拒绝;界面变化后动作返回 STALE_REF 或 AMBIGUOUS_TARGET,必须重新 snapshot 取新 ref。

ref 还有会话作用域。session 里生成的 ref 需要同一个 --session 或 AGENT_DESKTOP_SESSION;FAQ 列出 18 种能拿到 ref 的 role,静态文本与惰性容器拿不到。

默认 headless:用语义无障碍调用,不抢焦点、不动光标、不合成按键;只有 --headed 才允许物理输入。Windows 的 type 没有 headless 语义路径,严格模式下会失败。

这时要改用 set-value,它是 Windows 上的 headless 文本路径。最硬的边界在 FAQ:应用如果不发布可访问性树,对 agent-desktop 就不可见,命令再多也救不了一个不吐树的窗口。

03 · 关键细节与数据

61 个命令 57 个能跑,4 个还锁在守护进程

命令表、Release、CHANGELOG 三层规模都能数出来,但三处口径并不一致。

README 的命令表分 10 组,把反引号里的命令逐项数完是 61 个。它自己又写明:其中 57 个是 operational commands,另外 4 个拒绝执行。

被挡住的 4 个是 key-down、key-up、mouse-down、mouse-up,都属于「按住再松开」的边沿动作。README 说,要等守护进程能释放被按住的键或按钮,它们才肯运行。

10 组命令按数量列成表。密集数据先摆进表格,比在一段里连报十个数字清楚。

命令组数量命令组数量
Observe6Act on a ref16
Keyboard and mouse10Apps and windows12
Notifications4Clipboard3
Wait1Sessions3
Sandboxes1System5
合计 / 可运行61 / 57待守护进程4

版本口径更值得记。GitHub Releases 只有 4 条,全部集中在 11 月 3 日到 13 日;每版挂 13 个资产,即 12 个平台包加一份 checksums.txt。

但 tags 接口返回 53 个标签,CHANGELOG.md 有 51 个版本标题,最早是 2026-02-23 的 0.1.1,最新是 11-13 的 1.3.1。仓库发过很多版,只是没都做成 Release。

当前版本在三处对齐:最新 tag、npm/package.json、Cargo.toml 的 workspace.version 都是 1.3.1;rust-toolchain.toml 固定 1.89.0。

对象核对值
GitHub Releases4 条,v1.1.0 至 v1.3.1,各 13 个资产
tags 接口53 个标签
CHANGELOG.md51 个版本标题,0.1.1 至 1.3.1
当前版本tag / npm / Cargo 均为 1.3.1
编译工具链Rust 1.89.0,Node 18 以上

多 agent 的部分要读 CONCEPTS.md。session start --cursor --multi-agent 给每个 (session-id, agent-id) 一条光标,CLI 在这种模式下要求 --agent-id;光标是纯呈现层,不改动作策略与响应语义。

交互租约是全机独占的:同一时刻只由一个进程持有,防止并发调用把合成输入交错进彼此的动作。等待不占租约,拿到租约后会二次解析目标。

无头动作的光标位移发生在取租约之前,所以几条光标可以同时飞,动作却必须排队。Linux 的光标渲染还只支持 X11。短视频里「一队 agent 同时干活」是真的,并行的只是光标。

仓库自带的性能量具只有 benchmarks/locator-resolution 一份说明:合成 Chromium 与 Electron 无障碍树、31 次测量的 p50 与 p95 wall-clock,并明确不报告原生 AX 调用绝对数。

真机 Slack、Electron 的测量要另跑 tests/e2e/electron-live.sh 且先拿 Accessibility 权限。README、CHANGELOG 与 benchmarks 里都没有端到端点击耗时的实测值,这类传播数字本文不采用。

04 · 怎么用

三条命令起步,权限与会话要按平台分别处理

上手成本几乎全在授权和会话,不在命令本身。

安装路径有 npm 全局装、Homebrew、Release 压缩包和源码构建。npm/package.json 要求 Node 18 以上,os 与 cpu 字段列出三种系统、两种架构。

一个容易忽略的坑:npm 12 默认拦 postinstall。拦下之后每次调用都走 Node launcher,docs/install.md 写每次多约 125 ms;放行脚本重装即可恢复原生二进制直连。

README 的 quick start 是三步:取快照、按 ref 点击、再取快照验证。把常用命令集中列出来,按顺序跑就能复现。

命令用途
agent-desktop status查平台、权限与 supported_surfaces
agent-desktop permissions --guidemacOS 引导授予无障碍权限
agent-desktop snapshot --app Finder -i取可交互元素与 ref
agent-desktop click @s8f3k2p9:e8按快照里的 ref 动作
agent-desktop skills get desktop取随版本的核心工作流
agent-desktop skills get platform取当前系统的平台指南
agent-desktop mcp以 stdio 暴露 desktop_* 工具

技能跟着 CLI 版本发货:skills 目录下有 6 个子目录,主技能 skills/agent-desktop 下另有 4 份 references 文档。mcp 把每条命令包成同名工具,返回同一个 JSON 信封。

会话默认留痕。CONCEPTS.md 写 session start 的 manifest 里 trace 默认为 on,要关得加 --no-trace;trace 只脱敏结构化字段,仍可能保留证据制品。

把 trace 当公开日志是危险的。artifacts 设为 full 会存未脱敏的前后截图;README 开头直接警告快照、剪贴板读取、截图与命令输出都可能含私密桌面内容。

平台坑也各不一样:macOS 要 Accessibility 授权;Windows 二进制未签名,干净的 Win 11 上 Smart App Control 会拦,下载方式或启动模式都绕不开。

Linux 要求 Ubuntu 24.04 以上、glibc 2.35、at-spi2-core 与用户图形会话,TTY、SSH 或容器看不到应用;Wayland 下应用指针输入返回 ACTION_NOT_SUPPORTED。

FAQ 还提醒:CLI 本身不需要远端模型服务,但可选的 JEV helper 会把目标和屏幕描述发给你配置的模型提供商,用之前先确认那些数据对方能不能看。

05 · 冷思考

没有无障碍树的应用,等于不存在

该先验收的不是并发数,是目标应用肯不肯吐出可访问性树。

第一处质疑是覆盖面前提。FAQ 写死:不发布可访问性树的应用对 agent-desktop 不可见。自绘界面、游戏、加固过的客户端都不给树,61 个命令在这类窗口上无处下手。

第二处是平台差异不是小修。技能文档写明,Windows 与 Linux 上同名按钮的 twin 不能用 ref 唯一定位,只能退到带坐标的 headed 点击;Linux Wayland 还会拒绝这种输入。macOS 靠元素自身地址区分。

第三处是成熟度口径。23,853 星之外,还有 53 个 tag、51 个 CHANGELOG 版本段、4 个 Release,以及 87 个未结 issue 与 154 个未结 PR。CHANGELOG 的 1.3.1 段只有两条 bug fix,SUPPORT.md 写明 best-effort、没有 SLA。

第四处是「并行」这个词。多 agent 光标能同时移动,物理输入却被全机租约串行;把它理解成吞吐翻倍,任务排期就会错。真正省下的是观察上下文,不是操作时间。

按依赖顺序做三个检查,比先装 CLI 更能省时间。

顺序检查什么失败信号
1目标应用是否发布可访问性树snapshot 无节点,或 status 的 supported_surfaces 为空
2平台是否满足授权与会话条件macOS 未授权、Linux 无图形会话、Windows 被 Smart App Control 拦
3并发动作能否接受租约串行光标并行但动作排队,输入互斥

我的判断是:它更像一份严格的无障碍树适配层加 JSON 契约,而不是「让一堆 agent 同时用电脑」的开关。23,853 星买不来一个不吐树的窗口;先把前三行检查做完,再决定要不要把桌面交出去。

数据核对:全部走 api.github.com 的仓库接口、文件内容与目录清单,不引用短视频口播数字。

核对时间 2026-11-15;本文未安装、未运行该 CLI,仅作学习归档。

去看原始仓库

vercel-labs/agent-desktop:用系统可访问性树与 ref 把桌面应用拆成一条条 JSON 命令的 Rust CLI。

前往 GitHub

相关平台

#开源项目 #桌面自动化 #Agent 工具链