Metadata-Version: 2.4
Name: search-talent
Version: 0.1.1
Summary: LinkedIn Recruiter 搜索爬虫 & JSON 转 Excel 工具
Author-email: Chandler <275737875@qq.com>
License: MIT
Keywords: linkedin,recruiter,scraper,search,talent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: browser-dog>=0.1.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: selenium>=4.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# search-talent

[![PyPI version](https://img.shields.io/pypi/v/search-talent.svg)](https://pypi.org/project/search-talent/)
[![Python](https://img.shields.io/pypi/pyversions/search-talent.svg)](https://pypi.org/project/search-talent/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

基于 Selenium 的 LinkedIn Recruiter 搜索爬虫工具，可自动抓取候选人信息并导出为 Excel 文件。

## 功能特性

- **自动爬取**：模拟真人滚动行为，智能加载 LinkedIn Recruiter 搜索结果页的所有候选人信息。
- **结构化数据提取**：解析候选人姓名、头衔、地点、工作经历、教育背景、行业、关系度等字段。
- **断点续爬**：已保存的页面 JSON 文件会自动跳过，支持中断后继续爬取。
- **Excel 导出**：一键将 JSON 数据整理并导出为格式化的 `.xlsx` 文件，驼峰命名字段自动拆分，方便阅读。
- **CLI 驱动**：安装后直接通过终端命令 `search-talent` 运行，无需编写额外脚本。

## 安装

### 通过 pip 安装（推荐）

```bash
pip install search-talent
```

### 从源码安装

```bash
git clone https://github.com/your-username/search-talent.git
cd search-talent
pip install .
```

### 依赖项

安装时会自动安装以下依赖：

| 依赖 | 用途 |
|------|------|
| `typer` | CLI 框架 |
| `selenium` | 浏览器自动化 |
| `beautifulsoup4` | HTML 解析 |
| `pandas` | 数据处理 |
| `openpyxl` | Excel 文件读写（pandas 后端） |
| `browser-dog` | LinkedIn 登录与 Cookie 管理 |

> **注意**：运行爬虫需要本机已安装 Chrome/Chromium 浏览器及对应版本的 ChromeDriver。

## 前置准备

### Cookie 文件

本工具通过 Cookie 注入方式登录 LinkedIn Recruiter，你需要提前准备好一个 `cookie.json` 文件。

文件内容为 JSON 数组格式，每条记录是一个 Cookie 对象：

```json
[
  {
    "domain": ".linkedin.com",
    "name": "li_at",
    "value": "YOUR_COOKIE_VALUE",
    "path": "/",
    "secure": true,
    "httpOnly": true
  }
]
```

> **提示**：可使用浏览器扩展（如 EditThisCookie）导出已登录的 LinkedIn Cookie。

## CLI 使用指南

安装完成后，可在终端直接运行 `search-talent` 命令。

### 查看帮助

```bash
search-talent --help
```

### `scrape` 命令 - 爬取 LinkedIn 数据

从 LinkedIn Recruiter 搜索结果页爬取候选人信息，并保存为 JSON 文件。

```bash
search-talent scrape \
  --start-url "https://www.linkedin.com/talent/search?q=..." \
  --search-keyword "python-developer" \
  --folder ./output
```

**参数说明：**

| 参数 | 缩写 | 说明 | 默认值 |
|------|------|------|--------|
| `--start-url` | `-s` | LinkedIn Recruiter 搜索结果 URL（必填） | — |
| `--search-keyword` | `-k` | 搜索关键词，用于 JSON 文件命名（必填） | — |
| `--folder` | `-f` | 保存 JSON 文件的本地目录（必填） | — |
| `--cookie` | `-c` | Cookie JSON 文件路径 | `cookie.json` |
| `--scroll-times` | `-n` | 页面滚动次数 | `3` |
| `--max-pages` | `-m` | 最大爬取页数（不指定则不限制） | `None` |
| `--headless` | — | 以无头模式运行浏览器 | `False` |

**示例：**

```bash
# 爬取前 5 页，使用自定义 Cookie 文件
search-talent scrape \
  -s "https://www.linkedin.com/talent/search?q=engineer&location=China" \
  -k "engineer-china" \
  -f ./data/engineer-china \
  -c ~/linkedin_cookie.json \
  -m 5

# 无头模式运行
search-talent scrape \
  -s "https://www.linkedin.com/talent/search?q=..." \
  -k "my-search" \
  -f ./data \
  --headless
```

### `export` 命令 - 导出为 Excel

将 `scrape` 命令生成的 JSON 文件合并导出为一份 Excel 文件。

```bash
search-talent export \
  --input ./output \
  --output candidates.xlsx
```

**参数说明：**

| 参数 | 缩写 | 说明 | 默认值 |
|------|------|------|--------|
| `--input` | `-i` | 包含 JSON 文件的输入目录（必填） | — |
| `--output` | `-o` | 输出 Excel 文件路径（必填） | — |

**示例：**

```bash
search-talent export -i ./data/engineer-china -o engineer-china.xlsx
```

## 项目结构

```
search-talent/
├── pyproject.toml          # 项目配置与构建定义
├── README.md
└── src/
    └── search_talent/
        ├── __init__.py     # 包入口，版本信息
        ├── scraper.py      # LinkedIn 爬虫核心模块
        ├── reader.py       # JSON 读取与 Excel 导出模块
        └── cli.py          # Typer CLI 入口
```

## 注意事项

- **合规使用**：请遵守 LinkedIn 的使用条款，合理控制爬取频率和数量，避免账号被封禁。
- **Cookie 有效期**：LinkedIn Cookie 会过期，若登录失败请重新导出 Cookie 文件。
- **反爬机制**：工具内置了随机等待、拟人滚动等反检测策略，但仍建议控制爬取速度。
- **ChromeDriver 版本**：请确保本机 ChromeDriver 版本与 Chrome 浏览器版本匹配。

## 许可证

[MIT License](https://opensource.org/licenses/MIT)
