Vercel Labs 开源了一个 Rust CLI：agent-desktop。截至 11 月 5 日，16,561 stars、1,158 forks。仓库 2 月 19 日建，安静开发两个多月，10 月 30 日发 v1.0.2，11 月 3 日 v1.1.0（破坏性变更），11 月 5 日 v1.2.0（新增 MCP server），六天三个版本。

它的定位一句话：agent-browser, for your whole computer。不给模型、不截屏、不做像素匹配——把操作系统的无障碍树读成 JSON，给每个可交互元素一个 ref，Agent 按 ref 点击和输入，然后再读一次树来验证。

三条路线，一场迟到了十年的迁移

让 AI 操作电脑，目前有三派做法：

• 截图派：Anthropic Computer Use、OpenAI Operator。拍屏 → VLM 看图 → 输出鼠标坐标 → 执行。通用性最好，但有三个硬伤。
• DOM 派：browser-use、Playwright 系。结构化数据，准确率高，但只能操作浏览器。
• 无障碍树派：agent-desktop 走的路。macOS 用 AX API，Windows 用 UI Automation，Linux 用 AT-SPI。

截图派的三处硬伤值得复述一遍，因为它们正是树派存在的理由：

像素不等于语义。 模型看到的是颜色块，不是「按钮」和「输入框」。在一张密集表格里区分「编辑」和「删除」两个小按钮，对 VLM 是地狱级考题；弹窗盖住内容时，模型经常把弹窗里的按钮「点」到下层去。网上那些 Computer Use 演示，背后的重试次数通常不会写出来。

坐标会漂。 Agent 识别出「提交」按钮在 (637, 289)，下一秒来条系统通知盖住那片区域，或者用户把窗口拖偏了 20 像素，按旧坐标点下去就点到了别的东西。所以截图派每一步都得重拍重识别，成本翻倍。

速度与成本。 一张 1080p 截图喂给主流 VLM 大约消耗 1000-2000 个 image token；同一个界面转成无障碍树 JSON，通常 2-5K 文本 token 封顶，而且是信息无损的——按钮的文字、状态、可交互性全在里面，不需要模型去「认字」。一个 20 步的桌面任务，两条路线的 token 开销差 5-10 倍，延迟差更大：图像编码加 VLM 推理一轮是秒级，树查询是毫秒级。

这里有个容易被忽略的事实：无障碍树不是谁的新发明。它是无障碍工程的产物——视障用户靠屏幕阅读器「听」电脑，读的就是这棵树；测试工程圈用 UI Automation 做自动化测试也做了十几年。浏览器自动化圈其实早在十年前就把这场仗打完了：Selenium 靠 XPath/DOM 定位，Playwright/Puppeteer 全面转向 CDP 协议，主流框架里没有一家走截图路线。桌面端只是晚了十年才开始同样的迁移。

所以 Vercel 补的从来不是树，而是把树接到 LLM 上的那层干净接口：读树、给句柄、执行动作，封装成 Agent 能直接调用的 CLI / C 库 / MCP 工具。

循环活在 Agent 里

agent-desktop 最克制的设计选择是：循环放谁手里。它的答案是「循环在 Agent，工具无脑执行」。它不决定下一步做什么，只忠实地快照、执行、返回结果。

核心循环四步：

agent-desktop snapshot --app Finder -i    # 拿快照，每个元素带 ref
agent-desktop click @s8f3k2p9:e8           # 对某个 ref 点击
agent-desktop type  @s8f3k2p9:e12 --stdin  # 从 stdin 输入（避免密钥进进程参数）
agent-desktop snapshot --app Finder -i    # 再次快照，验证结果

那个 @s8f3k2p9:e8 是整个工具的灵魂：s8f3k2p9 是快照号，e8 是元素号。ref 绑定的是无障碍树里的节点，不是坐标——窗口动了、滚屏了、DPI 变了，ref 依然是那个按钮。更关键的是安全含义：快照号前缀强制「先观察再行动」，你拿着上一个快照的 ref 去操作下一个状态的世界，系统直接返回 STALE_REF 拒绝。

错误码都是机器可读的，而且带处置建议：STALE_REF 表示界面变了要重新观察，AMBIGUOUS_TARGET 表示目标描述不够精确、匹配到多个相同控件。官方 skill 文档把「行动后必须验证」写成了硬纪律——这是把自动化领域最经典的坑（点了但没生效、自己不知道）产品化了。设计哲学一句话：宁可拒绝执行，不可蒙着执行。

