Initial commit

2025-11-29 18:18:56 +08:00
commit 3aef0f6c84
70 changed files with 14222 additions and 0 deletions
--- a/skills/references/commands-reference.md
+++ b/skills/references/commands-reference.md
@@ -0,0 +1,574 @@
+# Browser Pilot Commands Reference
+
+Complete reference for all Browser Pilot CLI commands using the project-local wrapper script.
+
+## Command Entry Points
+
+Browser Pilot uses the CLI wrapper script `.browser-pilot/bp`:
+
+**Single command execution:**
+```bash
+node .browser-pilot/bp <command> [options]
+```
+
+**Chain mode (multiple commands):**
+```bash
+node .browser-pilot/bp chain <command1> [args1] <command2> [args2] ...
+```
+
+**Daemon management:**
+```bash
+node .browser-pilot/bp daemon-<action>
+```
+
+## Single Command Execution
+
+### Navigation Commands
+
+**navigate** - Navigate to URL (auto-generates interaction map on page load)
+```bash
+node .browser-pilot/bp navigate -u "<url>"
+```
+
+**back** - Navigate back in history
+```bash
+node .browser-pilot/bp back
+```
+
+**forward** - Navigate forward in history
+```bash
+node .browser-pilot/bp forward
+```
+
+**reload** - Reload current page (regenerates interaction map)
+```bash
+node .browser-pilot/bp reload
+```
+
+### Interaction Commands
+
+**click** - Click an element
+
+Smart Mode (Recommended):
+```bash
+node .browser-pilot/bp click --text "<text>" [options]
+
+Options:
+  --text <text>          Text content to search for
+  --index <number>       Select nth match (1-based)
+  --type <type>          Element type filter (supports aliases: "input" → "input-*")
+  --tag <tag>            HTML tag filter (e.g., "button", "input")
+  --viewport-only        Only search visible elements
+  --verify               Verify action success
+
+Examples:
+  node .browser-pilot/bp click --text Submit
+  node .browser-pilot/bp click --text "Sign In" --type button
+  node .browser-pilot/bp click --text Delete --index 2
+  node .browser-pilot/bp click --text Search --type input       # Auto-expands to all input types
+  node .browser-pilot/bp click --text Submit --tag button       # Tag-based search
+```
+
+Direct Mode (fallback for unique IDs):
+```bash
+node .browser-pilot/bp click -s "<selector>"
+node .browser-pilot/bp click -u "<url>" -s "<selector>"
+```
+
+**fill** - Fill input field
+
+Smart Mode (Recommended):
+```bash
+node .browser-pilot/bp fill --text "<label>" -v "<value>" [options]
+
+Options:
+  --text <label>         Label or placeholder text to search
+  --type <type>          Input type filter (supports aliases: "input" → "input-*")
+  --tag <tag>            HTML tag filter (e.g., "input", "textarea")
+  --viewport-only        Only search visible elements
+  --verify               Verify action success
+
+Examples:
+  node .browser-pilot/bp fill --text Email -v user@example.com
+  node .browser-pilot/bp fill --text Password -v secret --type input-password
+  node .browser-pilot/bp fill --text Email --tag input -v user@example.com   # Tag-based search
+```
+
+Direct Mode (fallback for unique IDs):
+```bash
+node .browser-pilot/bp fill -s "<selector>" -v "<value>"
+```
+
+**hover** - Hover over element
+```bash
+node .browser-pilot/bp hover -s "<selector>"
+```
+
+**press** - Press keyboard key
+```bash
+node .browser-pilot/bp press -k "<key>"
+
+Keys: Enter, Tab, Escape, ArrowUp, ArrowDown, etc.
+```
+
+**type** - Type text character by character
+```bash
+node .browser-pilot/bp type -t "<text>" -d <delay-ms>
+```
+
+**upload** - Upload file to input element
+```bash
+node .browser-pilot/bp upload -s "<selector>" -f "<file-path>"
+```
+
+### Data Extraction Commands
+
+**extract** - Extract text content from element
+```bash
+node .browser-pilot/bp extract -s "<selector>"
+```
+
+**content** - Get full page HTML
+```bash
+node .browser-pilot/bp content
+```
+
+**console** - Get console messages with powerful filtering and formatting
+```bash
+node .browser-pilot/bp console [options]
+
+Options:
+  -u, --url <url>           Navigate to URL before getting console messages
+
+  Level Filtering:
+  -e, --errors-only         Show only error messages
+  -l, --level <level>       Filter by level: error, warning, log, info, verbose
+  --warnings                Show only warning messages
+  --logs                    Show only log messages
+
+  Message Limiting:
+  --limit <number>          Maximum number of messages to display
+  --skip <number>           Skip first N messages
+
+  Text Filtering:
+  -f, --filter <pattern>    Show only messages matching regex pattern
+  -x, --exclude <pattern>   Exclude messages matching regex pattern
+
+  Output Format:
+  -j, --json                Output in JSON format
+  -t, --timestamp           Show timestamps
+  --no-color                Disable colored output
+
+  File Output:
+  -o, --output <file>       Save output to file
+
+  Source Filtering:
+  --url-filter <pattern>    Filter by source URL (regex)
+
+Examples:
+  # Get all console messages
+  node .browser-pilot/bp console
+
+  # Get only errors with timestamps
+  node .browser-pilot/bp console -e -t
+
+  # Filter messages containing "API"
+  node .browser-pilot/bp console -f "API"
+
+  # Get warnings and exclude messages containing "deprecated"
+  node .browser-pilot/bp console --warnings -x "deprecated"
+
+  # Get first 10 log messages in JSON format
+  node .browser-pilot/bp console --logs --limit 10 -j
+
+  # Save all console messages to file
+  node .browser-pilot/bp console -o console-output.txt
+
+  # Get errors from specific source file
+  node .browser-pilot/bp console -e --url-filter "app.js"
+
+  # Navigate and get console errors
+  node .browser-pilot/bp console -u "http://localhost:3000" -e
+```
+
+**cookies** - Get page cookies
+```bash
+node .browser-pilot/bp cookies
+```
+
+### Capture Commands
+
+**screenshot** - Capture screenshot (saved to `.browser-pilot/screenshots/`)
+```bash
+node .browser-pilot/bp screenshot -o "<filename>.png" [options]
+
+Options:
+  -u, --url <url>        URL to capture (optional)
+  -o, --output <path>    Output filename (saved to .browser-pilot/screenshots/)
+  --full-page            Capture full page (default: true)
+  --clip-x <x>           Clip region X coordinate (pixels)
+  --clip-y <y>           Clip region Y coordinate (pixels)
+  --clip-width <width>   Clip region width (pixels)
+  --clip-height <height> Clip region height (pixels)
+  --clip-scale <scale>   Clip region scale factor (default: 1)
+  --headless             Run in headless mode
+
+Note: Clip region options take priority over --full-page. When clip options are specified,
+only the specified region will be captured regardless of --full-page setting.
+
+Examples:
+  # Full page screenshot
+  node .browser-pilot/bp screenshot -o result.png --full-page
+  # Saves to: .browser-pilot/screenshots/result.png
+
+  # Capture specific region (clip takes priority over full-page)
+  node .browser-pilot/bp screenshot -o region.png --clip-x 100 --clip-y 200 --clip-width 800 --clip-height 600
+  # Saves to: .browser-pilot/screenshots/region.png
+```
+
+**pdf** - Generate PDF (saved to `.browser-pilot/pdfs/`)
+```bash
+node .browser-pilot/bp pdf -o "<filename>.pdf" [options]
+
+Options:
+  -u, --url <url>        URL to capture (optional)
+  -o, --output <path>    Output filename (saved to .browser-pilot/pdfs/)
+  --landscape            Landscape orientation
+  --headless             Run in headless mode
+
+Example:
+  node .browser-pilot/bp pdf -o document.pdf --landscape
+  # Saves to: .browser-pilot/pdfs/document.pdf
+```
+
+**set-viewport** - Set browser viewport size (useful for responsive design testing)
+```bash
+node .browser-pilot/bp set-viewport -w <width> -h <height> [options]
+
+Options:
+  -w, --width <width>    Viewport width in pixels (required)
+  -h, --height <height>  Viewport height in pixels (required)
+  --scale <scale>        Device scale factor (default: 1)
+  --mobile               Emulate mobile device (default: false)
+
+Examples:
+  # Desktop viewport
+  node .browser-pilot/bp set-viewport -w 1920 -h 1080
+
+  # Mobile viewport (iPhone 12)
+  node .browser-pilot/bp set-viewport -w 390 -h 844 --scale 3 --mobile
+
+  # Tablet viewport (iPad)
+  node .browser-pilot/bp set-viewport -w 768 -h 1024 --scale 2
+```
+
+**get-viewport** - Get current viewport size
+```bash
+node .browser-pilot/bp get-viewport
+
+Output:
+  === Viewport Information ===
+  Size: 1920x1080
+  Scale: 1
+```
+
+**get-screen-info** - Get screen and viewport information
+```bash
+node .browser-pilot/bp get-screen-info
+
+Output:
+  === Screen Information ===
+  Screen: 2560x1440          # Physical screen resolution
+  Available: 2560x1392        # Available screen (excluding taskbar)
+  Viewport: 1920x1080        # Current browser viewport
+  Scale: 1                   # Device pixel ratio
+```
+
+### Tab Management Commands
+
+**tabs** - List all open tabs
+```bash
+node .browser-pilot/bp tabs
+```
+
+**new-tab** - Open new tab
+```bash
+node .browser-pilot/bp new-tab -u "<url>"
+```
+
+**close-tab** - Close tab by index
+```bash
+node .browser-pilot/bp close-tab -i <index>
+```
+
+**close** - Close browser
+```bash
+node .browser-pilot/bp close
+```
+
+### Utility Commands
+
+**eval** - Execute JavaScript in browser context
+```bash
+node .browser-pilot/bp eval -e "<javascript-expression>"
+
+Example:
+node .browser-pilot/bp eval -e "document.title"
+```
+
+**wait** - Wait for element to appear
+```bash
+node .browser-pilot/bp wait -s "<selector>" -t <timeout-ms>
+```
+
+**scroll** - Scroll page or element
+```bash
+# Scroll to position
+node .browser-pilot/bp scroll -x <x-pos> -y <y-pos>
+
+# Scroll element into view
+node .browser-pilot/bp scroll -s "<selector>"
+```
+
+**select** - Select dropdown option
+```bash
+node .browser-pilot/bp select -s "<selector>" -v "<option-value>"
+```
+
+**find** - Find elements matching selector
+```bash
+node .browser-pilot/bp find -s "<selector>"
+```
+
+**query** - Query interaction map for elements
+```bash
+# List all element types with counts
+node .browser-pilot/bp query --list-types
+
+# List all text contents (paginated, default 20)
+node .browser-pilot/bp query --list-texts
+
+# List text contents with type filter
+node .browser-pilot/bp query --list-texts --type button
+
+# Find elements by text
+node .browser-pilot/bp query --text "<text-content>"
+
+# Find all elements of a type (paginated)
+node .browser-pilot/bp query --type <element-type>
+
+# Type aliases (auto-expanded)
+node .browser-pilot/bp query --type input          # Matches: input, input-text, input-search, etc.
+node .browser-pilot/bp query --type input-search   # Exact match only
+
+# Find by HTML tag
+node .browser-pilot/bp query --tag button          # All <button> elements
+node .browser-pilot/bp query --text Submit --tag button
+
+# Show detailed information
+node .browser-pilot/bp query --type button --verbose
+
+# Pagination options
+node .browser-pilot/bp query --type button --limit 50 --offset 20
+
+# Unlimited results
+node .browser-pilot/bp query --type button --limit 0
+
+# Other options:
+# --index <n>        Select nth match (1-based)
+# --viewport-only    Only visible elements
+# --id <id>          Direct element ID lookup
+```
+
+**map-status** - Check interaction map status
+```bash
+node .browser-pilot/bp map-status
+```
+
+**regen-map** - Force regenerate interaction map
+```bash
+node .browser-pilot/bp regen-map
+```
+
+## Chain Mode
+
+Execute multiple commands sequentially in a single call with automatic map synchronization.
+
+**Syntax:**
+```bash
+node .browser-pilot/bp chain <command1> [args1] <command2> [args2] ...
+```
+
+**Key Features:**
+- Auto-waits for page load and map generation after navigation
+- Supports Smart Mode (--text) for reliable element targeting
+- Adds random human-like delay (300-800ms) between commands
+- Stops execution if any command fails
+- Each command executes after the previous one completes
+
+**Chain-specific Options:**
+```bash
+--timeout <ms>    Timeout for waiting map ready after navigation (default: 10000ms)
+--delay <ms>      Fixed delay between commands (overrides random 300-800ms delay)
+```
+
+**Quote Rules:**
+- No quotes needed when values have no spaces
+- Use quotes when values contain spaces
+
+**Examples:**
+
+```bash
+# Basic chain (no quotes needed)
+node .browser-pilot/bp chain navigate -u <url> click --text Submit extract -s .result
+
+# With spaces (quotes required)
+node .browser-pilot/bp chain navigate -u <url> click --text "Sign In" fill -s #email -v "user@example.com"
+
+# Login workflow with Smart Mode
+node .browser-pilot/bp chain navigate -u <url> fill --text Email -v <email> fill --text Password -v <password> click --text Login
+
+# Multi-step workflow with Korean text
+node .browser-pilot/bp chain navigate -u <url> click --text "메인 메뉴" click --text "설정 변경" click --text "저장"
+
+# Screenshot workflow
+node .browser-pilot/bp chain navigate -u <url> wait -s .content-loaded screenshot -o result.png
+
+# Custom timing
+node .browser-pilot/bp chain --timeout 15000 --delay 1000 navigate -u <url> click --text Submit
+```
+
+## Daemon Commands
+
+Daemon starts automatically on first command and stops automatically at session end.
+
+**daemon-start** - Start daemon (auto-starts on first command)
+```bash
+node .browser-pilot/bp daemon-start
+```
+
+**daemon-stop** - Stop daemon and close browser
+```bash
+node .browser-pilot/bp daemon-stop
+```
+
+**daemon-restart** - Restart daemon
+```bash
+node .browser-pilot/bp daemon-restart
+```
+
+**daemon-status** - Check daemon status
+```bash
+node .browser-pilot/bp daemon-status
+```
+
+## System Maintenance Commands
+
+**reinstall** - Reinstall Browser Pilot scripts
+
+Removes the `.browser-pilot` directory to force complete reinstallation on next command. Useful when:
+- Installation or build is corrupted
+- Scripts are not updating properly
+- Troubleshooting persistent issues
+
+```bash
+# Show confirmation prompt
+node .browser-pilot/bp reinstall
+
+# Skip confirmation and reinstall immediately
+node .browser-pilot/bp reinstall --yes
+
+# Quiet mode (no output)
+node .browser-pilot/bp reinstall --yes --quiet
+```
+
+**What it does:**
+1. Stops the daemon if running
+2. Removes `.browser-pilot` directory completely
+3. Next command will trigger automatic reinstallation via SessionStart hook
+
+**Options:**
+- `-y, --yes`: Skip confirmation prompt
+- `-q, --quiet`: Suppress output messages
+
+**Example workflow:**
+```bash
+# Reinstall scripts
+node .browser-pilot/bp reinstall --yes
+
+# Next command triggers automatic reinstallation
+node .browser-pilot/bp navigate -u "https://example.com"
+```
+
+## Common Options
+
+Most commands support:
+- `-u, --url <url>`: Navigate to URL before action
+- `--headless`: Run in headless mode (no visible browser)
+- `--timeout <ms>`: Custom timeout for operations
+
+## Smart Mode vs Direct Mode
+
+**🌟 Recommendation: Use Smart Mode by default for better reliability**
+
+| Feature | Smart Mode (Recommended) | Direct Mode |
+|---------|--------------------------|-------------|
+| Selector | Text content | CSS or XPath |
+| Reliability | ⭐⭐⭐⭐⭐ High (stable) | ⭐⭐ Low (brittle) |
+| Duplicates | Auto indexing | Manual indexing |
+| Map Required | Yes (auto-generated) | No |
+| Speed | Medium | Fast |
+| Best For | Most cases, text-based UI | Unique IDs only |
+| Maintenance | Low (text rarely changes) | High (selectors break often) |
+
+**When to use Direct Mode:**
+- Element has a unique, stable ID (e.g., `#user-profile-button`)
+- Performance-critical operations requiring maximum speed
+- Element has no visible text content
+
+## Exit Codes
+
+- `0`: Success
+- `1`: General error
+- Non-zero: Command failed
+
+## Examples
+
+**Take screenshot:**
+```bash
+node .browser-pilot/bp screenshot -u "https://example.com" -o "example.png" --full-page
+```
+
+**Login flow (Direct Mode):**
+```bash
+node .browser-pilot/bp navigate -u "https://example.com/login"
+node .browser-pilot/bp fill -s "#email" -v "user@example.com"
+node .browser-pilot/bp fill -s "#password" -v "secret"
+node .browser-pilot/bp click -s "#login-btn"
+```
+
+**Login flow (Chain Mode):**
+```bash
+node .browser-pilot/bp chain navigate -u "https://example.com/login" fill -s "#email" -v "user@example.com" fill -s "#password" -v "secret" click -s "#login-btn"
+```
+
+**Smart mode workflow (map auto-generated on navigate):**
+```bash
+node .browser-pilot/bp navigate -u "https://example.com"
+node .browser-pilot/bp click --text "Login" --type button
+node .browser-pilot/bp fill --text "Email" -v "user@example.com"
+node .browser-pilot/bp fill --text "Password" -v "secret"
+node .browser-pilot/bp click --text "Submit" --verify
+```
+
+**Smart mode workflow (Chain Mode):**
+```bash
+node .browser-pilot/bp chain navigate -u "https://example.com" click --text "Login" --type button fill --text "Email" -v "user@example.com" fill --text "Password" -v "secret" click --text "Submit" --verify
+```
+
+**Extract data:**
+```bash
+node .browser-pilot/bp navigate -u "https://example.com/products"
+node .browser-pilot/bp extract -s ".product-title"
+node .browser-pilot/bp extract -s ".product-price"
+```