agent-desktop：用可访问性树驱动桌面应用
给 AI agent 操作桌面应用的 CLI，用可访问性树和 ref 替代像素匹配。
GitHub vercel-labs/agent-desktop 更新 2026-11-03 分支 main 星标 9.7K 分叉 657
Rust AI agents Accessibility API macOS/Windows/Linux

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你要让 AI agent 通过 Finder 或 Slack 的可访问性树执行点击、输入和验证。
    README 的 Quick start 使用 snapshot、click、snapshot 完成 observe-act-observe 循环；Dense apps 示例包含 Slack。
  • 你需要 macOS、Windows、Linux 三个平台的统一 CLI。
    README 的 Installation 写明 npm 可安装到 macOS、Windows 或 Linux；Platform support 表列出三个平台。
  • 你希望默认操作不移动鼠标或抢前台焦点。
    README 的 Quick start 写明 Headless by default，ref actions 通过 accessibility API 执行。
  • 你要在进程内集成，而不是每次启动 CLI。
    README 的 Language bindings 写明每个 release 提供 libagent_desktop_ffi，可在进程内调用。

不适合，如果你

  • 你的自动化依赖像素匹配，而目标应用不提供可用的 Accessibility tree。
    README 明确描述 agent-desktop 通过 OS accessibility tree 工作，并写明 no pixel matching。
  • 你在 Linux 上没有图形会话或 at-spi2-core。
    README Installation 写明 Linux needs the user's graphical session with at-spi2-core。
  • 你需要 Linux Wayland 下完整的系统窗口控制能力。
    README Platform support 表将 Linux 的 App & window management 标为 Launch/list; X11 window control，Wayland 仅在 Screenshot 行注明 portal。
  • 你不能接受桌面快照、剪贴板或调试产物包含私有内容。
    README 开头的隐私说明写明 snapshots、clipboard reads、screenshots、command output 和 debug artifacts 可能包含 private desktop content。

前置条件

  • 需要 Node.js 包安装路径：npm install -g agent-desktop；Requires the npm installation path: npm install -g agent-desktop.
  • macOS 需要 Accessibility permission；macOS requires Accessibility permission.
  • Linux 需要用户图形会话与 at-spi2-core；Linux requires the user's graphical session and at-spi2-core.
  • Linux Wayland 剪贴板需要 wl-clipboard；Linux Wayland clipboard requires wl-clipboard.
  • 平台原生二进制支持 x64 和 ARM64；Native binaries support x64 and ARM64.

第一步命令（README 原文）

npm install -g agent-desktop

要注意

  • 不要使用裸 @e8；ref 必须保留完整 snapshot id。
    README 写明裸 @e8 会被拒绝并返回 INVALID_ARGS，示例 ref 为 @s8f3k2p9:e8。
  • UI 变化后旧 ref 可能返回 STALE_REF。
    README Quick start 写明 UI changes 会返回 STALE_REF 或 AMBIGUOUS_TARGET，应重新 snapshot。
  • PowerShell 中必须引用 ref，否则 @token 会被当作 splatting operator。
    README 明确要求 PowerShell quote every ref，例如 '@s8f3k2p9:e8'。
  • 密集应用应先用 snapshot --skeleton，再用 --root 深入区域。
    README Dense apps 示例使用 snapshot --skeleton --app Slack -i --compact 和 snapshot --root。
  • 默认 headless 不代表可以执行物理输入；需使用全局 --headed。
    README 写明 ref actions 不移动指针或抢焦点，global --headed 才允许 physical input。

材料未说明

  • README 未说明支持的 Node.js 最低版本。
  • README 未给出不同桌面应用的兼容性清单或成功率。
  • README 未提供 snapshot、click 等命令的性能数据。
  • README 未说明 v1.0.2 相比前一版本的具体变更。
  • README 未说明 9 名贡献者和 10 个最近提交分别承担哪些维护工作。

