---
name: xiaohongshu-inspiration
description: 小红书内容灵感聚合技能，覆盖选题灵感全链路：关键词爆款笔记搜索（相关性/热度/时效三维评分）、批量获取作品数据（支持 Excel/HTML 导出）、每日爆款 TOP50 爆发榜、低粉爆款挖掘（粉丝<5000 点赞>500）、账号日/周/月榜 TOP50、同阶对标与高阶标杆推荐。当用户需要小红书灵感、爆款搜索、笔记查询、批量获取作品、每日爆款、低粉爆款、账号榜单、涨粉榜、对标账号推荐时使用。触发词：小红书灵感、小红书爆款、小红书搜索、小红书爬取、每日爆款、低粉爆款、小红书榜单、日榜周榜月榜、对标账号。严禁任何联网搜索。
dependency:
  python:
    - requests>=2.28.0
---

# 小红书内容灵感专家

## 📝 简介

一个 Skill 覆盖小红书选题灵感全链路——从找爆款、追榜单到选对标，基于红狐数据每日收录的小红书爆款库（互动数 1000 以上收录），帮创作者、品牌方和 MCN 快速找到下一个选题。数据覆盖昨天至 30 天前，各模块更新时间见对应章节。所有数据来源于红狐 API，**严禁任何联网搜索**；仅在主 Agent 中执行，不派发给子 Agent。

## ✨ 功能特性

| 功能模块 | 能力描述 | 核心价值 |
|---|---|---|
| M1 关键词爆款搜索 | 按关键词搜索爆款笔记（互动数 1000+ 收录，每日 7:00 更新昨日），三维评分排序推荐 | 找选题灵感，锁定赛道热点 |
| M2 批量获取作品 | 按关键词+日期范围+排序批量获取作品（昨天至 30 天前），支持 Excel/HTML 导出 | 数据化选题，便于复盘分享 |
| M3 每日爆款 TOP50 | 发布后第 3 天相对第 2 天互动增量爆发榜（每日 19:00 更新）+ 爆款规律分析 | 追踪爆发趋势，掌握爆款节奏 |
| M4 低粉爆款挖掘 | 粉丝 < 5000 且点赞 > 500 的黑马笔记 TOP50（每日 19:30 更新） | 小博主可直接复制的起号样本 |
| M5 账号榜单 | 日/周/月榜账号 TOP50，粉丝与互动增量加权评分 | 看赛道排名，找涨粉标杆 |
| M6 对标账号推荐 | 同阶对标（可直接复制玩法）+ 高阶标杆（粉丝量 3-5 倍） | 起号参考与投放选择有据可依 |

## 🔑 鉴权（REDFOX_API_KEY）

**依赖安装**（仅 M2/M3 需要 requests，其余模块用标准库）：

```bash
pip3 install "requests>=2.28.0"
```

