agent-desktop
vercel-labs/agent-desktop加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你让 Claude Code 或任意 CLI 型智能体"帮我把桌面版 Excel 里的这张表另存为 PDF"。传统做法是截图 + 视觉模型识别像素坐标 + 模拟鼠标点击——慢、脆、还容易点错。agent-desktop 换了个思路：它去问操作系统"这个窗口里都有哪些可交互元素"，把答案变成带稳定引用（ref）的 JSON，智能体直接对引用发指令，再读一次界面确认结果。
截至 2026 年 11 月，这个项目在 GitHub 上已收获 10,354 stars、694 forks，npm 包周下载量约 12,834 次，由 Vercel Labs 团队于 2026 年 2 月创建并在半年内快速迭代到 v1.1.0。
市面上大量桌面自动化方案都走像素路线——截图、目标检测、算坐标、模拟点击。视觉模型进步后这条路可行性上升，但它有结构性缺陷：坐标会漂、分辨率会变、控件会重排、每一步都要把整屏喂给模型，token 成本高且延迟大。
agent-desktop 押注的是另一条路：操作系统的无障碍（accessibility）接口。macOS 的 AX API、Windows 的 UI Automation、Linux 的 AT-SPI 都会把应用的界面结构化暴露出来——控件类型、名称、值、可执行动作。拿到这棵树，元素定位就从"猜像素"变成"查语义"。
这带来一个关键设计取舍：它读的是无障碍树，不做像素匹配，所以看不见没有发布无障碍树的界面。官方文档说得很直白：效果取决于目标应用自己把界面做得多好。对自绘控件的游戏、Canvas 渲染的编辑器，它就是无能为力。
把智能体比作一个远程操作员：
关键在于引用的时效性。agent-desktop 给每个快照分配一个 snapshot_id，所有 ref 都带着它（@s8f3k2p9:e8 而不是裸的 @e8）。一旦界面变化导致元素找不到或匹配到多个，返回 STALE_REF 或 AMBIGUOUS_TARGET——失败即拒绝，绝不瞎猜。这种"fail-closed"的设计在自动化工具里并不常见，但恰恰是它最专业的地方。
agent-desktop snapshot --app Finder -i # 1. 读界面，拿到带 ref 的元素清单
agent-desktop click @s8f3k2p9:e8 # 2. 对 ref 发动作
agent-desktop snapshot --app Finder -i # 3. 再读一次，确认结果
文档里有一句很克制的话："一次成功的动作并不证明界面变了。" 所以循环的终点必须是一次读取，而不是一次点击。这是把"我认为操作成功了"和"界面确实变了"分开的关键。
密集应用（如 Slack）还支持分层探索：先用 --skeleton 拿浅层骨架，再用 --root @ref 只钻进需要的区域，避免整棵树撑爆上下文。
| 分组 | 代表命令 |
|---|---|
| 观察 | snapshot、find、get、is、screenshot、list-surfaces |
| 按 ref 操作 | click、double-click、type、set-value、focus、select、toggle、expand、scroll |
| 键鼠 | press、hover、drag、scroll-to、mouse-move |
| 应用与窗口 | launch、close-app、list-apps、list-windows、focus-window、resize-window |
| 通知 | list-notifications、dismiss-notification、notification-action |
| 剪贴板 | clipboard-get、clipboard-set、clipboard-clear |
| 系统 | status、permissions、version、batch、skills |
其中 key-down/key-up/mouse-down/mouse-up 四个命令故意失败关闭（fail closed）——它们需要常驻守护进程才能释放按住的键，在守护进程就绪前一律拒绝执行。
默认所有操作走无障碍 API 完成，不移动指针、不夺取焦点，不会打断你正在做的事。要物理鼠标输入才需要显式加全局 --headed 开关。macOS 上还额外用"私有命令宿主"保留原生无障碍对象，避免行被删除后同 ID 的幸存行被错误命中。
这是个很有意思的设计：agent-desktop skills get desktop 会把配套的使用指南直接从二进制里吐出来，版本永远和工具本身匹配。仓库里还提供了 skills/ 目录（desktop / macos / windows / linux / ffi 五个技能），可以一行命令装进智能体框架：
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
也就是说，它的"说明书"和它的"实现"打包在同一个 npm 包里，永远不会脱节。
除了 CLI，每次 release 还附带 libagent_desktop_ffi（macOS/Linux/Windows），可以进程内直接调用，不用为每条命令付一次进程启动开销：
import ctypes
lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
lib.ad_adapter_create.restype = ctypes.c_void_p
平台差异被完整矩阵化：macOS 用 AX API，Windows 用 UI Automation，Linux 用 AT-SPI；Linux 还额外区分 X11 与 Wayland（Wayland 下指针输入被拒绝、窗口控制不支持，需 GNOME Mutter RemoteDesktop）。
低。 一条 npm 命令即可：
npm install -g agent-desktop
agent-desktop version
中。 系统权限是主要摩擦点，这是无法回避的：
agent-desktop permissions --guide 直接跳到系统设置的缺失项at-spi2-core；主目标 Ubuntu 24.04 + GNOME 46（glibc 2.35 下限）。SSH 或纯 TTY 环境拿不到会话总线，直接不可用开发侧：Rust workspace，需要按宿主系统裁剪包集——三个平台适配器只在各自系统编译，裸跑 cargo build 会在所有平台失败：
HOST_PKGS=(-p agent-desktop-core -p agent-desktop-macos -p agent-desktop -p agent-desktop-ffi)
cargo test "${HOST_PKGS[@]}"
一、不是通用替代品。 它明确定位为"桌面应用"工具，不做网页自动化（网页交给姊妹项目 agent-browser）。虽然对 Chromium/Electron 应用有 DevTools 端口衔接，但那是另一条路径。
二、依赖被控应用的配合度。 无障碍树是应用主动暴露的。自绘 UI、游戏、Canvas 渲染界面在它眼里就是一片空白。这不是 bug，是路线选择的必然代价——但也意味着它的实际覆盖率取决于目标应用生态。
三、权限与安全负担。 能读剪贴板、读通知、截图、操作任意窗口——这在生产环境是把双刃剑。项目自身也反复警告：快照、剪贴板、截图、调试产物都可能包含桌面隐私内容，不要进公开日志或上传。可选的 JEV 辅助技能会把屏幕描述发给模型提供商，需要单独配置。
四、跨平台语义差异是硬骨头。 CONCEPTS.md 里有一整套"证据三态"（Known / Absent / Unknown）规范：读失败必须和"确实没有"区分开，否则一个从未应答的目标会被误判为通过完整性检查。角色映射上 macOS 的 toggle 是 button + pressed，Windows 是 switch + checked，Linux 是 checked。这类差异工程量极大，也说明这个项目的门槛在"系统级细节"而不在"模型能力"。
五、生态仍是早期。 npm 周下载 12,834 次、贡献者约 900 人（GitHub contributors 接口显示 9 页 × 100），star 数很高但实际装机量与 star 比例说明它还处在"技术圈爆红、生产环境谨慎试用"阶段。
agent-desktop 代表了 computer use 从"视觉优先"转向"语义优先" 的路线分岔。
当模型本身足够强、上下文足够大时，让智能体"看屏幕猜坐标"是可行的通用方案；agent-desktop 则押注更工程化的一端：给智能体一个确定性的、可验证的、失败即拒绝的桌面接口。它把智能体从"消费者"变成"客户端"——智能体负责决策和循环，工具负责提供可靠的系统原语。
这也解释了为什么它把 observe-act-verify 循环"留给调用方"而不是内置 Agent：它刻意不做 Agent，以免与上层框架抢活。这与当前 Agent 工具生态的分工趋势完全一致。
从更长的视角看，当 Codex、Claude Code 这类终端型智能体开始需要碰真实桌面软件（填表格、点确认、调系统设置），一个跨三平台、原生级、无头优先的语义接口层，其价值可能远超一个又一个视觉 demo。
如果你在构建桌面自动化智能体，agent-desktop 值得认真评估：它不是又一个 Agent 框架，而是一层扎实的系统原语。工程成熟度在开源项目里属上游水平——80+ 测试文件、CodeQL、供应链审计、三平台 E2E、docs/solutions/ 里沉淀了几十条真实踩坑记录（含"AT-SPI 返回成功并不代表状态改变了"这类血泪教训）。
上手建议：先在一台有 GUI 的机器上 npm install -g agent-desktop，跑 agent-desktop status 看权限是否就绪，再用 agent-desktop skills get desktop 把官方指南喂给你的智能体。别一开始就指望它读懂所有应用——挑一个无障碍树完备的桌面应用（Finder、计算器、IDE）先跑通三步循环。