┌─────────────────────────────────────────────────────────┐
│  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 三级降级     ││
│  │  反检测指纹 / 会话持久化 / 单例浏览器管理            ││
│  └─────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘

# 克隆项目
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

python test_workflow.py

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

{
  "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
}

{
  "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}
  ]
}

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

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