十月二十八日,agent-desktop 打到 1.0;十月三十日发了 1.0.2,仓库从那会儿起搬进了 vercel-labs 组织;今天中午十二点十五分,1.1.0 上了 npm。三个版本号挤在六天里,改的多是 Windows 端的碎活——命令退出时崩、叠加层坐标缩放算了两遍、回车换行被拆成两次。
它想解决的事很朴素:让 Agent 操作你电脑上的软件,但不许截图。
它换掉的不是截图,是「看图猜坐标」这件事
现在绝大多数「电脑使用」类 Agent 的路子是四步:截图、把图喂给视觉模型、模型算出该点哪、按坐标点下去。这条路的毛病不在精度,在成本结构——每一帧都要重新看一遍图,按钮挪十像素就前功尽弃,而且一个不带视觉能力的命令行 Agent 根本没法参与,它读不了图。
agent-desktop 走的是另一条:读系统自己维护的无障碍树。Windows 上对接 UI Automation,macOS 上是 AX API,Linux 上走 AT-SPI。树里每个能操作的元素都会拿到一个引用号,形如 @s9gj3bfxd7q2i:e1,前半截是快照 id,后半截是元素序号。Agent 只需要说「点 e1」,再用一次快照确认结果。
所以它自己不带模型,也没有图形界面。每条命令吐一个 JSON 信封就退出,观察、动作、验证这三步的循环仍然留在你的 Agent 里。默认是无头模式:动作走无障碍接口,不移动鼠标、不抢焦点,你在前面干活,它在后面点。
这一点我实测能感觉到。我在记事本里跑通了一次完整闭环,快照出来 3,443 字节、14 个可操作元素、473 毫秒;把一段中文写进那个 textfield 的 value,524 毫秒,随后回读,一字不差。整个过程中鼠标指针躺在原地没动,记事本也没被抢到最前面——它的坐标在我这块副屏的边缘外,本来也不该被看见。

同一个窗口,用截图的方式交给模型是 30,504 字节的 PNG。数字的差别只是表面,底下那层差别是:截图只有视觉模型能读,而 JSON 连一个只会敲命令的 Agent 都能读。
装它只要一行,但 npm 会先拦你一下
npm install -g agent-desktop,Node 22 环境,装完一条命令就能跑。包不大,三秒装完,原生二进制按平台分开打包,x64 和 ARM64 都在里面。
第一条命令就给了个提醒:npm 没有执行安装脚本,所以每次调用会多走一层 Node 启动器,大约多 125 毫秒。这不是小事,同一个 1.1.0 我对比过——走启动器跑 version 是 894 毫秒,直接调包里那个 win32-x64 原生 exe 是 177 毫秒,五倍差距。要长期用,要么在 npm 11 上放行安装脚本,要么把原生二进制单独拎出来放 PATH 里。对一个每次动作都要调两三次的工具来说,这层开销会叠在每一轮循环上。
Windows 这边不需要额外授权,status 里 accessibility 直接是 granted,屏幕录制是 not_required。macOS 得去系统设置里手动开辅助功能,Linux 要有图形会话和 at-spi2-core,否则连树都读不到。
然后是那个容易被忽略的前提:它不自带模型。你得有一个能执行 shell 的编码 Agent,Claude Code、Codex CLI 这类都行,或者自己写一个循环去调它。这是它跟「装完就能用」的桌面助手最大的区别,也是它便宜的原因——花钱的地方不在工具本身,在你 Agent 的上下文里。
一个快照到底多大,我在这台机器上量了四个窗口
Chrome 那个窗口最重:29,794 字节、118 个可操作元素、单次快照 2.9 秒。桌上开着的 WorkBuddy(Electron 壳)是 15,053 字节、93 个元素。记事本 3,443 字节、14 个元素。资源管理器最轻,1,494 字节、5 个元素,1.1 秒。
按四字节一个 token 粗算,Chrome 那一屏大概是七千多 token 的量级,记事本八百多。这是我这台机器上的一手数,不是官方报的那组。
所谓 skeleton 模式,就是只读浅层节点、把深层结构留到需要时再下钻。它在两个窗口上的效果完全不同:WorkBuddy 从 15,053 字节砍到 2,371 字节,省了 84%;Chrome 从 29,794 砍到 27,359,只省了 8%。原因不难猜,Electron 壳的树浅,砍掉深层的控件就轻了;浏览器窗口的树本来就是页面本身,一层套一层,skeleton 只能削掉外圈那层。
官方自报的数字更漂亮:Slack、VS Code、Notion 这类密集应用省 78% 到 96%,Apple Maps 一次观察从 3,811 token 降到 273。这些是建设者自己量的,目前没有第三方 benchmark。我这两个数可以当参照——省多少取决于应用把界面暴露得多规整,跟工具本身的努力关系不大。

