agent-desktop

把桌面编译成 Shell 原语：拆解 vercel-labs/agent-desktop

项目背景与痛点

Agent 能写代码、能调 API，但它本质上仍是一个“只会调用工具的推理核心”。当任务落到桌面软件上——改一份 Excel、在 Figma 里拖个图层、点开某个只有 GUI 的老旧内部系统——整套优雅的工具链会瞬间失效。

过去两年主流解法有两条：一是接 Playwright、Puppeteer 这类浏览器自动化，但覆盖面被限制在 Web；二是直接用厂商的 computer-use 模型，把截图丢给视觉模型让它输出坐标，这条路线昂贵且脆弱。更根本的矛盾在于：绝大多数 Agent 运行时只暴露一个能力——执行 Shell 命令。MCP 也好、Function Calling 也罢，最终都要落到一次进程调用上。

agent-desktop 针对的正是这个缺口：它不做模型、不做编排，只把“用电脑”这件事抽象成一组可被 Shell 调用的原语。Agent 不需要理解 Accessibility API，不需要安装 SDK，只要能调用 exec，就能截图、点击、输入、滚动。

核心技术揭秘

从“Computer use CLI”这个定位推断，它的本质是一层平台抽象加上系统 API 封装。

感知侧走两条路：像素级截图，和语义级的辅助功能树（macOS 的 AXUIElement、Linux 的 AT-SPI）。截图负责让 Agent“看得见”，AX 树负责让 Agent“点得准”——直接按角色和标题定位元素，比让模型猜像素坐标稳定得多。

动作侧是输入事件合成：macOS 落到 CGEvent，X11 落到 XTEST，Wayland 下则只能退到 uinput、ydotool 这类内核级注入。这层最难的地方不是调用系统接口，而是坐标系换算：Retina 屏下截图是物理像素（2x），事件坐标却是逻辑点；多显示器还要处理负坐标与主屏偏移。任何一处换算错误，都会表现为“点偏了 8 像素”这种模型永远无法排查的细节问题。

CLI 的设计哲学大概率是无状态、单次调用、结构化输出：每个命令独立进程、独立连接，不保留 session；返回 JSON 而非自由文本，便于模型解析。最值得称道的一点是截图返回值——给文件路径而不是 base64。一张 1080p 截图转 base64 是几十万 token 的量级，足以占满上下文窗口；返回路径让模型按需读图，这是真正理解 Agent 成本的设计。

功能亮点与差异

与 self-operating-computer 这类项目相比，差异不在功能，而在形态。

其一，协议无关。它不绑定任何 Agent 框架，Claude、GPT、本地模型都能使用。MCP server 需要宿主支持协议，而 CLI 只需要一次 child_process。这是尽可能覆盖更多场景的通用方案，也是适用范围最广的方案。

其二，语义与像素双轨。纯视觉方案对 UI 改版、深色模式、动态渲染极其敏感；引入 AX 树后，click --role button --title "保存" 这类调用天然具备一定鲁棒性，成本还比消耗视觉 token 更低。

其三，可组合。Shell 原语能被管道、脚本、CI 复用，Agent 之外的人类也能拿来做 RPA。这让它具备“先当工具、再当 Agent 能力”的渐进式落地路径，而不是一上来就要求重构工作流。

应用场景与落地建议

最适合的是桌面 Client 的自动化回归测试，以及跨应用的数据搬运：从只有 GUI 的内部系统导出报表，再交给下游脚本处理。它同样适合作为 Agent 的兜底方案——当目标系统没有 API 时，用它来完成最后的操作。

生产环境要提前处理的问题：

• 权限：macOS 必须授予“辅助功能”和“屏幕录制”，首次授权需要人工点击，无法在无人值守的 CI 里静默完成；应用签名变化会导致授权失效，这是运维层面的重大风险。
• 隔离：桌面只有一个焦点窗口，并发运行的 Agent 会互相抢占鼠标键盘。一个 Agent 对应一台虚拟机或一个用户会话，不要指望进程级隔离。
• 不确定性：坐标点击天然脆弱，应优先用元素定位；每次动作后接一次截图校验，把“做没做成”的判定权交回模型，而不是信任命令的退出码。
• 残留状态：长按、拖拽一旦中断，会留下按键按下状态。建议在调用层做“释放所有按键”的保底处理。

综合评价

优点很鲜明：接口极小、零 SDK 依赖、token 友好、跨框架通用，把一个繁重的任务拆成了 Agent 能直接消化的原子操作。它不追求“智能”，只追求“可靠地被调用”——在 Agent 工具链普遍过度设计的当下，这种克制反而稀缺。

短板同样明显：能力上限受制于操作系统的可访问性接口，Linux 侧尤其 Wayland 下的支持注定严重碎片化；缺少事务语义与回滚，一次误点可能就改坏生产数据；安全模型基本空白——任何能执行它的进程都等同于拿到这台机器的键鼠控制权，这在多租户环境里是严重缺陷。

一言以蔽之：它不是让 Agent 变聪明的方案，而是让 Agent 的操作能力真正覆盖桌面的基础设施。值得放进工具箱，但别指望它替你做判断。