@qqbrowser/openclaw-qbot 0.10.13 → 0.10.16

package/skills/qqbrowser-skill/SKILL.md

@@ -10,310 +10,318 @@ permissions:
 
 # qqbrowser-skill
 
-## Platform Support
+## Installation
 
-- **Linux x86_64**: Supported
-- **Windows**: Supported
-- **macOS**: Supported
-- Other Linux architectures (ARM, etc.) are not supported.
+```bash
+# Linux / macOS
+pipx install qqbrowser-skill && qqbrowser-skill install
+# Windows
+pip install qqbrowser-skill && qqbrowser-skill install
+```
 
-## Security
+## Key Concepts
 
-### Permissions
+- **Element Index**: Encoded string like `2_sfli_qp0u` (`highlightIndex_attrHash_xpathHash`). Generated by `browser_snapshot`, used to target elements.
+- **Snapshot**: Returns page content with indexed elements. Re-snapshot after any DOM change.
+- **Task Recording**: All manual browser tasks MUST be wrapped with `task_begin`/`task_end`.
 
-This skill requires the following permissions to function properly:
+---
 
-| 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     |
+## ⚠️ Task Execution Priority (MANDATORY)
 
-### QQBrowser Binary
+> **CRITICAL: You MUST run `playbook_list` BEFORE any `task_begin` or `browser_go_to_url`. NEVER start manual automation without first checking for existing playbooks.**
 
-The `qqbrowser-skill install` command downloads the QQ Browser package from official Tencent distribution channels via HTTPS:
+```
+User task → playbook_list (MANDATORY) → Match? → YES → browser_replay
+                                                → NO  → Manual automation
+```
 
-- **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.
+### Step 0: Check Playbooks (DO NOT SKIP)
 
-### File Storage
+```bash
+qqbrowser-skill playbook_list
+```
 
-- **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.
+1. Match returned playbooks against user's task by `name`, `description`, keywords, target URL
+2. If matched (even partially): `browser_replay --script <path> --variables '{...}'`
+3. Only if NO match: proceed to manual automation
 
-## Note:
+### Step 1: Composite Task — Multi-Playbook Orchestration
 
-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.
+For tasks spanning multiple domains (e.g., "从知乎获取文章然后发到小红书"):
 
-## ⚠️ MANDATORY: Task Recording Required
+```
+Composite task → Decompose into sub-tasks → Match EACH against playbook_list
+→ Execute pipeline: playbook₁ → AI mediation → playbook₂ → ...
+```
 
-**EVERY browser automation task MUST be wrapped with `task_begin` and `task_end`.** This is NOT optional.
+**Rules:**
+1. Break request into atomic browser operations, match each independently
+2. AI mediates BETWEEN playbooks (summarize, rewrite, transform format) — no browser commands needed
+3. Each playbook runs independently — never chain inside a single `task_begin`/`task_end`
+4. If a sub-task has no playbook, fall back to manual for that sub-task only
+5. Report progress after each stage
 
+**Example:**
 ```bash
-# ALWAYS start with task_begin BEFORE any browser commands
-qqbrowser-skill task_begin --description "描述你要做的任务"
+# Sub-task A: playbook exists
+qqbrowser-skill browser_replay --script ~/.qqbrowser-skill/playbooks/zhihu-article-extractor.json \
+  --variables '{"topic": "人工智能", "count": "3"}'
+# AI mediation: transform extracted content to target platform style
+# Sub-task B: playbook exists
+qqbrowser-skill browser_replay --script ~/.qqbrowser-skill/playbooks/xiaohongshu-publish.json \
+  --variables '{"notes_title": "AI生成标题", "notes_content": "转换后内容"}'
+```
+
+### Step 2: Fallback to Manual Automation
 
-# ... your browser commands here ...
+Only when: no matching playbook / replay failed after retry / task requires dynamic AI decisions.
 
-# ALWAYS end with task_end AFTER all browser commands are done
+### Step 3: Save as Playbook (explicit user request only)
+
+Trigger words: "save this", "make reusable", "保存为脚本", "下次还要用"
+→ Load `qqbrowser-playbook` skill → `task_latest` → generate → save
+
+---
+
+## Core Workflow (Manual Automation)
+
+```bash
+qqbrowser-skill task_begin --description "描述任务"
+qqbrowser-skill browser_go_to_url --url <url>
+qqbrowser-skill browser_snapshot                    # Get element indices
+# ... interact using indices ...
+qqbrowser-skill browser_snapshot                    # Re-snapshot after DOM changes
 qqbrowser-skill task_end
 ```
 
