redfox-data 小红书七日爆款笔记
简介
一句话定位：专为内容创作者与运营人员设计的小红书七日爆款笔记工具，一键获取垂直领域热门笔记与深度分析。
核心价值：
- 解决「不知道当下什么内容火、为什么火」的选题难题
- 提供七日爆款笔记 + 智能分析 + 可选 HTML 报告，支撑复盘与创作决策
- 支持关键词自动匹配 24 个垂直分类（原"综合杂项"已归类到"综合全部"），降低查询门槛
适用对象：品牌方、MCN 机构、小红书博主、内容运营、增长团队
技术基础：Python 3 + RedFox 小红书数据 API，数据每日 19:00 更新
功能特性
🎯 核心功能
| 功能 | 说明 |
|---|---|
| 📊 近日热榜查询 | 按分类查询热门笔记，覆盖美妆、穿搭、美食、家居等24个垂直领域，快速掌握当下流量风向 |
| 📈 七日热门分析 | 基于近7天各分类TOP50热门笔记的深度洞察，从流行趋势、热门话题深度分析、实用价值等维度拆解爆款共性 |
| 🔍 形式规律对比 | 自动识别高质量封面、情绪共鸣点、实用价值、紧跟热点等爆款要素，提炼可复用的创作范式 |
| 📁 创作建议输出 | 基于分析结果，提供可执行的选题方向、差异化策略、高维作品拆解建议 |
| 🔔 订阅推送 | 定时推送最新趋势分析报告，持续跟踪赛道热点，不错过任何一个流量机会 |
✨ 特色亮点
- ⚡ 数据一致：七日爆款笔记表格与 HTML 页面使用相同数据源与排序逻辑，排名完全一致
- 📱 分页展示：首次展示 TOP20，回复「查看更多」可加载剩余数据
- 🎯 冷门爆款：聚焦低粉高互动笔记，适合挖掘可对标样本
- 🔒 零配置调用：Agent 执行时自动判断查询日期，无需手动维护
鉴权
获取 API Key
配置 API Key
REDFOX_API_KEY 从环境变量获取，格式 ak_xxxxxxxx。
若未设置，提示用户自行配置：export REDFOX_API_KEY=<你的apikey>；若不会配置，Agent 可主动帮用户设置：
- macOS/Linux：将
export REDFOX_API_KEY=<值>追加到~/.zshrc（zsh）或~/.bashrc（bash），然后source对应文件使其全局生效 - Windows：使用
[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "<值>", "User")设置用户级永久环境变量（需重启终端生效）
配置完成后应验证：echo $REDFOX_API_KEY（macOS/Linux）或 echo %REDFOX_API_KEY%（Windows），确保换一个 skill 也能读取到。
一键安装
前置条件
- Python 3.8+
- 网络可访问
redfox.hk数据 API - 已安装
requests库（pip install requests） - 已配置
REDFOX_API_KEY环境变量（参见上方「鉴权」章节）
安装方式
方式一：WorkBuddy / Cursor Skills（推荐）
- 将本 Skill 目录放置于 Skills 工作区（如
~/.workbuddy/skills/xiaohongshu-weeklytop） - 确保目录结构完整：
SKILL.md、references/、scripts/ - 在对话中直接触发，例如：
- 「帮我查一下睫毛膏相关的爆款笔记」
- 「最近小红书有什么热门内容」
- 「查看穿搭领域七日热榜」
方式二：命令行独立运行
# 进入 Skill 目录
cd xiaohongshu-weeklytop
# 获取榜单数据（JSON 输出）
python scripts/xhs_weekly_fetcher.py --keyword "睫毛膏" --top_n 50
# 生成 HTML 报告（从已获取的数据文件读取，不再调用API）
python scripts/gen_xhs_html.py --data_file "xhs_data.json" --category "化妆美容" --top 20
使用指南
执行约束（强制）：Agent 执行本 Skill 时，必须先完整阅读并严格遵循 references/core_workflow.md 中的调用 Key 说明、输出规范、操作步骤与注意事项。以下为基础用法摘要，详细流程以核心工作流文档为准。
基础使用
1. 关键词查询爆款
用户：帮我查一下睫毛膏相关的爆款笔记
助手：自动匹配「化妆美容」分类 → 获取 TOP50 数据 → 输出七日爆款笔记 TOP20 → 七日分析 → 功能询问（HTML+订阅）
2. 关键词未精确匹配（v2.0）
用户：查一下洗浴中心相关的爆款
助手：关键词未命中任何分类关键词 → 禁止直接查询 → 展示推荐相近分类（1~3个，按相关度，仅强相关不强凑） + "⚠️若无想要查询的分类，可前往 https://redfox.hk/apis/xiaohongshu/384C6W6B?source=github API文档查询更精确的作品~" 选项 → 等待用户确认分类（确认后以指定分类重新查询）或选择"若无..."（停止后续所有流程）
3. 泛领域热门查询
用户：最近小红书有什么热门内容
助手：使用「综合全部」分类 → 按标准三步输出完整结果
4. 查看更多数据
用户：查看更多
助手：延续输出 TOP21 至末尾 → 如用户选择生成 HTML，从已获取数据文件读取完整数据重新生成
高级使用
1. 指定日期查询
用户：查看 2026-04-15 穿搭领域热榜
助手：使用
--rank_date "2026-04-15"查询指定日期数据
2. 直接指定分类
python scripts/xhs_weekly_fetcher.py --category "时尚穿搭" --top_n 50
python scripts/gen_xhs_html.py --category "时尚穿搭" --top 50
3. 订阅每日推送 / 生成 HTML
首次查询完成后，助手会展示功能询问：回复 1 订阅每日 19:30 推送，回复 2 生成小红书风格 HTML 文件包。HTML 生成后会自动在对话中预览展示（优先 preview_url，未正常展示则用 open_result_view 兜底），无需手动查找文件。
4. 自定义 HTML 输出路径
python scripts/gen_xhs_html.py --data_file "xhs_data.json" --category "穿搭" --top 20 --output ./reports/小红书七日爆款笔记_穿搭.html
常用命令速查
| 命令 / 场景 | 功能 |
|---|---|
python scripts/xhs_weekly_fetcher.py --keyword "{词}" --top_n 50 |
获取榜单原始数据 |
python scripts/gen_xhs_html.py --data_file "{文件}" --category "{分类}" --top 20 |
首次生成 HTML（TOP20，从数据文件读取） |
python scripts/gen_xhs_html.py --data_file "{文件}" --category "{分类}" --top 50 |
查看更多后生成完整 HTML |
| 用户说「查看更多」 | 输出 TOP21+ |
用户回复 1 / "订阅" |
订阅每日 19:30 推送 |
用户回复 2 / "html" / "生成" |
生成 HTML 文件包 |
核心工作流引用
完整执行规范（输出格式、调用 Key、表格字段、数据一致性、订阅逻辑、使用示例等）见：
→ references/core_workflow.md
使用场景
场景一：博主选题灵感
角色：小红书新人博主
需求：了解同赛道当下什么内容容易爆
使用方式：
- 输入赛道关键词（如「护肤」「穿搭」）
- 查看七日爆款笔记 TOP20 与七日分析
- 对标参考笔记的标题结构与内容特征
预期收益：快速找到可借鉴的选题方向，降低冷启动试错成本
场景二：品牌竞品监测
角色：品牌营销经理
需求：监测垂直领域爆款内容与趋势变化
使用方式：
- 按产品/品类关键词查询（如「口红」「防晒」）
- 分析最高互动作品的共性特征
- 导出 HTML 报告供团队复盘
预期收益：掌握品类内容风向，优化投放与种草策略
场景三：MCN 达人运营复盘
角色：MCN 运营人员
需求：为旗下达人提供赛道热点参考
使用方式：
- 按达人赛道查询七日热榜
- 拆解爆款标题类型与发布规律
- 订阅每日推送，持续跟踪热点
预期收益：提升达人内容策划效率，缩短选题讨论周期
场景四：增长团队数据洞察
角色：增长/数据分析同学
需求：获取可导出的结构化热榜报告
使用方式：
- 查询目标分类完整 TOP50
- 使用 HTML 页面导出 PDF/图片
- 结合新增互动数据判断内容上升势头
预期收益：获得可分享、可归档的数据报告，支撑周报与策略会
项目架构
目录结构
xiaohongshu-weeklytop/
├── SKILL.md # Skill 入口与使用说明（本文件）
├── references/
│ └── core_workflow.md # 核心执行流程与输出规范（Agent 必读）
└── scripts/
├── xhs_weekly_fetcher.py # 榜单数据获取脚本
└── gen_xhs_html.py # HTML 可视化报告生成脚本
技术栈
| 项目 | 说明 |
|---|---|
| 运行环境 | Python 3.8+ |
| HTTP 请求 | requests（原生 Python） |
| 数据来源 | RedFox 小红书 Coze Skill API |
| 输出格式 | Markdown 表格 + 独立 HTML 文件 |
| 部署平台 | WorkBuddy / Cursor Agent Skills |
核心模块
| 模块 | 文件 | 职责 |
|---|---|---|
| 数据获取 | xhs_weekly_fetcher.py |
调用 API、分类匹配、日期判断、排序输出 |
| 报告生成 | gen_xhs_html.py |
从已获取的 JSON 数据文件渲染 HTML 页面，支持 PDF/图片导出 |
| 执行规范 | core_workflow.md |
定义输出格式、调用 Key、三步流程、功能询问等强制约束 |
数据更新规则
- 更新时间：每天 19:00 更新昨日榜单
- 数据范围：往前 7 天热门笔记 TOP50
- 分类覆盖：24 个垂直领域（原"综合杂项"已归类到"综合全部"）
- 日期判断：当前时间 ≥ 19:00 查昨日，< 19:00 查前天
常见问答
安装相关问题
Q1: 脚本运行报错 ModuleNotFoundError: requests？
A: 该依赖为标准 Python HTTP 库。请运行 pip install requests 安装。若在虚拟环境中运行，请确保已激活对应环境。
Q2: 脚本提示「未找到 REDFOX_API_KEY」？
A: 请按照上方「鉴权」章节完成 API Key 的获取和配置。确保环境变量 REDFOX_API_KEY 已正确设置且格式为 ak_xxxxxxxx。
Q3: 如何将 Skill 添加到 Cursor / WorkBuddy？
A: 将 xiaohongshu-weeklytop 文件夹放入 Skills 目录，Agent 会根据 description 自动匹配触发。对话中提及「小红书热门」「爆款笔记」等关键词即可调用。
使用相关问题
Q4: 数据多久更新一次？
A: 榜单数据每日 19:00 更新（更新的是昨日数据）。订阅推送时间为每日 19:30。
Q5: 为什么有时查的是「前天」而不是「昨天」？
A: 当日 19:00 之前，最新榜单尚未更新，系统自动查询前天数据。19:00 之后则查询昨日数据。详见 core_workflow.md 日期判断规则。
故障排除
Q6: 七日爆款笔记表格与 HTML 数据不一致？
A: HTML 生成时从已获取的 JSON 数据文件读取，与表格使用完全相同的原始数据。检查是否使用了不同的 --top 参数。
Q7: API 请求失败或无数据？
A: 按以下步骤排查：
- 确认网络可访问 红狐Hub 官网
- 检查
--rank_date是否为有效日期 - 尝试更换关键词或指定
--category - 19:00 前查询时，确认是否应使用前天日期
执行规范
Q8: Agent 执行时必须遵守哪些规则？
A: 必须完整遵循 references/core_workflow.md，包括但不限于：
- 调用 Key 说明（脚本参数与 top_n/top 取值规范）
- 三步输出顺序（七日爆款笔记 → 分析 → 功能询问）
- 禁止折叠输出、禁止输出除 HTML 外的文件
- 首次 TOP20 + 查看更多逻辑
- HTML 生成时从已获取数据文件读取，禁止再次调用 API
- HTML 生成后必须调用 preview_url 在对话中直接展示页面；若未正常展示则用 open_result_view 兜底
- 功能询问在分析之后立即展示，禁止跳过