名称： browser-ladder
版本： 1.0.0
描述： 浏览器阶梯 — 从免费开始，仅在需要时升级。L1 (fetch) → L2 (本地 Playwright) → L3 (BrowserCat) → L4 (Browserless.io，用于验证码/机器人绕过)。
元数据：
clawdbot:
emoji: "🪜"
requires:
bins:
- node
- docker
env:
- name: BROWSERCAT_API_KEY
description: BrowserCat API 密钥 (免费套餐) - 前往 https://browsercat.com 获取
required: false
- name: BROWSERLESS_TOKEN
description: Browserless.io 令牌 ($10/月) - 前往 https://browserless.io 获取
required: false

浏览器阶梯 🪜

从免费开始，仅在需要时付费升级。

快速设置

安装后运行设置脚本：

./skills/browser-ladder/scripts/setup.sh

或手动添加到你的 .env 文件：

# 可选 - 仅在第 3-4 级阶梯时需要
BROWSERCAT_API_KEY=你的密钥    # 免费：https://browsercat.com
BROWSERLESS_TOKEN=你的令牌     # 付费：https://browserless.io

阶梯结构

┌─────────────────────────────────────────────┐
│  🪜 第 4 级：Browserless.io (云端付费)       │
│  • 验证码解决，机器人检测绕过                │
│  • 成本：$10+/月                            │
│  • 要求：BROWSERLESS_TOKEN                  │
├─────────────────────────────────────────────┤
│  🪜 第 3 级：BrowserCat (云端免费)           │
│  • 当本地 Docker 失败时使用                  │
│  • 成本：免费 (有限制)                       │
│  • 要求：BROWSERCAT_API_KEY                 │
├─────────────────────────────────────────────┤
│  🪜 第 2 级：Playwright Docker (本地)        │
│  • JavaScript 渲染，截图                     │
│  • 成本：免费 (仅消耗 CPU)                   │
│  • 要求：已安装 Docker                       │
├─────────────────────────────────────────────┤
│  🪜 第 1 级：web_fetch (无浏览器)            │
│  • 静态页面、API、简单 HTML                  │
│  • 成本：免费                               │
│  • 要求：无                                 │
└─────────────────────────────────────────────┘

从底层开始。仅在需要时向上爬升。

何时升级

决策流程

需要访问一个 URL
         │
         ▼
    是静态内容？ ──是──▶ 第 1 级 (web_fetch)
         │ 否
         ▼
    仅需 JS 渲染？ ──是──▶ 第 2 级 (Playwright Docker)
         │ 否                        │
         │                    成功？ ──否──▶ 第 3 级
         ▼                           │ 是
    有验证码/机器人检测？ ────────────────────▶ 完成
         │ 是
         ▼
    第 4 级 (Browserless.io) ──▶ 完成

使用示例

第 1 级：静态内容

// 已内置在 Clawdbot 中
const content = await web_fetch("https://example.com");

第 2 级：需要 JS 渲染的页面

docker run --rm -v /tmp:/output mcr.microsoft.com/playwright:v1.58.0-jammy \
  npx playwright screenshot https://spa-app.com /output/shot.png

第 3 级：云端浏览器 (BrowserCat)

const { chromium } = require('playwright');
const browser = await chromium.connect('wss://api.browsercat.com/connect', {
  headers: { 'Api-Key': process.env.BROWSERCAT_API_KEY }
});

第 4 级：验证码绕过 (Browserless)

const { chromium } = require('playwright');
const browser = await chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_TOKEN}`
);
// 验证码会自动处理

成本优化

1. 从低处开始 — 始终先尝试第 1 级
2. 缓存结果 — 避免不必要的重复抓取
3. 批量请求 — 一个浏览器会话处理多个页面
4. 检查成功 — 仅在低级别失败时才升级

获取密钥

两者均为可选 — 第 1-2 级无需任何 API 密钥即可工作。