-**Rules:**
-
-- `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
+---
 
-## Core Workflow
+## Command Reference
 
-Every browser automation follows this pattern:
+### Navigation
+```bash
+browser_go_to_url --url <url>
+browser_go_back
+browser_wait --seconds <n>              # Default 3s
+```
 
-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`
+### Snapshot & Screenshot
+```bash
+browser_snapshot                        # Element indices (for interaction)
+browser_snapshot --markdown             # Markdown (for reading)
+browser_screenshot [--full] [--annotate]
+```
 
+### Click & Input
 ```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
+browser_click_element --index <id>
+browser_dblclick_element --index <id>
+browser_focus_element --index <id>
+browser_input_text --index <id> --text "<content>"
 ```
 
-## Essential Commands
+### Scroll
+```bash
+browser_scroll_down [--amount <px>]
+browser_scroll_up [--amount <px>]
+browser_scroll_to_text --text "<text>"
+browser_scroll_to_top / browser_scroll_to_bottom
+browser_scroll_by --direction <dir> --pixels <n> [--index <id>]
+browser_scroll_into_view --index <id>
+```
 
+### Keyboard
 ```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_keypress --key <key>
+browser_keyboard_op --action type --text "<content>"
+browser_keyboard_op --action inserttext --text "<content>"
+browser_keydown --key <key> / browser_keyup --key <key>
 ```
 
-## Common Patterns
+### 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
+```
 
-### Form Submission
+### Find and Act (Semantic Locators)
+```bash
+browser_find_and_act --by <role|text|label|placeholder|testid|css> --value "<v>" --action <click|fill|type> [--actionValue "<v>"] [--name "<n>"] [--nth <n>]
+```
+> `--nth`: 0-based index for list iteration. Use `by: "css"` + `--nth` for loops.
 
+### Get Information & State
 ```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
+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>
 ```
 
-### Data Extraction
+> **`list_selector`**: Auto-detect CSS selector for list iteration. Pass any list item's index → returns `{"selector": "...", "count": N, "samples": [...]}`. Use the returned selector in `find_and_act --by css --value <selector> --nth N`.
 
-Choose the right `browser_snapshot` mode based on intent:
+### JavaScript Evaluation
+```bash
+browser_eval_content_js --script "<js_code>"
+browser_eval_content_js --script "<base64>" --base64
+```
+
+### Download
+```bash
+browser_download_file --index <id>
+browser_download_url
+```
 
-- **`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.
+### Tab Management
+```bash
+browser_tab_open --url <url>
+browser_tab_list
+browser_tab_switch --tabId <n>
+browser_tab_close --tabId <n>
+```
 
+### Dialog
 ```bash
-qqbrowser-skill browser_go_to_url --url https://example.com/products
-qqbrowser-skill browser_snapshot --markdown                # Read the whole page as clean markdown
+browser_dialog --action <accept|dismiss> [--text "<input>"]
+```
 
-# 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
+### Replay & Playbook
+```bash
+playbook_list                              # List available playbooks
+browser_replay --script <path> [--variables '{"key":"value"}']
+browser_replay --script_content '<json>'
+```
+> ⚠️ `browser_replay` can take **up to 10 minutes**. Wait patiently — do NOT interrupt.
+
+**`browser_replay` Output Format:**
+```json
+{
+  "success": true,
+  "total_steps": 5,
+  "completed_steps": 5,
+  "step_results": [
+    {"index": 0, "action": "browser_go_to_url", "description": "...", "success": true, "result": "Success! Navigated to ..."},
+    {"index": 1, "action": "browser_eval_content_js", "description": "提取数据", "success": true, "result": "{\"title\":\"...\",\"content\":\"...\"}"}
+  ],
+  "duration_ms": 12345,
+  "summary": "Replay completed successfully: 5/5 steps in 12345ms."
+}
 ```
 
