xhs-explosive-detector（小红书爆款雷达）

SKILL.md

---
name: xhs-explosive-content-detector
description:
  当品牌方、MCN、创作者与增长团队要把小红书「爆款信号」沉淀为可复盘的对标样本与选题情报时使用：
  支持按赛道关键词与时间窗口，检索低粉高赞、周期高赞、单日爆发与持续增长等多维笔记，日更 2000+ 条收录维度、25 类主流赛道、意图分层匹配输出粒度、个性化推荐理由。
dependency:
  python:
    - requests>=2.28.0
---

# 小红书爆款雷达

需要执行完整判定规则、对话分支与脚本细节时，**必须先读取**同目录 `references/core_workflow.md` 并严格遵循其中的路径与步骤说明。

---

## 简介

面向 **品牌种草、MCN 星探、自媒体创作与内容运营** 的小红书爆款情报工具：用可复现的数据样本替代「凭感觉找对标」，缩短从选题到验证的路径。

通过关键词与时间窗口检索，你可以：

- 🔍 **规模化发现**：日更 2000+ 条符合收录维度的爆款样本，降低手工扒榜成本
- 🎯 **弱化头部偏差**：低粉爆款、周期高赞、单日互动增量与持续增长等维度并举，提升对标可参考性
- 📊 **即拿即用交付**：结构化摘要 + 可视化 HTML，便于内部分享、提案与复盘

**技术基础**：Python 3.8+、`requests`；数据来源于小红书公开内容聚合接口（具体字段与过滤逻辑见 `references/core_workflow.md`）。

---

## 功能特性

### 🎯 核心功能

- **📊 多维爆款筛选**：低粉爆款、周期高赞、单日爆发、持续增长等标准组合，减少「大号可复制性弱」带来的误判
- **🏷️ 赛道对齐**：支持 25 个主流内容分类，便于按垂直领域收敛样本
- **🤖 意图分层**：区分泛浏览、明确需求与数据向诉求，匹配输出粒度与排序侧重
- **💡 推荐理由生成**：结合意图与互动表现生成非模板化说明，单条理由不少于 15 字（规则见工作流）

### ✨ 特色亮点

- **⏰ 时间窗口弹性**：支持近 1 / 3 / 7 / 30 天；样本不足时按工作流自动扩展区间并明示
- **📤 双形态输出**：Markdown 卡片 + 本地 HTML 文件，便于预览、归档与二次编辑
- **🔗 细分词拓展**：识别泛化关键词后给出约 10 个细分方向，**用户确认后再执行**检索，降低无效请求
- **⚡ 低接入成本**：无需小红书账号与 API Key；配置依赖与可选代理即可运行（合规使用自有责任）

---

## 使用指南

### 环境与依赖（安装前）

1. 安装 **Python 3.8+**，保证终端可执行 `python`。
2. 进入项目根目录，安装依赖：

```bash
pip install requests>=2.28.0
```

3. （可选）配置环境变量：

| 变量名          | 必填 | 说明                                          |
| --------------- | ---- | --------------------------------------------- |
| `XHS_API_PROXY` | 否   | 代理地址，示例：`http://127.0.0.1:7890`       |
| `OUTPUT_PATH`   | 否   | 生成的 `.html` 保存目录；默认脚本当前工作目录 |

### 基础使用（执行顺序）

#### 第 1 步：对齐参数

用户应提供 **赛道关键词**（可为空表示全站热门）与 **起始日期**（格式与工作流一致）。若口头表达为「昨天 / 近一周」等，按 `references/core_workflow.md` 映射为具体日期。

> **用户**：看下近 7 天「职场穿搭」有什么低粉爆款可以参考。
> **助手**：确认关键词与日期区间 → 读取 `references/core_workflow.md` → 执行脚本 → 给出 TOP 摘要与规律要点，并告知 HTML 路径。

若用户只说「查查小红书爆款」：**追问**关键词（或是否全站）、日期与关注维度（例如更看重低粉还是飙升），勿擅自假定赛道。

#### 第 2 步：运行脚本

在项目根目录执行（参数占位符照抄替换即可）：

```bash
# 有赛道关键词
python scripts/fetch_xhs_trends.py --keyword <关键词> --start-date <日期>

# 无赛道关键词（全站热门）
python scripts/fetch_xhs_trends.py --keyword "" --start-date <日期>

# 多个关键词（英文逗号分隔）
python scripts/fetch_xhs_trends.py --keyword "减脂餐,职场穿搭,健身" --start-date <日期>
```

#### 第 3 步：交付与扩展

- **默认输出文件**：`{keyword}_爆款数据.html`（关键词规则以脚本与工作流为准）。
- 用户需要更深拆解（标题公式、选题簇、竞品对比）时：在已有榜单基础上继续追问，**不得脱离脚本结果编造互动数据或排名**。

### 常用口令速查

| 用户说法示例                   | 助手动作                                     |
| ------------------------------ | -------------------------------------------- |
| 查 [日期] [关键词] 爆款 / 对标 | 确认参数 → 跑脚本 → 摘要 + HTML 路径         |
| 不知道搜什么词                 | 走泛词拓展 → 列出细分方向 → 用户选定后再检索 |
| 要看全站热门                   | `--keyword ""` + 指定 `--start-date`         |
| 多个赛道一起比                 | 逗号分隔 `--keyword`，输出按工作流说明       |

### 失败或不可执行时

- **缺参数**：明确列出缺少项并请用户补齐；不猜测日期与关键词。
- **依赖或网络失败**：说明错误类型（安装、超时、代理），给出重试或配置 `XHS_API_PROXY` 的建议。
- **数据为空或接口不可用**：如实告知，禁止虚构笔记标题、链接与互动数字。

---

## 使用场景

| 场景             | 角色               | 需求描述                                     | 使用方式                                                                       |
| ---------------- | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------ |
| 新号冷启动选题   | 自媒体创作者       | 粉丝少，需要对「同级别账号」可复制的爆文样本 | 按赛道关键词 + 近 7～30 天拉榜；优先看低粉维度；提炼标题与选题簇               |
| 品牌节点种草     | 品牌小红书运营     | 活动前需要证据链充分的热点与形式参考         | 按品类关键词检索；导出 HTML 用于内部评审；对齐达人 Brief 里的内容范式          |
| 签约与孵化前筛号 | MCN 内容星探       | 要高互动潜力账号的内容轨迹而非单条偶然爆款   | 固定窗口多次抽样；关注持续增长与周期高赞；输出账号级观察（在工作流允许范围内） |
| 竞标与周报       | 内容策划 / 代理 PM | 客户需要「趋势 + 样本」一页纸结论            | 脚本结果做结构化摘要；附件 HTML；结论严格对应数据窗口                          |

---

## 注意事项与边界

- **数据真实性**：榜单与数字均来自脚本拉取结果；接口异常或无数据时如实说明，**不得编造**互动量、排名与笔记元数据。
- **合规与隐私**：遵守平台社区规范与本地法律；不引导违规导流；展示外链与正文片段时遵循工作流中的脱敏与引用边界。
- **能力边界**：推送订阅、PDF 导出等能力**仅在实际实现存在时**承诺；本仓库默认交付为脚本 + HTML / Markdown，见 `references/core_workflow.md`。
- **执行主体**：完整流程仅在主 Agent 执行，避免子 Agent 重复请求或绕过统一校验逻辑。