rea-captcha

rea-captcha

通过 CAPTCHA 交接，让 Browser Use 任务继续运行。

翻译

English · العربية · Deutsch · Ελληνικά · Español · فارسی · Français · Bahasa Indonesia · Italiano · 日本語 · 한국어 · Polski · Português (Brasil) · Русский · ไทย · Türkçe · Українська · Tiếng Việt · 简体中文 · 繁體中文

安装 · 在线演示 · 演示证据 · 工作原理 · MCP 工具目录 · 案例 · 架构

当 Browser Use 任务进行到一半遇到 CAPTCHA 时，rea-captcha 会在 Agent 已经拥有的浏览器会话中处理拦截和恢复。它会检测支持的验证挑战，协调经授权的操作或人工交接，要求提供经过服务器验证的最新证据，然后将控制权交还给同一任务。它提供 TypeScript SDK、本地 stdio MCP 服务、browser-use 插件、兼容 Vercel 的 Agent Skill，以及可选的授权来源本地 OCR。

**官方来源：**请从 masakaai/rea-captcha 和 npm 包 rea-captcha 安装。本项目没有托管式求解器、遥测、隐身声明，也不依赖 Jet Browser。它会复用 Agent 现有的浏览器；提供商示例仅使用有文档说明的非生产凭据。

运行四种实时验证案例

_{如果它解决了你实际遇到的交接问题，点个星就能帮助其他 Browser Use 开发者发现这个项目。}

## 演示证明了什么

这些是由 Agent 驱动的完整受保护操作流程，并非仅包含 DOM 的测试夹具。每次运行都会检测挑战，在同一页面中执行经授权的浏览器交互，提交至真实验证边界，获取最新的通过证据，验证会话 Cookie，并恢复同一个控制器。Google reCAPTCHA v2、Cloudflare Turnstile 和 hCaptcha 使用其文档说明的测试模式以及厂商的 Siteverify 端点；自有的图像／文本案例则使用明确授权的本地路径和本地服务端验证。

前三个案例会加载厂商托管的 JavaScript，并且只有在服务端从厂商验证端点收到 success: true 后，才接受受保护的操作。它们使用厂商文档说明的非生产凭据：Google 测试密钥、Cloudflare 虚拟密钥 和 hCaptcha 测试密钥。

npm run demo:web       # interactive local demo
npm run test:web-demo  # all four live validation paths

安装

Browser Use

从经过验证的发布 wheel 安装版本匹配的 Python 适配器：

python -m pip install 'rea-captcha[browser-use] @ https://github.com/masakaai/rea-captcha/releases/download/v0.3.1/rea_captcha-0.3.1-py3-none-any.whl'

将交接保护器附加到已拥有浏览器会话的 Agent：

from rea_captcha import ChallengePlugin

challenge = ChallengePlugin(mode="local", human_handoff=True)
await challenge.attach(agent)

该插件会借用 Agent 当前的 BrowserSession；它不会启动或替换浏览器。请参阅 Browser Use 交接指南 和完整示例。

CI 会安装受支持的 Browser Use 依赖，并针对真实的 Agent／BrowserSession 暂停－恢复约定测试该适配器；请参阅集成测试。

MCP 和编码 Agent

用于本地、无状态的证据分析：

npx [email protected] mcp --stateless

无状态模式不会控制浏览器。同一会话中的操作需要配置 Playwright/CDP 适配器；运行 npx [email protected] agent-config --agent mcp-json 可生成主机配置。

也可以请 Codex、Claude Code、Cursor 或其他编码 Agent 为项目配置正确路径：

Install rea-captcha in this project and connect it to the browser session this agent already uses.

工作原理

MCP 和编码 Agent

官方 Registry 条目为 io.github.masakaai/rea-captcha，并通过 npm 启动零配置 stdio 服务：

npx [email protected] mcp --stateless

请检查固定的程序包版本；只有在它与您打算运行的版本一致时，才批准 npm 的安装提示。该命令不会抑制此提示。

它提供六个工具：captcha_analyze、captcha_inspect、captcha_complete、captcha_handoff、captcha_wait 和 captcha_resume。captcha_complete 只会在已配置的现有浏览器中执行经策略授权的操作，并等待最新的验证证据。有关输入和生命周期语义，请参阅工具目录。

对于有状态的本地会话，请运行设置命令并打印主机配置：

npx rea-captcha agent-config --agent codex
npx rea-captcha agent-config --agent mcp-json

rea-captcha 提供验证智能和有界完成操作；它不会替代 Agent 的导航工具。两种集成都必须指向同一个浏览器会话。

Hermes Agent 用户可以查看 Portable Agent Plugins v1 程序包。其目录安全默认模式是无状态证据分析；同一会话中的浏览器操作仍需要显式配置有状态的 rea-captcha。

TypeScript SDK

import { ChallengeController, ChallengePolicy } from 'rea-captcha';
import { PlaywrightChallengeAdapter } from 'rea-captcha/playwright';

