vercel-labs/agent-desktop 用系统无障碍树给 Agent 读取和操作桌面,不靠截图像素(@SimonObserves 的实测笔记)
Agent 操控电脑常见两条路:看截图像素,或读屏幕阅读器已经在用的无障碍树。Vercel Labs 开源 agent-desktop(Apache-2.0,npm 1.2.0):CLI/C 库,不含模型;`snapshot` 给出带 @ref 的 JSON,再 `click`/`type`,默认 headless 不抢焦点。海外作者 @SimonObserves 写了 Linux 实测:无 AT-SPI 时几乎全拒,装上后能列窗、点菜单,终端输入需 `--headed`。我们在无桌面会话的 Linux 盒子上 `npm install -g agent-desktop`:`version` 报 1.2.0;`status` 里 accessibility=denied(无 D-Bus session),supported_surfaces=[]——与笔记一致。未接 Claude/Codex MCP 真控桌面。
访问官网 agent-desktop (vercel-labs) ↗- 定价
- 免费
- 地区
- 海外
- 出自哪里
- 海外社区
- 上架日期
- 2026 年 11 月 6 日
- 实测日期
- 2026 年 11 月 6 日
- 用的版本
- agent-desktop npm 1.2.0; protocol envelope version 2.6; repo HEAD b43ac4f
- 我们实测
- 部分实测
- 成本 / 耗时
- 开源免费(Apache-2.0)。驱动 Agent 另需 Claude Code / Codex 等订阅;Linux 可能要装 at-spi2-core 等桌面无障碍组件。
要解决的事
让编码 Agent 在本机真实桌面应用里点按钮、填表、读控件状态,而不是只靠截图坐标猜。
步骤
- 安装:`npm install -g agent-desktop`(Node ≥18,含各平台原生二进制),或 `brew install agent-desktop`。先跑 `agent-desktop version` 与 `agent-desktop status`。
- 授权:macOS 用 `agent-desktop permissions --guide` 开辅助功能;Linux 需要可用的 AT-SPI / D-Bus 桌面会话——云主机或纯 SSH 无会话时 status 会显示 accessibility denied。
- 给 Agent 读内置技能:`agent-desktop skills get desktop` 与 `agent-desktop skills get platform`(技能编进二进制,与版本绑定)。也可 `npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop`。
- 基本环:`agent-desktop snapshot --app "AppName" -i` → 对返回的 `@snapshot:ref` 执行 `click` / `type` → 再 snapshot 校验。UI 变了旧 ref 会 STALE_REF,需重拍。
- 终端等不支持语义输入的控件,headless 的 `type` 可能 POLICY_DENIED;显式加 `--headed` 才允许物理键鼠。截图/剪贴板可能含隐私,别公开上传。
提示词
用 agent-desktop 操作本机应用:先 status 确认无障碍可用,再对目标应用做 snapshot -i,只对当前 snapshot 的 ref 点击或输入,每次动作后重新 snapshot 校验;不要猜测屏幕坐标。
原文怎么说
@SimonObserves / vercel-labs:两条 computer-use 路径里,agent-desktop 走无障碍树;无模型,只做手和眼。Linux 上缺 AT-SPI 几乎不能用;装好后可列应用/窗口、点菜单;终端输入默认 headless 会被拒,需 --headed。失败返回带原因的 JSON(如 STALE_REF、POLICY_DENIED),宁可报错也不假截图。
我们实测
npm install -g [email protected];执行 version、status、--help。阅读 vercel-labs/agent-desktop README 与 @SimonObserves 长文。未安装 AT-SPI、未启动桌面会话、未对真实 GUI 做 snapshot/click,未接 MCP。
我们亲自试下来:version:ok,os=linux,target=x86_64,version=1.2.0。status:permissions.accessibility.state=denied,suggestion 提示无 D-Bus session bus;supported_surfaces=[]。与作者 Linux 笔记中「先过权限墙」一致。
怎么用上
npm / Homebrew / GitHub Releases;需本机桌面与无障碍权限。国内 npm 可能需镜像。原实测笔记英文,仓库文档英文。
适合谁
要让 Agent 操作本地 GUI(设置、IDE、办公软件)且应用暴露良好无障碍信息的人;云端无桌面环境不适合。
踩坑提示
- 无桌面会话 / 无 AT-SPI 时 status 会 denied,list/snapshot 基本不可用——先解决本机无障碍,再怪工具。
- 游戏、自绘控件、远程桌面画面常常没有可用树;工具只能操作暴露了 a11y 的程序。
- ref 绑定单次 snapshot;界面一变必须重拍,否则 STALE_REF。
- 我们实测:npm 全局装到 1.2.0,version 正常;本盒子无 D-Bus session,status=denied。未做真桌面点击。
同类用例
- 文档每页配演示视频,界面一改就报红视频创作ScreenplayClaude Code工具免费;需 Claude 等 agent 额度◐ 部分实测海外
- 让 AI 写后端时默认防并发、越权和改表事故编程开发backendskillsClaude CodePostgreSQL免费;每次任务多花约一倍额度◐ 部分实测海外
- 一个下午让 AI 做出能在浏览器里玩的 3D 动作游戏编程开发Claude CodeTripo即梦技能免费;需 Claude 额度,素材工具另计◐ 部分实测国内
- 长期让 AI 写同一个项目,仓库也不乱编程开发ClaudeCodexoil-delegate需 Claude 和 Codex 订阅◐ 部分实测国内
- 边用一个网页产品,边让 AI 写出它的工作原理调研搜索REAClaude CodeChrome工具免费;需 Claude 或 Codex◐ 部分实测海外