QQBrowserUse

SKILL.md 节选

# qqbrowser-use

Browser automation CLI for AI agents. Wraps every task in an isolated Chrome Tab Group, supports both live automation and reusable playbook replay.

## Platform Support

Linux x86_64, Windows, macOS. Other Linux architectures (ARM, etc.) are not supported.

## Installation

```bash
# Linux / macOS
pipx install qqbrowser-skill
qqbrowser-skill install   # Download and install QQ Browser

# Windows
pip install qqbrowser-skill
qqbrowser-skill install
```

## Quick Start

```bash
qqbrowser-skill browser_start_session --sessionId task-demo-001 --initialUrl https://example.com
qqbrowser-skill playbook_list                          # Check existing playbooks first
qqbrowser-skill browser_snapshot                       # Get elements with encoded indices
qqbrowser-skill browser_click_element --index "<index-from-snapshot>"
qqbrowser-skill browser_end_session --sessionId task-demo-001
```

---

## Commands

### Session Management

```bash
browser_start_session --sessionId <id> [--title "<title>"] [--color <color>] [--initialUrl <url>]
browser_end_session --sessionId <id>
browser_attach_session --tabIds "[<tabId1>,<tabId2>]" [--primaryTabId <id>] [--sessionId <id>] [--focus]
```

> `--initialUrl`: 启动会话时直接导航到指定 URL，省去单独调用 `browser_go_to_url` 的步骤。如果提供了该参数，会话创建后会自动打开对应页面。
>
> Isolation mode is fixed to `enforce` — `browser_start_session` does not accept an `--isolation` flag.
>
> `browser_attach_session`: 接管**已打开**的 tab 作为 AI 会话的交互对象（click / input / scroll / keys），补齐 `browser_start_session` 必然新建 tab 无法覆盖的场景。**前置步骤：标签的 `tabId` 无法凭空猜测或构造，必须先调用 `browser_tab_list` 获取当前打开标签的 `tabId`，再将返回的 `tabId` 作为 `--tabIds` 传入。** 仅需读取页面文本时改用 `browser_get_tab_content`（无需 session、无需激活、无需切换）。不传 `sessionId` 时由服务端生成并回传。

### Navigation

```bash
browser_go_to_url --url <url>
browser_go_back
browser_wait --seconds <n>              # Default 3s
```

### Snapshot & Screenshot

```bash
browser_snapshot                        # Element indices (for interaction)
browser_snapshot --markdown             # Markdown (for reading)
browser_screenshot [--full] [--annotate]
```

**`browser_snapshot --markdown`** returns clean Markdown of the page (ads/nav/scripts stripped, no element indices). Use it when AI needs to read/summarize page content in one-off tasks (Branch C). Do NOT use it inside `task_begin`/`task_end` (Branch B) or when you need structured data — use `browser_eval_content_js` instead.

### Click & Input

```bash
browser_click_element --index <id>
browser_dblclick_element --index <id>
browser_focus_element --index <id>
browser_input_text --index <id> --text "<content>"
```

### 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
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>
```

### 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
```

### Semantic Locators (Find and Act)

```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`: 1-based index for list iteration (`--nth 1` = first match). Use `by: "css"` + `--nth` for loops.

### Get Information & State

```bash

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 5 个文件，合计 67.5 KiB