brosdk-playwright

English | 简体中文

brosdk-playwright 是 BroSDK 指纹浏览器与 Playwright 自动化的一键式集成方案。

BroSDK 负责"造环境"（指纹 / 代理 / 会话持久化），Playwright 负责"干活"（页面自动化），两者通过 CDP（Chrome DevTools Protocol）桥接。

只需把 import 路径从 playwright.sync_api 换成 brosdk_playwright，即可在不改变任何 Playwright 使用习惯的前提下，获得多版本指纹内核、独立代理 IP、Cookie/Storage 会话持久化能力。

import brosdk_playwright as bp
bp.configure(api_key="your-api-key", work_dir="./.brosdk")

from brosdk_playwright import sync_playwright   # 与原生签名完全一致

with sync_playwright() as p:
    browser = p.chromium.launch(env={           # per-browser 环境配置
        "env_id": "2070365861541056512",   # 复用已有环境，自动恢复登录态
        "kernel_version": "134",
        "proxy": "socks5://user:pass@host:1080",
    })
    page = browser.new_page()
    page.goto("https://example.com")
    browser.close()                              # 断开 CDP + 关闭浏览器（自动持久化 cookie）

bp.shutdown()

核心能力

• 零切换成本：sync_playwright() 与 Playwright 官方签名完全一致；所有 Playwright API（new_page/goto/click/screenshot/…）原样可用。
• 指纹环境管理：自动创建/复用 BroSDK 浏览器环境（独立指纹、独立代理）。
• 会话持久化：通过 env_id 复用已有环境，同一环境自动恢复上次的 Cookie/Storage/登录态。
• CDP 自动桥接：内部把 BroSDK 异步启动事件（browser-open-success）桥接成同步的 launch()，自动获取 CDP 端口并连接 Playwright。
• 多环境并发：每个环境自动分配独立 CDP 端口，规避端口冲突。
• 混合用法：p.chromium.launch()（无 env）走原生 Playwright；p.firefox/p.webkit 透传给原生 Playwright。

工作原理

用户代码 (Playwright API, 不变)
        │
        ▼
brosdk-playwright 包装层
  ┌─────────────────────────────────────────┐
  │ _BroBrowserType.launch(env=...)         │
  │   1. resolve_env  → 创建/复用环境        │
  │   2. launch_browser → sdk.browser_open  │
  │      (异步事件 20111 → 同步等待 CDP 端口) │
  │   3. connect_over_cdp → Playwright 连接  │
  └─────────────────────────────────────────┘
        │
        ▼
BroSDK 原生 SDK (brosdk.dll/.dylib/.so)
  指纹内核 · 代理 · Cookie/Storage 持久化

关键技术点：sdk_browser_open 是异步的——CDP 端口不在返回值里，而是在事件回调 eventId=20111（browser-open-success）的 data.remoteDebuggingPort 字段中送达。本包用 threading.Event 把这个异步事件桥接成同步的 launch()，这是本项目的核心价值（BroSDK 官方各语言 Demo 都只是 sleep 等待，从未提取过该端口）。

安装

pip install brosdk-playwright

从源码安装：

git clone https://github.com/browsersdk/brosdk-playwright-python.git
cd brosdk-playwright-python
pip install .

还需要：

Playwright 浏览器二进制仅在 不走 BroSDK（launch() 不传 env，或用 firefox/webkit）时才需要 playwright install；走 BroSDK 时浏览器内核由 BroSDK 管理。

原生库自动下载

brosdk PyPI 包是纯 Python 包，不附带原生动态库。brosdk-playwright 在以下情况会自动从 GitHub Releases 下载并解压当前平台的动态库到工作目录的 libs/ 下：

• 未指定 lib_path，且本地（brosdk 包目录或工作目录）找不到动态库时；
• 默认开启，无需任何配置。

如需关闭自动下载（例如离线环境），传入 auto_download=False，并手动通过 lib_path= 指定已下载的库路径：

bp.configure(api_key="...", lib_path="/path/to/brosdk.dll", auto_download=False)