**获取方式**：
1. 访问 [红狐Hub](https://redfox.hk/?source=github) 了解服务
2. 前往 [注册页](https://redfox.hk/login?source=github) 注册（新用户赠免费积分）
3. 在 [API Key 页](https://redfox.hk/settings/api-keys?source=github) 获取，格式 `ak_xxxxxxxx`

**配置方式**（脚本按优先级自动回退）：

| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 环境变量 `REDFOX_API_KEY` | 直接读取当前进程环境变量 |
| 2 | Shell 配置文件 | 自动扫描 `~/.zshrc` `~/.bashrc` `~/.bash_profile` `~/.profile` `~/.zprofile` |
| 3 | 提示用户配置 | 以上都找不到时，引导用户配置 |

配置示例：`echo 'export REDFOX_API_KEY=ak_xxx' >> ~/.zshrc && source ~/.zshrc`；验证：`echo $REDFOX_API_KEY`。Windows：`[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "<值>", "User")` 后重启终端。

## 🔄 功能路由

| 用户意图 | 典型表述 | 模块 |
|---|---|---|
| 关键词搜爆款笔记、找选题灵感 | "搜一下睫毛膏的爆款笔记" | M1 |
| 按时间范围批量获取作品、导出报告 | "获取 8 月穿搭作品数据"、"导出 Excel" | M2 |
| 每日爆款榜、爆发笔记、互动增量 | "今日爆款笔记"、"睫毛膏爆发榜" | M3 |
| 低粉爆款、黑马笔记、小博主爆款 | "低粉爆款"、"粉丝少但很火的笔记" | M4 |
| 账号榜单、涨粉榜、赛道 TOP 账号 | "小红书日榜"、"美妆周榜 TOP50" | M5 |
| 找对标账号、相似账号、起号参考 | "我的 ID 是 xxx，推荐对标"、"做饭 3000 粉素人" | M6 |

混合意图按模块分别执行；无法判断时先询问用户。

## ⚙️ 全局规则（所有模块共享）

### 关键词类型判断（M1/M2/M3 共用）

- **细分词/垂直赛道**（含场景/人群/风格/属性修饰，如"职场穿搭"、"减脂餐"）→ **直接查询**
- **泛化词/大分类**（无修饰的大类词，如"美妆"、"美食"、"穿搭"）→ 执行泛化词拓展，**禁止直接调用脚本**
- **空关键词** → M1 直接查全站热门（无评分列）

**泛化词拓展策略（强制等待）**：
1. 结合近期热门趋势生成 10 个细分方向（趋势词、人群词、场景词、意图词各 2-3 个）
2. 输出推荐后**立即停止**，等待用户回复「拓展」或具体关键词，**不得在同一轮对话继续调用脚本**
3. 用户回复「拓展」→ 搜索这 10 个细分词；回复具体关键词 → 用该词查询

### 数据时间规则

- 小红书数据覆盖**昨天至 30 天前**，今天的数据未入库
- 用户查「今天/今日」→ 告知"今天的数据暂未更新，已为您展示最近可用的数据"；要求超过 30 天 → 告知"当前仅支持最近 30 天的数据，已为您展示最接近的数据"
- **数据不足时只能扩时间、禁止换词**（M1/M2/M3）：按 近1天 → 近3天 → 近7天 → 近30天 自动扩展，并告知"该关键词近X天数据较少，已自动扩展时间范围至近Y天"；❌ 禁止因数据不足更换关键词、推荐其他词或触发泛化词拓展
- M5 榜单回溯上限：日榜近 7 天、周榜近 3 周、月榜近 3 个月，超范围时切换最近可用日期并告知

### 输出铁律

1. **总数校验**：展示的条数 N 必须取自脚本返回的数组长度（如 `articles`），禁止人工计数
2. **忠实输出**：直接读取脚本返回的 JSON/Markdown，按各模块策略输出；❌ 禁止添加额外分析或建议、❌ 禁止解释原因、❌ 禁止询问用户真实目的（模块自带分析除外，如 M3/M4）
3. **数字格式**：< 10000 直接展示；≥ 10000 用 `x.xw`（如 56200 → 5.6w）
4. **标题格式**：`[标题](链接)`，超 30 字截断加 `...`；空标题显示「-」
5. **翻页闭环**：数据超过展示条数时必须提示剩余条数与展开方式；用户回复查看全部时完整输出
6. **单次查询单次 API 调用**：正常查询只调用一次接口，不做重复请求

### 标准赛道（25 个）

综合全部、出行代步、休闲爱好、影视娱乐、数码科技、医疗保健、综合杂项、星座情感、时尚穿搭、婚庆婚礼、拍摄记录、学习教育、化妆美容、居家装修、旅行度假、亲子育儿、个人护理、美味佳肴、职业发展、宠物天地、潮流鞋包、日常生活、科学探索、新闻资讯、体育锻炼。

## 🔍 M1 关键词爆款搜索

按关键词搜索小红书爆款笔记（收录标准：互动数 1000+），按三维评分排序推荐。

**前置说明（展示数据前必须告知）**：爆款笔记收录原则为互动数 1000 以上的文章，每日早上 7 点更新昨日数据；互动数据截止入库时间，非实时。排序说明：有关键词时按相关性（满分 10）+ 热度（满分 3）+ 时效（满分 2）加权，总分满分 15；全站热门按互动数排序、无评分列。

### 执行流程

```bash
# 关键词搜索（默认取 10 条）
python3 scripts/fetch_xhs_hot_articles.py --keyword "睫毛膏" --max-items 10

# 指定时间范围（YYYY-MM-DD）
python3 scripts/fetch_xhs_hot_articles.py --keyword "睫毛膏" --start-date 2026-08-01 --end-date 2026-09-06
```

主要参数：`--keyword`（必填）、`--max-items`（默认 10）、`--start-date/--end-date`、`--page-num`（默认 1）、`--page-size`（默认 50）、`--output-format json|html`。

时间范围换算：「最近」默认近 7 天；「今天」取昨天；「近 N 天」= 今天 - N 天。

### 展示策略（按 articles 数量分级）

表格字段顺序（总分加粗显示）：

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

| 情况 | 输出内容 |
|---|---|
| A：≥ 10 条 | 📅 查询时间范围 + 数据表格 + 🔤 拓词推荐（relatedSearches） |
| B：0 < n < 10 | 时间范围 + 💡"仅找到 X 条结果，可拓展词或拓展时间"提示 + 数据表格 + 拓词推荐 + 💡 推荐近期热门笔记（latestHotArticles 前 10 条，无评分列）+ 📈 热门赛道列表 |
| C：= 0 | 固定话术"🔍抱歉，爆款笔记收录原则为互动数1000以上的文章，该搜索词在查询时间范围（X - Y）内太小众，未找到与「XXX」直接相关的内容，你可以尝试用更短/宽泛的关键词重试" + **推荐搜索词**（relatedSearches 加粗）+ 推荐热门笔记 + 热门赛道列表 |

C 情况禁止添加额外分析、解释原因或主动提供其他方案。热门赛道列表：穿搭、美食、彩妆、影视、职场、萌宠、家居、旅行、交通、兴趣、科技、互联网、医疗保健、星座情感、婚庆婚礼、拍摄、教育、亲子育儿、个人护理、潮流鞋包、生活、科学探索、新闻资讯、运动。

### 分页、订阅与细分赛道

- **分页**：articles > 10 条时默认展示前 10 条，提示"💡 当前共找到 X 条相关笔记，已展示前10条。是否需要查看全部？"
- **订阅询问**（articles > 0 时必须执行，禁止跳过、禁止在展示结果前询问）：

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

用户选择订阅时，先告知"📅 数据更新时间：每日早上7点更新昨日数据"并询问推送时间，再用宿主的定时任务/日历工具创建订阅（title：小红书热门笔记订阅：{关键词}，参数用当前查询条件）。

- **推荐细分赛道**（展示数据后必须执行）：基于当前关键词生成 10 个细分方向（场景词、人群词、风格词、意图词各 2-3 个，大小适中），提示"回复具体关键词，我将为您查询该赛道的热门笔记"；空关键词直接使用热门赛道列表；已拓展过的词不再询问。

输出格式规范见 [references/m1_hot_article_format.md](references/m1_hot_article_format.md)。

## 📥 M2 批量获取作品

按关键词 + 日期范围 + 排序方式批量获取小红书作品数据，支持 Excel/HTML 报告导出。

### 执行流程

```bash
# 基础查询（关键词为位置参数）
python3 scripts/crawl_xhs.py "睫毛膏"

# 指定日期范围与排序
python3 scripts/crawl_xhs.py "睫毛膏" --start-date 2026-08-01 --end-date 2026-09-06 --sort-type _0
```

`--sort-type`：`_0` 综合排序（默认）/ `_2` 最多点赞 / `_4` 最新发布。

脚本返回 JSON：`articles`（作品数据）、`total`、`relatedSearches`（相关搜索词）、`latestHotArticles`（近期热门笔记，辅助展示 10 条）、`hotTopics`（热门话题，不在对话中展示）。

### 展示策略（按 articles 数量分级）

表格格式（标题用 `[标题](work_url)` 链接）：

`| # | 笔记标题 | 作者 | 收藏 | 分享 | 评论 | 点赞 | 发布时间 |`

| 情况 | 输出内容 |
|---|---|
| A：≥ 20 条 | 📊"关键词「XXX」共获取到 N 条小红书作品" + 风控提示 + 前 20 条表格 + "还剩 M 条未展示，回复「查看全部」展开" + 细分赛道推荐（10 个） |
| B：0 < n < 20 | 查询范围 + 💡"结果较少，可更换更短的关键词或扩大时间范围"提示 + 风控提示 + 全部表格 + 细分赛道推荐 |
| C：= 0 | 😔"抱歉，未找到与「XXX」相关的小红书作品" + **🔍 推荐搜索词**（relatedSearches 加粗）+ 💡 推荐热门笔记（latestHotArticles 前 10 条）+ 📈 热门赛道列表 |

**风控提示**（A/B 必须输出，紧跟查询范围之后）：

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

**格式化规则**：`publish_time` 转 `MM-DD HH:MM`（无论是否指定时间范围均展示）；其余同输出铁律。

### 更多操作与报告导出

展示后末尾追加（第二条仅 articles > 20 时展示，M = N - 20）：

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

导出时先将结果 JSON 写入临时文件，再调用报告脚本（输出到 `~/Downloads/XhsCrawl/`，生成后告知路径）：

```bash
echo '<JSON数据>' > /tmp/xhs_crawl_data.json
python3 scripts/generate_xhs_report.py "关键词" --input /tmp/xhs_crawl_data.json --format both
```

`--format`：`csv`（Excel 兼容）/ `html`（可视化报告）/ `both`（两者都生成）。

## 📊 M3 每日爆款 TOP50

查询某分类/关键词当日「爆发笔记」TOP50 —— 指标为笔记发布后第 3 天相对第 2 天的互动增量。每日 19:00 更新昨日数据（当前 ≥19:00 查昨日，<19:00 查前天）。

### 执行流程（两步 CLI，正常仅 1 次 API 调用）

```bash
# 第一步：拉取数据并写缓存
python3 scripts/xhs_daily_fetcher.py --keyword "睫毛膏" --top_n 50 --output_json /tmp/xhs_daily_cache.json

# 第二步：从缓存生成 HTML（0 次 API 调用）
python3 scripts/gen_xhs_html.py --keyword "睫毛膏" --top 20 --input_json /tmp/xhs_daily_cache.json
```

主要参数：`--rank_date`（YYYY-MM-DD，默认自动取最新可用日期）、`--category`、`--keyword`、`--top_n`（默认 10）、`--list_categories`（列出全部分类）、`--output_json`（数据缓存）。

### 输出规范（固定三部分，禁止折叠输出）

1. **爆发榜**：TOP50 表格（标题/作者/互动数据/发布时间）
2. **分析**：脚本自动生成的爆款规律分析
3. **功能服务询问**：订阅推送、导出报告等入口

HTML 文件名格式：`小红书每日爆款笔记_{分类}_唯一时间戳.html`，生成后告知用户路径。

详细工作流见 [references/m3_core_workflow.md](references/m3_core_workflow.md)。

## 💎 M4 低粉爆款挖掘

挖掘粉丝 < 5000 且点赞 > 500 的低粉爆款笔记（黑马样本），适合找选题、学标题写法。每日 19:30 更新昨日数据。

### 执行流程

```bash
# 查询低粉爆款（默认分类「综合全部」）
python3 scripts/fetch_explosive_articles.py --keyword "居家装修" --top_n 50
```

主要参数：`--keyword`、`--category`（默认 综合全部）、`--rank_date`（默认自动取最近可用日期）、`--top_n`（默认 50）、`--show_all`、`--realtime`、`--debug`。

脚本输出 Markdown 报告（爆款笔记表格 + 爆款规律分析 + 功能选择入口），**读取后原样输出给用户**；同时生成 `*_cache.json` 缓存文件。

### HTML 导出（节能模式，0 次 API 调用）

用户要求导出时，优先从缓存渲染；仅缓存缺失时用回退模式重新请求 API：

```bash
# 节能模式：从缓存生成（优先）
python3 scripts/generate_html_on_demand.py --from-cache ./小红书居家装修低粉爆款数据_xxx_cache.json --output ./output.html

# 回退模式：重新请求 API（仅缓存缺失时）
python3 scripts/generate_html_on_demand.py --rank_date 2026-09-06 --keyword 居家装修 --output ./output.html
```

生成后展示 HTML、交付文件并告知保存路径。接口规范见 [references/m4_api_spec.md](references/m4_api_spec.md)。

## 🏆 M5 账号榜单（日/周/月榜 TOP50）

查询小红书账号表现榜单：按总粉丝数、周期内粉丝/点赞/收藏/分享/评论增量加权计算排名，满分 100。

### 执行流程

```bash
# 推荐方式：直接传入用户原始问题，脚本自动解析周期/日期/赛道
python3 scripts/fetch_rank.py --query "小红书美妆日榜" --limit 20 --html
```

主要参数：`--query`（自然语言自动解析）、`--period`（day/week/month）、`--date`（YYYY-MM-DD）、`--category`（赛道）、`--limit`（默认 20）、`--format markdown|json`、`--html`（同时生成 HTML 报告）。

**榜单更新与回溯**：

| 榜单 | 更新时间 | 回溯上限 |
|---|---|---|
| 日榜 | 每日 19:00（昨日数据） | 近 7 天 |
| 周榜 | 每周一 15:00（上周数据） | 近 3 周 |
| 月榜 | 每月 1 日 9:00（上月数据，日期取每月 1 日） | 近 3 个月 |

「体育锻炼」等分类部分日期可能返回空数据，脚本自动回退日期（最多 3 天）。

### 输出规范（严格按顺序）

```
📊 小红书{日榜|周榜|月榜} · {赛道}

数据日期：{date}，共 {total} 个账号上榜

💡 榜单说明：{更新时间}更新昨日/上周/上月数据。
📐 排名算法：排名根据达人在小红书的总粉丝数、周期内的粉丝增量、点赞增量、收藏增量、分享增量以及评论增量加权计算所得，满分100分。

| 排名 | 账号名 | 综合评分 | 总粉丝数 | 新增笔记 | 新增粉丝 | 新增点赞 | 新增评论 | 新增收藏 | 新增分享 |

统计概览：上榜账号 {total} · 最高互动 {max_interaction} · 总新增笔记 {total_notes}
```

- 账号名格式「账号名 · 赛道」，带主页链接；排名 1-3 加 🥇🥈🥉
- 最高互动 = 点赞+评论+收藏+分享（计算得出，不能直接用接口的 `newInteraction` 字段）
- 追加「📬 订阅服务」询问：是否订阅每日/周/月榜单或具体赛道（25 个标准赛道）推送
- 交付 HTML 报告，并追加"⚡ 更多操作"：浏览器打开可导出 PDF；榜单完整 50 条，是否需要查看全部
- 用户要求查看全部时，以 `--limit 50` 重新拉取并完整输出 Markdown 表格 + 交付 HTML，两者缺一不可

API 详情见 [references/m5_api_docs.md](references/m5_api_docs.md)，评分规则见 [references/m5_score_rules.md](references/m5_score_rules.md)。

## 🎯 M6 对标账号推荐

输入小红书账号 ID 或「赛道 + 粉丝数 + 等级」，推荐同阶对标（粉丝量接近，可直接复制玩法）和高阶标杆（粉丝量 3-5 倍，可参考追赶）。

### 执行流程

```bash
# 方式 A：按账号 ID 查询
python3 scripts/xiaohongshu-similar-account.py --red_id "27493135897"

# 方式 B：按赛道 + 粉丝数 + 等级查询
python3 scripts/xiaohongshu-similar-account.py --track "美味佳肴" --min_fans 0 --max_fans 3000 --level "素人"
```

**粉丝数传参规则（重要）**：

- 单个粉丝数（如"3000 粉"）：`--max_fans 3000 --min_fans 0`
- 粉丝区间（如"1000-3000 粉"）：`--max_fans 3000 --min_fans 1000`
- 未指定粉丝数：两个参数都不传

**智能映射**：`--track` 支持口语化输入自动映射（做饭/美食/探店→美味佳肴、美妆/化妆→化妆美容、护肤→个人护理、穿搭→时尚穿搭、健身/运动→体育锻炼、母婴→亲子育儿、数码/AI→数码科技等，共 25 个标准赛道，见全局规则）；`--level` 支持口语映射（小白/新手/个人号→素人、大v/百万粉→头部kol、腰部/十万粉→腰部kol 等 7 级）。无法识别时脚本会列出完整赛道列表供选择。

### 输出规范（严格按顺序）

1. 开场白（只显示有数据的组）
2. 同阶对标表格：`| 账号名 | 粉丝数 | 近30天互动数 | 推荐理由 |`（账号名带主页链接）
3. 高阶标杆表格（同格式）
4. 分析总结
5. **订阅服务（必须输出，无论有无数据）**：是否订阅当前查询条件的对标账号推送，每日下午 7 点更新
6. 读取脚本输出的 `html_path` 并展示 HTML 报告

无数据时输出"✨ 暂未匹配到符合条件的对标账号，请尝试调整筛选条件" + 数据说明 + 订阅服务。数值格式同输出铁律（≥ 10000 显示 `X.Xw`）。报告模板见 [references/m6_account_template.html](references/m6_account_template.html)。