@qqbrowser/openclaw-qbot 0.10.13 → 0.10.15

package/skills/qqbrowser-playbook/SKILL.md

@@ -10,293 +10,321 @@ permissions:
 
 # qqbrowser-playbook
 
-A skill for managing browser automation playbooks. It works alongside `qqbrowser-skill` to convert raw task recordings into reusable, parameterized replay scripts.
+Convert raw `qqbrowser-skill` task recordings into reusable, parameterized replay scripts.
+
+## Critical Rules
+
+1. A playbook **MUST** be generated from actual task recording (`task_latest`). NEVER fabricate steps.
+2. Only use actions from `task_latest` — copy action names and index values **verbatim**.
+3. Only replace **user data** (`text`, `url`, file path) with `{{param_name}}`. NEVER replace `action` or `index`.
+4. Save to `~/.qqbrowser-skill/playbooks/<kebab-case-name>.json`. Create dir first: `mkdir -p ~/.qqbrowser-skill/playbooks`.
+5. JSON structure: `version` + `metadata` + `params` + `settings` + `steps`. Key is `params` not `parameters`.
+
+## Valid Actions
+
+### ✅ Allowed (replayable)
+
+| Action | Parameterizable Fields |
+|--------|----------------------|
+| `browser_go_to_url` | `url` |
+| `browser_click_element` / `browser_dblclick_element` / `browser_focus_element` | — |
+| `browser_input_text` / `browser_keyboard_op` | `text` |
+| `browser_keypress` / `browser_keydown` / `browser_keyup` | — |
+| `browser_select_dropdown_option` | `text` |
+| `browser_check_op` | — |
+| `browser_scroll_down` / `browser_scroll_up` / `browser_scroll_to_top` / `browser_scroll_to_bottom` / `browser_scroll_by` / `browser_scroll_into_view` | — |
+| `browser_scroll_to_text` | `text` |
+| `browser_wait` | — |
+| `browser_go_back` | — |
+| `browser_dialog` | `text` |
+| `browser_tab_open` | `url`, `as` (alias). Use semantic refs, NOT physical `tabId` |
+| `browser_tab_switch` / `browser_tab_close` | `tab` (`"origin"` / `"current"` / `"latest"` / custom alias) |
+| `browser_download_file` / `browser_download_url` | — |
+| `browser_eval_content_js` | `script` |
+| `browser_find_and_act` | `value`, `actionValue`, `name`, `nth` |
+| `loop` | `count`, nested `steps` |
+
+### ❌ Excluded (filter out from recording)
+
+`browser_snapshot`, `browser_screenshot`, `browser_get_info`, `browser_check_state`, `browser_get_dropdown_options`, `browser_tab_list`, `task_begin`/`task_end`/`task_latest`, `browser_done`
+
+## Playbook JSON Format
 
