back
loading skill details...
小红书账号榜单追踪分析工具,支持查询日榜周榜月榜TOP50排名和热门账号
---
name: xiaohongshu-rank-tracker
description: 小红书账号榜单追踪分析工具,支持查询日榜周榜月榜TOP50排名和热门账号
dependency:
python:
- requests>=2.28.0
---
# 小红书全品类账号榜单 Skill
## 概述
本 Skill 基于 `https://redfox.hk/story/api/xhsData/query` 数据接口,
提供小红书全品类/分品类账号每日/每周/每月的表现榜单查询。支持三大核心能力:
1. **排名查询** — 查日榜、周榜、月榜 TOP50
2. **领域查询** — 按品类筛选(美妆、美食、旅行、母婴、健身/体育锻炼等)
3. **报告下载** — 生成 HTML 可视化报告,支持导出 PDF/截图
4. **定时订阅** — 设置自动化定时推送
---
## 触发词与意图识别
| 用户意图 | 典型触发词 | 对应操作 |
| -------- | --------------------------------------------------------- | ----------------------------- |
| 排名查询 | 小红书日榜、周榜、月榜、TOP50、最夯账号、排行榜、最新推荐 | 调用 API 并格式化输出 |
| 领域查询 | 美妆类/美食类/旅行类/母婴类/健身类...小红书排名 | 调用 API 并按 category 筛选 |
| 报告下载 | 下载报告、导出榜单、生成报告 | 使用 --html 参数自动生成 HTML |
| 定时订阅 | 订阅日榜/周榜/月榜、定时推送、每天发给我 | 创建 WorkBuddy Automation |
---
## 执行流程
### 严格输出顺序(必须按顺序执行,不得跳过)
**第一步:内容输出**
1. 调用脚本查询榜单数据(默认只查20条):
```bash
python scripts/fetch_rank.py --query "用户原始问题" --limit 20 --html
```
2. 按标准模板格式化输出榜单数据(Markdown 表格形式,最多20条)
**第二步:询问定时订阅**
- 输出完榜单数据后,**直接**追加以下询问(不等待用户回复):
```
📬 订阅服务
1️⃣ 是否需要订阅每日/周/月的小红书账号最新排名,订阅后定时推送给您?
2️⃣ 是否需要订阅具体赛道的账号表现?我们支持:综合全部、出行代步、休闲爱好、影视娱乐、数码科技、医疗保健、综合杂项、星座情感、时尚穿搭、婚庆婚礼、拍摄记录、学习教育、化妆美容、居家装修、旅行度假、亲子育儿、个人护理、美味佳肴、职业发展、宠物天地、潮流鞋包、日常生活、科学探索、新闻资讯、体育锻炼
```
**第三步:交付 HTML 报告**
- 脚本已自动生成HTML文件,使用 deliver_attachments 工具交付脚本输出的 HTML 文件路径
- 追加以下内容:
```
⚡ 更多操作
• 点击下方下载HTML报告文件,可在浏览器中打开查看,支持一键导出PDF/高清图片
• 本次榜单完整共50条数据,是否需要查看全部?
```
**用户表示需要查看全部数据时:**
> ⚠️ **强制要求**:必须同时输出 Markdown 表格和交付 HTML 报告,两者缺一不可。
1. 重新调用脚本获取完整50条数据:
```bash
python scripts/fetch_rank.py --query "用户原始问题" --limit 50 --html
```
2. 在对话中输出完整50条数据的 Markdown 表格(按标准模板格式)
3. **必须使用 deliver_attachments 交付 HTML 文件**(关键步骤,不可遗漏),告知用户"以下是完整50条数据的 HTML 报告,可直接点击下载查看"
---
### 流程一:排名查询(推荐:自然语言模式)
**直接传入用户原始问题**,脚本自动完成全部解析:
```bash
python scripts/fetch_rank.py --query "用户原始问题" --limit 20 --html
```
**自动解析逻辑:**
#### ① 时间判断与日期计算
根据当前时间判断最新数据是否已更新:
| 榜单类型 | 更新时间 | 当前时间 < 更新时间 | 当前时间 >= 更新时间 |
| -------- | ---------------- | ------------------- | -------------------- |
| 日榜 | 每日 19:00 | 取前2天 (offset=2) | 取前一天 (offset=1) |
| 周榜 | 每周一 15:00 | 取前2周 (offset=2) | 取前1周 (offset=1) |
| 月榜 | 每月2号 上午9:00 | 取前2月 (offset=2) | 取前1月 (offset=1) |
**日期计算公式:**
- 日榜:`date.today() - timedelta(days=offset)`
- 周榜:`date.today() - timedelta(weeks=offset)` 后的最近周一
- 月榜:`date.today() - timedelta(days=30*offset)` 后的每月2号
**更新规则(输出时告知用户):**
- 日榜:每日 **19:00** 更新
- 周榜:每周一 **15:00** 更新
- 月榜:每月 **2号 9:00** 更新
#### ② 周期判断
自动从用户文本中识别日/周/月(无明确则默认**日榜**):
- 含"周"/"周榜"→ `week`
- 含"月"/"月榜"→ `month`
- 其余默认 → `day`
#### ③ 回溯范围校验
| 榜单类型 | 最大回溯 | 超范围处理 |
| -------- | -------- | ---------------------- |
| 日榜 | 近7天 | 自动切换至最近可用日期 |
| 周榜 | 近3周 | 自动切换至最近可用日期 |
| 月榜 | 近3个月 | 自动切换至最近可用日期 |
**超出范围时**:-若用户查询当日及未来日期的榜单,在榜单说明输出中增加:「非常抱歉🙏,我们最新的是昨日/上周/上月的数据,将为您提供最接近您需求的昨日/上周/上月热榜。」-若用户查询时间早于回溯日期,在榜单说明输出中增加回复:「非常抱歉🙏,目前榜单最多支持回溯「过去7天/过去3周/过去3月」,我将为您查询最接近您需求的时间范围~」
#### ④ 赛道(type)匹配
支持模糊匹配,映射表见 `references/api_docs.md`。
**常用映射:**
| 用户说 | 映射到 |
|--------|--------|
| 健身、运动、瑜伽 | 体育锻炼 |
| 美妆、彩妆、护肤 | 化妆美容/个人护理 |
| 美食、探店、烹饪 | 美味佳肴 |
| 旅行、旅游 | 旅行度假 |
| 母婴、育儿 | 亲子育儿 |
| 穿搭、时尚 | 时尚穿搭 |
若无法匹配,输出综合全部,并告知用户无法识别的赛道类别。
#### ⑤ 数据回退机制
**重要**:部分分类(如体育锻炼)在某些日期可能返回空数据。此时应:
1. 自动尝试前一个日期
2. 最多回退3天
3. 若仍无数据,告知用户该分类在该时间段暂无数据
---
### 流程二:报告下载
1. 查询时加 `--html --limit 50` 参数,脚本会自动生成HTML报告
2. 调用 `deliver_attachments` 交付 HTML 文件(账号名均可点击跳转小红书主页)
---
### 流程三:定时订阅
1. 询问订阅周期(每日 / 每周 / 每月)。
2. 使用 `automation_update` 创建自动化任务:
- 每日订阅:`FREQ=DAILY;BYHOUR=8;BYMINUTE=0`
- 每周订阅:`FREQ=WEEKLY;BYDAY=MO;BYHOUR=8;BYMINUTE=0`
- 每月订阅:`FREQ=WEEKLY;BYDAY=MO;BYHOUR=8;BYMINUTE=0;INTERVAL=4`
3. automation prompt:`查询小红书最新{period}榜(综合全部)并推送给用户`
---
## 标准输出模板
**必须按以下顺序输出,不得跳过任何步骤:**
### 第一步:内容输出
```
📊 小红书{period_label} · {category_label}
数据日期:{date}
共 {total} 个账号上榜
💡 榜单说明:{period_update_time}更新昨日/上周/上月数据。
📐 排名算法:排名根据达人在小红书的**总粉丝数**、周期内的**粉丝增量**、**点赞增量**、**收藏增量**、**分享增量**以及**评论增量**加权计算所得,满分100分。
| 排名 | 账号名 | 综合评分 | 总粉丝数 | 新增笔记 | 新增粉丝 | 新增点赞 | 新增评论 | 新增收藏 | 新增分享 |
|:---:|--------|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|
| 🥇 1 | 账号A · 赛道 | 96 | 254.06w | 7 | 6919 | 24.64w | 6.68w | 2.53w | 13.39w |
| 🥈 2 | 账号B · 赛道 | 89 | 113.55w | 1 | 1.91w | 7.90w | 4787 | 2.18w | 3.12w |
| 🥉 3 | 账号C · 赛道 | 87 | 439.14w | 2 | 5859 | 16.51w | 993 | 7688 | 687 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
统计概览:上榜账号 {total} · 最高互动 {max_interaction} · 总新增笔记 {total_notes}
```
### 第二步:询问定时订阅(直接追加,不等待回复)
```
📬 订阅服务
1️⃣ 是否需要订阅每日/周/月的小红书账号最新排名,订阅后定时推送给您?
2️⃣ 是否需要订阅具体赛道的账号表现?我们支持:综合全部、出行代步、休闲爱好、影视娱乐、数码科技、医疗保健、综合杂项、星座情感、时尚穿搭、婚庆婚礼、拍摄记录、学习教育、化妆美容、居家装修、旅行度假、亲子育儿、个人护理、美味佳肴、职业发展、宠物天地、潮流鞋包、日常生活、科学探索、新闻资讯、体育锻炼
```
**用户回复"需要订阅"时**,使用 `calendar_create` 工具创建日程:
- 参数:
- `title`: 小红书{period_label}榜单推送
- `description`: 订阅小红书{period_label}榜单,自动查询并推送最新排名数据
- `start_time`: 根据订阅周期计算(每日08:00/每周一08:00/每月2号08:00)
- `end_time`: start_time 后1小时
- `reminder`: 0(不需要提醒)
- 创建成功后告知用户日程已创建
### 第三步:交付 HTML 报告(必须交付)
> ⚠️ **强制要求**:必须立即使用 deliver_attachments 交付文件,不得仅提示用户下载而不实际交付。
- 脚本已自动生成HTML文件(路径在输出末尾)
- **必须使用 deliver_attachments 交付 HTML 文件**(这是关键步骤,遗漏将导致用户看不到报告)
- 交付后追加以下提示:
```
⚡ 更多操作
• 点击下方下载HTML报告文件,可在浏览器中打开查看,支持一键导出PDF/高清图片
• 本次榜单完整共50条数据,是否需要查看全部?
```
> ⚠️ **字段说明**:
>
> - **最高互动**:互动总数 = 点赞 + 评论 + 收藏 + 分享,取榜单中互动最高的账号
> - 当前接口仅返回各细分字段(总粉丝数、新增粉丝、新增点赞、新增评论、新增收藏、新增分享)
> - 赛道展示在账号名下方,使用 "账号名 · 赛道" 格式
---
## HTML 报告模板规范
### 表格列规范
| 列名 | 说明 |
| -------- | ------------------------------------------ |
| 排名 | 1-3名使用金银铜牌样式,其余使用灰色徽章 |
| 账号名 | 可点击跳转小红书主页,赛道展示在账号名下方 |
| 总粉丝数 | 格式:254.06w |
| 新增笔记 | 整数 |
| 新增粉丝 | 整数或带 w 单位 |
| 新增点赞 | 带 w 单位 |
| 新增评论 | 整数或带 w 单位 |
| 新增收藏 | 整数或带 w 单位 |
| 新增分享 | 整数或带 w 单位 |
**注意**:不展示综合评分列,表格从11列减少到9列。
### 统计卡片规范
| 指标 | 说明 |
| ---------- | ------------------------------------ |
| 上榜账号 | 榜单总数,默认50 |
| 最高互动 | 互动总数 = 点赞 + 评论 + 收藏 + 分享 |
| 总新增笔记 | 所有账号新增笔记之和 |
### 榜单说明与排名算法
```html
<div class="notice">
<div style="margin-bottom: 8px;">
💡 <strong>榜单说明</strong>:{period_update_desc}更新,与实时数据存在差异。
</div>
<div>
📐 <strong>排名算法</strong>:排名根据达人在小红书的
<strong>总粉丝数</strong>、周期内的
<strong>粉丝增量</strong
>、<strong>点赞增量</strong>、<strong>收藏增量</strong>、<strong
>分享增量</strong
>
以及 <strong>评论增量</strong> 加权计算所得。
</div>
</div>
```
---
## API 参数说明
### 接口信息
- **URL**:`POST https://redfox.hk/story/api/xhsData/query`
- **成功码**:`code: 2000`(非0!)
### 请求参数
| 参数名 | 类型 | 说明 | 示例 |
| -------- | ------ | -------------------------------- | -------------- |
| dateType | int | 榜单类型:1=日榜, 2=周榜, 3=月榜 | 1 |
| rankDate | string | 日期(格式:YYYY-MM-DD) | "2026-04-28" |
| type | string | 赛道名称(中文) | "体育锻炼" |
| source | string | **必须为** `小红书指数榜` | "小红书指数榜" |
### 各榜单日期参数
| 榜单类型 | rankDate 格式 | 示例 | offset计算 |
| -------- | ---------------------------- | ---------------- | ------------------------------------------ |
| 日榜 | YYYY-MM-DD(前一天或前两天) | "2026-04-28" | 当前时间<19:00→offset=2, ≥19:00→offset=1 |
| 周榜 | YYYY-MM-DD(周一) | "2026-04-20" | 当前时间周一<15:00→offset=2, 否则→offset=1 |
| **月榜** | **YYYY-MM-02(每月2号)** | **"2026-04-02"** | 当前时间2号<09:00→offset=2, 否则→offset=1 |
### 返回字段
| 字段 | 说明 |
| ------------ | -------------- |
| accountName | 账号名 |
| category | 赛道分类 |
| followers | 总粉丝数 |
| newNoteCount | 新增笔记数 |
| newFans | 新增粉丝 |
| newLikes | 新增点赞 |
| newComments | 新增评论 |
| newCollects | 新增收藏 |
| newShares | 新增分享 |
| profileUrl | 小红书主页链接 |
---
## 环境准备
```bash
pip install requests
```
---
## 使用示例
### 示例1:查询美妆类日榜
- 场景/输入:用户说"小红书美妆日榜"
- 预期产出:返回美妆类当日 TOP20 榜单数据
- 关键要点:自动解析赛道为"化妆美容",日期自动计算为最新可用日期
### 示例2:查询美食类周榜
- 场景/输入:用户说"最新美食周榜"
- 预期产出:返回美食类上周榜单
- 关键要点:自动解析周期为 week,赛道为"美味佳肴"
### 示例3:生成 HTML 报告
- 场景/输入:用户需要导出完整报告
- 预期产出:生成可下载的 HTML 文件
- 关键要点:调用 fetch_rank.py 时加 --html 参数自动生成HTML报告
---
## 资源索引
- 脚本:见 [scripts/fetch_rank.py](scripts/fetch_rank.py)(用途:查询小红书榜单数据)
- 脚本:见 [scripts/generate_report.py](scripts/generate_report.py)(用途:被 fetch_rank.py --html 调用生成 HTML)
- 参考:见 [references/api_docs.md](references/api_docs.md)(何时读取:需要查看 API 详细参数说明时)
---
## 注意事项
- 日榜默认展示 TOP 20,完整 50 条通过报告或追问查看。
- 赛道关键词支持 LLM 语义模糊匹配,实在无法识别时降级为综合全部。
- HTML 报告账号名均可点击跳转小红书主页(基于 `profileUrl` 字段)。
- 生成报告前确保 workspace 有写权限。
- **最高互动**需要根据点赞+评论+收藏+分享计算,不能直接使用接口返回的 `newInteraction` 字段(该字段值可能为0)。
- **月榜日期参数必须使用每月2号**,如查询上月榜单用 "2026-04-02"。
- **体育锻炼分类**:部分日期可能返回空数据,需要自动回退日期。
don't have the plugin yet? install it then click "run inline in claude" again.