mcpField
Q
qqbrowser-skill

qqbrowser-skill

github.com/qqbrowserteamAgent 工作流286 次安装24 周前更新
代码仓库

关于 qqbrowser-skill

qqbrowser-skill 是面向 Agent 的 QQ Browser 命令行浏览器自动化技能，可用于导航和操作网页。它提供带索引的页面快照供交互，并支持以 Markdown 快照读取内容。

主要功能

  1. 01导航并浏览历史记录
  2. 02通过带索引的快照检查页面
  3. 03以 Markdown 格式读取页面内容
  4. 04点击、输入文本和选择选项
  5. 05滚动页面并等待加载
  6. 06保存截图和下载文件

适用场景

  1. 01填写并提交网页表单
  2. 02阅读和提取网页信息
  3. 03加载无限滚动页面的更多内容

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/qqbrowserteam/qqbrowser-skill --skill qqbrowser-skill

安装后在 Claude Code 中输入/qqbrowser-skill确认已加载。

详细介绍

qqbrowser-skill

平台支持

  • Linux x86_64：支持
  • Windows：支持
  • macOS：支持
  • 不支持其他 Linux 架构（ARM 等）。

安装

Linux：

pipx install qqbrowser-skill
qqbrowser-skill install   # Download and install QQ Browser

Windows：

pip install qqbrowser-skill
qqbrowser-skill install   # Download and install QQ Browser

macOS：

pipx install qqbrowser-skill
qqbrowser-skill install   # Download and install QQ Browser

安全性

权限

此技能需要以下权限才能正常运行：

权限范围用途
网络访问出站 HTTP/HTTPS浏览器导航、页面加载和网页交互所需
文件系统（读/写）仅临时目录保存截图（.webp）和下载文件所需
QQBrowser 二进制文件

qqbrowser-skill install 命令通过 HTTPS 从腾讯官方分发渠道下载 QQ Browser 安装包：

  • 基础 URL：https://dldir1v6.qq.com/invc/tt/QB/Public/
  • dldir1v6.qq.com 是腾讯官方软件分发 CDN。
  • 所有下载均通过 HTTPS 执行，以确保传输层安全。
文件存储
  • 截图：保存到系统临时目录（例如 Linux 上的 /tmp/），并以文件路径形式返回。
  • 下载文件：保存到系统临时目录，或通过 browser_download_file / browser_download_url 保存到用户指定的路径。
  • 此技能不会访问或修改指定目录之外的文件。

注意：

每条命令执行后都会返回当前页面的快照，其中包含元素索引。 请仅在必要时调用独立的 qqbrowser-skill browser_snapshot 命令，以避免不必要的 Token 消耗。

核心工作流

每次浏览器自动化都遵循以下模式：

  1. 导航：qqbrowser-skill browser_go_to_url --url <url>
  2. 快照：qqbrowser-skill browser_snapshot（获取带索引的元素引用）
  3. 交互：使用元素索引进行点击、填写和选择
  4. 重新获取快照：导航或 DOM 发生变化后，获取新的引用
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"

qqbrowser-skill browser_input_text --index 1 --text "[email protected]"
qqbrowser-skill browser_input_text --index 2 --text "password123"
qqbrowser-skill browser_click_element --index 3
qqbrowser-skill browser_wait --seconds 2
qqbrowser-skill browser_snapshot  # Check result

基本命令

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

# 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   # Scroll element by direction
qqbrowser-skill browser_scroll_into_view --index 5   # 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           # Get dropdown options
qqbrowser-skill browser_select_dropdown_option --index 2 --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

# Get Information
qqbrowser-skill browser_get_info --type text --index 1   # 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 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

# 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 "[email protected]"
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      # 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

# 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

# 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

常见模式

表单提交
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 "[email protected]"
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_wait --seconds 2
qqbrowser-skill browser_snapshot  # Verify result
数据提取

根据目的选择合适的 browser_snapshot 模式：

  • browser_snapshot --markdown — 适合阅读/总结页面内容（文章、文档、搜索结果、产品页面）。返回清爽的 Markdown，并去除广告、导航和脚本。节省 Token，但不包含元素索引，因此无法用于点击或输入操作。
  • browser_snapshot（默认）— 与页面交互时必需。返回带索引的元素，以供 browser_click_element、browser_input_text 等命令使用。
qqbrowser-skill browser_go_to_url --url https://example.com/products
qqbrowser-skill browser_snapshot --markdown                # Read the whole page as clean markdown

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

元素索引生命周期（重要）

页面发生变化时，元素索引会失效。以下操作后始终重新获取快照：

  • 点击会触发导航的链接或按钮
  • 提交表单
  • 动态内容加载（下拉菜单、模态框、AJAX）
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

评估报告

查看完整的技能评估报告：QQBrowserSkillReport

评论

支持 Markdown