# QQ Browser Skill

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


## 安装

### 从 PyPI 安装（推荐）

```bash
pip install qqbrowser-skill
```

### 安装 QQ 浏览器

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

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

## 快速开始

### 1. 启动守护进程

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

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

### 2. 基本使用流程

```bash
# 导航到目标页面
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. 查看所有可用命令

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

## 开发指南

### 环境准备

本项目使用 [uv](https://docs.astral.sh/uv/) 作为包管理和构建工具，使用 [hatchling](https://hatch.pypa.io/) 作为构建后端。

```bash
# 安装 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 包
```

### 本地开发运行

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

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

## 构建

使用 `uv build` 构建 sdist 和 wheel 包：

```bash
uv build
```

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

## 发布到 PyPI

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

### 前置条件

1. 安装 [uv](https://docs.astral.sh/uv/) 和 [twine](https://twine.readthedocs.io/)：
   ```bash
   pip install twine
   # 或
   uv pip install twine
   ```

2. 配置 PyPI API Token（任选其一）：
   - 设置环境变量：`export TWINE_PASSWORD="pypi-你的Token"`
   - 配置 `~/.pypirc` 文件
   - 运行时传入：`TWINE_PASSWORD="pypi-xxx" bash publish.sh`

### 发布命令

```bash
# 发布到正式 PyPI
bash publish.sh

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

发布脚本会自动执行以下步骤：
1. 清理旧的构建产物
2. 执行 `uv build` 构建包
3. 使用 `twine check` 检查包合法性
4. 使用 `twine upload` 上传到 PyPI

### 版本管理

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

```toml
[project]
version = "1.0.10"
```

## 升级

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

## 调试

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

## 依赖

- Python >= 3.10
- [websockets](https://websockets.readthedocs.io/) >= 12.0