共计 6868 个字符,预计需要花费 18 分钟才能阅读完成。
今天早上我没接任何大模型,自己扮演 AI,去指挥一只「手」。这只手叫 agent-desktop,Vercel Labs 放出来的命令行程序,专门给 AI 代理用:它读操作系统的无障碍树,把桌面程序里每个按钮、输入框都编上号,代理拿着编号去点、去打字,点完再读一遍确认结果。它自己不带模型,也不看截图。
08:02 我抓 GitHub 日榜时它排第一,当天 +2,275★。我在一台没有显示器的 Linux 机器上照着它的规矩点了一早上计算器。下面按时间记,几点几分发生了什么就写什么,包括两次翻车。
本次环境:作者的 Linux 测试机 · Debian 13 x86_64 · 8 vCPU · Node v24.22.1 · agent-desktop 1.0.2 · 单独起的 Xvfb 虚拟屏 :9(1280×800)· 2026-11-03 上午(UTC+8)

08:00 它不看截图,那看什么
我之前见过的 computer use 方案大多是截图派,比如 Anthropic 2024 年放出来的 computer-use-demo:把整块屏幕截给模型,模型数像素,回一个坐标,再由 xdotool 去点。agent-desktop 走另一条路,问操作系统要一棵「无障碍树」。这棵树本来是给读屏软件准备的,里面写着窗口里有几个按钮、每个叫什么、能执行哪些动作。macOS 上叫 AX,Windows 上叫 UI Automation,Linux 上叫 AT-SPI。
代理拿到的是结构化 JSON,不用猜像素。反过来,程序不往这棵树里写东西,它就看不见。今年 5 月它还在作者 lahfir 个人名下时上过 Hacker News 的 Show HN,评论区有人猜,egui、Dear ImGui 这类自己画界面的库它多半够不着。我手上没有这类程序,没验证。
几个数,查的时候是今天 08:07:
- 仓库 vercel-labs/agent-desktop,9,583★,649 个 fork,Apache-2.0
- 1.0.0 是 10 月 28 日发的,1.0.2 是北京时间 10 月 31 日凌晨 5 点多发的;1.0.2 的更新记录里写着仓库刚从个人名下转到 vercel-labs
- npm 下载量:10 月 26 日到 11 月 1 日这一周 12,834 次,最近 30 天(10 月 3 日到 11 月 1 日)总共 14,843 次。大部分是最近一周来的
08:01 装依赖两分半,装它一秒
Linux 版的前提写得很清楚:要在用户的图形会话里跑,要有 AT-SPI 无障碍总线。平台说明要求 Ubuntu 24.04 以上,官方实测过的桌面是 GNOME。我这台是没有显示器的 Debian 服务器,先把无障碍总线和几个练手用的程序装上:
sudo apt install at-spi2-core gnome-calculator mousepad galculator
apt 跑了两分半,大头是下载 150 个包、84.7MB。(galculator 其实是 08:05 中途补装的,这里并成一行写。)然后才轮到主角:
npm install -g agent-desktop@1.0.2
agent-desktop version
0.98 秒。npm 11 顺手提醒了一句:这个包有个 postinstall 脚本,没在 allowScripts 白名单里,所以没执行。我没管它,后面的命令都正常。
08:04:07 给它拼一个「桌面」
没有显示器,就起一块虚拟屏,再把会话总线、无障碍总线、窗口管理器一样样补上:
Xvfb :9 -screen 0 1280x800x24 & # 虚拟屏
export DISPLAY=:9 XDG_RUNTIME_DIR=/tmp/xdg-lab9 GTK_A11Y=atspi
dbus-daemon --session --fork --address=unix:path=/tmp/xdg-lab9/bus
export DBUS_SESSION_BUS_ADDRESS=unix:path=/tmp/xdg-lab9/bus
/usr/libexec/at-spi-bus-launcher --launch-immediately & # 无障碍总线
xfwm4 & # 随便一个窗口管理器
gnome-calculator &
拼好以后先跑 agent-desktop status。官方文档专门提醒:supported_surfaces 如果是空的,说明无障碍总线没应答,不是桌面上没程序。我这里返回了 window, sheet, alert, menu 四项,accessibility: granted,可以往下走。


