humanize-automation

自動化の人間らしい動作

瞬時のプログラムによる操作を、人間らしいマウスの動き、キーボード入力、スクロールパターンに置き換えます。Playwright の API をクラスレベルでパッチし、page.click()、page.type()、page.fill()、および Locator のメソッドを、ベジェ曲線に沿ったマウスの軌跡、タイプミスを含む1文字ずつの入力、複数段階のスクロール加速で自動的に置き換えます。1つのフラグ（humanize=True）ですべての動作パッチを有効にできます。コードを変更する必要はありません。

使用する場面

• 対象サイトで、行動に基づくボット検出（マウス軌跡の分析、タイピング速度のプロファイリング）が使われている場合。
• ブラウザーのフィンガープリントが正しいにもかかわらず、reCAPTCHA v3 のスコアが低い（<0.3）場合。
• フォーム送信が速すぎると、対象サイトがタイムアウトしたり、チャレンジを表示したりする場合。
• ログインやアカウント作成で、実際のユーザーのブラウジングセッションをシミュレートする必要がある場合。
• 対象サイトで requestAnimationFrame に基づくマウス移動の追跡が使われている場合。

前提条件

• python3 がインストールされた terminal。
• cloakbrowser がインストールされていること：pip install cloakbrowser。
• または、カスタムパッチを適用したスタンドアロンの Playwright：humanize モジュールから patch_page をインポートします。

クイックスタート

from cloakbrowser import launch

browser = launch(humanize=True)
page = browser.new_page()
page.goto("https://target.com/login")

# All interactions are automatically humanized
page.locator("#email").fill("[email protected]")     # per-character timing
page.locator("#password").fill("password123")       # with thinking pauses
page.locator("button[type=submit]").click()         # Bézier curve movement
browser.close()

手順

フェーズ1 — デフォルトの人間らしい動作

1つのフラグですべての動作パッチを有効にできます。

browser = launch(
    headless=False,
    proxy="http://residential-proxy:port",
    geoip=True,
    humanize=True,  # enables all behavioral patches
)
page = browser.new_page()
page.goto("https://target.com")

# All Playwright interactions are replaced with human-like equivalents
page.locator("input[name='search']").fill("restricted query")
page.locator("button[type='submit']").click()

フェーズ2 — 慎重モード（低速で、より慎重な操作）

操作速度がプロファイリングされるサイト向けです。

browser = launch(
    humanize=True,
    human_preset="careful",  # slower typing, more idle pauses
)

慎重プリセットによる変更点：タイピングは100±50ms（70±40msから変更）、クリック時の照準は80～180ms（60～140msから変更）、idle_between_actions が有効になり、0.4～1.0秒の待機が挿入されます。

フェーズ3 — カスタム動作プロファイル

サイトに合わせて個別のパラメーターを上書きします。

from cloakbrowser import HumanConfig

custom = HumanConfig(
    typing_delay=150,
    typing_delay_spread=60,
    typing_pause_chance=0.15,
    mistype_chance=0.03,
    mouse_wobble_max=2.0,
    click_aim_delay_input=(100, 200),
    scroll_delta_base=(60, 100),
    idle_between_actions=True,
    idle_between_duration=(0.5, 1.5),
)

browser = launch(humanize=True, human_config=custom)

フェーズ4 — 呼び出しごとの上書き

個々の操作の動作を上書きします。

# Slow, careful typing for password field
page.locator("#password").fill("secret", human_config={"typing_delay": 200})

# Fast click (bypass aim delay)
page.locator("#submit").click(human_config={"click_aim_delay_input": (0, 0)})

フェーズ5 — CloakBrowser を使わない単独の人間らしい動作

既存の Playwright ページにパッチを適用します。

from playwright.sync_api import sync_playwright
from cloakbrowser.human import patch_page, resolve_config

pw = sync_playwright().start()
browser = pw.chromium.launch()
page = browser.new_page()

# Apply humanization to an existing page
config = resolve_config("default")
patch_page(page, config)

# All interactions now humanized
page.locator("#email").fill("[email protected]")

動作パラメーターのリファレンス

マウスの動き

パラメーター	デフォルト	効果
mouse_steps_divisor	8	滑らかさを制御します（値が小さいほど滑らかになり、ステップ数が増えます）
mouse_min_steps	25	1回の移動における最小ステップ数
mouse_max_steps	80	1回の移動における最大ステップ数
mouse_wobble_max	1.5 px	横方向の正弦波状の揺れの振幅
mouse_overshoot_chance	0.15	目標を通り過ぎる確率
mouse_overshoot_px	(3, 6) px	通り過ぎる距離

移動アルゴリズム： ランダムな垂直方向の制御点を2つ使った3次ベジェ曲線 → イーズイン・イーズアウトの3次イージング → 正弦波状の揺れ → 15%の確率で目標を通り過ぎてから修正します。

キーボード入力

