这一页把 agent-desktop 的一次完整往返走一遍：读界面、动一次、再读回来。
示例用的是 macOS 的 Finder，agent-desktop list-apps 里的任意应用名都可以替换它。
先跑这三条，把「环境是否就绪」和「命令是否写错」分开判断：
agent-desktop status # 平台、权限、支持的界面
agent-desktop permissions # 权限是否给到位（macOS 尤其容易漏）
agent-desktop list-apps # 目标应用是否真的在运行读不到界面最常见的原因不是命令写错，而是权限没给、或者这个应用压根没有发布可访问性树。
status 里的权限状态不正常时，先解决权限再往下走。
1. 观察
-i 只保留可交互元素，每个都带一个 ref。每条命令打印一个 JSON 信封，下面的快照经过裁剪。
agent-desktop snapshot --app Finder -i{
"version": "2.6",
"ok": true,
"command": "snapshot",
"data": {
"app": "Finder",
"window": { "id": "w-204749", "title": "Downloads" },
"snapshot_id": "s8f3k2p9",
"ref_count": 59,
"complete": true,
"tree": {
"role": "window",
"name": "Downloads",
"children": [
{
"role": "treeitem",
"name": "Documents",
"ref_id": "@s8f3k2p9:e8",
"available_actions": ["Click"]
}
]
}
}
}值得注意的几个字段：
| 字段 | 含义 |
|---|---|
snapshot_id |
这次快照的 id。ref 由它和元素序号两段拼成。 |
ref_count |
这棵树里可操作元素的数量。 |
complete |
树是否读全了。为 false 时说明有分支没展开。 |
available_actions |
这个元素此刻允许的动作，是选命令的依据。 |
2. 操作
对上一步结果里的一个 ref 执行动作。默认无头：动作走可访问性 API，既不移动指针，也不夺取焦点。
agent-desktop click @s8f3k2p9:e83. 再观察
一次成功的操作并不能证明界面变了，所以循环以一次读取结束。
agent-desktop snapshot --app Finder -i密集界面：先看骨架，再钻进去
界面元素很多的应用，一次全量快照会淹没上下文。先摸清整体结构，再挑一块深入。
agent-desktop snapshot --skeleton --app Slack -i --compact # 整体骨架
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact # 深入其中一块区域--compact 去掉空格与冗余字段，--skeleton 只保留结构。
两种模式的区别见骨架与下钻。
有多个窗口时
同一应用开了多个窗口，用 --app 选目标会返回 AMBIGUOUS_TARGET，并把候选窗口 id 放在
error.details 里。这是目标选择歧义，和 ref 身份歧义不同；用 --window-id 指定其中一个：
agent-desktop snapshot --app Finder --window-id w-204749 -i需要物理输入时
全局 --headed 标志才允许物理输入——移动真实指针、按下真实按键。无头调用依然禁止激活前台窗口和合成输入。
单条命令接受哪些参数由它自己的 --help 说明，不要凭记忆猜：
agent-desktop --headed mouse-click --helpPowerShell 用户
每个 ref 都要加引号。不加引号的 @token 在 PowerShell 里是散裂（splatting）运算符，命令会被静默改形。
agent-desktop click '@s8f3k2p9:e8'