Metadata-Version: 2.4
Name: fusion-crawler
Version: 0.1.0
Summary: FusionCrawler - 统一的 AI 驱动全栈爬虫平台
Author: FusionCrawler Team
License: MIT
Project-URL: Homepage, https://github.com/fusion-crawler/fusion-crawler
Project-URL: Repository, https://github.com/fusion-crawler/fusion-crawler
Project-URL: Bug Tracker, https://github.com/fusion-crawler/fusion-crawler/issues
Keywords: crawler,web-scraping,ai-agent,llm,browser-automation,spider,data-extraction,anti-detection
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: anyio>=4.0
Requires-Dist: pydantic>=2.0
Requires-Dist: playwright>=1.40
Requires-Dist: curl-cffi>=0.7
Requires-Dist: httpx>=0.27
Requires-Dist: parsel>=1.9
Requires-Dist: lxml>=5.0
Requires-Dist: litellm>=1.40
Requires-Dist: aiosqlite>=0.20
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: websockets>=12.0
Requires-Dist: typer>=0.9
Requires-Dist: structlog>=24.0
Requires-Dist: rich>=13.0
Requires-Dist: bloom-filter2>=0.1
Requires-Dist: Pillow>=10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: orjson>=3.9
Requires-Dist: cachetools>=5.3
Provides-Extra: stealth
Requires-Dist: cloakbrowser>=0.3; extra == "stealth"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Requires-Dist: hiredis>=2.0; extra == "redis"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == "postgres"
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == "s3"
Provides-Extra: all
Requires-Dist: fusion-crawler[stealth]; extra == "all"
Requires-Dist: fusion-crawler[redis]; extra == "all"
Requires-Dist: fusion-crawler[postgres]; extra == "all"
Requires-Dist: fusion-crawler[s3]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: pre-commit>=3.6; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# FusionCrawler

统一的 AI 驱动全栈爬虫平台，融合 Scrapling / Firecrawl / MediaCrawler / Crawl4AI / EasySpider / CloakBrowser 六个顶级开源项目的核心能力。

## 六层架构

```
Layer 0: 基础设施层    — 存储 / 缓存 / 代理 / 日志 / 配置
Layer 1: 浏览器引擎层  — HTTP / Playwright / CloakBrowser 三引擎
Layer 2: 内容处理层    — 自适应解析 / LLM 提取 / 过滤 / 格式转换
Layer 3: 智能调度层    — AI Agent / 任务调度 / 爬取策略 / 断点续爬
Layer 4: 用户交互层    — API / SDK / CLI / 可视化设计器
Layer 5: 平台适配层    — 通用 Web + 10 个主流平台适配器
```

## 平台适配层

支持 10 个主流平台 + 通用 Web 适配器：

| 平台 | 类型 | 数据源 | 登录要求 |
|------|------|--------|---------|
| 通用 Web | 任意网站 | CSS 选择器解析 | 可选 |
| 微博 | 中文社交 | m.weibo.cn API + HTML 解析 | Cookie |
| 知乎 | 中文问答 | 页面 JSON 嵌入数据 | Cookie |
| 微信公众号 | 中文媒体 | 搜狗微信搜索 + 文章解析 | Cookie |
| 小红书 | 中文社交 | 笔记页解析 + API | Cookie + 签名 |
| B站 | 视频平台 | 公开 REST API | 无 |
| 抖音 | 短视频 | 页面 SSR 数据 + 评论 API | Cookie |
| Twitter/X | 国际社交 | HTML Meta 解析 | Cookie |
| YouTube | 视频平台 | ytInitialPlayerResponse 解析 | 无 |
| Reddit | 论坛社区 | 公开 JSON API | 无 |
| 今日头条 | 新闻资讯 | 页面 SSR 数据 | Cookie |

## 快速开始

### 安装

```bash
pip install -e ".[dev]"
```

### Python SDK

```python
from fusion_crawler import FusionCrawler

client = FusionCrawler()
result = client.scrape("https://example.com")
print(result.markdown)
```

### 平台适配器使用

```python
from fusion_crawler.platform.registry import AdapterRegistry

registry = AdapterRegistry()

# 根据 URL 自动匹配适配器
adapter = registry.match_url("https://weibo.com/123")
if adapter:
    post = await adapter.get_post_detail("123")
    print(post.title, post.content[:100])

# 搜索内容
bilibili = registry.get("bilibili")
videos = await bilibili.search("Python教程")
for v in videos:
    print(v.title, v.url)
```

### CLI

```bash
# 爬取网页
fusion-crawler https://example.com

# 使用特定平台适配器
fusion-crawler --platform weibo "关键词"

# 启动 API 服务
fusion-crawler api
# 访问 http://localhost:8000/docs
```

### API 服务

```bash
fusion-crawler api
curl http://localhost:8000/api/v1/health
```

## LLM 补充模块

FusionCrawler 提供四个可选 LLM/Agent 增强模块：

