让 AI 替你操作电脑，这件事现在能做了。

Vercel 实验室开源的 agent-desktop 干的就是这件事：读你电脑上正在显示什么，找到要点的那个按钮，点下去。窗口里有哪些元素、哪个是输入框、哪个能勾，它一项项向系统要，然后照着做。

你不用教它认界面。

过去 24 小时它涨了 2,243 颗星，现在 10,668 星，Rust 写的，Apache-2.0，macOS、Windows、Linux 都能跑。

它自己不是 agent

官方在文档里把这件事写得很直白：这是一把给 agent 用的工具，不是一个 agent。

它里面没有模型，没有界面，没有对话框。每条命令读一次界面、或做一个动作，输出一段 JSON 就退出进程。观察、决策、复查这套循环跑在调用它的 agent 里，不在它里面。

所以装完它你不会得到一个能自己干活的助手。它提供的是"手和眼睛"，脑子还是你那边的。

网页上的操作归它的兄弟项目 agent-browser，桌面应用才归它。

不看屏幕，为什么反而点得准

截图路线的逻辑是：拍一张图，让模型在图上找"登录"按钮，算出坐标，把鼠标挪过去按一下。

问题在于坐标不是按钮的属性，是这张图的属性。窗口挪一格、缩放变一下、列表滚一行、弹个提示挡住半边，算出来的坐标就全错了。更麻烦的是它不知道自己错了，照样按下去，按到了别的东西上。

agent-desktop 走的是各家系统本来给无障碍工具用的那套结构：macOS 的辅助功能、Windows 的 UI Automation、Linux 的 AT-SPI。它拿到的是一棵树，里面写着这个元素叫什么、是按钮还是输入框、能不能点、在哪个窗口下。

每个能操作的元素配一个编号，长这样：

agent-desktop snapshot --app Finder -i    

读一次，元素带编号

agent-desktop click @s8f3k2p9:e8          

点那个编号

agent-desktop snapshot --app Finder -i    

再看一次，确认点上了

编号自带快照 ID，@s8f3k2p9:e8的意思是"第 s8f3k2p9 次快照里的 e8"。单独写一个@e8会被直接拒绝，它不允许拿上一次的编号去点这一次的界面。

界面变了怎么办？它不猜。匹配不上就报STALE_REF，匹配到两个以上就报AMBIGUOUS_TARGET，让调用方重新读一次再动手。宁可报错，也不静默点错地方。

这一点在跑一整套流程时价值很高。点错一个"发送"，代价是一封发错的邮件；静默地错，比大声地错麻烦得多。

上手只要三行

装它：

npm install -g agent-desktop

agent-desktop version

macOS 第一次用要开辅助功能权限，它带了引导：

agent-desktop permissions --guide

然后就是上面那三步：读界面、点编号、再读一次确认。

想交给 agent 用，它自带配套的说明书：

agent-desktop skills get desktop    

循环、编号、验证与重试规则

agent-desktop skills get platform    

你这个系统上哪些能力不一样

也可以把技能装进 agent 框架（npx skills add <项目仓库> --skill agent-desktop），或者在 AGENTS.md 里写一句"用 agent-desktop 看和操作桌面应用，第一次使用前先跑 skills get desktop"。

出错之后，怎么知道该不该重试

这是它比截图路线更实用的地方，也是很多自研脚本栽跟头的地方。

一次点击失败，其实有两种完全不同的情况：动作压根没送到应用，可以放心重试；动作可能已经送到了，只是效果没确认，这时候重试就是重复提交——重复下一单、重复发一封邮件、重复扣一次款。

两种情况，处理方式相反。

agent-desktop 把这一层做成了返回值。出错时带一个disposition字段，里面写明这次重试安不安全，规则只有一条：retry是safe的时候才重试。

别的都不行。

它还单独区分"已送达未验证"这种中间状态：输入确实发出去了，但效果没读到，那就再读一次确认，而不是再发一遍。

自己写过自动化的人应该知道，这一层判断平时全靠拍脑袋。工具把它变成一个字段，是这套东西真正省事的地方。

它干活的时候，你还能用这台电脑

默认模式叫 headless：动作走无障碍接口直接触发，不移动指针、不抢焦点、不合成键盘输入。所以它跑的时候，你还能接着打字。

代价得说清楚：语义走不通的场景，它是直接失败，不会偷偷降级成物理点击。真要物理点击得显式加--headed，那一刻它才会动你的鼠标、抢你的焦点。

省心和能力，只能选一个。

另外它默认带 5 秒的等待轮询：元素还没准备好就等，等不到再报超时。

密码框是单独处理的。系统一旦把某个输入框标记成密码字段，它的内容不会出现在任何输出里，读不出、也回显不出。

用之前要知道的几件事

权限不小。macOS 的辅助功能权限，等于允许它读你所有窗口的内容，也能模拟输入。这是这类工具的前提，不接权限就没法工作。不用的时候可以在系统设置里关掉。

它看不见不暴露结构的界面。它只读无障碍树，不做像素识别。游戏、canvas 自绘的界面、自己画控件又不声明角色的应用，它读不到东西——因为那里没有树。这既是它的边界，也是它不点错的原因。

60 个命令名里，实际能跑 56 个。key-down、key-up、mouse-down、mouse-up四个现在会直接拒绝执行，要等一个能接管按键按住状态的守护进程做出来。

快照可能带隐私。窗口标题、剪贴板内容、通知、截图、命令输出，都可能在返回值里。官方明确说这些要当作私密内容对待，调试记录别贴进公开日志或者随手传上去。

该不该用

你在写 agent 或者自动化脚本，需要它去操作桌面应用，这套东西现在的成熟度够用，值得试。它的错误码、重试建议、动作是否已经送达的标记都设计得比较完整，接进流程里不用自己猜。

你只是想让 AI 帮你点网页上的按钮，那应该看 agent-browser，方向不对。

你希望装完就有一个助手接管电脑、替你干活，这个不是成品。它没有模型也没有界面，你手上得已经有一个会调工具的 agent。

一句话：它把"AI 操作电脑"里最容易出事的两件事——点的是哪个位置、失败之后该不该重试——从流程里拿掉了，换成可以核对的编号和字段。剩下的编排，还得你自己接。