agent-desktop 是 Vercel Labs 出的一个命令行工具，一句话说清它干什么：让 AI 助手能操作你电脑上的桌面软件，而且不靠截图和像素匹配。

一、问题是什么

过去两年「AI 会用电脑」这件事一直卡在一个很别扭的地方。最直接的方案是让 AI 看截图、判断按钮在哪、算坐标、点下去——这套方案的问题很实在：换分辨率就失效、换主题就失效、界面小改版就失效，而且模型算坐标的能力是它最弱的一项，点到旁边是常有的事。

第二条路是给每个软件单独写接口，也就是「集成」。这条路的问题是成本：全世界有几百万个桌面软件，你不可能一个个对接，而且很多软件根本不提供接口。

所以中间缺了这么一层：有没有办法让 AI 像人一样「看见」界面元素，但不需要真的去看像素？

二、核心设计

答案是利用操作系统自己就有的东西——辅助功能树（accessibility tree）。

这个机制原本是给屏幕阅读器用的：操作系统会维护一棵结构化的树，描述当前界面上有哪些元素、每个元素是什么角色（按钮、输入框、列表项）、叫什么名字、能不能点。既然屏幕阅读器能靠这棵树把界面念给盲人听，那 AI 当然也能靠它把界面「读」进来。

agent-desktop 做的就是把这棵树读出来，转成 JSON，并且给每一个可以操作的元素分配一个 ref 编号。AI 拿到的不是一张图片，而是一份带编号的清单：


{ "role": "window", "name": "Downloads",
"children": [
{ "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8" }
] }

接下来它按编号操作：agent-desktop click @s8f3k2p9:e8。点完再取一次快照，看结果对不对，对就继续，不对就重来。这个「看→点→再看」的循环住在你自己的 agent 里，agent-desktop 只是提供手和眼睛——它内部没有任何模型。


三、功能拆解


跨三平台：macOS、Windows、Linux 都支持，x64 和 ARM64 都有原生二进制。

快照（snapshot）：snapshot --app Finder -i 只列可交互元素，每个带 ref 编号；不带 -i 会返回完整树。

精确定位：ref 是快照内有效的编号，UI 变化了旧 ref 会返回 STALE_REF 或 AMBIGUOUS_TARGET，让你重新取一次——这是刻意的设计，防止 AI 拿着过期的编号乱点。

权限引导：macOS 上必须给辅助功能权限，agent-desktop permissions --guide 会一步步带你去系统设置里打开。

双形态交付：既有 npm 包（npm install -g agent-desktop），也有纯粹的 C 库和原生二进制，不需要 Node 运行时也能跑。

状态自检：agent-desktop status 告诉你当前平台、权限状态、支持哪些操作面。


四、适合谁、不适合谁
适合：正在做 AI agent、需要它操作桌面软件（不只是浏览器）的开发者；想做 RPA 但受够了截图识别的脆弱性的人；需要跨平台（同一套逻辑在 Mac 和 Windows 上跑）的场景。
不适合：只想让 AI 操作网页的人——那种情况用浏览器自动化工具更合适，没必要上桌面层；不写代码的普通用户也不适合，它是个 CLI 工具，没有图形界面；以及想开箱即用一个「AI 助手」的人，它明确不包含模型。
五、诚实提醒
隐私这件事得自己上心。 官方在 README 开头就写了：快照、剪贴板读取、截图、命令输出、调试产物里都可能含有你的私人桌面内容，别把它们放进公开日志或上传。这不是危言耸听——辅助功能树里常常带文件名、路径、聊天记录预览。
它不替你做判断。 因为不含模型，所以「点哪个」「这步对不对」全在你自己的 agent 里决定。这既是优点（不锁定任何一家模型）也是负担（你得自己写好那个循环，包括失败重试和危险操作拦截）。

ref 是会失效的，这是设计不是 bug。界面一变旧 ref 就作废，必须重新取快照。如果你的 agent 不做这一步，就会一直撞 STALE_REF`。

平台差异仍然存在。 三个系统暴露的辅助功能树结构不一样，同一个软件在 Mac 和 Windows 上读出来的元素可能形状不同。跨平台代码需要处理这些差异。