vercel-labs/agent-desktop

来源：https://github.com/vercel-labs/agent-desktop

agent-desktop

AI 智能体的 Computer use 能力：通过操作系统的无障碍（accessibility）树读取并操作桌面应用。提供适用于 macOS、Windows 和 Linux 的 CLI 与 C 库。

一次快照（snapshot）会返回 JSON，其中每个智能体可操作的元素都带有一个 ref。智能体对 ref 执行操作，然后再次快照进行验证，全程无需像素匹配；循环逻辑保留在你自己的智能体中。

在 macOS 上，CLI 调用会在每个快照命名空间和二进制构建中复用一个私有的命令宿主（command host）。它保留原生无障碍对象，因此被移除的行不会悄悄地解析到具有相同标识符的存活行上。宿主在空闲 15 分钟后退出。TMPDIR 必须由当前用户所有且权限为 0700；macOS 标准的按用户临时目录即满足此要求。无头（headless）调用仍然禁止前台激活和合成输入。

快照、剪贴板读取、截图、命令输出和调试产物都可能包含私密的桌面内容。请勿将它们写入公开日志或上传。

可选的 JEV helper 会将屏幕描述发送到已配置的模型提供商，它与原生 CLI 相互独立。参见隐私与数据处理。

安装

在 macOS、Windows 或 Linux 上使用 npm 安装：

npm install -g agent-desktop
agent-desktop version

Bun、Yarn 和 pnpm 也可以安装同一个包。该包包含适用于 x64 和 ARM64 的原生二进制文件和平台辅助程序。

如需不依赖 JavaScript 启动器直接执行，请从 GitHub Releases（https://github.com/vercel-labs/agent-desktop/releases）下载对应的原生存档，并将其辅助程序放在可执行文件旁边。

官方的 Homebrew 和 Scoop 软件包正在提交中，尚未进入默认仓库。该仓库不再维护自定义的 Homebrew tap 或 Scoop bucket。

• macOS 需要辅助功能（Accessibility）权限：agent-desktop permissions --guide。
• Windows 对于与你的终端完整性级别相同的应用无需额外授权。
• Linux 需要用户的图形会话以及 at-spi2-core。

参见安装与权限了解软件包管理器行为、发布归档以及从源码构建的说明。

快速开始

观察、对 ref 执行操作、再次观察。agent-desktop list-apps 返回的任何应用名都可以使用；下面以 macOS 的 Finder 为例。每条命令都会打印一个 JSON 信封（envelope）；命令后面附有一个精简后的快照。

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

{
  "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"]
        }
      ]
    }
  }
}

• Ref 属于其所在的快照。 单独的 @e8 会被拒绝并返回 INVALID_ARGS。当 UI 发生变化时，操作会返回 STALE_REF 或 AMBIGUOUS_TARGET：请获取新快照并使用其中的 ref。
• 多个窗口会导致 AMBIGUOUS_TARGET；snapshot 会在 error.details 中列出候选窗口 id。用 --window-id 传入其中一个。
• 元素密集的应用： 先用 snapshot --skeleton --app Slack -i --compact 绘制全局地图，再用 snapshot --root @s8f3k2p9:e3 -i --compact 深入某个区域。
• 默认无头模式。 Ref 操作通过无障碍 API 执行，不会移动指针或抢占焦点。全局 --headed 标志允许物理输入。
• PowerShell。 每个 ref 都要用引号包起来（'@s8f3k2p9:e8'），因为裸的 @token 是 PowerShell 的 splatting 运算符。

面向 AI 智能体

二进制文件自带与版本匹配的文档：

agent-desktop skills get desktop    # 循环、ref、验证与重试规则
agent-desktop skills get platform   # 你所运行操作系统的差异说明
agent-desktop --help                # 单条命令的标志说明

从 skills.sh（https://skills.sh/vercel-labs/agent-desktop/agent-desktop）将该 skill 安装到智能体框架中：

npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

或者将以下内容添加到你的 AGENTS.md：

Use `agent-desktop` to see and operate desktop apps. Before the first use, run `agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.

每条命令都会打印一个信封，包含 ok 字段以及 data 或 error。错误中带有 code、disposition，通常还有 suggestion；仅当 error.disposition.retry 为 safe 时才重试。

契约、错误码和退出码见 docs/json-output.md。

命令

该工具包含 60 个命令名，其中 56 个为可操作命令。另外四个（key-down、key-up、mouse-down、mouse-up）在守护进程能够释放按住的按键或鼠标按钮之前拒绝执行。

平台支持

Windows 的 surface 和 launch 说明，以及 Linux 的 X11 和 Wayland 说明见 docs/install.md。agent-desktop skills get platform 会打印你所运行操作系统的完整能力表。

语言绑定

每个版本还为 macOS、Linux 和 Windows 提供 libagent_desktop_ffi，这样程序可以在进程内直接调用该工具，而无需为每条命令启动 CLI。agent-desktop skills get ffi 涵盖入口点、内存所有权和线程规则。

import ctypes

lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
lib.ad_adapter_create.restype = ctypes.c_void_p
lib.ad_adapter_destroy.argtypes = [ctypes.c_void_p]

assert lib.ad_init(6) == 0  # AD_RESULT_OK，前提是头文件的 AD_ABI_VERSION_MAJOR 与库匹配

adapter = lib.ad_adapter_create()
lib.ad_adapter_destroy(adapter)

开发

每个平台适配器只能在其对应的操作系统上构建，因此请将 cargo 的作用域限定到宿主平台的包。在 macOS 上：

HOST_PKGS=(-p agent-desktop-core -p agent-desktop-macos -p agent-desktop -p agent-desktop-ffi)
cargo test "${HOST_PKGS[@]}"
cargo clippy "${HOST_PKGS[@]}" --all-targets -- -D warnings

在 Windows 上，将该列表中的 agent-desktop-macos 替换为 agent-desktop-windows；在 Linux 上，替换为 agent-desktop-linux。

CONTRIBUTING.md 列出了所有关卡（gate）。从源码构建见 docs/install.md。

文档

许可证

Apache-2.0