🛡️ hCaptcha Challenger (OpenAI-Compatible Fork)

用多模态大模型优雅地应对 hCaptcha 人机验证挑战。

AI vs AI · 无油猴脚本 · 无第三方打码服务

---

📌 项目说明

本仓库是 QIN2DIM/hcaptcha-challenger 的二次开发分支（Fork），在原项目能力之上新增了 OpenAI 兼容后端支持：

• 新增 OpenAIProvider：对接任意 OpenAI 兼容接口（含视觉模型），支持图片 base64 输入、JSON 结构化输出、自动重试
• AgentConfig 全面支持环境变量配置：OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL
• 设置了 OpenAI 兼容后端时自动优先使用，未设置时回退 Gemini

许可证：GPL-3.0（继承上游）。上游原版：https://github.com/QIN2DIM/hcaptcha-challenger

---

✨ 核心能力

挑战类型	可插拔资源	状态
image_label_binary	ResNet ONNX 分类	✅
image_label_area_select: point	YOLOv8 ONNX 检测	✅
image_label_area_select: bounding box	YOLOv8 ONNX 分割	-
image_label_multiple_choice	ViT ONNX zero-shot 动作	-
image_drag_drop	空间链式推理 (Spatial CoT)	✅

无需依赖任何 Tampermonkey 脚本，也不调用任何第三方打码服务——让 AI 直接对抗 AI。

---

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt
# 或使用 uv
uv sync

2. 配置后端（二选一）

方式 A：OpenAI 兼容后端（本分支新增）

复制 .env.example 为 .env 并填写：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-endpoint/v1   # 任意 OpenAI 兼容地址
OPENAI_MODEL=your-vision-model             # 例如 point/glm-5v-turbo

方式 B：Gemini 后端（上游原版）

GEMINI_API_KEY=your-gemini-api-key

优先规则：设置了 OPENAI_BASE_URL 时使用 OpenAI 兼容后端；否则回退 Gemini。两者都未配置时启动会报错提示。

3. 使用

from hcaptcha_challenger import AgentV, AgentConfig

config = AgentConfig()            # 自动读取环境变量 / .env
agent = AgentV(page=page, config=config)

# 处理挑战
result = agent.handle_challenge(challenge_payload)

---

📂 环境变量一览

变量	必填	说明
OPENAI_API_KEY	方式 A	OpenAI 兼容接口的 API Key
OPENAI_BASE_URL	方式 A	OpenAI 兼容接口地址（以 /v1 结尾）
OPENAI_MODEL	否	使用的模型名（默认取各任务模型，可统一覆盖）
GEMINI_API_KEY	方式 B	Gemini API Key（未设 OpenAI 时必填）
MAX_CRUMB_COUNT	否	每次挑战的最大轮数（默认 2）
EXECUTION_TIMEOUT	否	执行超时（秒，默认 120）
RETRY_ON_FAILURE	否	失败自动重试（默认 true）

完整配置项见 examples/.env.example。

---

📚 参考与致谢

• 上游项目：QIN2DIM/hcaptcha-challenger 🙏
• Microsoft/playwright-python
• Google/Gemini

---

⚠️ 免责声明

本项目仅用于学习与技术研究。请遵守目标网站的服务条款与相关法律法规，请勿用于任何违规用途。