@qqbrowser/openclaw-qbot 0.10.11 → 0.10.13

package/skills/qqbrowser-playbook/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: qqbrowser-playbook
+description: Playbook management skill for generating, listing, and running parameterized browser automation replay scripts. Use after completing a browser automation task with qqbrowser-skill to convert the recorded steps into a reusable, parameterized playbook.
+source: local
+homepage: https://browser.qq.com/
+permissions:
+  - filesystem: Required for reading/writing playbook files in the playbooks directory
+  - network: Required for executing replay via qqbrowser-skill
+---
+
+# qqbrowser-playbook
+
+A skill for managing browser automation playbooks. It works alongside `qqbrowser-skill` to convert raw task recordings into reusable, parameterized replay scripts.
+
+## 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`:
+
+| Platform | Playbooks Directory |
+|----------|-------------------|
+| Linux / macOS | `~/.qqbrowser-skill/playbooks/` |
+| Windows | `%LOCALAPPDATA%/qqbrowser-skill/playbooks/` |
+
+**To determine the playbooks directory at runtime:**
+
+```bash
+# Linux / macOS
+PLAYBOOKS_DIR="$HOME/.qqbrowser-skill/playbooks"
+
+# Windows (PowerShell)
+$PLAYBOOKS_DIR = "$env:LOCALAPPDATA/qqbrowser-skill/playbooks"
+```
+
+File naming convention: `<name>.json` (name derived from metadata, kebab-case, e.g. `xiaohongshu-publish-note.json`)
+
+## Workflow
+
+### Step 1: Get the Latest Task Recording
+
+```bash
+qqbrowser-skill task_latest
+```
+
+This returns a JSON object with the raw recorded steps. Example output:
+
+```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"
+}
+```
+
+### Step 2: AI Analyzes and Generates the Playbook
+
+Based on the task recording, you (the AI) must:
+
+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)
+
+**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.
+
+### Step 3: Write the Playbook File
+
+Generate a JSON file conforming to this exact format and save it to the playbooks directory:
+
+```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": "点击暂存离开"
+    }
+  ]
+}
+```
+
+## Playbook File Format Specification
+
+| 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 |
+
+### Parameter Placeholder Syntax
+
+Use `{{param_name}}` in step params to reference a defined parameter. The param_name must match a key in the top-level `params` object.
+
+## Commands
+
+### Generate a Playbook
+
+After retrieving task_latest output, write the generated playbook JSON to the playbooks directory:
+
+```bash
+# 1. Get the latest recording
+qqbrowser-skill task_latest
+
+# 2. AI analyzes the output and generates the playbook content (this is done by you, the AI)
+
+# 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"
+
+# 4. Save the JSON file as <kebab-case-name>.json in the playbooks directory
+```
+
+### List Available Playbooks
+
+```bash
+# Linux / macOS
+ls ~/.qqbrowser-skill/playbooks/
+
+# Windows (PowerShell)
+Get-ChildItem "$env:LOCALAPPDATA/qqbrowser-skill/playbooks"
+```
+
+To show details of a specific playbook:
+
+```bash
+cat "<playbooks_dir>/<name>.json"
+```
+
+### Run a Playbook
+
+Use `qqbrowser-skill browser_replay` to execute a playbook:
+
+```bash
+# Run without parameters (all params must have defaults or be optional)
+qqbrowser-skill browser_replay --script "<playbooks_dir>/<name>.json"
+
+# Run with parameters
+qqbrowser-skill browser_replay --script "<playbooks_dir>/<name>.json" --variables '{"notes_title": "今日分享", "notes_content": "这是内容..."}'
+```
+
+## Parameter Extraction Guidelines
+
+When analyzing task recordings to identify parameters, follow these rules:
+
+### 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
+
+### 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
+
+### 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`
+
+## Example: Full Workflow
+
+```
+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
+```
+
+## 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 |

package/skills/qqbrowser-skill/SKILL.md

@@ -28,6 +28,14 @@ This skill requires the following permissions to function properly:
 | **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     |
 
