Agent Desktop（vercel-labs/agent-desktop）：不用截图猜坐标，把系统无障碍树变成智能体的眼睛和手

一、导读

当大多数 computer-use 方案还在「截图 → 模型猜像素坐标 → 点击 → 再截图」的循环里打转时，vercel-labs/agent-desktop 走了屏幕阅读器走了三十年的老路：操作系统早就暴露了结构化的无障碍树——macOS 有 AX API，Windows 有 UI Automation，Linux 有 AT-SPI。这个 Rust 单二进制把无障碍树变成快照，给每个可交互元素发一个带命名空间的稳定引用（ref），智能体拿引用操作、再拿快照验证，观察与定位全程不需要视觉模型。项目 10 月 28 日发布 v1.0.0 首个稳定版，10 月 30 日完成向 Vercel Labs 的组织转移，随后冲上 GitHub 涨星榜，单日进账 2,243 颗星（2026-11-03 读取 trending 数据）。它明确「不做智能体、只做眼睛和手」，观察-行动循环完全留给调用方的大模型。

二、项目速览

项目	内容
仓库	vercel-labs/agent-desktop（原 lahfir/agent-desktop，旧地址 301 重定向）
定位	给 AI 智能体的桌面 computer-use 基础设施：读无障碍树、吐 JSON、按引用操作
语言与形态	Rust 工作区，单一 CLI 二进制（CI 硬卡 15 MB 上限）+ C-ABI 动态库
平台	macOS（AX API）/ Windows（UI Automation）/ Linux（AT-SPI），npm 分发三平台二进制
命令规模	60 个命令名、56 个可用，覆盖观察、引用操作、键鼠、窗口、通知、剪贴板、会话
协议	JSON Envelope v2.5：ok / data / error + 交付语义 disposition
许可	Apache-2.0，个人与商用免费
热度	总星 8,577、单日 +2,243（2026-11-03）；npm 周下载 12,834（2026-10-26 至 11-01）
作者与归属	lahfir 个人项目（2026-05 上 Show HN 获 99 分），2026-10-30 转入 Vercel Labs

三、为什么是它：单日 2,243 颗星的三重动因

第一重是里程碑。10 月 25 日 v0.11.x 把原生安装器从 npm postinstall 里拆出来独立分发，10 月 28 日 v1.0.0 发布——从作者自述「122 颗星起步」到第一个稳定版用时约半年。第二重是组织转移。v1.0.2（10 月 30 日）的变更列表是一串明确的交接动作：移除个人赞助链接（#332）、仓库链接指向 vercel-labs（#333）、补上 Labs 产品徽章（#334，由 Vercel 工程师 Railly 提交）、上线 agent-browser.dev/desktop 文档站（#335）。lahfir/agent-desktop 现在 301 重定向到 vercel-labs/agent-desktop——与作者公开承认的灵感来源 agent-browser（Vercel Labs 的浏览器结构化操作工具）在同一个屋檐下会师，一个管浏览器、一个管桌面，拼成完整的 agent 操作面。第三重是赛道卡位。computer use 是智能体落地最拥挤的方向之一，而 agent-desktop 是少数把自己摆在「基础设施」位置的项目：不内嵌任何大模型，也不做像素匹配，被 Claude Code、Codex 或自研 agent harness 无差别接入。三条动因叠加造就了这波涨星，具体传播链路（例如 Vercel 官方渠道宣发的力度）待确认，但仓库侧证据链完整可查。

四、架构原理：把「看」和「点」都换成结构化证据

4.1 整体架构与数据流

agent-desktop 五层架构手绘信息图：调用方、CLI 二进制、平台无关契约核心、三平台适配器与桌面应用，右侧标注 JSON 响应回流

一句话概括这张图：调用方只见两样东西——一个 CLI 进程和一份 JSON 契约；所有平台差异被压进三个适配器，所有可靠性机制被压进 core。适配器只在自家操作系统上编译（在 macOS 机器上构建 Windows 包会直接失败），core 却要接受跨平台交叉编译检查——CI 明确要求 agent-desktop-core 通过 Windows MSVC 与 Linux GNU 两个 target 的编译。这种「核心可交叉验证、适配器各守其土」的结构，是多平台 GUI 工具控制腐烂速度的务实选择。

4.2 四大中立词表：三个 OS 说同一种话

