# WebAutomator 

**Repository Path**: coderyrepos/web-automator

## Basic Information

- **Project Name**: WebAutomator 
- **Description**: 一个强大的浏览器插件与 Python 后端服务通信的框架，支持 **URL 规则自动化**和 **WebSocket 实时通信**。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-01
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 浏览器插件 + Python 后端通信框架 (v3.0)

一个强大的浏览器插件与 Python 后端服务通信的框架，支持 **URL 规则自动化**和 **WebSocket 实时通信**。

## 📋 核心特性

### v3.0 新功能 ✨
- ✅ **URL 规则自动化**: 为不同网站配置自动化操作流程
- ✅ **多种操作类型**: input、click、select、checkbox、keydown、wait、custom
- ✅ **可视化元素选择器**: 点选页面元素自动生成 CSS 选择器
- ✅ **规则管理界面**: Popup 中管理所有自动化规则
- ✅ **智能 URL 匹配**: 支持通配符模式（`*` 和 `?`）

### v2.0 功能（保留）✅
- ✅ **WebSocket 单向通信**: 浏览器插件只通过 WebSocket 接收后端消息
- ✅ **HTTP 接口**: 后端提供 HTTP 接口供外部服务发送消息到插件
- ✅ **自动插入功能**: 开启后，来自后端的消息自动插入到光标位置
- ✅ **后台运行**: Service Worker 支持后台持久化运行
- ✅ **状态持久化**: 开关状态保存在本地存储，重启不丢失
- ✅ **智能文本插入**: 支持 input、textarea、contenteditable 元素
- ✅ **自动重连**: WebSocket 断开后每 5 秒自动重连
- ✅ **悬浮按钮**: 右下角可视化开关控制
- ✅ **向后兼容**: v3.0 完全兼容 v2.0 的所有功能

## 📁 项目结构

```
browser_plugin/
├── backend/                 # Python 后端服务
│   ├── main.py             # FastAPI 主程序
│   └── requirements.txt    # Python 依赖
├── extension/              # 浏览器插件
│   ├── manifest.json       # 插件配置 (v3.0)
│   ├── background.js       # Background Service Worker
│   ├── content.js          # Content Script (注入页面)
│   ├── popup.html          # Popup 界面 (v3.0)
│   ├── popup.css           # Popup 样式 (v3.0)
│   ├── popup.js            # Popup 逻辑 (v3.0)
│   ├── rules-storage.js    # 规则存储管理 (新增)
│   ├── url-matcher.js      # URL 匹配引擎 (新增)
│   ├── action-executor.js  # 操作执行引擎 (新增)
│   └── element-picker.js   # 元素选择器 (新增)
├── test_sender.html        # 消息发送测试工具
├── http_send_test.py       # HTTP 接口测试脚本
├── test_automation_v3.py   # v3.0 自动化测试脚本 (新增)
├── start_backend.py        # Python 启动脚本
├── start.bat               # Windows 一键启动
├── USAGE_v3.0.md           # v3.0 使用指南 (新增)
├── IMPLEMENTATION_v3.0.md  # v3.0 实现报告 (新增)
├── ARCHITECTURE.md         # 架构说明文档
└── README.md               # 说明文档
```

## ✨ 功能特性

- ✅ **HTTP 通信**: GET/POST 请求,适合常规数据交互
- ✅ **WebSocket 实时通信**: 双向实时消息传递
- ✅ **自动插入开关**: 悬浮按钮控制是否将后端内容插入光标位置
- ✅ **智能文本插入**: 支持 input、textarea、contenteditable 元素
- ✅ **自动重连**: WebSocket 断开后自动重连
- ✅ **多标签页支持**: 同时管理多个浏览器标签页的连接
- ✅ **可视化界面**: Popup 弹窗提供状态监控和测试工具
- ✅ **日志系统**: 完整的通信日志记录
- ✅ **易于扩展**: 清晰的代码结构，方便添加新功能

## ✨ 架构说明

```
┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
│             │  HTTP   │              │   WS    │                 │
│  External   │ ──────> │   Python     │ ──────> │ Browser Plugin  │
│  Services   │  POST   │   Backend    │  Push   │ (Content Script)│
│             │         │  (FastAPI)   │         │                 │
└─────────────┘         └──────────────┘         └────────┬────────┘
                                                           │
                                                           │ Auto Insert
                                                           ▼
                                                    ┌─────────────────┐
                                                    │  Cursor Position│
                                                    └─────────────────┘
```