08:04:30 第一次看见计算器
agent-desktop snapshot --app gnome-calculator -i --compact
0.07 秒,返回一段 5KB 左右的 JSON,ref_count 是 36。-i 只要能交互的元素,--compact 压掉一部分没名字的空壳层级。挑几行看:
@s22161u5k4903r:e4 textfield [SetValue, TypeText, ...]
@s22161u5k4903r:e13 button '1' [Click, SetFocus]
@s22161u5k4903r:e18 button '×' [Click, SetFocus]
@s22161u5k4903r:e28 button '=' [Click, SetFocus]
ref 的格式是 @快照编号:e序号。前半截是这次快照的 ID,意思是这个编号只在这次观察里有效。界面一变,老编号可能就指错了东西,所以规矩是:动作做完,重新拍一次快照。

08:04:42 第一次点「1」,等了 5 秒
agent-desktop click @s22161u5k4903r:e13
5.01 秒后,TIMEOUT。它的错误信息写得挺细,四项检查里 enabled、supported_action、policy 都过了,卡在 visible 上,原因是 bounds unavailable,拿不到按钮在屏幕上的位置。我又点了一次,还是 5.01 秒超时。用 get --property bounds 查,返回 null。

接下来我没去修它,转头开了两个 GTK3 程序 galculator 和 mousepad 试别的。08:05:57 回头拿同一个老 ref 再点,0.12 秒成功,bounds 也有了:x 24、y 524、宽 71、高 44。后来我把计算器关掉重开,连着查了 12 次、36 秒,每次 bounds 都是立刻就有。
到底是什么让它从拿不到变成拿得到,我没坐实。可能是总线刚起来时有个注册过程,也可能和另外两个程序启动有关。如果你在新环境里第一次就撞上 bounds unavailable,先等一会儿,或者先开个别的程序,再重新 snapshot 试一次。
08:05:21 换 galculator,一路顺
galculator 是 GTK3 写的老派计算器,第一次点就成功,0.06 秒。我按 AC、1、1、0、3、*、8、= 依次点下去,每下之间睡 0.3 秒。
这里撞到另一个限制:galculator 的显示屏没进无障碍树,snapshot 里找不到结果在哪。只能用 agent-desktop 自带的截图看:
agent-desktop screenshot --app galculator ./shot-galculator.png
截出来是 8824,1103×8,对的。也说明一件事:代理想「核对结果」,前提是结果本身在树里。不在的话,它还是得退回去看图。

08:05:51 Mousepad 里打一行中文
编辑器这种程序菜单多,-i --compact 拍下来有 271 个 ref、46,400 字节,绝大多数是菜单项。官方给的办法是先拍骨架:
agent-desktop snapshot --app mousepad --skeleton -i --compact
骨架只有 79 个 ref、14,662 字节,不到原来的三分之一。要喂给模型的话,先喂骨架,看中哪一块再用 --root 展开那一块。

找到正文区 e269,打字,再读回来:
agent-desktop type @s15etan2zhf9fw:e269 "科技喵仔 11-03 早上好,这行字是 agent-desktop 敲的"
agent-desktop get @s15etan2zhf9fw:e269 --property text
打字 0.18 秒,读回来一字不差,中文全角逗号也在。文档说默认的 headless 模式不动鼠标、不抢焦点,走的是无障碍接口。虚拟屏上我看不到鼠标,这一条只能先信文档。
顺手试了两个它会拒绝的操作。用裸编号 @e269,直接 INVALID_ARGS,提示必须带快照 ID。按 alt+f4,POLICY_DENIED,说这个组合键出于安全默认屏蔽,真要按得加 --force。代理要是脑子一热想关窗口,这一道闸挺有用。


08:07 824 是怎么来的
平台说明里有一句我一开始没当回事:在 GTK4 上,两次点击同一个按钮间隔不到大约 250 毫秒,只算一次,而且两次都返回 ok: true。
我先单测了一下。清零,连点两次「1」,不等待,过一秒再读:「1」。连做 4 轮,4 轮都是「1」。中间加一句 agent-desktop wait 300 再点,就是「11」。
然后我写了个二十来行的小脚本 loop.py,模仿代理的做法:拍一次快照,按按钮名字找到 ref,挨个点,最后读显示框。同一串「1 1 0 3 × 8 =」跑两遍:
- 不等待:1.4 秒跑完,显示 824
- 每步之后
wait 300:3.6 秒跑完,显示 8824