| 模块 | 功能 |
|------|------|
| SchemaValidator | JSON Schema 校验、类型强制转换、默认值填充、从数据推断 Schema |
| LLMCostController | Token 用量追踪、预算控制、熔断机制、模型选择推荐 |
| CrawlResumeManager | SQLite 断点续爬、检查点管理、自动保存 |
| ToolRegistry | AI Agent 工具注册中心、@register 装饰器、OpenAI/Anthropic 格式转换 |

```python
from fusion_crawler.processing.llm.schema import SchemaValidator
from fusion_crawler.processing.llm.cost_controller import LLMCostController
from fusion_crawler.orchestrator.resume_manager import CrawlResumeManager
from fusion_crawler.orchestrator.tool_registry import ToolRegistry, ToolParameter

# Schema 校验
validator = SchemaValidator()
report = validator.validate([{"name": "Alice", "age": "30"}],
    {"properties": {"name": {"type": "string"}, "age": {"type": "integer"}}})
print(report.valid)  # True (age 自动从 string 转为 int)

# LLM 成本控制
controller = LLMCostController(monthly_budget_usd=50.0)
controller.track_call("gpt-4o-mini", prompt_tokens=500, completion_tokens=200)
print(controller.stats().total_cost)

# 断点续爬
manager = CrawlResumeManager()
await manager.initialize()
task_id = await manager.save_checkpoint(Checkpoint(
    task_id="task-1", seed_urls=["https://example.com"],
    visited_urls={"https://example.com/a"}, pending_urls=["https://example.com/b"],
))

# 工具注册
registry = ToolRegistry()
@registry.register(name="scrape", description="抓取页面",
    parameters=[ToolParameter(name="url", type="string", required=True)])
async def scrape(url: str) -> dict:
    return {"url": url, "status": 200}
```

## 测试

```bash
# 全量测试（936 用例）
python -m pytest tests/ -v

# 仅平台适配层测试
python -m pytest tests/platform/ -v

# 指定模块测试
python -m pytest tests/processing/llm/ tests/orchestrator/ -v

# 集成测试
python -m pytest tests/test_platform_integration.py -v
```

## Docker 部署

### 快速启动（单命令）

```bash
# 1. 复制环境配置
cp .env.example .env

# 2. 构建并启动
make deploy
# 或: docker-compose up -d

# 3. 访问 http://localhost:8000
```

### 含 Nginx 反向代理

```bash
make up-nginx
# 或: docker-compose --profile with-nginx up -d
```

### 生产环境部署

```bash
# 完全重建（无缓存）
make deploy-clean

# 查看日志
make logs

# 进入容器
make shell
```

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `FUSION_CRAWLER_PORT` | 8000 | 服务端口 |
| `FUSION_CRAWLER_WORKERS` | 2 | Uvicorn 工作进程数 |
| `FUSION_CRAWLER_REDIS_URL` | redis://redis:6379/0 | Redis 连接 |
| `FUSION_CRAWLER_DATABASE_URL` | sqlite:///data/db.sqlite | 数据库连接 |
| `FUSION_CRAWLER_LOG_LEVEL` | info | 日志级别 |

## 前端开发

```bash
cd frontend
npm install
npm run dev     # 开发模式，端口 5173
npm run build   # 生产构建
```

## 项目结构

```
fusion-crawler/
├── fusion_crawler/          # 核心 Python 包
│   ├── api/                 # API 服务层（FastAPI）
│   ├── cli/                 # CLI 命令行（Typer）
│   ├── core/                # 核心接口 / 数据模型 / 异常体系
│   ├── orchestrator/        # 智能调度层（策略 / Agent / 工具注册 / 断点续爬）
│   ├── processing/          # 内容处理层（解析 / 过滤 / LLM 提取 / 格式转换）
│   ├── browser/             # 浏览器引擎层（HTTP / Playwright / 反检测）
│   ├── platform/            # 平台适配层（11 个适配器）
│   └── infrastructure/      # 基础设施层（存储 / 缓存 / 代理 / 日志）
├── frontend/                # 可视化设计器（React + Vite + TypeScript）
├── tests/                   # 测试（936 用例，覆盖所有模块）
├── docs/                    # 文档
├── deploy/                  # 部署配置（Docker 入口 / Nginx）
├── .github/workflows/       # CI/CD 工作流
├── pyproject.toml           # 项目配置与依赖管理
└── docker-compose.yml       # 容器化部署
```

## 开发阶段

| 阶段 | 状态 |
|------|------|
| Phase 0: 基础设施 | ✅ 100% |
| Phase 1: 浏览器引擎 | ✅ 100% |
| Phase 2: 内容处理 | ✅ 100% |
| Phase 3: 智能调度 | ✅ 100% |
| Phase 4: 交互层 | ✅ 100% |
| Phase 5: 可视化设计器 | 🚧 Scaffold（React/Vite 骨架就绪） |
| Phase 6: 平台适配层 | ✅ 100% |
| Phase 7: 集成测试 | ✅ 100% |
| Phase 8: 文档与发布 | 🚧 In Progress |

## 许可证

MIT
