用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824

255次阅读
没有评论

共计 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)

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824

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,可以往下走。

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:终端输出整理成的样式图,命令和数字取自我的实测日志,2026-11-03 上午(UTC+8)
用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824

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,意思是这个编号只在这次观察里有效。界面一变,老编号可能就指错了东西,所以规矩是:动作做完,重新拍一次快照。

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
循环顺序:拍快照 → 点 / 打字 → 读回来 → 再拍新快照。读回来对不上,就回去重点一次

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。

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:终端输出整理成的样式图,命令和数字取自我的实测日志,2026-11-03 上午(UTC+8)

接下来我没去修它,转头开了两个 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,对的。也说明一件事:代理想「核对结果」,前提是结果本身在树里。不在的话,它还是得退回去看图。

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:agent-desktop screenshot 原图,我在 Linux 测试机上实测,2026-11-03 08:05(UTC+8)

08:05:51 Mousepad 里打一行中文

编辑器这种程序菜单多,-i --compact 拍下来有 271 个 ref、46,400 字节,绝大多数是菜单项。官方给的办法是先拍骨架:

agent-desktop snapshot --app mousepad --skeleton -i --compact

骨架只有 79 个 ref、14,662 字节,不到原来的三分之一。要喂给模型的话,先喂骨架,看中哪一块再用 --root 展开那一块。

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:终端输出整理成的样式图,命令和数字取自我的实测日志,2026-11-03 上午(UTC+8)

找到正文区 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。代理要是脑子一热想关窗口,这一道闸挺有用。

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:终端输出整理成的样式图,命令和数字取自我的实测日志,2026-11-03 上午(UTC+8)
用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:agent-desktop screenshot 原图,我在 Linux 测试机上实测,2026-11-03 08:08(UTC+8)

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
用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:终端输出整理成的样式图,命令和数字取自我的实测日志,2026-11-03 上午(UTC+8)

第二个「1」被吞了,1103 变成了 103。七次点击每次都回 ok=True delivered_unverified。这个 delivered_unverified 我前面一直扫过去没细看,直译是「送到了,没验证」。只看返回值的代理,会以为自己算对了。

计算器的历史记录把两次都留了下来,一行 103×8=824,一行 1103×8=8824,正好当证据:

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824
本机实测:agent-desktop screenshot 原图,我在 Linux 测试机上实测,2026-11-03 08:07(UTC+8)

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

用 agent-desktop 替 AI 点了一早上计算器,少等 300 毫秒,1103×8 就成了 824

写给打算接进自己代理的人

我这次没接模型。真要接,官方给了两种方式,二选一:

# 装成 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 细得多。

照我这一早上的体会,接进去之前有三件事最好写进你的提示词或脚本:

  1. 每个会改界面的动作后面,跟一句 wait 或者 wait --element … --predicate value,等结果真出来
  2. 别信 ok: true,用 get 把值读回来对一遍
  3. 结果不在无障碍树里的程序(比如 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")

出处

正文完
 0

版权声明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。

科技喵仔
版权声明:本站原创文章,由 科技喵仔 于2026-11-03发表,共计6868字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
验证码
    中文English