# UAE Contact Crawler

**Repository Path**: lainyu/uae-contact-crawler

## Basic Information

- **Project Name**: UAE Contact Crawler
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-20
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UAE Contacts Crawler

一个基于 LangGraph 和 AI 的智能联系信息爬虫系统，专门用于从阿联酋企业网站中提取联系信息和商业数据。

## 📋 功能概述

### 核心功能
- 📧 **联系信息提取**: 邮箱、电话、WhatsApp
- 🌐 **社交媒体**: Facebook、LinkedIn、Twitter 等平台链接
- 🏢 **商业信息**: 公司规模、业务范围、行业信息
- 📍 **地理信息**: 公司地址和位置信息
- 🔄 **智能补充**: 自动探索相关页面获取更完整信息

### 工作流程

```mermaid
flowchart TD
    A([开始]) --> B[初始化队列 含初始URL depth 0]

    B --> C{队列为空?}
    C -->|是| Z[结束 输出已收集JSON 写入数据库]
    C -->|否| D[弹出下一个URL]

    D --> E[调用工具: Selenium 获取HTML]
    E --> F{返回状态200且包含HTML?}
    F -->|否| C
    F -->|是| G[HTML预处理: 去除CSS/style/script等垃圾标签]
    
    %% === 前置信息提取 ===
    G --> G1[提取联系信息: 邮箱/电话/社交媒体链接]
    G1 --> G2[提取页面链接: Contact/About/Team等关键页面]
    G2 --> G3{前置提取结果是否为空?}
    G3 -->|是| G6[跳过AI分析直接输出空结果JSON]
    G3 -->|否| G4{联系信息是否完整?}
    G4 -->|否| G5[爬取关键页面补充联系信息]
    G5 --> G7[整合所有联系信息]
    G4 -->|是| G7
    G7 --> H[将预处理结果传递给Agent]
    G6 --> Y

    %% === Agent 专注商业信息提取 ===
    H --> I([Agent节点: 专注提取公司商业信息])
    I --> I1[分析公司业务范围和规模]
    I1 --> I2[提取公司描述和行业信息]
    I2 --> I3[获取公司位置和其他商业信息]
    I3 --> J[整合联系信息和商业信息]
    J --> K{商业信息完整性评分>=3分?}
    K -->|是| Y[输出完整JSON 写入数据库]

    K -->|否| L[Agent智能补充: 寻找更多商业信息]
    L --> L1[使用crawl_html_with_selenium获取补充页面]
    L1 --> L2[分析补充页面的商业信息]
    L2 --> M{补充后商业信息完整性>=3分?}
    M -->|是| Y
    M -->|否| N[输出当前可用信息的JSON]
    N --> Y

```

## 🛠️ 技术栈

- **Python 3.13+**: 主要开发语言
- **LangGraph**: AI 工作流引擎
- **SQLAlchemy**: ORM 数据库操作
- **Selenium**: 无头浏览器自动化
- **BeautifulSoup**: HTML 解析
- **Pandas**: 数据处理
- **OpenAI API**: AI 模型调用（硅基流动）

## 📦 安装与配置

### 环境要求
- Python 3.13+
- Chrome 浏览器（用于 Selenium）
- uv 包管理器

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd UAE_Contacts_Crawler
```

2. **安装依赖**
```bash
uv sync
```

3. **配置环境变量**
修改 `src/config_example.py` 文件为`src/config.py`，配置 API 密钥.

4. **初始化数据库**
```bash
uv run python scripts/export_to_db.py
```

## 🚀 使用方法

### 主程序运行

```bash
# 单个文件处理（强制覆盖）
uv run python src/main.py 1

# 批量处理指定索引
uv run python src/main.py 1,2,3,4,5

