# exotic-amazon-v2

**Repository Path**: elfbobo_admin_admin/exotic-amazon-v2

## Basic Information

- **Project Name**: exotic-amazon-v2
- **Description**: AI Agent 驱动的 Amazon 数据采集系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-22
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Exotic Amazon V2

AI Agent 驱动的 Amazon 数据采集系统，基于 Browser4 SDK 实现智能调度、多层提取与反反爬。

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| Java | 17 | LTS |
| Kotlin | 2.1.21 | 协程 + Spring 全支持 |
| Spring Boot | 3.5.13 | Web + Data + Actuator |
| Browser4 | 4.6.0 | pulsar-boot + pulsar-rest + pulsar-agentic |
| MongoDB | 7.x | 任务/产品/规则持久化 |
| Redis | 7.x | 限流/缓存/去重 |

## 架构

```
                    ┌─────────────────────────────────────────┐
                    │              REST API (:8182)            │
                    │  /v2/crawl  /v2/data  /v2/system         │
                    └──────────────┬──────────────────────────┘
                                   │
                    ┌──────────────▼──────────────────────────┐
                    │          SmartScheduler                 │
                    │  轮询PENDING → 原子占位RUNNING → 分发   │
                    └──────────────┬──────────────────────────┘
                                   │
                    ┌──────────────▼──────────────────────────┐
                    │        Browser4CrawlEngine               │
                    │  Semaphore限流 → 6阶段Pipeline           │
                    └──┬────────┬─────────┬──────────┬───────┘
                       │        │         │          │
              ┌────────▼┐ ┌─────▼────┐ ┌──▼──────┐ ┌▼────────┐
              │ loadPage │ │ Extract  │ │ Quality │ │ Persist │
              │ Browser4 │ │ 3层智能  │ │  质检   │ │ MongoDB │
              └─────────┘ └──────────┘ └─────────┘ └─────────┘
```

### 三层智能提取 (AUTO_FALLBACK)

```
Layer 1: Auto Extraction  ──confidence≥0.95──▶  直接采用
              │
              ▼ (不达标)
Layer 2: LLM Extraction   ──confidence≥0.85──▶  合并 Auto + LLM
              │
              ▼ (不达标)
Layer 3: X-SQL Fallback   ──────────────────▶  合并全部，兜底
```

支持 5 种提取策略：`AUTO_FALLBACK` | `AUTO_ONLY` | `LLM_ONLY` | `XSQL_ONLY` | `LLM_AUTO_HYBRID`

## 项目结构

```
src/main/kotlin/ai/platon/exotic/v2/
├── ExoticAmazonV2Application.kt          # Spring Boot 入口
├── agent/                                 # AI Agent 层
│   ├── core/CrawlAgent.kt                #   Agent 接口与实现
│   ├── planner/TaskPlanner.kt            #   任务规划器
│   ├── tools/AgentTools.kt               #   Agent 工具集
│   └── validator/ResultValidator.kt      #   结果验证器
├── api/                                   # API 层
│   ├── rest/CrawlController.kt           #   爬虫任务 API
│   ├── rest/DataController.kt            #   数据查询 API
│   ├── rest/SystemController.kt          #   系统管理 API
│   ├── websocket/CrawlWebSocketHandler.kt#   WebSocket 实时推送
│   └── cli/CrawlCliRunner.kt             #   CLI 命令行入口
├── browser/                               # 浏览器层
│   ├── pool/BrowserPool.kt               #   Browser4 会话池
│   ├── pool/PulsarBrowserSession.kt      #   PulsarRPA 会话封装
│   ├── privacy/PrivacyContextManager.kt   #   隐私上下文管理
│   └── stealth/                           #   反检测 (指纹/行为模拟)
├── core/                                  # 核心业务层
│   ├── engine/Browser4CrawlEngine.kt      #   爬虫引擎 (6阶段Pipeline)
│   ├── extractor/SmartExtractionService.kt#   智能提取调度
│   ├── scheduler/SmartScheduler.kt        #   智能调度器
│   ├── pipeline/DefaultDataPipeline.kt    #   数据持久化管道
│   ├── quality/QualityAssurance.kt        #   质量保证
│   └── proxy/ProxyManager.kt             #   代理池管理
├── extraction/                            # 提取器实现
│   ├── auto/                              #   Auto Extraction (ML字段发现)
│   ├── llm/                               #   LLM Extraction (大模型)
│   └── xsql/                              #   X-SQL 兼容层
├── infrastructure/                        # 基础设施层
│   ├── persistence/                       #   MongoDB Repository
│   ├── cache/                             #   Redis 缓存/去重
│   ├── messaging/EventPublisher.kt        #   事件发布
│   └── monitoring/                        #   健康检查/指标/告警
└── shared/                                # 共享层
    ├── model/                             #   领域模型 (CrawlTask/Product/Review/Seller)
    ├── config/AppProperties.kt            #   配置属性
    └── util/                              #   工具类
```

## 快速开始

### 前置依赖

- JDK 17+
- MongoDB 7.x (本地 `127.0.0.1:27017`)
- Redis 7.x (本地 `127.0.0.1:6379`)
- Chrome 浏览器 (Browser4 自动发现)

### 构建与运行

```bash
# 测试
mvn test

# 构建
mvn clean package -DskipTests

# 开发模式 (GUI浏览器, 1个隐私上下文)
java -jar target/exotic-amazon-v2-2.0.0-SNAPSHOT.jar --spring.profiles.active=dev

# 生产模式 (Headless, 5个隐私上下文)
java -jar target/exotic-amazon-v2-2.0.0-SNAPSHOT.jar --spring.profiles.active=prod
```

