前言¶
让 Agent 打开网页、填表、点按钮，常见做法是接 Playwright 或 Selenium，再由模型拼脚本。链路长、环境杂，还要自己处理会话隔离和「这次操作下次还能用」的沉淀。QQBrowserUse 把能力收成一套 qqbrowser-skill CLI，并配套 SkillHub 上的 Agent Skill，让 Cursor、Claude Code 等客户端在识别到真实浏览器任务时，按固定命令与会话模型执行，而不是只回答 HTML/CSS 理论题。
这是什么¶
QQBrowserUse（坐标 @tencent-adm/qqbrowser-skill，当前版本 1.0.16）是 Browser automation CLI for AI agents：用命令驱动 QQ 浏览器完成打开页面、交互、截图、下载、读页面状态、抽结构化数据，以及录制任务与回放 Playbook。发布方为 腾讯 QQ 浏览器团队，在 SkillHub 分类为 ai-agent，标签 requires_api_key=false（安装 Skill 本身不要求额外 API Key）。上游仓库见 clawhub.ai/qqbrowserteam/qqbrowser-skill。
每个任务包在独立的 Chrome Tab Group 里；支持现场自动化，也支持把流程保存为可复用的 Playbook 再 browser_replay。
核心功能¶
以下能力均来自官方 Skill 说明与上游文档，按用途归纳。
何时启用 Skill（Agent 侧）
- 用户要打开、导航或与网站交互。
- 需要填表、点按钮、截图、下载文件或查看页面状态。
- 要从网页提取结构化数据。
- 用户明确要录制、保存或复用浏览器任务（如「保存为脚本」「录一下」「下次还要用」）。
- 用户要运行已有 Playbook。
不应使用：仅讨论 HTML、CSS、JavaScript 且没有真实浏览器操作需求时。
CLI 能力概览
| 类别 | 代表命令 | 作用 |
|---|---|---|
| 会话 | browser_start_session、browser_end_session、browser_attach_session |
新建隔离会话或接管已有标签 |
| 导航与等待 | browser_go_to_url、browser_go_back、browser_wait |
打开 URL、后退、等待 |
| 页面感知 | browser_snapshot、browser_snapshot --markdown、browser_screenshot |
带元素索引的快照、可读 Markdown、截图 |
| 交互 | browser_click_element、browser_input_text、browser_find_and_act 等 |
点击、输入、语义定位 |
| 标签 | browser_tab_list、browser_get_tab_content、browser_tab_switch 等 |
列标签、读非激活页内容、切换 |
| 数据与脚本 | browser_eval_content_js、browser_get_info |
在页面内执行 JS、取文本/属性等 |
| 录制与回放 | task_begin / task_end、playbook_list、browser_replay |
在用户明确要求时录制；列出并回放 Playbook |
隔离模式固定为 enforce；browser_start_session 可用 --initialUrl 在建会话时直接打开页面。已打开的标签需先 browser_tab_list 取得 tabId，再 browser_attach_session 或 browser_get_tab_content（只读内容可不建会话）。
安装与启用¶
分两层：Agent Skill（教模型何时、如何用 CLI）和 qqbrowser-skill 可执行环境（实际驱动浏览器）。
1. 安装 SkillHub CLI（若尚未安装）¶
command -v skillhub && skillhub --version
未安装时可执行完整安装（CLI + 默认 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
仅 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2. 安装 QQBrowserUse Skill¶
安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。
skillhub install @tencent-adm/qqbrowser-skill --dir <skills 目录>
常见路径（以 SkillHub 安装文档为准）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下.agents/skills/
也可让 AI 按 skillhub.cn/install/skillhub.md 安装 @tencent-adm/qqbrowser-skill。
3. 安装 qqbrowser-skill 与 QQ 浏览器¶
上游要求平台：Linux x86_64、Windows、macOS；其他 Linux 架构（如 ARM）不在支持范围内。
# Linux / macOS
pipx install qqbrowser-skill
qqbrowser-skill install # 下载并安装 QQ 浏览器
# Windows
pip install qqbrowser-skill
qqbrowser-skill install
OpenClaw 生态也可通过 openclaw skills install @qqbrowserteam/qqbrowser-skill 安装同名 Skill（坐标与 SkillHub 企业镜像不同，以你使用的客户端为准）。
典型用法¶
下面示例来自上游 Quick Start，可在终端直接复现流程骨架。
qqbrowser-skill browser_start_session --sessionId task-demo-001 --initialUrl https://example.com
qqbrowser-skill playbook_list
qqbrowser-skill browser_snapshot
qqbrowser-skill browser_click_element --index "<index-from-snapshot>"
qqbrowser-skill browser_end_session --sessionId task-demo-001
需要读页面、不做点击时，可用 Markdown 快照（无元素索引，适合一次性阅读）：
qqbrowser-skill browser_snapshot --markdown
用户明确要求「录一下」「保存为脚本」时，再进入录制；task_end 之后需按 Skill 内 references/playbook.md 把录制整理为可回放的 Playbook JSON，而不是直接把原始录制当脚本跑。
回放已有 Playbook：
qqbrowser-skill playbook_list
qqbrowser-skill browser_replay --script <path> --variables '{"key":"value"}'
官方说明：browser_replay 最长可达约 10 分钟，应等待完成，不宜中途打断或改用纯手工步骤。
适用场景与注意¶
适合谁：已经在用 Cursor、Claude Code、Codex 或 OpenClaw 类 Agent，且任务里经常出现「帮我在网站上做完一串操作」或「下次用同一套流程」的团队或个人。
限制与坑
- 依赖 QQ 浏览器与
qqbrowser-skill本机环境；ARM Linux 等未列出的架构不要强行部署。 tabId、groupId不能猜测，必须先browser_tab_list/browser_tabgroup_list。- AI 会话对应的 Tab Group 在任务进行中受保护，勿用标签组变更命令去动活跃会话；结束用
browser_end_session。 - 纯前端知识问答、无浏览器操作需求时，不应加载本 Skill，避免模型误开浏览器。
SkillHub 页面当前统计（以抓取资料为准）：评分 100000，下载 13384，安装 329；企业源 enterprise。
结尾¶
QQBrowserUse 把「开页、交互、读状态、抽数据、录制与 Playbook 回放」统一成 Agent 可调用的 CLI，并由腾讯 QQ 浏览器团队在 SkillHub 维护 Skill 坐标与版本。若你的 Agent 需要可复现的浏览器任务而不是一次性脚本拼装，可从官方 Skill 页安装并配对 qqbrowser-skill 使用。
- SkillHub：https://www.skillhub.cn/skills/tencent-adm/qqbrowser-skill
- API 入口：https://api.skillhub.cn/tencent-adm/qqbrowser-skill
