介绍
# Browser Ladder 🪜
仅在需要时从免费方案升级到付费方案。
## 快速开始
安装后运行设置脚本： ```bash ./skills/browser-ladder/scripts/setup.sh ```
或者手动添加到你的 `.env` 文件中： ```bash # Optional - only needed for Rungs 3-4 BROWSERCAT_API_KEY=your-key # Free: https://browsercat.com BROWSERLESS_TOKEN=your-token # Paid: https://browserless.io ```
## 阶梯说明
``` ┌─────────────────────────────────────────────┐ │ 🪜 Rung 4: Browserless.io (Cloud Paid) │ │ • CAPTCHA solving, bot detection bypass │ │ • Cost: $10+/mo │ │ • Requires: BROWSERLESS_TOKEN │ ├─────────────────────────────────────────────┤ │ 🪜 Rung 3: BrowserCat (Cloud Free) │ │ • When local Docker fails │ │ • Cost: FREE (limited) │ │ • Requires: BROWSERCAT_API_KEY │ ├─────────────────────────────────────────────┤ │ 🪜 Rung 2: Playwright Docker (Local) │ │ • JavaScript rendering, screenshots │ │ • Cost: FREE (CPU only) │ │ • Requires: Docker installed │ ├─────────────────────────────────────────────┤ │ 🪜 Rung 1: web_fetch (No browser) │ │ • Static pages, APIs, simple HTML │ │ • Cost: FREE │ │ • Requires: Nothing │ └─────────────────────────────────────────────┘
Start at the bottom. Climb only when needed. ```
## 何时升级
| 场景 | 阶梯 | 原因 | |-----------|------|-----| | 静态 HTML、API | 1 | 不需要 JS | | React/Vue/SPA 应用 | 2 | JS 渲染 | | Docker 不可用 | 3 | 云端回退 | | CAPTCHA/Cloudflare | 4 | 需要绕过机器人检测 | | OAuth/MFA 流程 | 4 | 复杂认证 |
## 决策流程
``` Need to access a URL │ ▼ Static content? ──YES──▶ Rung 1 (web_fetch) │ NO ▼ JS rendering only? ──YES──▶ Rung 2 (Playwright Docker) │ NO │ │ Success? ──NO──▶ Rung 3 ▼ │ YES CAPTCHA/bot detection? ────────────────────▶ DONE │ YES ▼ Rung 4 (Browserless.io) ──▶ DONE ```
## 使用示例
### 阶梯 1：静态内容 ```javascript // Built into Clawdbot const content = await web_fetch("https://example.com"); ```
### 阶梯 2：JS 渲染页面 ```bash 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：云浏览器 ```javascript const { chromium } = require('playwright'); const browser = await chromium.connect('wss://api.browsercat.com/connect', { headers: { 'Api-Key': process.env.BROWSERCAT_API_KEY } }); ```
### 阶梯 4：CAPTCHA 绕过 ```javascript const { chromium } = require('playwright'); const browser = await chromium.connectOverCDP( `wss://production-sfo.browserless.io?token=${process.env.BROWSERLESS_TOKEN}` ); // CAPTCHA handled automatically ```
## 成本优化
1. **从低开始** — 始终先尝试阶梯 1 2. **缓存结果** — 避免不必要的重新获取 3. **批量请求** — 一个浏览器会话处理多个页面 4. **检查成功** — 仅在低阶梯失败时才升级
## 获取密钥
| 服务 | 成本 | 注册链接 | |---------|------|---------| | BrowserCat | 免费层级 | https://browsercat.com | | Browserless.io | $10+/月 | https://browserless.io |
两者均为可选 — 阶梯 1-2 无需任何 API 密钥即可工作。