**数据流：**
1. 外部服务通过 HTTP POST 发送消息到 `/api/send`
2. Python 后端接收消息并转发给所有连接的浏览器插件
3. 浏览器插件收到消息后，如果自动插入开启，则插入到光标位置

详细架构说明请查看：[ARCHITECTURE.md](ARCHITECTURE.md)

## 📁 项目结构

### 1. 启动 Python 后端

**Windows:**
```bash
# 双击运行
start.bat

# 或者命令行运行
python start_backend.py
```

**Mac/Linux:**
```bash
# 安装依赖
pip install -r backend/requirements.txt

# 启动服务
python start_backend.py
```

后端服务将在 `http://127.0.0.1:8000` 启动

### 2. 加载浏览器插件

1. 打开 Chrome/Edge 浏览器
2. 访问 `chrome://extensions/` (Chrome) 或 `edge://extensions/` (Edge)
3. 开启右上角的 **"开发者模式"**
4. 点击 **"加载已解压的扩展程序"**
5. 选择 `extension` 文件夹
6. 插件加载成功!

### 3. 测试通信

#### v2.0 测试（基础功能）
1. 点击浏览器工具栏的插件图标,打开 Popup 界面
2. 查看后端状态和 WebSocket 连接状态
3. 在消息输入框输入内容,点击发送

#### v3.0 测试（URL 规则自动化）✨
1. 打开任意网页（如 Google: https://www.google.com）
2. 点击插件图标，点击 “📄 当前页面” 按钮
3. 输入规则名称（例如 “Google 搜索”）
4. 规则已创建！现在发送消息将自动执行操作
5. 使用测试脚本：
   ```bash
   python test_automation_v3.py
   ```

### 4. 使用自动插入功能

1. 打开任意网页(如记事本、邮件编辑器等)
2. 页面右下角会出现一个**圆形悬浮按钮**
   - 🔵 **紫色(○)**: 自动插入关闭
   - 🟢 **绿色(✓)**: 自动插入开启
3. **点击按钮**切换开关状态
4. 开启后,来自后端的内容会自动插入到当前光标位置
5. 支持以下元素:
   - 输入框 (`<input>`)
   - 文本域 (`<textarea>`)
   - 可编辑区域 (`contenteditable`)

### 5. 从外部服务发送消息到插件

**方式 1: 使用 Python 测试脚本**
```bash
# 安装依赖
pip install requests

# 发送消息
python http_send_test.py "Hello from HTTP"

# 使用模板
python http_send_test.py --template welcome

# 批量发送
python http_send_test.py --content "Test" --repeat 5 --delay 1
```

**方式 2: 使用 curl**
```bash
curl -X POST http://127.0.0.1:8000/api/send \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "type": "user_message"}'
```

**方式 3: 在代码中使用**
```python
import requests

response = requests.post("http://127.0.0.1:8000/api/send", json={
    "content": "Hello from external service",
    "type": "user_message"
})

print(response.json())
```

## 📖 使用指南

### v3.0 URL 规则自动化 ✨

**详细文档**: [USAGE_v3.0.md](USAGE_v3.0.md)

#### 快速开始

1. **为当前页面创建规则**
   ```
   1. 打开任意网页（如 Google）
   2. 点击插件图标
   3. 点击 “📄 当前页面” 按钮
   4. 输入规则名称
   5. 规则已创建！
   ```

2. **发送消息触发自动化**
   ```bash
   python test_automation_v3.py
   # 或
   python http_send_test.py "测试消息"
   ```

3. **查看规则列表**
   - 点击插件图标打开 Popup
   - 查看所有已配置的规则
   - 启用/禁用/删除规则

#### 支持的操你类型

- **input**: 在输入框中输入文本
- **click**: 点击按钮或链接
- **select**: 选择下拉框选项
- **checkbox**: 勾选/取消复选框
- **keydown**: 模拟按键（Enter、Tab 等）
- **wait**: 等待延迟
- **custom**: 执行自定义 JavaScript 代码

#### 示例：Google 搜索自动化

