@qqbrowser/openclaw-qbot 0.10.13 → 0.10.15

package/skills/qqbrowser-skill/SKILL.md

@@ -10,310 +10,406 @@ permissions:
 
 # qqbrowser-skill
 
-## Platform Support
+## Installation
 
-- **Linux x86_64**: Supported
-- **Windows**: Supported
-- **macOS**: Supported
-- Other Linux architectures (ARM, etc.) are not supported.
-
-## Security
+```bash
+# Linux / macOS
+pipx install qqbrowser-skill && qqbrowser-skill install
 
-### Permissions
+# Windows
+pip install qqbrowser-skill && qqbrowser-skill install
+```
 
-This skill requires the following permissions to function properly:
+## Key Concepts
 
-| Permission                   | Scope                      | Purpose                                                            |
-| ---------------------------- | -------------------------- | ------------------------------------------------------------------ |
-| **Network Access**           | Outbound HTTP/HTTPS        | Required for browser navigation, page loading, and web interaction |
-| **File System (Read/Write)** | Temporary directories only | Required for saving screenshots (`.webp`) and downloaded files     |
+- **Element Index**: Encoded string like `2_sfli_qp0u` (format: `highlightIndex_attrHash_xpathHash`). Generated by `browser_snapshot`, used to target elements for interaction. Features a 4-level degradation matching mechanism for cross-snapshot stability.
+- **Snapshot**: Returns page content with indexed elements. Re-snapshot is required after any DOM change (navigation, form submission, AJAX loading).
+- **Task Recording**: All browser tasks MUST be wrapped with `task_begin`/`task_end` to enable replay.
 
-### QQBrowser Binary
+## Core Workflow
 
-The `qqbrowser-skill install` command downloads the QQ Browser package from official Tencent distribution channels via HTTPS:
+```bash
+qqbrowser-skill task_begin --description "描述任务"     # 1. Start recording (MANDATORY)
+qqbrowser-skill browser_go_to_url --url <url>           # 2. Navigate
+qqbrowser-skill browser_snapshot                        # 3. Get element indices
+# ... interact using indices ...                        # 4. Perform actions
+qqbrowser-skill browser_snapshot                        # 5. Re-snapshot after DOM changes
+qqbrowser-skill task_end                                # 6. End recording (MANDATORY)
+```
 
-- **Base URL**: `https://dldir1v6.qq.com/invc/tt/QB/Public/`
-- `dldir1v6.qq.com` is Tencent's official software distribution CDN.
-- All downloads are performed over **HTTPS** to ensure transport-level security.
+## Command Reference
 
-### File Storage
+### Navigation
+```bash
+browser_go_to_url --url <url>          # Navigate to URL
+browser_go_back                         # Go back
+browser_wait --seconds <n>              # Wait (default 3s)
+```
 
-- **Screenshots**: Saved to the system's temporary directory (e.g., `/tmp/` on Linux) and returned as file paths.
-- **Downloaded files**: Saved to the system's temporary directory or user-specified path via `browser_download_file` / `browser_download_url`.
-- This skill does **not** access or modify files outside of its designated directories.
+### Snapshot & Screenshot
+```bash
+browser_snapshot                        # Element indices mode (for interaction)
+browser_snapshot --markdown             # Clean Markdown mode (for reading, no indices)
+browser_screenshot [--full] [--annotate]  # Screenshot (returns .webp temp path)
+```
 
-## Note:
+### Click & Input
+```bash
+browser_click_element --index <id>                     # Click
+browser_dblclick_element --index <id>                  # Double-click
+browser_focus_element --index <id>                     # Focus
+browser_input_text --index <id> --text "<content>"     # Clear + input text
+```
 
-Each command will return a snapshot of the current page after execution, including the encoded index of elements (format: `index_attrHash_xpathHash`, e.g. `2_sfli_qp0u`).
-Please call the standalone qqbrowser-skill browser_snapshot command only when necessary to avoid unnecessary token consumption.
+### Scroll
+```bash
+browser_scroll_down [--amount <px>]     # Scroll down (default one page)
+browser_scroll_up [--amount <px>]       # Scroll up
+browser_scroll_to_text --text "<text>"  # Scroll to text
+browser_scroll_to_top / browser_scroll_to_bottom
+browser_scroll_by --direction <dir> --pixels <n> [--index <id>]
+browser_scroll_into_view --index <id>
+```
 
-## ⚠️ MANDATORY: Task Recording Required
+### Keyboard
+```bash
+browser_keypress --key <key>                           # Press key (Enter, Tab, etc.)
+browser_keyboard_op --action type --text "<content>"   # Type text
+browser_keyboard_op --action inserttext --text "<content>"  # Insert without key events
+browser_keydown --key <key> / browser_keyup --key <key>
+```
 
