rea-captcha

rea-captcha

CAPTCHA の引き継ぎ後も、Browser Use タスクを継続できます。

翻訳

英語 · アラビア語 · ドイツ語 · ギリシャ語 · スペイン語 · ペルシャ語 · フランス語 · インドネシア語 · イタリア語 · 日本語 · 韓国語 · ポーランド語 · ポルトガル語（ブラジル） · ロシア語 · タイ語 · トルコ語 · ウクライナ語 · ベトナム語 · 簡体字中国語 · 繁体字中国語

インストール · ライブデモ · デモの検証結果 · 仕組み · MCP カタログ · ケース · アーキテクチャ

Browser Use タスクの途中で CAPTCHA に遭遇した場合、rea-captcha はブロックへの対処と復旧を、エージェントがすでに使用しているブラウザーセッション内で行います。対応する認証チャレンジを検出し、許可された操作または人間への引き継ぎを調整して、サーバーで検証された最新の証拠を必須としたうえで、同じタスクに制御を戻します。TypeScript SDK、ローカル stdio MCP サーバー、browser-use プラグイン、Vercel 互換の Agent Skill、さらにオプションで許可されたオリジンに対するローカル OCR を提供します。

公式ソース： masakaai/rea-captcha および npm パッケージ rea-captcha からインストールしてください。このプロジェクトには、ホスト型ソルバー、テレメトリー、ステルス機能の主張、Jet Browser への依存はありません。エージェントが既存のブラウザーを再利用します。プロバイダーの例では、ドキュメントに記載された非本番用の認証情報のみを使用します。

ライブ認証ケース4種類を実行

_{実際に遭遇した引き継ぎ問題の解決に役立った場合は、スターを付けていただくと、ほかの Browser Use 開発者にも見つけてもらいやすくなります。}

## デモで実証すること

これらは、DOM のみを使ったテスト用フィクスチャではなく、エージェントが操作する完全な保護アクションのフローです。各実行ではチャレンジを検出し、同じページ上で許可されたブラウザー操作を実行して、実際の検証境界に送信し、新しい合格証拠を確認し、セッション Cookie を検証して、同じコントローラーを再開します。Google reCAPTCHA v2、Cloudflare Turnstile、hCaptcha では、各ベンダーのドキュメントに記載されたテストモードと Siteverify エンドポイントを使用します。独自の画像／テキストケースでは、明示的に許可されたローカルパスとローカルサーバーの検証を使用します。

最初の 3 つのケースでは、ベンダーがホストする 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

検証済みのリリースホイールから、バージョンが一致する 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)

プラグインはエージェントの現在の BrowserSession を借用します。ブラウザーを起動したり置き換えたりすることはありません。Browser Use ハンドオフガイドと完全な例を参照してください。

CI ではサポート対象の Browser Use 依存関係をインストールし、実際の Agent／BrowserSession の一時停止・再開コントラクトに対してアダプターをテストします。統合テストを参照してください。

MCP とコーディングエージェント

ローカルでステートレスな証拠分析を行う場合：

npx [email protected] mcp --stateless

ステートレスモードではブラウザーを制御しません。同じセッションでアクションを実行するには、Playwright／CDP アダプターを設定する必要があります。npx [email protected] agent-config --agent mcp-json を実行して、ホスト設定を生成してください。

または、Codex、Claude Code、Cursor、その他のコーディングエージェントに、プロジェクトに適した方法を設定するよう依頼できます：

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

仕組み

MCP とコーディングエージェント

公式レジストリエントリーは io.github.masakaai/rea-captcha です。npm を通じて、設定不要の stdio サーバーを起動します：

npx [email protected] mcp --stateless

固定されたパッケージバージョンを確認し、実行する予定のリリースと一致する場合にのみ、npm のインストールプロンプトを承認してください。このコマンドはそのプロンプトを非表示にしません。

6 つのツールを公開します：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 は検証に関するインテリジェンスと制約された完了アクションを提供しますが、エージェントのナビゲーションツールを置き換えるものではありません。どちらの連携も、同じブラウザーセッションを参照する必要があります。

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 を借用します。ブラウザーの作成や終了は行いません。人間による完了は再開を促すシグナルであり、成功の証明ではありません。ハンドオフ ID はタスク、既存のタブ／セッション、ゲートの世代に紐付けられており、コントローラーはそれを一度だけ消費する前に、新しい証拠を引き続き要求します。

ブラウザプロバイダー

エージェント間での利用に推奨されるプロバイダーは、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、Playwright-over-CDP、browser-use、およびオプションの Jet Browser 管理型／スタンドアロン型アダプターを実装しています。Jet Browser は明示的に選択する必要があり、デフォルトの経路ではインストールも起動もされません。設定例とプロバイダーの境界については、アーキテクチャおよびケースに記載されています。

browser-use とローカル OCR

Python アダプターはまだ PyPI に公開されていないため、バージョン指定なしの pip install rea-captcha は機能しません。固定されたホイールは v0.3.1 タグからビルドされ、GitHub Actions でスモークテストされており、対応するリリースに添付されています。

エージェントによる解決では、rea-captcha の Playwright/CDP セッションを、browser-use が使用している既存のブラウザーと同じブラウザーに接続してください。MCP のライフサイクルはブロックを検出し、許可された操作を実行して結果を検証した後、ブラウザーやタスクのコンテキストを置き換えることなく制御を返します。

インストールに記載されている Python プラグインは、互換性のある CDP 操作インターフェイスを公開していない browser-use 連携向けの、軽量な検出および手動復旧のフォールバックとして引き続き利用できます。

ローカルの ddddocr は、許可された正確なオリジン上にある単純な画像／テキスト形式のチャレンジにのみ使用できる、オプションのプリミティブです。allowLocalImageText と authorizedOrigins の両方が設定されていない限り無効です。モデルの重みは再配布されず、OCR の予測結果は信頼できない証拠として扱われます。

実装済みの機能

• reCAPTCHA、hCaptcha、Turnstile、GeeTest、DataDome、PerimeterX、AWS WAF、画像／テキスト入力、および汎用の認証ページに対する証拠検出。
• タイムアウトの上限、キャンセル、および新たな証拠に基づく再開確認を備えた、決定論的な状態。
• 6 つの 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で行ってください。リアルタイムでのチャットには、MASAKA Discordに参加し、専用の#rea-captcha チャンネルをご利用ください。再現可能なバグはGitHub Issuesで報告し、脆弱性については非公開のセキュリティポリシーに従ってください。ブラウザープロファイル、Cookie、チャレンジトークン、API キー、非公開ページの証拠を投稿しないでください。

対象範囲と免責事項

rea-captcha は、自らが所有するワークフロー、または明示的に許可されたワークフローを対象としています。プロバイダーの自動化を受け入れるのは、アダプターがベンダーの文書で定められた非本番環境用のテストキーを確認した場合に限られます。本番環境における対話型の保護を回避することはありません。商用ソルバー API、認証情報の転送、ステルス性の主張、および第三者の本番環境におけるチャレンジの自動解決は対象外です。

morluto/reaに着想を得ています。

ライセンス

コアコードと連携機能は MIT ライセンスで提供されます。オプションの依存関係とモデル成果物には、それぞれ独自の利用条件が適用されます。第三者向け通知およびモデルライセンスをご覧ください。