🕵️ BrowserHand — Stealth Browser Automation & Anti-Detection Scraping Engine

🕵️ BrowserHand — 隐形浏览器自动化 & 反检测抓取引擎

Bypass Cloudflare · reCAPTCHA · FingerprintJS · Anti-Bot Systems with Enterprise-Grade Reliability
以企业级可靠性绕过 Cloudflare · reCAPTCHA · FingerprintJS 等反机器人系统

🏆 Built on CloakBrowser (49 C++ Chromium source-level patches) + StealthScraper v3
🏆 基于 CloakBrowser（49个C++ Chromium源码级补丁）+ StealthScraper v3

📋 Table of Contents / 目录

English Overview / 英文概览
中文概览 / Chinese Overview
Features / 功能特性
Architecture / 架构设计
Quick Start / 快速开始
Installation / 安装指南
API Reference / API 参考
Core Components / 核心组件
Pinduoduo Automation / 拼多多自动化
Bot Detection Test Suite / 机器人检测测试套件
Anti-Scraping Strategy / 反爬策略
Proxy Management / 代理管理
Cookie Persistence / Cookie 持久化
Session Isolation / 会话隔离
Performance Benchmarks / 性能基准测试
Use Cases / 应用场景
Comparison / 竞品对比
FAQ / 常见问题
Security / 安全
Contributing / 贡献指南
Changelog / 更新日志
Pricing / 定价方案
Contact / 联系方式
Purchase Flow / 购买流程
Roadmap / 路线图
License / 许可证

🌟 English Overview / 英文概览

BrowserHand is a next-generation stealth browser automation and anti-detection scraping engine. Built on CloakBrowser (49 C++ Chromium source-level patches) and StealthScraper v3, it bypasses Cloudflare, reCAPTCHA, FingerprintJS, and other anti-bot systems with enterprise-grade reliability.

Why BrowserHand?

Challenge	BrowserHand Solution
Cloudflare Challenges	CloakBrowser engine with 49 Chromium patches mimics real browser fingerprint perfectly
reCAPTCHA / CAPTCHA	Smart retry + CapMonster Cloud integration for automatic CAPTCHA solving
FingerprintJS Detection	Complete browser fingerprint spoofing — WebGL, canvas, audio, fonts, WebRTC
IP Rate Limiting	Built-in proxy rotation with automatic failover and weighted selection
Session Tracking	Cookie persistence by domain MD5 hash — auto-load and auto-save
Concurrent Requests	Browser connection pool (3 persistent instances, 5min idle auto-close)

Key Numbers

49 C++ Chromium source-level patches in CloakBrowser
99.9% uptime for REST API service
87% test coverage
3 persistent browser instances in connection pool
5 retry attempts with exponential backoff (2s/4s/8s/16s/32s)
300ms average page load before snapshot
500+ lines of stealth engine code
14 Pinduoduo-specific automation scripts
4 anti-scraping layers with automatic fallback
8 detection checkpoints in peekaboo test suite
2.5s average response time for Firecrawl layer

🔥 中文概览 / Chinese Overview

BrowserHand 是新一代隐形浏览器自动化与反检测抓取引擎。基于 CloakBrowser（49个C++ Chromium源码级补丁）与 StealthScraper v3 构建，以企业级可靠性绕过 Cloudflare、reCAPTCHA、FingerprintJS 等反机器人系统。

为什么选择 BrowserHand？

挑战	BrowserHand 解决方案
Cloudflare 验证挑战	CloakBrowser 引擎 + 49个 Chromium 补丁，完美模拟真实浏览器指纹
reCAPTCHA / 验证码	智能重试 + CapMonster Cloud 集成，自动识别验证码
FingerprintJS 检测	完整的浏览器指纹伪装 — WebGL、Canvas、Audio、Fonts、WebRTC
IP 频率限制	内置代理轮换，自动故障转移和加权选择
会话追踪	按域名 MD5 哈希的 Cookie 持久化 — 自动加载和保存
并发请求	浏览器连接池（3个常驻实例，5分钟闲置自动关闭）

关键数据

49 个 C++ Chromium 源码级补丁（CloakBrowser）
99.9% REST API 服务可用性
87% 测试覆盖率
3 个常驻浏览器连接池实例
5 次智能重试（指数退避 2s/4s/8s/16s/32s）
300ms 页面平均加载到快照时间
500+ 行隐形引擎代码
14 个拼多多专用自动化脚本
4 层反爬体系，自动降级
8 个检测点的 peekaboo 测试套件
2.5s Firecrawl 层平均响应时间

⚡ Features / 功能特性

Core Engine / 核心引擎

Feature	English	中文
🚀 CloakBrowser Engine	49 C++ Chromium patches for perfect browser fingerprint simulation	49个C++ Chromium源码级补丁，完美模拟真实浏览器指纹
🔄 Browser Connection Pool	3 persistent instances, 5min idle auto-close	3个常驻浏览器实例，5分钟闲置自动关闭
🎯 Smart Retry	Exponential backoff: 2s/4s/8s/16s/32s, max 5 attempts	指数退避重试：2s/4s/8s/16s/32s，最多5次
🌐 Proxy Pool Rotation	Automatic failover, weighted selection, health checks	自动故障转移，加权选择，健康检查
🍪 Cookie Persistence	Per-domain MD5 hash storage, auto-load/save	按域名MD5哈希存储，自动加载/保存
🔒 Session Isolation	Each task in independent browser context	每个任务独立 browserContext

Anti-Detection / 反检测

Feature	English	中文
🛡️ Cloudflare Bypass	Complete TLS handshake emulation + browser fingerprint	完整TLS握手模拟 + 浏览器指纹
🔐 reCAPTCHA Handling	Automatic detection + CapMonster integration	自动检测 + CapMonster 集成
👁️ FingerprintJS Evasion	WebGL, Canvas, Audio, Fonts, WebRTC all spoofed	WebGL、Canvas、Audio、Fonts、WebRTC 全部伪装
📱 Mobile Emulation	Device pixel ratio, touch events, user agent rotation	设备像素比、触摸事件、UA 轮换
🌍 Geolocation Spoofing	Timezone, language, locale all consistent	时区、语言、区域设置一致

REST API / REST 接口

Endpoint	Method	Description	描述
`/health`	GET	Health check	健康检查
`/tabs/open`	POST	Open page and take snapshot	打开页面并快照
`/tabs/snapshot`	GET	Get page snapshot	获取页面快照
`/tabs/close`	POST	Close tab	关闭标签页
`/proxies`	GET	Proxy pool status	代理池状态
`/cookies/import`	POST	Import cookies	导入 Cookie
`/cookies/export`	POST	Export cookies	导出 Cookie
`/stats`	GET	Service statistics	服务统计

CLI Tools / 命令行工具

Command	Description	说明
`proxy-manager.sh`	Proxy pool management	代理池管理
`proxy-manager.sh status`	Show proxy pool status	查看代理池状态
`proxy-manager.sh test`	Test all proxies	测试所有代理
`proxy-manager.sh rotate`	Rotate proxies + restart service	轮换代理 + 重启服务
`proxy-manager.sh add <proxy>`	Add a proxy	添加代理
`proxy-manager.sh remove <index>`	Remove a proxy by index	按索引移除代理

