用途
小红书热门笔记搜索工具，支持按关键词搜索小红书热门爆款笔记，并基于相关性、热度、时效三维评分智能排序推荐。同时提供热门笔记推荐和细分赛道引导，面向创作者、品牌方和 MCN 机构发现热门趋势、获取创作灵感。
注意：本工具仅在主 Agent 中执行，不派发给子 Agent。
主要能力
- 关键词智能搜索：支持关键词精确搜索、多关键词组合（逗号分隔）、全站热门查询（空关键词）。
- 三维评分排序：有关键词时按相关性（满分10分）、热度（满分3分）、时效（满分2分）加权计算总分（满分15分），全站热门按互动数排序。
- 精细意图理解：优先从用户描述中提取细分方向词，识别泛化词并自动推荐 10 个细分方向。
- 灵活时间范围：默认查询最近7天，数据不足时自动扩展时间范围（1天→3天→7天→30天），每日早上7点更新。
- 热门笔记推荐：结果较少时自动展示近期热门推荐笔记和热门话题标签。
- 细分赛道引导：每次查询后主动推荐 10 个相关细分方向。
- 拓词推荐：脚本返回 relatedSearches 字段，自动展示相关搜索建议。
- 定时订阅推送：支持创建日历订阅任务，到达设定时间自动推送最新热门笔记。
- HTML 报告生成：自动生成 {keyword}_热门数据.html 可视化文件。
- 数据说明：热门笔记收录标准为互动数1000+，顶部展示数据说明和排序依据。
安装与配置
鉴权：前往红狐hub获取 API Key。
配置方式一（以 OpenClaw 为例），将 REDFOX_API_KEY 添加到 ~/.openclaw/openclaw.json 中：
{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }
配置方式二（终端配置）：
export REDFOX_API_KEY="ak_xxxx..."
依赖安装：本 Skill 使用 Python 3 标准库，无需额外安装第三方依赖，确保系统中已安装 Python 3.x 即可。
环境变量：REDFOX_API_KEY（红狐数据 API Key），必填，获取方式为红狐hub。
使用方式
核心执行规则：泛化词必须先询问再查询。识别到泛化词时，禁止直接调用脚本，必须先输出细分词推荐并等待用户选择后再执行查询。正确执行顺序为：关键词提取 → 判断是否泛化词 → 是泛化词则询问用户 → 用户回复后再调用脚本。输出细分词推荐后必须停止执行，等待用户下一轮回复「拓展」或「不拓展」。
基础使用（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，按指南规定的展示策略输出结果。
常用命令速查：
| 场景 | 命令 |
|---|---|
| 关键词搜索（默认近7天） | 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 "词1,词2,词3" --start-date <日期> |
| 分页查询 | python scripts/fetch_xhs_hot_articles.py --keyword "关键词" --start-date <日期> --page-num 1 --page-size 50 |
| 生成 HTML 报告 | 脚本自动生成 {keyword}_热门数据.html |
| 订阅创建 | 回复1️⃣后使用 calendar_create 工具创建定时任务 |
时间范围与数据查询：数据库只包含昨天至30天前的数据；「最近」默认定义为最近7天（startDate = 今天 - 7天）。数据不足时只能扩展时间范围，不能更换或拓展关键词，调整顺序为 近1天→近3天→近7天→近30天，并告知用户自动调整结果。用户说「今天/今日」时提示今天数据暂未更新；超出30天时提示仅支持最近30天数据。
输出文件：筛选后推荐数据生成 {keyword}_热门数据.html。
展示前置说明：热门笔记范围为互动数1000以上的文章，每日早上7点更新昨日数据，互动数据截止为入库时间而非实时数据。有关键词搜索时按相关性（10分）、热度（3分）、时效（2分）加权计算总分共15分；全站热门按互动数排序，无评分字段。
展示逻辑：当 articles 数量 ≥ 10 条时展示时间范围、正常笔记数据（按对应规则排序）和拓词推荐；当 articles 数量 < 10 条但 > 0 时，额外提示结果较少并展示推荐热门笔记（默认10条，不含评分字段）和热门话题；当 articles 数量 = 0 时，输出未找到相关内容的提示、推荐搜索词和近期热门笔记。当结果超过 10 条时，初始只展示前10条并询问是否查看全部；用户确认后展示全部数据。结果输出完成后需询问订阅服务，用户选择订阅时使用 calendar_create 工具创建定时提醒，订阅成功后展示关键词、时间范围、推送时间和数据更新时间等信息。展示完数据后须推荐10个细分赛道方向词。
输出前自检：检查意图识别是否准确、笔记数据字段是否完整、HTML 卡片是否包含、是否列出10个细分词，如有遗漏必须补齐后再输出。
适用场景
- 小红书博主寻找选题灵感：输入细分关键词如「减脂餐」，系统返回高评分热门笔记列表，展示后自动推荐细分方向。
- 品牌方市场调研：输入泛化词如「穿搭」，系统推荐10个细分方向，回复「拓展」批量搜索。
- MCN 机构达人内容规划：使用逗号分隔多关键词跨领域查询。
- 每日热门笔记定时推送：搜索关键词后选择订阅，设置推送时间，创建日历定时任务。
限制
- 热门笔记收录标准为互动数1000+，关键词太小众或时间范围太短可能无数据。
- 数据库仅包含昨天至30天前的数据，每日早上7点更新昨日数据，不支持当天数据与超过30天的查询。
- 仅在主 Agent 中执行，不派发给子 Agent。
- 需配置有效的 REDFOX_API_KEY，脚本执行报错常见原因为 Key 未配置或过期、Python 版本低于 3.x、网络连接问题。
- 数据来源于红狐 API 收录的小红书公开笔记，笔记版权归原作者所有，仅供学习和内容创作参考使用。
项目架构
目录结构：
xiaohongshu-search/ ├── SKILL.md # Skill 定义与使用文档（本文件） ├── scripts/ │ └── fetch_xhs_hot_articles.py # 核心搜索脚本，调用红狐 API 获取小红书热门笔记 └── references/ └── xhs_hot_article_format.md # 数据字段格式参考文档
技术栈：运行环境为 Python 3.x（标准库，无第三方依赖）；数据接口为红狐 API (Redfox)，通过 REDFOX_API_KEY 鉴权；输出格式为 JSON (stdout) + HTML (文件)，JSON 供 AI 解析，HTML 为可视化报告；展示格式为 Markdown 表格；执行限制为仅主 Agent。
核心模块：搜索脚本 scripts/fetch_xhs_hot_articles.py 调用红狐 API 获取小红书热门笔记，支持 --keyword、--start-date、--page-num、--page-size 参数，自动生成 HTML 报告；数据格式参考 references/xhs_hot_article_format.md 说明接口返回的数据字段格式和输出规范；SKILL.md 定义 Skill 元数据、意图理解规则、泛化词拓展策略、展示策略、订阅逻辑、自检清单。