zhiyun-autoweb/README.md

# Selenium 模块化项目架构

这是一个使用 Python 和 Selenium 的模块化项目架构，支持通过命令行参数调用不同的业务逻辑，并支持两种方式启动和控制 Google Chrome 浏览器。

## 操作指南

详细的操作步骤请参考 **[项目操作手册](operate.md)**。

## 文件结构

```
.
├── browser_manager.py          # 管理浏览器启动和 WebDriver 实例
├── config.py                   # 存放项目配置，如调试端口和用户目录
├── main.py                     # 项目主入口，负责解析参数和调用模块
├── requirements.txt            # 项目依赖库
├── modules/                    # 存放所有独立的业务逻辑模块
│   └── or_address_handler.py   # 处理 o-address.csv 的业务模块
├── data/                       # 存放数据文件
│   └── o-address.csv           # 示例数据文件
└── chrome_user_data/           # (自动生成) Chrome 用户数据目录
```

## 安装依赖

在开始之前，请确保你已经安装了 Python。然后通过以下命令安装所需的库：

```bash
pip install -r requirements.txt
```

## 如何运行

现在，所有操作都通过命令行来执行，使用 `main.py` 作为入口。

### 基本命令格式

```bash
python main.py --module <模块名称> [--debug]
```

-   `--module <模块名称>`: **必需参数**。指定要运行的业务模块。当前可用的模块是 `or-address`。
-   `--debug`: **可选参数**。如果带上这个参数，脚本会尝试连接到一个已存在的 Chrome 浏览器，而不是启动一个新浏览器。

### 示例 1: 启动新浏览器执行任务

这是最常见的用法。下面的命令会启动一个全新的浏览器，并执行 `or-address` 模块定义的任务。

```bash
python main.py --module or-address
```

### 示例 2: 连接到现有浏览器执行任务

如果你需要保持登录状态或利用已打开的浏览器会话，可以使用 `--debug` 模式。

1.  **手动启动 Chrome 浏览器**：
    打开你的命令行工具 (CMD 或 PowerShell)，然后运行以下命令。这会启动一个特殊的 Chrome 实例，并开启一个调试端口。

    ```bash
    chrome.exe --remote-debugging-port=9222 --user-data-dir="d:/project/zhiyun-scripy/chrome_user_data"
    ```
    > **注意**: 
    > - `--remote-debugging-port` 的值必须与 `config.py` 中的 `CHROME_DEBUGGER_PORT` 一致。
    > - `--user-data-dir` 指定了一个用户配置文件的目录，请确保路径是绝对路径。
    > - 如果 `chrome.exe` 不在你的系统 PATH 中，你可能需要提供它的完整路径。

2.  **运行脚本并连接**：
    在另一个终端中，运行以下命令。`--debug` 参数会告诉脚本去连接你刚才手动打开的浏览器。

    ```bash
    python main.py --module or-address --debug
    ```

## 如何添加新的业务模块？

1.  在 `modules/` 目录下创建一个新的 Python 文件，例如 `new_task_handler.py`。
2.  在这个新文件中，定义一个函数，该函数接收 `driver` 作为参数。例如：

    ```python
    # modules/new_task_handler.py
    def process_new_task(driver):
        print("正在执行新任务...")
        driver.get("https://www.example.com")
        # ... 在这里编写你的新业务逻辑 ...
    ```

3.  打开 `main.py` 文件，将你的新模块和处理函数添加到 `MODULES` 字典中：

    ```python
    # main.py
    from modules.or_address_handler import process_addresses
    from modules.new_task_handler import process_new_task # 导入新函数

    MODULES = {
        "or-address": process_addresses,
        "new-task": process_new_task, # 添加新模块的映射
    }
    ```

4.  现在你就可以通过命令行调用你的新模块了：

    ```bash
    python main.py --module new-task
    ```

## 其他说明

-   **`browser_manager.py`**: 一般情况下你不需要修改这个文件。
-   **`config.py`**: 如果你需要更改调试端口或用户数据目录的名称，可以修改这个文件。
-   **`data/`**: 所有需要被脚本读取的数据文件（如 CSV, Excel, TXT）都建议放在这个目录下。