パラメーター	デフォルト	効果
typing_delay	70 ms	1文字ごとの平均入力間隔
typing_delay_spread	40 ms	入力間隔のランダムなばらつき
typing_pause_chance	0.10	1文字ごとに考えるための間を置く確率
typing_pause_range	(400, 1000) ms	考えるために間を置く時間
mistype_chance	0.02	1文字ごとのタイプミスの確率
mistype_delay_notice	(100, 300) ms	タイプミスに気付くまでの時間
mistype_delay_correct	(50, 150) ms	タイプミスを修正する時間
field_switch_delay	(800, 1500) ms	フォームフィールドを切り替える際の遅延

入力アルゴリズム： ランダムなばらつきを加えた1文字ごとの入力間隔 → 10%の確率で間を置く → 2%の確率でタイプミス（近くのキーを入力 → 気付く → バックスペース → 再入力） → CDP の Input.dispatchKeyEvent を使って Shift キーが必要な記号を入力し、isTrusted=true にします。

スクロール

パラメーター	デフォルト	効果
scroll_delta_base	(80, 130) px	1ステップあたりのスクロール距離
scroll_accel_steps	(2, 3)	加速段階のステップ数
scroll_decel_steps	(2, 3)	減速段階のステップ数
scroll_overshoot_chance	0.10	目標を通り過ぎる確率
scroll_overshoot_px	(50, 150) px	通り過ぎる距離
scroll_target_zone	(0.20, 0.80)	ビューポート内の目標範囲
scroll_settle_delay	(300, 600) ms	目標に到達した後の遅延

スクロールアルゴリズム： 加速（2～3ステップ、80～100px）→ 巡航（80～130px、8～20ms間隔で20～40pxのホイール操作を連続実行）→ 減速（2～3ステップ、60～90px）→ 10%の確率で目標を通り過ぎてから修正します。

クリック動作

パラメーター	デフォルト	効果
click_aim_delay_input	(60, 140) ms	入力要素をクリックする前の遅延
click_aim_delay_button	(80, 200) ms	ボタンをクリックする前の遅延
click_hold_input	(40, 100) ms	入力要素を押し続ける時間
click_hold_button	(60, 150) ms	ボタンを押し続ける時間
click_input_x_range	(0.05, 0.30)	入力要素内のクリック位置（左側）

アイドル動作

パラメーター	デフォルト	効果
idle_between_actions	False	アクション間の微細な動きを有効にします
idle_between_duration	(0.3, 0.8) sec	アクション間のアイドル時間
idle_drift_px	3 px	アイドル中のカーソルのランダムなドリフト
idle_pause_range	(300, 1000) ms	アイドル時の休止時間
initial_cursor_x	(400, 700) px	カーソルの開始 X 座標（アドレスバー領域）
initial_cursor_y	(45, 60) px	カーソルの開始 Y 座標（アドレスバー領域）

プリセット

プリセット	入力速度	目標までの遅延	アクション間のアイドル	用途
default	70±40ms	60-140ms	なし	通常の人間の速度
careful	100±50ms	80-180ms	あり（0.4-1.0s）	より遅く、慎重な操作

注意点

• 人間らしい操作にはラッパーが必要です。 ラッパーを使わずに CDP 経由で接続すると、人間らしさが失われます。生の CDP で機能するのはフィンガープリントのパッチのみです。
• Playwright の ElementHandle オブジェクトを使うと、人間らしい操作がバイパスされます。 page.click(selector) または page.locator(selector).* を使用し、query_selector() のハンドルは避けてください。
• humanize を指定した page.fill() は、既存の内容を消去してから文字を一つずつ入力します。 これは意図した動作ですが、生の fill() より時間がかかります。
• 入力速度のプロファイリングが行われます。 一部のサイトでは、キー入力間のミリ秒数を測定します。不審な対象には、careful プリセットを使うか、typing_delay を増やしてください。
• 要素までのスクロールは自動です。 クリックまたはホバー時には、操作前に人間らしいスクロールで要素が表示範囲内に移動します。
• ステルスな DOM クエリには CDP の分離ワールドを使用します。 これにより、メインの JavaScript コンテキストでのモンキーパッチ検出を防ぎます。

検証

1. https://deviceandbrowserinfo.com に対してテストします。動作に関するシグナルが 24/24 個合格と表示されるはずです。
2. humanize=True を指定した場合と指定しない場合の reCAPTCHA v3 スコアを比較します。humanize を指定すると、スコアが 0.2-0.4 上がるはずです。
3. ブラウザーの DevTools の Performance タブでセッションを記録します。マウスイベントに、瞬間的なジャンプではなく、現実的なタイミングの推移が表示されるはずです。
4. イベントリスナーで Input.dispatchKeyEvent イベントの isTrusted: true を確認します。

関連スキル

• stealth-browser-launch — C++ によるフィンガープリント変更を適用した Chromium バイナリを起動します。
• tls-fingerprint-impersonation — HTTP レベルでの回避に使う TLS/JA4 フィンガープリントの偽装。