-## Overview
-
-After you complete a browser automation task using `qqbrowser-skill` (wrapped in `task_begin`/`task_end`), use this skill to:
-
-1. **Retrieve** the latest task recording
-2. **Analyze** the steps and identify values that should be parameterized
-3. **Generate** a playbook file (parameterized replay script)
-4. **List** all available playbooks
-5. **Run** a playbook with specified parameters
-
-**CRITICAL RULES:**
-- A playbook MUST be generated from an actual task recording (`task_latest`). You MUST NOT invent or fabricate steps.
-- You MUST only use actions that appear in the `task_latest` output. These are the only valid actions for the playbook.
-- The generated playbook steps must be a direct transformation of the recorded steps — only replacing literal user data with `{{param_name}}` placeholders.
-- Element identification MUST use the `index` field from the recording (e.g., `"index": "154_17q6_1w8c"`). Do NOT substitute indices with arbitrary values.
-- If no recording exists (`task_latest` returns empty), you MUST first complete the task using `qqbrowser-skill` with `task_begin`/`task_end`, then generate the playbook from the recording.
-- **FILE PATH**: Playbook files MUST be saved to `~/.qqbrowser-skill/playbooks/<name>.json` on macOS/Linux. Do NOT save to any other directory such as `~/.qbotclaw/`, project directories, or temp directories.
-- **FILE FORMAT**: The JSON file MUST follow the exact nested structure defined below (with `version`, `metadata`, `params`, `settings`, `steps` as top-level keys). Do NOT use a flat/simplified format. Do NOT use `parameters` instead of `params`. Do NOT omit `metadata` or `settings`.
-- **USE write_to_file**: When saving the playbook JSON, use the `write_to_file` tool with the full absolute path (e.g., `/Users/<username>/.qqbrowser-skill/playbooks/xiaohongshu-publish-note.json`). Ensure the directory exists first (create with `mkdir -p`).
-
-## Playbook Storage
-
-Playbooks are stored in the `playbooks` subdirectory under the qqbrowser-skill data directory (`DEFAULT_DATA_DIR/playbooks/`). The data directory follows the same convention as `qqbrowser-skill`:
+```json
+{
+  "version": "1.0",
+  "metadata": {
+    "name": "小红书发布笔记",
+    "description": "自动打开小红书并发布一篇笔记",
+    "created_at": "2026-05-21T16:59:00Z",
+    "url": "https://www.xiaohongshu.com/explore",
+    "requires_ai": false
+  },
+  "params": {
+    "notes_title": { "description": "笔记标题", "required": true },
+    "notes_content": { "description": "笔记正文内容", "required": true }
+  },
+  "settings": { "default_delay_ms": 1000, "default_retry_count": 1, "step_timeout_ms": 30000 },
+  "steps": [
+    { "action": "browser_go_to_url", "params": { "url": "https://www.xiaohongshu.com/explore" }, "description": "打开小红书探索页" },
+    { "action": "browser_input_text", "params": { "index": "6_2vl4_txwg", "text": "{{notes_title}}" }, "description": "输入笔记标题" },
+    { "action": "browser_click_element", "params": { "index": "19_oxgq_ttmr" }, "description": "点击发布" }
+  ]
+}
+```
 
-| Platform | Playbooks Directory |
-|----------|-------------------|
-| Linux / macOS | `~/.qqbrowser-skill/playbooks/` |
-| Windows | `%LOCALAPPDATA%/qqbrowser-skill/playbooks/` |
+**Fields**: `version`(always "1.0"), `metadata.name`, `metadata.description`, `metadata.created_at`(ISO8601) are required. `metadata.url`, `metadata.requires_ai`(default false) are optional. Each param needs `description`(string) and `required`(bool), optional `default`. Steps need `action`, `params`, `description`; optional `condition: {"param":"xx"}` for conditional execution.
 
-**To determine the playbooks directory at runtime:**
+## Parameter Extraction
 
-```bash
-# Linux / macOS
-PLAYBOOKS_DIR="$HOME/.qqbrowser-skill/playbooks"
+**Parameterize**: user text, emails, usernames, quantities, file paths, user-specific URL segments.
+**Never parameterize**: `index`, `action`, fixed workflow URLs, fixed UI buttons, `settings`.
+**Naming**: `snake_case`, descriptive (`notes_title` not `title`).
 
-# Windows (PowerShell)
-$PLAYBOOKS_DIR = "$env:LOCALAPPDATA/qqbrowser-skill/playbooks"
-```
+## Conditional Steps
 
-File naming convention: `<name>.json` (name derived from metadata, kebab-case, e.g. `xiaohongshu-publish-note.json`)
+Add `condition: {"param": "cc"}` to ALL steps dependent on an optional param. If param absent, step is skipped.
 
-## Workflow
+## Loop Steps
 
-### Step 1: Get the Latest Task Recording
+Use `loop` when recording shows **2+ repetitions** of the same action sequence differing only in target element, and count is user-controlled.
 
-```bash
-qqbrowser-skill task_latest
-```
+**Do NOT use loop** for fixed form fields or when a single `browser_eval_content_js` can extract all data at once.
 
