让 Agent 看懂桌面而不是猜像素。agent-desktop 是 Rust 编写的原生桌面自动化 CLI:通过操作系统无障碍树读取任意应用的真实 UI 结构,元素引用稳定、动作可安全重试,替代脆弱的截图加坐标点击;渐进式骨架遍历大幅压缩 Token 消耗,结构化 JSON 输出带错误码与恢复提示,另经 CDP 与 Chromium 应用互通。单二进制、无运行时依赖,Apache 2.0 开源。最新版 v1.3.1(2026-11-13,GitHub 标记 Latest):小补丁——rustix 升到 1.1.6 修复 RUSTSEC-2026-0486;修已启动沙箱在启动器退出后保持运行。前一版 v1.3.0 新增 sandbox 命令与 macOS VM 沙箱、进程清单改用 libproc。(详见下方「版本记录」) 定价:免费开源(Apache 2.0)。编辑评分:⭐ 4.5。
agent-desktop 是什么?
agent-desktop 是一个用 Rust 编写的原生桌面自动化 CLI,专为 AI Agent 打造,Apache 2.0 协议开源。它要解决的是 Computer Use 领域的老大难问题:绝大多数桌面 Agent 靠「截图—视觉模型—预测坐标—点击」循环工作,慢、贵、脆,界面挪动几个像素整条链路就断。
它的答案朴素而有力:不猜像素,读操作系统自己维护的无障碍树(accessibility tree)。这套语义结构——每个元素的角色、名称、可用动作、层级、焦点与状态——正是屏幕阅读器几十年来依赖的数据源,Finder、Safari、系统设置、Xcode、Slack 等任何有辅助功能实现的应用都在其中。Agent 拿到的是结构化快照与确定的元素引用(如 @s8f3k2p9:e1),动作前引用会重新解析,界面变了就返回 STALE_REF 错误而不是误点别处。工程形态上它是约 15MB 的单一二进制、无运行时依赖,npm install -g agent-desktop 即装即用,也可从源码构建;另提供 C-ABI 动态库,Python、Swift、Go、Ruby、Node 都能一次加载复用,不必每个调用都 fork 一次 CLI。社区把它类比作「桌面的 Playwright」——为原生应用补上浏览器自动化早就有的选择器与动作模型。
核心功能
- 无障碍树观察与操作:58 个命令名覆盖观察、交互、键盘、鼠标、通知、剪贴板、窗口管理与会话生命周期,输出全部为带错误码与恢复提示的结构化 JSON。
- 稳定引用与安全重试:快照 ID 加限定引用在每次动作前重新解析,UI 变化即报 STALE_REF;CHECK/UNCHECK 等幂等动词替代切换,重试不产生副作用。
- 渐进式骨架遍历:先浅层总览、再按需 DRILL/WIDEN 深入或展开,官方口径在 Slack、VS Code、Notion 等密集应用上把 Token 消耗压缩 78–96%。
- 链式交互与状态判定:单击按 AXPress、AXOpen、内格激活、写入选择、AXConfirm 依序尝试,成败以应用状态的实际变化为准——因为「应用两个方向都会撒谎」。
- 无头默认与权限治理:引用动作走无障碍 API,默认阻断焦点、光标、键盘与剪贴板副作用;权限状态以显式结构返回,缺失权限经隔离辅助进程请求。
- CDP 互通:对 Chromium 应用开启验证过的 DevTools 端口,网页内容交给 Playwright 等框架,原生菜单与对话框仍走无障碍路径。
版本/套餐对比
项目完全免费开源,Apache 2.0。三平台均已支持:macOS 需授予辅助功能权限、Windows 对同完整性级别的应用无需额外授权、Linux 需 at-spi2-core 的图形会话;官方平台支持表里只有「Shell surfaces(open-system-surface)」在 macOS 仍标为 Planned。构建需 Rust 1.89+;npm 包自动下载预编译二进制(x64 / ARM64),Node 18+ 即可使用;Jev 相关脚本需要自备 API key 且按量计费,纯 CLI 路径完全本地、不外发数据。它不内置模型、不绑定任何 Agent 框架——Claude Code、Codex、Cursor 或自研 Agent 都可以把它当作工具调用,也可配合可选的 jev-desktop 技能形成「观察—决策—执行」闭环。项目已于 2026-10-28 进入 1.0 正式线,C ABI 以主版本号声明兼容性,升级仍以官方变更记录为准——0.10.0 已把 C ABI 升到第 5 版并移除 ad_get_tree、ad_find、ad_launch_app、ad_focus_window 等一批有 *_exact 替代的旧入口,属破坏性变更。
值不值得用?
值得投入的场景:为原生应用构建 GUI 自动化与 QA 测试的团队——稳定的元素引用让断言可重复;想给编程 Agent 补上「桌面双手」的平台工程组——与浏览器自动化、Shell 工具形成三层互补;对隐私敏感、要求动作链路本地化的场景——纯 CLI 路径不外发任何数据。
需要冷静的地方:三平台能力并不齐平(macOS 走私有 command host、能力最全,Windows 免额外授权,Linux 依赖 at-spi2-core 且部分表面仍为 Planned);效果依赖目标应用的无障碍实现质量,实现糟糕的应用仍会难缠;需要授予辅助功能等系统权限,企业分发要做权限预案;项目处于早期,把它定位为有前景的开发者基础设施而非开箱即用的自主员工更符合实际。给 Agent 大范围桌面控制权前,先划好审批与安全边界。
使用建议
- 从 npx agent-desktop snapshot --app Finder -i 开始体验,先看无障碍树长什么样,再设计自动化流程。
- 让 Agent 优先使用 CHECK/UNCLICK 等幂等动词,配合 STALE_REF 重试逻辑,把误操作概率压到最低。
- 密集应用务必启用渐进骨架遍历,控制上下文成本;只有定位到具体子树后再深入。
- 涉及 Chromium 应用时用 --cdp 把网页部分交给专业浏览器框架,别用无障碍树硬啃 DOM。
适合谁用?
推荐:构建桌面 GUI 自动化与回归测试的 QA 工程师、为 Agent 添加原生应用操作能力的平台团队、Computer Use 方向的研究者与工具开发者。
可考虑:有大量重复桌面操作的个人用户,可结合脚本做轻量自动化。
不推荐:要求三平台能力完全一致、不接受 Linux 侧部分表面仍为 Planned 的团队;期待视觉理解通用兜底的场景——它不解决无障碍实现缺失的应用;希望零权限、零配置静默运行的用户。
版本记录
以下按时间倒序收录历次版本更新的完整说明(页面顶部简介只保留最新一版说明)。
最新版 v1.3.1(2026-11-13T21:02Z 发布,GitHub 标记 Latest,prerelease=false):小补丁——升级 rustix 到 1.1.6 修复 RUSTSEC-2026-0486;修已启动的沙箱在其启动器退出后继续运行(#672)。
前一版 v1.3.0(2026-11-12T22:31Z 发布):官方 Full Changelog 为 v1.2.0...v1.3.0。新增——sandbox 命令(#505)与 macOS VM 沙箱(#506)。修复——macOS 原生菜单解析与生命周期转换验证(#376);关闭 sessions、refs、trace、mcp 与 waits 中可达的非法状态转换(#602)。性能——macOS 用 libproc 读取应用进程清单,不再 spawn ps(#573)。文档——说明每个本地账户都能访问 --cdp 端口(#589);文档升级到 TypeScript 7(#622)。
前一版 v1.2.0(2026-11-05 发布,GitHub 标记 Latest,prerelease=false):主题为内置 MCP 支持(官方收尾提交「chore: release 1.2.0 with mcp support」),官方 Full Changelog 为 v1.1.0...v1.2.0。新增——agent-desktop 自带 MCP server(#519),Claude 等 MCP 客户端可把桌面自动化直接挂成工具;文本命令支持从 stdin 读入(#373),便于管道串联;macOS 可选中「仅其容器才可选」的列表行(#503)。修复——macOS 光标 overlay 改为绘制在菜单与系统面板之上(#511);观察(observation)过期后保留部分快照而非丢弃(#372);workspace 清单忽略已退出的应用(#371);macOS 光标 overlay 不再从调用者目录启动(#381)。文档——README 与仓库文档简化,新增 Homebrew core 安装说明(#524)。官方发布说明未声明新增 C ABI。
前一版 v1.1.0(2026-11-03 发布,prerelease=false):这是 1.0 线之后的第一个功能版,官方 Full Changelog 为 v1.0.2...v1.1.0。新增——type --interval-ms 可以按固定节奏逐字输入;文本录入后在 macOS 与 Windows 都显示插入光标,按键后光标保持在插入点,缩进新行也能落对位置;光标标签改成随文字自适应的 pill,未指定填充色时用系统强调色;Windows 的 overlay 现在能绘制图片光标;取交互租约前先移动光标;macOS 可通过元素自身的无障碍地址重新识别 refs,Linux 与 Windows 的 refs 改由 capture rule 解析。修复——Windows 命令退出时崩溃、overlay 坐标被缩放两次、启动时闪一个黑方块、type 把 CR LF 打成两个换行;macOS overlay 控件不再等齐才画、点击高亮的光晕与弹跳不再被裁掉、清掉的标签不再残留;移除了 macOS command host。macOS 现在能触达 Dock、菜单栏状态项与系统面板(#480);功能请求与提问迁到 Discussions。官方发布说明未声明新增 API。
前一版 v1.0.2(2026-10-30,GitHub 标记 Latest,prerelease=false):本版是仓库迁移与文档收口——代码库从 lahfir/agent-desktop 迁到 vercel-labs/agent-desktop(仓库链接与徽标全部指向新地址),AGENTS.md 成为唯一的 agent 说明文件并纠正了过时文档;新增 agent-browser.dev/desktop 文档站,含入门页、快照/引用/骨架钻取等核心概念、全部 60 个命令与配置参考、各平台页面、C 库文档与 changelog;npm 用户在 node 启动器拖慢每次调用时会收到提示;权限引导改为可选中启动它的应用、逐个查看每项授权,并清理残留的 host。官方说明无新增 API 或功能项。
前一版 v1.0.1(2026-10-28,GitHub 标记 Latest,prerelease=false):发布流程自动化——退役自定义包目录(Homebrew tap / Scoop bucket 不再维护)、技能里去掉版本行、CI 去掉慢速 live 测试(#320 / #324 / #325)。
前一版 v1.0.0(2026-10-28,正式线起点):简化原生安装并自动生成发布包元数据,修复 0.11.1 的 Homebrew 安装(#317 / #318 / #322);官方发布说明无新增 API 或功能项。
前一版 v0.11.1(2026-10-25):修复三个平台发行包的完整安装(#315)。
v0.10.1(2026-10-18):修 Windows 上 launch 可只给裸名称、不必带 .exe(#276)。
v0.10.0(2026-10-18,破坏性):C ABI 主版本升到 5;移除各自已有 *_exact 替代的旧入口——ad_list_surfaces、ad_surface_list_count、ad_surface_list_get、ad_surface_list_free、ad_list_windows、ad_window_list_count、ad_window_list_get、ad_window_list_free、ad_launch_app、ad_release_window_fields、ad_get_tree、ad_find、ad_is、ad_focus_window、ad_window_op、ad_resolve_element、ad_execute_ref_action_with_policy,以及 AdSurfaceList 与 AdWindowList 句柄。
v0.9.4(2026-09-23):同步 0.9.3 的 cargo lock。v0.9.2(2026-09-17):无头桌面动作改为回报真实结果,并新增 jev-desktop。v0.9.1(2026-09-13):--wait-for 默认按落点范围生效(--wait-for-scope from|to)、继承的 deadline 过期时保留 wait_timeout 信封、修 wait --count 在快照不完整时的误报。