# 处理所有HTML文件
uv run python src/main.py all
```

### 独立脚本使用

#### 1. 数据导入脚本
```bash
# 从Excel文件导入联系人数据到数据库
uv run python scripts/export_to_db.py
```

#### 2. HTML爬取脚本
```bash
# 批量爬取数据库中所有URL的HTML内容
uv run python scripts/crawl_html.py
```

#### 3. 数据库操作脚本
```bash
# 数据库管理和查询操作
uv run python scripts/db_helpler.py
```

## 📁 项目结构

```
UAE_Contacts_Crawler/
├── src/                    # 核心源代码
│   ├── main.py            # 主程序入口
│   ├── workflow.py        # LangGraph 工作流定义
│   ├── config.py          # 配置文件
│   ├── nodes.py           # 工作流节点实现
│   ├── states.py          # 状态管理
│   ├── tools.py           # 工具函数
│   └── utils/             # 工具模块
│       └── logger.py      # 日志配置
├── scripts/               # 独立处理脚本
│   ├── crawl_html.py      # HTML爬取脚本
│   ├── db_helpler.py      # 数据库操作脚本
│   └── export_to_db.py    # Excel数据导入脚本
├── docs/                  # 项目文档
│   ├── develop_introduction.md  # 开发文档
│   └── project_introduction.md  # 项目介绍
├── data/                  # 数据目录
│   ├── html_cache/        # HTML缓存文件
│   ├── results/           # 处理结果
│   └── uae_contacts.db    # SQLite数据库
├── files/                 # Excel源文件
├── pyproject.toml         # 项目配置
└── README.md             # 项目说明
```

## 💾 数据库结构

### contacts 表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键，自动增长 |
| url | String(500) | 联系人URL（唯一） |
| url_phone | String(50) | 网址里爬取的联系电话 |
| has_whatsapp | String(10) | 是否有WhatsApp |
| remarks | Text | 备注 |
| email | String(200) | 对应网址的邮箱 |
| social_media | String(500) | 社交媒体信息 |
| contact_remarks | Text | 联系信息备注 |
| other_remarks | Text | 公司相关信息（规模、业务范围等） |
| updated | DateTime | 更新时间 |

### company 表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| contacts_id | Integer | 关联contacts表 |
| map_coordinate | String | 地图坐标 |
| company_name | String | 公司名称 |
| industry | String | 行业 |
| phone | String | 电话 |
| address | Text | 地址 |
| country | String | 国家 |

## 🔧 配置说明

### AI 模型配置
- **模型**: Qwen/Qwen3-235B-A22B
- **API提供商**: 硅基流动 (https://www.siliconflow.cn/)
- **上下文长度**: 无限制
- **准确性**: 高精度商业信息提取

### 爬取策略
- **最大深度**: 3层
- **单域名页面限制**: 10个
- **搜索策略**: 广度优先
- **智能终止**: 信息完整性评分机制

## 📊 输出格式

处理结果以JSON格式保存在 `data/results/` 目录下：

```json
{
  "url": "https://example.com",
  "emails": ["contact@example.com"],
  "phones": ["+971-xxx-xxxx"],
  "social_media": {
    "facebook": "https://facebook.com/company",
    "linkedin": "https://linkedin.com/company/example"
  },
  "company_info": {
    "name": "Example Company",
    "industry": "Technology",
    "size": "50-100 employees",
    "description": "Leading tech company..."
  },
  "processed_files": 3,
  "has_company_info": true
}
```

## 🐛 故障排除

### 常见问题

1. **Chrome驱动问题**
   - 确保安装了Chrome浏览器
   - 检查Selenium版本兼容性

2. **API调用失败**
   - 验证API密钥配置
   - 检查网络连接

3. **数据库连接错误**
   - 确保数据库文件路径正确
   - 检查文件权限

### 日志查看
日志采用标签化格式：`[emoji标签] 消息内容`
- `[🔍]` - 信息提取和搜索相关
- `[📋]` - 数据预处理和验证
- `[🔗]` - 链接提取和处理
- `[🕷️]` - 网页爬取相关
- `[🤖]` - AI Agent处理
- `[📁]` - 文件处理相关
- `[✅]` - 成功操作
- `[❌]` - 错误信息
- `[⚠️]` - 警告信息
- `[CLEANUP]` - 日志清理
- `[AGENT_TOOL_DEBUG]` - Agent工具调试

## 🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

---

**注意**: 请遵守目标网站的robots.txt和使用条款，合理使用爬虫功能。