jerry 5c27acff2a refactor: migrate cloud config fetching to VSCloudApi and unify plugin error types and utilities преди 2 месеца
..
README.md 5c27acff2a refactor: migrate cloud config fetching to VSCloudApi and unify plugin error types and utilities преди 2 месеца
cf_bypasser.py 5c27acff2a refactor: migrate cloud config fetching to VSCloudApi and unify plugin error types and utilities преди 2 месеца
tls_flow.py 5c27acff2a refactor: migrate cloud config fetching to VSCloudApi and unify plugin error types and utilities преди 2 месеца

README.md

TLScontact 签证预约自动化系统 (DrissionPage 注解流驱动)

本项目基于 DrissionPage 与 声明式注解状态机(Annotation-Driven Flow) 架构,专为 TLScontact 等复杂多步骤、带 Cloudflare 挑战与动态页面流转的签证预约场景设计。


🌟 核心特性

  1. 声明式注解架构:
    • @on(url=..., title=..., ele=..., not_ele=..., priority=...):声明页面状态与触发动作。
    • @guard(...):高优先级异常守卫(处理 502/504、Cloudflare Challenge、Session 过期)。
    • @fatal(...):命中特定错误(如未添加申请人、账号锁定)时立即终止。
    • @done:命中成功终态时自动提交并成功退出。
  2. Cloudflare 自动穿透:
    • 自动识别 Cloudflare Turnstile / 5秒盾挑战,穿透 iframe 与 DOM 节点进行拟人化点击,带人工兜底。
  3. 开箱即用内置 Chromium:
    • 自动优先检测并加载项目目录自带的 ungoogled-chromium-148.0.7778.215-1-x86_64_linux/chrome,无需复杂安装。
  4. 内置 Mock 模拟测试:
    • 提供内置轻量 Mock 服务,一键进行全链路离线模拟测试,验证各状态转移与规则调度。
  5. 健壮防卡死自愈:
    • 内置步数扫描、停滞检测与页面自愈刷新机制。

📁 目录结构

.
├── config.yaml          # 运行时主配置文件
├── config.example.yaml  # 配置文件模板
├── flow_annotated.py    # 注解流驱动核心引擎 (BaseFlow, @on, @guard, @done, @fatal)
├── cf_bypasser.py       # Cloudflare Turnstile / 5秒盾自动绕过模块
├── tls_flow.py          # TLScontact 业务流程状态机实现 (TlsContactFlow)
├── mock_server.py       # 本地离线 Mock 服务端
├── main.py              # 主程序命令行启动入口
├── requirements.txt     # Python 依赖清单
└── ungoogled-chromium-* # 内置免安装 Chromium 浏览器

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 一键离线 Mock 模拟测试 (推荐优先尝试)

无需配置真实账号或连接外部网络,运行本地模拟测试:

# 无头模式快速测试
python main.py --mock --headless

# 有头模式可视化测试 (观察浏览器真实点击与跳转)
python main.py --mock

3. 正式生产环境运行

编辑 config.yaml 填写您的实际信息:

auth:
  username: "your_email@example.com"
  password: "your_secure_password"

target:
  url: "https://visas-de.tlscontact.com/visa/gb/gbLON2de/home"
  login_url: "https://visas-de.tlscontact.com/visa/gb/gbLON2de/login"

flow:
  interval: 1.0
  max_steps: 45
  preferred_dates:
    - "2026-09"

启动正式流程:

python main.py

4. 命令行参数支持

  • --mock / --test:启动本地 Mock 服务进行端到端测试。
  • --headless:强制使用无头模式运行。
  • --config <path>:指定自定义配置文件路径(默认 config.yaml)。
  • --username <user> / --password <pwd>:命令行覆盖账号密码。
  • --url <url>:命令行覆盖目标入口 URL。