agent-desktop：读无障碍树操控 Mac 应用的智能体 CLI

桌面自动化的主流做法是截屏加视觉模型：找到坐标，点下去。贵、脆，而且 Slack、VS Code 这类密集应用一屏就能把模型的上下文吃掉大半。agent-desktop 是 2026 年 2 月开源的另一种思路（Rust 单二进制，Apache-2.0，截至 2026-10-12 已 1.8k star）：不猜像素，直接读操作系统的无障碍树，看到应用真实的 UI 结构，再按稳定引用操作它。

核心功能

• 无障碍树加稳定 ref：快照按深度优先给元素发引用（形如 @s8f3k2p9:e1），click @e12 --snapshot s8f3k2p9 按 ref 操作；ref 在同一次快照内保持稳定，动作可以安全重试。
• 动作前六项预检：可见性、稳定性、可用状态、支持的动作、策略、可编辑性全部通过才执行；默认不抢焦点、不动真实鼠标、键盘和剪贴板。
• 省 token 的两层观察：--skeleton 先给三层浅层概览，被截断的容器显示 children_count，再沿安全的 drill ref 下钻到具体控件；官方称密集应用可省 78–96% token，Slack 的快照从 30,743 token 降到 383。
• 58 个命令名、54 个可执行命令：快照、点击、输入、按键之外，还有会话录制和 trace 回放——trace show --limit 500 看操作时间线，trace export --out run.html 导出可读报告。
• 为多 agent 设计：AGENT_DESKTOP_AGENT_ID 给每个 worker 一个稳定 ID，多个 subagent 可以共享会话并行观察和操作，光标 overlay 沿人类路径移动（90–320 ms）显示各自意图。
• Chromium 应用可换后端：launch --cdp 打开 CDP 端口，交给 Playwright、Puppeteer 或 agent-browser 驱动 web contents，原生菜单、对话框和窗口仍走无障碍路径；CDP 需要全新启动，对着已经运行的目标启动会返回 ACTION_FAILED。

「省 token」不是口号，README 给了对照：同一时刻的 Slack 界面，完整无障碍树快照 30,743 token，浅层概览加定向下钻 383 token。

典型使用场景

• 多 agent harness 的调度者：让 researcher、builder 等 subagent 各自带 ID，在 Xcode 或 Finder 上并行观察与点击，互不抢焦点，意图在屏幕上看得见。
• 跑完长任务要复盘的人：session start --screenshots 开局，操作完后用 trace 回放整条时间线，定位哪一步点空了。
• 要驱动 Electron 应用的 agent 作者：agent-desktop launch "Obsidian" --cdp 拿端口，web 层交给 CDP 工具链，原生 UI 仍用 ref。

快速上手

npm install -g agent-desktop        # 自动下载预编译二进制
npx agent-desktop snapshot --app Finder -i

第一次跑之前先 agent-desktop permissions --request：macOS 需要辅助功能权限，截屏另需屏幕录制权限。上面这条命令会列出 Finder 的交互元素、ref 和 snapshot_id，接着就能 agent-desktop click @e3 --snapshot s8f3k2p9 点按钮、agent-desktop type @e5 --snapshot s8f3k2p9 "quarterly report" 填字段。密集应用先用 --skeleton 拿概览再下钻，别把整棵树塞给模型。

小结

agent-desktop 适合把桌面 GUI 当作动作空间的 agent 开发者和 harness 作者。三个要认清的点：第一，它只做观测和执行，不调用任何模型——「选哪个」是调用方 agent 自己的事，这正是它省 token 的原因，也是它的边界；第二，平台支持表里只有 macOS 是全 Yes，Windows 和 Linux 全部列为 Planned，源码构建要求 macOS 13.0+ 和 Rust 1.89+；第三，--cdp 的端点绑在 127.0.0.1，开着的时候同用户的本地进程都能连。代码 Apache-2.0，Rust 编写。想看「截屏派」与「结构派」的完整对比，可以读我们的智能体控制浏览器五条路线；这个项目在 Jev 生态十例里是那个不调用 Jev 的反向证据。