-**EVERY browser automation task MUST be wrapped with `task_begin` and `task_end`.** This is NOT optional.
+### Dropdown & Checkbox
+```bash
+browser_get_dropdown_options --index <id>
+browser_select_dropdown_option --index <id> --text "<option>"
+browser_check_op --index <id> --value / --no-value
+```
 
+### Find and Act (Semantic Locators)
 ```bash
-# ALWAYS start with task_begin BEFORE any browser commands
-qqbrowser-skill task_begin --description "描述你要做的任务"
+browser_find_and_act --by <role|text|label|placeholder|testid|css> --value "<v>" --action <click|fill|type> [--actionValue "<v>"] [--name "<n>"] [--nth <n>]
+# --nth: select the Nth matching element (0-based). Essential for loop patterns in lists.
+```
 
-# ... your browser commands here ...
+### Get Information & State
+```bash
+browser_get_info --type <text|url|title|html|value|attr|count|box|styles|list_selector> [--index <id>] [--attribute <name>]
+browser_check_state --state <visible|enabled|checked> --index <id>
+```
 
-# ALWAYS end with task_end AFTER all browser commands are done
-qqbrowser-skill task_end
+> **💡 Key Usage**: `browser_get_info` returns **only the requested info** (no page state or interactive elements), making it lightweight and token-efficient.
+>
+> **🔑 `list_selector` — Auto-detect CSS selector for list iteration (PREFERRED for loop tasks):**
+> ```bash
+> # From snapshot you see a list of articles:
+> #   [3_abc1_def2]<a 人工智能的未来/>
+> #   [4_xyz3_uvw4]<a 深度学习入门/>
+> #   [5_mno5_pqr6]<a 大模型时代/>
+>
+> # Pick ANY one element from the list and run:
+> browser_get_info --type list_selector --index "3_abc1_def2"
+> # → {"success":true, "selector":".ContentItem h2 a", "count":10,
+> #    "samples":["人工智能的未来","深度学习入门","大模型时代","...","..."],
+> #    "strategy":"parent_level_1"}
+>
+> # Now use this selector directly in find_and_act for loop iteration:
+> browser_find_and_act --by css --value ".ContentItem h2 a" --action click --nth 1
+> ```
+> **This is the RECOMMENDED way to find CSS selectors for list operations.** It replaces the manual workflow of `get_info --type html` → analyze → construct selector → probe verify. One command does it all.
+>
+> If `list_selector` returns `success: false`, fall back to manual inspection:
+> ```bash
+> browser_get_info --type html --index "5_abc1_def2"
+> # → returns element HTML, use it to construct a selector manually
+> ```
+
+### JavaScript Evaluation
+```bash
+browser_eval_content_js --script "<js_code>"           # Evaluate JS, return result
+browser_eval_content_js --script "<base64>" --base64   # Base64-encoded script
 ```
 
-**Rules:**
+### Download
+```bash
+browser_download_file --index <id>     # Download by clicking element
+browser_download_url                    # Download from URL
+```
 
-- `task_begin` MUST be the **first** command you execute (before `browser_go_to_url` or any other browser command)
-- `task_end` MUST be the **last** command you execute (after the task is complete)
-- There are NO exceptions to this rule — even for simple tasks like data extraction or page reading
-- Failure to use `task_begin`/`task_end` means the task cannot be replayed or saved as a playbook later
+### Tab Management
+```bash
+browser_tab_open --url <url>           # Open new tab
+browser_tab_list                        # List tabs
+browser_tab_switch --tabId <n>         # Switch tab
+browser_tab_close --tabId <n>          # Close tab
+```
 
-## Core Workflow
+### Dialog
+```bash
+browser_dialog --action <accept|dismiss> [--text "<input>"]
+```
 
-Every browser automation follows this pattern:
+### Replay
+```bash
+browser_replay --script <path>         # Replay from file
+browser_replay --script_content '<json>'  # Replay from JSON string
+browser_replay --script <path> --variables '{"key":"value"}'  # With params
+```
 