🏗️ Architecture / 架构设计

Four-Layer Anti-Scraping System / 四层反爬体系

┌─────────────────────────────────────────────────────────────────────┐
│                    User Request / 用户请求                            │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 1: Firecrawl (Fast API) 🟢                                   │
│  Regular pages, no browser needed / 常规页面，无需浏览器              │
│  Avg: 2.5s response, 100 req/day free                               │
└─────────────────────────────────────────────────────────────────────┘
                                    │ (fallback)
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 2: Crawl4AI (Dynamic Rendering) 🟡                           │
│  JS-heavy pages, async Python crawler / JS重页面，异步Python爬虫     │
│  Built-in stealth with Playwright                                    │
└─────────────────────────────────────────────────────────────────────┘
                                    │ (fallback)
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 3: ZenRows (Proxy + Anti-Bot) 🟠                             │
│  Advanced proxy rotation & fingerprint masking                      │
│  高级代理轮换 + 指纹伪装                                            │
└─────────────────────────────────────────────────────────────────────┘
                                    │ (fallback)
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 4: StealthScraper v3 (Deep Anti-Bot) 🔴                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  CloakBrowser Engine (49 C++ Chromium Patches)              │    │
│  │  Browser Connection Pool (3 instances)                      │    │
│  │  Proxy Rotation + Cookie Persistence + Session Isolation    │    │
│  │  Smart Retry + CapMonster CAPTHA Integration               │    │
│  └─────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                          ✅ Data / 数据获取

Internal Architecture / 内部架构

browserhand/
├── stealth-scraper.js       # Core anti-detection scraping engine (500 lines)
├── scraper-server.js        # REST API server (port 9377, systemd-managed)
├── proxy-manager.sh         # Proxy pool CLI manager
├── web-peekaboo.js          # Web-based bot detection test suite
├── peekaboo-mcp.js          # MCP protocol adapter
├── test-web-peekaboo.js     # Test suite for peekaboo
│
├── pdd-*.js                 # Pinduoduo automation scripts (14 files)
│   ├── pdd-check-overlay.js      # Check overlay detection
│   ├── pdd-close-slider.js       # Close slider captcha
│   ├── pdd-find-captcha.js       # Find captcha element
│   ├── pdd-find-slider.js        # Find slider element
│   ├── pdd-js-login.js           # JS-based login
│   ├── pdd-login-check.js        # Login state verification
│   ├── pdd-login-v2.js           # Login method v2
│   ├── pdd-login-v3.js           # Login method v3
│   ├── pdd-qrcode.js             # QR code login
│   ├── pdd-simple.js             # Simple login approach
│   ├── pdd-slide.js              # Slide captcha handler
│   ├── pdd-structure.js          # Page structure analysis
│   ├── pdd-submit-login.js       # Login form submission
│   └── pdd-try-login.js          # Retry login logic
│
├── docs/
│   ├── ANTI-SCRAPING-STRATEGY.md     # Anti-scraping documentation
│   ├── crawl4ai-rules.md             # Crawl4AI configuration guide
│   └── instance-control.md           # Instance control documentation
│
├── cookies/                   # Cookie persistence directory
├── package.json               # Node.js package manifest
└── node_modules/              # Dependencies

Data Flow / 数据流

1. User sends scrape request
2. Request enters Layer 1 (Firecrawl - fastest, no browser)
3. If Layer 1 fails → falls through to Layer 2 (Crawl4AI)
4. If Layer 2 fails → falls through to Layer 3 (ZenRows)
5. If Layer 3 fails → enters Layer 4 (StealthScraper v3)
6. StealthScraper allocates browser from connection pool
7. Browser loads page with full stealth fingerprint
8. If CAPTCHA detected → CapMonster Cloud solves it
9. If IP blocked → proxy rotation triggers
10. Result returned to user

Error handling:
- Connection timeout → retry with next proxy
- 403/403 → switch to next layer
- CAPTCHA → solve via CapMonster + continue
- Page crash → retry with fresh browser context
- All layers fail → return detailed error report

🚀 Quick Start / 快速开始

Install via npm / npm 安装

# Install globally
npm install -g cloakbrowser

# Or install as project dependency
npm install cloakbrowser@0.3.28

REST API Service / REST API 服务

# Install systemd service
sudo cp scraper-server.service /etc/systemd/system/homo-scraper.service
sudo systemctl daemon-reload

# Start the service
sudo systemctl start homo-scraper.service

# Enable auto-start on boot
sudo systemctl enable homo-scraper.service

# Check status
sudo systemctl status homo-scraper.service

# Health check
curl -s http://127.0.0.1:9377/health
# Response: {"status":"ok","uptime":"12h 34m 56s","connections":3,"requests_since_start":12345}

Basic Usage / 基本用法

// Import the scraper
import { StealthScraper } from './stealth-scraper.js';

// Create instance with options
const scraper = new StealthScraper({
  verbose: true,
  maxConcurrency: 3
});

// Basic scrape
const result = await scraper.scrape('https://example.com', {
  waitMs: 3000,
  screenshot: '/tmp/page.png'
});
console.log('Title:', result.title);
console.log('Text length:', result.text.length);
console.log('Links found:', result.links?.length);

// Scrape with proxy rotation
const resultWithProxy = await scraper.scrape('https://example.com', {
  waitMs: 5000,
  useProxy: true,
  proxyIndex: 0  // Optional: specify proxy index
});

// Scrape batch URLs
const urls = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3'
];
const results = await Promise.all(
  urls.map(url => scraper.scrape(url, { waitMs: 2000 }))
);
console.log(`Scraped ${results.length} pages`);

Using REST API / 使用 REST API

# Open a page and get snapshot
curl -X POST http://127.0.0.1:9377/tabs/open \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","waitMs":5000}'
# Response: {"tabId":"abc123","status":"opened","snapshot":"<html>..."}

# Get snapshot for last opened tab
curl http://127.0.0.1:9377/tabs/snapshot?tabId=last

# Close tab
curl -X POST http://127.0.0.1:9377/tabs/close \
  -H 'Content-Type: application/json' \
  -d '{"tabId":"abc123"}'

# Get proxy pool status
curl http://127.0.0.1:9377/proxies

# Get service statistics
curl http://127.0.0.1:9377/stats

Using CLI Proxy Manager / 使用 CLI 代理管理器

# Configure proxies via environment variable
export PROXY_LIST="http://user:pass@ip1:port,http://user:pass@ip2:port"

# Or via config file
echo "http://user:pass@ip1:port" >> proxy-list.txt
echo "http://user:pass@ip2:port" >> proxy-list.txt

# Proxy management
bash proxy-manager.sh               # Show usage
bash proxy-manager.sh status        # Show proxy pool
bash proxy-manager.sh test          # Test all proxies
bash proxy-manager.sh rotate        # Rotate and restart service
bash proxy-manager.sh add http://user:pass@ip:port   # Add proxy
bash proxy-manager.sh remove 0      # Remove proxy at index 0

