dym-agent-desktop-drive 是一个用于驱动 macOS 桌面应用的技能，基于 agent-desktop 工具，采用 skeleton → drill → act → verify 的工作流程，并支持在多次 CLI 调用之间保持 @snapshot:eN 引用有效。
适用场景
当需要读取或操作某个 macOS 桌面应用（原生应用，或开启了 AX 的 Electron 应用），操作涉及多个步骤，并且希望引用不会中途失效时，可以使用本技能。它也适合需要“已点击正确元素”的证据、而不是盲目坐标的场景。
如果是纯浏览器内的网页，应先查看 /dym-agent-desktop route，通常 playwright 或 CDP 成本更低。
使用方式
前置设置：AD=<二进制路径>，export AGENT_DESKTOP_HOME=<绝对路径>。
快照前先锁定窗口。应用有多个窗口时，snapshot --app 会返回 AMBIGUOUS_TARGET 并附带候选列表（这是特性而非错误）：
$AD list-windows --app "Microsoft Teams" $AD snapshot --window-id w-9249 --skeleton -i --compact
先骨架、后下钻，仅在应用结构较厚时使用：
$AD snapshot --app "System Settings" --skeleton -i --compact # 实测：4630 B，27 ref $AD snapshot --root "@s23de9t04j589e:e5" -i --compact # 只展开所需区域
结构稀疏的应用（Finder、Calculator、TextEdit）可跳过骨架，直接 snapshot。
已知名称或 role 时，用 find 成本最低，无需 snapshot：
$AD find --app "System Settings" --role button --name "Sound" --exact --limit 2
使用完整 ref @<snapshot_id>:e<N> 执行动作，始终加引号，因为 shell 中的冒号：
$AD click "@s23de9t04j589e:e12" $AD set-value "@s23de9t04j589e:e2" "text" $AD toggle "@s23de9t04j589e:e6" # 或 check/uncheck（幂等） $AD select "@s23de9t04j589e:e4" "Option B"
默认 headless：走语义 AX 路径，不抢占焦点、不移动鼠标、不合成按键。需要真实输入或拖拽时，全局加 --headed： $AD --headed drag --from "@s..:e1" --to "@s..:e5"。
等待状态而不是 sleep：
$AD wait --element "@s..:e5" --predicate actionable --timeout 5000 $AD wait --text "Done" --app "App" --timeout 5000 $AD wait --menu --app "App" # 等待菜单展开
验证时重新下钻已变更的区域。其他区域的 ref 仍然有效（作用域失效），无需重新快照整个应用。
当步骤之间不依赖中途观察时，可一次批量执行多条命令：
$AD batch '[{"command":"list-surfaces","args":{"app":"System Settings"}},{"command":"clipboard-get","args":{}}]' --stop-on-error
实测：2 条命令耗时 629 ms，max_entries: 64，max_input_bytes: 1 MiB。
规则
退出码：0 成功 · 1 结构化错误 · 2 参数错误（三者均实测）。应依据 error.code 分支，而不是 error.message——仓库自述 message/suggestion 可能在不同版本间变化。
引用跨进程持久：上一条命令取得的 snapshot 在下一条命令中仍可解析，因为 refmap 写入 $AGENT_DESKTOP_HOME/snapshots/<id>/refmap.json（实测：几分钟前、另一进程取得的 ref 仍可 get）。这是与 orca computer element-index（仅在单次返回内有效）的平台差异。
引用索引错误 → STALE_REF（rc=1）并附带 recovery.strategy；snapshot_id 不存在 → SNAPSHOT_NOT_FOUND。绝不要猜测下一个索引。
常见错误码：PERM_DENIED（授权后重开终端）· AMBIGUOUS_TARGET（锁定 --window-id 或加 --exact）· ACTION_NOT_SUPPORTED（换其他命令）· POLICY_DENIED（处于 headless 但需要 --headed）· TIMEOUT（先读 error.details.kind 再放宽超时）。
点击返回 receives_events + occluder: {...} 表示有元素遮挡。应先把窗口置前或移除遮挡物，不要盲目重试。
Electron 未开启 AX 时两个工具都会失效。在 Microsoft Teams 上实测：orca computer 看到 5 个节点，agent-desktop 看到 ref_count: 4——都停在 “Web content” 边界。出路：launch --cdp（仅在可接受重启应用时）然后使用 CDP 客户端。
需要细节时，完整原始文档来自二进制本身：$AD skills get desktop --full（包含 SKILL 和 5 个参考文件）。不要把它们复制进仓库。