小红书爆款雷达
需要执行完整判定规则、对话分支与脚本细节时，必须先读取同目录 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；配置依赖与可选代理即可运行（合规使用自有责任）
使用指南
环境与依赖（安装前）
- 安装 Python 3.8+，保证终端可执行
python。 - 进入项目根目录，安装依赖：
pip install requests>=2.28.0
- （可选）配置环境变量：
| 变量名 | 必填 | 说明 |
|---|---|---|
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 步：运行脚本
在项目根目录执行（参数占位符照抄替换即可）：
# 有赛道关键词
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 重复请求或绕过统一校验逻辑。