-### Infinite Scroll Pages
+**How to use the output (especially for composite tasks):**
+- `success`: Check overall success/failure. If `false`, check `failed_step` for error details.
+- `step_results[N].result`: Contains the return value of each step. **For `browser_eval_content_js` steps, this is the extracted data (usually JSON string)** — parse it for use in subsequent AI processing or next playbook's variables.
+- For composite pipelines: find all `eval_content_js` steps in `step_results`, parse their `result` field to get structured data for AI mediation.
+
+### Task Recording
+```bash
+task_begin --description "<desc>"
+task_end
+task_latest                                # Get most recent recording
+```
+> After `task_end`, raw recordings are NOT replay-ready. Must generate proper playbook.
 
+### Utility
 ```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_done --success --text "<msg>"
+status
+list
 ```
 
-## Element Index Lifecycle (Important)
+---
+
+## Replay-Friendly Execution Rules
 
-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 1: Task Classification
 
-- Clicking links or buttons that navigate
-- Form submissions
-- Dynamic content loading (dropdowns, modals, AJAX)
+| Category | Replayable? | Strategy |
+|----------|-------------|----------|
+| **A: Fixed-path** (navigate, click, fill) | ✅ | Standard commands |
+| **B: Data extraction** | ⚠️ | Use `browser_eval_content_js`, NOT `snapshot --markdown` |
+| **C: Content understanding** | ❌ | Mark `"requires_ai": true` |
+| **D: Dynamic iteration** | ⚠️ | Fixed operation count |
+
+### Rule 2: Data Extraction — Always Prefer JS
 
 ```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
+# ✅ Replayable
+browser_eval_content_js --script "JSON.stringify(Array.from(document.querySelectorAll('.item')).slice(0,10).map(el=>({title:el.querySelector('.title')?.textContent?.trim()})))"
+# ❌ Non-replayable
+browser_snapshot --markdown  # then AI summarizes
 ```
 
-## Evaluation Report
+### Rule 3: Analyze First, Execute Once
 
-See the full skill evaluation report: [QQBrowserSkillReport](https://bak.res.qq.com/nav/qqbrowser_skills/QQBrowserSkillReport.html)
+Do NOT trial-and-error during recorded tasks. Use `browser_snapshot` to analyze, then write ONE definitive script. If it fails, `task_end` → discard → re-record.
 
-## Task Recording (Important for AI Agents)
+**PROHIBITED:**
+- ❌ Multiple `eval_content_js` with different selectors
+- ❌ Hardcoding element index in JS scripts
+- ❌ Using regex on page text as selector strategy
 
-**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.
+### Rule 4: JS Selector Priority
 
-### Workflow
+`id` > `data-*` > ARIA > semantic class > structural path. ❌ NEVER use dynamic/hash classes (`.css-1a2b3c`).
 
-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
+### Rule 5: Loop Recording
 
-### Commands
+Record **at least 2 iterations** using `browser_find_and_act --by css --nth`:
 
 ```bash
-# Start recording — call this BEFORE any browser commands for the task
-qqbrowser-skill task_begin --description "自动打开小红书并发布一篇笔记"
+# ★ MANDATORY: Discover selector first
+browser_get_info --type list_selector --index "3_abc1_def2"
+# Record probe for playbook generator:
+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())})"
+# Iteration 1:
+browser_find_and_act --by css --value ".result-item h2 a" --action click --nth 1
+# ... extract, go back ...
+# Iteration 2:
+browser_find_and_act --by css --value ".result-item h2 a" --action click --nth 2
+# ... extract, go back ...
+```
 
-# ... 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 ...
+**Key:** Use `list_selector` to discover CSS selector (NEVER guess). Use `find_and_act --nth` (not `click_element` with hardcoded index).
 
-# Stop recording — call this AFTER all browser commands are done
-qqbrowser-skill task_end
+### Rule 6: Multi-Tab Recording
 
-# Retrieve the most recent completed task recording
-qqbrowser-skill task_latest
-```
+When links open new tabs:
+1. After click, `browser_tab_list` to detect new tab
+2. `browser_tab_switch` → extract → `browser_tab_close` → `browser_tab_switch` back
+3. Do NOT use `browser_go_back` for cross-tab navigation
+4. Record 2+ iterations for loop detection
 
-### Output
+### Rule 7: Fixed vs Variable Parameters
 
-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.
+| Fixed (never parameterize) | Variable (→ `{{param}}`) |
+|---|---|
+| `index`, `action`, base URLs, `settings` | `text`, query params, `actionValue`, count in scripts |
 
-### Notes
+### Rule 8: Non-Replayable Commands (filtered during replay)
 
-- `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)
+`browser_snapshot`, `browser_screenshot`, `browser_get_info`, `browser_check_state`, `browser_get_dropdown_options`, `browser_tab_list`
 
