agent-desktop
让 agent 操作桌面软件，但不靠截图——它读系统无障碍树，给每个元素一个 ref，点完再读一遍校验。
要自动化 Windows/macOS 桌面软件（Excel、设计工具、内部系统）但又不想上视觉模型的人；以及已经被截图方案的不稳定折磨过的团队。
桌面自动化的主流做法是截图 + 视觉模型找坐标，问题是同一个按钮换一个分辨率、换一次主题、换一种语言就点不中，而且每次调用都要付一次图像 token。
agent-desktop 走的是另一条路：它读操作系统的无障碍树（macOS 的 AX API、Windows 的 UI Automation、Linux 的 AT-SPI），把整棵 UI 树导出成 JSON，每个可操作元素带一个 ref。agent 对 ref 执行点击/输入，再读一次 UI 确认结果——循环写在你的 agent 里，这个工具本身不带模型。
它同时给 CLI 和 C 库。60 个命令里 56 个是可用的，剩下 4 个（key-down、key-up、mouse-down、mouse-up）要等守护进程能释放按住的键鼠才会放行。除了点击、输入、滚动，还能启动/关闭应用、列举窗口和显示器、读写剪贴板、处理通知。
对已经在用 Claude Code、Codex 这类工具的人，最省事的是它的 MCP 模式：`agent-desktop mcp` 把每个命令变成一个工具（desktop_snapshot、desktop_click 等），塞进 MCP 配置就能用。仓库里还带了版本对齐的 skill，`agent-desktop skills get desktop` 会告诉 agent 这套循环该怎么走。
能拿它做什么
- 批量处理桌面软件：把 Excel、PDF 工具、内部管理系统的重复操作交给 agent
- 无 API 的老系统：只有图形界面、没有接口的内部工具，也能被自动化
- MCP 接入：一行配置挂进 Claude Code / Codex，不用自己写工具层
- 前台无干扰：默认 headless 执行，不抢焦点、不动鼠标（需要真点的时候加 --headed）
- 稳定校验：点完再快照一次，靠 ref 判断动作有没有生效，而不是靠"看起来对了"
怎么用起来
- 安装：npm install -g agent-desktop（也支持 bun / yarn / pnpm，macOS 和 Linux 还能 brew install agent-desktop）
- 自检：agent-desktop status 看平台、权限和可用面；macOS 再跑 agent-desktop permissions --guide 授权辅助功能
- 第一次快照：agent-desktop snapshot --app Finder -i，只列可交互元素，每个带 ref
- 动作：agent-desktop click @s8f3k2p9:e8，ref 必须带快照 id
- 校验：再 snapshot 一次，看目标元素的状态有没有变
- 接 MCP：在配置里写 command 为 agent-desktop、args 为 ["mcp"]，即可在支持 MCP 的客户端里用 desktop_* 工具
官网在 github.com/vercel-labs/agent-desktop ，源码在 GitHub 仓库 ↗。
坑在哪
默认 headless 是优点也是限制：不移动指针、不抢焦点，但某些应用会拒绝无焦点的合成输入，这类场景必须切 --headed，而一旦切过去，执行期间你就不能用这台机器干别的。
ref 是跟快照绑定的。UI 一变，动作会返回 STALE_REF 或 AMBIGUOUS_TARGET，必须重新快照拿新 ref——裸写 @e8 会直接报参数错误。这意味着每次交互都是"快照-动作-再快照"的三步，长流程的调用次数不低。
Windows 上要装 Windows 10 1809 以上，Linux 要 Ubuntu 24.04 以上，macOS 要 13 以上并授予辅助功能权限（`agent-desktop permissions --guide` 会带你走一遍）。老系统直接不支持。
隐私是最需要注意的一条。快照、剪贴板、截图、命令输出都可能包含桌面上的私人内容，README 专门警告不要写进公开日志或上传。拿它跑生产的，第一件事是把 trace 目录排除在日志采集之外。
它替代的是"截图+视觉"这条路，不是替代人。真正省下来的不是点击次数，是不用再为每个界面写一套坐标。