Vercel 开源跨平台智能体桌面操作工具

vercel-labs/agent-desktop 想让 AI 操作桌面应用时，少依赖截图找坐标，多利用操作系统提供的控件信息。它把应用界面读成带引用标识的 JSON，供 agent 选择目标、执行动作，再重新观察结果。

这套方案值得程序员关注的地方，是把桌面操作变成了可检查的工具调用。但它没有包办任务规划，也没有证明自己能适配所有应用。理解它的接口约束，比记住几个点击命令更有用。

不靠像素匹配，agent 怎么找到按钮

agent-desktop 提供跨 macOS、Windows、Linux 的 CLI 和 C 库，主要通过操作系统的无障碍树（accessibility tree）读取和操作应用。可以把它理解成一份界面结构：有哪些窗口、控件叫什么、支持什么动作。

快照会为可操作元素生成 ref。原文示例返回的 JSON 包含 "version": "2.6"、snapshot_id、ref_count: 59 和 complete: true；一个名为 Documents 的节点，角色是 treeitem，可执行动作是 Click。

下面三条命令展示了完整闭环：先观察，再操作，最后验证。

agent-desktop snapshot --app Finder -i      # 读取交互元素，每个元素都有 ref
agent-desktop click @s8f3k2p9:e8            # 使用这次快照中的 ref 操作
agent-desktop snapshot --app Finder -i      # 再次观察以验证结果

要留意第二行：@s8f3k2p9:e8 同时携带快照和元素标识。单独传 @e8 会得到 INVALID_ARGS。

ref 是一次观察的产物，不能当成永久有效的控件 ID。

界面变化后，动作可能返回 STALE_REF 或 AMBIGUOUS_TARGET，此时应重新获取快照。若应用存在多个候选窗口，错误的 error.details 会列出窗口 ID，需要用 --window-id 指定目标。

复杂应用还可以分层读取。先运行 snapshot --skeleton --app Slack -i --compact 看结构，再用 snapshot --root @s8f3k2p9:e3 -i --compact 深入某一区域，避免每次都把整棵树交给模型。

默认不抢焦点，但环境条件不能省

默认 headless 模式下，ref 动作通过无障碍 API 执行，不移动鼠标，也不抢焦点。前台激活和合成输入仍然被禁止；全局参数 --headed 才允许物理输入。

这里的 headless 不代表可以脱离桌面环境运行。macOS 需要通过 agent-desktop permissions --guide 配置 Accessibility 权限；Windows 对与终端处于相同完整性级别的应用无需额外授权；Linux 则需要用户图形会话和 at-spi2-core。

安装入口是 npm install -g agent-desktop，随后用 agent-desktop version 检查。Bun、Yarn、pnpm 也能安装同一个包，包内包含 x64、ARM64 原生二进制和平台辅助程序。直接使用原生发布包时，辅助程序必须放在可执行文件旁边。

原文还明确说明，官方 Homebrew、Scoop 包正在提交，默认目录尚不可用，仓库也不再维护自定义 tap 或 bucket。

隐私边界同样具体：快照、剪贴板、截图、命令输出、调试文件都可能含有桌面私密内容，不应进入公开日志或上传。可选的 JEV helper 会向配置的模型提供方发送屏幕描述，它与原生 CLI 分开。

接入 agent，关键是错误处理和执行边界

每次 CLI 调用都会启动独立进程，每条命令输出一个 JSON envelope，包含 ok，以及 data 或 error。错误通常带有 code、disposition 和 suggestion。

只有 error.disposition.retry 表明安全时，才应重试。

这比笼统的「失败就再点一次」更适合自动化。任务规划、观察、验证和重试仍由调用方的 agent 负责。完整输出契约、错误码、退出码位于 docs/json-output.md。

工具内置与二进制版本匹配的文档：首次使用先读 agent-desktop skills get desktop 和 agent-desktop skills get platform，具体参数查 agent-desktop <command> --help。也可以通过 skills.sh 安装技能，或把首次读取文档的要求加入 AGENTS.md。

它提供 60 个命令名，其中 56 个可操作。key-down、key-up、mouse-down、mouse-up 暂时拒绝执行，原因是还缺少能释放持续按键或鼠标按钮的 daemon。PowerShell 下，每个 ref 都要加引号，例如 '@s8f3k2p9:e8'，否则 @token 会被解释为 splatting 操作符。

如果需要进程内调用，各平台发布包还提供 libagent_desktop_ffi。下面是原文的 Python 初始化示例：

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)

重点是 ad_init(7) 的 ABI 匹配检查。正式接入还要通过 agent-desktop skills get ffi 阅读入口、内存所有权和线程规则，不能只复制初始化代码。

我的判断

这个项目最有价值的设计，是让操作目标、观察结果和错误处理都有明确结构。相比依赖坐标的脚本，它给 agent 提供了控件角色、名称和动作；相比只返回自然语言的工具，也更方便程序检查结果。

但原文没有提供成功率、耗时、模型成本，也没有与截图方案做对照。它说明了机制，没有证明普遍更快、更准。

一般团队还要验证目标应用的无障碍信息是否完整、控件动作能否覆盖任务，以及各系统的能力差异。跨平台有安装包，不等于每个平台的操作能力完全一致。对于已经有稳定 API 的任务，我会优先考虑直接调用 API；需要操作现有桌面界面时，再评估这条路径。

能拿来做什么

• 给日常 AI 编程 agent 增加桌面工具时，先用 agent-desktop list-apps 确认应用，再实现「快照、动作、复查」闭环。
• 在 Node 编排层解析 JSON 输出，分别处理过期 ref、多窗口歧义和安全重试，避免把所有错误都交给模型猜。
• 面对 Slack 等密集界面，先获取骨架，再读取局部区域，并检查日志是否保留了私密桌面内容。
• 需要源码集成时，只构建宿主系统对应的 adapter，并先验证实际任务，再决定采用独立 CLI 进程还是 FFI。