小红书爆款笔记查询

1. 简介

小红书热门笔记搜索工具，支持按关键词搜索小红书热门爆款笔记，并基于相关性、热度、时效三维评分智能排序推荐。同时提供热门笔记推荐和细分赛道引导，助力创作者、品牌方和 MCN 机构发现热门趋势、获取创作灵感。注意：本工具仅在主 Agent 中执行，不派发给子 Agent。

2. 功能特性

• 🔍 关键词智能搜索 — 支持关键词精确搜索、多关键词组合（逗号分隔）、全站热门查询（空关键词）
• 📊 三维评分排序 — 有关键词时按相关性（满分10分）、热度（满分3分）、时效（满分2分）加权计算总分（满分15分），全站热门按互动数排序
• 🧠 精细意图理解 — 优先从用户描述中提取细分方向词，识别泛化词并自动推荐 10 个细分方向
• ⏱️ 灵活时间范围 — 默认查询最近7天，数据不足时自动扩展时间范围（1天→3天→7天→30天），每日早上7点更新
• 🔥 热门笔记推荐 — 结果较少时自动展示近期热门推荐笔记和热门话题标签
• 📈 细分赛道引导 — 每次查询后主动推荐 10 个相关细分方向，帮助用户深入探索
• 🏷️ 拓词推荐 — 脚本返回 relatedSearches 字段，自动展示相关搜索建议
• 📩 定时订阅推送 — 支持创建日历订阅任务，到达设定时间自动推送最新热门笔记
• 📄 HTML 报告生成 — 自动生成 {keyword}_热门数据.html 可视化文件
• 🛡️ 强数据说明 — 热门笔记收录标准为互动数1000+，顶部展示数据说明和排序依据

3. 一键安装

鉴权

获取 API Key

请前往 红狐hub 获取API KEY

配置 API Key

方案1: 以OpenClaw为例，将REDFOX_API_KEY添加到~/.openclaw/openclaw.json中：

{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }

方案2: 终端配置

export REDFOX_API_KEY="ak_xxxx..."

依赖安装

本 Skill 使用 Python 3 标准库，无需额外安装第三方依赖。确保系统中已安装 Python 3.x 即可。

环境变量配置

4. 使用指南

⚠️ 核心执行规则（必须遵守）

1. 泛化词必须先询问再查询：当识别到泛化词时，绝对禁止直接调用脚本，必须先输出细分词推荐并等待用户选择后再执行查询
2. 正确执行顺序：关键词提取 → 判断是否泛化词 → 是泛化词则询问用户 → 用户回复后再调用脚本
3. 强制等待规则：输出细分词推荐后，必须停止执行，等待用户下一轮对话回复「拓展」或「不拓展」，不得在同一次对话中继续执行任何脚本调用

常见泛化词：

泛词：抽象层级高、覆盖范围广的概括性词汇，无具体场景/属性修饰，行业分类等，可包含多个子类。特征：①语义上为上位概念（如"美妆"包含"粉底液/口红"；"运动"包含"跑步/瑜伽"；如AI）；②上下文中常搭配"领域""类型"等概括词（如"美妆领域""运动类型"）。

常见具体词：

具体词：抽象层级低、指向明确的实例化词汇，含具体场景/属性修饰，属于某泛词的直接子类。特征：①语义上为下位概念（如"粉底液"是"美妆产品"子类；"生酮饮食"是"饮食方式"子类）；②词语结构多含修饰成分（如"春日"→"春日穿搭"；"生酮"→"生酮饮食"）。

基础使用（3 步完成查询）

Step 1 — 提取关键词：从用户自然语言描述中提取搜索关键词。优先提取细分方向词（含具体场景/属性修饰），而非泛化大类词。

Step 2 — 调用脚本：

python scripts/fetch_xhs_hot_articles.py --keyword <关键词> --start-date <日期>