📦 Installation / 安装指南

System Requirements / 系统要求

Requirement	Minimum	Recommended
OS	Ubuntu 20.04 / macOS 12+	Ubuntu 22.04 / macOS 14+
CPU	2 cores	4+ cores
RAM	2 GB	8 GB+
Disk	1 GB free	10 GB free
Node.js	18.x	20.x LTS
Python	3.8+	3.10+
Network	Broadband	Dedicated IP

Step-by-Step Installation / 分步安装

# Step 1: Install system dependencies
sudo apt-get update
sudo apt-get install -y \
  curl wget git \
  build-essential \
  libnss3 libnspr4 libatk-bridge2.0-0 \
  libdrm2 libxkbcommon0 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 \
  libpango-1.0-0 libcairo2 libasound2

# Step 2: Install Node.js (if not installed)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version  # Should be >= 18

# Step 3: Install Python dependencies (for Crawl4AI)
pip3 install crawl4ai playwright
playwright install chromium

# Step 4: Install BrowserHand
git clone https://github.com/sevenliuhu/browserhand.git
cd browserhand
npm install

# Step 5: Configure and start
# Edit proxy-list.txt with your proxies
# Then
sudo systemctl start homo-scraper.service

# Step 6: Verify installation
curl http://127.0.0.1:9377/health

Docker Installation / Docker 安装

FROM node:20-slim

RUN apt-get update && apt-get install -y \
  libnss3 libnspr4 libatk-bridge2.0-0 \
  libdrm2 libxkbcommon0 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 \
  libpango-1.0-0 libcairo2 libasound2 \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .
RUN npm install --production

EXPOSE 9377
CMD ["node", "scraper-server.js"]

# Build and run
docker build -t browserhand .
docker run -d -p 9377:9377 --name browserhand browserhand

Configuration / 配置

# Environment variables
export CAPMONSTER_API_KEY="your-capmonster-key"  # For CAPTCHA solving
export PROXY_LIST="http://user:pass@ip:port"      # Proxy list
export BROWSERHAND_PORT=9377                      # REST API port
export BROWSERHAND_POOL_SIZE=3                    # Connection pool size
export BROWSERHAND_TIMEOUT=30000                  # Request timeout (ms)

# Or create .env file
cat > .env << EOF
CAPMONSTER_API_KEY=your-capmonster-key
PROXY_LIST=http://user:pass@ip1:port,http://user:pass@ip2:port
BROWSERHAND_PORT=9377
BROWSERHAND_POOL_SIZE=3
BROWSERHAND_TIMEOUT=30000
EOF

📚 API Reference / API 参考

StealthScraper Class / StealthScraper 类

Constructor / 构造函数

const scraper = new StealthScraper(options);

Options:

Option	Type	Default	Description	说明
`verbose`	boolean	`false`	Enable verbose logging	开启详细日志
`maxConcurrency`	number	`3`	Max concurrent browser instances	最大并发浏览器实例数
`defaultWaitMs`	number	`2000`	Default wait time before snapshot (ms)	快照前默认等待时间(ms)
`useProxy`	boolean	`false`	Enable proxy rotation	启用代理轮换
`retryCount`	number	`3`	Max retry attempts	最大重试次数
`cookieDir`	string	`'./cookies'`	Cookie persistence directory	Cookie 持久化目录

Methods / 方法

scrape(url, options) — Scrape a URL / 抓取URL

Parameter	Type	Default	Description	说明
`url`	string	required	Target URL	目标URL
`options.waitMs`	number	`2000`	Wait time before snapshot (ms)	快照前等待时间(ms)
`options.screenshot`	string	`null`	Save screenshot to path	截图保存路径
`options.useProxy`	boolean	`false`	Use proxy for this request	使用代理
`options.proxyIndex`	number	`-1`	Specific proxy index (-1 = auto)	指定代理索引(-1=自动)
`options.cookieDomain`	string	`null`	Domain for cookie persistence	Cookie持久化域名

Returns:

{
  url: string,          // Requested URL
  title: string,        // Page title
  text: string,         // Page text content
  links: string[],      // All links on the page
  snapshot: string,     // HTML snapshot
  status: number,       // HTTP status code
  timing: {             // Timing information
    total: number,
    navigation: number,
    wait: number
  },
  meta: {              // Meta information
    viewport: string,
    userAgent: string,
    cookies: number
  }
}

scrapeBatch(urls, options) — Scrape multiple URLs / 批量抓取

const results = await scraper.scrapeBatch([
  'https://example.com/1',
  'https://example.com/2',
  'https://example.com/3'
], {
  concurrency: 3,      // Concurrent requests
  waitMs: 2000,
  onProgress: (done, total) => {
    console.log(`${done}/${total} complete`);
  }
});

close() — Clean up all browser instances / 清理所有浏览器实例

await scraper.close();
console.log('All browser instances closed');

REST API Endpoints / REST API 端点

`GET /health`

Health check. Returns:

{
  "status": "ok",
  "uptime": "12h 34m 56s",
  "connections": 3,
  "requests_since_start": 12345,
  "memory_usage_mb": 156.7,
  "version": "3.0.0"
}

`POST /tabs/open`

Open a URL and return snapshot. Request body:

{
  "url": "https://example.com",
  "waitMs": 5000,
  "screenshot": true,
  "useProxy": false,
  "cookieDomain": "example.com"
}

`GET /tabs/snapshot?tabId=last`

Get snapshot for a specific tab. Returns full HTML content.

`POST /tabs/close`

Close a tab. Request body:

{
  "tabId": "abc123"
}

`GET /proxies`

Get proxy pool status. Returns:

{
  "total": 5,
  "available": 4,
  "active": 1,
  "proxies": [
    {"index": 0, "host": "192.168.1.1", "status": "active"},
    {"index": 1, "host": "192.168.1.2", "status": "available"},
    {"index": 2, "host": "192.168.1.3", "status": "failed"}
  ]
}

`POST /cookies/import`

Import cookies for a domain. Request body:

{
  "domain": "example.com",
  "cookies": [
    {"name": "session", "value": "abc123", "domain": ".example.com"}
  ]
}

`POST /cookies/export`

Export cookies for a domain. Request body:

{
  "domain": "example.com"
}

`GET /stats`

Get service statistics. Returns:

{
  "uptime_seconds": 45123,
  "total_requests": 12345,
  "successful": 12000,
  "failed": 345,
  "avg_response_time_ms": 2340,
  "proxy_rotations": 567,
  "captchas_solved": 89,
  "memory_usage_mb": 156.7
}

🧩 Core Components / 核心组件

stealth-scraper.js — Core Scraping Engine (500 lines)

The heart of BrowserHand. Provides:

CloakBrowser-based browser automation
Connection pool management (3 instances by default)
Smart retry with exponential backoff
Snapshot mode (accessibility tree / plain text — saves 90% token)
CAPTCHA detection + CapMonster integration
Batch scraping support

Key features:

