agent-desktop-macos 是 agent-desktop CLI 的 macOS 平台专属技能说明，用于在 macOS 上执行桌面自动化。使用前应先阅读核心技能（agent-desktop skills get desktop），了解「观察—操作—验证」循环；本技能只介绍 macOS 上与其他平台不同的部分，常见症状与修复方法见 references/troubleshooting.md。
环境要求 需要 macOS 13 或更高版本，Intel 或 Apple Silicon 均可。需要为启动 agent-desktop 的应用（如 Terminal、iTerm2、Warp、VS Code、Codex）授予「辅助功能」权限；如果系统设置中单独列出了 agent-desktop 二进制文件，也需为其授权。「屏幕录制」权限仅在截图和 session start --screenshots artifacts 时需要。「自动化」权限针对 System Events，仅在命令报告缺失时授予。
首次配置 运行 agent-desktop status，其中包含权限报告与状态根目录。运行 agent-desktop permissions 查看 accessibility、screen_recording、automation 三项状态（granted、denied、not_required 或 unknown），被拒绝的项会附带建议。若某项被拒绝，运行 agent-desktop permissions --request 弹出系统提示；随后在「系统设置 > 隐私与安全性 > 辅助功能」中打开启动应用的开关，并重启该应用（运行中的进程不会获取新授权）。最后运行 agent-desktop snapshot --app Finder -i 确认。注意 permissions 本身不会弹窗，--request 可以弹窗（包括 Automation）；Automation 在 macOS 需要弹窗时会报告 unknown。
macOS 的差异 默认无头模式：ref 操作仅使用辅助功能动作，不抢占焦点、不移动光标、不发送按键、不写剪贴板。仅在需要物理输入时添加全局 --headed 标志。在 --headed 下，click、right-click、type、clear、scroll 以物理输入优先；expand、collapse、set-value、select、toggle、check、uncheck、focus、scroll-to 仍保持语义化；双击、三击、悬停和拖拽必须使用 --headed；--xy 原始输入不会改变焦点。判断操作是否生效应靠再次观察，因为 AX 返回码不能证明效果。
界面表面：用 list-surfaces --app "App" 查看已打开内容；菜单、表单、警告或弹出层打开时，用 --surface menu|sheet|alert|popover 快照；菜单栏用 --surface menubar。覆盖层关闭后需重新快照窗口。
菜单：无头右键使用 AXShowMenu；若菜单已打开但应用返回 APP_UNRESPONSIVE 且 retry: unsafe，不要重试。组合框与菜单按钮用 select @ref "Option"，且需先关闭已打开的菜单。
通知中心：list-notifications、dismiss-notification、dismiss-all-notifications、notification-action 通过辅助功能操作系统通知中心；所有变更操作需 --headed，仅当中心已打开时列表可在无头下工作。单个关闭或操作时应传 --expected-app 与 --expected-title，因为索引会随堆栈变化；对会消失的横幅可用 wait --notification --app "App"。
Chromium 与 Electron：辅助功能是默认路径，也是原生界面和已运行应用的唯一路径；需要时自动启用渲染器的 Web 辅助功能。全新启动可用 launch "App" --cdp 暴露 DevTools 端口；密集运行的应用可先用 snapshot --skeleton -i --compact 再以 --root @ref 深入。
标识与按键：launch 接受显示名称或 bundle ID，其他命令通过 --app 传显示名称；窗口 ID 在窗口生命周期内有效，可用 list-windows 查找。主修饰键为 cmd；cmd+q 等退出快捷键默认返回 POLICY_DENIED，需 --force 才可执行，退出应用应使用 close-app。标点键可用符号或名称表示。
光标叠加层：cursor-overlay enable 在点击穿透窗口中绘制代理光标，不移动系统指针；--image 与 --pointer-image 仅接受 PNG（最大 2 MiB、每边最多 1024 像素），无效图像回退为箭头。命令失败时可查阅 troubleshooting 文档定位症状。