• 有赛道关键词：python scripts/fetch_xhs_hot_articles.py --keyword <关键词> --start-date <日期>
• 无赛道关键词（查询全站热门）：python scripts/fetch_xhs_hot_articles.py --keyword "" --start-date <日期>
• 多个关键词用逗号分隔：python scripts/fetch_xhs_hot_articles.py --keyword "减脂餐,职场穿搭,健身" --start-date <日期>
• 分页参数：--page-num 1 --page-size 50

Step 3 — 查看结果：脚本返回结构化 JSON，按本指南规定的展示策略输出结果。

高级使用

用户意图理解（查询脚本前）

⚠️ 核心规则：应该语意理解，优先提取用户描述中的细分方向词，而非泛化的大类词

1. 判断用户是否提到赛道关键词：

• 无赛道关键词（如"最近的热门笔记有哪些"、"最近有什么热门内容"、"看看热门数据"）→ 直接调用脚本，关键词传空字符串 ""，查询全站热门
• 有赛道关键词 → 继续提取和判断

2. 提取精确搜索关键词（仅当用户提到赛道时执行）：

• 分析用户描述：从用户自我介绍或需求描述中提取明确的细分领域词
• 示例分析：
• 用户输入："我是一个文艺类自媒体万粉小红书博主，平时会发小众电影审美积累、书评、乐评、港台文化等相关内容，帮我找电影领域热门话题"
• 分析结果：用户提到的细分方向 = 小众电影、书评、乐评、港台文化
• 将前文场景和"电影"相关，得到细分词 = 小众电影、港台电影、电影乐评
• 搜索关键词：小众电影、港台电影、电影乐评
• ❌ 错误做法：只提取泛化词「电影」去搜索

3. 关键词类型判断（仅当提取到关键词时执行）：

• 细分词/垂直赛道（含具体场景/属性修饰的词，如"职场穿搭"、"减脂餐"、"小个子穿搭"）→ 直接搜索，无需拓展询问
• 泛化词/分类（纯大类词，如"穿搭"、"美食"、"美妆"，无任何修饰）→ 执行拓展策略
• 判断原则：有修饰词（场景/人群/风格/意图）= 细分词，直接搜索；无修饰词 = 泛化词，需要拓展

泛化词拓展策略

1. 泛化词处理流程（⚠️ 必须等待用户明确回复后再调用脚本！）：

第一步：生成细分词（禁止调用脚本搜索数据）

拓展词生成原则：

• 词的大小适中：词语不要加组合，避免过细（如"中产穿搭"太细，查不到数据）
• 必须覆盖不同场景：趋势词、人群词、场景词、意图词各2-3个

输出示例：

```

我识别到「中产」是较大的分类，已查询近期热门趋势，推荐以下细分方向：

老钱、轻奢、品质生活、松弛感、高级感穿搭、体面、法式穿搭、律师、医生、品质家居

回复「拓展」将同时搜索这10个词，回复「不拓展」将继续搜索「中产」

```

第二步：等待用户回复

• ❌ 禁止：用户未回复时调用脚本
• ✅ 正确：只等待用户明确回复「拓展」或「不拓展」后再执行

第三步：根据用户明确回复执行

• 用户回复「拓展」 → 调用脚本搜索10个细分词
• 用户回复「不拓展」或「继续」 → 调用脚本搜索原关键词
• 用户未回复或回复其他内容 → 识别对应意图

时间范围与数据查询

时间范围：

• 数据库只包含昨天至30天前的数据
• "最近"的默认定义：最近7天（startDate = 今天 - 7天）
• 日期计算（将用户表达转换为 startDate）：
• 今天：直接用昨天日期，startDate = 昨天
• 最近/近7天：startDate = 今天 - 7天
• 近N天：startDate = 今天 - N天
• 示例：用户说"近15天" → startDate = 今天 - 15天

数据不足时的自动调整（⚠️ 优先扩展时间，禁止换词！）：

• 处理原则：数据不足时，只能扩展时间范围，不能更换或拓展关键词
• 调整顺序：按以下顺序自动扩展时间范围

