Juddlyfire01/x-timeline-scraper

# x-timeline-scraper 抓取任何公开 X (Twitter) 账号的最近时间线，并保存为 JSONL 文件以便进行离线分析。使用 [Twikit](https://github.com/d60/twikit) —— 无需开发者 API 密钥；您只需作为普通登录用户进行一次身份验证，随后会话将通过 `cookies.json` 被重复使用。 本仓库包含五个小型脚本，构成一个完整的处理流程： ### 抓取器 | 脚本 | 抓取内容 | |---|---| | `scrape_timeline.py` | 仅包含顶层推文（时间线视图） | | `scrape_timeline_with_replies.py` | 推文 + 通过 `Replies` 端点获取的回复（捕获话题延续） | | `scrape_timeline_complete.py` | 两个端点，去重并按最新排序 —— 推荐用于获取完整语料库 | ### 后处理器 | 脚本 | 用途 | |---|---| | `organize_threads.py` | 将账号的自回复拼接回重建的话题中，并带有 `[1/N]` 编号。 | | `extract_tweet_text.py` | 将 JSONL 精简为纯净的纯文本（每个段落一条推文），供 LLM / 语料库 / embedding 使用。 | ## 设置 ``` python -m venv .venv # Windows PowerShell: . .venv/Scripts/Activate.ps1 # macOS/Linux: source .venv/bin/activate pip install -r requirements.txt ``` ## 凭证 将 `.env.example` 复制到 `.env` 并填入您的 X 登录信息（或者将变量导出到您的 shell 中）。这些是**您的**登录凭证 —— 它们被 Twikit 用于在首次运行时执行真实登录。随后，会话 cookie 将被写入 `cookies.json` 并在后续运行中重复使用。 ``` X_USERNAME=your_handle X_EMAIL=login_email@example.com X_PASSWORD=your_password ``` PowerShell: ``` $env:X_USERNAME = "your_handle" $env:X_EMAIL = "login_email@example.com" $env:X_PASSWORD = "your_password" ``` `.env`、`cookies.json` 以及 `data/` 目录均已被 gitignore 忽略。 **切勿将它们提交到代码仓库。** ## 用法 ### 1. 抓取 ``` # 过去 365 天的顶级推文： python scrape_timeline.py SomeAccount # 自定义时间窗口 + 自定义输出路径： python scrape_timeline.py SomeAccount --days 90 --out data/sample.jsonl # 推文 + 回复（保留 threads）： python scrape_timeline_with_replies.py SomeAccount --days 365 # 完整语料库（推荐）： python scrape_timeline_complete.py SomeAccount --days 365 ``` 默认输出路径： - `data/_tweets_d.jsonl` - `data/_tweets_replies_d.jsonl` - `data/_complete_d.jsonl` ### 2. 重建话题（可选） 如果您抓取了回复，可以将自回复组合成正确的话题： ``` python organize_threads.py data/someaccount_complete_365d.jsonl ``` 生成内容： - `data/someaccount_complete_365d_organized.jsonl` —— 结构化记录 - `data/someaccount_complete_365d_threads_text.txt` —— 带有 `[1/N]` 编号的可读文本 您可以使用 `--out-jsonl` 和 `--out-text` 覆盖默认路径。 ### 3. 提取纯净文本（可选） 供语料库 / LLM / embedding 使用： ``` python extract_tweet_text.py data/someaccount_tweets_365d.jsonl ``` 生成 `data/someaccount_tweets_365d_clean.txt` —— 每个段落一条推文，过滤掉转推和回复，剥离 URL 和 `RT @` 前缀，丢弃过短的片段（默认 `--min-len 10`）。 ## 输出格式 ### 抓取器 JSONL —— 每行一个 JSON 对象 ``` { "id": "1234567890", "created_at": "Wed Mar 12 14:22:00 +0000 2026", "text": "...", "lang": "en", "is_retweet": false, "in_reply_to_status_id": null, "type": "tweet" } ``` `type`（`"tweet"` 或 `"reply"`）仅存在于 `scrape_timeline_complete.py` 的输出中。 `is_reply` 仅存在于 `scrape_timeline_with_replies.py` 的输出中。 ### `organize_threads.py` JSONL ``` {"type": "standalone", "tweet": {...}} {"type": "thread", "thread_id": "...", "tweet_count": 14, "tweets": [...]} ``` 话题内部按最旧优先排序（发布顺序）；整个文件则按话题根节点按最新优先排序。 ## 注意事项与警告 - **尊重平台服务条款和速率限制。** 抓取器在每次请求页面之间默认休眠 1.5 秒。如果触发限制，请增加休眠时间或减少 `--days` 窗口期。 - **登录挑战。** 如果 X 向您提供了验证码或双重认证（2FA）提示，请先在浏览器中登录一次账号，然后重新运行脚本。Twikit 将复用该会话。 - **依赖安全性。** `twikit` 是一个自动化 X Web 客户端的第三方库。如果可能，请使用专用/一次性账号 —— 过去曾有因大量抓取而导致账号被封禁的情况。 - **仅限公开数据。** 这些脚本仅访问对登录用户公开可见的推文。 - **话题重建仅限作者本人。** `organize_threads.py` 仅检测作者回复自己的话题。与其他用户的对话不会被拼接。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：API绕过, ESC4, JSONL格式, LLM数据集, OSINT, Python, Twikit, Twitter, URL抓取, Web爬虫, X平台, 会话Cookie, 帖子抓取, 推特爬虫, 数据抓取, 数据清洗, 数据管道, 文本提取, 无API密钥, 无后门, 时序数据库, 模拟器, 社交媒体采集, 离线分析, 自回复拼接, 舆情分析, 语料库构建, 软件工程, 逆向工具