Açıklama Yok

zhangweijp dc92bb3b0d feat(ita): improve Dublin booking form and session handling 1 ay önce
config 8070975493 feat: update 1 ay önce
data 7f3fc1b215 feat: update 6 ay önce
docs 65afa28f52 feat: add lightweight keepalive for plugin instance and standalone loop 2 ay önce
plugins dc92bb3b0d feat(ita): improve Dublin booking form and session handling 1 ay önce
test 95ddf8eb4b feat: implement proxy reputation scheduling, telemetry metrics, and safe account release 1 ay önce
toolkit 95ddf8eb4b feat: implement proxy reputation scheduling, telemetry metrics, and safe account release 1 ay önce
tools 8070975493 feat: update 1 ay önce
utils 8070975493 feat: update 1 ay önce
.dockerignore 8070975493 feat: update 1 ay önce
.gitignore 8070975493 feat: update 1 ay önce
Dockerfile 8070975493 feat: update 1 ay önce
README.md 8070975493 feat: update 1 ay önce
booker.py 95ddf8eb4b feat: implement proxy reputation scheduling, telemetry metrics, and safe account release 1 ay önce
configure.py 4ed096dc13 feat: update keygens, refactor sentinel/standalone query flow and cleanup registration tools 1 ay önce
core_types.py 742dcf8e6d refactor 1 ay önce
deps.txt 07ead8e888 feat: update 5 ay önce
deps_registry.py 8070975493 feat: update 1 ay önce
docker-compose.yml c79cef102c refactor(sweeper): use configure.REDIS_CFG, setup_app_logger and add graceful shutdown; update docker default NODE_ID 2 ay önce
download_deps.py 8070975493 feat: update 1 ay önce
entrypoint.sh 757dc068dc feat(core): 重构统一入口并完善插件动态元数据与状态监控 2 ay önce
francevisa_keygen.py df1fe293ba fix: vfs cloudflare block 1 ay önce
gco_wrapper.py 742dcf8e6d refactor 1 ay önce
log_macros.py 742dcf8e6d refactor 1 ay önce
logger_setup.py 742dcf8e6d refactor 1 ay önce
main.py 8070975493 feat: update 1 ay önce
main_sweeper.py 742dcf8e6d refactor 1 ay önce
plugin.py 742dcf8e6d refactor 1 ay önce
plugin_factory.py 742dcf8e6d refactor 1 ay önce
requirements.txt 8070975493 feat: update 1 ay önce
sentinel.py 95ddf8eb4b feat: implement proxy reputation scheduling, telemetry metrics, and safe account release 1 ay önce
standalone.py 742dcf8e6d refactor 1 ay önce
start_proxy.py 8070975493 feat: update 1 ay önce
supersaas_keygen.py 8070975493 feat: update 1 ay önce
tls_keygen.py 8070975493 feat: update 1 ay önce
vfs_keygen.py df1fe293ba fix: vfs cloudflare block 1 ay önce

README.md

Coordinate 签证预约自动化系统

Coordinate 是一个高并发、插件化的多国签证预约与监控自动化系统。支持通过声明式状态机与拟人化浏览器自动化(DrissionPage / curl_cffi / 大模型视觉识别 / CapSolver 等)完成反爬穿透、会话建立、号源实时监控与自动占位预约。


目录


插件测试工具 (PluginTester) 全指南

Coordinate 提供了全功能的插件测试脚手架 tools/plugin_tester.py,用于在不启动分布式任务调度的情况下,对任意签证插件进行孤立、可复现的完整生命周期测试、反爬连通性验证与号源查询调试。

7 步标准化测试流水线

PluginTester 按照以下生命周期顺序执行契约测试:

