xiaohongshu-lowtop

---
name: xiaohongshu-lowtop
description: 小红书低粉爆款笔记专注于挖掘小红书平台上的低粉爆款数据，获取粉丝量低于5000但互动量超过500的笔记榜单。寻找拥有爆款规律和热门趋势的优质样本。
dependency:
  python:
    - requests>=2.28.0

---

## 1. 简介

**一句话定位**：帮你发现小红书上那些粉丝不多但内容很能打的低粉笔记，从中找到可以借鉴的选题和写法。

**核心价值**：

你只需要告诉我一个感兴趣的分类，比如「居家装修」「化妆美容」，我就能帮你捞出一批粉丝不到5000却拿到高互动的笔记。每一条都附带互动数据、发布时间和内容分析，还会自动总结这批爆款的标题套路和内容特征，让你快速摸清什么内容在涨。

**适用对象**：

+ 📌 小红书内容创作者：找选题灵感，学标题写法，了解赛道风向
+ 📌 内容运营：低粉爆款是最真实的用户喜好信号，比大V数据更有参考价值
+ 📌 MCN / 品牌方：发现潜力博主，评估内容趋势

## 2. 功能特性

### 核心功能

| 功能模块 | 能力描述 |
|:-------:|:--------|
| 📊 **分类筛选** | 覆盖25个内容分类，从综合热门到亲子育儿，输入分类名或关键词就能查 |
| 🏆 **TOP50榜单** | 按互动量从高到低排列，每条笔记都标出点赞、收藏、评论、分享数据 |
| 💡 **爆款规律分析** | 自动拆解这批笔记的标题类型、内容主题分布，提炼出可以复用的写法亮点 |
| 🔔 **每日订阅推送** | 订阅后每天19:30自动推送当日最新榜单，不用手工查询 |
| 📄 **文件包导出** | 生成小红书风格的完整页面，支持导出PDF，方便保存和分享 |

### 数据标准

查询范围：粉丝数低于5000、笔记点赞数大于500

每条笔记包含：标题、作者、粉丝数、发布时间、点赞数、评论数、收藏数、分享数、互动总数

## 3.鉴权