第二个「1」被吞了,1103 变成了 103。七次点击每次都回 ok=True delivered_unverified。这个 delivered_unverified 我前面一直扫过去没细看,直译是「送到了,没验证」。只看返回值的代理,会以为自己算对了。
计算器的历史记录把两次都留了下来,一行 103×8=824,一行 1103×8=8824,正好当证据:

还有个小细节。第二遍拍快照时 ref_count 从 36 变成 37,按钮「1」的编号从 e13 变成了 e14,因为历史列表多了一行。要是代理拿着上一轮的 e13 去点,点到的就不一定是「1」了。

写给打算接进自己代理的人
我这次没接模型。真要接,官方给了两种方式,二选一:
# 装成 skill
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
或者在项目的 AGENTS.md 里加两行,让代理第一次用之前先读 agent-desktop skills get desktop 和 agent-desktop skills get platform。这两份文档跟着二进制走,版本永远对得上。我读了 Linux 那份,GTK4 连点、Chromium 要加 --force-renderer-accessibility、Wayland 下截图要弹授权框,这些坑都写在里面,比 README 细得多。
照我这一早上的体会,接进去之前有三件事最好写进你的提示词或脚本:
- 每个会改界面的动作后面,跟一句
wait或者wait --element … --predicate value,等结果真出来 - 别信
ok: true,用get把值读回来对一遍 - 结果不在无障碍树里的程序(比如 galculator 的显示屏),要准备好用截图兜底
另外 README 里有一句隐私提醒我觉得应该放大说:snapshot、剪贴板、截图里都可能有你桌面上的私人内容,别把这些 JSON 原样贴进公开日志或 issue。
这一早上没碰的
- 没接真实的大模型,所有「代理决策」都是我手动或脚本写死的
- 只在 X11 的 Xvfb 虚拟屏上跑,没测 Wayland,没测 macOS 和 Windows
- 系统是 Debian 13,不在官方写的 Ubuntu 24.04+ 范围里;我测到的命令都能用,别的没保证
- 没测 Chromium、Electron、Qt 程序,也没测
--headed物理鼠标键盘 - 08:04 那次 5 秒超时的原因没查清
下一步我想把它接到一个本地小模型上,让模型自己去点这台计算器,看它会不会也把 1103 算成 103。
附:loop.py
本文 824 和 8824 两组数都出自这个脚本,第三个参数是每步之后等多少毫秒:
#!/usr/bin/env python3
"""手动扮演 AI 代理:观察 -> 按名字找 ref -> 动作 -> 再观察核对。"""
import json, subprocess, sys, time
def ad(*a):
r = subprocess.run(["agent-desktop", *a], capture_output=True, text=True)
return json.loads(r.stdout)
def refs(tree, out):
if "ref_id" in tree and tree.get("name"): out.setdefault(tree["name"], tree["ref_id"])
if tree.get("role") == "textfield" and "ref_id" in tree: out.setdefault("<display>", tree["ref_id"])
for c in tree.get("children", []): refs(c, out)
return out
app, keys, gap = sys.argv[1], sys.argv[2].split(), int(sys.argv[3])
t0 = time.time()
snap = ad("snapshot", "--app", app, "-i", "--compact")
m = refs(snap["data"]["tree"], {})
print(f"snapshot {snap['data']['snapshot_id']} ref_count={snap['data']['ref_count']}")
for k in keys:
r = ad("click", m[k])
print(f"click {k:>2} -> {m[k]} ok={r['ok']} {r.get('data',{}).get('disposition',{}).get('delivery','')}")
if gap: ad("wait", str(gap))
time.sleep(0.5)
v = ad("get", m["<display>"], "--property", "value")["data"]["value"]
print(f"display = {v!r} gap={gap}ms 用时 {time.time()-t0:.1f}s")
出处
- 仓库与 Release:https://github.com/vercel-labs/agent-desktop ,https://github.com/vercel-labs/agent-desktop/releases/tag/v1.0.2
- 官方文档:https://agent-browser.dev/desktop
- npm 下载量 API:https://api.npmjs.org/downloads/point/last-week/agent-desktop
- GitHub Trending 日榜:https://github.com/trending (2026-11-03 08:02 UTC+8 抓取)
- Hacker News Show HN 讨论:https://news.ycombinator.com/item?id=47982708
- Anthropic computer-use-demo:https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo
- 本文命令输出与截图:我在自己的 Linux 测试机上 2026-11-03 08:04–08:08(UTC+8)实测