项目内已提供 `.mvn/maven.config`，Maven 会默认加载 `.mvn/settings.xml` 中的镜像配置，通常不需要手动追加 `-s .mvn/settings.xml`。

### 回归验证

```bash
# P0 回归烟测：覆盖有 Seller / 无 Seller 两类样本
pwsh -File scripts/regression-smoke.ps1
```

### 环境变量

| 变量 | 必需 | 说明 |
|------|------|------|
| `LLM_API_KEY` | 是 | 大模型 API Key (默认阿里云 DashScope) |
| `LLM_BASE_URL` | 否 | 大模型 API 地址 |
| `QCC_ENABLED` | 否 | 是否启用企查查公开信息增强 |
| `QCC_APP_KEY` | 否 | 企查查开放平台 AppKey |
| `QCC_SECRET_KEY` | 否 | 企查查开放平台 SecretKey |
| `QCC_MOCK_MODE` | 否 | Mock 场景：`OFF/HIGH_MATCH/LOW_MATCH/NO_MATCH/ERROR` |

## API 参考

### 爬虫任务

```bash
# 提交ASIN详情采集
curl -X POST http://localhost:8182/api/v2/crawl/tasks \
  -H "Content-Type: application/json" \
  -d '{"taskType":"ASIN_DETAIL","targetUrl":"https://www.amazon.com/dp/B08PNWG993"}'

# 提交自然语言任务
curl -X POST http://localhost:8182/api/v2/crawl/instructions \
  -H "Content-Type: application/json" \
  -d '{"instruction":"采集该商品的价格和评论数"}'

# 批量提交
curl -X POST http://localhost:8182/api/v2/crawl/tasks/batch \
  -H "Content-Type: application/json" \
  -d '[{"taskType":"ASIN_DETAIL","targetUrl":"https://www.amazon.com/dp/B08PNWG993"},
       {"taskType":"BEST_SELLERS","targetUrl":"https://www.amazon.com/Best-Sellers/zgbs"}]'

# 查询任务状态
curl http://localhost:8182/api/v2/crawl/tasks/{taskId}

# 查看队列状态
curl http://localhost:8182/api/v2/crawl/queue/status

# 调度器暂停/恢复
curl -X POST http://localhost:8182/api/v2/crawl/scheduler/pause
curl -X POST http://localhost:8182/api/v2/crawl/scheduler/resume
```

### 数据查询

```bash
# 产品列表
curl http://localhost:8182/api/v2/data/products?page=0&size=20

# 按ASIN查询产品
curl http://localhost:8182/api/v2/data/products/B08PNWG993

# 查询评论
curl http://localhost:8182/api/v2/data/reviews?asin=B08PNWG993

# 查询卖家详情
curl http://localhost:8182/api/v2/data/sellers/A330MMJQNRFB32?tld=com

# 查询卖家公开企业信息
curl http://localhost:8182/api/v2/data/sellers/A330MMJQNRFB32/public-profile?tld=com

# 手动触发卖家公开企业信息增强
# QCC_ENABLED=false 时返回 SKIPPED，但仍保留查询关键词与匹配评分链路
# QCC_CONTACT_DISPLAY_THRESHOLD 默认 0.75，低于阈值时隐藏电话/邮箱/网站，仅保留 rawData
curl -X POST http://localhost:8182/api/v2/data/sellers/A330MMJQNRFB32/public-profile?tld=com

# 不改配置，直接用接口参数演练高分命中
curl -X POST "http://localhost:8182/api/v2/data/sellers/A330MMJQNRFB32/public-profile?tld=com&mockMode=HIGH_MATCH"

# 演练低分命中：会生成联系方式原始值，但接口响应中默认隐藏
curl -X POST "http://localhost:8182/api/v2/data/sellers/A330MMJQNRFB32/public-profile?tld=com&mockMode=LOW_MATCH"

# 清理脏数据 (删除全部产品/任务/规则)
curl -X DELETE http://localhost:8182/api/v2/data/cleanup
```

### 系统管理

```bash
# 健康检查
curl http://localhost:8182/api/v2/system/health

# 系统指标
curl http://localhost:8182/api/v2/system/metrics
```

## 任务类型

| TaskType | 说明 | 级联 |
|----------|------|------|
| `BEST_SELLERS` | 畅销榜 | → ASIN_DETAIL |
| `MOST_WISHED_FOR` | 心愿单 | → ASIN_DETAIL |
| `NEW_RELEASES` | 新品榜 | → ASIN_DETAIL |
| `MOVERS_SHAKERS` | 飙升榜 | → ASIN_DETAIL |
| `ASIN_DETAIL` | 产品详情 | → REVIEW |
| `SELLER_DETAIL` | 卖家详情 | - |
| `REVIEW` | 产品评论 | - |
| `PRICE_MONITOR` | 价格监控 | - |
| `CUSTOM` | 自然语言自定义 | - |

## 配置项

| 配置 | 默认值 | 说明 |
|------|--------|------|
| `server.port` | 8182 | HTTP 端口 |
| `exotic.scheduler.enabled` | true | 是否启用调度器 |
| `exotic.scheduler.max-domain-qps` | 2 | 单域名 QPS 上限 |
| `exotic.extraction.strategy` | AUTO_FALLBACK | 默认提取策略 |
| `exotic.extraction.auto.confidence-threshold` | 0.95 | Auto 提取置信度阈值 |
| `exotic.extraction.llm.confidence-threshold` | 0.85 | LLM 提取置信度阈值 |
| `exotic.llm.model` | qwen3.5-plus | 大模型名称 |
| `browser4.display.mode` | GUI/HEADLESS | 浏览器显示模式 |
| `browser4.privacy.context.number` | 1/5 | 隐私上下文数 |

## License

Apache License 2.0