浏览器自动化+数据采集框架。支持Playwright控制、DdddOcr验证码识别、东方财富/雪球/AKShare金融数据采集。反爬对抗、UA池、代理。
# Browser Collector Skill
**版本**: 1.3.0
**更新日期**: 2026-05-02
**状态**: 架构整合完成 ✅
---
## 简介
browser-collector 是基于 Playwright 的浏览器数据采集工具,提供反检测、代理池、验证码识别、批量采集等企业级功能。
## 快速入门
### 安装依赖
```bash
pip install -r requirements.txt
playwright install chromium
```
### 基本使用
```python
from collectors.adapters.builtin.cloud_docs.aliyun import AliyunDocAdapter
from collectors.adapters.extraction.spawait import wait_for_page_ready
# 创建适配器
adapter = AliyunDocAdapter()
# 使用
result = adapter.extract(page, "https://help.aliyun.com/document_detail/xxx")
print(result.title)
print(result.content)
```
### CLI 使用
```bash
# 采集文档
python3 collectors/cli.py collect --url "https://help.aliyun.com/document_detail/xxx"
# 使用指定适配器
python3 collectors/cli.py collect --url "xxx" --adapter aliyun_doc
# 批量采集
python3 collectors/cli.py batch --file urls.txt --workers 5
```
## 目录结构
```
browser-collector/
├── SKILL.md # 本文件
├── INTEGRATION_PLAN.md # 集成方案文档
├── requirements.txt # Python依赖
├── spa_sites.json # SPA站点配置
├── collectors/
│ ├── __init__.py # 模块导出
│ ├── base.py # 数据结构定义(StructuredItem等)
│ ├── registry.py # 采集器注册表(CollectorRegistry)
│ ├── cli.py # 统一CLI入口
│ │
│ ├── captcha_solver.py # 验证码识别(ddddocr + 滑块轨迹)
│ ├── tesseract_ocr.py # Tesseract OCR优化
│ ├── batch_collector.py # 批量采集 + 多进程Session隔离
│ ├── stealth.py # Playwright反检测(多级配置)
│ ├── proxy_pool.py # 代理池(抓取→验证→评分)
│ ├── cookie_db.py # SQLite Cookie持久化(加密)
│ │
│ ├── adapters/ # 适配器系统(重构后)
│ │ ├── __init__.py # 模块导出(自动注册所有内置适配器)
│ │ ├── base.py # 统一DocAdapter基类 + AdapterRegistry注册表
│ │ │
│ │ ├── builtin/ # 内置适配器
│ │ │ ├── cloud_docs/ # 云厂商文档
│ │ │ │ ├── aliyun.py # 阿里云文档
│ │ │ │ ├── tencent.py # 腾讯云
│ │ │ │ ├── volcengine.py # 火山引擎
│ │ │ │ └── coze.py # Coze扣子
│ │ │ ├── api_docs/ # API文档
│ │ │ │ ├── kimi.py # Kimi API
│ │ │ │ └── minimax.py # MiniMax API
│ │ │ └── social/ # 社交媒体
│ │ │ ├── github.py # GitHub仓库/Issue/用户
│ │ │ ├── zhihu.py # 知乎
│ │ │ ├── juejin.py # 掘金
│ │ │ └── csdn.py # CSDN
│ │ │
│ │ └── extraction/ # 提取能力模块
│ │ ├── __init__.py
│ │ ├── structure.py # 结构化数据模型(DocumentItem等)
│ │ └── spawait.py # 动态等待策略
│ │
│ └── builtin/ # 兼容层(仅browser_collector.py)
│ └── browser_collector.py # 通用浏览器采集器
```
## 核心功能
### 1. 通用浏览器采集器
```python
from collectors.builtin.browser_collector import BrowserCollector
collector = BrowserCollector(headless=True)
result = await collector.collect(url="https://example.com", wait_until="networkidle")
```
### 2. 文档适配器系统(★新增)
```python
from collectors.adapters import get_registry
# 获取适配器(自动注册所有内置适配器)
registry = get_registry()
adapter = registry.get_for_url('https://help.aliyun.com/doc')
# 提取完整文档结构
doc = adapter.extract(page, url)
# DocumentItem 包含:
# - toc: 嵌套目录结构
# - content: 正文内容
# - code_blocks: 代码块列表(带语言标记)
# - tables: 表格列表
# - images: 图片列表
# 输出格式
print(doc.to_json()) # JSON格式
print(doc.to_markdown()) # Markdown格式
```
### 3. 内置网站适配器
- **东方财富**: 股票数据、财经新闻
- **雪球**: 投资者社区、股票讨论
- **知乎**: 文章、问答
- **掘金**: 技术文章
- **CSDN**: 技术博客
- **GitHub**: 代码仓库信息
- **阿里云文档**: 云厂商文档(★重构)
### 4. 反检测功能
```python
from collectors.stealth import StealthConfig, apply_stealth
config = StealthConfig(level="high") # low, medium, high
context = await browser.new_context()
apply_stealth(context, config)
```
### 5. 代理池
```python
from collectors.proxy_pool import ProxyPool
pool = ProxyPool()
proxy = await pool.get_proxy() # 自动抓取、验证、评分
```
### 6. 验证码识别
```python
from collectors.captcha_solver import CaptchaSolver
solver = CaptchaSolver()
result = await solver.solve_captcha(image_bytes)
```
### 7. 批量采集
```python
from collectors.batch_collector import BatchCollector
collector = BatchCollector(max_workers=5)
results = await collector.run(urls=["url1", "url2", ...])
```
## CLI使用方式
```bash
# 通用采集(必填:--url)
python3 collectors/cli.py collect --url https://example.com
# 指定适配器采集
python3 collectors/cli.py collect --url https://help.aliyun.com/doc/xxx --adapter aliyun_doc
# 等待元素出现后采集
python3 collectors/cli.py collect --url https://platform.kimi.com/api/doc --wait-selector ".api-endpoint" --wait-time 5
# 东方财富数据
python3 collectors/cli.py eastmoney --stock 600519 --type basic
# 雪球数据
python3 collectors/cli.py xueqiu --symbol AAPL --type discussion
# 批量采集
python3 collectors/cli.py batch --file urls.txt --workers 5
# 代理池测试
python3 collectors/cli.py proxy --test
```
## 依赖安装
```bash
pip install -r requirements.txt
playwright install chromium
```
## 配置说明
### 反检测级别
| 级别 | 说明 |
|------|------|
| low | 基本隐身模式 |
| medium | 拦截 WebDriver 属性 |
| high | 完整反检测 + 随机UA |
### 代理池评分
- 分数 > 80: 优质代理
- 分数 50-80: 普通代理
- 分数 < 50: 低质代理(自动剔除)
## 注意事项
1. 反检测功能会修改 navigator 对象,慎用于需要真实信息的场景
2. 批量采集建议设置合理的 `max_workers` 避免被封
3. Cookie持久化支持多域名隔离
4. 验证码识别需要配置ddddocr模型
---
## 能力矩阵
### 适配器总览
| 适配器 | 支持站点 | 核心能力 | 状态 |
|--------|---------|---------|------|
| **云厂商文档** | | | |
| AliyunDocAdapter | help.aliyun.com | ✅ 文档结构化提取(标题/目录/正文/代码块/表格/图片/面包屑/元信息) | ✅ 已实现 |
| TencentDocAdapter | cloud.tencent.com | ✅ 文档结构化提取(标题/目录/正文/代码块/表格/图片/面包屑/元信息) | ✅ 已实现 |
| VolcengineDocAdapter | volcengine.com | ✅ 文档结构化提取(标题/目录/正文/代码块/表格/图片/面包屑/元信息) | ✅ 已实现 |
| CozeDocAdapter | coze.com, coze.cn | ✅ 文档结构化提取(标题/目录/正文/代码块/表格/图片/面包屑/元信息) | ✅ 已实现 |
| **API 文档** | | | |
| KimiApiAdapter | platform.kimi.com, api.moonshot.cn | ✅ API端点提取(路径/方法/参数/示例)、✅ 模型列表、✅ 代码示例 | ✅ 已实现 |
| MiniMaxApiAdapter | platform.minimaxi.com, api.minimax.chat | ✅ API端点提取(路径/方法/参数/示例)、✅ 模型列表、✅ 代码示例 | ✅ 已实现 |
| **社交媒体** | | | |
| GitHubAdapter | github.com | ✅ 仓库提取、✅ Issue提取、✅ 用户页、✅ README | ✅ 已实现 |
| ZhihuAdapter | zhihu.com | ✅ 文章提取、✅ 问答提取 | ✅ 已实现 |
| JuejinAdapter | juejin.cn | ✅ 技术文章提取 | ✅ 已实现 |
| CsdnAdapter | csdn.net | ✅ 技术博客提取 | ✅ 已实现 |
| **科技媒体** | | | |
| **通用采集** | | | |
| BrowserCollector | 通用网站 | ✅ 通用页面采集、✅ 反检测、✅ 代理池、✅ 验证码识别 | ✅ 已实现 |
| EastmoneyCollector | eastmoney.com | ✅ 股票数据、✅ 财经新闻 | ✅ 已实现 |
| XueqiuCollector | xueqiu.com | ✅ 投资者社区、✅ 股票讨论 | ✅ 已实现 |
### 适配器能力详情
#### 云厂商文档适配器
| 能力 | AliyunDocAdapter |
|------|------------------|
| 标题提取 | ✅ |
| 目录提取(侧边栏) | ✅ |
| 正文内容(Markdown) | ✅ |
| 代码块(带语言标记) | ✅ |
| 表格(格式保留) | ✅ |
| 图片(含Alt) | ✅ |
| 面包屑导航 | ✅ |
| 作者信息 | ✅ |
| 发布/更新时间 | ✅ |
| 版本标签 | ✅ |
| 标签提取 | ✅ |
#### 腾讯云/火山引擎文档适配器
| 能力 | TencentDocAdapter | VolcengineDocAdapter |
|------|-------------------|---------------------|
| 标题提取 | ✅ | ✅ |
| 目录提取(侧边栏) | ✅ | ✅ |
| 正文内容(Markdown) | ✅ | ✅ |
| 代码块(带语言标记) | ✅ | ✅ |
| 表格(格式保留) | ✅ | ✅ |
| 图片(含Alt) | ✅ | ✅ |
| 面包屑导航 | ✅ | ✅ |
| 作者信息 | ✅ | ✅ |
| 发布/更新时间 | ✅ | ✅ |
| 版本标签 | ✅ | ✅ |
| 标签提取 | ✅ | ✅ |
#### API文档适配器
| 能力 | KimiApiAdapter | MiniMaxApiAdapter |
|------|---------------|-------------------|
| API端点提取 | ✅ | ✅ |
| HTTP方法识别 | ✅ | ✅ |
| 参数列表(名称/类型/必填/描述) | ✅ | ✅ |
| 请求示例(JSON) | ✅ | ✅ |
| 响应示例(JSON) | ✅ | ✅ |
| 代码示例(curl/Python) | ✅ | ✅ |
| 模型列表 | ✅ | ✅ |
| 速率限制信息 | ✅ | ✅ |
| 认证方式 | ✅ | ✅ |
| 标签/分类 | ✅ | ✅ |
| 面包屑导航 | ✅ | ✅ |
#### 通用适配器
| 能力 | BrowserCollector | EastmoneyCollector | XueqiuCollector |
|------|------------------|---------------------|-----------------|
| 页面内容提取 | ✅ | ✅ | ✅ |
| 反检测(Playwright) | ✅ | ✅ | ✅ |
| 代理池 | ✅ | ✅ | ✅ |
| 验证码识别 | ✅ | ✅ | ✅ |
| 批量采集 | ✅ | ✅ | ✅ |
| Cookie持久化 | ✅ | ✅ | ✅ |
### 适配器选择建议
```python
from collectors.adapters import get_registry
registry = get_registry()
# 自动选择适配器(根据URL)
adapter = registry.get_for_url('https://help.aliyun.com/doc/12345')
# 手动指定适配器
adapter = registry.get('aliyun_doc')
# 列出所有适配器
all_adapters = registry.list_all()
for name in all_adapters:
adapter = registry.get(name)
print(f"{name}: {adapter.__class__.__name__}")
```don't have the plugin yet? install it then click "run inline in claude" again.