三次失败,比成功那次更有信息量
第一次,我拿一个菜单项的引用去读它的角色,返回 AMBIGUOUS_TARGET。原因写在错误里:这个引用在快照时没有被证明是唯一的,同一个菜单里有两个同名项,工具拒绝猜。这个立场贯穿整套设计——不唯一的身份就不执行,宁可让你重拍一次快照。
第二次,我图省事只写了 @e5,直接 INVALID_ARGS。引用必须带快照 id,因为界面一变,旧引用就该作废。这个设计看着啰嗦,实际是在救命:截图路线的 Agent 最常见的翻车就是「拿着上一帧的坐标点新一帧的界面」。
第三次,close-app 一个刚写过字的记事本,超时了。因为它弹了「是否保存」的对话框,工具不会替你在这种对话框上按「不保存」。要关这类会二次确认的应用,得先快照、找到按钮、点它,再关。
还有一条不在文档里的:我从脚本里 launch 记事本时,命令一结束窗口就没了。把 launch、快照、写入、截图塞进同一条命令里,才一次跑通。要让窗口长驻,得让它脱离父进程——这在把它接进自己的流水线时会立刻撞上。
什么时候值得装,什么时候别浪费时间
值得的场景很具体:没有 API 的老软件,财务、进销存、老 ERP 客户端这类;Electron 写的桌面客户端;批量填表;把一堆窗口里的数字抄进表格。这类活人做起来烦、脚本写起来脆,元素级的引用刚好补上这个缝。
不值得的场景同样具体。网页自动化别用它,Playwright 更稳也更便宜;自绘界面的程序别指望它,游戏、部分 Qt 和 Flutter 应用根本没有可读的无障碍树,读出来是一片空白;需要精确像素判断的活——验证码、图表读数——它也不适合,它压根不看像素。
钱这块没有悬念:Apache-2.0,完全免费,没有额度这个概念,GitHub 上 11,878 个 star(十一月三日)。真正的成本在你的模型 token 上,装它不花钱,跑起来烧的是 Agent 的上下文,Chrome 那种窗口一次快照就是七千 token 的量级。
替代方案有三条。Python 的 pywinauto 同样走 UI Automation,免费、可控,代价是判断逻辑全得自己写,没有现成的快照和引用体系。Claude 和 ChatGPT 的 computer use 跨平台、开箱即用,但每一步都要过一遍视觉模型,贵且慢。再就是上周写过的 Ghosthand,那是让 Agent 去点一台真 iPhone,场景不重叠。
安全上有一句必须说清:快照、剪贴板、截图、命令输出都可能包含你的私人内容,README 里写得很直白,别往公开日志和上传里放。有辅助功能权限的 Agent,能操作你能操作的一切。
先拿一个只读任务试。 比如让它把某个老软件里的订单号读出来写进 CSV,全程不许点「提交」,跑通二十次再给写权限。
把 skeleton 当第一刀。 先 snapshot --skeleton 看骨架,再对着具体区域用 --root 下钻,比一次拉全树省得多,尤其是 Electron 应用。
给它单独一个 Windows 账号。 这个账号只装它要碰的那几个软件,能打开的东西越少,你出事时能损失的东西也越少。
附:本文信息来源
一、一手信息
项目与版本
- agent-desktop 仓库(README、60 个命令表、平台能力矩阵)
- v1.1.0 发布说明(2026 年 11 月 3 日)
- 安装、权限与平台差异说明
- 官方文档站
- npm 包页(版本号与发布时间)
系统接口
二、媒体报道
- MarkTechPost:Vercel Labs Open-Sources agent-desktop for Agent Computer Use(10 月 31 日)
- DEV Community:Vercel’s agent-desktop Gives Your Coding Agent Hands on the Whole Desktop(对自报数字的逐条核对)
相关阅读
本文为公开信息整理与实测记录,版本号与命令以 npm 与仓库当天状态为准。
原创声明:本文由 618A 情报站整理撰写,基于公开信息与实测记录,转载请注明出处并保留原文链接。