三个平台的无障碍 API 原本是三套方言：UIA 的 Tab 是容器而 TabItem 才是页签，与 ARIA 命名正好相反；macOS 的开关按钮是 button 角色带 pressed 状态，Windows 会把带 toggle 支持的按钮重分类为 switch 带 checked。agent-desktop 的解法是让 core 拥有四份封闭词表——角色、状态、能力、名称证据——适配器只负责把方言映射进来，不允许自造 token。配套的是「证据三态」纪律：每个读到的属性只能是 Known、Absent 或 Unknown，三者绝不折叠成两态。Absent 是「问过了、它没有」，Unknown 是「没问成」；一个从不响应的目标不允许冒充回答「否」，反之角色的授予必须基于肯定性证据，读取失败就要扣下。这个看似学究的区分，直接决定了后面所有「失败能不能重试」的判断质量。

4.3 快照与引用：ref 的生命周期

snapshot 命令对无障碍树做一次持久化观察，按深度优先序给每个可交互元素分配引用，形如 @s8f3k2p9:e8——内嵌快照 ID，自描述归属。三条硬规则：引用只属于所属快照，裸 @e8 直接以 INVALID_ARGS 拒绝；UI 一变，旧引用以 STALE_REF 失效，必须重新快照；同一窗口名命中多个实例时报 AMBIGUOUS_TARGET，错误详情里列出候选窗口 ID 让调用方带 --window-id 消歧。这套设计把「元素是谁」从坐标问题变成了身份问题：RefMap 里存的是身份证据而非指针，重新解析时走分级策略——先走存储的位置路径，再按标识符（Windows 的 AutomationId、macOS 的 AXIdentifier、Linux 的 accessible-id）确认，再按稳定文本确认，最后才允许无身份引用按唯一几何位置晋升，且零面积的存储矩形永不晋升（调查记录 A17-7：离屏与虚拟化元素会塌缩成相同的退化矩形）。窗口身份同样设防：句柄会被系统回收复用，身份必须由句柄加进程代际令牌共同佐证——macOS 用窗口号加进程启动时间，Windows 用 HWND 加创建时间令牌，Linux 用 X11 客户端 ID 加启动 ID 限定的进程时间令牌；截屏前后还要做一次「身份三明治」校验，防止截到一半显示器热插拔把像素归错屏幕。

4.4 交付语义：让失败说真话

这是整个项目最有辨识度的设计。智能体点击「提交订单」失败了，该重试吗？答案取决于输入到底有没有送达：没送达可以放心重试，可能已送达再点一次就是重复提交。JSON 契约因此给每个错误和动作结果都带上 disposition 字段，delivery 取五档：not_delivered（确定没送达，retry 安全）、delivered_unverified（已派发但效果未读回确认）、delivered_verified（读回确认过）、delivery_uncertain 和 unknown（一律不自动重试）。规则只有一条链：retry 为 safe 当且仅当 delivery 为 not_delivered。配套机制同样扎实——Auto-Wait 默认开启，5000 毫秒预算内轮询可见性、稳定性、启用态等瞬态检查（type 按字符数加时），策略与可编辑性这类终态检查则快速失败不占预算；遮挡闸门做三点探测，证据不足时按 Unknown 放行而不是凭空捏造一个遮挡者；Windows 上 SendInput 的返回值被明文规定不算送达证据（这个 API 在被 UIPI 拦截时也报成功，见调查记录 A9-3），物理步骤因此只能报 delivered_unverified，效果要靠独立读回判断。写路径还有一个变更分类器，把「写入已生效但报错」「能力真不存在」「真失败」三类分开，避免读路径的可重试错误码被用在写路径上——那恰好会授权一次危险的重复派发。

{
  "version": "2.5",
  "ok": false,
  "command": "click",
  "error": {
    "code": "STALE_REF",
    "message": "@s8f3k2p9:e7 not found in current RefMap",
    "suggestion": "Re-run a snapshot to obtain fresh refs, then retry with the new ref",
    "recovery": {
      "strategy": "refresh_snapshot_then_retry_original",
      "retryable": true,
      "requires_fresh_snapshot": true
    },
    "disposition": { "delivery": "not_delivered", "retry": "safe" }
  }
}

4.5 无头优先与交互策略