-This returns a JSON object with the raw recorded steps. Example output:
+### Loop JSON
 
 ```json
 {
-  "task_id": "task_20260521_165900",
-  "description": "自动打开小红书并发布一篇笔记",
-  "commands": [
-    {"skill_name": "browser_go_to_url", "params": {"url": "https://www.xiaohongshu.com/explore"}},
-    {"skill_name": "browser_click_element", "params": {"index": "154_17q6_1w8c"}},
-    {"skill_name": "browser_click_element", "params": {"index": "7_ek3h_2b3r"}},
-    {"skill_name": "browser_click_element", "params": {"index": "10_4bq5_u01g"}},
-    {"skill_name": "browser_input_text", "params": {"index": "6_2vl4_txwg", "text": "我的笔记标题"}},
-    {"skill_name": "browser_input_text", "params": {"index": "4_ku44_rrpt", "text": "这是笔记的正文内容..."}},
-    {"skill_name": "browser_click_element", "params": {"index": "19_oxgq_ttmr"}}
-  ],
-  "started_at": "2026-05-21T16:59:00Z",
-  "ended_at": "2026-05-21T17:01:30Z"
+  "action": "loop",
+  "params": { "count": "{{count}}", "variable": "i", "start": 1 },
+  "description": "逐个访问前N篇文章",
+  "steps": [ ... ]
 }
 ```
 
-### Step 2: AI Analyzes and Generates the Playbook
+Fields: `count`(string/number, supports `{{param}}`), `variable`(loop var name), `start`(default 1, 1-based for `nth`).
 
-Based on the task recording, you (the AI) must:
+### Key Rules for Loop Steps
 
-1. **Keep all actions and indices exactly as recorded** — do NOT change `action` names or `index` values
-2. **Identify parameterizable values** — values that a user would likely want to change on each run:
-   - Text inputs (`browser_input_text` → the `text` field)
-   - URLs (`browser_go_to_url` → the `url` field, only if the URL varies per use)
-   - File paths in upload actions
-   - Any user-specific data (names, emails, content, etc.)
-3. **Define parameters** with descriptive names, descriptions, and whether they are required
-4. **Replace ONLY literal values** with `{{param_name}}` placeholders in the steps (only the `text`, `url`, or file path fields — NEVER replace `action` or `index`)
-5. **Add meaningful descriptions** to each step
-6. **Set appropriate metadata** (name, description, url)
+1. **Use `browser_find_and_act` with `by: "css"` + `nth: "{{i}}"`** inside loops — NOT `browser_click_element` with hardcoded index.
+2. **`by` MUST be `"css"` when `nth` is used** — NEVER `by: "text"` or `by: "label"` with `nth`. Text/label is for single unique elements, not list iteration.
+3. **`value` must be a list-level CSS selector** matching ALL items (e.g., `.ContentItem h2 a`), NOT specific text content.
+4. **CSS selector MUST come from actual DOM**, with this priority:
+   - **Best**: Extract from `__list_probe__` in recording (see Step 2b)
+   - **Good**: Use `by: "css"` selector already in recording's `find_and_act`
+   - **Fallback**: Use `browser_get_info --type list_selector --index <id>` to auto-detect, or run `browser_eval_content_js` probe to discover (before generating playbook)
+   - **NEVER**: Fabricate or guess. If all above fail, set `metadata.requires_ai: true`.
+5. **`{{i}}` is 1-based** (start=1), aligning with `nth` (nth=1 = first element).
+6. **Check recording for tab operations in each iteration** — if recording has `tab_switch`/`tab_close`, loop body MUST use `tab_switch("latest")` → ... → `tab_close("current")` → `tab_switch("origin")`. **NEVER silently convert tab-based recording to `go_back`.**
+7. **Use `browser_go_back` ONLY** if iteration stays in the **same tab** (no tab ops in recording).
+8. **Include `browser_wait`** between iterations for stability.
 