-1. **Record start**: `qqbrowser-skill task_begin --description "task description"`
-2. **Navigate**: `qqbrowser-skill browser_go_to_url --url <url>`
-3. **Snapshot**: `qqbrowser-skill browser_snapshot` (get indexed element refs)
-4. **Interact**: Use element index to click, fill, select
-5. **Re-snapshot**: After navigation or DOM changes, get fresh refs
-6. **Record end**: `qqbrowser-skill task_end`
+> **⚠️ LONG EXECUTION TIME**: `browser_replay` executes ALL steps in the playbook sequentially (navigation, waiting, data extraction, etc.). **This can take up to 10 minutes** depending on the number of steps, network conditions, and configured delays/timeouts.
+>
+> **You MUST wait patiently** for the command to complete — do NOT assume it has hung or timed out. Do NOT interrupt or retry unless you receive an explicit error message.
+> Typical durations: simple playbooks (5-10 steps) ~30s–1min, complex playbooks with loops (20+ steps) ~3–10min.
 
+### Task Recording
 ```bash
-qqbrowser-skill task_begin --description "Fill out example form"
-qqbrowser-skill browser_go_to_url --url https://example.com/form
-qqbrowser-skill browser_snapshot
-# Output includes element indices: [1_abc1_def2] input "email", [2_xyz3_uvw4] input "password", [3_klm5_nop6] button "Submit"
-
-qqbrowser-skill browser_input_text --index 1_abc1_def2 --text "user@example.com"
-qqbrowser-skill browser_input_text --index 2_xyz3_uvw4 --text "password123"
-qqbrowser-skill browser_click_element --index 3_klm5_nop6
-qqbrowser-skill browser_wait --seconds 2
-qqbrowser-skill browser_snapshot  # Check result
-qqbrowser-skill task_end
+task_begin --description "<description>"   # Start recording (MUST be first)
+task_end                                    # Stop recording → then auto-generate playbook (see below)
+task_latest                                 # Get most recent recording (for playbook generation)
 ```
 
-## Essential Commands
+> **IMPORTANT**: After `task_end`, do NOT just show the raw recording path. The raw recording (`~/.qqbrowser-skill/records/task_*.json`) is NOT a ready-to-use replay script. You MUST proceed to generate a proper playbook — see "Generating Replay Scripts / Playbooks" section.
 