默认策略是无头（headless）：引用操作走语义化无障碍调用，不动鼠标、不抢焦点、不合成键盘输入、不碰剪贴板；语义路径走不通就「失败关闭」，绝不悄悄退化成物理点击。物理输入必须显式加全局 --headed 旗标授权。中间还有一档 CLI 触及不到的 focus fallback（只许聚焦、不许动鼠标），留给显式按键类动作和语言绑定。策略差异落到具体命令上很微妙：Windows 的 UIA 不提供「在光标处插入文本」的写入原语，所以 type 在严格无头下直接在策略层失败，set-value 才是无头写文本的正道——这类「哪个动作在哪平台是物理的」被逐动作、逐平台钉死在调查记录里。物理侧同样层层设闸：机器级交互租约保证同一时刻只有一个进程能合成输入（等待期不持锁，持锁后重新解析目标才是正确性边界）；前台闸门要求注入前目标窗口仍是前台（Windows 的 SendInput 只进前台队列，无法按进程定向）；多段物理序列（拖拽、修饰键和弦）配释放保护，中止时在原点补反向输入——拖拽回起点加鼠标抬起、按住的键逐个扫尾抬起，清理失败时如实报告 uncertainty 而不是谎称没有输入落地。

4.6 JSON 契约的五版演进：一部「反谄媚」史

契约版本号刻在每条响应的 version 字段里，五次大版本的演进方向高度一致：不让工具对智能体说漂亮话。2.1 把「重试这条命令」的字符串换成结构化 recovery 对象并引入 disposition，禁止调用方盲信旧命令串；2.2 把超大树的「超时报错、什么都不给」换成显式部分快照——返回 ok 加 complete: false 加已观察到的树，每个被截断的子树标记 subtree_truncated，让调用方自己决定要不要 drill-down；2.4 给带状态的引用操作加后置条件校验，读回失败保留适配器错误码，且 macOS 上「状态没变化」不再被当成「没送达」——那会授权一条危险的降级重试链；2.5 最狠：拖拽、窗口操作、剪贴板这批命令里那些「每次成功都带、但什么也证明不了」的无条件成功旗标被整体删除，无兼容别名，代之以适配器自己的操作报告——verified 必须指明读回了哪项后置条件（窗口尺寸、位置、最小化状态）及其容差（macOS 2 点、Windows 8 像素、Linux 2 像素）。作者在 2026 年 8 月那篇「让桌面自动化停止对智能体撒谎」的发布里总结的正是这条主线。

4.7 工程纪律：证据文化与 15 MB 红线

仓库的工程文化在一众开源项目里相当罕见。平台行为不做想当然：每个平台先跑 probe corpus（可重跑的原始探测脚本），产出经脱敏的 capture 与 findings ledger，每行结论带稳定编号（如 A15-7），VERDICT 只有 CONFIRMS、CONTRADICTS、NEW-EDGE、DEFERRED 四种——一个被测量推翻的假设按缺陷处理，当次修改里同步纠正。测量本身也有防造假设计：声明了却没产出的测量会让整轮失败，自检夹具确保「检查器悄悄失灵」时大声报错而不是输出干净的绿。发布纪律同样刚性：release 产物超过 15 MB 直接 CI 失败，git 历史要求线性，贡献指南禁止 AI 署名尾巴。macOS 侧还有一个独家机制：每次快照命名空间复用一个私有命令宿主进程，持有原生无障碍对象，防止「删掉的行悄悄解析到同 ID 的幸存行」，闲置 15 分钟自动退出。

五、应用场景：四类落地与一条边界

agent-desktop 观察-操作-验证循环手绘流程图：快照、智能体决策、按引用操作、交付语义判定与验证回路

5.1 给编码智能体装上桌面手脚

痛点：Claude Code、Codex 这类编码智能体被关在终端里，一旦任务跨出命令行——打开 Finder 整理下载目录、在 Notes 里记一条结论、操作一个只有 GUI 的发布工具——流程就断链，通用兜底又只有又贵又脆的截图方案。解决路径是把 agent-desktop 作为工具挂进 agent harness：二进制自带与版本匹配的文档，agent-desktop skills get desktop 与 skills get platform 直接吐出「循环、引用、验证、重试规则」的技能说明；也可以在仓库 AGENTS.md 里加一段引导，或用 skills.sh 一键安装。

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.

收益是三重的：观察环节零视觉模型调用（无障碍树是文本 JSON，直接进上下文）；引用定位不受像素漂移影响；错误码与重试建议是结构化的，智能体的重试逻辑可以直接分支。适用边界：目标应用必须暴露无障碍树——Electron、Qt、原生框架一般都有，游戏画面与自绘 UI 没有，后者请看 5.5。

5.2 把桌面自动化从「录制回放」升级为「自证可靠」

痛点：传统 RPA 脚本脆在两处——选择器失效后静默点错地方；失败后不知道动作是否已执行，盲目重试会把「提交」点成「双提交」。解决路径是利用严格引用解析加交付语义：脚本不再对着坐标点，而是「快照 → 拿引用操作 → 按 disposition 决定重试与否 → 读回验证」。高频调用的场景还可以绕过 CLI 进程开销，直接用 C-ABI 动态库在进程内调用：