-### Generating Replay Scripts / Playbooks
+### Rule 9: Prefer `browser_find_and_act` for Dynamic Content
 
-**CRITICAL**: When the user asks to "save as replay script", "generate playbook", "保存成回放脚本", "生成回放脚本", or any similar request to create a reusable automation script:
+```bash
+# ✅ Stable across page changes
+browser_find_and_act --by text --value "{{target}}" --action click
+# ⚠️ Only for stable structures
+browser_click_element --index 15_abc1_def2
+```
 
-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)
+---
 
-**DO NOT**:
+## Generating Playbooks
 
-- 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
+After `task_end`, if task is replayable:
+
+1. Load `qqbrowser-playbook` skill
+2. `task_latest` → get raw recording
+3. Generate clean playbook (filter AI-only commands, parameterize user data)
+4. Save to `~/.qqbrowser-skill/playbooks/<name>.json`
+
+**Rules:**
+- MUST base on `task_latest` — never fabricate steps
+- MUST filter excluded commands
+- MUST use `qqbrowser-playbook` skill JSON format
+- Raw recordings are NOT replay-ready — always generate proper playbook

package/node_modules/@smithy/core/dist-cjs/getSmithyContext.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSmithyContext = void 0;
-const types_1 = require("@smithy/types");
-const getSmithyContext = (context) => context[types_1.SMITHY_CONTEXT_KEY] || (context[types_1.SMITHY_CONTEXT_KEY] = {});
-exports.getSmithyContext = getSmithyContext;

package/node_modules/@smithy/core/dist-cjs/middleware-http-auth-scheme/getHttpAuthSchemeEndpointRuleSetPlugin.js

@@ -1,21 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getHttpAuthSchemeEndpointRuleSetPlugin = exports.httpAuthSchemeEndpointRuleSetMiddlewareOptions = void 0;
-const httpAuthSchemeMiddleware_1 = require("./httpAuthSchemeMiddleware");
-exports.httpAuthSchemeEndpointRuleSetMiddlewareOptions = {
-    step: "serialize",
-    tags: ["HTTP_AUTH_SCHEME"],
-    name: "httpAuthSchemeMiddleware",
-    override: true,
-    relation: "before",
-    toMiddleware: "endpointV2Middleware",
-};
-const getHttpAuthSchemeEndpointRuleSetPlugin = (config, { httpAuthSchemeParametersProvider, identityProviderConfigProvider, }) => ({
-    applyToStack: (clientStack) => {
-        clientStack.addRelativeTo((0, httpAuthSchemeMiddleware_1.httpAuthSchemeMiddleware)(config, {
-            httpAuthSchemeParametersProvider,
-            identityProviderConfigProvider,
-        }), exports.httpAuthSchemeEndpointRuleSetMiddlewareOptions);
-    },
-});
-exports.getHttpAuthSchemeEndpointRuleSetPlugin = getHttpAuthSchemeEndpointRuleSetPlugin;

package/node_modules/@smithy/core/dist-cjs/middleware-http-auth-scheme/getHttpAuthSchemePlugin.js

@@ -1,21 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getHttpAuthSchemePlugin = exports.httpAuthSchemeMiddlewareOptions = void 0;
-const httpAuthSchemeMiddleware_1 = require("./httpAuthSchemeMiddleware");
-exports.httpAuthSchemeMiddlewareOptions = {
-    step: "serialize",
-    tags: ["HTTP_AUTH_SCHEME"],
-    name: "httpAuthSchemeMiddleware",
-    override: true,
-    relation: "before",
-    toMiddleware: "serializerMiddleware",
-};
-const getHttpAuthSchemePlugin = (config, { httpAuthSchemeParametersProvider, identityProviderConfigProvider, }) => ({
-    applyToStack: (clientStack) => {
-        clientStack.addRelativeTo((0, httpAuthSchemeMiddleware_1.httpAuthSchemeMiddleware)(config, {
-            httpAuthSchemeParametersProvider,
-            identityProviderConfigProvider,
-        }), exports.httpAuthSchemeMiddlewareOptions);
-    },
-});
-exports.getHttpAuthSchemePlugin = getHttpAuthSchemePlugin;