+### Utility
 ```bash
-# Navigation
-qqbrowser-skill browser_go_to_url --url <url>       # Navigate to URL
-qqbrowser-skill browser_go_back                      # Go back
-qqbrowser-skill browser_wait --seconds 3             # Wait for page load (default 3s)
-
-# Snapshot & Screenshot
-qqbrowser-skill browser_snapshot                     # Default mode: page content with element indices (for interaction)
-qqbrowser-skill browser_snapshot --markdown          # Markdown mode: clean Markdown of the page (for reading/extraction, no indices)
-qqbrowser-skill browser_screenshot                   # Take screenshot (returns temp file path of .webp image)
-qqbrowser-skill browser_screenshot --full            # Full-page screenshot (returns temp file path)
-qqbrowser-skill browser_screenshot --annotate        # Annotated screenshot with element labels (returns temp file path)
-
-# Click & Input (use indices from snapshot, index is an encoded string like "2_sfli_qp0u")
-qqbrowser-skill browser_click_element --index 2_sfli_qp0u      # Click element
-qqbrowser-skill browser_dblclick_element --index 2_sfli_qp0u   # Double-click element
-qqbrowser-skill browser_focus_element --index 2_sfli_qp0u      # Focus element
-qqbrowser-skill browser_input_text --index 3_abc1_def2 --text "hello"  # Input text into element
-
-# Scroll
-qqbrowser-skill browser_scroll_down                  # Scroll down one page
-qqbrowser-skill browser_scroll_down --amount 300     # Scroll down 300px
-qqbrowser-skill browser_scroll_up                    # Scroll up one page
-qqbrowser-skill browser_scroll_up --amount 300       # Scroll up 300px
-qqbrowser-skill browser_scroll_to_text --text "Section 3"    # Scroll to text
-qqbrowser-skill browser_scroll_to_top                # Scroll to top
-qqbrowser-skill browser_scroll_to_bottom             # Scroll to bottom
-qqbrowser-skill browser_scroll_by --direction down --pixels 500                          # Scroll page by direction
-qqbrowser-skill browser_scroll_by --direction right --pixels 200 --index 3_klm5_nop6    # Scroll element by direction
-qqbrowser-skill browser_scroll_into_view --index 5_xyz3_uvw4   # Scroll element into view
-
-# Keyboard
-qqbrowser-skill browser_keypress --key Enter         # Press a key
-qqbrowser-skill browser_keyboard_op --action type --text "hello"        # Type text
-qqbrowser-skill browser_keyboard_op --action inserttext --text "hello"  # Insert text without key events
-qqbrowser-skill browser_keydown --key Shift          # Hold down a key
-qqbrowser-skill browser_keyup --key Shift            # Release a key
-
-# Dropdown
-qqbrowser-skill browser_get_dropdown_options --index 2_abc1_def2           # Get dropdown options
-qqbrowser-skill browser_select_dropdown_option --index 2_abc1_def2 --text "Option A"  # Select option
-
-# Checkbox
-qqbrowser-skill browser_check_op --index 4_klm5_nop6 --value               # Check checkbox
-qqbrowser-skill browser_check_op --index 4_klm5_nop6 --no-value            # Uncheck checkbox
-
-# Get Information
-qqbrowser-skill browser_get_info --type text --index 1_abc1_def2   # Get element text
-qqbrowser-skill browser_get_info --type url              # Get current URL
-qqbrowser-skill browser_get_info --type title            # Get page title
-qqbrowser-skill browser_get_info --type html --index 1_abc1_def2   # Get element HTML
-qqbrowser-skill browser_get_info --type value --index 1_abc1_def2  # Get element value
-qqbrowser-skill browser_get_info --type attr --index 1_abc1_def2 --attribute href   # Get attribute
-qqbrowser-skill browser_get_info --type count            # Get element count
-qqbrowser-skill browser_get_info --type box --index 1_abc1_def2    # Get bounding box
-qqbrowser-skill browser_get_info --type styles --index 1_abc1_def2 # Get computed styles
-qqbrowser-skill browser_check_state --state visible --index 1_abc1_def2    # Check visibility
-qqbrowser-skill browser_check_state --state enabled --index 1_abc1_def2    # Check if enabled
-qqbrowser-skill browser_check_state --state checked --index 1_abc1_def2    # Check if checked
-
-# Find and Act (semantic locators)
-qqbrowser-skill browser_find_and_act --by role --value button --action click --name "Submit"
-qqbrowser-skill browser_find_and_act --by text --value "Sign In" --action click
-qqbrowser-skill browser_find_and_act --by label --value "Email" --action fill --actionValue "user@test.com"
-qqbrowser-skill browser_find_and_act --by placeholder --value "Search" --action type --actionValue "query"
-qqbrowser-skill browser_find_and_act --by testid --value "submit-btn" --action click
-
-# Download
-qqbrowser-skill browser_download_file --index 5_xyz3_uvw4      # Download file by clicking element
-qqbrowser-skill browser_download_url                 # Download from URL
-
-# Tab Management
-qqbrowser-skill browser_tab_open --url <url>         # Open URL in new tab
-qqbrowser-skill browser_tab_list                     # List open tabs
-qqbrowser-skill browser_tab_switch --tabId 2         # Switch to tab
-qqbrowser-skill browser_tab_close --tabId 2          # Close tab
-
-# Dialog
-qqbrowser-skill browser_dialog --action accept       # Accept dialog
-qqbrowser-skill browser_dialog --action dismiss      # Dismiss dialog
-qqbrowser-skill browser_dialog --action accept --text "input text"  # Accept prompt with text
-
-# JavaScript Evaluation
-qqbrowser-skill browser_eval_content_js --script "document.title"                    # Evaluate JS and return result
-qqbrowser-skill browser_eval_content_js --script "ZG9jdW1lbnQudGl0bGU=" --base64    # Evaluate base64-encoded JS script
-
-# Replay (execute a recorded automation script)
-qqbrowser-skill browser_replay --script /path/to/record.json                         # Replay from file
-qqbrowser-skill browser_replay --script_content '{"version":"1.0",...}'              # Replay from JSON string
-qqbrowser-skill browser_replay --script /path/to/record.json --variables '{"user":"test@example.com","pass":"123"}'  # With parameterized variables
-
-# Task Completion
-qqbrowser-skill browser_done --success --text "Task completed"      # Mark task as done
-qqbrowser-skill browser_done --text "Still in progress"              # Mark task as incomplete
-
-# Task Recording
-qqbrowser-skill task_begin --description "description of what you are doing"   # Start recording commands
-qqbrowser-skill task_end                                                        # Stop recording and save
-qqbrowser-skill task_latest                                                     # Get the most recent task recording
-
-# Help
-qqbrowser-skill list                                 # List all available skills
-qqbrowser-skill <skill_name> --help                  # Show help for a specific skill
-
-# Skill Check
-qqbrowser-skill status                               # Check skill status
+browser_done --success --text "<msg>"  # Mark task complete
+status                                  # Check skill status
+list                                    # List available skills
 ```
 
-## Common Patterns
+---
+
+## ⚠️ MANDATORY: Replay-Friendly Execution Rules
+
+**All operations MUST prioritize replayability. Follow these rules to ensure recorded steps can be replayed with parameterized variables.**
+
+### Rule 1: Task Classification
 