1. 近1天 → 近3天
2. 近3天 → 近7天
3. 近7天 → 近30天
• 告知用户：自动调整时告知用户："该关键词近X天数据较少，已自动扩展时间范围至近Y天"
• 禁止行为：❌ 不可因为数据不足就更换关键词、推荐其他词或触发泛化词拓展流程

超出范围或未更新数据的道歉说明：

• 用户说"今天/今日"时：回答"非常抱歉，今天的数据暂未更新，已为您展示最近可用的数据"
• 用户要求的时间超出30天时：回答"非常抱歉，当前仅支持最近30天的数据，已为您展示最接近的数据"

输出文件：

• 筛选后推荐数据：{keyword}_热门数据.html

前置说明（在展示数据前必须告知用户）

• 数据说明：热门笔记范围为互动数1000以上的文章，每日早上7点更新昨日数据。文章互动数据截止为入库时间，不是实时数据，入库后互动数据可能持续增长。
• 排序说明（有关键词搜索时）：根据相关性（满分10分）、热度（满分3分）、时效（满分2分）三个维度加权计算，总分共15分
• 排序说明（全站热门/无关键词时）：按互动数排序，无评分字段

数据展示策略（核心）

⚠️ 强制输出规则：

• ✅ 必须严格按照本步骤规定的格式输出
• ❌ 禁止在输出前添加任何分析或解读
• ❌ 禁止自作主张给建议或方案
• ❌ 禁止询问用户的真实目的或需求
• ✅ 直接读取脚本返回的JSON数据，按照对应策略输出即可

数据字段说明：

• articles：正常笔记数据（主要展示内容）
• latestHotArticles：推荐热门笔记（辅助内容，默认展示10条，表格不含评分字段）
• hotTopics：热门话题（接口返回，仅供参考，不在对话中展示）

A. articles数量 ≥ 10条

展示内容：

1. 时间范围说明：必须告知用户查询的时间范围，如"📅 查询时间范围：5月8日 - 5月19日"
2. 正常笔记数据（有关键词时按totalScore降序排序，全站热门时按互动数排序）
3. 拓词推荐（relatedSearches）

Markdown表格格式：

⚠️ 表格字段顺序必须严格按以下顺序展示：

有关键词时：

全站热门时（无评分字段）：

注意：总分字段需要加粗显示（使用分数格式）

示例（有关键词）：

📅 查询时间范围：5月8日 - 5月19日

示例（全站热门）：

📅 查询时间范围：5月8日 - 5月19日

🔤 拓词推荐：职场沟通、职场晋升、打工人

B. articles数量 < 10条但 > 0

展示内容：

1. 时间范围说明：必须告知用户查询的时间范围，如"📅 查询时间范围：5月8日 - 5月19日"
2. 提示信息："💡当前关键词当前时间段仅找到 X 条结果，您可以尝试拓展词或者拓展时间，我们还为您推荐了近期的热门笔记"
3. 正常笔记数据
4. 拓词推荐（relatedSearches）
5. 推荐热门笔记（latestHotArticles，带"推荐热门笔记"标题分区，默认展示10条）
6. 推荐热门话题

Markdown格式示例：

📅 爆款笔记收录原则为互动数1000以上的文章, 查询时间范围：5月8日 - 5月19日

> 当前关键词当前时间段仅找到 3 条结果：

有关键词时：

全站热门时（无评分字段）：

🔤 拓展词推荐：职场沟通、职场晋升、打工人

💡我们为您推荐了近期的热门笔记供参考，或许对您有帮助：

⚠️ 推荐热门笔记表格不需要评分字段，格式为：

📈 您还可以尝试搜索以下热门赛道：：

穿搭、美食、彩妆、影视、职场、萌宠、家居、旅行、交通、兴趣、科技、互联网、医疗保健、星座情感、婚庆婚礼、拍摄、教育、亲子育儿、个人护理、潮流鞋包、生活、科学探索、新闻资讯、运动

C. articles数量 = 0