graph LR
    Step1[1. test_init<br>插件实例化与配置注入] --> Step2[2. test_create_session<br>反爬穿透与会话建立]
    Step2 --> Step3[3. test_health_check<br>会话心跳与保活验证]
    Step3 --> Step4[4. test_status<br>运行时指标与健康度]
    Step4 --> Step5[5. test_query<br>可预约时段与日历抓取]
    Step5 --> Step6[6. test_book<br>锁定号源与提交 - 可选]
    Step6 --> Step7[7. test_cleanup<br>浏览器销毁与临时文件清理]
  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. 运行单个插件的查询流水线 (推荐最常用)

# 测试波兰 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 现场不退出,方便人工在页面上审查元素、排查原因:

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)

用于在测试完全成功后仍想人工查看最终页面状态的场景:

python3 tools/plugin_tester.py --plugin vfs_plugin --no-cleanup

4. 包含预约提交流程测试 (--book)

默认测试只会执行到 query 查询步骤,若需验证选时间与提交申请逻辑,追加 --book:

python3 tools/plugin_tester.py --plugin vfs_plugin --book

5. 快速检查插件工厂配置与实例化 (--only-init)

毫秒级校验插件能否被工厂识别并成功装载配置,不启动真实浏览器:

# 检查单个插件
python3 tools/plugin_tester.py --plugin vfs_plugin --only-init

# 检查所有插件
python3 tools/plugin_tester.py --plugin all --only-init

6. 命令行即时覆盖账号密码与代理

无需修改配置文件,直接通过命令行临时传入特定的账号或独立代理:

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 指定自定义配置文件:

python3 tools/plugin_tester.py --plugin vfs_plugin -c "config/staging_conf.json"

8. 全量批量回归测试

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)

配置文件集中管理各签证中心的站点参数、测试账号及申请人信息:

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

诊断报告解读与排错

每次测试结束时,控制台将输出格式化的执行时间与状态诊断表格:

=================================================================
📊 [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 库直接被你的脚本或集成测试脚本导入:

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,支持从 Keycloak 注册、邮箱验证、初始密码设定、登录探针到 Step 1 填表(含中国本土及海外各领区/递签中心,如都柏林、伦敦等)及最终官方 FRA1 申请编号的即时提取。

1. 核心自动化流水线

graph TD
    A[1. 账号注册<br>Keycloak Usager 提交与验证码识别] --> B[2. 邮箱激活<br>CloudApi 轮询 Action-Token 极速激活]
    B --> C[3. 设定初始密码<br>申请重置并提交 password-new/confirm]
    C --> D[4. 登录探针与会话<br>OAuth2 回调换取 JSESSIONID]
    D --> E[5. 新建申请组与填表<br>Step 1 级联选项与护照资料填充]
    E --> F[6. 表单校验与弹窗确认<br>Verify + Next + Modal Yes 确认锁定]
    F --> G[7. 提取官方 FRA1 编号<br>解析 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)

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...。

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:

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"

命令行直接加载:

python francevisa_keygen.py --config config/france_apply.yaml

示例 D: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,支持任意基于 OpenAI 兼容协议的多模态模型(如通义千问 Qwen-VL、GPT-4o、DeepSeek-VL、OneAPI 代理等)。

1. 特性

  • 多输入格式归一化:自动兼容本地文件路径、原始二进制字节(bytes)、io.BytesIO、Base64 字符串以及标准 Data URL。
  • 动态清理:自动剥离大模型返回的 Markdown 代码块标记(```)与常见前后引号。
  • 即时配置感知:在模块顶部静态载入配置,缺省时自动回退读取环境变量;未配置 API Key 访问客户端时抛出结构化 CaptchaBreakerError。

2. 配置方式 (configure.py)

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. 代码中使用

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)

项目目录结构

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+ 虚拟环境:

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. 执行插件自检

python3 tools/plugin_tester.py --plugin pol_plugin

单元测试

运行项目内置的自动化单元测试集:

# 运行 CaptchaBreaker 通用大模型识别测试套件 (13 项测试)
./venv/bin/python -m unittest test/test_captcha_breaker.py

# 发现并运行全部测试
./venv/bin/python -m unittest discover -s test -p "test_*.py"