agent-desktop 是一个命令行工具（CLI），它让 AI 智能体通过操作系统的无障碍树（accessibility tree）观察和操作桌面应用。官方明确说明它本身是工具而非智能体：每条命令输出一个 JSON 信封（ok、data 或 error），观察、操作、验证的循环由调用方执行。
用途与定位 它用于在 macOS、Windows 和 Linux 上操作桌面应用。首次运行时，先执行 agent-desktop status 查看平台、权限与 supported_surfaces，再执行 agent-desktop skills get platform 加载当前操作系统的技能说明。各命令的参数与语法可通过 agent-desktop <command> --help 查看。
主要能力 观察方面，提供 snapshot（快照）、find（按角色或名称查找）、get、is、screenshot、list-surfaces 等命令。snapshot 支持 --skeleton 浅层映射（截断分支上带 children_count），也支持 --root 钻取某一区域；--surface（menu、sheet、alert）不适用 skeleton，因为 surface 本身已聚焦。 操作方面，覆盖 click、type、set-value、select、toggle、scroll、press 及鼠标命令。输出引用带限定符，格式为 @<snapshot_id>:e<N>，例如 @s8f3k2p9:e1，可直接传给后续命令。引用只对一次快照有效；UI 变化后需重新钻取受影响区域或重新快照。只有可寻址元素才有引用，静态文本和惰性容器没有。 系统性能力包括启动与关闭应用、窗口管理、剪贴板、等待、批处理、会话、多智能体光标、追踪与加载技能。异步步骤后应使用 wait，固定 sleep 属于竞态。
使用方式与安全语义 操作结果带 data.disposition，错误带 error.disposition，各自含 delivery 与 retry。只有 not_delivered 才是安全重试；其他 delivery 值意味着操作可能已生效，重复执行可能造成二次点击、输入或提交，toggle 甚至可能自行撤销。遇到非安全结果时应读取实时状态（get、is 或新快照）再决策，details.post_state 在有提供时可作参考。错误处理应基于 error.code 与 error.disposition 分支，message 与 suggestion 文本可能变化；details.retryable: false 表示等待无法改变结果。
无头与有头模式 引用操作默认无头，使用语义化无障碍调用，不抢焦点、不移动光标、不合成按键、不使用剪贴板；若无语义路径则失败关闭（fail closed）。只有在用户明确允许物理输入（如双击、悬停、拖拽、聚焦）时才使用全局 --headed，且不得用 --headed 来恢复无头失败。原始坐标（--xy）从不隐含焦点。哪些操作需要 --headed 因操作系统而异，需查阅平台技能。
适用场景 当 AI 智能体需要查看或操作桌面应用界面时使用，例如在已知角色或精确名称时用 find，否则先映射应用再钻取单一区域。操作打开菜单、sheet 或 alert 时，结果会在 data.surfaces 中列出该覆盖层，下一步应针对它操作。
限制与注意事项 引用一次性有效，过期会报 SNAPSHOT_NOT_FOUND；目标不唯一会报 AMBIGUOUS_TARGET，需用 find --role --name --exact 或 --root 收窄后再用新引用；引用失效会报 STALE_REF，需重新快照。示例默认使用 POSIX shell；PowerShell 中需为每个引用加引号（如 '@s8f3k2p9:e1'），因为裸 @token 是 splatting 运算符，并用 $env:NAME = 'value' 代替 export、用 | ConvertFrom-Json 代替 $(...) 与 jq。参考文档（commands-observation、commands-interaction、commands-system、workflows）按需通过 agent-desktop skills get desktop <reference> 加载，其中 workflows 提供表单、菜单、对话框、等待新窗口、滚动查找、拖拽等范例及反模式清单。