-**IMPORTANT**: The transformation from recording to playbook is purely:
-- Recording `"text": "我的搜索词"` → Playbook `"text": "{{search_keyword}}"`
-- Everything else (action names, index values, key names) stays **exactly** the same.
+### Decision Tables
 
-### Step 3: Write the Playbook File
+**Loop vs Single JS Extraction:**
 
-Generate a JSON file conforming to this exact format and save it to the playbooks directory:
+| Scenario | Method |
+|----------|--------|
+| List page data only | Single `browser_eval_content_js` |
+| Need detail page content | `loop` (navigate in/out per item) |
+| Pagination + extract | `loop` |
+| Fixed different form fields | Linear steps |
 
-```json
-{
-  "version": "1.0",
-  "metadata": {
-    "name": "小红书发布长文笔记",
-    "description": "自动打开小红书，发布一篇长文笔记并暂存离开",
-    "created_at": "2026-05-21T16:59:00Z",
-    "url": "https://www.xiaohongshu.com/explore"
-  },
-  "params": {
-    "notes_title": {
-      "description": "笔记标题",
-      "required": true
-    },
-    "notes_content": {
-      "description": "笔记正文内容",
-      "required": true
-    }
-  },
-  "settings": {
-    "default_delay_ms": 1000,
-    "default_retry_count": 1,
-    "step_timeout_ms": 30000
-  },
-  "steps": [
-    {
-      "action": "browser_go_to_url",
-      "params": { "url": "https://www.xiaohongshu.com/explore" },
-      "description": "打开小红书探索页"
-    },
-    {
-      "action": "browser_click_element",
-      "params": { "index": "154_17q6_1w8c" },
-      "description": "点击发布按钮"
-    },
-    {
-      "action": "browser_click_element",
-      "params": { "index": "7_ek3h_2b3r" },
-      "description": "选择写长文"
-    },
-    {
-      "action": "browser_click_element",
-      "params": { "index": "10_4bq5_u01g" },
-      "description": "点击新的创作"
-    },
-    {
-      "action": "browser_input_text",
-      "params": { "index": "6_2vl4_txwg", "text": "{{notes_title}}" },
-      "description": "输入笔记标题"
-    },
-    {
-      "action": "browser_input_text",
-      "params": { "index": "4_ku44_rrpt", "text": "{{notes_content}}" },
-      "description": "输入笔记正文"
-    },
-    {
-      "action": "browser_click_element",
-      "params": { "index": "19_oxgq_ttmr" },
-      "description": "点击暂存离开"
-    }
-  ]
-}
-```
+**`go_back` vs `tab_close` + `tab_switch`:**
 
-## Playbook File Format Specification
+| Scenario | Method |
+|----------|--------|
+| Link opens in **same tab** | `browser_go_back` |
+| Link opens in **new tab** | `browser_tab_close` + `browser_tab_switch` |
+| Unsure | Prefer `tab_close` + `tab_switch` (safer) |
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `version` | string | Yes | Always `"1.0"` |
-| `metadata.name` | string | Yes | Human-readable name of the playbook |
-| `metadata.description` | string | Yes | What this playbook does |
-| `metadata.created_at` | string | Yes | ISO 8601 timestamp of creation |
-| `metadata.url` | string | No | The starting URL of the automation |
-| `params` | object | No | Parameter definitions (omit if no parameters needed) |
-| `params.<key>.description` | string | Yes | What this parameter is for |
-| `params.<key>.required` | boolean | Yes | Whether the parameter must be provided |
-| `params.<key>.default` | string | No | Default value if not provided |
-| `settings.default_delay_ms` | number | Yes | Delay between steps in milliseconds |
-| `settings.default_retry_count` | number | Yes | Number of retries on step failure |
-| `settings.step_timeout_ms` | number | Yes | Timeout for each step |
-| `steps[].action` | string | Yes | The browser action (must have `browser_` prefix) |
-| `steps[].params` | object | Yes | Parameters for the action |
-| `steps[].description` | string | Yes | Human-readable step description |
+## Tab Management
 