import ctypes
lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
lib.ad_adapter_create.restype = ctypes.c_void_p
assert lib.ad_init(6) == 0  # 头文件 AD_ABI_VERSION_MAJOR 与库一致时返回 AD_RESULT_OK
adapter = lib.ad_adapter_create()
lib.ad_adapter_destroy(adapter)

收益可量化：每个动作结果都带 delivery 分档与读回验证范围（窗口几何类验证标明容差——macOS 2 点、Windows 8 像素、Linux 2 像素），「这步到底成没成」从猜测变成查表。边界：delivered_unverified 不等于业务成功，关键流程仍需业务层断言；等待期不占交互租约，但持租约后的重新解析是必要开销，不适合亚毫秒级延迟诉求。

5.3 多智能体并行操作同一台桌面

痛点：让几个智能体同时操作一台机器，最大的恐惧是物理输入互相踩踏——A 的鼠标拖拽混进 B 的键盘输入。解决路径是三层并行设施：会话命名空间隔离各自的快照与 trace；机器级交互租约把物理输入的派发串行化（只串行派发瞬间，不串行长等待）；可选的智能体光标叠层给每个（session-id, agent-id）配一条动画光标，人眼能看到「现在是谁在点哪里」，点击落点还有涟漪与轮廓高亮。

agent-desktop session start --cursor --multi-agent
agent-desktop click @s8f3k2p9:e12 --agent-id worker-1
agent-desktop click @s8f3k2p9:e15 --agent-id worker-2

收益：多智能体桌面协作从「不敢开」变成「可观测地开」。边界：多智能体模式要求 harness 给每个子智能体分配稳定的 agent-id；X11 之外 Linux 的光标叠层不可用（Wayland 暂缺）。

5.4 桌面 GUI 自动化测试与审计取证

痛点：GUI 冒烟测试最尴尬的失败是「断言过了但界面没变」——工具报了成功旗标，谁也没验证过。解决路径是把 v2.5 契约的读回验证当断言用：操作返回里 verified 字段必须写明读回了哪项后置条件；配合 session trace 的 JSONL 时间线（按时间戳、进程、文件内位置确定性合并，支持导出回放），测试报告从「ok」升级为带证据链的判定。窗口、通知、剪贴板管理命令还能覆盖安装向导、首次运行弹窗这类传统测试框架够不着的角落。边界：trace 的 replay 工件（前后截图、refmap 副本）默认不开启，开启后体积与隐私面都会变大，CI 里要当作敏感产物管理。

5.5 边界：什么时候不该用它

三类场景请绕行。其一，无树可读的目标：游戏画面、Canvas 自绘界面、经压缩像素流转发的远程桌面——没有无障碍树就没有快照，这是架构级限制，不是功能缺失。其二，需要视觉判断的任务：布局是否美观、图表趋势如何——截图命令配合视觉模型更合适，仓库里的 JEV 辅助工具（仅仓库分发）可以把屏幕描述发给配置的模型供应商，但要把隐私面纳入考量。其三，纯 Web 页面操作：同门的 agent-browser 与 Playwright 在 DOM 语义层工作，成熟度更高，没必要绕道桌面无障碍树。

六、快速上手

三步跑通 macOS 上的完整循环（Windows 与 Linux 无需辅助功能授权）：

npm install -g agent-desktop        # 三平台二进制随 npm 包分发，也支持 Bun/Yarn/pnpm
agent-desktop permissions --guide   # macOS 需授辅助功能权限，命令会引导授权
agent-desktop snapshot --app Finder -i          # 观察：每个可交互元素带一个 ref
agent-desktop click @s8f3k2p9:e8                # 操作：引用来自上一步快照
agent-desktop snapshot --app Finder -i          # 验证：重新观察确认效果

三个高频提醒：PowerShell 里引用必须加引号（裸 @token 是展开运算符）；密密麻麻的应用先用 snapshot --skeleton -i --compact 画浅层地图，再用 --root @ref 钻进目标区域，省上下文也省时间；动作默认无头执行，需要真实鼠标键盘行为（拖拽、悬停）时显式加 --headed。想深入时，agent-desktop skills get desktop 与 skills get platform 内置了与二进制版本一致的全部操作守则。

七、横向对比：五条技术路线