+### QQBrowser Binary
+
+The `qqbrowser-skill install` command downloads the QQ Browser package from official Tencent distribution channels via HTTPS:
+
+- **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.
+
 ### File Storage
 
 - **Screenshots**: Saved to the system's temporary directory (e.g., `/tmp/` on Linux) and returned as file paths.
@@ -36,28 +44,53 @@ This skill requires the following permissions to function properly:
 
 ## Note:
 
-Each command will return a snapshot of the current page after execution, including the index of elements.
+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.
 
+## ⚠️ MANDATORY: Task Recording Required
+
+**EVERY browser automation task MUST be wrapped with `task_begin` and `task_end`.** This is NOT optional.
+
+```bash
+# ALWAYS start with task_begin BEFORE any browser commands
+qqbrowser-skill task_begin --description "描述你要做的任务"
+
+# ... your browser commands here ...
+
+# ALWAYS end with task_end AFTER all browser commands are done
+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
 
 Every browser automation follows this pattern:
 
-1. **Navigate**: `qqbrowser-skill browser_go_to_url --url <url>`
-2. **Snapshot**: `qqbrowser-skill browser_snapshot` (get indexed element refs)
-3. **Interact**: Use element index to click, fill, select
-4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
+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`
 
 ```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] input "email", [2] input "password", [3] button "Submit"
+# 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 --text "user@example.com"
-qqbrowser-skill browser_input_text --index 2 --text "password123"
-qqbrowser-skill browser_click_element --index 3
+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
 ```
 
 ## Essential Commands
@@ -75,11 +108,11 @@ qqbrowser-skill browser_screenshot                   # Take screenshot (returns
 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)
-qqbrowser-skill browser_click_element --index 1      # Click element
-qqbrowser-skill browser_dblclick_element --index 1   # Double-click element
-qqbrowser-skill browser_focus_element --index 1      # Focus element
-qqbrowser-skill browser_input_text --index 1 --text "hello"  # Input text into element
+# 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
@@ -89,9 +122,9 @@ 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   # Scroll element by direction
-qqbrowser-skill browser_scroll_into_view --index 5   # Scroll element into view
+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
@@ -101,26 +134,26 @@ 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           # Get dropdown options
-qqbrowser-skill browser_select_dropdown_option --index 2 --text "Option A"  # Select option
+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 --value               # Check checkbox
-qqbrowser-skill browser_check_op --index 4 --no-value            # Uncheck 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   # Get element text
+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   # Get element HTML
-qqbrowser-skill browser_get_info --type value --index 1  # Get element value
-qqbrowser-skill browser_get_info --type attr --index 1 --attribute href   # Get attribute
+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    # Get bounding box
-qqbrowser-skill browser_get_info --type styles --index 1 # Get computed styles
-qqbrowser-skill browser_check_state --state visible --index 1    # Check visibility
-qqbrowser-skill browser_check_state --state enabled --index 1    # Check if enabled
-qqbrowser-skill browser_check_state --state checked --index 1    # Check if checked
+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"
@@ -130,7 +163,7 @@ qqbrowser-skill browser_find_and_act --by placeholder --value "Search" --action
 qqbrowser-skill browser_find_and_act --by testid --value "submit-btn" --action click
 
 # Download
-qqbrowser-skill browser_download_file --index 5      # Download file by clicking element
+qqbrowser-skill browser_download_file --index 5_xyz3_uvw4      # Download file by clicking element
 qqbrowser-skill browser_download_url                 # Download from URL
 
 # Tab Management
@@ -148,10 +181,20 @@ qqbrowser-skill browser_dialog --action accept --text "input text"  # Accept pro
 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
@@ -167,11 +210,11 @@ qqbrowser-skill status                               # Check skill status
 ```bash
 qqbrowser-skill browser_go_to_url --url https://example.com/signup
 qqbrowser-skill browser_snapshot
-qqbrowser-skill browser_input_text --index 1 --text "Jane Doe"
-qqbrowser-skill browser_input_text --index 2 --text "jane@example.com"
-qqbrowser-skill browser_select_dropdown_option --index 3 --text "California"
-qqbrowser-skill browser_check_op --index 4 --value
-qqbrowser-skill browser_click_element --index 5
+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
 ```
