QQ Browser Skill

Browser automation CLI for AI agents — 通过 WebSocket 控制 QQ 浏览器，实现网页自动化操作。

安装

从 PyPI 安装（推荐）

pip install qqbrowser-skill

安装 QQ 浏览器

安装 Python 包后，还需安装 QQ 浏览器本体：

qqbrowser-skill install          # 安装 QQ 浏览器
qqbrowser-skill install --force  # 强制重新安装

快速开始

1. 启动守护进程

执行任何浏览器操作前，必须先启动守护进程服务：

qqbrowser-skill serve --daemon   # 后台模式启动
qqbrowser-skill status           # 检查守护进程状态
qqbrowser-skill stop             # 停止守护进程

2. 基本使用流程

# 导航到目标页面
qqbrowser-skill browser_go_to_url --url https://example.com

# 获取页面快照（包含元素索引）
qqbrowser-skill browser_snapshot

# 使用元素索引进行交互
qqbrowser-skill browser_click_element --index 1
qqbrowser-skill browser_input_text --index 2 --text "hello"

# 截图
qqbrowser-skill browser_screenshot

3. 查看所有可用命令

qqbrowser-skill list                     # 列出所有可用技能
qqbrowser-skill <skill_name> --help      # 查看特定技能的帮助

开发指南

环境准备

本项目使用 uv 作为包管理和构建工具，使用 hatchling 作为构建后端。

# 安装 uv（如未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone <repo-url>
cd X5UseLinuxMcp

# 安装依赖
uv sync

项目结构

X5UseLinuxMcp/
├── pyproject.toml          # 项目配置与依赖
├── publish.sh              # 构建 & 发布脚本
├── SKILL.md                # 技能使用说明（供 AI Agent 参考）
├── uv.lock                 # 锁定的依赖版本
├── src/x5use/
│   ├── __init__.py
│   ├── server.py           # CLI 入口 & 主服务
│   ├── daemon_server.py    # 守护进程服务
│   ├── skill_registry.py   # 技能注册表
│   ├── websocket_manager.py# WebSocket 管理
│   ├── rpc_client.py       # RPC 客户端
│   ├── installer.py        # 安装器入口
│   ├── installer_linux.py  # Linux 安装逻辑
│   ├── installer_mac.py    # macOS 安装逻辑
│   ├── installer_win.py    # Windows 安装逻辑
│   ├── installer_common.py # 安装通用逻辑
│   ├── upgrader.py         # 升级模块
│   ├── constants.py        # 常量定义
│   ├── debug_collector.py  # 调试信息收集
│   ├── vnc_proxy.py        # VNC 代理
│   └── vnc_util.py         # VNC 工具
└── build_whl/              # 预构建的 whl 包

本地开发运行

# 使用 uv 直接运行
uv run qqbrowser-skill <command>

# 或者先安装到虚拟环境再运行
uv pip install -e .
qqbrowser-skill <command>

构建

使用 uv build 构建 sdist 和 wheel 包：

uv build

构建产物输出到 dist/ 目录。

发布到 PyPI

项目提供了 publish.sh 脚本来自动化构建和上传流程。

前置条件

1. 安装 uv 和 twine：

   pip install twine
   # 或
   uv pip install twine
   

2. 配置 PyPI API Token（任选其一）：

   • 设置环境变量：export TWINE_PASSWORD="pypi-你的Token"
   • 配置 ~/.pypirc 文件
   • 运行时传入：TWINE_PASSWORD="pypi-xxx" bash publish.sh

发布命令

# 发布到正式 PyPI
bash publish.sh

# 发布到 TestPyPI（用于测试）
bash publish.sh --test

发布脚本会自动执行以下步骤：

1. 清理旧的构建产物
2. 执行 uv build 构建包
3. 使用 twine check 检查包合法性
4. 使用 twine upload 上传到 PyPI

版本管理

修改 pyproject.toml 中的 version 字段来更新版本号：

[project]
version = "1.0.10"

升级

qqbrowser-skill upgrade                # 检查并升级 qqbrowser-skill 和 QQ 浏览器
qqbrowser-skill upgrade --check-only   # 仅检查更新，不执行升级
qqbrowser-skill upgrade --skip-browser # 仅升级 Python 包，跳过浏览器更新

调试

qqbrowser-skill debug                          # 收集调试信息和日志
qqbrowser-skill debug --output /tmp/debug.tar.gz  # 指定输出路径

依赖

• Python >= 3.10
• websockets >= 12.0