Metadata-Version: 2.4
Name: x-scraper-tool
Version: 0.1.0
Summary: A tool for scraping user data from X (Twitter)
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: twscrape>=0.17
Description-Content-Type: text/markdown

# X (Twitter) Scraper

基于 [twscrape](https://github.com/vladkens/twscrape) 的 X (Twitter) 数据爬取工具，支持用户资料、推文、粉丝列表和互动数据的抓取，输出为 JSON 或 CSV。

## 功能

- 用户资料（profile）爬取
- 用户推文时间线（最多 3200 条，X API 硬限制）
- 粉丝列表（followers）和关注列表（following）
- 推文回复（replies）和转推用户（retweeters）
- 多账号自动轮换，cookie 导入绕过 CAPTCHA
- JSON / CSV 双格式输出

## 前置条件

- Python >= 3.11
- [uv](https://github.com/astral-sh/uv) 包管理器
- 至少一个 X 账号的 cookie（非主账号）

## 安装

```bash
git clone https://github.com/ChaNg1o1/x-scraper.git
cd x-scraper
uv sync
```

## 配置

复制示例配置并填入你的账号 cookie：

```bash
cp config.example.toml config.toml
```

编辑 `config.toml`：

```toml
[scraper]
output_dir = "./output"
request_delay = 1.5
max_tweets = 3200

[[accounts]]
username = "your_account"
cookies = "ct0=YOUR_CT0; auth_token=YOUR_AUTH_TOKEN"
# proxy = "http://user:pass@host:port"  # 可选
```

### 获取 Cookie

1. 在浏览器中登录 X
2. 打开 DevTools（F12）-> Application -> Cookies -> `https://x.com`
3. 复制 `ct0` 和 `auth_token` 的值

## 使用方法

```bash
# 爬取用户全部数据（资料 + 推文 + 粉丝 + 关注）
x-scraper scrape --user elonmusk --all

# 只爬取推文和粉丝
x-scraper scrape --user elonmusk --tweets --followers

# 爬取推文互动数据
x-scraper scrape --tweet 1234567890 --replies --retweeters

# 指定输出格式为 CSV
x-scraper scrape --user elonmusk --all --format csv

# 限制爬取数量
x-scraper scrape --user elonmusk --tweets --limit 100

# 使用指定配置文件
x-scraper scrape --config ./my_config.toml --user elonmusk --all

# 查看已配置账号
x-scraper accounts
```

## 输出结构

```
output/
  {username}/
    profile.json
    tweets.json
    followers.json
    following.json
  tweet_{id}/
    replies.json
    retweeters.json
```

## 项目结构

```
x-scraper/
  pyproject.toml
  config.example.toml
  src/x_scraper/
    cli.py          # CLI 入口（click）
    config.py       # TOML 配置加载
    auth.py         # 账号管理与 cookie 导入
    scraper.py      # 核心爬取逻辑
    models.py       # 数据模型（dataclass）
    export.py       # JSON/CSV 导出
  tests/
    test_models.py  # 数据模型单元测试
```

## 注意事项

- 请勿使用主账号，账号存在被封禁的风险
- X 的 ToS 禁止未授权的自动化访问，请自行承担使用风险
- X 的反爬策略大约每 2-4 周变更，工具可能需要随之调整
- 本工具已内置对 twscrape `xclid` 脚本解析错误的 monkey-patch 修复（[vladkens/twscrape#284](https://github.com/vladkens/twscrape/issues/284)）

## 许可证

MIT
