Back to Details

browser-probe

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Browser Probe

浏览器探测

Detect CDN bot protection blocking headless Chrome and produce a browser recipe for downstream 
playwright-cli
consumers. Node 22+ required. No npm dependencies.
检测CDN机器人防护对无头Chrome的封锁情况，并为下游
playwright-cli
使用者生成浏览器配置文件。需要Node 22及以上版本，无npm依赖。

When to Use

使用时机

Run before any 
playwright-cli
interaction with an untested domain, or when a downstream script reports a blocked/empty page (403, "access denied", "captcha").
在与未测试的域名进行任何
playwright-cli
交互之前运行，或者当下游脚本报告页面被封锁/空白（403、“访问被拒绝”、“验证码”）时运行。

Script Location

脚本位置

bash
if [[ -n "${CLAUDE_SKILL_DIR:-}" ]]; then
  PROBE_DIR="${CLAUDE_SKILL_DIR}/scripts"
else
  PROBE_DIR="$(dirname "$(command -v browser-probe.js 2>/dev/null || \
    find ~/.claude -path "*/browser-probe/scripts/browser-probe.js" \
    -type f 2>/dev/null | head -1)")"
fi
bash
if [[ -n "${CLAUDE_SKILL_DIR:-}" ]]; then
  PROBE_DIR="${CLAUDE_SKILL_DIR}/scripts"
else
  PROBE_DIR="$(dirname "$(command -v browser-probe.js 2>/dev/null || \
    find ~/.claude -path "*/browser-probe/scripts/browser-probe.js" \
    -type f 2>/dev/null | head -1)")"
fi

Workflow

工作流程

Step 1 — Run the probe

步骤1 — 运行探测

bash
node "$PROBE_DIR/browser-probe.js" "$URL" "$OUTPUT_DIR"
The script tries up to 5 browser configurations, stopping at the first success:
  1. default — headless Chromium (baseline)
  2. stealth — headless Chromium + JS stealth init script (patches 
    navigator.webdriver
    , plugins, languages)
  3. stealth-ua — headless Chromium + JS stealth + User-Agent override (removes 
    HeadlessChrome
    from HTTP UA header via 
    --user-agent
    launch arg)
  4. chrome — system Chrome (
    --browser=chrome
    ) + JS stealth + UA override (fixes TLS fingerprint detection)
  5. persistent — system Chrome + JS stealth + UA override + persistent profile (cookie/session challenges)
Output: 
$OUTPUT_DIR/probe-report.json
bash
node "$PROBE_DIR/browser-probe.js" "$URL" "$OUTPUT_DIR"
脚本会尝试最多5种浏览器配置，在首次成功时停止：
  1. default — 无头Chromium（基准测试）
  2. stealth — 无头Chromium + JS隐身初始化脚本（修补
    navigator.webdriver
    、插件、语言信息）
  3. stealth-ua — 无头Chromium + JS隐身脚本 + 用户代理覆盖（通过
    --user-agent
    启动参数从HTTP UA头中移除
    HeadlessChrome
    标识）
  4. chrome — 系统Chrome（
    --browser=chrome
    ） + JS隐身脚本 + 用户代理覆盖（修复TLS指纹检测）
  5. persistent — 系统Chrome + JS隐身脚本 + 用户代理覆盖 + 持久化配置文件（应对Cookie/会话验证挑战）
输出：
$OUTPUT_DIR/probe-report.json

Step 2 — Read the report

步骤2 — 读取报告

Load 
probe-report.json
. Check 
firstSuccess
:
  • If non-null: a configuration worked. Proceed to Step 3.
  • If null: all configurations failed. Skip to Step 5.
加载
probe-report.json
，查看
firstSuccess
字段：
  • 如果非空：说明某一配置生效，继续步骤3。
  • 如果为空：所有配置均失败，跳至步骤5。

Step 3 — Interpret results

步骤3 — 解读结果

Match 
detectedSignals
against the Provider Signature Table in 
references/stealth-config.md
to confirm why blocking occurred and validate that 
firstSuccess
is the minimum sufficient config.
将
detectedSignals
与
references/stealth-config.md
中的供应商特征表进行匹配，确认封锁原因，并验证
firstSuccess
是否为满足需求的最低配置。