-### Form Submission
+Before executing, classify the task:
+
+| Category | Replayable? | Strategy |
+|----------|-------------|----------|
+| **A: Fixed-path** (navigate, click, fill forms) | ✅ | Standard commands, all recorded |
+| **B: Data extraction** | ⚠️ Partial | Use `browser_eval_content_js` (replayable), NOT `snapshot --markdown` + AI summarization |
+| **C: Content understanding** (summarize, compare) | ❌ | Separate from replayable steps, mark with `"requires_ai": true` |
+| **D: Dynamic iteration** (pagination, load more) | ⚠️ | Use fixed number of operations based on predictable calculation |
+
+### Rule 2: Data Extraction — Always Prefer JS
 
 ```bash
-qqbrowser-skill browser_go_to_url --url https://example.com/signup
-qqbrowser-skill browser_snapshot
-qqbrowser-skill browser_input_text --index 1_abc1_def2 --text "Jane Doe"
-qqbrowser-skill browser_input_text --index 2_xyz3_uvw4 --text "jane@example.com"
-qqbrowser-skill browser_select_dropdown_option --index 3_klm5_nop6 --text "California"
-qqbrowser-skill browser_check_op --index 4_pqr7_stu8 --value
-qqbrowser-skill browser_click_element --index 5_vwx9_yza0
-qqbrowser-skill browser_wait --seconds 2
-qqbrowser-skill browser_snapshot  # Verify result
+# ✅ Replayable: JS extraction
+browser_eval_content_js --script "JSON.stringify(Array.from(document.querySelectorAll('.item')).slice(0,10).map(el=>({title:el.querySelector('.title')?.textContent?.trim()})))" --base64
+
+# ❌ Non-replayable: AI reading
+browser_snapshot --markdown  # then AI summarizes
 ```
 
-### Data Extraction
+**Exception**: Tasks explicitly requiring AI understanding (e.g., "总结文章要点") — note in `task_begin` description: "需要AI在线参与，不可纯回放".
 
-Choose the right `browser_snapshot` mode based on intent:
+### Rule 3: Analyze First, Execute Once (No Trial-and-Error Recording)
 
-- **`browser_snapshot --markdown`** — preferred for **reading/summarizing** page content (articles, docs, search results, product pages). Returns clean Markdown with ads/nav/scripts stripped. Token-efficient, but contains **no element indices** — cannot be used to drive clicks or inputs.
-- **`browser_snapshot`** (default) — required for **interacting** with the page. Returns indexed elements for use with `browser_click_element`, `browser_input_text`, etc.
+**CRITICAL**: Do NOT use trial-and-error during a recorded task. Every command between `task_begin` and `task_end` is recorded — failed attempts pollute the recording and make it unreplayable.
 
+**Correct workflow for data extraction:**
 ```bash
-qqbrowser-skill browser_go_to_url --url https://example.com/products
-qqbrowser-skill browser_snapshot --markdown                # Read the whole page as clean markdown
+task_begin --description "..."
+browser_go_to_url --url "..."
+browser_wait --seconds 3
+browser_snapshot                    # ← AI analyzes page structure here (not recorded in replay)
+# AI identifies the correct, stable selector BEFORE writing the JS script
+browser_eval_content_js --script "/* one correct script */"   # ← Only this gets replayed
+task_end
+```
+
+**PROHIBITED patterns:**
+- ❌ Running multiple `browser_eval_content_js` with different selectors hoping one works
+- ❌ Using `browser_get_info` to "check" results mid-recording then adjusting
+- ❌ Hardcoding element index strings (e.g., `[id='25_tg4y_yb9z']`) inside JS scripts — index is for command params only, not JS selectors
+- ❌ Using regex to match page text content as a selector strategy (fragile, locale-dependent)
+
+**Rule**: Use `browser_snapshot` to understand the DOM, then write **one definitive** JS extraction script. If the first script fails, call `task_end` to discard, fix the script, then re-record with `task_begin`.
+
+### Rule 4: JS Selector Priority
 
