git:20260527.20d0351 to git:20260602.08c4de8

- ## 概述

- 提供小红书全品类/分品类账号每日/每周/每月的表现榜单查询。支持三大核心能力：

- 1. **排名查询** — 查日榜、周榜、月榜 TOP50

- 2. **领域查询** — 按品类筛选（美妆、美食、旅行、母婴、健身/体育锻炼等）

- 3. **报告下载** — 生成 HTML 可视化报告，支持导出 PDF/截图

- 4. **定时订阅** — 设置自动化定时推送

- ## 环境准备

- 无需安装第三方依赖，使用 Python 标准库 `urllib` 发送请求即可。

- 方案1: 以OpenClaw为例，将REDFOX_API_KEY添加到~/.openclaw/openclaw.json中，部分内容如下：

- 方案2: 终端配置

- ---

-

- ## 触发词与意图识别

- | 用户意图 | 典型触发词 | 对应操作 |

- | -------- | --------------------------------------------------------- | ----------------------------- |

- | 排名查询 | 小红书日榜、周榜、月榜、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 报告，可直接点击下载查看"

- ---

- ### 流程一：排名查询（推荐：自然语言模式）

- **直接传入用户原始问题**，脚本自动完成全部解析：

- **自动解析逻辑：**

-

- #### ① 时间判断与日期计算

- 根据当前时间判断最新数据是否已更新：

- **日期计算公式：**

-

- - 日榜：`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月」，我将为您查询最接近您需求的时间范围~」

-

- #### ④ 赛道（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}榜（综合全部）并推送给用户`

- ---

- ## 标准输出模板

- **必须按以下顺序输出，不得跳过任何步骤：**

- ### 第一步：内容输出

-

- | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |

-

- ### 第二步：询问定时订阅（直接追加，不等待回复）

-

- ```

- 📬 订阅服务

- 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！）

- - **认证方式**：`X-API-KEY` Header（从环境变量 `REDFOX_API_KEY` 获取）

- ### 请求头

- | Header | 值 | 说明 |

- | ------------ | ------------------ | -------------------------------------- |

- | Content-Type | `application/json` | 必填 |

- | X-API-KEY | `ak_xxxxxxxx` | 从环境变量 `REDFOX_API_KEY` 获取，必填 |

- ### 请求参数

- | 参数名 | 类型 | 说明 | 示例 |

- | -------- | ------ | -------------------------------- | -------------- |

- | 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 | 小红书主页链接 |

- ## 使用示例

-

- ### 示例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"。

- - **体育锻炼分类**：部分日期可能返回空数据，需要自动回退日期。