前言¶
讓 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