-# Use default snapshot + get_info when you need to interact or read a specific element
-qqbrowser-skill browser_snapshot
-qqbrowser-skill browser_get_info --type text --index 5_abc1_def2     # Get a specific element's text
+| Priority | Type | Example |
+|----------|------|---------|
+| 1 | `id` | `#rank-list` |
+| 2 | `data-*` | `[data-testid="item"]` |
+| 3 | ARIA | `[role="listitem"]` |
+| 4 | Semantic class | `.article-title` |
+| 5 | Structural path | `main > ul > li` |
+| ❌ | Dynamic/hash class | `.css-1a2b3c` — NEVER use |
+
+### Rule 5: Repeating Patterns & Pagination
+
+**Identify repeating patterns during recording**. If you find yourself doing the same sequence of actions N times (e.g., click item → read → go back), this is a **loop pattern**. Record it correctly:
+
+**Recording strategy for loop tasks:**
+```bash
+task_begin --description "搜索{{topic}}并提取前{{count}}篇文章内容"
+browser_go_to_url --url "https://example.com/search?q=AI"
+browser_wait --seconds 3
+browser_snapshot                           # AI analyzes list structure
+
+# ★ STEP 0: DISCOVER LIST SELECTOR (MANDATORY before any list iteration)
+# Use list_selector to auto-detect the CSS selector from any list item's snapshot index:
+browser_get_info --type list_selector --index "3_abc1_def2"
+# → {"success":true, "selector":".result-item h2 a", "count":10, "samples":[...]}
+# Then record the probe with the discovered selector for playbook generation:
+browser_eval_content_js --script "JSON.stringify({__list_probe__: true, selector: '.result-item h2 a', count: document.querySelectorAll('.result-item h2 a').length, samples: Array.from(document.querySelectorAll('.result-item h2 a')).slice(0,3).map(e=>e.textContent.trim())})"
+# The __list_probe__ marker helps the playbook generator locate this data.
+
+# Record ONE complete iteration as the pattern:
+browser_find_and_act --by css --value ".result-item h2 a" --action click --nth 1
+browser_wait --seconds 2
+browser_eval_content_js --script "JSON.stringify({title: document.querySelector('h1')?.textContent, content: document.querySelector('.content')?.textContent?.substring(0,2000)})"
+browser_go_back
+browser_wait --seconds 1
+
+# Record second iteration to confirm the pattern:
+browser_find_and_act --by css --value ".result-item h2 a" --action click --nth 2
+browser_wait --seconds 2
+browser_eval_content_js --script "JSON.stringify({title: document.querySelector('h1')?.textContent, content: document.querySelector('.content')?.textContent?.substring(0,2000)})"
+browser_go_back
+
+task_end
 ```
 
-### Infinite Scroll Pages
+**Key points:**
+- **★ MUST discover and probe list selector** before iterating — first use `browser_get_info --type list_selector --index <id>` to auto-detect the CSS selector, then use `browser_eval_content_js` with `__list_probe__: true` to record it. **NEVER guess CSS selectors.**
+- Record **at least 2 iterations** so the playbook generator can identify the loop pattern
+- Use `browser_find_and_act` with `--nth` (not `browser_click_element` with hardcoded index) for list items — this enables loop parameterization
+- The playbook generator will automatically convert repetitions into a `loop` structure with `{{count}}` controlling iterations
+
+**How to find the CSS selector (MANDATORY — use `list_selector`):**
+```
+★ PREFERRED (one command, auto-detect):
+1. browser_snapshot              → AI sees list elements: [3_abc1_def2]<a 人工智能的未来/> ...
+2. browser_get_info --type list_selector --index "3_abc1_def2"
+                                 → returns: {"success":true, "selector":".ContentItem h2 a", "count":10, "samples":[...]}
+3. Use the returned selector     → proceed with __list_probe__ and find_and_act
+
+FALLBACK (if list_selector returns success=false):
+1. browser_get_info --type html --index "3_abc1_def2"
+                                 → returns: <a class="ContentItem-title" href="/p/123456">人工智能的未来</a>
+2. AI reads the HTML             → identifies class, parent structure, etc.
+3. AI constructs CSS selector    → ".ContentItem-title" or "a[data-za-detail-view-element_name='Title']"
+4. browser_eval_content_js       → run __list_probe__ to verify the selector
+```
+**NEVER guess CSS selectors.** Always use `list_selector` first, then fall back to `html` inspection if needed.
 
+**For simple pagination** (next page button):
 ```bash
-qqbrowser-skill browser_go_to_url --url https://example.com/feed
-qqbrowser-skill browser_scroll_to_bottom     # Trigger lazy loading
-qqbrowser-skill browser_wait --seconds 2     # Wait for content
-qqbrowser-skill browser_snapshot             # Get updated content
+browser_eval_content_js --script "/* extract page 1 */"
+browser_find_and_act --by text --value "下一页" --action click
+browser_wait --seconds 2
+browser_eval_content_js --script "/* extract page 2 */"
 ```
 
-## Element Index Lifecycle (Important)
+**DO NOT** use AI judgment loops ("check if enough, scroll more").
 