本技能调用 [红狐Hub API](https://redfox.hk/) 获取小红书低粉爆款数据，需要有效的 API Key 才能正常使用。

### 获取 API Key

1. 访问 [红狐Hub 官网](https://redfox.hk/) 了解服务详情
2. 前往 [注册页面](https://redfox.hk/login) 注册账号
3. **新注册用户将获赠免费积分**，可立即开始使用 API 服务
4. 注册登录后，在个人中心获取 API Key，格式为 `ak_xxxxxxxx`

### 配置 API Key

技能运行时会按以下三级回退自动获取 API Key：

| 优先级 | 来源 | 行为 |
|:---:|------|------|
| 1 | 当前环境变量 `REDFOX_API_KEY` | 直接使用 |
| 2 | Shell 配置文件（自动扫描 `~/.zshrc`、`~/.bashrc`、PowerShell profile 等） | 读取后注入当前环境变量 |
| 3 | 未找到 | 打印详细的获取和配置指引 |

若未配置，请按对应系统设置：

**macOS / Linux**：
```bash
# 将以下行追加到 ~/.zshrc（zsh）或 ~/.bashrc（bash）
export REDFOX_API_KEY=<你的apikey>
# 然后执行使其生效
source ~/.zshrc  # 或 source ~/.bashrc
```

**Windows**：
```powershell
# PowerShell（管理员模式）
[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "<你的apikey>", "User")
```
配置后需重启终端生效。

**验证配置**：
- macOS / Linux：`echo $REDFOX_API_KEY`
- Windows CMD：`echo %REDFOX_API_KEY%`
- Windows PowerShell：`echo $env:REDFOX_API_KEY`

若不会配置，告诉Agent主动帮助设置。

## 4. 使用指南

### 4.1 基础查询

1. 触发技能后，告诉我想查的分类和日期
2. 不指定日期时，系统自动取最近可用的数据日
3. 等待结果输出，包含榜单表格和规律分析

### 4.2 进阶操作

**订阅每日推送**

回复「订阅」或在结果页选择订阅，之后每天19:30自动收到最新榜单。

**导出文件包**

回复「2」生成完整页面文件包，包含所有笔记数据和排版，可导出PDF。

### 4.3 核心执行流程

1. 触发技能后，先问用户要查什么分类、哪天的数据
2. 调用主脚本获取数据，脚本通过原生 socket+SSL 请求 API，自动匹配分类、处理日期
3. 脚本按三级回退（环境变量 → Shell 配置 → 提示用户）获取 REDFOX_API_KEY 进行鉴权
4. 脚本生成 md 报告文件和数据缓存 JSON 文件（`*_cache.json`），读取 md 全部内容原样输出给用户
5. 输出包含三部分：爆款笔记表格、爆款规律分析、功能选择入口
6. 等待用户选择：订阅、导出文件包（回复「2」）、查看更多，或不操作
7. 用户回复「2」时：从缓存生成 HTML → preview_url 自动展示（若未正常展示则用 open_result_view 兜底）→ deliver_attachments 发送文件 → 告知保存路径

### 4.4 节能机制：HTML 生成不重复请求 API + 自动展示

用户回复「2」生成 HTML 文件包时，Agent 执行以下步骤：

**第一步：生成 HTML（不请求 API）**

直接从已获取的数据缓存文件渲染，不再请求 API：

- 主脚本在生成 md 报告的同时，自动输出 `*_cache.json` 缓存文件，存储完整的 articles 列表
- HTML 生成脚本 `generate_html_on_demand.py` 支持 `--from-cache` 参数，指向缓存文件即可直接渲染
- 保留 `--rank_date` + `--keyword` 回退模式，仅在缓存文件不可用时手动请求

**调用示例**：
```bash
# 节能模式：从缓存生成 HTML（0 次 API 请求）
python generate_html_on_demand.py --from-cache ./小红书居家装修低粉爆款数据_xxx_cache.json --output ./output.html

# 回退模式：重新请求 API 获取数据后渲染（仅缓存缺失时使用）
python generate_html_on_demand.py --rank_date 2026-05-26 --keyword 居家装修 --output ./output.html
```

**第二步：自动展示 + 发送 HTML（必须执行，两步都要做）**

生成 HTML 后，Agent 必须按顺序执行以下操作：

1. 优先使用 `preview_url` 工具打开该文件，让用户直接看到可视化页面
2. 若 `preview_url` 未正常展示（含中文路径等兼容问题），立即改用 `open_result_view` 兜底展示
3. 使用 `deliver_attachments` 工具将 HTML 文件作为附件发送给用户，确保用户在不同客户端都能收到文件

以上操作缺一不可。完成后告知用户文件保存路径。

## 5. 使用场景

### 场景一：日常选题找灵感

**角色**：小红书创作者

**需求**：不知道今天写什么，想看同一赛道别人在发什么

**使用方式**：

1. 输入自己所在的内容分类，比如「化妆美容」
2. 浏览 TOP50 榜单，看看哪些选题拿到了高互动
3. 参考爆款规律分析中的标题模版和内容特征，结合自己的风格重新创作


### 场景二：竞品内容监测

**角色**：内容运营 / 品牌方

**需求**：了解某一赛道的低粉黑马在做什么内容，判断趋势

**使用方式**：

1. 选择目标分类定期查询
2. 关注笔记的内容主题分布和标题特征变化
3. 对比不同日期的规律分析，发现新兴的话题方向


### 场景三：爆款规律研究

**角色**：内容策略分析师

**需求**：系统性研究某一分类的爆款规律

**使用方式**：

1. 连续多天查询同一分类
2. 对比不同日期的标题类型占比和内容主题变化
3. 导出文件包存档，便于整理分析报告


## 6. 项目架构

### 6.1 目录结构

```
xiaohongshu-lowtop/
├── SKILL.md
├── scripts/
│   ├── fetch_explosive_articles.py      # 主脚本：数据获取（原生 socket+SSL） + 分析 + md输出
│   └── generate_html_on_demand.py       # HTML文件包生成
├── references/
│   └── api-spec.md                      # API接口规范
└── assets/
    └── preview-template.html            # HTML页面模版
```

### 6.2 技术构成

| 组件 | 说明 |
|:----:|:----|
| Python 3 | 核心脚本语言 |
| socket / ssl | 原生网络请求 |
| json | 数据解析 |
| argparse | 命令行参数 |
| HTML模板 | 文件包页面渲染 |

### 6.3 数据流转

**主查询流程**：用户输入分类关键词 → 匹配对应分类 → 调用数据接口（1次API请求） → 获取笔记数据 → 按互动量排序 → 生成榜单表格 + 缓存JSON → 自动分析标题特征和内容主题 → 输出完整报告

**HTML生成流程（节能+自动展示）**：用户选择导出 → 读取缓存JSON文件（0次API请求） → 渲染HTML页面 → Agent 立即用 preview_url 自动展示 → 告知保存路径

## 7. 常见问答

### 查询相关问题

**Q1：查出来好多笔记跟我想的分类不相关怎么办？**

A：分类匹配基于关键词和内容标签，偶尔会有跨界内容混入。如果结果偏差较大，可以试试换个更精准的关键词，比如查「居家装修」比查「装修」更准确。

**Q2：为什么数据不是当天的？**

A：数据每天19:30更新一次。19:30之前查询会取前一天的数据，这是正常的更新节奏。

**Q3：输入「查看更多」后没有反应？**

A：确认数据总量超过20条。如果总数不超过20条，首次输出就是全部内容。

### 订阅相关问题

**Q4：订阅后每天什么时候推送？**

A：每天19:30自动推送当日最新数据。

**Q5：可以订阅多个分类吗？**

A：当前每次订阅一个分类，想换分类需要重新订阅。

### 文件导出问题

**Q6：导出的文件包长什么样？**

A：生成一个完整的小红书风格页面，每条笔记都有独立卡片，包含标题、作者、互动数据和内容分析。可以直接在浏览器打开或导出PDF。

## 8. 资源索引

- 核心脚本：[scripts/fetch_explosive_articles.py](scripts/fetch_explosive_articles.py) — 数据获取（原生 socket+SSL，三级 API Key 鉴权）、分析和 md 输出
- HTML生成：[scripts/generate_html_on_demand.py](scripts/generate_html_on_demand.py) — 用户回复「2」后调用，支持 `--from-cache` 节能模式（0次API请求）和 `--rank_date` 回退模式
- 页面模版：[assets/preview-template.html](assets/preview-template.html) — HTML文件包排版模版
- 接口规范：[references/api-spec.md](references/api-spec.md) — 数据接口说明及 API Key 认证方式