# AI Browser Automation

通用浏览器自动化框架，支持反检测、智能元素定位、工作流编排，通过 MCP 协议对外暴露单一工具接口。

## 核心特性

- **反检测浏览器** — CloakBrowser / rebrowser-playwright / Playwright 三级降级，自动选择最佳后端
- **三级元素查找** — A(AX树相似度匹配) → B(Shadow-DOM TreeWalker穿透) → C(多模态VLM视觉定位)
- **工作流编排** — 一次调用执行完整动作序列，内置重试与熔断机制
- **MCP 协议** — 对外仅暴露 `run_workflow` 单一工具，Host 侧零调度逻辑
- **会话持久化** — 浏览器降级时自动保留登录状态（cookies + localStorage）

## 架构

```
┌─────────────────────────────────────────────────────────┐
│  Host (OpenCode / Claude-Code / 任意 MCP Client)        │
│  仅负责生成 action_list，调用一次 run_workflow            │
└───────────────────────┬─────────────────────────────────┘
                        │ MCP 协议（单次调用）
┌───────────────────────▼─────────────────────────────────┐
│  MCP Server (mcp_server.py)                             │
│  ┌─────────────────────────────────────────────────────┐│
│  │  WorkflowRunner (workflow_runner.py)                ││
│  │                                                     ││
│  │  for action in action_list:                         ││
│  │      A: AX树匹配 (similarity.py)                    ││
│  │         ↓ 置信度 < 0.7 或失败                        ││
│  │      B: Shadow-DOM穿透 (_browser_utils.py)          ││
│  │         ↓ 找不到或失败                               ││
│  │      C: VLM视觉定位 (vlm_client.py) [可选]          ││
│  │         ↓ 全部失败 → 重试 → 熔断                     ││
│  └─────────────────────────────────────────────────────┘│
│                                                         │
│  ┌─────────────────────────────────────────────────────┐│
│  │  Browser Manager (browser_manager.py)               ││
│  │  CloakBrowser → rebrowser → Playwright 三级降级     ││
│  │  反检测指纹 / 会话持久化 / 单例浏览器管理            ││
│  └─────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘
```

## 快速开始

### 安装

```bash
# 克隆项目
git clone https://github.com/your-username/ai-browser-automation.git
cd ai-browser-automation

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 安装浏览器（必须）
playwright install chromium
```

### 依赖说明

| 依赖 | 用途 | 必须 |
|------|------|------|
| `playwright` | 浏览器自动化核心 | 是 |
| `cloakbrowser` | 源码级反检测（推荐） | 否 |
| `rebrowser-playwright` | 反检测 Playwright 分支 | 否 |
| `mcp` | MCP 协议支持 | 是 |
| `crewai` | Agent 框架（可选） | 否 |
| `openai` | VLM 多模态兜底（C方案） | 否 |

浏览器后端按优先级自动选择：CloakBrowser > rebrowser-playwright > Playwright。至少需要安装其中一个。

### 直接测试

```bash
python test_workflow.py
```

测试脚本会启动可见浏览器，依次执行：导航 → 输入 → 点击，验证工作流引擎和熔断机制。

## MCP 集成

### 配置

在 MCP 客户端（OpenCode / Claude Desktop）中添加：

```json
{
  "mcpServers": {
    "browser-automation": {
      "command": "python",
      "args": ["/path/to/ai-browser-automation/mcp_server.py"]
    }
  }
}
```

### 调用示例

```json
{
  "action_list": [
    {"action": "goto", "target_url": "https://www.baidu.com"},
    {"action": "type", "element_label": "搜索框", "text": "hello world"},
    {"action": "click", "element_label": "百度一下"}
  ],
  "single_step_max_retry": 2,
  "enable_vlm_fallback": false
}
```

### 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `action_list` | `list[dict]` | 必填 | 动作清单数组 |
| `single_step_max_retry` | `int` | `2` | 单步最大重试次数，耗尽后熔断 |
| `enable_vlm_fallback` | `bool` | `false` | 是否启用 VLM 视觉兜底（C方案） |

### 动作类型