也可指定下载特定版本：bp.configure(api_key="...", lib_version="1.0.0.5")。

快速开始

1. 配置 SDK（进程级，只需一次）

import brosdk_playwright as bp

bp.configure(
    api_key="your-api-key",     # 或设置环境变量 BROSDK_API_KEY
    work_dir="./.brosdk",       # SDK 工作目录
    # lib_path="...",           # 可选：指定动态库路径（缺省时自动查找/下载）
    # auto_download=True,       # 可选：找不到库时自动从 GitHub Releases 下载（默认开启）
    # lib_version="1.0.1.1",    # 可选：指定下载的库版本（默认 latest）
    # stealth=True,             # 可选：反检测模式（见下文），默认 False
    # port=0,                   # 可选：0=自动分配端口（默认）
    # customer_id="default",    # 可选
)

反检测模式（Stealth）

BroSDK 已经管理指纹和 Chromium 启动参数（如 --disable-blink-features=AutomationControlled）， 但 Playwright 通过 CDP 连接时仍会暴露自动化特征（Runtime.enable / Console.enable 泄漏等）。

开启 stealth=True 后，CDP 连接客户端从 Playwright 切换为 patchright （undetected playwright fork），在 BroSDK 管理的浏览器之上叠加 driver 级反检测补丁， 可过 Cloudflare / Datadome / Akamai / CreepJS / Sannysoft 等检测。

bp.configure(api_key="your-api-key", stealth=True)

需先安装可选依赖：

pip install brosdk-playwright[stealth]

也可用环境变量 BROSDK_STEALTH=1 开启。注意 patchright 仅支持 Chromium 内核 （与本项目的 BroSDK 流程一致，firefox/webkit 透传不受影响）。

也支持纯环境变量配置（无需 configure）：

export BROSDK_API_KEY=your-api-key
export BROSDK_WORK_DIR=./.brosdk

2. 像 Playwright 一样写代码

from brosdk_playwright import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(env={"kernel_version": "134"})
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

运行 Demo

python examples/demo.py --api-key YOUR_API_KEY            # 交互式
python examples/demo.py --quick --api-key YOUR_API_KEY    # 快速演示

env 配置参考

p.chromium.launch(env={...}) 的 env 字典支持以下字段：

会话复用：记住 browser.brosdk_env_id，下次 launch(env={"env_id": ...}) 传入即可—— BroSDK 环境本身持久化 cookie/storage，同一 envId 再次启动自动恢复登录态。 省略 env_id 时创建新环境。

API 概览

模块级

browser 增强字段

走 BroSDK 启动的 browser 对象额外暴露：

适用场景

1. 多账号运营 SaaS：每个账号用独立 env_id 隔离环境，独立指纹/代理/cookie。
2. 自动化测试：现有 Playwright 测试套件零改动获得指纹和代理能力。
3. AI Agent 浏览器任务：在 LangChain/AutoGPT 工具链中为 Playwright 注入指纹环境。
4. ERP/CRM 集成：企业 Playwright 脚本复用，带会话持久化。

项目结构

brosdk-playwright-python/
├── brosdk_playwright/
│   ├── __init__.py        # 公共 API 导出
│   ├── _config.py         # 全局配置 + 认证（configure / get_config）
│   ├── _sdk.py            # 环境管理 + 异步事件→同步 launch/close 桥接
│   ├── _downloader.py     # 原生库自动下载（GitHub Releases）
│   ├── _playwright.py     # Playwright API 包装层
│   └── sync_api.py        # sync_playwright() 上下文管理器
├── examples/              # 使用示例 + 交互式 CLI Demo (demo.py)
├── config/               # E2E 测试配置（e2e.config.json，含密钥，已 gitignore）
├── tests/                # 单元测试 + e2e/ 子目录（无需真实 SDK/浏览器）
└── pyproject.toml

开发

pip install -e ".[dev]"
pytest

测试不依赖真实 SDK、浏览器或 API Key——通过伪 BrosdkManager 注入验证核心的异步→同步桥接逻辑。

与 BroSDK 生态的关系

License

MIT