-Element indices are encoded strings (e.g. `2_sfli_qp0u`) that contain hash information for cross-snapshot matching. They are generated by each snapshot and may change when the page DOM changes. Always re-snapshot after:
+### Rule 6: Multi-Tab Recording Strategy
 
-- Clicking links or buttons that navigate
-- Form submissions
-- Dynamic content loading (dropdowns, modals, AJAX)
+When a task involves links that open in new tabs (e.g., `target="_blank"`), record using **explicit tab management commands** instead of relying on `browser_go_back`:
 
 ```bash
-qqbrowser-skill browser_click_element --index 5_abc1_def2   # May navigate to new page
-qqbrowser-skill browser_snapshot                             # MUST re-snapshot
-qqbrowser-skill browser_click_element --index 1_xyz3_uvw4   # Use new indices
+task_begin --description "搜索并提取文章(新Tab场景)"
+browser_go_to_url --url "https://example.com/search?q=AI"
+browser_wait --seconds 3
+browser_snapshot                           # AI analyzes list structure
+
+# ★ DISCOVER + PROBE LIST SELECTOR (same as Rule 5 — MANDATORY before list iteration):
+browser_get_info --type list_selector --index "3_abc1_def2"   # auto-detect selector
+browser_eval_content_js --script "JSON.stringify({__list_probe__: true, selector: '.result-item h2 a', count: document.querySelectorAll('.result-item h2 a').length, samples: Array.from(document.querySelectorAll('.result-item h2 a')).slice(0,3).map(e=>e.textContent.trim())})"
+
+# Click link that opens in new tab:
+browser_find_and_act --by css --value ".result-item h2 a" --action click --nth 1
+browser_tab_list                           # AI checks: new tab appeared?
+browser_tab_switch --tabId <new_tab_id>    # Switch to the new tab
+browser_wait --seconds 2
+browser_eval_content_js --script "..."     # Extract content in detail page
+browser_tab_close --tabId <current_tab_id> # Close detail tab
+browser_tab_switch --tabId <origin_tab_id> # Switch back to list page
+browser_wait --seconds 1
+
+# Repeat for second item...
+browser_find_and_act --by css --value ".result-item h2 a" --action click --nth 2
+# ... same pattern ...
+
+task_end
 ```
 
-## Evaluation Report
+**Key points:**
+- Use `browser_tab_list` to observe tab changes (this is AI-only, filtered from playbook)
+- Record physical `tabId` during recording — the **playbook generator** will convert them to semantic references (`"origin"`, `"latest"`, `"current"`)
+- **DO NOT use `browser_go_back`** when the previous action opened a new tab — `go_back` navigates within the current tab's history, it cannot close tabs or switch between them
+- Record **at least 2 iterations** of the tab pattern (same as loop recording) so the playbook generator can detect and convert to `loop` + tab management
 