| action | 必填参数 | 可选参数 | 说明 |
|--------|----------|----------|------|
| `goto` | `target_url` | — | 导航到指定 URL |
| `click` | `element_label` | — | 查找并点击元素 |
| `type` | `element_label`, `text` | — | 查找输入框并填写文本 |
| `wait` | — | `wait_ms` (默认 1000) | 等待指定毫秒 |

### 返回值

```json
{
  "success": true,
  "total_steps": 3,
  "executed_steps": 3,
  "failed_step": null,
  "error_message": "",
  "step_results": [
    {"step_index": 0, "action": {"action": "goto", ...}, "success": true, "method": "direct", "confidence": 1.0},
    {"step_index": 1, "action": {"action": "type", ...}, "success": true, "method": "aria", "confidence": 0.0},
    {"step_index": 2, "action": {"action": "click", ...}, "success": true, "method": "aria", "confidence": 0.95}
  ]
}
```

## 元素查找策略

### A 方案：AX树本地匹配

通过 JS 注入提取页面所有可交互元素，使用 `difflib.SequenceMatcher` 计算目标文本与元素的文本相似度。置信度 ≥ 0.7 时直接通过元素索引点击。

- 速度最快，无外部依赖
- 适用于标准 HTML 页面

### B 方案：Shadow-DOM TreeWalker 穿透

递归遍历所有 DOM 节点及 Shadow DOM 子树，搜索目标文本。找到后向上查找最近的可交互父元素，检查可见性、视口位置后点击。

- 支持 Web Components / Shadow DOM
- 包含可见性、视口内、可交互父元素三重验证

### C 方案：多模态 VLM 视觉定位（可选）

截取页面截图，发送给远端多模态大模型（如 Qwen2.5-VL），获取目标元素归一化坐标，鼠标点击。

需配置环境变量：

```bash
export VLM_API_BASE="http://localhost:11434/v1"
export VLM_API_KEY="ollama"
export VLM_MODEL="qwen2.5-vl:7b"
```

## CrewAI 集成（可选）

项目同时支持 CrewAI Agent 调度模式，提供 6 个原子工具：

```python
from ecommerce_api import run_browser_task, run_ecommerce_search, run_form_fill

# 自然语言的任务
result = run_browser_task("在百度搜索 Python 教程", url="https://www.baidu.com")

# 电商搜索快捷接口
result = run_ecommerce_search("iPhone 16", platform_url="https://www.taobao.com")

# 表单自动填写
result = run_form_fill("https://example.com/form", {"name": "张三", "phone": "13800138000"})
```

## 项目结构

```
ai-browser-automation/
├── tools/
│   ├── browser_manager.py        # 隐身浏览器管理（三级降级 + 会话持久化）
│   ├── browser_navigate_tool.py  # 导航工具
│   ├── browser_scan_tool.py      # ARIA 扫描工具
│   ├── browser_click_tool.py     # 点击工具
│   ├── browser_type_tool.py      # 输入工具
│   ├── browser_screenshot_tool.py# 截图工具
│   ├── browser_extract_tool.py   # 数据提取工具
│   ├── similarity.py             # 文本相似度计算
│   ├── _browser_utils.py         # 底层原子函数（扫描/点击/Shadow DOM/VLM）
│   ├── vlm_client.py             # VLM 多模态视觉定位客户端
│   ├── workflow_runner.py        # 工作流编排引擎
│   └── __init__.py
├── mcp_server.py                 # MCP 协议层（run_workflow 工具）
├── ecommerce_api.py              # CrewAI Agent 调度入口
├── manual_test.py                # 交互式测试
├── test_workflow.py              # 工作流引擎测试
├── requirements.txt
├── .gitignore
├── LICENSE
└── README.md
```

## 设计原则

1. **单一工具暴露** — MCP 层只注册 `run_workflow`，Host 侧零调度逻辑
2. **无 LLM 依赖** — 元素匹配、重试熔断全部是普通业务代码，不调用大模型
3. **增量不改原有代码** — 6 个原子工具完全不动，新功能全部通过新增文件实现
4. **降级而非失败** — 浏览器后端三级降级、元素查找三级降级、单步重试后熔断

## License

MIT