💡 深度解析

6
不适合 我想把 agent-desktop 接入企业 Agent，并把 snapshot、截图和剪贴板结果上传给模型或写入公共日志；README 是否支持这种数据流？
适合读者： 需要把桌面快照、截图和剪贴板内容发送给 AI 模型或写入日志的企业内部工具团队

不适合按默认方式直接上传或公开记录：README 明确把这些输出视为可能包含私密桌面内容的数据。

  • README 开头直接警告 snapshots、clipboard reads、screenshots、command output 和 debug artifacts 可能包含 private desktop content，并要求不要放入 public logs and uploads。
  • 项目提供的可访问性 snapshot 可能包含窗口标题、控件名称和文本；clipboard 与 screenshot 则可能暴露更广泛的用户内容。项目没有承诺自动脱敏。
  • 可选的 JEV helper 会把屏幕描述发送给配置的模型提供商，而且它与 native CLI 分离；这意味着企业必须单独审查该数据通道。
  • 因此，若需求是无条件上传完整桌面上下文，项目与该约束冲突；README 未提供脱敏、保留期限、访问控制或合规策略，不能把这些能力视为内置保证。
  • README 开头：Snapshots, clipboard reads, screenshots, command output and debug artifacts can contain private desktop content
  • README 开头：Keep them out of public logs and uploads
  • README 开头：The optional JEV helper sends screen descriptions to a configured model provider
  • 项目洞察「usage_limitations」：快照、截图、剪贴板和调试产物存在数据泄露风险
材料未说明：README 未说明是否提供内置字段级脱敏、内容过滤或日志访问控制。；README 未说明 JEV helper 的数据保留期限、区域和模型提供商合规认证。
适合 我需要让 Agent 操作 macOS Finder，并在 Slack 这类控件密集的应用中避免因为窗口变化或同名控件而点击错误目标；snapshot 和 ref 是否足够？
适合读者： 在 macOS Finder 和 Slack 等原生应用上实现观察—操作—验证循环的 AI Agent 开发者

适合：项目把目标绑定到 snapshot，并把过期引用和窗口歧义变成可处理的错误，而不是静默点击。

  • Quick start 展示了 snapshot --app Finder -i、按 ref 点击、再次 snapshot 验证的闭环。
  • README 规定裸 @e8 会返回 INVALID_ARGS；界面变化会返回 STALE_REF 或 AMBIGUOUS_TARGET，要求重新获取 snapshot。
  • 多窗口时可从错误详情取得候选 window id，再通过 --window-id 缩小范围。
  • Slack 等密集应用可先使用 skeleton 和 compact，再以 --root 深入局部区域，减少 Agent 一次处理过大的 UI 树。不过，项目仍依赖应用正确暴露 Accessibility tree，动态或自绘控件并不会自动变得可定位。
  • README「Quick start」：Observe, act on a ref, observe again
  • README「Quick start」：Refs belong to their snapshot；STALE_REF 或 AMBIGUOUS_TARGET
  • README「Quick start」：Several windows give AMBIGUOUS_TARGET；Pass one with --window-id
  • README「Quick start」：Dense apps 使用 snapshot --skeleton --app Slack -i --compact 和 --root
agent-desktop snapshot --app Finder -i      # interactive elements, each with a ref
材料未说明：README 未说明 Finder 或 Slack 的所有控件是否都暴露完整 role、name 和 available_actions。；README 未说明具体动态页面在异步加载期间产生 STALE_REF 的频率。
适合 我在 Windows 上用 PowerShell 控制多个原生应用窗口，并希望 Agent 能根据错误码安全决定是否重试；agent-desktop 是否比坐标脚本更合适？
适合读者： 使用 PowerShell 编排 Windows 原生应用、需要处理多个窗口和 JSON 错误状态的自动化工程师

