xiaohongshu-crawler

---
name: xiaohongshu-crawler
description: 小红书作品爬取工具。根据关键词爬取小红书热门作品数据，支持按日期范围、排序方式筛选，结果以结构化表格展示。当用户需要爬取小红书作品、查询小红书热门内容、搜索小红书爆款笔记时使用。触发词：小红书爬取、小红书作品、小红书爆款、小红书搜索、小红书热门、小红书笔记查询。
---

# 小红书作品爬取

## 📝 简介

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

## ✨ 功能特性

| 功能模块 | 能力描述 | 核心价值 |
|---------|---------|---------|
| 作品爬取 | 关键词搜索小红书作品 | 精准发现高热度内容 |
| 日期筛选 | 支持按日期范围筛选 | 定位特定时间段的热门内容 |
| 多种排序 | 相关性/最新/最热三种排序 | 灵活满足不同筛选需求 |
| 互动数据 | 返回收藏、分享、评论、点赞等 | 全面评估作品热度 |
| 报告导出 | CSV（Excel兼容）+ HTML可视化报告 | 本地离线查看与分享 |

## 🔑 鉴权

- 获取 API Key：前往 [红狐hub](https://redfox.hk/settings/api-keys?source=github)
- 配置方式1：写入 `~/.openclaw/openclaw.json` → `{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }`
- 配置方式2：终端执行 `export REDFOX_API_KEY="ak_xxxx..."`

## ⚙️ 工作流程

### Step 1: 🔍 用户意图理解

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

| 参数 | 提取规则 | 默认值 |
|------|---------|--------|
| keyword | 用户提到的搜索关键词 | 空字符串 `""` |
| startDate | 起始日期，解析为 `YYYY-MM-DD` | 30天前（脚本自动计算） |
| endDate | 结束日期，解析为 `YYYY-MM-DD` | 今天（脚本自动计算） |
| sortType | 排序方式，见下表 | `"_0"` |

**sortType 枚举：**

| 值 | 含义 | 触发词 |
|----|------|--------|
| `_0` | 相关性排序（默认） | 默认排序、综合排序、相关 |
| `_2` | 最新（按发布时间排序） | 最新、 newest、按时间 |
| `_4` | 最热（按互动数排序） | 最热、最火、hottest、按热度 |

**时间解析规则：**

| 用户输入 | 解析方式 | 示例 |
|---------|---------|------|
| 绝对日期 | 解析为 `YYYY-MM-DD` | `6月1号` → `2026-06-01` |
| 相对日期 | 基于当前日期计算 | `最近7天` → start=7天前, end=今天 |
| 日期范围 | 分别解析为 startDate/endDate | `5月30日到6月2日` |
| 未提供时间 | **不传** `--start-date`/`--end-date`，脚本默认查最近30天 | 不传参数 |

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

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

**关键词分类：**

| 类型 | 特征 | 处理方式 |
|------|------|----------|
| 空关键词 | 用户未提供关键词（如「最近热门笔记」） | 直接查询全站热门，keyword 传 `""` |
| 细分词 | 含具体场景/属性/人群修饰（如「减脂餐」「小个子穿搭」「生酮饮食」） | 直接调用脚本 |
| 泛化词 | 纯大类词，无修饰成分（如「美食」「穿搭」「美妆」） | **必须先推荐细分词，等待用户回复后再查询** |

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

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

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

输出示例：

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

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

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

### Step 2: 📡 调用脚本

```bash
# 基础调用（仅关键词，日期默认最近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` 总数，以及以下辅助字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `articles` | 数组 | 作品数据（主要展示内容） |
| `relatedSearches` | 数组 | 相关搜索词推荐 |
| `latestHotArticles` | 数组 | 近期热门笔记推荐（辅助内容，默认展示 10 条） |
| `hotTopics` | 数组 | 热门话题标签（仅供参考，不在对话中展示） |

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

| 脚本字段 | 接口原始字段 | 说明 |
|-------------|---------------|------|
| `title` | `title` | 笔记标题 |
| `author` | `authorNickname` | 作者昵称 |
| `collect_count` | `collectedCount` | 收藏数 |
| `share_count` | `sharedCount` | 分享数 |
| `comment_count` | `commentsCount` | 评论数 |
| `like_count` | `likedCount` | 点赞数 |
| `publish_time` | `createTime` | 发布时间 |
| `work_url` | `shareInfoLink` | 作品链接 |
| `cover` | `cover` | 封面图 URL |
| `desc` | `desc` | 笔记描述/话题标签 |
| `author_fans` | `authorFans` | 作者粉丝数 |
| `interactive_count` | `interactiveCount` | 互动总数 |
| `work_id` | `id` | 作品 ID |

### Step 3: 📊 结果展示

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

#### 情况 A：articles ≥ 20

**A1.** 输出查询范围：

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

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

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

**A3.** 展示前 20 条表格：

```markdown
| # | 笔记标题 | 作者 | 收藏 | 分享 | 评论 | 点赞 | 发布时间 |
|---|---------|------|------|------|------|------|----------|
| 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 条，表格不含评分字段）：

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

```markdown
| # | 笔记标题 | 作者 | 收藏 | 分享 | 评论 | 点赞 | 发布时间 |
|---|---------|------|------|------|------|------|----------|
| 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: 📦 更多操作

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

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

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

#### 4.1 下载报告

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

```bash
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>
```

| `--format` | 生成文件 | 告知用户示例 |
|------------|---------|-------------|
| `csv` | CSV（Excel 兼容） | `✅ Excel（CSV）文件已生成：~/Downloads/XhsCrawl/小红书作品_关键词_时间戳.csv` |
| `html` | HTML 可视化报告 | `✅ HTML 可视化报告已生成：~/Downloads/XhsCrawl/小红书作品_关键词_时间戳.html` |
| `both` | CSV + HTML | 同时告知两个文件路径 |

#### 4.2 用户回复「查看全部」

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