xhs-batch-crawler

name	xhs-batch-crawler
description	小红书批量爬虫（反爬感知版）。在 xiaohongshu-skills 基础上增加批量抓取能力， 自动处理反爬验证码、智能退避、断点续爬、进度持久化。 当用户要求批量浏览/分析小红书博主的帖子、评论、或需要连续抓取多篇笔记时触发。 单篇笔记抓取仍使用 xiaohongshu-skills 的 get-feed-detail。

小红书批量爬虫（反爬感知版）

基于 xiaohongshu-skills CLI 的高层批量抓取框架。解决连续调用 CLI 导致小红书触发扫码验证的问题。

问题背景

小红书的反爬机制检测短时间内的连续页面导航。xiaohongshu-skills 的 get-feed-detail 每次调用都会 navigate 到新 URL，连续 8-15 次后几乎必定触发扫码验证。

反爬特征：

• 触发条件：短时间内 navigate 次数过多（阈值约 10-20 次/5分钟）
• 验证类型：扫码验证（需要手机 App 扫码，无法自动解决）
• 恢复方式：用户在 Chrome 手动扫码后可继续

核心策略

1. 分批 + 长间隔

批次大小: 5-8 篇（随机）
批次间隔: 60-120 秒（随机）
请求间隔: 8-15 秒（随机，而非原来的 2-4 秒）

2. 验证码检测与自动暂停

每次请求后检测返回是否包含验证码错误。一旦检测到：

• 立即暂停，通知用户在 Chrome 中手动扫码
• 用户确认后，先用一篇已知的帖子测试恢复
• 恢复成功后自动继续，并将批次大小减半

3. 断点续爬

进度保存到 JSON 文件，支持中断后从上次位置继续：

{
  "target": "user_profile",
  "user_id": "xxx",
  "total_posts": 62,
  "completed": ["feed_id_1", "feed_id_2"],
  "failed": {"feed_id_3": "blocked"},
  "pending": ["feed_id_4", ...],
  "state_file": "/tmp/xhs_crawl_<timestamp>.json"
}

4. 中间浏览消遣

在批次之间随机访问小红书首页（explore）或搜索页，模拟正常用户行为，降低被检测概率。

使用方式

主脚本：scripts/batch_crawl.py

# 批量抓取博主所有帖子（含评论）
python scripts/batch_crawl.py crawl-user \
  --user-id 5b78e2bfafee930001b97776 \
  --xsec-token "AByofUPDrJ..." \
  --output /tmp/xhs_results.json \
  --batch-size 6 \
  --batch-delay 90 \
  --request-delay 12

# 从断点恢复
python scripts/batch_crawl.py resume \
  --state /tmp/xhs_crawl_1714364400.json

# 查看抓取进度
python scripts/batch_crawl.py status \
  --state /tmp/xhs_crawl_1714364400.json

参数说明

参数	默认值	说明
--batch-size	6	每批抓取数量
--batch-delay	90	批次间隔（秒）
--request-delay	12	请求间隔（秒）
--max-retries	3	单篇最大重试次数
--output	必须	结果输出 JSON 文件
--state	自动生成	状态文件路径
--no-comments	false	不加载评论

输出格式

{
  "user_id": "5b78e2bfafee930001b97776",
  "nickname": "酱香玉桂狗",
  "crawl_time": "2026-04-28T20:00:00+08:00",
  "total_posts": 62,
  "successful": 58,
  "blocked": 4,
  "posts": [
    {
      "feed_id": "...",
      "title": "...",
      "content": "...",
      "comments": [
        {
          "user_id": "...",
          "nickname": "...",
          "content": "...",
          "ip_location": "广东",
          "like_count": 10,
          "sub_comments": [...]
        }
      ]
    }
  ]
}

实现细节

反爬感知逻辑

1. 请求前：随机决定是否先访问 explore 页面（30% 概率）
2. 请求后：检查返回是否为 PageNotAccessibleError 或包含"扫码"关键词
3. 被拦截时：
   • 保存当前进度到状态文件
   • 等待用户手动扫码（轮询 check-login 确认恢复）
   • 恢复后重新测试 1 篇帖子，成功则继续
4. 批次结束时：随机浏览 1-2 页 explore，增加行为多样性

延迟策略

# 基础请求间隔：8-15秒随机
base_delay = random.uniform(8, 15)

# 每 3 篇额外休息：20-40秒
if i % 3 == 0 and i > 0:
    time.sleep(random.uniform(20, 40))

# 批次间隔：60-120秒
batch_delay = random.uniform(60, 120)

# 随机长休息（每 2 个批次）：30-60秒额外延迟
if batch_index % 2 == 1:
    time.sleep(random.uniform(30, 60))

状态文件

自动保存在 /tmp/xhs_crawl_<timestamp>.json。每次成功抓取一篇帖子后更新。

依赖

• xiaohongshu-skills（已安装在 workspace skills 中）
• Python 3.12+
• Chrome 浏览器 + Bridge 扩展已运行

限制

• 扫码验证无法自动解决，必须用户手动配合
• 62 篇帖子预计耗时 20-40 分钟（含延迟）
• 评论数多的帖子加载时间更长