让 AI 操作桌面软件,不用靠截图找按钮

agent-desktop 是 Vercel Labs 出的命令行工具，Rust 写的，npm install -g agent-desktop 一行装上，三个系统都带原生二进制。它做的事很窄：把桌面软件的界面读成一份控件清单，让 AI 照清单上的编号去点、去填、去读状态。命令表上有 60 个名字，macOS 上 56 个真能跑，剩下四个是按住不放那类，key-down、key-up、mouse-down、mouse-up，没有守护进程兜住松开的那一刻，它直接拒。工具本身不带模型，观察、动手、再确认这个循环跑在你这边。

截图配像素匹配是大家都熟的路子：丢一张图给模型，问按钮在哪，回一个坐标。窗口一挪、缩放一变，坐标就废了，每问一次还要付一张图的上下文。它走另一条，读操作系统的无障碍接口，macOS 的 AX API、Windows 的 UIA、Linux 的 AT-SPI。这三套本来是给读屏软件准备的，控件是什么角色、叫什么名字、能不能点、有哪些动作，软件自己都写清楚了。清单是软件自己交出来的，不是从图上认出来的。

返回的 JSON 里，可操作元素带一个形如 @s8f3k2p9:e8 的编号，前一段是这次快照的号，后一段是第 8 个元素。动作要把整条原样传回去，只写 @e8 会被 INVALID_ARGS 拒掉。界面一变，旧编号作废，动作回 STALE_REF，让你重新看一眼再动。

界面密的应用不能一次读到底。snapshot --skeleton 先给一层浅图，被截掉的分支带上子节点数，再用 --root 加编号只钻你要动的那块。读不完它不装读完了：整窗快照超时会把看到的部分都返回，带 complete: false 和 nodes_observed，被切的容器自己标 subtree_truncated。--root 钻取是往已有快照里换编号，读不全就宁可回 TIMEOUT，不塞给你一棵残缺的树。

有个取舍我认可：列表里每行都挂一个删除按钮时，位置和大小不算身份。macOS 的编号存着元素自己的地址，双胞胎各点各的；拿不出地址的元素，跟 Windows、Linux 一样，要整个窗口读全了、角色连同 native id、名字、描述在窗口里唯一匹配才算数。两个匹配就 AMBIGUOUS_TARGET，还没碰应用就拒。真要点对一模一样的控件，只剩 --headed 加裸坐标，那会把前台抢过来。

无头是默认：改状态走语义接口，不动指针、不抢焦点、不合成键盘。--headed 得显式打开，随包的说明书里写死一句，不许因为无头失败就切到有头。Windows 上有个具体的坑，type 没有无头路径，因为 UIA 不提供在当前选区插入文字的写接口，无头打字只能走 set-value，--headed 才真去合成按键。等目标变得可点是默认开着的，上限 5000 毫秒，type 再按字数每字符加 30 毫秒，--timeout-ms 0 退回单次尝试。

出错时信封里除了 code 和 suggestion，还有 disposition 两格。delivery 说这次输入到底到了没有，retry 说重复一次安不安全，只有 not_delivered 给 safe，其余值都不给。2.5 版把 clicked、moved、hovered 这些成功标记全删了，理由写在迁移说明里：每次成功都带的标记什么也没证明。现在要看效果，得靠工具自己回读后置状态，读到才算 delivered_verified。

说明书编译进了二进制。agent-desktop skills get desktop 打出循环规则和重试条件，get platform 打出你所用系统的能力表，AI 用之前先问它这个版本能干什么。README 里 60 个命令名、56 个可执行这句话有专门的测试盯着，改了命令不改文档，测试就红。落盘的东西都在 ~/.agent-desktop，一次快照的映射表上限 1 MB，每个命名空间留最新 128 个快照，多了清到 96。

装之前得知道边界。macOS 要给发起它的终端加辅助功能权限，截图还要屏幕录制。Windows 对同完整性级别的应用不用授权，目标级别更高时读得到、写不进，它拿令牌完整性判断，不信 SendInput 的返回值。Linux 要 at-spi2-core，Wayland 下截图走 portal 弹窗同意，剪贴板另要 wl-clipboard。软件不交出无障碍树它就看不见，自绘界面的编辑器和游戏里那些控件，还得回到截图那条路；网页自动化它明确不管，那是另一个工具的活。快照、剪贴板和截图都可能带上桌面上的私密内容，别顺手丢进公开日志。Apache-2.0，版本 1.0.2。

还有个可选的 jev-desktop，把看屏幕、问模型、动手整包接走，但要仓库源码和另一家的密钥，跟这个命令行本身是两件事。AI 点错按钮，多半不是模型笨，是它拿着一份过期的地址还装作没过期。已经在自己写 agent 循环的人，这个工具管的是手的可靠性；平时没这种活，不必专门装。