MacPilot Dialog Handler 是 MacPilot 技能集中的一项技能，用于与任意应用中出现的 macOS 原生文件对话框（打开、存储为、打印等）进行交互。它可以导航到文件夹、选择文件、设置文件名，并确认或取消对话框。
用途 当出现文件打开或存储对话框且需要对其进行导航时；需要通过原生对话框以编程方式打开或保存文件时；需要关闭模态对话框（警告、确认）时；需要检查对话框包含哪些元素时；需要自动化文件选择工作流时，可使用本技能。
主要能力 本技能通过 macpilot dialog 系列命令提供以下能力：
- 检测对话框：macpilot dialog detect --json，返回是否存在模态对话框/表单、其类型及所属应用。
- 检查对话框元素：macpilot dialog inspect --json，返回对话框中所有交互元素（按钮、文本字段、列表）；可用 --depth 20 进行更深层检查。
- 导航到文件夹：macpilot dialog navigate "/Users/me/Documents" --json，打开“前往文件夹”表单（Cmd+Shift+G），设置路径并按回车，等待导航完成。
- 列出对话框中的文件：macpilot dialog list-files --json，返回当前对话框位置中可见的文件/文件夹列表。
- 选择文件：macpilot dialog select "myfile.txt" --json（仅高亮选中）；加 --confirm 则选中并确认（打开/存储）。
- 设置文本字段（文件名）：macpilot dialog set-field "output.pdf" --json；可用 --label "Search" 指定带标签的字段；可用 --focused 设置当前聚焦字段。
- 点击对话框按钮：macpilot dialog click-button "Save" --json，可点击 Save、Cancel、Open、Replace 等。
- 等待对话框：macpilot dialog wait-for --timeout 30 --json；可用 --app "Safari" 等待特定应用中的对话框。
- 点击主按钮：macpilot dialog click-primary --json，点击默认/主按钮（OK、Allow、Open 等）；可用 --app "Finder" 指定应用。
- 关闭对话框：macpilot dialog dismiss "OK" --json，按名称点击按钮关闭；macpilot dialog auto-dismiss --json，以安全默认值（Cancel/OK）自动关闭。
- 触发文件打开/保存：macpilot dialog file-open "/path/to/file.txt" --json；macpilot dialog file-save "/path/to/output.pdf" --json。
使用方式 资料提供了若干完整工作流示例，包括：将文件保存到指定位置（聚焦应用、发送 Cmd+Shift+S、等待、导航到目标文件夹、设置文件名、点击 Save）；打开指定文件（发送 Cmd+O、等待、导航并选择确认）；处理“替换现有文件”确认（点击 Save 后等待，用 dialog detect 检查是否出现确认对话框，若出现则点击 Replace）；检查未知对话框（先 detect 再 inspect）；一次性文件打开（file-open 组合触发、导航与选择）。
关键模式
- 触发对话框后等待：在 cmd+o 或 cmd+s 之后始终执行 macpilot wait seconds 1，让对话框完全出现后再交互。
- 先导航再选择：文件对话框会打开上次使用的目录，应始终先 dialog navigate 到正确文件夹。
- 对话框拥有焦点：对话框打开时，其所属应用必须处于活动状态；MacPilot 的对话框命令会自动扫描所有应用中的对话框来处理这一点。
- 对未知对话框使用 inspect：不确定对话框有哪些元素时，先运行 dialog inspect --json 查看所有可用按钮、字段和控件。
- 处理级联对话框：保存操作可能触发“替换？”或“格式？”确认对话框，点击 Save 后应始终用 dialog detect 检查。
- set-field 与键盘输入：输入文件名应使用 dialog set-field 而非键盘输入，它直接设置 AX 值，比模拟按键更可靠。
- wait-for + click-primary：自动化工作流中，用 dialog wait-for 检测对话框出现，再用 dialog click-primary 接受默认操作；主按钮检查会先查找 AXDefaultButton，再回退到常见标签（OK、Allow、Open、Save、Continue、Yes、Done、Confirm）。
适用场景 适用于需要自动化 macOS 原生文件对话框的各类场景，例如批量文件打开/保存、自动化测试、脚本化文档处理等。
限制 资料未提供关于系统版本要求、权限要求、收费或价格、平台限制等具体信息，暂未提供。