用途 该技能适用于需要操作 macOS 桌面应用（GUI）而非网页的任务：打开应用并下发任务、点击按钮、在输入框输入、滚动阅读、向桌面应用发送提示词，或检验某个智能体能否操作屏幕。当某个 computer use 工具开始返回与窗口相关的异常错误时，也建议先按本文档的预检流程排查。文档覆盖工具选型、避免误诊的预检步骤，以及导致辅助功能树看似损坏的常见陷阱。
使用前预检
- 屏幕必须处于解锁状态：运行 python3 scripts/session-lock-check.py 查看 LOCKED/UNLOCKED 与空闲秒数。锁定状态下前台进程为 loginwindow，应用窗口不可见，多个独立工具同时以相似错误失败通常说明是会话问题而非应用问题。
- TCC 权限属于发起进程而非 shell。辅助功能为必需，屏幕录制仅用于截图，自动化仅用于操作 System Events。状态显示已授权不等于树可读取，需用 scripts/ax-probe.py 直接探测或通过快照确认。
- 确认是否有人在场：HIDIdleTime 很长且前台为 loginwindow 时不应继续操作，应说明缺失条件并停止。
工具选型
- 按语义操作任意 GUI 应用：agent-desktop，默认无头运行，返回稳定元素引用，并说明动作是否送达。
- Discord 桌面端频道或线程：agent-desktop 配合 discord-desktop 参考文档。
- Dia 浏览器：不使用辅助功能，改用 CDP（--remote-debugging-port=9222）。
- LinkedIn 发布或存草稿：CDP + linkedin-compose 参考。
- 视觉截图与按索引点击：computer_use（cua-driver），后台输入不抢焦点。
- 浏览器、用户会话、DOM 或 JS：CDP 或 Playwright。
- 无辅助功能树的应用（游戏、画布、Dia）：截图加坐标，无语义验证。
- 并行读取大量公开页面：Lightpanda，不适用于需登录或反爬的站点。
观察—操作—验证循环 这些工具本身不是智能体，只返回状态并执行单个动作，循环由调用方实现。典型流程：先取骨架快照，再用 --root 下钻某个区域，执行点击，然后重新读取同一区域验证。引用仅在单个快照内有效，遇到 STALE_REF、AMBIGUOUS_TARGET、SNAPSHOT_NOT_FOUND 应重新取快照而非重试旧引用。仅在 disposition.retry 为 safe（通常是 not_delivered）时重试；其他送达状态意味着动作可能已生效。不要只信 ok，需通过 get、is 或新快照再次确认。
安全规则 默认无头运行；仅在用户明确授权时使用 --headed。绝不输入密码、2FA 验证码或银行卡数据；需要登录时由用户自行完成。操作前先读取，不关闭用户应用、不写入真实文档、未经许可不从用户账号发送消息。测试应使用中性应用，快照含屏幕文本，应保存在临时目录。
主要陷阱 应用名可能被本地化，launch 与 --app 名称不一致会导致 APP_NOT_FOUND。contenteditable 输入框上 type 可能无效，可改用 set-value 或带界面的 type。滚动可能返回失败但实际已滚动，应通过观察新内容验证。Electron/Chromium 应用的 --skeleton 可能返回空映射，此时应取完整树并在代码中过滤。osascript 统计窗口数在无权限时静默返回 0，不可作为无窗口的证据。全局清单是 agent-desktop 的脆弱环节，全局命令失败而指定应用命令正常时通常属于此问题。密集应用应先用骨架快照再下钻。launch 不一定会将应用置前，需要焦点时使用 --activate。第三方未公证二进制可在终端运行但会被 spctl 拒绝，应在报告中说明。
随附支持 脚本包括会话锁检查、辅助功能探测、强制启用 AXManualAccessibility、Discord 频道读取与历史滚动、X 时间线滚动去重。参考文档涵盖 agent-desktop、应用配方、Discord、Dia 浏览器、LinkedIn 草稿、Lightpanda 以及各命令的实测延迟与上下文成本。
限制 文档测量环境为特定时间的 macOS 版本与 arm64 架构，未提供跨平台支持说明；许多行为与具体应用和系统权限相关，缺失信息未在资料中给出。