const authorizedOrigin = 'https://fixture.example';
const controller = new ChallengeController({
  browser: new PlaywrightChallengeAdapter({
    id: 'checkout',
    page,
    agentActions: {
      authorizedOrigins: [authorizedOrigin],
      allowProviderTestAutomation: true,
      submitSelector: 'button[type="submit"]'
    }
  }),
  policy: new ChallengePolicy({
    authorizedOrigins: [authorizedOrigin],
    allowProviderTestAutomation: true
  })
});

const inspection = await controller.inspect();
if (inspection.policy.decision === 'agent-action' || inspection.policy.decision === 'local-processing') {
  await controller.complete({ timeoutMs: 30_000 });
  await controller.resume();
} else if (inspection.policy.decision === 'human-handoff') {
  const handoff = await controller.handoff({ taskId: 'checkout-run-42' });
  await controller.wait({ timeoutMs: 120_000 });
  await controller.resume({
    taskId: 'checkout-run-42',
    handoffId: handoff.handoff.id
  });
}

控制器会借用 page；它不会创建或关闭浏览器。人工完成只是唤醒信号，并非成功证明：交接身份绑定到任务、现有标签页／会话和关卡代次；控制器仍会在消费该信号前要求最新证据，并且只消费一次。

浏览器提供方

推荐用于跨 Agent 的提供方是已开放 CDP 的浏览器：

{
  "version": 1,
  "sessions": {
    "local-chrome": {
      "adapter": "playwright-cdp",
      "endpoint": "http://127.0.0.1:9222",
      "allowProviderTestAutomation": true,
      "submitSelector": "button[type=submit]",
      "authorizedOrigins": ["https://fixture.example"]
    }
  }
}

已实现通用 Playwright Page、基于 CDP 的 Playwright、browser-use，以及可选的 Jet Browser 托管式／独立适配器。必须显式选择 Jet Browser，默认路径既不会安装也不会启动它。配置示例和提供方边界见架构和案例。

browser-use 和本地 OCR

Python 适配器尚未发布到 PyPI，因此不带限定条件的 pip install rea-captcha 将无法使用。固定版本的 wheel 根据 v0.3.1 标签构建，在 GitHub Actions 中经过冒烟测试，并附在相应的发行版中。

要由 Agent 驱动完成流程，请将 rea-captcha 的 Playwright/CDP 会话指向 browser-use 使用的同一个现有浏览器。MCP 生命周期会检测拦截、执行已获授权的操作、验证结果，然后交还控制权，而不会替换浏览器或任务上下文。

安装中展示的 Python 插件仍是轻量级检测和手动恢复备用方案，适用于未提供兼容 CDP 操作界面的 browser-use 集成。

本地 ddddocr 仅是可选的基础能力，只用于精确授权源上的简单图像／文本挑战。除非同时配置 allowLocalImageText 和 authorizedOrigins，否则该功能处于禁用状态。不会重新分发任何模型权重，OCR 预测仍属于不可信证据。

已实现的功能

• 检测 reCAPTCHA、hCaptcha、Turnstile、GeeTest、DataDome、PerimeterX、AWS WAF、图像／文本输入和通用验证页面的证据。
• 提供确定性状态、有限时长的超时、取消，以及恢复时对新证据的检查。
• 六个 stdio MCP 工具、CLI/MCP 功能对等、TypeScript SDK、browser-use 钩子，以及兼容 Vercel 的 Agent Skill。
• 借用的 Playwright/CDP 会话，以及可选的 Jet Browser 适配器。
• 本地 JSONL 事件，明确所有权，且不收集遥测数据。
• npm Trusted Publishing／来源证明工作流，以及通过 GitHub OIDC 发布到官方 MCP Registry。

文档

• 架构和信任边界
• Browser Use 交接指南
• 案例矩阵和测试固定项说明
• MCP 工具目录
• 验证证据
• 发行和 Trusted Publisher 流程
• 生态系统和 awesome-list 收录
• 安全策略
• 贡献指南

社区

在 GitHub Discussions 中咨询集成问题，并分享同会话的 Agent 示例。如需实时聊天，请加入 MASAKA Discord，并使用专用的 #rea-captcha 频道。可复现的 Bug 请通过 GitHub Issues 提交；漏洞请遵循私密安全策略报告。切勿发布浏览器配置文件、Cookie、挑战令牌、API 密钥或私人页面证据。

范围和免责声明

rea-captcha 适用于自有或明确授权的工作流。只有在适配器确认使用供应商文档中注明的非生产测试密钥时，才允许进行提供方自动化。它不会绕过生产环境中的交互式防护。商用求解器 API、凭据传输、隐身相关声明，以及自动完成第三方生产环境挑战均不在支持范围内。

灵感来自 morluto/rea。

许可证

核心代码和集成采用 MIT 许可证。可选依赖项和模型制品遵循各自的条款；请参阅第三方声明和模型许可证。