-### Parameter Placeholder Syntax
+Playbooks **MUST use semantic tab references** — physical `tabId` changes every session.
 
-Use `{{param_name}}` in step params to reference a defined parameter. The param_name must match a key in the top-level `params` object.
+| Reference | Meaning |
+|-----------|---------|
+| `"origin"` | Tab active when replay started (always available) |
+| `"current"` | Currently active tab (dynamic) |
+| `"latest"` | Most recently opened tab (after any `tab_open`) |
+| Custom alias | Named via `"as"` param in `tab_open` |
 
-## Commands
+**Tab action examples:**
+```json
+{ "action": "browser_tab_open", "params": { "url": "https://example.com", "as": "detail" } }
+{ "action": "browser_tab_switch", "params": { "tab": "origin" } }
+{ "action": "browser_tab_close", "params": { "tab": "current" } }
+```
 
-### Generate a Playbook
+**Rules:**
+1. NEVER use physical `tabId` — always semantic references.
+2. `browser_go_back` does NOT work across tabs — use `tab_close` + `tab_switch`.
+3. After `tab_close`, explicitly `tab_switch` — don't assume Chrome's active tab.
 
-After retrieving task_latest output, write the generated playbook JSON to the playbooks directory:
+## Workflow
 
 ```bash
-# 1. Get the latest recording
+# 1. Get recording
 qqbrowser-skill task_latest
 
-# 2. AI analyzes the output and generates the playbook content (this is done by you, the AI)
+# 2. AI analyzes → generates playbook:
+#    2a: Filter excluded actions (snapshot, screenshot, tab_list, etc.)
+#    2b: Extract CSS selector from __list_probe__ (see below)
+#    2c: Detect loop patterns (repeated sequences → loop, using selector from 2b)
+#    2d: Detect tab patterns (tabId → semantic refs). NEVER silently drop tab ops.
+#    2e: Cross-check loop+tab — if loop iteration has tab ops, use tab_switch/close NOT go_back
+#    2f: Identify parameterizable values → {{param}}
+#    2g: Add descriptions, metadata, settings
+
+# 3. Save
+mkdir -p ~/.qqbrowser-skill/playbooks
+# write_to_file tool
+
+# 4. Run
+# ⚠️ browser_replay can take UP TO 10 MINUTES for complex playbooks with loops.
+# You MUST wait patiently for the command to finish. Do NOT assume it has timed out.
+qqbrowser-skill browser_replay --script ~/.qqbrowser-skill/playbooks/<name>.json \
+  --variables '{"param1": "value1"}'
+```
+
+> **⚠️ IMPORTANT**: `browser_replay` executes all playbook steps sequentially in the browser. Depending on step count, delays, and network conditions, **execution can take up to 10 minutes**. Wait for the command to return a result before proceeding — do NOT interrupt or retry prematurely.
 
-# 3. Ensure the playbooks directory exists and write the file
-# Linux / macOS:
-mkdir -p "$HOME/.qqbrowser-skill/playbooks"
-# Windows (PowerShell):
-New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA/qqbrowser-skill/playbooks"
+### Step 2b: Extract CSS Selector from Recording
 
-# 4. Save the JSON file as <kebab-case-name>.json in the playbooks directory
+**Primary source**: Look for `browser_eval_content_js` calls whose output contains `__list_probe__: true`.
+```
+Recording data example:
+  browser_eval_content_js → output: {"__list_probe__": true, "selector": ".SearchResult-Card .ContentItem h2 a", "count": 10, "samples": ["文章A", "文章B", "文章C"]}
 ```
+Extract the `selector` value — this is the **verified CSS selector** from actual DOM, use it directly in the loop's `find_and_act`.
 