方案	感知方式	动作通道	失败语义	甜区
agent-desktop	无障碍树快照 + 引用	语义优先，`--headed` 物理兜底	disposition 五档交付语义	桌面原生与 Electron 应用
视觉派（CUA / 计算机使用 API）	截图 + 视觉模型	像素坐标点击	模型自行判断，工具层无契约	含无障碍树缺失的任意 UI
agent-browser / Playwright	DOM / CDP	浏览器协议	结构化错误	Web 页面
AutoHotkey / AppleScript	人写硬编码选择器	系统 API 与合成事件	基本没有	固定流程的个人自动化
OSWorld 类基准环境	容器化桌面 + 视觉	混合	环境侧评分	学术评测

agent-desktop 与视觉派不是替代关系而是分工关系：结构化树覆盖「树存在」的绝大多数桌面场景，成本低一个数量级且抗像素漂移；视觉模型留给无树的少数场景。与传统自动化脚本的本质差异在于「为谁设计」——前者默认读者是概率性的、会误读文档的大模型，所以失败必须自解释；后者默认读者是确定性的脚本，失败就抛异常。

八、局限与风险

五个必须写进选型文档的点。第一，可访问性盲区：无障碍树缺失即失明，个别应用的无障碍信息质量差（空名、错角色）也会拖累定位成功率，这类质量问题在三个平台间分布不均。第二，隐私面大：快照树、窗口标题、剪贴板读取、通知、截图与 trace 全都可能包含私密桌面内容，官方 FAQ 明确要求不得进公共日志与上传——把 agent-desktop 接进云端智能体时，数据边界要在架构层先画好；JEV 辅助工具会把屏幕描述发给模型供应商，仅适合经批准的数据。第三，平台不对齐：Linux 的截图在 Wayland 走 portal、鼠标 headed 仅 X11、通知仅 GNOME Shell；Windows 上高完整性目标进程受 UIPI 边界保护，写入会以 PERM_DENIED 失败关闭——这是安全特性不是缺陷，但自动化脚本要预案。第四，提示注入风险：被操作窗口里的文本就是智能体的输入源，恶意页面或文档可以借桌面内容操纵智能体，工具层不做防御（它只提供眼睛和手），防线必须建在调用方智能体上——有社区评论直指「桌面访问加提示注入」的组合风险，这个批评是中肯的。第五，成熟度尾巴：key-down、key-up、mouse-down、mouse-up 四个按住类命令要等守护进程支持才开放，Homebrew 与 Scoop 官方包尚在提交流程中，跨平台会话的行为差异仍在逐版拉平（v2.4 与 v2.5 两次破坏性迁移就是证据）。

九、小结与行动建议

agent-desktop 用半年时间验证了一个朴素的判断：智能体需要的不是更聪明的眼睛，而是诚实的报告。它的可复用价值不止于桌面操作本身——「交付语义五分档」「证据三态」「带编号的调查记录」这三件套，任何做智能体工具层的项目都值得整套搬走。行动建议：第一，给 Claude Code 或自研智能体接桌面能力，先跑 npx skills add 装 skill 再写业务提示词，内置文档比自己读 README 更新更及时；第二，把 disposition 语义写进你的工具调用规范——重试决策不该由大模型自由发挥；第三，生产环境把它当敏感组件管理：会话 trace、截图工件、剪贴板读取都按数据分级走；第四，跟踪 v1.x 的平台对齐进度再决定 Linux 大规模铺开；第五，如果业务以 Web 为主，先看 agent-browser，桌面侧才是 agent-desktop 的主场。

参考资料

vercel-labs/agent-desktop 仓库 README 与 AGENTS.md（获取日期：2026-11-03）——https://github.com/vercel-labs/agent-desktop
CONCEPTS.md：引用身份、交付语义、调查记录词条（获取日期：2026-11-03）——https://github.com/vercel-labs/agent-desktop/blob/main/CONCEPTS.md
docs/json-output.md：JSON 契约 v2.0 至 v2.5 迁移说明（获取日期：2026-11-03）——https://github.com/vercel-labs/agent-desktop/blob/main/docs/json-output.md
docs/faq.md 与 skills/agent-desktop/SKILL.md：官方问答与智能体操作守则（获取日期：2026-11-03）
GitHub Releases：v1.0.0（2026-10-28）与 v1.0.2（2026-10-30）变更列表，含组织转移相关 PR（获取日期：2026-11-03）——https://github.com/vercel-labs/agent-desktop/releases
Show HN: Agent-desktop – Native desktop automation CLI for AI agents（2026-05-02，99 分）及作者「让桌面自动化停止撒谎」发布帖（2026-08-15）——https://news.ycombinator.com/item?id=47982708
npm 下载量 API：agent-desktop 周下载 12,834（2026-10-26 至 11-01 窗口）——https://api.npmjs.org/downloads/point/last-week/agent-desktop