macOS 上 agent-desktop 走系统的 AX API。前提是「辅助功能」权限：授予运行 agent-desktop 的 那个应用（Terminal、iTerm2、Warp、VS Code 或智能体宿主），不是二进制文件本身。
系统要求
macOS 13 或更高，Intel 或 Apple Silicon 都可以。
授予权限
agent-desktop permissions # 只报告状态
agent-desktop permissions --request # 让系统弹出授权请求
agent-desktop permissions --guide # 打开系统设置并给出引导面板--guide 只覆盖辅助功能与屏幕录制。自动化权限需要 --request 触发，
没有弹窗时它报 unknown。路径是 系统设置 → 隐私与安全性：把启动 agent-desktop 的应用
勾进「辅助功能」；截屏需要「屏幕录制」；打开通知中心需要允许该应用控制 System Events。
没有权限时
可能返回 PERM_DENIED，也可能只是读不到界面或读数稀疏。先跑一次：
agent-desktop permissionsaccessibility 不是 granted 时先解决权限，再怀疑命令写错了。授权后不需要重启终端，
下一次调用就会看到新的状态。
Dock 与菜单栏
外壳界面这一层，macOS 上可以打开的是 Dock 与菜单栏附加项：
agent-desktop open-system-surface --help--help 会列出当前支持的名字。应用自己的菜单用 --surface menubar，
sheet、popover、alert 等界面用 list-surfaces 查看。见界面。
能力表
| 能力 | 状态 |
|---|---|
| 可访问性树 | 支持 |
| 点击 / 输入 / 键盘 | 支持 |
| 鼠标输入 | 支持（双击、三击、拖拽需要 --headed） |
| 截图 | 支持，需要「屏幕录制」 |
| 剪贴板 | 支持 |
| 应用与窗口管理 | 支持 |
| 通知 | 支持，通知中心需要 System Events 的自动化权限 |
| 外壳界面 | 窗口、菜单、menubar、sheet、popover、alert、Dock、菜单栏附加项 |
--headed 下点击、输入和滚动以物理事件优先。launch 接受显示名或 bundle ID。
ref 携带元素自己的地址，同名「删除」按钮各自作用于自己那一行；元素被移除或应用重启后
ref 返回 STALE_REF，不会退化为按外观重新查找。规则见快照与 ref。
这台机器上的完整能力表由二进制自己给出：
agent-desktop skills get platform