Step 4 — Generate recipe

步骤4 — 生成配置文件

Write 
browser-recipe.json
to 
$OUTPUT_DIR
:
json
{
  "url": "<probed URL>",
  "generated": "<ISO timestamp>",
  "cliConfig": {
    "browser": {
      "browserName": "chromium",
      "launchOptions": { "channel": "<from firstSuccess step>" }
    }
  },
  "stealthInitScript": "<full script from stealth-config.md if stealth was needed>",
  "notes": "<1-2 sentence explanation of what was detected and why this config>"
}
Config mapping from 
firstSuccess
:
firstSuccesschannelargsstealthInitScript
default
——null
stealth
——from reference
stealth-ua
—
--user-agent=<realistic UA>
from reference
chrome
chrome
--user-agent=<realistic UA>
from reference
persistent
chrome
--user-agent=<realistic UA>
from reference
If 
firstSuccess
is 
persistent
, add 
"persistent": true
to the recipe.
将
browser-recipe.json
写入
$OUTPUT_DIR
：
json
{
  "url": "<被探测的URL>",
  "generated": "<ISO时间戳>",
  "cliConfig": {
    "browser": {
      "browserName": "chromium",
      "launchOptions": { "channel": "<来自firstSuccess步骤的配置>" }
    }
  },
  "stealthInitScript": "<如果需要隐身脚本，取自stealth-config.md的完整脚本>",
  "notes": "<1-2句话说明检测到的内容及该配置的作用>"
}
从
firstSuccess
到配置的映射：
firstSuccesschannel参数stealthInitScript
default
——null
stealth
——取自参考文档
stealth-ua
—
--user-agent=<真实用户代理>
取自参考文档
chrome
chrome
--user-agent=<真实用户代理>
取自参考文档
persistent
chrome
--user-agent=<真实用户代理>
取自参考文档
如果
firstSuccess
为
persistent
，需在配置文件中添加
"persistent": true
。

Step 5 — Report results

步骤5 — 报告结果

If a configuration worked:
Browser probe complete for <url>.
  Working config: <firstSuccess>
  Detected: <detectedSignals or "no bot protection detected">
  Recipe: <path to browser-recipe.json>
If all configurations failed:
Browser probe failed for <url>. No headless configuration could load the page.
  Tried: default, stealth, stealth-ua, chrome, persistent
  Detected signals: <detectedSignals>

  Options:
  1. Use --headed flag for manual browser interaction
  2. Provide pre-captured data (DOM snapshot, screenshots) manually
  3. Check if the URL requires authentication or VPN access
Do NOT produce a recipe when all steps fail. Do NOT silently continue with a broken configuration.
若某一配置生效：
<url>的浏览器探测完成。
  生效配置：<firstSuccess>
  检测结果：<detectedSignals或“未检测到机器人防护”>
  配置文件：<browser-recipe.json的路径>
若所有配置均失败：
<url>的浏览器探测失败。没有任何无头配置能够加载页面。
  已尝试：default、stealth、stealth-ua、chrome、persistent
  检测到的特征：<detectedSignals>

  可选方案：
  1. 使用--headed标志进行手动浏览器交互
  2. 手动提供预捕获的数据（DOM快照、截图）
  3. 检查该URL是否需要身份验证或VPN访问
当所有步骤均失败时，请勿生成配置文件。请勿在配置失效的情况下静默继续执行。

How Consumers Use the Recipe

使用者如何使用配置文件

Pass 
--config=<path-to-cliConfig>
to 
playwright-cli open
. If the recipe has 
stealthInitScript
, add it to 
browser.initScript
in the config (not via 
eval
— eval is expression-only). If 
"persistent": true
, also pass 
--persistent
. Run 
playwright-cli --help
for the full command reference.
将
--config=<cliConfig的路径>
传递给
playwright-cli open
。如果配置文件包含
stealthInitScript
，需将其添加到配置的
browser.initScript
中（不可通过
eval
添加——eval仅支持表达式）。如果包含
"persistent": true
，还需传递
--persistent
参数。运行
playwright-cli --help
查看完整命令参考。