macpilot-dialog-handler（macpilot 对话框处理程序）

MacPilot Dialog Handler

Use MacPilot's dialog commands to interact with native macOS file dialogs (Open, Save As, Print, etc.) that appear in any application. Navigate to folders, select files, set filenames, and confirm or cancel dialogs.

When to Use

Use this skill when:

• A file Open or Save dialog is showing and you need to navigate it
• You need to programmatically open or save files through native dialogs
• A modal dialog (alert, confirmation) needs to be dismissed
• You need to inspect what elements a dialog contains
• You need to automate file selection workflows

Commands

Detect Dialogs

macpilot dialog detect --json
# Returns: whether a modal dialog/sheet is present, its type, and owning app

Inspect Dialog Elements

macpilot dialog inspect --json
# Returns: all interactive elements (buttons, text fields, lists) in the dialog
macpilot dialog inspect --depth 20 --json   # Deeper inspection

Navigate to Folder

macpilot dialog navigate "/Users/me/Documents" --json
# Opens the Go To Folder sheet (Cmd+Shift+G), sets the path, presses Return
# Waits for navigation to complete

List Files in Dialog

macpilot dialog list-files --json
# Returns: list of files/folders visible in the current dialog location

Select a File

macpilot dialog select "myfile.txt" --json            # Select file (highlight only)
macpilot dialog select "myfile.txt" --confirm --json   # Select and confirm (Open/Save)

Set Text Field (Filename)

macpilot dialog set-field "output.pdf" --json              # Set filename in Save dialog
macpilot dialog set-field "query" --label "Search" --json  # Set specific labeled field
macpilot dialog set-field "text" --focused --json          # Set currently focused field

Click Dialog Button

macpilot dialog click-button "Save" --json
macpilot dialog click-button "Cancel" --json
macpilot dialog click-button "Open" --json
macpilot dialog click-button "Replace" --json

Wait for Dialog

macpilot dialog wait-for --timeout 30 --json         # Wait for any dialog to appear
macpilot dialog wait-for --app "Safari" --json        # Wait for dialog in specific app

Click Primary Button

macpilot dialog click-primary --json                 # Click default/primary button (OK, Allow, Open, etc.)
macpilot dialog click-primary --app "Finder" --json  # In specific app

Dismiss Dialogs

macpilot dialog dismiss "OK" --json           # Dismiss by clicking named button
macpilot dialog auto-dismiss --json           # Auto-dismiss with safe defaults (Cancel/OK)

Trigger File Open/Save

macpilot dialog file-open "/path/to/file.txt" --json   # Trigger Open and navigate
macpilot dialog file-save "/path/to/output.pdf" --json  # Trigger Save As and navigate

Complete Workflows

Save a File to Specific Location

# 1. Trigger Save dialog (Cmd+S or Cmd+Shift+S)
macpilot app focus "TextEdit"
macpilot keyboard key cmd+shift+s

# 2. Wait for dialog to appear
macpilot wait seconds 1

# 3. Navigate to target folder
macpilot dialog navigate "/Users/me/Desktop"

# 4. Set the filename
macpilot dialog set-field "report.txt"

# 5. Click Save
macpilot dialog click-button "Save"

Open a Specific File

# 1. Trigger Open dialog
macpilot app focus "TextEdit"
macpilot keyboard key cmd+o

# 2. Wait for dialog
macpilot wait seconds 1

# 3. Navigate and select
macpilot dialog navigate "/Users/me/Documents"
macpilot wait seconds 1
macpilot dialog select "readme.md" --confirm

Handle "Replace Existing File" Confirmation

macpilot dialog click-button "Save"
macpilot wait seconds 0.5
# Check if a confirmation dialog appeared
macpilot dialog detect --json
# If yes, click Replace
macpilot dialog click-button "Replace"

Inspect an Unknown Dialog

# First, see what dialog is present
macpilot dialog detect --json

# Then inspect all its interactive elements
macpilot dialog inspect --json

# Now you know what buttons and fields are available

One-Shot File Open

# Combines triggering the open dialog, navigating, and selecting
macpilot dialog file-open "/Users/me/Documents/report.pdf"

Critical Patterns

1. Wait after triggering dialogs: Always macpilot wait seconds 1 after cmd+o or cmd+s to let the dialog fully appear before interacting.
2. Navigate before selecting: File dialogs open in the last-used directory. Always dialog navigate to the correct folder first.
3. Dialog owns focus: When a dialog is open, the dialog's owning app must be active. MacPilot's dialog commands handle this automatically by scanning all apps for dialogs.
4. Use inspect for unknown dialogs: If you're unsure what elements a dialog has, run dialog inspect --json first to see all available buttons, fields, and controls.
5. Handle cascading dialogs: Save operations may trigger "Replace?" or "Format?" confirmation dialogs. Always check with dialog detect after clicking Save.
6. set-field vs keyboard type: Use dialog set-field instead of keyboard type for entering filenames - it directly sets the AX value, which is more reliable than simulating keystrokes.
7. wait-for + click-primary: For automated workflows, use dialog wait-for to detect when a dialog appears, then dialog click-primary to accept the default action. The primary button check looks for AXDefaultButton first, then falls back to common labels (OK, Allow, Open, Save, Continue, Yes, Done, Confirm).