humanize-automation

Humanize Automation

将即时的程序化交互替换为类似人类的鼠标移动、键盘输入和滚动模式。在类级别修补 Playwright 的 API — page.click()、page.type()、page.fill() 和 Locator 方法会自动替换为贝塞尔曲线鼠标轨迹、逐字符输入（包含错字）和多阶段滚动加速。只需一个标志（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 — 默认拟人化

一个标志即可启用所有行为修补：

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.0s。

阶段 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	每次移动的最小步数
mouse_max_steps	80	每次移动的最大步数
mouse_wobble_max	1.5 px	横向正弦摆动幅度
mouse_overshoot_chance	0.15	超过目标的概率
mouse_overshoot_px	(3, 6) px	超出距离

移动算法： 使用 2 个随机垂直控制点绘制三次贝塞尔曲线 → 缓入缓出三次缓动 → 正弦摆动 → 15% 概率超过目标并进行修正。

键盘输入

参数	默认值	效果
typing_delay	70 ms	每个字符的平均延迟
typing_delay_spread	40 ms	延迟的随机浮动范围
typing_pause_chance	0.10	每个字符触发思考停顿的概率
typing_pause_range	(400, 1000) ms	思考停顿时长
mistype_chance	0.02	每个字符输错的概率
mistype_delay_notice	(100, 300) ms	发现错字前的时间
mistype_delay_correct	(50, 150) ms	更正错字所需的时间
field_switch_delay	(800, 1500) ms	在表单字段之间切换时的延迟

输入算法： 每个字符的延迟带随机浮动 → 10% 概率暂停 → 2% 概率输错（按下邻近按键 → 发现错误 → 退格 → 重新输入）→ 通过 CDP Input.dispatchKeyEvent 输入 Shift 符号，以确保 isTrusted=true。

滚动

参数	默认值	效果
scroll_delta_base	(80, 130) px	每步滚动距离
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，每次滚动分成 20-40px 的滚轮小段，间隔 8-20ms）→ 减速（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() 句柄。
• 启用拟人化后，page.fill() 会清除现有内容并逐字符输入。 这是有意设计的，但比原始 fill() 更慢。
• 存在输入速度分析。 某些网站会测量按键间隔的毫秒数。对可疑目标使用 careful 预设或增大 typing_delay。
• 自动滚动至元素。 点击或悬停时，元素会通过拟人化滚动滚动到视野内，然后再进行交互。
• 隐身 DOM 查询使用 CDP 隔离世界。 这可防止在主 JavaScript 上下文中被检测到猴子补丁。

验证

1. 在 https://deviceandbrowserinfo.com 上测试——应显示 24/24 项行为信号通过。
2. 比较启用和未启用 humanize=True 时的 reCAPTCHA v3 评分——启用拟人化应使评分提高 0.2-0.4。
3. 使用浏览器 DevTools 的 Performance 选项卡录制会话——鼠标事件应呈现真实的计时曲线，而非瞬间跳变。
4. 验证事件监听器中 Input.dispatchKeyEvent 事件的 isTrusted: true。

相关技能

• stealth-browser-launch — 使用 C++ 指纹修改启动打过补丁的 Chromium 二进制文件。
• tls-fingerprint-impersonation — 用于 HTTP 层规避的 TLS/JA4 指纹伪装。