-### List Available Playbooks
+**Fallback** (if no `__list_probe__` in recording):
+1. Check if recording's `find_and_act` already uses `by: "css"` — use that selector directly
+2. If recording only has `by: "text"` or `click_element(index)`, the selector is unknown
+3. Use `browser_get_info --type list_selector --index <any_list_item_index>` to auto-detect the selector
+4. If `list_selector` also fails, run `browser_eval_content_js` with a probe script to discover the selector
+5. **NEVER** guess or fabricate selectors
 
-```bash
-# Linux / macOS
-ls ~/.qqbrowser-skill/playbooks/
+### Step 2c: Loop Pattern Detection
 
-# Windows (PowerShell)
-Get-ChildItem "$env:LOCALAPPDATA/qqbrowser-skill/playbooks"
+```
+1. Group consecutive steps into sequences
+2. If 2+ adjacent sequences share the SAME action pattern → convert to `loop`
+3. What varies between iterations:
+   - `nth` increments → use `{{i}}`
+   - Different index values → replace with `find_and_act` + `nth: "{{i}}"`
+   - Different text/title in `find_and_act(by="text")` → convert to `by: "css"` + `nth: "{{i}}"`
+4. Use the CSS selector from Step 2b (from __list_probe__ or fallback probe)
+5. Convert `browser_click_element(index=...)` → `find_and_act(by="css", nth="{{i}}")`
+6. Count source: user-mentioned quantity → `{{count}}` param; fixed → literal
 ```
 
-To show details of a specific playbook:
+**Recording patterns → playbook conversion:**
 
-```bash
-cat "<playbooks_dir>/<name>.json"
+| Recording Pattern | Conversion |
+|---|---|
+| Repeated sequences with different text targets | `loop` + `by: "css"` + `nth: "{{i}}"` |
+| Repeated sequences with different `index` values | `loop` + `by: "css"` + `nth: "{{i}}"` |
+| `find_and_act(by="text", value="标题A")` → ... → `find_and_act(by="text", value="标题B")` | **MUST** convert `by: "text"` → `by: "css"` + `nth: "{{i}}"` |
+
+### Step 2d: Tab Pattern Detection
+
+```
+1. `browser_tab_open` → discard physical tabId, add semantic `"as"` alias
+2. `browser_tab_switch(tabId=N)` → replace with "origin"/"latest"/custom alias
+3. `browser_tab_close(tabId=N)` → replace with semantic ref
+4. `browser_go_back` after new tab → replace with tab_close("current") + tab_switch("origin")
 ```
 
-### Run a Playbook
+## Complete Example: Loop + New Tab
 
-Use `qqbrowser-skill browser_replay` to execute a playbook:
+This example demonstrates ALL key conversions (text→css, tabId→semantic, linear→loop):
 