工程细节能看出这是个正经的基础设施项目：

• 一个 core 引擎 + PlatformAdapter trait，三个平台各自编译（agent-desktop-macos / -windows / -linux），CI 对每个 PR 跑对应平台的 clippy 全警告拒绝。三个 OS 的无障碍 API 哲学完全不同（macOS AX 是 Objective-C 对象树、Windows UIA 是 COM 组件模型、Linux AT-SPI 是 D-Bus 总线协议），这层脏活 Vercel 替所有 Agent 开发者干了
• 60 个命令，56 个是操作命令：snapshot / find / screenshot / list-surfaces、click / type / set-value / scroll、press / hover / drag、launch / close-app / focus-window、剪贴板与通知、session / trace
• 默认 headless：不移动鼠标指针、不抢焦点，只在无障碍层发送事件。加 --headed 才有物理输入效果。这意味着你可以边打字边让 Agent 操作另一个窗口
• key-down / key-up / mouse-down / mouse-up 四个命令必须配合 daemon 才能跑——确保按下的键或鼠标键最终能被释放，防止 Agent 失控卡住输入状态
• 三种形态：CLI、C 库 libagent_desktop_ffi（Python / Go / Node 进程内零开销调用）、MCP server（v1.2.0 起，每个叶子命令包成一个工具，如 desktop_snapshot，兼容 Claude、Cursor）。npm 包内置 x64 / ARM64 原生二进制，原生调用约 21ms，走 Node launcher 约 146ms

天花板在哪，得说清楚

一个独立的 Linux 实测（Ubuntu 24.04.5 + XFCE + X11，v1.0.2）暴露了真实摩擦：

• list-windows 对一个明明在屏幕上的窗口返回空数据，snapshot 报 WINDOW_NOT_FOUND，得用 --activate 启动才行
• Mousepad 全量快照 271 个 ref，skeleton 快照 79 个——密集应用必须走「先骨架、再按 root ref 下钻」的模式
• 最要命的一条：set-value 改了内存里的文本缓冲区，但磁盘上的文件内容没变；不带 --force 关闭时卡在「是否保存」对话框上。也就是说「字段显示了新文本」和「数据保存了」是两个不同的断言，Agent 必须验证后者
• 两个 GTK 点击间隔小于约 250ms，只生效一次

结构性限制也在：很多 Win32 应用暴露的树很薄甚至为空，自绘控件、游戏、关了无障碍的 Electron 构建基本读不到东西，只能退回截图或键盘模拟——所以 screenshot 命令被保留成独立路径，不逼你做二选一。完整性级别也是硬墙：中等完整性进程读不了高完整性窗口，还得走 UAC / UIAccess 那套。

安全面值得单独提醒。README 明确说快照、剪贴板读取、截图、命令输出、调试产物都可能包含私密桌面内容；batch 的 JSON 文本会出现在进程参数里，密钥要用 --stdin 单独传。独立评审指出：项目没有文档化的沙箱，也没有讨论屏幕上文字带来的提示词注入风险。作者自己的建议是放在虚拟机里、用测试数据跑，不要跑日常机器。

值得关注的原因

第一，范式从「视觉模拟」转向「结构理解」。 过去两年我们教 AI「看图做事」，现在多了一条路：操作系统本身就维护着一份完整的 UI 结构树，为什么不直接读？这不是新技术，是新视角——残障用户和 AI 面对的是同一个问题：机器如何感知为人设计的界面。

第二，基础设施的最佳姿态是「笨但可靠」。 不带模型、不带规划器、循环留给上层，好处是模型升级时（GPT-5 → GPT-6）策略自动跟着升级，工具本身保持极简、出问题时调试面小。这个原则 Unix 时代如此，Agent 时代依然如此。

第三，token 经济性会决定路线胜负。 单步省一点看不出来，但当 Agent 任务从十步走到千步（批量操作、持续监控），「发一条微信」和「寄一封挂号信」的差别就变成了方案能不能通过成本核算。

最后一句提醒：1.6 万星的曲线通常是「被某个大 Agent 框架的文档引用」的信号，不是产品成熟度的信号。这项目现在最真实的定位是——它把桌面自动化欠了十年的路线迁移，重新拉回了台面。