agent-desktop 是做什么的？
agent-desktop 是一个 CLI，让 AI 代理能够通过操作系统无障碍树观察和操作桌面应用程序。它是一个工具，而非代理。每条命令输出一个 JSON 信封（ok、data 或 error）。观察、操作和验证的循环由您自己控制。
Shell 语法
示例使用 POSIX shell。在 PowerShell 中，每个引用都要加引号（'@s8f3k2p9:e1'），因为裸的 @token 是展开运算符。使用 $env:NAME = 'value' 代替 export，使用 | ConvertFrom-Json 代替 $(...) 和 jq。Windows 技能包含 PowerShell 形式。
预检查
在任务的第一个命令之前运行此步骤。这是唯一安装工具的地方。
-
运行
agent-desktop version。退出码为 0 表示 CLI 已存在：跳至步骤 4。 -
如果缺失，通过 npm 安装。npm 是唯一支持的路径：
npm install -g agent-desktop不要尝试 Homebrew、Scoop、下载的归档或旧版本。本技能是针对 npm 解析的任何版本编写的。如果
npm不在 PATH 上，运行node -v和where npm（Windows）或which npm（macOS、Linux）并报告找到的结果。不要猜测其他包管理器。 -
再次运行
agent-desktop version。如果仍然失败，停止并告知用户：安装输出的最后 20 行、agent-desktop --help是否能运行、以及您所在的 OS。不要自行回退到截图或鼠标自动化。 -
运行
agent-desktop status。它会报告平台、权限和supported_surfaces。在 macOS 上，缺少辅助功能授权会在此处显示；告诉用户运行agent-desktop permissions --guide，而不是自行尝试授权。 -
运行
agent-desktop skills get platform。它会加载运行二进制文件的 OS（macOS、Windows 或 Linux）的技能，并且在与本文件冲突时以它为准。 -
关于标志和语法，运行
agent-desktop <command> --help。本技能从不重复标志列表，因此--help始终与安装版本匹配。
如果 agent-desktop skills get desktop 输出与本文件不同的规则，则二进制文件是正确的：本文件是副本，真正驱动的是二进制文件。
循环
当您知道角色或确切名称时使用 find。否则先映射应用程序，然后深入一个区域。
agent-desktop snapshot --skeleton --app "Notes" -i --compact # 浅层映射，截断分支上的子节点数量
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact # 深入一个区域
agent-desktop click @s8f3k2p9:e12 # 对合格引用执行操作
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact # 验证：重新读取同一区域
- 小型应用程序不需要骨架。直接获取完整的
snapshot -i。 -i仅保留交互节点，因此行的静态文本标签会被丢弃。要判断重复按钮属于哪一行，使用--root深入该行的容器并省略-i。在 Windows 和 Linux 上，这会读取该行但不会使其按钮变得可操作：在其他行重复的按钮在窗口中是一个孪生体，其引用会被拒绝（参见“引用”）。--root深入会将引用添加到同一快照 ID。已深入子树外部的引用以及已深入根本身的引用保持有效；已存在于内部的引用会被替换，因此那里的旧引用会返回STALE_REF。- 绝不对表面进行骨架化（
--surface menu、sheet、alert）。表面已经聚焦。 - 打开菜单、表单或警报的操作会将其列在
data.surfaces中。下一步针对该覆盖层。 - 在异步步骤之后，使用
wait（参见references/commands-system.md）。固定的 sleep 是竞态条件。
引用
- 输出引用是限定的：
@<snapshot_id>:e<N>，例如@s8f3k2p9:e1。按原样传递给后续命令。 - 引用仅对一个快照有效。任何 UI 更改后，重新深入受影响的区域或获取新的快照。
- 只有可寻址的元素才能获得引用。静态文本和惰性容器不会。
- 命令在执行操作前会重新识别元素。在 macOS 上，引用携带元素自身的地址，因此相同的孪生体各自保留其引用。在 Windows 和 Linux 上，只有当引用被快照捕获时，其角色、原生 ID、名称和描述在窗口中唯一，并且在快照深度截断或骨架下计数后，仍然恰好有一个活跃元素匹配时，引用才会被解析。那里的相同孪生体没有引用路径：只有
--headed mouse-click --xy X,Y可以选择一个，它会获取前景，而 Linux Wayland 会话会拒绝它。 STALE_REF：元素已消失或不再匹配。details.kind是saved_ref_absent，在 macOS 上是retained_object_stale。获取新的快照并使用新引用。AMBIGUOUS_TARGET：出现了相同的元素（saved_ref_ambiguous），或者引用在捕获时未被证明唯一（identity_not_unique）。重复引用或重新快照相同的孪生体会得到同样的拒绝；对窗口中唯一的控件进行操作。identity_not_unique也发生在快照未能在时间内读取整个窗口时：使用更大的--timeout-ms重新获取。TIMEOUT且details.kind: resolution_identity_unknown：实时读取未响应，因此身份未证明。未发送任何内容；重试。SNAPSHOT_NOT_FOUND：快照 ID 已过期。重新快照。
交付与重试
操作结果携带 data.disposition，错误携带 error.disposition，每个都有 delivery 和 retry。观察命令（如 snapshot）成功时没有处置；它们的错误以及每个 INVALID_ARGS 拒绝携带 not_delivered 和 retry: safe。
- 仅当
disposition.retry为safe时重试或替换操作。只有not_delivered是安全的。 - 任何其他交付值意味着操作可能已生效。重复操作可能会点击、输入或提交两次，而
toggle可能撤销自身。 - 对于不安全的结果，读取实时状态（
get、is或新的快照）并据此判断。details.post_state在可用时很有帮助。 - 根据
error.code和error.disposition进行分支。消息和建议文本可能更改。 details.retryable: false意味着等待无法改变结果。尝试不同的方法。
无头模式与有头模式
默认情况下，引用操作是无头的。它们使用语义化的辅助功能调用，不会获取焦点、移动光标、合成按键或使用剪贴板。如果不存在语义路径，操作会以失败告终。仅在用户明确允许物理输入（如双击、悬停、拖拽或聚焦）时使用全局 --headed 标志。绝不要切换到有头模式来从无头失败中恢复。原始坐标（--xy）绝不意味着获取焦点。哪些操作需要 --headed 因 OS 而异：请阅读平台技能。
参考
仅在需要时加载一个：agent-desktop skills get desktop <reference>。
| 参考 | 何时打开 |
|---|---|
commands-observation | 您需要 snapshot、find、get、is、screenshot、list-surfaces 的语义、部分树或 --root 规则时 |
commands-interaction | 您在 click、type、set-value、select、toggle、scroll、press 和 mouse 命令之间选择，或调试操作错误时 |
commands-system | 您启动或关闭应用程序、管理窗口、使用剪贴板、wait、batch、会话、多代理光标、追踪或加载技能时 |
workflows | 您想要已整理的模式（表单、菜单、对话框、等待新窗口、滚动查找、拖拽）和反模式列表时 |