产品简介
agent-desktop 是 Vercel Labs 开源的桌面操作层，1.0.2 版，Apache-2.0。它做的事很具体：让能调 shell 的编码 agent 通过操作系统的无障碍树读取并操作原生应用，而不是截图之后让视觉模型猜坐标。
用法是一条命令一个动作。snapshot 拿到一棵树，每个可操作元素带一个 ref；agent 对 ref 执行 click、type 这类动作，再快照一次确认结果。循环留在 agent 自己的代码里，工具只负责观察和执行。ref 属于某一次快照，界面变了就返回 STALE_REF 或 AMBIGUOUS_TARGET，让 agent 重新看一遍，不会点到同名但已经换位置的那一行。
它是一套 Rust 写的 CLI 加 C 库，npm 全局装，macOS、Windows、Linux 都有原生二进制。默认无头执行，不移动指针也不抢焦点，要物理输入得显式加 --headed。
核心功能
- 无障碍树快照：一次 snapshot 返回 JSON，树里每个可操作元素带角色、名称与 ref，agent 读结构而不是读像素。
- ref 与失效处理：ref 绑定某次快照，裸写 @e8 会被拒绝；界面变化时返回 STALE_REF，多窗口时返回 AMBIGUOUS_TARGET 并列出候选窗口。
- 默认无头：ref 动作走无障碍接口，不抢焦点也不合成输入；需要真实键鼠时才加 --headed。
- 三平台：macOS 需要辅助功能权限，Windows 在终端同权限级别下免授权，Linux 需要图形会话与 at-spi2-core。
- 两种安装形态：npm 全局装带原生二进制与平台辅助程序，也提供各平台压缩包；Homebrew 与 Scoop 官方包在提交中。
- CLI 与 C 库：命令行给人和 agent 直接用，C 库供其他语言绑定，同一条命令输出单行 JSON 信封，便于解析与断言。
适合谁用
以下类型的用户会特别受益于 agent-desktop：
- 没有 API 的老桌面软件自动化，用元素语义定位按钮与输入框。
- 把桌面步骤接进编码 agent 的循环，观察、动作、再观察。
- 在 CI 或服务器上无头跑桌面流程，不弹窗、不抢焦点。
- 批量整理文件与表单：在 Finder 或资源管理器里定位条目再操作。
- 桌面应用的回归检查，点完按快照比对界面结构。
- 跨应用搬数据，从一个窗口读、在另一个窗口写。
优点亮点
- 用元素语义定位，界面换主题或改分辨率时不会因为坐标偏移点错。
- 失效有明确错误码，agent 知道该重新快照而不是硬着头皮重试。
- 默认无头执行，跑任务时不影响正在用电脑的人。
- 三平台一套命令，脚本不用按系统分叉。
- Apache-2.0 许可，可商用可改。
- 输出是结构化 JSON，便于 agent 解析、记录与断言。
价格与方案
开源免费，Apache-2.0。npm install -g agent-desktop 即可安装，也提供 macOS、Windows、Linux 的原生压缩包，Homebrew 与 Scoop 官方包仍在提交中。没有托管服务，也没有用量计费。
总结与建议
视觉方案的通病是脆。换个主题、弹个窗、分辨率一变，坐标就偏了。agent-desktop 换了一条更笨但更稳的路，读系统自己维护的无障碍树，元素有角色、有名字、有稳定的 ref。代价是它只能操作那些愿意暴露无障碍信息的应用，收益是每次动作都能验证。对要把桌面操作塞进 CI 或后台 agent 的人来说，无头执行和明确的失效错误，比多模态识别更实用。
版本演进
- agent-desktop 1.0.2：用无障碍树操作桌面应用 （2026-11-01）：Vercel Labs 开源 agent-desktop 1.0.2，Apache-2.0，Rust 写的 CLI 加 C 库，npm 全局安装，覆盖 macOS、Windows 与 Linux。通过操作系统无障碍树做快照，每个可操作元素返回稳定 ref，agent 对 ref 执行动作后再次快照校验，不依赖截图与视觉模型。默认无头执行，不抢焦点也不合成输入；界面变化时返回 STALE_REF，多窗口时返回 AMBIGUOUS_TARGET。macOS 需辅助功能权限，Linux 需 at-spi2-core，Windows 在终端同权限级别下免授权。