agent-desktop#

面向 AI 智能体的计算机使用（Computer use）：通过操作系统无障碍树（accessibility tree）读取和操作桌面应用。

一款适用于 macOS、Windows 和 Linux 的 CLI 和 C 库。一次快照会返回 JSON，其中为智能体可以操作的每个元素提供一个引用（ref）。智能体对某个 ref 执行操作，然后再次快照以检查结果，全程无需像素匹配；循环留在你的智能体内部。

每次 CLI 调用都在自己的进程中运行。无头（headless）调用仍然禁止前台激活和合成输入。

快照、剪贴板读取、截图、命令输出和调试产物可能包含私人桌面内容。请让它们远离公开日志和上传。可选的 JEV 助手会将屏幕描述发送到配置的模型提供商；它与原生 CLI 是分开的。请参阅隐私和数据处理。

安装#

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

npm install -g agent-desktop
agent-desktop version

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

若要在没有 JavaScript 启动器的情况下直接执行，请从 GitHub Releases 下载匹配的原生归档，并将它的辅助程序放在可执行文件旁边。

官方 Homebrew 和 Scoop 软件包正在提交中；它们尚未在默认目录中提供。该仓库不再维护自定义的 Homebrew tap 或 Scoop bucket。

macOS 需要辅助功能（Accessibility）权限：agent-desktop permissions --guide。

Windows 对于与终端完整性级别相同的应用无需授权。

Linux 需要用户的图形会话以及 at-spi2-core。

有关包管理器行为、发布归档和从源码构建，请参阅安装与权限。

快速开始#

观察、对 ref 执行操作、再次观察。agent-desktop list-apps 中的任何应用名称都可以使用；Finder 是 macOS 示例。每条命令打印一个 JSON 信封（envelope）；命令之后是一个精简的快照。

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

{
  "version": "2.6",
  "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"] }
      ]
    }
  }
}

Refs 属于其快照。裸的 @e8 会被拒绝并返回 INVALID_ARGS。当 UI 发生变化时，操作会返回 STALE_REF 或 AMBIGUOUS_TARGET：请拍摄新快照并使用其中的 refs。

出现多个窗口时会返回 AMBIGUOUS_TARGET；快照会在 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 是展开运算符（splatting operator）。

面向 AI 智能体#

该二进制文件携带自己的文档，并与其版本匹配：

agent-desktop skills get desktop # 循环、refs、验证和重试规则
agent-desktop skills get platform # 你所运行的操作系统有何不同
agent-desktop <command> --help # 单条命令的标志

从 skills.sh 将技能安装到智能体框架中：

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 安全时才重试。契约、错误码和退出码见 docs/json-output.md。

命令#

它提供 60 个命令名称，其中 56 个是可操作命令。另外四个（key-down、key-up、mouse-down、mouse-up）在守护进程能够释放被按住的键或按钮之前拒绝运行。

平台支持#

Windows 表面和启动说明，以及 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(7) == 0 # 当头文件中的 AD_ABI_VERSION_MAJOR 与库匹配时返回 AD_RESULT_OK
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 列出了每一道关卡。从源码构建：docs/install.md。

文档#

许可证#

Apache-2.0