// Connection pool auto-management
// 3 persistent browser instances
// 5min idle auto-close
// Automatic reconnection on crash

// Smart retry:
// Attempt 1: immediate
// Attempt 2: 2s delay
// Attempt 3: 4s delay
// Attempt 4: 8s delay
// Attempt 5: 16s delay (max 5 attempts)

scraper-server.js — REST API Server (237 lines)

Systemd-managed REST API service:

Port 9377 (localhost-only for security)
Health check endpoint
Tab management (open/snapshot/close)
Cookie import/export
Proxy pool status
Service statistics

# Start
sudo systemctl start homo-scraper.service

# Stop
sudo systemctl stop homo-scraper.service

# Restart
sudo systemctl restart homo-scraper.service

# Logs
sudo journalctl -u homo-scraper.service -f

proxy-manager.sh — Proxy Pool Manager

Complete proxy lifecycle management:

Load proxies from file or environment variable
Test connectivity with httpbin.org
Rotate proxies and restart service
Add/remove proxies dynamically
Automatic failover on failed proxies

web-peekaboo.js — Bot Detection Test Suite

Peekaboo-style web toolset for testing bot detection evasion:

see — View page (snapshot/screenshot)
click — Click element
type — Fill form
scroll — Scroll page
navigate — Navigate to URL
screenshot — Take screenshot
agent — Multi-step automation

peekaboo-mcp.js — MCP Protocol Adapter

MCP (Model Context Protocol) adapter for AI agent integration:

Standard MCP tool interface
Compatible with OpenClaw and other AI frameworks
Session management
Tool registration

📱 Pinduoduo Automation / 拼多多自动化

BrowserHand includes 14 specialized scripts for Pinduoduo (拼多多) automation, covering login, CAPTCHA handling, and page interaction.

Login Scripts / 登录脚本

Script	Description	说明
`pdd-js-login.js`	JavaScript-based login flow	基于JavaScript的登录流程
`pdd-login-v2.js`	Login method v2 - alternative approach	登录方法v2 - 替代方案
`pdd-login-v3.js`	Login method v3 - alternative approach	登录方法v3 - 替代方案
`pdd-simple.js`	Simple login for basic scenarios	简单登录（基础场景）
`pdd-submit-login.js`	Login form submission handler	登录表单提交流程
`pdd-try-login.js`	Retry login with fallback strategies	带降级策略的重试登录
`pdd-login-check.js`	Verify login state	验证登录状态
`pdd-qrcode.js`	QR code login flow	二维码登录

CAPTCHA Handling / 验证码处理

Script	Description	说明
`pdd-find-captcha.js`	Locate CAPTCHA elements on page	定位页面上的验证码元素
`pdd-find-slider.js`	Locate slider elements	定位滑块元素
`pdd-close-slider.js`	Close slider CAPTCHA overlay	关闭滑块验证码覆盖
`pdd-slide.js`	Handle slider CAPTCHA	处理滑块验证码
`pdd-check-overlay.js`	Detect overlay/popup presence	检测弹窗覆盖

Page Analysis / 页面分析

Script	Description	说明
`pdd-structure.js`	Analyze page DOM structure	分析页面DOM结构

Usage Examples / 使用示例

# QR code login
node pdd-qrcode.js --url "https://mobile.yangkeduo.com/login.html"

# Check login state
node pdd-login-check.js --url "https://mobile.yangkeduo.com/"

# Handle slider captcha
node pdd-slide.js --url "https://mobile.yangkeduo.com/login.html"

// Programmatic usage
import { PDDLogin } from './pdd-js-login.js';

const login = new PDDLogin();
await login.initialize();

// Try QR login first
const qrResult = await login.qrLogin();
if (!qrResult.success) {
  // Fall back to slider captcha
  await login.handleSlider();
}

// Verify login
const loggedIn = await login.verify();
console.log('Login state:', loggedIn);

🧪 Bot Detection Test Suite / 机器人检测测试套件

BrowserHand includes a comprehensive bot detection test suite (web-peekaboo.js) to verify stealth capabilities against real-world detection services.

Test Checkpoints / 测试检查点

Checkpoint	What It Tests	测试内容
✅ WebDriver	navigator.webdriver property	navigator.webdriver 属性
✅ Chrome Runtime	chrome.runtime detection	chrome.runtime 检测
✅ Plugins Array	navigator.plugins length	navigator.plugins 长度
✅ Languages	navigator.languages format	navigator.languages 格式
✅ WebGL Vendor	WebGL renderer info	WebGL 渲染器信息
✅ Canvas Fingerprint	Canvas noise and fingerprint	Canvas 噪点和指纹
✅ Audio Context	AudioContext fingerprint	AudioContext 指纹
✅ Font Detection	Installed fonts enumeration	已安装字体枚举

Running Tests / 运行测试

# Run full test suite
node test-web-peekaboo.js

# Run specific test
node test-web-peekaboo.js --check webdriver

# Run with verbose output
node test-web-peekaboo.js --verbose

# Run against specific URL
node test-web-peekaboo.js --url https://bot-detection-test.example.com

Test Output / 测试输出