```json
{
  "https://www.google.com/*": {
    "name": "Google 搜索",
    "enabled": true,
    "actions": [
      {
        "type": "input",
        "selector": "textarea[name='q']",
        "useMessageContent": true,
        "delay": 0
      },
      {
        "type": "keydown",
        "selector": "textarea[name='q']",
        "key": "Enter",
        "delay": 300
      }
    ]
  }
}
```

**效果**: 收到消息后自动在 Google 搜索框输入内容并按回车搜索

---

### v2.0 WebSocket 通信（浏览器插件 → 后端）

**注意**: v2.0 版本中，浏览器插件只通过 WebSocket **接收**后端消息，不发送业务数据。

```javascript
// 检查 WebSocket 连接状态
const connected = await checkWsStatus();
console.log('WebSocket connected:', connected);

// 发送心跳（可选）
await wsSend({ type: 'ping' });
```

### HTTP 接口（外部服务 → 后端 → 插件）

后端提供 HTTP 接口供外部服务发送消息到浏览器插件：

**端点**: `POST http://127.0.0.1:8000/api/send`

**请求格式**:
```json
{
  "content": "消息内容",
  "type": "user_message",
  "data": {}
}
```

**响应格式**:
```json
{
  "status": "success",
  "message": "Message sent to 1 plugin(s)",
  "connected_clients": 1
}
```
});
```

#### 接收消息

在 `content.js` 中处理收到的 WebSocket 消息:

```javascript
function handleWebSocketMessage(data) {
  console.log('收到后端消息:', data);
  
  // 根据你的业务逻辑处理消息
  if (data.type === 'notification') {
    alert(data.message);
  }
}
```

### 在后端添加新接口

编辑 `backend/main.py`:

```python
@app.post("/api/custom")
async def custom_endpoint(data: dict):
    """自定义接口"""
    print(f"收到数据: {data}")
    
    # 处理逻辑...
    
    return {
        "status": "success",
        "result": "处理完成"
    }
```

## 🔧 API 参考

### 后端 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 健康检查 |
| `/health` | GET | 详细健康检查 |
| `/api/message` | POST | 接收消息 |
| `/api/data` | GET | 获取数据 |
| `/api/broadcast` | POST | 广播消息到所有客户端 |
| `/ws` | WebSocket | WebSocket 连接端点 |

### 前端通信 API

#### HTTP 方法

```javascript
// GET 请求
httpGet(endpoint: string): Promise<any>

// POST 请求
httpPost(endpoint: string, data: object): Promise<any>
```

#### WebSocket 方法

```javascript
// 发送消息
wsSend(message: object): Promise<boolean>

// 检查连接状态
checkWsStatus(): Promise<boolean>
```

## 🛠️ 开发建议

### 添加新功能

1. **后端功能**: 在 `backend/main.py` 中添加新的路由
2. **前端调用**: 在 `content.js` 或 `popup.js` 中调用新接口
3. **消息处理**: 根据需要添加消息类型和处理逻辑

### 调试技巧

1. **查看后端日志**: 终端会显示所有请求和 WebSocket 消息
2. **浏览器控制台**: 
   - Background: `chrome://extensions/` → 插件详情 → "Service Worker"
   - Content Script: 网页开发者工具 → Console
   - Popup: 右键插件图标 → "检查弹出内容"

### 生产环境部署

1. 修改 `backend/main.py` 中的 CORS 配置,限制允许的域名
2. 使用 HTTPS 和 WSS (WebSocket Secure)
3. 添加身份验证机制
4. 配置反向代理 (Nginx)
5. 设置环境变量管理配置

## 📝 常见问题

### Q: WebSocket 连接失败?
A: 确保后端服务正在运行,检查防火墙设置,确认端口 8000 未被占用

### Q: 插件无法访问后端?
A: 检查 `manifest.json` 中的 `host_permissions` 是否包含后端地址

### Q: 如何修改后端端口?
A: 修改 `start_backend.py` 中的 `port` 参数,同时更新 `background.js` 中的 `BACKEND_URL`

### Q: 支持哪些浏览器?
A: Chrome、Edge、Brave 等 Chromium 内核浏览器。Firefox 需要调整 manifest 格式。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request!

## 📄 许可证

MIT License

## 📮 联系方式

如有问题,请提交 GitHub Issue