开源agent-desktop告别AI截图：一棵树省掉96%Token消耗
内容提要
agent-desktop 是一款用 Rust 编写的桌面自动化 CLI 工具，通过操作系统无障碍树为 AI 代理提供结构化界面访问，无需截图或像素匹配。它支持渐进式骨架遍历，可减少 78–96% 的 Token 消耗，并提供智能引用系统确保元素稳定定位。工具兼容 Chromium 应用，但当前仅 macOS 完整可用，Windows 和 Linux 支持尚在规划中。
延伸解读
为什么无障碍树比截图更高效
截图方案需要AI从像素中推断UI元素的语义，而操作系统本身已经通过无障碍树提供了这些信息。agent-desktop直接读取这棵树，避免了像素识别带来的误差和计算开销。这就像直接阅读翻译好的文本，而不是破译原版天书，从根本上减少了Token消耗和错误率。
渐进式骨架遍历如何节省Token
无障碍树虽然信息丰富，但可能非常庞大，例如Slack的完整树可超过5万Token。agent-desktop采用渐进式骨架遍历，先返回浅层结构，再根据AI的请求定向展开特定子树，从而将Token消耗减少78%到96%。这种方法让AI只获取必要的上下文，避免了全量加载带来的浪费。
引用系统如何解决坐标失效问题
传统截图方案依赖坐标定位元素，但窗口移动或界面变化会导致坐标失效。agent-desktop为每个元素分配一个引用ID，基于元素在无障碍树中的身份而非坐标。即使界面变化，只要元素存在，引用仍能重新定位；若元素消失，则返回STALE_REF错误码，提示AI重新获取快照。
平台支持现状与未来
目前agent-desktop仅在macOS上完整可用，Windows和Linux的支持仍在规划中。尽管Windows有UIA、Linux有AT-SPI等现成的无障碍接口，但适配工作尚未完成。一旦跨平台支持落地，截图操控电脑的方式可能会被彻底取代，但具体时间表尚不明确。
Q&A
agent-desktop是什么？它如何帮助AI代理操作桌面应用？
agent-desktop是一个用Rust编写的桌面自动化CLI工具，通过操作系统的无障碍树为AI代理提供结构化界面访问，无需截图或像素匹配。它让AI代理能够直接读取界面元素的语义信息，如角色、名称、状态等，从而精确控制应用。
agent-desktop如何减少Token消耗？能减少多少？
agent-desktop采用渐进式骨架遍历技术，先返回浅层结构，再根据AI的需求定向展开特定区域，避免一次性加载完整无障碍树。对于密集型应用，可减少78%到96%的Token消耗。
agent-desktop的智能引用系统是如何工作的？它解决了什么问题？
智能引用系统为每个元素分配一个稳定的引用ID（如@s8f3k2p9:e1），绑定元素在无障碍树中的身份而非坐标。操作时，系统根据引用重新识别目标，即使界面发生变化也能正确定位。如果元素消失，返回STALE_REF错误码；如果多个元素匹配，返回AMBIGUOUS_TARGET，避免猜测。这解决了截图方案中坐标失效的问题。
agent-desktop支持哪些平台？目前哪些平台完整可用？
agent-desktop目前仅macOS完整可用，Windows和Linux的支持仍在规划中。Windows有UIA，Linux有AT-SPI，但适配层尚未实现。
agent-desktop如何处理Chromium应用（如Slack、VS Code）？
agent-desktop通过launch --cdp命令为Chromium应用打开Chrome DevTools Protocol端点，允许使用Playwright、Puppeteer等框架驱动Web内容，而原生部分仍通过无障碍树控制。这样各取所长，解决了Electron应用无障碍树又深又吵的问题。
agent-desktop为什么选择不依赖应用的返回码？它如何判断操作是否成功？
因为应用可能会返回错误的返回码（如Finder对成功操作返回错误码），agent-desktop选择观察界面状态变化来判断操作是否成功。它执行一系列有序的AXPress、AXOpen等步骤，只要界面状态发生变化，就认为操作成功。
agent-desktop的安装方式有哪些？它是否依赖运行时？
agent-desktop可以通过npm安装（npm install -g agent-desktop）或使用npx直接运行（npx agent-desktop snapshot --app Finder -i）。它是一个约15MB的单一二进制文件，无运行时依赖。
agent-desktop提供了哪些编程语言接口？
agent-desktop提供C-ABI动态库（libagent_desktop_ffi），可从Python、Swift、Go、Ruby、Node、C等语言加载调用，实现进程内调用，避免每次操作启动新进程，提高性能。
