MacPilot UI Inspector 是一个基于 MacPilot 辅助功能（AX）命令的技能，用于检查、查找和操作任意 macOS 应用中的 UI 元素，实现对应用界面的精确程序化控制。
用途
当用户需要完成以下任务时，可以使用该技能：
- 在应用中查找特定的按钮、文本框、复选框或其他 UI 元素
- 读取 UI 控件的值或状态
- 按标签点击按钮或与控件交互
- 检查应用的完整 UI 层级/辅助功能树
- 以编程方式设置文本框的值或切换复选框
- 发现应用支持的键盘快捷键
- 识别特定屏幕坐标处的元素
主要能力
该技能提供了一系列 macpilot ui 命令，覆盖 UI 检查与交互的常见需求：
- 列出 UI 元素：
macpilot ui list --app "Safari" --json，可按角色过滤（如--role AXButton）、控制扫描深度（--depth 5）或输出层级结构（--hierarchy）。 - 按文本查找元素：
macpilot ui find "Save" --app "TextEdit" --json，支持按角色过滤和精确匹配（--exact）。 - 查找元素坐标：
macpilot ui find-text "Submit" --app "Safari" --json，返回位置{x, y}和尺寸{w, h}，可用于点击。 - 按标签点击 UI 元素：
macpilot ui click "Save" --app "TextEdit" --json，也可指定角色。 - 获取/设置值：
macpilot ui get-value "Search" --app "Safari" --json读取字段值；macpilot ui set-value "Search" "query text" --app "Safari"设置字段值；macpilot ui set-value "Dark Mode" "1" --role AXCheckBox切换复选框。 - 设置焦点：
macpilot ui set-focus "Search" --app "Safari" --json。 - 在元素内滚动：
macpilot ui scroll "content" down 5 --app "Safari"。 - 检查元素属性：
macpilot ui attributes "Save" --app "TextEdit" --json，返回所有 AX 属性。 - 查询坐标处元素：
macpilot ui elements-at 500 300 --json，可用--radius 50扩大搜索范围。 - 获取辅助功能树：
macpilot ui tree --app "Finder" --json，可用--depth 3限制深度。 - 获取键盘快捷键：
macpilot ui shortcuts --app "Safari" --json，可用--menu File限定菜单。 - 等待元素出现：
macpilot wait element "Download Complete" --app "Safari" --timeout 30 --json。
常见 AX 角色
技能中列出了常用的辅助功能角色，包括：AXButton（按钮）、AXTextField（文本输入框）、AXTextArea（多行文本区域）、AXStaticText（标签和显示文本）、AXCheckBox（复选框和开关）、AXRadioButton（单选按钮）、AXPopUpButton（下拉菜单）、AXComboBox（组合框）、AXTable（表格和列表）、AXRow（表格/列表行）、AXMenuItem（菜单项）、AXToolbar（工具栏）、AXScrollArea（可滚动区域）、AXWindow（窗口）、AXSheet（模态表单）、AXImage（图像）、AXLink（超链接）、AXGroup（通用容器）。
使用方式
技能文档提供了多种工作流模式：
- 查找并点击：先聚焦应用（
macpilot app focus "Safari"），再查找元素确认存在，最后点击。 - 读取表单状态：聚焦应用后使用
get-value读取字段值。 - 填写表单：聚焦应用后依次使用
set-value设置字段，再点击提交。 - 探索未知 UI：先用
ui tree --depth 2进行宽泛扫描，再用ui list --role AXButton缩小范围，最后用ui attributes检查特定元素。 - 按坐标点击（回退方案）：当基于标签的点击失败时，先用
ui find-text获取坐标，再用macpilot click x y点击。
适用场景
该技能适用于需要对 macOS 应用界面进行自动化检查和操作的场景，例如：自动化测试、辅助功能探索、表单自动填写、读取应用状态、发现快捷键等。
限制与注意事项
- 必须在系统设置中为 MacPilot.app 授予辅助功能（AX）权限。
- 在进行任何 UI 交互前，应始终先调用
macpilot app focus聚焦目标应用。 - 建议使用
--json输出以便可靠解析元素属性。 - 当
ui click失败时，可回退到ui find-text加macpilot click x y的方式。 - 建议先用
ui tree --depth 2了解应用结构，再进行深度扫描。 - 在复杂应用中使用
--role过滤可以显著加快元素搜索速度。