适合：Windows 的 Accessibility tree、窗口筛选和统一 JSON 错误契约正好对应这些约束。

  • Platform support 将 Windows 的 Accessibility tree、click/type/keyboard、鼠标、剪贴板及应用窗口管理均列为支持项；Windows 在终端完整性级别下不需要额外授权。
  • 多窗口时，README 规定会返回 AMBIGUOUS_TARGET，并要求使用错误详情中的候选 id 配合 --window-id，比固定坐标更能表达目标上下文。
  • 每条命令都输出 ok 以及 data 或 error；error 包含 code、disposition 和 suggestion，只有 error.disposition.retry 为 safe 时才应自动重试。
  • PowerShell 需要给每个 ref 加引号，因为裸 @token 会被解释为 splatting。这样可以把窗口选择、ref 生命周期和重试逻辑纳入脚本，而不是依赖像素位置。
  • README「Platform support」：Windows 的 Accessibility tree、Click / type / keyboard、Mouse input、Clipboard、App & window management 均为 Yes
  • README「Installation」：Windows needs no grant for apps at your terminal's integrity level
  • README「For AI agents」：error carries code、disposition、suggestion；retry only when retry is safe
  • README「Quick start」：PowerShell 中 quote every ref；多窗口使用 --window-id
材料未说明：README 未说明目标 Windows 应用在不同完整性级别之间的控制限制。；README 未提供与坐标脚本相比的错误率或执行速度数据。
视情况 我需要在 Linux GNOME 环境中让 Agent 操作应用、读取剪贴板并处理通知；我的环境可能使用 Wayland，agent-desktop 是否适合直接部署？
适合读者： 在 Linux GNOME 工作站上部署桌面 Agent、同时需要 AT-SPI、X11/Wayland、通知和剪贴板能力的自动化开发者

视情况：如果运行在真实的 Linux 图形会话并满足 AT-SPI、桌面协议和 GNOME 条件，它可以覆盖主要能力，但不能按“Linux 支持”推断所有功能一致。

  • Installation 要求 Linux 具备用户图形会话和 at-spi2-core，所以无桌面的通用服务器不是 README 直接支持的部署形态。
  • Platform support 表明 Accessibility tree、应用启动/列表和通知可用，但鼠标输入标为 X11，截图区分 X11 windows 与 Wayland portal。
  • Wayland 剪贴板需要 wl-clipboard；通知能力列为 GNOME Shell，shell surface 也只列出 GNOME tray、Action Center 等平台差异。
  • 若流程主要依赖语义快照、点击、输入和 GNOME 通知，适配度较好；若依赖 Wayland 下的物理鼠标或统一系统面板，README 证据不足。
  • README「Installation」：Linux needs the user's graphical session with at-spi2-core
  • README「Platform support」：Mouse input: X11, --headed；Screenshot: X11 windows, Wayland portal
  • README「Platform support」：Clipboard 在 Wayland 需要 wl-clipboard；Notifications 为 GNOME Shell
  • README「Platform support」：Linux shell surfaces 为 GNOME tray、Action Center
agent-desktop skills get platform     # what differs on the OS you run on
材料未说明：README 未说明具体 GNOME 版本、Wayland compositor 和发行版组合的支持范围。；README 未说明在无显示器、远程桌面或虚拟显示环境中的可用性。
视情况 我正在用 Rust 构建一个需要同时控制 macOS、Windows 和 Linux 原生应用的 AI Agent；我能否用 agent-desktop 替代三套平台专用的鼠标键盘脚本？
适合读者： 正在构建计算机使用型 AI Agent、希望在 macOS、Windows 和 Linux 上复用同一套桌面控制接口的开发者

