AI 分析 · 由大模型根据 README 与仓库数据生成 · 2026年11月17日
让 AI 代理通过系统无障碍树读取并操作桌面应用的命令行工具。
agent-desktop 是 Vercel Labs 出品的计算机使用(computer use)CLI,用 Rust 编写,支持 macOS、Windows 和 Linux。它不依赖截图或像素匹配,而是读取桌面应用的无障碍树并输出 JSON,为每个可操作元素附带 ref,代理按 ref 点击或输入,再重新读取界面验证结果。项目以 CLI 和 C 库形式发布,内部不含模型,操作循环由调用方代理实现。
推荐指数
思路清晰、跨平台且对代理友好,适合需要稳定操作桌面应用的自动化场景。
近 7 天
+3,574
新增 Star
总 Star 排名
#288
雷达追踪的 3,931 个 AI 仓库中
创建于
2026
2026年2月20日
核心亮点
1不靠截图
直接读取操作系统无障碍树,避免像素匹配带来的不稳定。
2ref 定位元素
快照为每个可操作元素生成 ref,点击和输入都基于 ref 执行。
3跨三平台
分别对接 macOS AX、Windows UI Automation 和 Linux AT-SPI。
4默认无头
ref 操作走无障碍 API,不移动指针、不抢焦点,可选用 --headed。
5自带代理指南
内置 skills 命令和 MCP 服务,方便接入代理框架。
适用场景
桌面应用自动化测试
例如:用 snapshot 读取 Finder 窗口,按 ref 点击 Documents 目录并再次快照验证。
AI 代理操作桌面软件
例如:代理通过 MCP 调用 desktop_snapshot 和 desktop_click 完成文件整理任务。
跨平台桌面流程脚本
例如:在 macOS 和 Windows 上用同一套命令操作应用界面。
它是怎么工作的
第 1 步
读取界面
调用 snapshot 获取目标应用的无障碍树 JSON,每个元素带 ref。
第 2 步
执行动作
用 click、type 等命令对指定 ref 操作,默认不移动真实指针。
第 3 步
验证结果
再次 snapshot 观察界面变化,确认动作是否生效。
第 4 步
处理异常
遇到 STALE_REF 或 AMBIGUOUS_TARGET 时重新快照或指定窗口。
快速上手
- 1
安装
通过 npm 全局安装,包含各平台原生二进制。
npm install -g agent-desktop - 2
检查环境
查看平台、权限和可用界面。
agent-desktop status - 3
获取快照
读取 Finder 的可交互元素及 ref。
agent-desktop snapshot --app Finder -i - 4
执行点击
对快照中的 ref 执行点击。
agent-desktop click @s8f3k2p9:e8
适合谁
- 构建桌面操作代理的开发者
- 需要跨平台桌面自动化的团队
- 希望用结构化数据替代截图的自动化工程师
不太适合
- 只想做网页自动化的用户
- 不愿配置系统无障碍权限的人
成熟度
- 活跃度创建于 2026 年 2 月,最近一次推送在 2026 年 11 月,star 约 2.4 万。
- 文档README 覆盖安装、快照、ref 规则、MCP 和代理指南,细节较全。
- 社区fork 约 1800,开放 issue 258 个,有一定讨论量。
- 上手难度需安装原生二进制并授予系统无障碍权限,ref 和窗口规则需要理解。
使用前注意
- · macOS 需手动授予辅助功能权限,否则无法读取界面。
- · 快照、剪贴板和截图可能包含隐私内容,不要上传到公开日志。
- · ref 与快照绑定,界面变化后需重新快照,否则返回 STALE_REF。
- · 项目采用 Apache-2.0 许可,使用前确认与自身分发方式兼容。