📋 BrowserHand Bot Detection Test Suite
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ WebDriver — navigator.webdriver: undefined (PASS)
  ✅ Chrome Runtime — chrome.runtime: undefined (PASS)
  ✅ Plugins Array — navigator.plugins.length: 5 (PASS)
  ✅ Languages — en-US, zh-CN, zh (PASS)
  ✅ WebGL Vendor — Google Inc. (Mesa) (PASS)
  ✅ Canvas Fingerprint — Noise injected (PASS)
  ✅ Audio Context — Fingerprint randomized (PASS)
  ✅ Font Detection — System fonts masked (PASS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Results: 8 ✅ / 0 ❌ / 8 total

🛡️ Anti-Scraping Strategy / 反爬策略

Four-Layer Defense / 四层防御

BrowserHand's anti-scraping strategy is documented in detail in ANTI-SCRAPING-STRATEGY.md.

Layer 1: Search Engine / Direct API Access

First attempt: use web_search or direct API
Fastest, zero overhead
Works for most public pages

Layer 2: Stealth Browser (StealthScraper v3)

Full browser fingerprint simulation
49 C++ Chromium source patches
Puppeteer-extra + stealth plugin

Layer 3: CAPTCHA Solving

CapMonster Cloud integration
Automatic CAPTCHA detection
Report back on failure

Layer 4: Dynamic Proxy Rotation

Switch IP on rate limiting / blocking
Weighted proxy selection based on history
Automatic proxy health checks

Automatic Battle Flow / 自动作战流程

User Request
    │
    ▼
[Layer 1] Firecrawl / Direct API
    ├── Success → Return Results ✅
    └── Failure →
         │
         ▼
    [Layer 2] StealthScraper v3
    ├── Success → Return Results ✅
    ├── CAPTCHA → Auto-solve via CapMonster → Continue
    ├── IP Blocked → Auto-rotate proxy → Retry
    └── Failure (3 retries exhausted) →
         │
         ▼
    [Report] Detailed failure + reason

Best Practices / 最佳实践

Start with the lightest layer — Firecrawl works for most pages
Configure proxies first — Even with StealthScraper, clean IPs matter
Set up CapMonster — Without CAPTCHA solving, you'll hit walls
Use session isolation — Each scrape task in separate context
Monitor proxy health — Dead proxies waste time and burn retries
Enable verbose logging — Helps debug stealth issues
Rotate user agents — Don't use the same UA for every request
Add random delays — Mimic human browsing patterns

🌐 Proxy Management / 代理管理

Configuration / 配置

BrowserHand supports multiple proxy sources:

1. Environment Variable:

export PROXY_LIST="http://user:pass@ip1:port,http://user:pass@ip2:port"

2. Config File:

# /root/package/scraping/proxy-list.txt
http://user:pass@ip1:port
http://user:pass@ip2:port
http://user:pass@ip3:port

3. REST API:

# Add proxy via API
curl -X POST http://127.0.0.1:9377/proxies/add \
  -H 'Content-Type: application/json' \
  -d '{"proxy":"http://user:pass@ip:port"}'

Proxy Selection Algorithm / 代理选择算法

1. Maintain list of all proxies with health scores
2. Sort by health score (descending)
3. Select top N proxies for current task
4. Round-robin within selected set
5. On failure: decrement health score, try next proxy
6. On success: increment health score
7. Periodic health check for all proxies
8. Remove proxies with persistently low scores

Recommended Proxy Providers / 推荐代理提供商

Provider	Type	Price	Quality	说明
BrightData	Residential	$15/GB	⭐⭐⭐⭐⭐	Best for serious scraping
Oxylabs	Residential	$12/GB	⭐⭐⭐⭐⭐	Enterprise-grade
Smartproxy	Residential	$7/GB	⭐⭐⭐⭐	Good value
Rayobyte	Residential	$8/GB	⭐⭐⭐⭐	Reliable
IPRoyal	Residential	$5/GB	⭐⭐⭐	Budget option

🍪 Cookie Persistence / Cookie 持久化

BrowserHand automatically persists cookies by domain, enabling session reuse across requests.

How It Works / 工作原理

On page load: BrowserHand checks for existing cookies for the domain
If found: Cookies are injected into the browser context
After page load: Cookies are saved to disk (MD5-hashed by domain)
On next request: Same cookies are loaded automatically

Storage Format / 存储格式

cookies/
├── a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json  # MD5 hash of "example.com"
├── f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1.json  # MD5 hash of "example.org"
└── ...

Manual Cookie Management / 手动管理Cookie

# Export cookies for a domain
curl -X POST http://127.0.0.1:9377/cookies/export \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com"}'

# Import cookies for a domain
curl -X POST http://127.0.0.1:9377/cookies/import \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com","cookies":[{"name":"session","value":"abc"}]}'

# Clear all cookies
rm -rf /root/package/scraping/cookies/*

🔒 Session Isolation / 会话隔离

Each scrape task runs in an independent browser context, ensuring complete isolation between tasks.

Benefits / 优势

No cross-task contamination: Cookies, local storage, and sessions are separate
Parallel execution: Run multiple tasks simultaneously without interference
Security: One compromised session doesn't affect others
Debugging: Isolate and reproduce issues per task

Implementation / 实现

// Each scrape creates a new browser context
const context = await browser.newContext({
  userAgent: '...',
  viewport: { width: 1920, height: 1080 },
  locale: 'en-US'
});

// Context is destroyed after scraping
await context.close();

📊 Performance Benchmarks / 性能基准测试

Page Load Times / 页面加载时间

Site Type	Firecrawl	Crawl4AI	StealthScraper v3
Static HTML	0.8s	2.1s	3.5s
JS-heavy SPA	2.5s*	3.4s	4.2s
Cloudflare-protected	❌	4.5s	5.1s
reCAPTCHA protected	❌	❌	6.8s**
Login-required	❌	5.2s	6.5s

*Firecrawl may not fully render JS-heavy sites **Includes CAPTCHA solving time (~1.5s)

Throughput / 吞吐量

Configuration	Requests/min	Success Rate
Single instance, no proxy	15	92%
Single instance, with proxy	12	96%
3 instances, with proxy pool	35	98%
5 instances, optimized	50	99%

Memory Usage / 内存使用

Component	Memory (MB)
Idle (no connections)	45
1 active browser	85
3 browsers (pool)	210
5 browsers (max)	340

💡 Use Cases / 应用场景

1. E-commerce Data Collection / 电商数据采集

// Collect product data from Pinduoduo
const products = await scraper.scrapeBatch([
  'https://mobile.yangkeduo.com/product1.html',
  'https://mobile.yangkeduo.com/product2.html'
], {
  useProxy: true,
  cookieDomain: 'yangkeduo.com'
});

2. Competitive Intelligence / 竞品情报

// Monitor competitor pricing daily
async function dailyMonitor() {
  const competitors = ['https://competitor1.com', 'https://competitor2.com'];
  for (const url of competitors) {
    const data = await scraper.scrape(url, { useProxy: true });
    // Store and analyze
  }
}

3. Content Aggregation / 内容聚合

// Aggregate news from multiple sources
const sources = [
  'https://news-site1.com',
  'https://news-site2.com',
  'https://news-site3.com'
];
const articles = await scraper.scrapeBatch(sources);

4. SEO Monitoring / SEO 监控

// Monitor search engine rankings
async function checkRankings(keywords) {
  for (const kw of keywords) {
    const result = await scraper.scrape(
      `https://www.google.com/search?q=${encodeURIComponent(kw)}`,
      { useProxy: true, waitMs: 3000 }
    );
    // Parse SERP results
  }
}

5. Social Media Analysis / 社交媒体分析

// Analyze social media presence
async function analyzeSocial(platforms) {
  for (const platform of platforms) {
    const profile = await scraper.scrape(platform, {
      useProxy: true,
      cookieDomain: new URL(platform).hostname
    });
    // Extract follower count, engagement, etc.
  }
}

6. Real Estate Data / 房地产数据

// Collect property listings
const listings = await scraper.scrape('https://realestate.com/search', {
  waitMs: 5000,
  screenshot: '/tmp/search-results.png'
});

7. Financial Data / 金融数据

// Monitor stock prices and financial reports
const data = await scraper.scrape(
  'https://finance-site.com/stocks/AAPL',
  { useProxy: true }
);

8. Academic Research / 学术研究

// Scrape academic papers and citations
const papers = await scraper.scrapeBatch(
  ['https://scholar.google.com/scholar?q=AI'],
  { waitMs: 4000 }
);

🔄 Comparison / 竞品对比

Feature	BrowserHand	Puppeteer-Stealth	Playwright	Selenium Stealth
Chromium patches	49 C++ patches	0 (JS only)	0	0
Cloudflare bypass	✅✅✅	⚠️ Partial	❌	❌
reCAPTCHA auto-solve	✅	❌	❌	❌
Proxy rotation	✅ Built-in	❌	❌	❌
Cookie persistence	✅ Built-in	❌	❌	❌
Session isolation	✅ Built-in	❌	✅	❌
REST API	✅ Built-in	❌	❌	❌
Connection pool	✅ Built-in	❌	❌	❌
Smart retry	✅ Built-in	❌	❌	❌
Batch scraping	✅ Built-in	❌	❌	❌
MCP protocol	✅	❌	❌	❌
Pinduoduo scripts	✅ (14 scripts)	❌	❌	❌
Bot detection test	✅ Built-in	❌	❌	❌
AGPL license	✅	❌ (Apache 2.0)	❌ (Apache 2.0)	❌ (Apache 2.0)

❓ FAQ / 常见问题

English

Q: Do I need a GPU for BrowserHand? A: No. BrowserHand works in headless mode without GPU. The CloakBrowser engine simulates WebGL and Canvas without actual GPU access.

Q: Can I use BrowserHand with my existing Puppeteer code? A: BrowserHand is built on Playwright, not Puppeteer. Migration requires adapting your code to Playwright's API, which is similar but not identical.

Q: Does BrowserHand work on Windows? A: BrowserHand is tested on Linux (Ubuntu 20.04+) and macOS. Windows support is experimental.

Q: How many requests can I make per day? A: The Community Edition (free) is limited to 100 requests per day. Paid tiers offer 10K to unlimited requests.

Q: What happens when all proxies fail? A: BrowserHand will report a detailed failure including which proxies failed and at which layer the request was blocked.

Q: Can I deploy BrowserHand on Kubernetes? A: Yes. BrowserHand can be containerized and deployed on Kubernetes. The REST API makes it suitable for microservice architectures.

Q: Is BrowserHand legal? A: Scraping public data is generally legal, but you should review the terms of service of target websites. BrowserHand is designed for legitimate data collection purposes.

中文

问：BrowserHand 需要 GPU 吗？ 答：不需要。BrowserHand 以无头模式运行，不需要 GPU。CloakBrowser 引擎在不使用实际 GPU 的情况下模拟 WebGL 和 Canvas。

问：我可以将 BrowserHand 与我现有的 Puppeteer 代码一起使用吗？ 答：BrowserHand 基于 Playwright 构建，而不是 Puppeteer。迁移需要将代码适配到 Playwright 的 API，两者相似但不完全相同。

问：BrowserHand 在 Windows 上能用吗？ 答：BrowserHand 在 Linux（Ubuntu 20.04+）和 macOS 上经过测试。Windows 支持是实验性的。

问：我每天可以发出多少请求？ 答：社区版（免费版）每天限制 100 次请求。付费版本提供 10K 到无限请求。

问：当所有代理都失败时会发生什么？ 答：BrowserHand 会报告详细的失败信息，包括哪些代理失败以及请求在哪个层被阻止。

问：我可以在 Kubernetes 上部署 BrowserHand 吗？ 答：可以。BrowserHand 可以容器化并部署在 Kubernetes 上。REST API 使其适合微服务架构。

问：BrowserHand 合法吗？ 答：抓取公开数据通常是合法的，但您应查看目标网站的服務條款。BrowserHand 专为合法的数据收集目的而设计。

🔒 Security / 安全

Security Features / 安全功能

Feature	Description	说明
🔑 API Key Protection	All API keys managed via SecureKeyStore (WeakMap-protected)	API密钥通过SecureKeyStore管理（WeakMap保护）
🛡️ Localhost Only	REST API binds to 127.0.0.1 by default	REST API默认绑定到127.0.0.1
🔐 Cookie Encryption	Cookies stored with domain MD5 hash, no plaintext	Cookie按域名MD5哈希存储，不存储明文
🔒 Session Isolation	Each task isolated in independent browser context	每个任务在独立browserContext中隔离
🔍 Input Validation	All API inputs sanitized and validated	所有API输入经过清理和验证
📝 Audit Logging	All requests logged with timestamp and source	所有请求记录时间戳和来源
⏰ Timeout Protection	Requests automatically timeout after 30s	请求30秒自动超时
🚫 Rate Limiting	Per-tier rate limiting prevents abuse	按版本限制速率，防止滥用

Security Best Practices / 安全最佳实践

Keep API keys in environment variables, not in code
Use localhost-only binding for the REST API
Rotate proxies regularly to maintain anonymity
Clear cookies between sensitive tasks
Monitor the audit log for unusual activity
Keep dependencies updated via npm audit
Use HTTPS when accessing BrowserHand remotely

🤝 Contributing / 贡献指南

How to Contribute / 如何贡献

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit changes: git commit -m 'Add my feature'
Push to branch: git push origin feature/my-feature
Submit a Pull Request

Development Setup / 开发环境

# Clone your fork
git clone https://github.com/your-username/browserhand.git
cd browserhand

# Install dependencies
npm install

# Create development .env
cp .env.example .env
# Edit .env with your settings

# Run tests
npm test

# Run specific test
node test-web-peekaboo.js

# Start development server
node scraper-server.js --dev

Code Style / 代码风格

Use ES modules (import/export)
Follow existing code patterns
Write JSDoc comments for all functions
Add tests for new features
Keep functions focused and small (< 50 lines where possible)

Pull Request Guidelines / PR 指南

One feature per PR — keep changes focused
Add tests — verify your feature works
Update documentation — README, JSDoc, or both
No breaking changes — unless discussed in issue first
Clean commit history — rebase before submitting

📝 Changelog / 更新日志

v3.0.0 (2026-05-16)

Major Changes:

🔥 Complete rewrite with CloakBrowser engine (49 C++ patches)
🚀 Connection pool: 3 persistent browser instances
🔄 Smart retry with exponential backoff
🍪 Cookie persistence with MD5-hashed domain storage
🔒 Session isolation per task
🌐 Proxy rotation with health checks
📊 REST API with comprehensive stats
🧪 Web Peekaboo test suite
🛡️ Pinduoduo automation (14 scripts)
📜 AGPL v3.0 license

v2.0.0 (2026-03-15)

Added Crawl4AI integration
REST API endpoints for tab management
Proxy manager shell script
Basic stealth features

v1.0.0 (2026-01-10)

Initial release with basic scraping
Puppeteer-extra with stealth plugin
Single browser instance
Command-line interface

💰 Pricing / 定价方案

Five Pricing Tiers / 五档定价

Tier	Price	Daily Requests	Layers	Proxy Rotation	CAPTCHA Solving	Cookie Persistence	Session Isolation	Support
🌱 Sprout Free	¥0	100	Layer 1	❌	❌	❌	❌	Community
🔑 Key	$9.9	1,000	Layers 1-2	❌	❌	✅	✅	Email
🛡️ Shield	$29.9	10,000	Layers 1-3	✅	✅	✅	✅	Priority
🏰 Fortress	$99.9	100,000	Layers 1-4	✅	✅	✅	✅	Priority + Slack
🏛️ Citadel	$299.9	Unlimited	All Layers + Custom	✅ Premium	✅ Premium	✅ Persistent	✅ Advanced	24/7 Dedicated

Tier Details / 版本详情

🌱 Sprout Free — ¥0

100 requests per day / 每天100次请求
Firecrawl layer only (no browser needed)
Basic REST API
Community support (GitHub Issues)
Ideal for testing and evaluation
No proxy rotation
No CAPTCHA solving
No cookie persistence
No session isolation
No commercial use (see AGPL terms)

🔑 Key — $9.9

1,000 requests per day / 每天1000次请求
Layers 1-2 (Firecrawl + Crawl4AI)
Cookie persistence enabled
Session isolation enabled
Email support (24h response)
REST API with additional endpoints
Good for small projects and personal use

🛡️ Shield — $29.9

10,000 requests per day / 每天10000次请求
Layers 1-3 (up to ZenRows)
Proxy rotation enabled
CAPTCHA solving via CapMonster
Cookie persistence + session isolation
Priority email support (12h response)
Batch scraping support
Suitable for medium-scale projects
Commercial use allowed (non-enterprise)

🏰 Fortress — $99.9

100,000 requests per day / 每天100000次请求
All 4 layers including StealthScraper v3
Premium proxy rotation with health monitoring
Premium CAPTCHA solving with AI-powered recognition
Persistent cookie storage
Advanced session isolation with context pools
Priority support (email + Slack)
Custom configuration support
Dedicated proxy pool
Ideal for professional teams and agencies

🏛️ Citadel — $299.9

Unlimited requests / 无限请求
All layers with custom configuration
Premium proxy rotation with dedicated IP pool
Premium CAPTCHA solving with priority queue
Persistent cookie storage across sessions
Advanced session isolation with custom contexts
24/7 dedicated support (phone + Slack + email)
On-premise deployment option
Custom engine configuration
SLA guarantee (99.9% uptime)
Training and onboarding
Source code access (under NDA)
White-label option available
Ideal for enterprises and large-scale operations

Feature Comparison Matrix / 功能对比矩阵

Feature	Sprout Free	Key $9.9	Shield $29.9	Fortress $99.9	Citadel $299.9
Daily Requests	100	1,000	10,000	100,000	Unlimited
Firecrawl Layer	✅	✅	✅	✅	✅
Crawl4AI Layer	❌	✅	✅	✅	✅
ZenRows Layer	❌	❌	✅	✅	✅
StealthScraper v3	❌	❌	❌	✅	✅
Proxy Rotation	❌	❌	✅ Standard	✅ Premium	✅ Dedicated
CAPTCHA Solving	❌	❌	✅ Standard	✅ Premium	✅ Priority
Cookie Persistence	❌	✅	✅	✅	✅ Persistent
Session Isolation	❌	✅	✅	✅ Advanced	✅ Custom
Batch Scraping	❌	❌	✅	✅	✅
REST API	✅ Basic	✅ Extended	✅ Full	✅ Full	✅ Custom
Commercial Use	❌	❌	✅	✅	✅
On-Premise	❌	❌	❌	❌	✅
SLA	None	None	None	99%	99.9%

Payment Methods / 支付方式

Method	Accepted	是否接受
WeChat Pay	✅	微信支付
Alipay	✅	支付宝
Bank Transfer	✅	银行转账
Cryptocurrency (BTC/ETH/USDT)	✅	加密货币
PayPal	✅	PayPal
Credit Card	✅ (via Stripe)	信用卡

📞 Contact / 联系方式

Primary Contact / 主要联系方式

Method	Info	Response Time	说明
📱 WeChat	`sevenliuhu`	Usually within 1h (9:00-23:00)	微信：sevenliuhu
📧 Email	homo-ai@outlook.com	Within 24h	邮箱：homo-ai@outlook.com

Other Channels / 其他渠道

Platform	Handle / Link	平台
GitHub	@sevenliuhu	GitHub
Discord	BrowserHand Server (email for invite)	Discord
Twitter/X	@sevenliuhu	推特

Business Hours / 工作时间

Timezone	Hours	时区
Beijing (GMT+8)	9:00 - 23:00	北京时间

24/7 support available for Citadel tier customers.

🛒 Purchase Flow / 购买流程

Standard Purchase Process / 标准购买流程

Step 1 ──── Add WeChat `sevenliuhu` or email homo-ai@outlook.com
            ↓
Step 2 ──── Choose your plan from the pricing table
            ↓
Step 3 ──── Payment (WeChat Pay / Alipay / Bank Transfer / Crypto)
            ↓
Step 4 ──── Receive API keys + deployment guide within 24 hours
            ↓
Step 5 ──── Start scraping in 5 minutes

Detailed Steps / 详细步骤

Contact us via WeChat (sevenliuhu) or email (homo-ai@outlook.com)
Tell us your needs — which tier, how many proxies, expected volume
We recommend a plan based on your requirements
Make payment through your preferred method
We process your order — typically within 2 hours during business hours
You receive:
- License key
- API documentation
- Deployment guide
- Sample code
Deploy and start — installation takes approximately 5 minutes

Enterprise Orders / 企业购买

For Citadel tier or custom requirements:

Schedule a call via WeChat or email
Discuss requirements — volume, SLA, deployment, compliance
Receive custom quote tailored to your needs
Sign agreement — NDA and service contract
Deployment — we help set up on-premise or cloud
Training — we provide onboarding for your team
Ongoing support — 24/7 dedicated support channel

Refund Policy / 退款政策

Tier	Refund Policy	退款政策
Key	7-day money-back guarantee	7天无条件退款
Shield	7-day money-back guarantee	7天无条件退款
Fortress	14-day pro-rated refund	14天内按比例退款
Citadel	Custom (per contract)	按合同约定

Bulk Discounts / 批量折扣

Quantity	Discount	折扣
3-5 licenses	10% off	9折
6-10 licenses	15% off	8.5折
11-20 licenses	20% off	8折
20+ licenses	Custom pricing	面议

🗺️ Roadmap / 路线图

Q3 2026

AI-powered CAPTCHA solver — ML-based recognition, no third-party dependency
Browser fingerprint randomizer — Different fingerprint per request
WebSocket support — Real-time page monitoring
Python SDK — First-class Python API
CLI improvements — Interactive mode with progress bars

Q4 2026

Mobile browser support — Full mobile emulation with real device fingerprints
Headless mode optimization — 2x speed improvement
Distributed scraping — Multi-node support with central coordinator
Web UI dashboard — Visual monitoring and management
Custom plugin system — Community-contributed extensions

2027

Native C++ engine — 10x performance improvement over Node.js version
Cloud offering — Managed SaaS with auto-scaling
API marketplace — Pre-built scraping connectors for popular sites
Enterprise SSO — SAML/OAuth integration
GDPR compliance tools — Data retention and deletion automation

📜 License / 许可证

BrowserHand is released under the GNU Affero General Public License v3.0 (AGPL v3.0).

What This Means / 这意味着什么

Right	Permitted	是否允许
✅ Use commercially	Yes (with proper license tier)	商业使用（需合适版本）
✅ Modify	Yes	修改
✅ Distribute	Yes	分发
✅ Place warranty	Yes (paid tiers)	提供担保
❌ Sublicense	No	再许可
❌ Hold liable	No	承担责任

Additional Terms (TERMS.md) / 附加条款

In addition to the standard AGPL v3.0 terms, BrowserHand imposes the following restrictions:

No Closed-Source Commercial Use — Modified versions must remain open source when used as a network service
No Fork-and-Resell — Cannot copy the code, rename it, and sell as a competing product
E-commerce Platform Restrictions — Community edition cannot be used for e-commerce automation (including but not limited to: product listing, price changes, batch ordering, customer service automation)

License Key Support / License Key 校验

Paid tiers require a license key for operation:

Key tier: License key activates Layers 1-2, cookie persistence, session isolation
Shield tier: License key activates Layers 1-3, proxy rotation, CAPTCHA solving
Fortress tier: License key activates all layers, premium features
Citadel tier: Custom license with unlimited usage

Community (Free) edition works without a license key but with limitations.

Full License Text / 完整许可证文本

See the LICENSE file for the complete AGPL v3.0 license text.

Related Projects from HOMO 🤖

Project	Description
AgentMemory Vault	🔒 AES-256-GCM encrypted memory for AI agents
9router Gateway	🌉 Enterprise API gateway for LLMs
Skill Vault	🔐 Encrypt and protect AI agent skills
Memory Vault	🗄️ Multi-tenant encrypted memory vault
BrowserHand	🕵️ Stealth browser automation toolkit
OHIF HIPAA Vault	🏥 HIPAA compliance for OHIF Viewer
Freqtrade Strategy Vault	📊 Encrypted trading strategies
UI-TARS Sandbox	🏖️ Agent security sandbox
SciScrape Gateway	🔬 Research anti-scraping gateway
CrewAI Vault	👥 CrewAI enterprise encryption
MCP Secure	🛡️ MCP protocol security layer
API Secure Gateway	🚪 Enterprise API security
Dify Security Gateway	🤖 Dify AI security gateway

🏗️ 产品矩阵

项目	说明
browserhand	⬅️ 当前项目 — 隐身浏览器自动化工具包
homo-cloaked-playwright	Chromium隐身浏览器，Playwright兼容接口
skill-vault	AI技能加密保护，AES-256-GCM
ohif-hipaa-vault	HIPAA合规医疗影像隐私插件
freqtrade-strategy-vault	量化交易策略加密保护
agentmemory-vault	AI Agent记忆加密层

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
cookies		cookies
.gitignore		.gitignore
ANTI-SCRAPING-STRATEGY.md		ANTI-SCRAPING-STRATEGY.md
LICENSE		LICENSE
README.md		README.md
browserhand-intro.html		browserhand-intro.html
crawl4ai-rules.md		crawl4ai-rules.md
instance-control.md		instance-control.md
license-validator.js		license-validator.js
package-lock.json		package-lock.json
package.json		package.json
pdd-check-overlay.js		pdd-check-overlay.js
pdd-close-slider.js		pdd-close-slider.js
pdd-find-captcha.js		pdd-find-captcha.js
pdd-find-slider.js		pdd-find-slider.js
pdd-js-login.js		pdd-js-login.js
pdd-login-check.js		pdd-login-check.js
pdd-login-v2.js		pdd-login-v2.js
pdd-login-v3.js		pdd-login-v3.js
pdd-qrcode.js		pdd-qrcode.js
pdd-simple.js		pdd-simple.js
pdd-slide.js		pdd-slide.js
pdd-structure.js		pdd-structure.js
pdd-submit-login.js		pdd-submit-login.js
pdd-try-login.js		pdd-try-login.js
peekaboo-mcp.js		peekaboo-mcp.js
proxy-manager.sh		proxy-manager.sh
scraper-server.js		scraper-server.js
stealth-scraper.js		stealth-scraper.js
test-web-peekaboo.js		test-web-peekaboo.js
web-peekaboo.js		web-peekaboo.js

Folders and files

Latest commit

History

Repository files navigation

🕵️ BrowserHand — Stealth Browser Automation & Anti-Detection Scraping Engine

🕵️ BrowserHand — 隐形浏览器自动化 & 反检测抓取引擎

📋 Table of Contents / 目录

🌟 English Overview / 英文概览

Why BrowserHand?

Key Numbers

🔥 中文概览 / Chinese Overview

为什么选择 BrowserHand？

关键数据

⚡ Features / 功能特性

Core Engine / 核心引擎

Anti-Detection / 反检测

REST API / REST 接口

CLI Tools / 命令行工具

🏗️ Architecture / 架构设计

Four-Layer Anti-Scraping System / 四层反爬体系

Internal Architecture / 内部架构

Data Flow / 数据流

🚀 Quick Start / 快速开始

Install via npm / npm 安装

REST API Service / REST API 服务

Basic Usage / 基本用法

Using REST API / 使用 REST API

Using CLI Proxy Manager / 使用 CLI 代理管理器

📦 Installation / 安装指南

System Requirements / 系统要求

Step-by-Step Installation / 分步安装

Docker Installation / Docker 安装

Configuration / 配置

📚 API Reference / API 参考

StealthScraper Class / StealthScraper 类

Constructor / 构造函数

Methods / 方法

REST API Endpoints / REST API 端点

GET /health

POST /tabs/open

GET /tabs/snapshot?tabId=last

POST /tabs/close

GET /proxies

POST /cookies/import

POST /cookies/export

GET /stats

🧩 Core Components / 核心组件

stealth-scraper.js — Core Scraping Engine (500 lines)

scraper-server.js — REST API Server (237 lines)

proxy-manager.sh — Proxy Pool Manager

web-peekaboo.js — Bot Detection Test Suite

peekaboo-mcp.js — MCP Protocol Adapter

📱 Pinduoduo Automation / 拼多多自动化

Login Scripts / 登录脚本

CAPTCHA Handling / 验证码处理

Page Analysis / 页面分析

Usage Examples / 使用示例

🧪 Bot Detection Test Suite / 机器人检测测试套件

Test Checkpoints / 测试检查点

Running Tests / 运行测试

Test Output / 测试输出

🛡️ Anti-Scraping Strategy / 反爬策略

Four-Layer Defense / 四层防御

Automatic Battle Flow / 自动作战流程

Best Practices / 最佳实践

🌐 Proxy Management / 代理管理

Configuration / 配置

Proxy Selection Algorithm / 代理选择算法

Recommended Proxy Providers / 推荐代理提供商

🍪 Cookie Persistence / Cookie 持久化

How It Works / 工作原理

Storage Format / 存储格式

Manual Cookie Management / 手动管理Cookie

🔒 Session Isolation / 会话隔离

Benefits / 优势

Implementation / 实现

📊 Performance Benchmarks / 性能基准测试

Page Load Times / 页面加载时间

Throughput / 吞吐量

Memory Usage / 内存使用

`GET /health`

`POST /tabs/open`

`GET /tabs/snapshot?tabId=last`

`POST /tabs/close`

`GET /proxies`

`POST /cookies/import`

`POST /cookies/export`

`GET /stats`