视情况：它提供统一 CLI、JSON 和 C library，但三个平台的能力并不完全相同。

  • README 明确支持 macOS、Windows 和 Linux，并通过 Accessibility API 或 Linux AT-SPI 返回结构化快照；ref 操作不依赖像素匹配。
  • macOS 需要 Accessibility 权限；Linux 需要用户图形会话和 at-spi2-core，鼠标输入依赖 X11，Wayland 的截图和剪贴板也有额外条件。
  • Shell surfaces 在 macOS 仍是 Planned，Linux 的窗口、通知和物理输入能力也按 X11、Wayland、GNOME 分开列出。
  • 因此，跨平台的观察、语义点击和文本输入较适合统一抽象；涉及系统面板、物理鼠标或 Linux 桌面环境的流程，不能假定行为一致。
  • README「Platform support」：macOS、Windows、Linux 均支持 Accessibility tree
  • README「Installation」：macOS needs Accessibility permission；Linux needs the user's graphical session with at-spi2-core
  • README「Platform support」：Shell surfaces（open-system-surface）在 macOS 为 Planned
  • README「Quick start」：Headless by default；ref actions go through the accessibility API
npm install -g agent-desktop
材料未说明：README 未给出你的具体目标应用在三个操作系统上的 Accessibility tree 完整度。；README 未给出同一工作流在 macOS、Windows 和不同 Linux 桌面环境中的兼容性矩阵。
视情况 我的 Agent 核心也是 Rust，而且会高频执行 click、type、find 等操作；由于 README 说每次 CLI 调用都是独立进程，我是否应该直接接入 C FFI？
适合读者： 需要把桌面控制嵌入现有 Rust Agent、并减少每次 CLI 调用独立启动进程开销的开发者

视情况：高频或低延迟场景值得评估 C FFI，但它不是无需额外工程约束的 CLI 替代品。

  • README 明确指出每次 CLI 调用运行在独立进程中；这有利于隔离，却可能增加进程启动和 JSON 序列化成本。
  • 项目同时提供 C library，适合进程内调用；项目洞察还指出 FFI 有 ABI 版本、内存所有权和线程规则。
  • CLI 输出统一为带 ok、data 或 error 的 JSON envelope，适合先快速验证 Agent 循环；FFI 则需要处理更严格的生命周期和 ABI 兼容问题。
  • 因此，Rust Agent 若仍在验证工作流，CLI 接入更直接；当调用频率和延迟成为明确瓶颈时，再根据 README 未提供的 FFI 性能数据决定是否迁移。
  • README 开头：Every CLI call runs in its own process
  • README「Language bindings」（项目洞察）：提供 C FFI library
  • README「For AI agents」：Every command prints one envelope with ok and either data or error
  • 项目洞察「usage_limitations」：FFI 集成需要遵守 ABI 主版本、内存所有权和线程规则
agent-desktop skills get desktop      # the loop, refs, verification and retry rules
材料未说明：README 未提供 CLI 与 C FFI 的延迟、吞吐或进程启动基准。；README 未说明 Rust 直接绑定 C FFI 时是否有官方 Rust wrapper。

✨ 核心亮点

  • snapshot 返回带 ref 的 JSON 可访问性树
  • headless ref 操作默认不抢焦点
  • 覆盖 macOS、Windows 与 Linux
  • 提供 60 个命令和 C FFI
  • macOS 需要 Accessibility 权限

🔧 工程化

  • 用 snapshot、click 和 JSON ref 读写桌面应用
  • CLI 每次调用独立进程，支持 60 个命令
  • libagent_desktop_ffi 可在进程内调用工具

⚠️ 风险

  • UI 变化会导致 STALE_REF，必须重新 snapshot
  • 多窗口会返回 AMBIGUOUS_TARGET，需指定 --window-id
  • Linux 需要图形会话与 at-spi2-core
  • snapshot 和截图可能包含私有桌面内容

👥 适合谁？

  • 需要让 AI agent 操作 Finder 或 Slack 的团队
  • 使用 macOS、Windows 或 Linux 桌面自动化的开发者
  • 需要 Rust CLI 或 libagent_desktop_ffi 的集成者