# Coordinate 签证预约自动化系统 Coordinate 是一个高并发、插件化的多国签证预约与监控自动化系统。支持通过声明式状态机与拟人化浏览器自动化(DrissionPage / curl_cffi / 大模型视觉识别 / CapSolver 等)完成反爬穿透、会话建立、号源实时监控与自动占位预约。 --- ## 目录 - [插件测试工具 (PluginTester) 全指南](#插件测试工具-plugintester-全指南) - [7 步标准化测试流水线](#7-步标准化测试流水线) - [CLI 命令行常用方法与示例](#cli-命令行常用方法与示例) - [命令行全量参数速查表](#命令行全量参数速查表) - [测试配置文件说明 (`config/test_conf.json`)](#测试配置文件说明-configtest_confjson) - [诊断报告解读与排错](#诊断报告解读与排错) - [France-Visas (法签申请表) 账号全自动注册、填表与 FRA1 提取](#france-visas-法签申请表-账号全自动注册填表与-fra1-提取) - [核心自动化流水线](#1-核心自动化流水线) - [命令行全量参数速查表](#2-命令行全量参数速查表) - [典型场景使用示例 (北京/爱尔兰都柏林等)](#3-典型场景使用示例) - [系统架构与模块组成](#系统架构与模块组成) - [已支持插件列表](#已支持插件列表) - [通用大模型验证码识别器 (CaptchaBreaker)](#通用大模型验证码识别器-captchabreaker) - [项目目录结构](#项目目录结构) - [环境搭建与快速开始](#环境搭建与快速开始) - [单元测试](#单元测试) --- ## 插件测试工具 (PluginTester) 全指南 Coordinate 提供了全功能的插件测试脚手架 [`tools/plugin_tester.py`](file:///Users/hujiarui/workspace/coordinate/tools/plugin_tester.py),用于在不启动分布式任务调度的情况下,对任意签证插件进行孤立、可复现的完整生命周期测试、反爬连通性验证与号源查询调试。 ### 7 步标准化测试流水线 `PluginTester` 按照以下生命周期顺序执行契约测试: ```mermaid graph LR Step1[1. test_init
插件实例化与配置注入] --> Step2[2. test_create_session
反爬穿透与会话建立] Step2 --> Step3[3. test_health_check
会话心跳与保活验证] Step3 --> Step4[4. test_status
运行时指标与健康度] Step4 --> Step5[5. test_query
可预约时段与日历抓取] Step5 --> Step6[6. test_book
锁定号源与提交 - 可选] Step6 --> Step7[7. test_cleanup
浏览器销毁与临时文件清理] ``` 1. **`test_init`**: 通过插件工厂动态加载目标插件,验证其继承自 `IPlugin`,并注入 `PluginConfig` 与日志记录器。 2. **`test_create_session`**: 启动指纹隔离的 Chromium 实例,通过反爬盾挑战(如 Cloudflare Turnstile、AWS WAF、KBA 密保回答),完成登录获取会话凭据(Cookie / JWT / SessionId)。 3. **`test_health_check`**: 触发心跳检查(`health_check()`),验证会话存活状态与页面响应能力。 4. **`test_status`**: 抓取插件的运行时指标对象 `PluginStatus`(含会话存活时长、关联代理、账号标识、URL 状态等)。 5. **`test_query`**: 导航至号源日历页面,结合 OCR/大模型识别输入验证码,查询预约号源并输出规范化 `QueryResult`(`AvailabilityStatus`、最早已开放日期 `earliest_date` 等)。 6. **`test_book`** *(可选)*: 当附加 `--book` 参数时执行,根据 `user_inputs` 填报申请人资料、上传护照文档、选择时间槽并锁定预约。 7. **`test_cleanup`**: 验证 `cleanup()` 函数能够安全退出浏览器进程,并彻底清除隔离工作区数据(`data/temp_browser_data/`)。 --- ### CLI 命令行常用方法与示例 #### 1. 运行单个插件的查询流水线 (推荐最常用) ```bash # 测试波兰 e-konsulat 插件 python3 tools/plugin_tester.py --plugin pol_plugin # 测试 VFS 全球签证插件 python3 tools/plugin_tester.py --plugin vfs_plugin # 也支持直接使用位置参数 python3 tools/plugin_tester.py tls_plugin ``` #### 2. 发生错误时保留浏览器现场 (`--keep-on-error` 调试利器) 如果插件在挑战反爬、找选择器或解析日历时发生异常,默认会自动销毁浏览器。添加 `--keep-on-error` 参数后,**测试器将保留浏览器窗口和 DevTools 现场不退出**,方便人工在页面上审查元素、排查原因: ```bash python3 tools/plugin_tester.py --plugin pol_plugin --keep-on-error python3 tools/plugin_tester.py --plugin vfs_plugin --keep-on-error ``` #### 3. 测试结束保留浏览器窗口 (`--no-cleanup`) 用于在测试完全成功后仍想人工查看最终页面状态的场景: ```bash python3 tools/plugin_tester.py --plugin vfs_plugin --no-cleanup ``` #### 4. 包含预约提交流程测试 (`--book`) 默认测试只会执行到 `query` 查询步骤,若需验证选时间与提交申请逻辑,追加 `--book`: ```bash python3 tools/plugin_tester.py --plugin vfs_plugin --book ``` #### 5. 快速检查插件工厂配置与实例化 (`--only-init`) 毫秒级校验插件能否被工厂识别并成功装载配置,不启动真实浏览器: ```bash # 检查单个插件 python3 tools/plugin_tester.py --plugin vfs_plugin --only-init # 检查所有插件 python3 tools/plugin_tester.py --plugin all --only-init ``` #### 6. 命令行即时覆盖账号密码与代理 无需修改配置文件,直接通过命令行临时传入特定的账号或独立代理: ```bash python3 tools/plugin_tester.py --plugin pol_plugin \ -u "myuser@example.com" \ -pwd "MySecretPass123" \ --proxy "http://127.0.0.1:7890" ``` #### 7. 指定特定配置文件 默认自动加载 `config/test_conf.json`,可通过 `-c` 指定自定义配置文件: ```bash python3 tools/plugin_tester.py --plugin vfs_plugin -c "config/staging_conf.json" ``` #### 8. 全量批量回归测试 ```bash python3 tools/plugin_tester.py --plugin all ``` --- ### 命令行全量参数速查表 | 参数 / 简写 | 类型 | 默认值 | 详细说明 | | :--- | :--- | :--- | :--- | | `plugin_pos` / `--plugin` / `-p` | string | `None` | 目标插件标识(如 `vfs_plugin`、`pol_plugin`、`tls_plugin` 或 `'all'`) | | `--keep-on-error` | flag | `False` | **出错时保留浏览器不退出**,极大便利人工复现与审查页面错误 | | `--no-cleanup` | flag | `False` | 测试结束后不自动执行 `cleanup()`,保持浏览器打开 | | `--book` | flag | `False` | 是否执行预约提交流程(`test_book`),默认仅执行到查询步骤 | | `--only-init` | flag | `False` | 仅验证插件类装载与配置注入后立即退出 | | `--config` / `-c` | string | `config/test_conf.json` | 指定自定义 JSON 测试配置文件路径 | | `--group` / `-g` | string | `None` | 覆盖插件分组标识 `group_id` | | `--user` / `-u` | string | `None` | 覆盖测试账号用户名 / 邮箱 | | `--password` / `-pwd` | string | `None` | 覆盖测试账号密码 | | `--proxy` | string | `None` | 覆盖代理网络(格式如 `http://user:pass@ip:port`) | --- ### 测试配置文件说明 (`config/test_conf.json`) 配置文件集中管理各签证中心的站点参数、测试账号及申请人信息: ```json { "default": { "account": { "username": "tester@example.com", "password": "SamplePassword123!" }, "proxy": { "proto": "http", "ip": "127.0.0.1", "port": 7890, "username": "", "password": "" }, "session_max_life": 3600, "debug": true }, "plugins": { "vfs_plugin": { "group_id": "vfs.cn.at", "account": { "username": "cn_at_wfvl5y@text.skin", "password": "SamplePassword$" }, "appointment_types": [ { "city": "Beijing", "country": "Austria", "visa_type": "Tourist", "routing_key": "slot.bjs.at.tourist", "weight": 10 } ], "free_config": { "language": "en", "country_code": "chn", "mission_code": "aut", "apt_configs": { "slot.bjs.at.tourist": { "vac_code": "Bei", "category_code": "VTC", "subcategory_code": "TR" } } }, "user_inputs": { "first_name": "San", "last_name": "Zhang", "email": "applicant@example.com", "expected_start_date": "2026-09-01", "expected_end_date": "2026-11-30" } }, "pol_plugin": { "group_id": "pol.dublin", "free_config": { "query_url": "https://secure.e-konsulat.gov.pl/placowki/151/wiza-schengen/wizyty/weryfikacja-obrazkowa", "service_type": "Wiza Schengen", "location": "Dublin" } } } } ``` --- ### 诊断报告解读与排错 每次测试结束时,控制台将输出格式化的执行时间与状态诊断表格: ```text ================================================================= 📊 [Test Report Summary] Plugin: pol_plugin (Group: pol.dublin) ================================================================= Step Name | Status | Duration (s) | Details ----------------------------------------------------------------- test_init | ✅ PASS | 0.49 | {'name': 'pol_plugin', 'version': '1.0.0'} test_create_session | ✅ PASS | 7.09 | test_health_check | ✅ PASS | 0.00 | True test_status | ✅ PASS | 0.00 | PluginStatus(instance_id='a7418055', is_healthy=True...) test_query | ✅ PASS | 26.55 | success=False, status=AvailabilityStatus.NoneAvailable test_status | ✅ PASS | 0.00 | PluginStatus(instance_id='a7418055', is_healthy=True...) test_cleanup | ✅ PASS | 1.29 | ----------------------------------------------------------------- Overall Result: 🎉 ALL TESTS PASSED | Total Time: 35.42s ================================================================= ``` - **PASS**: 步骤完全符合接口契约并正常完成; - **FAIL**: 步骤抛出异常或返回结果未达到断言要求,日志中会打印完整 Traceback; - **排错建议**: 遇到失败时,第一时间使用 `--keep-on-error` 重跑,查看浏览器所停留在的网页界面(例如是否被 Cloudflare 拦截、验证码识别错误提示、或是账号被锁定)。 --- ### Python 代码内嵌调用方式 `PluginTester` 也可以作为 Python 库直接被你的脚本或集成测试脚本导入: ```python from tools.plugin_tester import PluginTester # 从配置文件自动加载并运行 tester = PluginTester.from_json_config( plugin_name="pol_plugin", config_path="config/test_conf.json" ) all_passed = tester.run_pipeline(test_book=False, keep_on_error=True) # 动态自定义配置测试 custom_config = PluginTester.create_default_config( username="custom_user@example.com", password="Password123!", proxy_url="http://127.0.0.1:7890" ) tester = PluginTester(plugin_name="vfs_plugin", group_id="vfs.custom", config=custom_config) tester.test_init() tester.test_create_session() query_result = tester.test_query() print("号源结果:", query_result.availability_status) tester.test_cleanup() ``` --- ## France-Visas (法签申请表) 账号全自动注册、填表与 FRA1 提取 Coordinate 提供了法签申请表系统的全流程自动化工具 [`francevisa_keygen.py`](francevisa_keygen.py),支持从 Keycloak 注册、邮箱验证、初始密码设定、登录探针到 Step 1 填表(含中国本土及海外各领区/递签中心,如都柏林、伦敦等)及最终官方 `FRA1` 申请编号的即时提取。 ### 1. 核心自动化流水线 ```mermaid graph TD A[1. 账号注册
Keycloak Usager 提交与验证码识别] --> B[2. 邮箱激活
CloudApi 轮询 Action-Token 极速激活] B --> C[3. 设定初始密码
申请重置并提交 password-new/confirm] C --> D[4. 登录探针与会话
OAuth2 回调换取 JSESSIONID] D --> E[5. 新建申请组与填表
Step 1 级联选项与护照资料填充] E --> F[6. 表单校验与弹窗确认
Verify + Next + Modal Yes 确认锁定] F --> G[7. 提取官方 FRA1 编号
解析 accueil.xhtml 提取 FRA1 编号并本地持久化] ``` --- ### 2. 命令行全量参数速查表 | 参数 Flag / 别名 | 类型 | 默认值 | 详细说明 | | :--- | :--- | :--- | :--- | | **`--config`** / `-c` | string | `None` | 指定 YAML 或 JSON 配置文件路径 | | **`--email`** | string | 自动随机 | 账号邮箱 (如 `user@text.skin`,不传则按前缀+域名自动生成) | | **`--password`** | string | 自动生成 | 账号强密码 (不传则自动生成如 `FraVis@829103!`) | | **`--first-name`** | string | `Jerry` | 申请人名 (First Name) | | **`--last-name`** | string | `Wang` | 申请人姓 (Last Name) | | **`--language`** | string | `English` | 界面语言 (`English` / `Français` 等) | | **`--prefix`** / `--account-prefix` | string | `fra` | 自动生成邮箱前缀 | | **`--domain`** / `--email-domain` | string | `text.skin` | 自动生成邮箱域名 | | **`--master-email`** | string | `hujiarui8@gmail.com` | 接收验证与设密邮件的主邮箱 | | **`--email-token`** | string | `None` | 邮箱 API Token | | **`--proxy`** | string | `None` | 指定网络代理 (如 `http://127.0.0.1:7897`) | | **`--proxy-pool`** | string | `None` | 代理池名称 (在 `config/proxies.yaml` 中定义,如 `local`) | | **`--account-pool`** | string | `None` | 注册成功后上报的云端账号池名称 (如 `fra.app.pool`) | | **`--create-app`** / `--fill-form` | flag | `True` | 注册后自动执行 Step 1 填表并获取 FRA1 编号 (默认开启) | | **`--no-create-app`** | flag | `False` | 仅注册账号,不进行填表获取 FRA1 | | **`--nationality`** | string | `CHN` | 申请人国籍代码 (如 `CHN`, `USA`, `IRL`) | | **`--has-family`** | flag | `False` | 是否有欧盟/欧洲经济区亲属 (默认 No,添加该 flag 为 Yes) | | **`--deposit-country`** | string | `CHN` | 递签国家代码 (如中国 `CHN`、爱尔兰 `IRL`、英国 `GBR`) | | **`--stay-duration`** | string | `C` | 停留期限: `C` (短期 $\le$ 90天), `D` (长期 > 90天), `A` (机场过境) | | **`--destination`** | string | `MET` | 主目的地: `MET` (法国本土), `MCO` (摩纳哥), `REU` (留尼汪) 等 | | **`--city`** / `--town` | string | `1PE` | 递签中心城市代码 (见下方城市代码对照表) | | **`--authority`** | string | `CHN` | 护照签发国代码 (中国护照填 `CHN`,爱尔兰护照填 `IRL`) | | **`--doc-type`** | string | `10` | 证件类型: `10` (普通护照), `30` (外交护照), `40` (公务护照) | | **`--passport-number`** | string | 自动随机 | 填表护照号 (不传则自动随机生成合规 `E`+8位数字) | | **`--release-date`** | string | `01/01/2022` | 护照签发日期 `DD/MM/YYYY` | | **`--expiration-date`** | string | `01/01/2032` | 护照失效日期 `DD/MM/YYYY` | | **`--purpose-category`** | string | `TOUR` | 签证主目的: `TOUR` (旅游), `VISF` (探亲), `ETUD` (留学), `TRAV` (商务) | | **`--purpose`** | string | 自动匹配第一项 | 签证目的子项编号: `1` (个人旅游), `134` (欧盟家属旅游) 等 | | **`--output`** / `-o` | string | `data/francevisa_accounts.txt` | 账号本地持久化文件路径 (同时生成 `.json`) | | **`--max-retries`** | int | `3` | 验证码或网络失败时的最大重试次数 | #### 常用递签城市代码对照表 (`--city` / `--town`) - **中国境内签证中心**: - `1PE`:北京 (Beijing) - `1SH`:上海 (Shanghai) - `1CB`:广州 (Canton) - `1CA`:成都 (Chengdu) - `1WU`:武汉 (Wuhan) - `1SY`:沈阳 (Shenyang) - `1XI`:西安 (Xian) - `1JN`:济南 (Jinan) - `1HN`:杭州 (Hangzhou) - `1NA`:南京 (Nankin) - `1SZ`:深圳 (Shenzhen) - `1CS`:长沙 (Changsha) - `1CQ`:重庆 (Chongqing) - `1FU`:福州 (Fuzhou) - `1KU`:昆明 (Kunming) - **海外热门签证中心**: - **爱尔兰**:`--deposit-country IRL --city 1DB` (都柏林 Dublin,生成的编号格式如 `FRA1DB...`) - **英国**:`--deposit-country GBR --city 1LO` (伦敦 London,生成的编号格式如 `FRA1LO...`) --- ### 3. 典型场景使用示例 #### 示例 A:国内常规申请(北京 1PE,一键注册+填表+生成 FRA1) ```powershell python francevisa_keygen.py ` --email "my_france_01@text.skin" ` --password "FraVis@2026888!" ` --first-name "San" ` --last-name "Zhang" ` --proxy "http://127.0.0.1:7897" ` --city "1PE" ``` #### 示例 B:爱尔兰都柏林递签申请(中国护照持有人在都柏林申请申根签) > **参数说明**:递签国为 `IRL`,递签城市为 `1DB`,护照签发国为 `CHN`。生成的官方申请号前缀为 `FRA1DB...`。 ```powershell python francevisa_keygen.py ` --email "my_dublin_01@text.skin" ` --password "FraVis@2026888!" ` --first-name "San" ` --last-name "Zhang" ` --proxy "http://127.0.0.1:7897" ` --deposit-country "IRL" ` --city "1DB" ` --nationality "CHN" ` --authority "CHN" ` --passport-number "E88765432" ` --purpose-category "TOUR" ``` #### 示例 C:指定 YAML / JSON 配置文件运行 创建配置文件 `config/france_apply.yaml`: ```yaml email: "my_france_custom@text.skin" password: "FraVis@2026888!" first_name: "Jerry" last_name: "Wang" proxy: "http://127.0.0.1:7897" # 填表参数 deposit_country: "IRL" # 爱尔兰 city: "1DB" # 都柏林 nationality: "CHN" # 中国国籍 authority: "CHN" # 中国护照 passport_number: "E99887766" purpose_category: "TOUR" # 旅游 purpose: "1" ``` 命令行直接加载: ```powershell python francevisa_keygen.py --config config/france_apply.yaml ``` #### 示例 D:Python 代码内嵌调用 ```python from francevisa_keygen import FranceVisaKeygen, auto_register # 1. 一键全自动注册 + 填表 + 提取 FRA1 申请号 result = auto_register({ "email": "my_france_app@text.skin", "password": "FraVis@2026888!", "proxy": "http://127.0.0.1:7897", "deposit_country": "IRL", "city": "1DB", "passport_number": "E12345678" }) print("获取到的 FRA1 申请号:", result.get("fra1_number")) # 2. 对已有账号单独调用填表生成 FRA1 client = FranceVisaKeygen( proxy="http://127.0.0.1:7897", account_detail={"email": "my_france_02@text.skin", "password": "FraVis@2026888!"} ) app_res = client.fill_step1_and_create_application({ "deposit_country": "CHN", "city": "1SH", "passport_number": "E87654321" }) print("生成申请编号:", app_res["fra1_number"]) ``` --- ## 系统架构与模块组成 系统分为 **巡检层 (Sentinel)**、**预约层 (Booker)** 与 **插件层 (Plugins)**: - **Sentinel (`sentinel.py`)**: 高频轮询任务,负责维护池化会话并进行号源日历巡检。一旦发现有效号源,立刻写入号源队列并触发通知。 - **Booker (`booker.py`)**: 专职预约执行层,监听抢号任务队列,接收来自 Sentinel 的实时空闲 Slot,迅速填报申请人资料并锁定预约。 - **Standalone (`standalone.py`)**: 独立模式,集查询、监控、预约于一体的单机作业进程。 - **Flow Engine (`utils/flow_engine.py`)**: 声明式状态机,以规则装饰器驱动多步骤拟人化交互(如动态表单跳转、错误弹窗拦截、Turnstile 盾穿透)。 --- ## 已支持插件列表 | 插件标识 (`plugin_name`) | 签证中心 / 平台 | 核心技术方案 | 验证码与反爬对策 | | :--- | :--- | :--- | :--- | | `vfs_plugin` | VFS Global 全球签证 | DrissionPage + JS Fetch 注入、JWT 会话保持 | Cloudflare Turnstile 自动穿透、大模型 OTP 识别 | | `pol_plugin` | 波兰 e-konsulat | DrissionPage 浏览器自动化、日历下拉遍历 | **通用大模型验证码识别器 (`CaptchaBreaker`)** | | `tls_plugin` | TLSContact 欧洲多国 | 声明式 Flow 状态机、贝塞尔拟人化鼠标轨迹 | Cloudflare 5秒盾旁路、动态 Cookie 同步 | | `usa_plugin` | 美签 USVisaScheduling | 声明式 Flow 状态机、网络封包拦截、日历漫游 | KBA 密保问答自动补全、防并发锁控制 | | `ita_plugin` | 意大利 Prenot@Mi | 声明式 Flow 状态机、多领区调度 | PingID 多因素认证、OTP 自动读取 | | `bel_plugin` | 比利时 Visa On Web | 新标签页日历提取与会话绑定 | CapSolver hCaptcha 破解 | | `de_plugin` | 德国 Visametric | 动态 CSRF 提取、Stripe 支付链接捕获 | Visametric 专用字符识别模型 | | `bls_plugin` | 西班牙 BLS | 动态表单解析、护照图片 Multipart 提交 | 字符算术验证码识别 | | `grc_plugin` | 希腊 GVCW | 复杂表单步进控制与材料校验 | 字符验证码识别与会话保活 | | `prt_plugin` | 葡萄牙签证中心 | 流程步进与预约日历提取 | 基础反爬挑战绕过 | --- ## 通用大模型验证码识别器 (CaptchaBreaker) 坐标库中提供了全新的通用大模型视觉识别模块 [`toolkit/captcha_breaker.py`](file:///Users/hujiarui/workspace/coordinate/toolkit/captcha_breaker.py),支持任意基于 OpenAI 兼容协议的多模态模型(如通义千问 Qwen-VL、GPT-4o、DeepSeek-VL、OneAPI 代理等)。 ### 1. 特性 - **多输入格式归一化**:自动兼容本地文件路径、原始二进制字节(`bytes`)、`io.BytesIO`、Base64 字符串以及标准 Data URL。 - **动态清理**:自动剥离大模型返回的 Markdown 代码块标记(```` ``` ````)与常见前后引号。 - **即时配置感知**:在模块顶部静态载入配置,缺省时自动回退读取环境变量;未配置 API Key 访问客户端时抛出结构化 `CaptchaBreakerError`。 ### 2. 配置方式 ([configure.py](file:///Users/hujiarui/workspace/coordinate/configure.py)) ```python CAPTCHA_LLM_CONFIG = { "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key": "sk-your-api-key", "model": "qwen-vl-max", # 或 gpt-4o, deepseek-vl 等 "timeout": 30.0, } ``` *注:若 `CAPTCHA_LLM_CONFIG = None`,系统将自动读取环境变量 `CAPTCHA_LLM_API_KEY`、`CAPTCHA_LLM_BASE_URL`、`CAPTCHA_LLM_MODEL`。* ### 3. 代码中使用 ```python from toolkit.captcha_breaker import CaptchaBreaker breaker = CaptchaBreaker() # 支持直接传入图片字节、Base64 或文件路径 captcha_code = breaker.break_captcha("data:image/png;base64,iVBORw0KGgo...") # 也支持自定义业务场景的 Prompt(例如 VFS 指向型验证码) custom_prompt = "图片中有多组验证码,其中OTP箭头指向的验证码为真,其余为假。只输出真实验证码的内容。" otp_code = breaker.break_captcha(image_data, prompt=custom_prompt) ``` --- ## 项目目录结构 ```text coordinate/ ├── config/ # 运行时与测试配置目录 │ ├── test_conf.json # PluginTester 全插件测试参数集 │ ├── config_booker.json # 抢号预约进程配置 │ └── config_sentinel.json # 巡检监控进程配置 ├── configure.py # 核心系统配置(Redis、大模型 API、Mihomo 等) ├── plugins/ # 签证中心业务插件 (实现 IPlugin 规范) │ ├── vfs_plugin.py # VFS 插件 │ ├── pol_plugin.py # 波兰插件 (已接入 CaptchaBreaker) │ ├── tls_plugin.py # TLS 插件 │ └── ... ├── toolkit/ # 通用底层工具库 │ ├── captcha_breaker.py # 通用多模态大模型验证码识别器 │ ├── mihomo_tunnel.py # 智能代理隧道与节点管理 │ ├── backoff.py # 指数退避重试器 │ └── cloud_api.py # 云端邮箱验证码与配置同步 ├── tools/ # 运维与开发工具 │ └── plugin_tester.py # 插件标准生命周期测试器 ├── utils/ # 辅助机制 (状态机、反爬绕过、指纹配置) │ ├── flow_engine.py # 声明式状态机引擎 │ ├── plugin_utils.py # 浏览器初始化与环境清理 │ └── cloudflare_bypass_for_scraping.py # Cloudflare 穿透工具 └── test/ # 单元测试与测试用例集 └── test_captcha_breaker.py ``` --- ## 环境搭建与快速开始 ### 1. 安装依赖 建议使用 Python 3.10+ 虚拟环境: ```bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` ### 2. 检查浏览器支持 系统基于 DrissionPage 驱动 Chromium 浏览器。推荐系统预装 Google Chrome 或 Ungoogled Chromium。若需要指定路径,可在 `configure.py` 中配置 `CHROME_PATH`。 ### 3. 执行插件自检 ```bash python3 tools/plugin_tester.py --plugin pol_plugin ``` --- ## 单元测试 运行项目内置的自动化单元测试集: ```bash # 运行 CaptchaBreaker 通用大模型识别测试套件 (13 项测试) ./venv/bin/python -m unittest test/test_captcha_breaker.py # 发现并运行全部测试 ./venv/bin/python -m unittest discover -s test -p "test_*.py" ```