⚠️ 必须严格按照以下格式输出，禁止自作主张给建议或分析

展示内容：

**🔍抱歉，爆款笔记收录原则为互动数1000以上的文章,该搜索词在查询时间范围（5月8日 - 5月19日）内太小众，未找到与"XXX"直接相关的内容，你可以尝试用更短/宽泛的关键词重试。**

**推荐搜索词**：从脚本返回的relatedSearches字段中提取推荐词，以加粗形式展示；

💡我们为您推荐了近期的热门笔记供参考，或许对您有帮助：

⚠️ 推荐热门笔记表格不需要评分字段，格式为：
| 笔记标题 | 作者 | 互动数 | 发布时间 |
|---------|------|--------|----------|
| [热门笔记1](url) | [作者A](https://www.xiaohongshu.com/user/profile/xxx) | 8.5w | 2026-05-14 |
| [热门笔记2](url) | [作者B](https://www.xiaohongshu.com/user/profile/xxx) | 6.2w | 2026-05-13 |

📈 您还可以尝试搜索以下热门赛道：
穿搭、美食、彩妆、影视、职场、萌宠、家居、旅行、交通、兴趣、科技、互联网、医疗保健、星座情感、婚庆婚礼、拍摄、教育、亲子育儿、个人护理、潮流鞋包、生活、科学探索、新闻资讯、运动

输出规则：

• ✅ 必须直接输出上述格式内容
• ❌ 禁止添加额外的分析或建议
• ❌ 禁止解释为什么搜不到数据
• ❌ 禁止主动提供其他搜索方案
• ❌ 禁止询问用户的真实目的

展示逻辑（分页）

当articles数量 > 10条时：

1. 初始默认只展示前10条数据
2. 必须提示用户：

💡 当前共找到 X 条相关笔记（X为实际返回条数），已展示前10条。是否需要查看全部？

3. 等待用户回复：
• 用户回复"是"/"查看全部"/"全部" → 展示全部数据
• 用户回复"否"/"不用"/"不需要" → 不展示更多

展示全部数据时的格式：

📊 全部结果（共X条，X为实际返回条数）：

有关键词时：
| 笔记标题 | 作者 | 互动数 | 发布时间 | 相关性 | 热度 | 时效 | **总分** |

全站热门时：
| 笔记标题 | 作者 | 互动数 | 发布时间 |

| ...（全部数据）...

订阅服务询问（必须执行）

当articles数量 > 0时，结果输出完成后必须询问：

📬 订阅服务
1️⃣ 是否需要订阅当前搜索条件笔记，订阅后将定时推送给您？
2️⃣ 暂不需要

处理用户回复：

• 用户选择1️⃣ → 使用 calendar_create 工具创建日程，订阅当前搜索条件
• 用户选择2️⃣ → 结束当前对话

订阅实现步骤：

1. 告知数据更新时间并询问推送时间：

📅 数据更新时间：每日早上7点更新昨日数据

请告诉我您希望推送的具体时间~

1. 用户选择后，调用 calendar_create 工具：
• title：小红书热门笔记订阅：{关键词}
• description：记录当前搜索参数（关键词、时间范围）
• start_time：根据用户选择的时间设置
• remind_type：设置为定期提醒
• 其他参数使用当前查询参数

1. 订阅成功后提示：

✅ 订阅创建成功！

📌 订阅信息：

- 关键词：{关键词}
- 时间范围：{当前时间范围}
- 推送时间：{用户选择的时间}
- 数据更新：每日早上7点更新昨日数据

到达设定时间后，将自动为您推送最新的小红书热门笔记。

⚠️ 强制规则：

• ✅ 必须在结果输出完成后立即询问
• ✅ 用户选择订阅时，必须使用 calendar_create 工具
• ✅ 参数必须使用当前查询参数（关键词、时间范围等）
• ❌ 禁止跳过此步骤
• ❌ 禁止在展示结果前询问

推荐细分赛道（⚠️ 展示数据后必须执行）

核心规则：展示完热门数据后，必须主动询问用户是否需要查询更具体的细分赛道

1. 推荐细分词生成：
• 基于当前查询的关键词，生成10个相关的细分方向词
• 生成原则：
• 词的大小适中：避免过细（查不到数据）或过泛（范围太大）
• 覆盖不同维度：场景词、人群词、风格词、意图词各2-3个
• 参考数据表现：优先推荐近期热度较高的方向

1. 输出格式：

以上是「{当前关键词}」的热门数据。

如需深入了解某个细分方向，可以从以下赛道中选择：
{细分词1}、{细分词2}、{细分词3}、{细分词4}、{细分词5}、 {细分词6}、{细分词7}、{细分词8}、{细分词9}、{细分词10}

回复具体关键词，我将为您查询该赛道的热门笔记。

1. 示例输出：

以上是「减脂餐」的热门数据。

如需深入了解某个细分方向，可以从以下赛道中选择：
早餐减脂、减脂便当、低卡晚餐、减脂零食、学生党减脂、一周食谱、减脂沙拉、减脂主食、控糖减脂、懒人减脂餐

回复具体关键词，我将为您查询该赛道的热门笔记。

1. 特殊情况处理：
• 如果用户查询的是非常细分的词（如"减脂餐一周食谱"），可不再推荐更细的方向;已经拓展过的词不需要再询问拓展
• 如果用户查询的是空关键词（全站热门），直接使用热门赛道列表推荐，格式如下：

```

以上是全站热门数据。

如需深入了解某个细分赛道，可以从以下热门赛道中选择：

穿搭、美食、彩妆、影视、职场、萌宠、家居、旅行、交通、兴趣、科技、互联网、医疗保健、星座情感、婚庆婚礼、拍摄、教育、亲子育儿、个人护理、潮流鞋包、生活、科学探索、新闻资讯、运动

回复具体关键词，我将为您查询该赛道的热门笔记。

```

输出前自检【必须执行】

在输出前,逐项检查输出格式的每一个字段是否完整:

• [] 意图识别:是否准确识别用户搜索意图？
• [] 笔记数据:是否如实展示脚本返回的所有筛选结果（max_items=10时展示10条），每条包含序号（加粗）、笔记标题、作品链接、作者名、作者链接、发布时间、互动数、推荐理由（加粗）？
• [] HTML卡片:是否包含html卡片?
• [] 推荐细分词:是否列出10个细分词？

如有任何字段遗漏或不完整,必须补齐后再输出。

常用命令速查表

5. 使用场景

场景一：小红书博主寻找选题灵感

• 角色：小红书内容创作者
• 需求：想了解近期"减脂餐"领域有哪些热门笔记，为下一篇笔记找选题方向
• 使用方式：输入细分关键词「减脂餐」，系统返回高评分热门笔记列表，展示后自动推荐 10 个细分方向（如"早餐减脂""减脂便当"等）
• 预期收益：通过三维评分排序快速锁定高价值选题，同时获取细分赛道灵感，提升内容产出质量

场景二：品牌方市场调研

• 角色：品牌市场人员
• 需求：了解"穿搭"赛道的整体热门趋势，但不确定具体细分方向
• 使用方式：输入泛化词「穿搭」后，系统推荐 10 个细分方向（如"小个子穿搭""法式穿搭""职场穿搭"等），回复「拓展」批量搜索所有方向
• 预期收益：一次性覆盖多个细分领域，全面掌握赛道热度分布，为品牌内容营销策略提供数据支撑

场景三：MCN 机构达人内容规划

• 角色：MCN 机构内容总监
• 需求：需要一次性查看多个领域（减脂餐、健身、职场穿搭）的热门笔记，规划旗下达人矩阵内容排期
• 使用方式：使用逗号分隔多关键词 --keyword "减脂餐,健身,职场穿搭" 进行跨领域查询
• 预期收益：一个命令覆盖多个品类，高效获取跨领域热门趋势，提升内容规划效率

场景四：每日热门笔记定时推送

• 角色：小红书运营人员
• 需求：希望每天上午自动收到特定赛道的热门笔记列表，持续追踪趋势
• 使用方式：搜索关键词后选择「1️⃣ 订阅」，设置推送时间，创建日历定时任务
• 预期收益：无需手动重复搜索，每日定时获取最新热门笔记，持续跟踪赛道动态，保持创作敏感度

6. 项目架构

目录结构

xiaohongshu-search/
├── SKILL.md                               # Skill 定义与使用文档（本文件）
├── scripts/
│   └── fetch_xhs_hot_articles.py          # 核心搜索脚本，调用红狐 API 获取小红书热门笔记
└── references/
    └── xhs_hot_article_format.md          # 数据字段格式参考文档

技术栈

核心模块说明

资源索引

• 核心脚本：scripts/fetch_xhs_hot_articles.py — 调用红狐 API 获取小红书热门笔记数据并生成 HTML 报告
• 参考文档：references/xhs_hot_article_format.md — 何时读取：需要了解数据字段格式和输出规范时

7. 常见问答

安装

Q: 需要安装哪些依赖？

A: 本工具使用 Python 3 标准库，无需额外安装第三方依赖。确保系统已安装 Python 3.x 即可。

Q: 如何获取 API Key？

A: 请访问 红狐hub 注册并获取 API Key，按本文"一键安装"章节配置环境变量。

使用

Q: 泛化词和细分词有什么区别？

A: 泛化词是抽象层级高、覆盖范围广的概括性词汇（如"美妆""穿搭"），无具体场景/属性修饰；细分词含有具体修饰成分（如"粉底液""小个子穿搭"）。泛化词会触发拓展策略，细分词直接搜索。

Q: 数据的时间范围是什么？

A: 数据库仅包含昨天至30天前的数据。默认查询最近7天，数据不足时自动扩展时间（1天→3天→7天→30天）。每日早上7点更新昨日数据。

Q: 为什么有的表格有评分字段、有的没有？

A: 有关键词搜索时按 totalScore（相关性+热度+时效）排序，展示评分字段；全站热门按互动数排序，无评分字段。推荐热门笔记表格也不含评分。

Q: 如何查看超过 10 条的完整结果？

A: 当结果超过 10 条时，系统会提示「是否需要查看全部？」。回复「是」「查看全部」或「全部」即可展示完整数据。

Q: 为什么每次查询后都会推荐细分赛道？

A: 这是设计功能 — 帮助用户从当前查询结果中进一步发现更精准的细分方向，深入挖掘数据价值。如果查询的已是细分词，系统会智能判断是否跳过推荐。

故障排除

Q: 搜索结果为空怎么办？

A: 热门笔记收录标准为互动数1000+。如果关键词太小众或时间范围太短，可能无数据。系统会自动扩展时间范围，也可从 relatedSearches 推荐的搜索词中选择重试。

Q: 提示"今天的数据暂未更新"？

A: 数据库每日早上7点更新昨日数据，当天数据尚未入库。系统会自动展示最近可用的数据。

Q: 脚本执行报错？

A: 常见原因：(1) REDFOX_API_KEY 未配置或已过期；(2) Python 版本低于 3.x；(3) 网络连接问题。请逐一排查。

安全许可

Q: API Key 如何安全存储？

A: 推荐使用方案 1（配置到 openclaw.json 的 env 字段中），避免在终端历史中泄露。请勿将 API Key 硬编码在脚本中或上传到公开仓库。

Q: 数据来源和版权？

A: 数据来源于红狐 API 收录的小红书公开笔记。笔记版权归原作者所有，本工具仅供学习和内容创作参考使用。

Q: 为什么要在主 Agent 中执行？

A: 小红书搜索工具涉及完整的意图理解、泛化词拓展和数据展示策略，流程复杂且依赖全局上下文判断，仅在主 Agent 中执行以确保行为一致和规则完整。