Xiaohongshu Crawler

小红书作品爬取

📝 简介

根据关键词爬取小红书热门作品，支持按日期范围筛选和多种排序方式（相关性、最新、最热），返回笔记标题、作者、互动数据等，结果以结构化表格展示。

✨ 功能特性

🔑 鉴权

• 获取 API Key：前往 红狐hub
• 配置方式1：写入 ~/.openclaw/openclaw.json → { "env": { "REDFOX_API_KEY": "ak_xxxx..." } }
• 配置方式2：终端执行 export REDFOX_API_KEY="ak_xxxx..."

⚙️ 工作流程

Step 1: 🔍 用户意图理解

从用户输入中提取以下参数：

sortType 枚举：

时间解析规则：

Step 1.5: 🧠 关键词类型判断（⚠️ 调用脚本前必须执行）

核心规则：泛化词必须先询问再查询，具体词直接查询。

关键词分类：

泛化词处理流程（⚠️ 禁止直接调用脚本！）：

第一步：生成 10 个细分词推荐

生成原则：

• 词的大小适中，避免过细（查不到数据）或过泛
• 必须覆盖不同场景：趋势词、人群词、场景词、意图词各 2-3 个

输出示例：

我识别到「美食」是较大的分类，推荐以下细分方向： 家常菜、烘焙甜点、减脂餐、早餐、宵夜、地方菜系、懒人食谱、宝宝辅食、火锅、咖啡饮品 回复「拓展」将同时搜索这 10 个词，回复「不拓展」将继续搜索「美食」

第二步：等待用户回复（禁止在同一次对话中继续执行脚本）

• 用户回复「拓展」 → 调用脚本搜索 10 个细分词（逗号分隔）
• 用户回复「不拓展」 → 调用脚本搜索原关键词

Step 2: 📡 调用脚本

# 基础调用（仅关键词，日期默认最近30天，排序默认相关性）
python3 ~/.qoderwork/skills/xiaohongshu-crawler/scripts/crawl_xhs.py "<关键词>"

# 完整参数（仅传入非空的时间/排序参数）
python3 ~/.qoderwork/skills/xiaohongshu-crawler/scripts/crawl_xhs.py "<关键词>" --start-date <startDate> --end-date <endDate> --sort-type <_0|_2|_4>

脚本返回 JSON，包含 articles 数组、total 总数，以及以下辅助字段：

每条作品字段（脚本内部字段 ↔ 接口原始字段）：

Step 3: 📊 结果展示

⚠️ 总数校验：展示的 N 必须取自 articles 数组长度，禁止人工计数。 ⚠️ 强制输出规则：直接读取脚本返回的 JSON 数据，按对应策略输出，禁止添加额外分析或建议。

情况 A：articles ≥ 20

A1. 输出查询范围：

📊 关键词「XXX」共爬取到 N 条小红书作品，以下是详细数据：

A2. 输出风控提示（紧跟 A1 之后、表格之前）：

！！！受小红书风控规则限制，部分作品链接可能无法正常跳转，您可复制对应作品标题前往小红书搜索查看，感谢理解🙇‍♀️🙇‍♀️

A3. 展示前 20 条表格：

| # | 笔记标题 | 作者 | 收藏 | 分享 | 评论 | 点赞 | 发布时间 |
|---|---------|------|------|------|------|------|----------|
| 1 | [标题](work_url) | 作者名 | 1.2w | 3.5w | 8000 | 5.6w | 06-02 19:55 |

A4. 提示剩余数据：

以上展示了前 20 条数据，还剩 M 条未展示。回复「查看全部」展开剩余数据。

A5. 推荐细分赛道（基于当前关键词生成 10 个相关细分方向词）：

如需深入探索某个细分方向，可以从以下关键词中选择： {细分词1}、{细分词2}、...、{细分词10} 回复具体关键词，我将为您查询。

情况 B：0 < articles < 20

B1. 输出查询范围 + 数据较少提示：

📊 关键词「XXX」共爬取到 N 条小红书作品。 💡 当前关键词在该时间段结果较少，您可以尝试更换更短的关键词或扩大时间范围。

B2. 输出风控提示：

！！！受小红书风控规则限制，部分作品链接可能无法正常跳转，您可复制对应作品标题前往小红书搜索查看，感谢理解🙇‍♀️🙇‍♀️

B3. 展示全部表格（同 A3 格式）。

B4. 推荐细分赛道（同 A5）。

情况 C：articles = 0

😔 抱歉，未找到与「XXX」相关的小红书作品，请尝试更换关键词或调整时间范围。

C1. 推荐搜索词（从 relatedSearches 字段提取，以加粗形式展示）：

🔍 推荐搜索词：词1、词2、词3...

⚠️ 若 relatedSearches 为空则不展示此条。

C2. 推荐热门笔记（从 latestHotArticles 字段取前 10 条，表格不含评分字段）：

💡 我们为您推荐了近期的热门笔记供参考：

| # | 笔记标题 | 作者 | 收藏 | 分享 | 评论 | 点赞 | 发布时间 |
|---|---------|------|------|------|------|------|----------|
| 1 | [标题](work_url) | 作者名 | 1.2w | 3.5w | 8000 | 5.6w | 06-02 19:55 |

⚠️ 若 latestHotArticles 为空则不展示此块。

C3. 推荐热门赛道（从 hotTopics 字段提取；若为空则使用以下默认列表）：

📈 您还可以尝试搜索以下热门赛道： 穿搭、美食、彩妆、影视、职场、萌宠、家居、旅行、运动、科技、互联网、医疗保健、教育、亲子育儿、生活

格式化规则（适用于所有情况）：

• 数字 < 10000 直接展示；≥ 10000 用 x.xw 格式
• publish_time 转为 MM-DD HH:MM；无论是否指定时间范围均展示
• 标题超 30 字截断加 ...，使用 [标题](work_url) 链接格式
• 标题为空时显示“-”

Step 4: 📦 更多操作

展示完结果后，末尾追加以下内容：

⚡ 更多操作
• 是否需要下载 Excel 文件或 HTML 可视化报告？便于您在浏览器中打开查看
• 本次共 N 条作品，是否需要查看剩余 M 条？

⚠️ 第二条仅在 articles > 20 时展示，N 为总数，M = N - 20。

4.1 下载报告

将爬取结果 JSON 写入临时文件，再调用报告生成脚本：

echo '<JSON数据>' > /tmp/xhs_crawl_data.json
python3 ~/.qoderwork/skills/xiaohongshu-crawler/scripts/generate_report.py "<关键词>" \
  --input /tmp/xhs_crawl_data.json --format <csv|html|both>

4.2 用户回复「查看全部」

直接展示剩余数据（从第 21 条开始），使用与 A3 相同的表格格式，不再追加「更多操作」提示。