用途
本技能用于让 Claude Code 驱动、测试或自动化原生 macOS 应用，覆盖端到端场景，例如在 Mac 应用上复现 Bug、运行 AI 驱动的 UI 测试、演示特定 Mac 应用等。其触发症状包括：用户要求驱动/测试/演示某个 Mac 应用；测试判定标准是视觉性的（如“错误横幅是否显示”“图表是否与设计稿一致”）；Bug 复现需要每步截图证据；布局动态变化，单一谓词无法覆盖所有状态。
不适用场景：目标是 iOS（应使用 iOS WDA 技能，端口 8100）；已有该应用的 Xcode 项目访问权限（应直接编写 XCUITest）；用户希望在同一台 Mac 上跨应用编排（Mac2 每台机器仅支持单会话）。
主要能力
- 元素定位与操作：通过 macOS 辅助功能树查找元素并执行点击、输入、拖拽、按键等操作。定位策略按速度从快到慢为：accessibility id、class name、-ios predicate string、-ios class chain、xpath。
- 截图与视觉判断：通过辅助脚本截图，Claude Code 直接读取图像进行判断，无需外部 LLM 调用或 API 密钥。
- 等待与状态探测：提供 wait、wait-not、exists、attr 等命令，用于轮询元素出现/消失、读取 AX 属性以进行状态分支。
- 录制人类输入：通过 CGEventTap 监听真实鼠标和键盘，将点击转换为稳定的 AX 定位器，输出可回放的脚本（bash 与 markdown 两种格式）。
- 会话管理：缓存会话 ID，支持 session-alive 检查、activate 激活应用、stop 关闭会话。
使用方式
一次性安装
npm i -g appium
appium driver install mac2
appium driver doctor mac2
appium
doctor 会提示手动步骤：为 Xcode Helper.app 授予辅助功能权限；执行 automationmodetool enable-automationmode-without-authentication（macOS 12+）；运行 appium driver run mac2 open-wda 重新签名 WDA 目标。若 Appium 未在 4723 端口运行，应自行在后台启动。
核心循环
每次迭代只执行一个动作，绝不批量操作。流程为：启动 Mac2 会话（一次）→ 截图 → Claude 读取图像 → 判断是否完成/卡住/下一步动作 → 执行动作 → 回到截图。
常用命令（mac2.sh）
./mac2.sh start <bundleId>：启动会话，设置 newCommandTimeout: 3600。./mac2.sh screenshot [path]：保存 PNG，默认缩放到长边 1200px。./mac2.sh click <strategy> <value>：查找并点击元素。./mac2.sh type <strategy> <value> "text"：查找并输入文本。./mac2.sh drag <fromX> <fromY> <toX> <toY> [duration]：在绝对坐标间拖拽。./mac2.sh wait <strategy> <value> [timeout]：轮询直到元素存在。./mac2.sh keys <key> [...]：发送按键，如 Return、cmd+n。./mac2.sh click-at <x> <y>：绝对屏幕坐标，仅在无定位器时使用。./mac2.sh applescript "<cmd>"：用于 Finder/菜单栏/Mission Control 的逃生通道。./mac2.sh source [xml|description]：导出辅助功能树。./mac2.sh activate <bundleId>：将应用带到前台。./mac2.sh session-alive：检查缓存会话是否有效。./mac2.sh stop [--hard]：关闭会话。./mac2.sh exists <strategy> <value>：单次探测。./mac2.sh wait-not <strategy> <value> [timeout]：等待元素消失。./mac2.sh attr <strategy> <value> <attribute>：读取 AX 属性。./mac2.sh clear <strategy> <value>：清空文本字段。./mac2.sh record start/stop/status：录制人类输入。
录制功能
录制器通过 CGEventTap 监听真实鼠标和键盘，询问 AX 树以确定点击目标，输出 journeys/<name>.sh 和 journeys/<name>.md。首次使用需将 mac2-recorder 添加到辅助功能权限。录制器会跳过安全文本输入字段（密码），不捕获依赖悬停状态的菜单栏项。
持久化测试的两种模式
- 模式 A（bash，无视觉）：适用于已知稳定路径的快速回归验证。脚本运行快、确定性强，但遇到意外对话框或状态漂移会失败且无法恢复。
- 模式 B（markdown 提示，由 Claude 实例执行）：适用于 Bug 复现、探索性测试或需要视觉判断的路径。journey 是自然语言测试计划，执行者是有视觉能力的 Claude 实例。
适用场景
- 需要视觉验证的 Mac 应用 UI 测试。
- 需要每步截图证据的 Bug 复现。
- 布局动态变化、单一谓词无法覆盖的测试。
- 通过录制人类操作快速生成可回放的测试脚本。
限制
- Mac2 每台机器仅支持单会话，HID 是独占的，同时运行会竞争。
- 不适用于 iOS 目标。
- 已有 Xcode 项目访问权限时应直接编写 XCUITest。
- 录制器不捕获安全文本输入字段和依赖悬停状态的菜单栏项。
- 录制内容会暂存于 /tmp/mac2-record.jsonl，敏感信息需手动删除。
- 本地调试构建若与已安装应用使用相同 bundle ID，会导致会话附加到错误进程，需使用不同的 bundle ID。
- 首次启动会话需编译 WDA（20–60 秒），后续启动约 2 秒。
- 使用 sleep 等待 UI 会浪费固定时间，应使用 wait 命令。