-```bash
-# Run without parameters (all params must have defaults or be optional)
-qqbrowser-skill browser_replay --script "<playbooks_dir>/<name>.json"
+Recording (raw):
+```
+eval_content_js → {"__list_probe__": true, "selector": ".ContentItem h2 a", "count": 10, "samples": ["文章标题A","文章标题B","文章标题C"]}
+find_and_act(by="text", value="文章标题A", action="click")
+click_element(index="197_3i4c_uv7n")        ← opened new tab
+tab_switch(tabId=1412776911)
+eval_content_js(script="...")
+tab_close(tabId=1412776911)
+find_and_act(by="text", value="文章标题B", action="click")
+click_element(index="206_90r2_rddo")
+tab_switch(tabId=1412776913)
+eval_content_js(script="...")
+tab_close(tabId=1412776913)
+```
 
-# Run with parameters
-qqbrowser-skill browser_replay --script "<playbooks_dir>/<name>.json" --variables '{"notes_title": "今日分享", "notes_content": "这是内容..."}'
+Playbook generator extracts selector `.ContentItem h2 a` from the `__list_probe__` line.
+
+Playbook (generated):
+```json
+{
+  "version": "1.0",
+  "metadata": {
+    "name": "搜索并提取文章(新Tab场景)",
+    "description": "搜索主题，逐个在新Tab打开文章提取内容",
+    "created_at": "2026-06-02T15:00:00Z",
+    "requires_ai": false
+  },
+  "params": {
+    "topic": { "description": "搜索关键词", "required": true },
+    "count": { "description": "提取数量", "required": false, "default": "3" }
+  },
+  "settings": { "default_delay_ms": 2000, "default_retry_count": 1, "step_timeout_ms": 30000 },
+  "steps": [
+    { "action": "browser_go_to_url", "params": { "url": "https://example.com/search?q={{topic}}" }, "description": "搜索主题" },
+    { "action": "browser_wait", "params": { "seconds": 3 }, "description": "等待搜索结果" },
+    {
+      "action": "loop",
+      "params": { "count": "{{count}}", "variable": "i", "start": 1 },
+      "description": "逐个在新Tab打开文章并提取",
+      "steps": [
+        { "action": "browser_find_and_act", "params": { "by": "css", "value": ".ContentItem h2 a", "nth": "{{i}}", "action": "click" }, "description": "点击第{{i}}篇文章" },
+        { "action": "browser_tab_switch", "params": { "tab": "latest" }, "description": "切到文章Tab" },
+        { "action": "browser_wait", "params": { "seconds": 2 }, "description": "等待加载" },
+        { "action": "browser_eval_content_js", "params": { "script": "JSON.stringify({title:document.querySelector('h1')?.textContent?.trim(),content:document.querySelector('.RichText')?.textContent?.substring(0,2000)})" }, "description": "提取内容" },
+        { "action": "browser_tab_close", "params": { "tab": "current" }, "description": "关闭文章Tab" },
+        { "action": "browser_tab_switch", "params": { "tab": "origin" }, "description": "切回列表页" },
+        { "action": "browser_wait", "params": { "seconds": 1 }, "description": "等待恢复" }
+      ]
+    }
+  ]
+}
 ```
 
-## Parameter Extraction Guidelines
+**Key conversions:** `by:"text"`+title → `by:"css"`+`nth:"{{i}}"` | `click_element(index)` → merged into `find_and_act` | `tabId:N` → `"latest"`/`"current"`/`"origin"` | 2× linear → `loop`
 
-When analyzing task recordings to identify parameters, follow these rules:
+## `requires_ai` Tasks
 
-### SHOULD be parameterized:
-- **User-generated text content**: titles, messages, descriptions, comments, posts
-- **User-specific data**: usernames, email addresses, phone numbers, passwords
-- **Search queries**: any text entered into search boxes
-- **File paths**: paths to files being uploaded
-- **Variable URLs**: URLs that contain user-specific identifiers or change per use
+Set `metadata.requires_ai: true` when recording contains AI-dependent steps (summarization, comparison, conditional decisions). Include only replayable portions as steps.
 
-### Should NOT be parameterized:
-- **Fixed navigation URLs**: the starting URL of the workflow (e.g., `https://www.xiaohongshu.com/explore`)
-- **Element indices**: the `index` field in click/input actions (these are structural, not data)
-- **UI interaction steps**: clicks on fixed buttons like "Submit", "Next", "Save"
-- **Fixed option selections**: dropdown choices that are always the same for this workflow
+## `browser_find_and_act` Usage
 
-### Naming Conventions for Parameters:
-- Use `snake_case` for parameter names
-- Be descriptive: `notes_title` not `title`, `search_query` not `q`
-- Group related params with common prefix: `login_username`, `login_password`
+For single-element targeting (NOT in loops): `by: "text"` or `by: "label"` with known stable text.
+For list iteration (in loops): `by: "css"` + `nth: "{{i}}"` with list-level selector.
 
-## Example: Full Workflow
+## `browser_eval_content_js` Usage
 
