agent-desktop 是一个面向 macOS、Windows 和 Linux 的 CLI 与 C 库。它读取操作系统提供的可访问性树，把界面里智能体能够操作的每一个元素变成一个带 ref 的 JSON 节点。智能体对某个 ref 执行一次操作，然后再快照一次来确认结果，全程不做像素匹配，控制循环始终留在你自己的智能体里。
npm install -g agent-desktop
agent-desktop status # 平台、权限、支持的界面
agent-desktop skills get desktop # 智能体应该先读的指南它是什么，不是什么
智能体调用的工具
观察—操作—验证的循环由调用方（你的代码或 LLM 循环）持有。它只负责把界面变成可寻址的数据，再把一次动作落下去。
内部没有模型
不内嵌 LLM，不联网推理。每条命令打印一个 JSON 信封然后退出，输出完全可预测，也完全可脚本化。
只管桌面应用
网页自动化请用 agent-browser：它走 Chrome DevTools 协议读网页，agent-desktop 只读操作系统的可访问性树。对于你自己启动的 Chromium 或 Electron 应用里的网页内容，agent-desktop 会开一个 DevTools 端口让 agent-browser 用 --cdp 连上去。
只看得见应用愿意暴露的
它读可访问性树，不做像素匹配，所以一个不发布可访问性树的界面，它同样读不到。
四步循环
智能体先把应用摸清，再钻进需要的那块区域，对一个 ref 执行动作，最后把结果读一遍。
agent-desktop snapshot --app gnome-calculator --skeleton -i --compact # 1. 摸清整体骨架
agent-desktop snapshot --root @s2txcl95uv:e1 -i --compact # 2. 展开其中一块区域
agent-desktop click @s2txcl95uv:e11 # 3. 按下按钮 7
agent-desktop wait --element @s2txcl95uv:e11 --predicate value --value 7 # 4. 核对显示的是 7一次成功的操作并不能证明界面真的变了，所以循环的最后一步永远是一次读取。
ref 自带产生它的那次快照的 id，规则见快照与 ref，
前两条命令的解释见骨架与下钻。
怎么实现的
从调用方到被操作的应用，中间只有这一条链：
- 调用方 —— 你的代码或 LLM 循环，运行一条命令并读取它打印的 JSON 信封。
- agent-desktop CLI，或者在进程内直接调用时的 C 库。
- agent-desktop-core —— 命令、
RefStore和快照构建。core 定义了PlatformAdaptertrait 和所有共享类型。 PlatformAdapter—— core 触达操作系统的唯一途径。- 一个平台 crate ——
agent-desktop-macos、agent-desktop-windows或agent-desktop-linux。 - 操作系统的可访问性 API —— macOS 的 AX API、Windows 的 UI Automation、Linux 的 AT-SPI。
- 应用本身，通过上面那个 API 暴露它的界面。
core 永远不 import 任何平台 crate，平台 crate 之间也互不 import。只有 CLI 和 C 库把一个平台 crate 接到 core 上，并且在编译期就选定，所以一个二进制只能驱动它构建时所属的那个操作系统。
平台支持
| 能力 | macOS | Windows | Linux |
|---|---|---|---|
| 可访问性树 | 支持 | 支持 | 支持（AT-SPI） |
| 点击 / 输入 / 键盘 | 支持 | 支持 | AT-SPI；X11 / GNOME 按键 |
| 鼠标输入 | 支持 | 支持 | X11，--headed |
| 截图 | 支持，需要「屏幕录制」 | 支持 | X11 窗口；Wayland 门户 |
| 剪贴板 | 支持 | 支持 | 支持；Wayland 需要 wl-clipboard |
| 应用与窗口管理 | 支持 | 支持 | 启动/列出；X11 窗口控制 |
| 通知 | 支持；通知中心需要 System Events 的自动化权限 | 支持 | GNOME Shell |
| 外壳界面 | Dock、菜单栏附加项 | 任务栏、系统托盘、开始菜单、操作中心 | 仅 system-tray 与 action-center 可用 |
CLI 在每个平台上都是同一套 60 个命令名。运行在你这个平台上的完整能力表，由
agent-desktop skills get platform 直接输出。