agent-desktop 是什么：让 Agent 操作桌面 App 的 CLI
Vercel Labs 的 agent-desktop 让 AI Agent 读取并操作桌面 App：它读系统无障碍树，给每个可操作元素一个引用，Agent 按引用点击、输入，再拍一次快照核对结果，全程不靠像素识别。2026-11-03 12:13（北京时间）发布 v1.1.0，Apache-2.0，GitHub 约 1.07 万星，macOS、Windows、Linux 都能装。
它是什么
agent-desktop 是给 Agent 用的「电脑操作」CLI，另附一个 C 库。它和站内写过的 agent-browser 出自同一团队，思路也一样：先拿结构化快照，再按引用动手。区别在于对象从网页换成了 Finder、Slack、系统设置这类原生桌面应用。
| 仓库 | github.com/vercel-labs/agent-desktop |
|---|---|
| 作者 | Vercel Labs |
| 许可证 | Apache-2.0 |
| 热度 | GitHub 10,666 星（GitHub API，2026-11-03 14:09 北京时间）；npm 2026-10-26 至 11-01 周下载 12,834；skills.sh 安装约 2.9K（同日抓取） |
| 语言 / 运行要求 | Rust；npm 安装要求 Node.js ≥ 18。macOS 要开「辅助功能」权限；Linux 以 Ubuntu 24.04+ / GNOME 46 为主要目标，需在图形会话里装好 at-spi2-core |
| 最新版本 | v1.1.0（GitHub 发布于 2026-11-03 12:13，北京时间；npm 同版本） |
解决什么问题
让 Agent 操作桌面软件，常见做法是截图后让模型猜坐标再点。按钮挪了位置、分辨率变了、窗口被挡住，就会点错，而且点错了也不容易发现。agent-desktop 改读操作系统本来就有的无障碍树：每个按钮、输入框、列表项都有角色、名字和可执行动作，快照以 JSON 形式返回，每个元素带一个 ref_id。
引用写成 @s8f3k2p9:e8，前半段是快照编号。只写 @e8 会被 INVALID_ARGS 拒绝；界面变了以后再用旧引用，会返回 STALE_REF 或 AMBIGUOUS_TARGET。Agent 拿到的是一个明确的错误，可以重新拍快照，不会在点错位置后还以为成功了。
每条命令只输出一个 JSON 信封：成功时给 ok 和 data，失败时给 error，里面有 code、disposition，通常还有一条 suggestion。官方约定只在 error.disposition.retry 为 safe 时重试，Agent 照这个字段写重试逻辑就行。
怎么用
npm install -g agent-desktop
agent-desktop version
agent-desktop permissions --guide # macOS：引导打开辅助功能权限
agent-desktop list-apps官方示例里的观察—动作—再观察：
agent-desktop snapshot --app Finder -i # 只列可交互元素，每个带 ref
agent-desktop click @s8f3k2p9:e8 # 按那次快照的 ref 操作
agent-desktop snapshot --app Finder -i # 再拍一次确认结果像 Slack 这种元素多的应用，先画骨架再钻进某一块，免得一次塞满上下文：
agent-desktop snapshot --skeleton --app Slack -i --compact
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact有多个窗口时会报 AMBIGUOUS_TARGET，候选窗口 id 在 error.details 里，用 --window-id 指定其中一个。在 PowerShell 里，引用要加引号（'@s8f3k2p9:e8'），否则 @ 会被当成展开运算符。
接入编程 Agent 有两种方式，二选一：
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 并照做。说明文档打包在二进制里、跟版本走，升级后不会读到过期的说明。
上手要点
| 平台 | 要准备什么 | 限制 |
|---|---|---|
| macOS | 辅助功能权限；截图另需「屏幕录制」 | Dock、菜单栏状态项从 v1.1.0 起可达 |
| Windows | 与终端同权限级别的应用无需授权 | 以管理员运行的应用只能读，需提权 Agent 才能输入；二进制未签名，浏览器下载会触发 SmartScreen |
| Linux | 用户图形会话 + at-spi2-core；X11 键盘需 XTEST | SSH/TTY 看不到桌面应用；Wayland 下拒绝指针输入、不支持原生窗口控制 |
还有一个安装细节：npm 包的 postinstall 会把 Node 启动器换成指向原生二进制的链接，官方给的数据是每次调用约 21 ms；脚本被拦时走 Node 启动器，约 146 ms。npm 12 默认拦安装脚本，可以用 npm install-scripts approve agent-desktop 放行，或者安装时加 --allow-scripts。
引用带快照编号，界面一变旧引用就作废。旧引用会直接报 STALE_REF，Agent 据此重拍快照，而不是在点错的位置上接着操作。
v1.1.0 新增 type --interval-ms（按固定节奏输入），macOS 可以操作 Dock、菜单栏状态项和系统面板，修了 Windows 下命令退出时崩溃，三个平台的引用重新定位规则也改了。60 个命令名里 56 个可用，另外 4 个（key-down、key-up、mouse-down、mouse-up）要等有守护进程能负责释放按键后才开放。
适合谁，不适合谁
适合：想让编程 Agent 帮忙点桌面应用、做原生 App 冒烟测试或重复操作；想用结构化 JSON 和稳定引用，不想靠截图猜坐标；需要进程内调用的，可以接每个版本附带的 libagent_desktop_ffi C 库。
不适合 / 请改道：只操作网页的，用 agent-browser 或 Chrome DevTools MCP 更直接。只有 SSH 登录、没有图形会话的 Linux 服务器跑不起来。无障碍信息写得差的应用，快照里能用的元素会很少。对隐私敏感的场景，注意快照和截图会原样带出窗口内容；仓库里可选的 JEV 助手会把屏幕描述发给你配置的模型服务，它和原生 CLI 是分开的。
最后
想让 Agent 操作桌面应用，先 npm install -g agent-desktop，拿一个自己常用的应用跑一遍 snapshot → click → snapshot，再用 npx skills add 或在 AGENTS.md 里加一行说明，把它接进你的编程 Agent。