-```
-User: "帮我生成一个回放脚本"
-
-AI steps:
-1. Run: qqbrowser-skill task_latest
-2. Analyze the returned commands
-3. Identify that browser_input_text steps contain user data that should be parameterized
-4. Generate the playbook JSON with params and {{placeholders}}
-5. Determine the correct playbooks directory for the current platform
-6. Ensure the playbooks directory exists (mkdir -p)
-7. Write the JSON file to <playbooks_dir>/<name>.json
-8. Report to the user: playbook name, parameters defined, file path, and how to run it
-```
+Primary data extraction method. Supports `{{param}}` in script for selectors, counts, keywords.
+Selector priority: `id` > `data-*` > ARIA > semantic class > structural path. NEVER use dynamic/hashed classes.
+
+## Common Mistakes
 
-## Notes
-
-- This skill does NOT require any additional installation — it uses `qqbrowser-skill` commands and file system operations
-- The AI is responsible for the analysis and generation logic — no separate binary or service is needed
-- Playbook files are plain JSON and can be manually edited if needed
-- Always ensure the playbooks directory exists before writing
-- The playbooks directory follows the same platform convention as `qqbrowser-skill` data directory (`~/.qqbrowser-skill/` on Linux/macOS, `%LOCALAPPDATA%/qqbrowser-skill/` on Windows)
-
-## Common Mistakes to Avoid
-
-| Mistake | Why it's wrong | Correct approach |
-|---------|---------------|-----------------|
-| Generating steps without running `task_latest` first | Playbooks must be based on actual recordings | Always run `task_latest` first, then transform |
-| Using actions not in `task_latest` output | Only actions from the recording are valid | Copy actions exactly from `task_latest` output |
-| Changing the `action` field from what was recorded | Actions must match the recording exactly | Copy action names verbatim |
-| Replacing `index` values with something else | Index is a structural reference, not user data | Never parameterize index values |
-| Using `{{param}}` in fields other than user data | Only user-provided content should be parameterized | Only replace `text`, `url`, or file path values |
-| Saving to wrong directory (e.g. `~/.qbotclaw/workspace/`) | Playbooks have a designated storage path | Always save to `~/.qqbrowser-skill/playbooks/` |
-| Using flat JSON format (top-level `name`, `parameters`, `steps`) | The schema requires nested structure | Must use `metadata.name`, `params`, `settings`, `steps` structure |
-| Using `parameters` key instead of `params` | The schema key is `params` | Use `params` with `description` and `required` fields |
-| Using `write content=` shell command to save | May corrupt JSON formatting | Use `write_to_file` tool with proper path |
+| Mistake | Fix |
+|---------|-----|
+| Including `browser_snapshot` etc. in steps | Filter out — AI-decision only |
+| Fabricating steps without `task_latest` | Always base on actual recording |
+| Parameterizing `index` or `action` | Only parameterize value fields (`text`, `url`, `script`) |
+| Using `parameters` instead of `params` | Schema key is `params` |
+| Expanding N repetitions as linear steps | Use `loop` with `{{count}}` |
+| Using `click_element` + hardcoded index in loops | Use `find_and_act` + `nth: "{{i}}"` |
+| Using `by: "text"`/`"label"` with `nth` in loops | `nth` requires `by: "css"` |
+| Keeping `by: "text"` + specific content in loops | Recording's `find_and_act(text, "标题")` MUST convert to `by: "css"` + `nth` in loop |
+| Fabricating CSS selectors | Must come from `__list_probe__` in recording, or existing `find_and_act(css)`, or a live probe — never guess |
+| Using search keyword as `value` in loop | `value` is CSS selector (`.ContentItem h2 a`), not the keyword |
+| `find_and_act(text)` + `click_element(index)` for same target | Merge into single `find_and_act(css, nth)` in loop |
+| Hardcoding physical `tabId` | Use semantic refs: `"origin"`, `"current"`, `"latest"`, custom alias |
+| `browser_go_back` after new tab opened | Use `tab_close` + `tab_switch` — new tab has no history |
+| Silently dropping tab ops from recording | If recording has tab ops, playbook MUST include tab management |
+| Loop with `go_back` when recording had tab ops | Check recording — if tab_switch/close exists, use tab management not go_back |