-See the full skill evaluation report: [QQBrowserSkillReport](https://bak.res.qq.com/nav/qqbrowser_skills/QQBrowserSkillReport.html)
+**How to detect new tab during recording:**
+1. After clicking a link, call `browser_tab_list`
+2. If a new tab appeared (tab count increased), use `browser_tab_switch` to go to it
+3. If no new tab (same count), the link navigated in-place → use normal flow with `browser_go_back`
 
-## Task Recording (Important for AI Agents)
+### Rule 7: Fixed vs Variable Parameters
 
-**IMPORTANT**: When using qqbrowser-skill to complete any automation task, you MUST wrap your commands with `task_begin` and `task_end`. This records all browser operations performed during the task, enabling replay and reuse later.
+| Command | Fixed | Variable (→ `{{param}}`) |
+|---------|-------|--------------------------|
+| `browser_go_to_url` | Base URL | Query params, path segments |
+| `browser_click_element` | `--index` | — (never parameterize) |
+| `browser_input_text` | `--index` | `--text` |
+| `browser_select_dropdown_option` | `--index` | `--text` |
+| `browser_keyboard_op` | `--action` | `--text` |
+| `browser_eval_content_js` | Script structure | Count, selector, keyword in script |
+| `browser_find_and_act` | `--by`, `--action` | `--value`, `--actionValue`, `--name` |
+| `browser_dialog` | `--action` | `--text` |
+| `browser_wait` / `browser_scroll_*` | All params | — |
 
-### Workflow
+### Rule 8: Non-Replayable Commands (AI-Decision Only)
 
-1. **Before starting any browser automation task**, call `task_begin` with a description of what you're about to do
-2. Execute your browser commands as normal
-3. **After completing the task**, call `task_end` to save the recording
+These commands help AI decide but produce **no replayable action** — they are skipped during replay:
 
-### Commands
+`browser_snapshot`, `browser_snapshot --markdown`, `browser_screenshot`, `browser_get_info`, `browser_check_state`, `browser_get_dropdown_options`, `browser_tab_list`
 
-```bash
-# Start recording — call this BEFORE any browser commands for the task
-qqbrowser-skill task_begin --description "自动打开小红书并发布一篇笔记"
+**Principle**: AI uses these to decide; the resulting **actions** (click, input, select) are what gets recorded and replayed.
+
+### Rule 9: Prefer `browser_find_and_act` for Dynamic Content
 
-# ... execute browser commands normally ...
-qqbrowser-skill browser_go_to_url --url https://www.xiaohongshu.com
-qqbrowser-skill browser_snapshot
-qqbrowser-skill browser_click_element --index 5_abc1_def2
-# ... more commands ...
+For elements in dynamic lists (search results, feeds) where index stability is uncertain:
 
-# Stop recording — call this AFTER all browser commands are done
-qqbrowser-skill task_end
+```bash
+# ✅ Preferred: semantic locator (stable across page changes)
+browser_find_and_act --by text --value "{{target_text}}" --action click
 
-# Retrieve the most recent completed task recording
-qqbrowser-skill task_latest
+# ⚠️ Acceptable: index-based (for stable page structures only)
+browser_click_element --index 15_abc1_def2
 ```
 
-### Output
+---
+
+## Generating Replay Scripts / Playbooks
+
+### Auto-Generate Trigger
 
-The recorded commands are saved as a JSON file in `~/.qqbrowser-skill/records/` directory. The output format is compatible with the `browser_replay` command, containing a `steps` array where each step has `action` and `params` fields.
+After every `task_end`, if the task description indicates it should be replayable (e.g., contains "可回放", "replay", or is a standard operational task without AI summarization), the AI **MUST automatically**:
 
-### Notes
+1. Load the `qqbrowser-playbook` skill
+2. Run `task_latest` to get the raw recording
+3. Generate a clean playbook (filtering out AI-only commands, parameterizing user data)
+4. Save to `~/.qqbrowser-skill/playbooks/<name>.json`
 
-- `task_begin` and `task_end` do not interact with the browser — they only manage the recording state
-- If `task_begin` is called while a previous recording is still active (not ended), the previous recording is discarded
-- All browser skill commands executed between `task_begin` and `task_end` are automatically recorded
-- The recorded file can be used as a reference for generating parameterized replay scripts
-- Use `task_latest` to retrieve the content of the most recently completed recording (useful for reviewing or processing the recorded steps)
+**DO NOT** simply tell the user to run `browser_replay --script <raw_recording_path>`. Raw recordings contain trial-and-error steps and AI-only commands — they are NOT replay-ready.
 
-### Generating Replay Scripts / Playbooks
+### Explicit Trigger
 
-**CRITICAL**: When the user asks to "save as replay script", "generate playbook", "保存成回放脚本", "生成回放脚本", or any similar request to create a reusable automation script:
+When the user explicitly asks to "save as replay script" / "generate playbook" / "保存成回放脚本" / "生成回放脚本":
 
-1. You **MUST** load and follow the `qqbrowser-playbook` skill instructions
-2. You **MUST** use `task_latest` to get the recorded steps — do NOT fabricate steps
-3. You **MUST** save the file to `~/.qqbrowser-skill/playbooks/<name>.json` (macOS/Linux) or `%LOCALAPPDATA%/qqbrowser-skill/playbooks/<name>.json` (Windows)
-4. You **MUST** use the exact JSON format specified in the `qqbrowser-playbook` skill (with `metadata`, `params`, `settings`, `steps` structure)
+Same workflow as above.
 
-**DO NOT**:
+### Rules
 
-- Save to any other directory (e.g., `~/.qbotclaw/workspace/` or project directories)
-- Use a flat/simplified JSON format — the format has specific nested structure requirements
-- Skip loading the playbook skill — it contains the authoritative format specification
+1. **MUST** load the `qqbrowser-playbook` skill for format specification
+2. **MUST** use `task_latest` to get recorded steps — do NOT fabricate
+3. **MUST** filter out all AI-only commands (`browser_snapshot`, `browser_screenshot`, `browser_get_info`, `browser_check_state`, etc.)
+4. **MUST** save to `~/.qqbrowser-skill/playbooks/<name>.json` (macOS/Linux) or `%LOCALAPPDATA%/qqbrowser-skill/playbooks/<name>.json` (Windows)
+5. **MUST** use the exact JSON format from the `qqbrowser-playbook` skill specification
+6. **MUST NOT** output the raw recording path as the "replay script" — it is source material, not a ready playbook