vercel-labs/agent-desktop

项目介绍

Agent Desktop 给 AI 智能体提供操作真实桌面应用的能力，但不用像素匹配。一次 snapshot 返回应用的 JSON 无障碍树，每个可操作元素都带一个 ref。智能体对 ref 执行动作，再 snapshot 一次验证结果。控制循环留在智能体里；工具本身是用 Rust 写的 CLI 加 C 库，并为 macOS、Windows、Linux 提供语言绑定。

它适合需要可靠操作原生应用的智能体开发者和自动化工程师，尤其当坐标点击容易失准时。它不是视觉模型，也不是现成助手，而是智能体调用的观察与执行层。

快速使用

用 npm、Bun、Yarn 或 pnpm 安装 CLI，然后检查版本：

npm install -g agent-desktop
agent-desktop version

macOS 上先授予辅助功能权限：

agent-desktop permissions --guide

从 agent-desktop list-apps 里挑一个应用，然后跑「观察—操作—再观察」循环：

agent-desktop snapshot --app Finder -i      # 可交互元素，每个带 ref
agent-desktop click @s8f3k2p9:e8            # 对该快照中的 ref 执行动作
agent-desktop snapshot --app Finder -i      # 再次观察以验证

截取后的 snapshot 返回结果类似：

{
  "version": "2.5",
  "ok": true,
  "command": "snapshot",
  "data": {
    "app": "Finder",
    "window": { "id": "w-204749", "title": "Downloads" },
    "snapshot_id": "s8f3k2p9",
    "ref_count": 59,
    "complete": true,
    "tree": {
      "role": "window",
      "name": "Downloads",
      "children": [
        { "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }
      ]
    }
  }
}

要接进智能体，可以用 npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop 从 skills.sh 安装内置技能，或者在 AGENTS.md 里写明首次使用前先执行 agent-desktop skills get desktop 和 agent-desktop skills get platform。二进制自带与版本匹配的文档，可通过 agent-desktop skills get desktop、agent-desktop skills get platform 和 <command> --help 查看。

若不想经过 JavaScript 启动器，可从 GitHub Releases 下载对应平台的原生压缩包，并把辅助程序放在可执行文件旁边。

ref 与错误语义

ref 只属于生成它的那个快照。单独写 @e8 会被拒绝并返回 INVALID_ARGS。UI 变化后，动作会返回 STALE_REF 或 AMBIGUOUS_TARGET，智能体需要重新 snapshot。存在多个候选窗口时同样返回 AMBIGUOUS_TARGET，快照会在 error.details 里列出窗口 id，用 --window-id 指定其一。元素密集的应用先执行 snapshot --skeleton --app Slack -i --compact 得到整体结构，再用 snapshot --root @s8f3k2p9:e3 -i --compact 深入某个区域。

每条命令只打印一个 JSON 信封，包含 ok 以及 data 或 error 之一。错误带有 code、disposition，通常还有 suggestion；只有 error.disposition.retry 为 safe 时才重试。完整约定见 docs/json-output.md。ref 动作默认无头执行：走无障碍 API，不移动指针、不抢焦点。全局 --headed 标志启用物理输入。在 PowerShell 中每个 ref 都要加引号（'@s8f3k2p9:e8'），因为裸 @token 是 splatting 运算符。

平台要求

macOS 需要辅助功能权限。Windows 对与终端同级完整性级别的应用无需授权。Linux 需要用户图形会话并安装 at-spi2-core。

各平台能力不同：无障碍树和点击/输入/键盘在三个平台都支持。Linux 的鼠标输入仅限 X11 加 --headed。Linux 截图覆盖 X11 窗口和 Wayland portal；Wayland 剪贴板需要 wl-clipboard。Linux 的应用与窗口管理是启动/列出加 X11 窗口控制。Linux 通知依赖 GNOME Shell。macOS 的 shell surface 命令仍在计划中。分平台细节见平台说明，agent-desktop skills get platform 会打印当前机器的完整能力表。

隐私与数据处理

快照、剪贴板读取、截图、命令输出和调试产物可能含有私人桌面内容，不要放进公开日志或上传。可选的 JEV 辅助工具会把屏幕描述发送给配置的模型提供商，它独立于原生 CLI；项目在 FAQ 中说明了哪些数据可能含隐私信息。

HotRepo 点评

在 2026-11-01 的 Rust 月榜记录中，该仓库有 5,606 个 Star、416 个 Fork，当期新增 3,699 个 Star，最好名次为第 11。新增量相对总量很大，说明这一时段出现过集中关注，而非长期缓慢积累。技术上值得注意的是无障碍树这套思路：用稳定 ref 加上明确的 stale/ambiguous 错误码，让重试比坐标式自动化更可控，而这正是智能体构建者常碰到的失败点。榜单只代表当时的关注度，不能当作三平台生产可靠性的证据。