# NovaCaptcha 全自动智能打码浏览器插件使用与批量部署指南 (v2.1.0)

> **适用版本**：`v2.1.0` (Manifest V3)
> **线上生产网关地址 (`Gateway BaseURL`)**：`https://solver.captchabox.cc`
> **插件压缩包下载**：`https://solver.captchabox.cc/assets/novacaptcha_extension.zip`
> **核心特性**：支持 **Google reCAPTCHA v2/v3/Enterprise**、**Cloudflare Turnstile 单选框**、**Arkose Labs (FunCaptcha) 6宫格/3D旋转题**、**hCaptcha 九宫格与动态补图** 全自动识别与拟人轨迹点击。

---

## 一、 核心能力与工作原理

1. **All-Frames 跨层自动监听 (`content_solver.js`)**：
   - 自动挂载至页面顶层与所有同源/跨域验证码 `iframe`（包括 `google.com/recaptcha/api2/anchor`、`recaptcha/api2/bframe`、`challenges.cloudflare.com`、`client-api.arkoselabs.com`、`newassets.hcaptcha.com`）。
2. **CDP 硬件级拟人轨迹点击 (`background.js`)**：
   - 针对 Cloudflare Turnstile 与高风控单选框，通过 `chrome.debugger` 协议调用 `Input.dispatchMouseEvent` 生成 7 段加速/减速贝塞尔鼠标移动轨迹并派发硬件级 `isTrusted: true` 点击事件。
3. **3×3 / 4×4 整图与 100×100 动态淡入补图极速识别**：
   - 首轮自动截取 300×300 / 450×450 完整九宫格图像发送至 `https://solver.captchabox.cc/createTask`（优先命中 SQLite 3级感知哈希题库，平均耗时 **0.08s**；未命中题目自动路由至云端 `Gemini-3.5-Flash-Lite` 视觉集群推理并自动回写题库）。
   - 对于点击后原地淡入新图的动态九宫格（`rc-imageselect-dynamic-selected`），插件自动监听新图加载完成并批量并发识别，直至页面内不再出现目标物体后自动点击 `#recaptcha-verify-button` 完成过盾。

---

## 二、 方式一：Chrome / Edge 桌面浏览器手动安装步骤

1. **下载并解压插件包**：
   - 在 NovaCaptcha 官网顶部导航点击 **「浏览器插件 (`/extension`)」**，下载 `novacaptcha_extension.zip` 并解压到本地固定文件夹（例如 `D:\novacaptcha_extension` 或 `~/novacaptcha_extension`）。
2. **打开浏览器扩展管理页**：
   - Chrome 浏览器地址栏输入：`chrome://extensions/`
   - Edge 浏览器地址栏输入：`edge://extensions/`
3. **开启开发者模式并加载**：
   - 打开页面右上角的 **「开发者模式 (Developer mode)」** 开关。
   - 点击左上角 **「加载已解压的扩展程序 (Load unpacked)」**，选择刚才解压的 `novacaptcha_extension` 目录。
4. **配置专属 ClientKey 与生产网关**：
   - 点击浏览器右上角拼图图标，固定并打开 **「NovaCaptcha 智能打码助手」** 弹窗：
     - **专属 API 密钥 (`ClientKey`)**：填入您在「用户控制台 (`/dashboard`)」创建的任意启用中的 `ak_live_...` 密钥（支持多 Key 分流不同机器）。
     - **生产网关地址 (`Gateway BaseURL`)**：默认已填好线上生产网关 `https://solver.captchabox.cc`。
   - 点击 **「保存配置并同步至所有标签页」** 即可全自动工作。

---

## 三、 方式二：AdsPower / 比特浏览器 (BitBrowser) 批量分发方案

1. **预设团队默认 ClientKey（免逐窗口手动输入）**：
   - 解压 `novacaptcha_extension.zip` 后，用文本编辑器打开 `background.js`，将第 10 行的 `clientKey` 修改为您在控制台为该集群专门创建的子密钥（例如 `ak_live_adspower...`），重新打包为 `.zip`。
2. **上传至指纹浏览器应用中心**：
   - 打开 AdsPower 或比特浏览器客户端 → 左侧进入 **「应用中心 / 扩展管理」** → 点击 **「上传扩展」** 上传插件包，并开启 **「对所有新建环境自动启用」**。
3. **多窗口并发过盾**：
   - 所有环境启动后会自动加载插件，并在后台静默完成 reCAPTCHA / Turnstile / FunCaptcha / hCaptcha 过盾，控制台可按子密钥独立统计调用次数与消耗点数。

---

## 四、 方式三：Playwright / Puppeteer 自动化脚本挂载插件示例

### 4.1 Python Playwright 自动加载插件过盾示例

```python
from playwright.sync_api import sync_playwright

EXT_PATH = "/path/to/novacaptcha_extension"

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        user_data_dir="/tmp/novacaptcha_profile",
        headless=False,
        args=[
            f"--disable-extensions-except={EXT_PATH}",
            f"--load-extension={EXT_PATH}",
            "--no-sandbox",
        ],
    )
    page = context.new_page()
    page.goto("https://www.google.com/recaptcha/api2/demo")
    # 插件将自动点击复选框、识别九宫格并取得 g-recaptcha-response Token
    page.wait_for_Function(
        "() => document.querySelector('#g-recaptcha-response')?.value?.length > 20",
        timeout=45000,
    )
    token = page.eval_on_selector("#g-recaptcha-response", "el => el.value")
    print("過盾成功，获取到 Token 前 48 位:", token[:48])
```

### 4.2 Node.js Puppeteer 自动加载插件过盾示例

```javascript
const puppeteer = require('puppeteer');
const path = require('path');

(async () => {
  const extPath = path.resolve('./novacaptcha_extension');
  const browser = await puppeteer.launch({
    headless: false,
    args: [
      `--disable-extensions-except=${extPath}`,
      `--load-extension=${extPath}`,
      '--no-sandbox'
    ]
  });
  const page = await browser.newPage();
  await page.goto('https://www.google.com/recaptcha/api2/demo');
})();
```

---

## 五、 插件面板配置项完整参考表

| 配置项名称 | 字段名 (`chrome.storage.local`) | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| **生产网关地址** | `gatewayUrl` | `https://solver.captchabox.cc` | 指向 NovaCaptcha 线上高并发网关 |
| **专属 API 密钥** | `clientKey` | `ak_live_...` | 用于身份鉴权与点数结算（识别失败不扣费） |
| **全自动打码总开关** | `enabled` | `true` | 控制是否自动监听页面内的验证码框架 |
| **Google reCAPTCHA** | `enableRecaptchaV2` | `true` | 自动点击复选框 + 3×3/4×4 九宫格与动态补图识别 |
| **Cloudflare Turnstile** | `enableTurnstile` | `true` | 自动计算验证框坐标并通过 CDP 派发拟人轨迹点击 |
| **Arkose FunCaptcha** | `enableFuncaptcha` | `true` | 自动点击开始按钮并完成 6 宫格 3D 朝向/旋转识别 |
| **hCaptcha 图像分类** | `enableHcaptcha` | `true` | 自动勾选复选框并完成九宫格多图分类点击 |
| **拟人点击间隔 (ms)** | `clickDelayMs` | `220` | 多格连续点击之间的拟人随机间隔基准毫秒数 |