@@ -189,7 +232,7 @@ qqbrowser-skill browser_snapshot --markdown                # Read the whole page
 
 # 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     # Get a specific element's text
+qqbrowser-skill browser_get_info --type text --index 5_abc1_def2     # Get a specific element's text
 ```
 
 ### Infinite Scroll Pages
@@ -203,18 +246,74 @@ qqbrowser-skill browser_snapshot             # Get updated content
 
 ## Element Index Lifecycle (Important)
 
-Element indices are invalidated when the page changes. Always re-snapshot after:
+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:
 
 - Clicking links or buttons that navigate
 - Form submissions
 - Dynamic content loading (dropdowns, modals, AJAX)
 
 ```bash
-qqbrowser-skill browser_click_element --index 5   # May navigate to new page
-qqbrowser-skill browser_snapshot                   # MUST re-snapshot
-qqbrowser-skill browser_click_element --index 1   # Use new indices
+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
 ```
 
 ## Evaluation Report
 
 See the full skill evaluation report: [QQBrowserSkillReport](https://bak.res.qq.com/nav/qqbrowser_skills/QQBrowserSkillReport.html)
+
+## Task Recording (Important for AI Agents)
+
+**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.
+
+### Workflow
+
+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
+
+### Commands
+
+```bash
+# Start recording — call this BEFORE any browser commands for the task
+qqbrowser-skill task_begin --description "自动打开小红书并发布一篇笔记"
+
+# ... 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 ...
+
+# Stop recording — call this AFTER all browser commands are done
+qqbrowser-skill task_end
+
+# Retrieve the most recent completed task recording
+qqbrowser-skill task_latest
+```
+
+### Output
+
+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.
+
+### Notes
+
+- `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)
+
+### Generating Replay Scripts / Playbooks
+
+**CRITICAL**: When the user asks to "save as replay script", "generate playbook", "保存成回放脚本", "生成回放脚本", or any similar request to create a reusable automation script:
+
+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**:
+
+- 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

package/node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-utf8/dist-cjs/index.js

@@ -1,65 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  fromUtf8: () => fromUtf8,
-  toUint8Array: () => toUint8Array,
-  toUtf8: () => toUtf8
-});
-module.exports = __toCommonJS(src_exports);
-
-// src/fromUtf8.ts
-var import_util_buffer_from = require("@smithy/util-buffer-from");
-var fromUtf8 = /* @__PURE__ */ __name((input) => {
-  const buf = (0, import_util_buffer_from.fromString)(input, "utf8");
-  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength / Uint8Array.BYTES_PER_ELEMENT);
-}, "fromUtf8");
-
-// src/toUint8Array.ts
-var toUint8Array = /* @__PURE__ */ __name((data) => {
-  if (typeof data === "string") {
-    return fromUtf8(data);
-  }
-  if (ArrayBuffer.isView(data)) {
-    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength / Uint8Array.BYTES_PER_ELEMENT);
-  }
-  return new Uint8Array(data);
-}, "toUint8Array");
-
-// src/toUtf8.ts
-
-var toUtf8 = /* @__PURE__ */ __name((input) => {
-  if (typeof input === "string") {
-    return input;
-  }
-  if (typeof input !== "object" || typeof input.byteOffset !== "number" || typeof input.byteLength !== "number") {
-    throw new Error("@smithy/util-utf8: toUtf8 encoder function only accepts string | Uint8Array.");
-  }
-  return (0, import_util_buffer_from.fromArrayBuffer)(input.buffer, input.byteOffset, input.byteLength).toString("utf8");
-}, "toUtf8");
-// Annotate the CommonJS export names for ESM import in node:
-
-0 && (module.exports = {
-  fromUtf8,
-  toUint8Array,
-  toUtf8
-});
-

package/node_modules/@aws-crypto/sha256-browser/node_modules/@smithy/util-utf8/dist-es/index.js

@@ -1,3 +0,0 @@
-export * from "./fromUtf8";
-export * from "./toUint8Array";
-export * from "./toUtf8";