核心用法
qqbrowser-skill 是一款面向 AI Agent 的浏览器自动化命令行工具，基于 QQ 浏览器内核实现，支持跨平台（Linux x86_64、Windows、macOS）。核心工作流遵循「导航 → 快照 → 交互 → 重载快照」的循环模式：通过 browser_go_to_url 打开目标页面，调用 browser_snapshot 获取带索引的元素列表，再使用元素索引执行点击、输入、选择等操作，页面变化后必须重新快照以刷新索引。
工具提供丰富的原子能力：
- 导航控制：前进/后退、等待加载、多标签管理
- 元素交互：点击（单/双击）、文本输入、下拉选择、复选框操作、键盘事件模拟
- 信息提取：获取文本/URL/标题/HTML/属性/样式、页面转 Markdown、全页截图
- 智能定位：支持
browser_find_and_act通过 role/text/label/placeholder/testid 语义定位元素 - 文件下载：点击下载或直链下载，默认保存至系统临时目录
显著优点
1. 官方背书：由腾讯 QQ 浏览器团队维护，二进制文件通过官方 CDN（dldir1v6.qq.com）HTTPS 分发，来源可信
2. 跨平台一致：统一 CLI 接口覆盖主流桌面系统，降低多环境适配成本
3. 语义化操作：find_and_act 系列命令减少对 DOM 结构的依赖，提升脚本健壮性
4. 快照机制：带索引的快照输出便于 AI 理解页面状态，降低多轮交互的 token 消耗（文档特别提醒避免频繁调用 browser_snapshot）
潜在局限
- 架构限制：Linux 仅支持 x86_64，ARM 等架构不可用
- 元素索引易失：页面任何变动（导航、AJAX、弹窗）均使旧索引失效，必须重新快照，在复杂动态页面中可能增加交互步数
- 权限边界：需网络访问和临时目录写权限，虽文档声明不越界，但 Agent 仍可能意外访问敏感站点或下载恶意文件
- 生态封闭：绑定 QQ 浏览器内核，无法切换至 Chromium/Firefox 等其他引擎，调试和定制自由度受限
适合人群
- 需为 AI Agent 快速搭建浏览器自动化能力的开发者
- 已使用 QQ 浏览器生态、希望保持一致内核行为的团队
- 对来源可信度要求高、倾向官方维护工具的企业场景
常规风险
- 供应链风险：二进制自动下载，需信任腾讯 CDN 及 PyPI 包完整性
- 数据泄露：Agent 操作过程中可能接触用户敏感页面，截图/下载文件留存临时目录需及时清理
- 反爬对抗：部分网站对自动化浏览器有检测机制，可能触发验证码或封禁
- 误操作风险：语义定位（如
by text）可能匹配非预期元素，关键操作建议结合索引确认