# Playlet Xhs Feed

> 短剧-小红书信息源 — 每日扫描小红书短剧爆款内容,按互动量筛选热门笔记,智能聚类题材方向后生成包含封面、互动数据与创作洞察的HTML日报。支持按题材(穿越/霸总/重生等)、达人、时间范围定向查询。⚠️数据每日15:00更新前一天数据,目标日期无数据时必须先告知用户并等待确认后才能调用接口,禁止自动获取。⚠️查询前先校验分类/关键词是否符合短剧题材词库,不满足时不请求接口直接提示并推荐相关词。当用户需要短剧小红书日报、小红书短剧爆款、短剧热点、短剧创作趋势或自定义题材查询时使用。

- Skill: `redfox-data/playlet-xhs-feed` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds add redfox-data/playlet-xhs-feed`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redfox-data/playlet-xhs-feed/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: redfox-data (https://skillmd.com/u/redfox-data)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/redfox-data/playlet-xhs-feed

---


# 短剧-小红书信息源

## 简介

**短剧-小红书信息源**是一款专为短剧创作者设计的小红书爆款内容追踪工具,参考AI-B站信息源的功能和样式设计。

通过红狐Hub API,你可以:
- 📊 每日自动扫描小红书短剧内容,按互动量筛选爆款作品
- 🏷️ 智能聚类题材方向(穿越/霸总/重生/悬疑等)
- 📈 生成包含封面图、互动数据与创作洞察的可视化HTML日报
- 🔍 支持按题材、达人、时间范围定向查询

适用于短剧编剧、制作人、运营人员等需要把握小红书短剧流量风口的场景。

> ⚠️ **重要-确认逻辑**:数据每日15:00更新前一天数据,目标日期无数据时**禁止自动调用接口/禁止自动回退**,必须先告知用户并等待确认后才能执行。
>
> 🧭 **重要-前置校验**:查询前先校验分类/关键词是否符合短剧题材词库(穿越/霸总/重生/甜宠/悬疑/逆袭等)、日期是否在有效查询范围;关键词/分类全部不满足时**不请求任何接口**,直接提示"关键词不满足查询条件"并推荐相关分类和关键词。
>
> ⛔ **输出规范**:日报生成后,对话回复**必须严格按照输出模板输出 md 内容**,禁止任何自由发挥、省略或口语化文字。详见下方「📊 输出格式」。

## 功能特性

### 🎯 核心功能

| 功能模块 | 能力描述 | 核心价值 |
|---------|---------|----------|
| 📊 爆款发现 | 从小红书短剧中按互动量筛选热门内容 | 精准定位高热度短剧笔记 |
| 🏷️ 题材聚类 | 自动识别题材方向(穿越/霸总/重生/悬疑等) | 每天题材分类由内容动态决定 |
| 🔍 智能查询 | 默认查询全部短剧,数据不足时自动扩展题材批量查询 | 节省接口额度,高效获取数据 |
| 🎯 自定义查询 | 用户可指定任意题材/达人/关键词定向查询 | 灵活覆盖任意短剧细分方向 |
| 📈 创作洞察 | 分析爆款标题特征、题材趋势、达人表现 | 深度挖掘创作规律 |
| 🎨 可视化日报 | 深色主题HTML,封面图+互动数据+笔记直链 | 直观展示每日短剧热点 |
| 🔔 一键订阅 | `--subscribe` 开启每日自动产出 | 日报自动攒在本地文件夹 |

### ✨ 特色亮点

- **🧭 前置输入校验(v2.3)**:查询前先判断分类/关键词是否符合短剧题材词库、日期是否在有效查询范围;全部不满足时**不请求任何接口**,直接提醒"关键词不满足查询条件"并推荐相关分类和关键词;混合词保留有效关键词查询
- **⚡ 智能日期判断**:脚本内置 `DATA_UPDATE_HOUR = 15` 常量,调用接口前自动检测目标日期是否在无数据区间,无数据时提示用户等待确认
- **🧠 结构化空因**:空结果时明确输出原因分类(数据源无数据/关键词无匹配/接口异常)并给出下一步建议
- **🔄 自动扩展题材**:全量查询数据不足(<100条)时,自动追加穿越→霸总→重生→悬疑→甜宠→逆袭定向查询补充
- **🔁 空结果重试**:单题材查询为空/异常时,间隔4秒自动重试1次
- **📱 小红书适配**:作品链接自动拼接 `xiaohongshu.com/explore/{photoId}`,互动数据为0的字段自动隐藏,HEIF封面自动转JPG,加载失败自动fallback默认封面
- **🔒 安全可靠**:API Key通过环境变量 `REDFOX_API_KEY` 获取,禁止硬编码

## 一键安装

### 前置条件

- Python 3 运行环境
- 已注册红狐Hub账号并获取 API Key

### 安装步骤

#### 1. 获取 API Key

前往 [红狐Hub 官网](https://redfox.hk?source=github) 注册,登录后在个人中心获取,格式为 `ak_xxxxxxxx`。新注册用户获赠免费积分。

#### 2. 配置环境变量

**macOS/Linux**:
```bash
echo 'export REDFOX_API_KEY=ak_xxxxxxxx' >> ~/.zshrc
source ~/.zshrc
```

**Windows**(PowerShell):
```powershell
[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "ak_xxxxxxxx", "User")
```
配置后需**重启终端**使环境变量生效。

#### 3. 验证配置

```bash
# macOS/Linux
echo $REDFOX_API_KEY

# Windows
echo %REDFOX_API_KEY%
```

### 环境变量配置

| 变量名 | 必填 | 说明 |
|--------|------|------|
| `REDFOX_API_KEY` | 是 | 红狐Hub API访问密钥,通过 `X-API-KEY` 请求头鉴权 |

## 工作流程

### 第零步:日期有效性预检(必须执行,先于任何接口调用)

> ⛔ **核心规则:未经用户确认,禁止调用任何数据接口,禁止自动执行 `--latest`**
>
> **绝对不能**在用户未确认的情况下自动执行脚本获取数据(与B站版本不同,B站为自动兜底,本技能保留确认逻辑)。

**数据更新规则**:每日15:00更新前一天的数据
- 15:00前:最新可用日期 = T-2(前天)
- 15:00后:最新可用日期 = T-1(昨天)

**执行流程(每次查询前强制执行)**:

1. **前置校验-日期(v2.3)**:检查日期格式(YYYY-MM-DD)且不晚于今天;超出有效查询范围时提醒并推荐最近可用日期
2. 获取当前系统日期 T 和当前时间,按15:00规则计算最新可用日期
3. 判断用户请求的目标日期是否在无数据区间(即 > 最新可用日期)
4. **若目标日期有数据**(≤ 最新可用日期):直接执行查询,无需额外确认
5. **若目标日期无数据**(> 最新可用日期),向用户输出以下提示,并**等待用户明确确认**后才能执行(带 `--latest` 参数);若用户拒绝,则不执行任何接口调用:

```
**⚠️{查询日期}数据尚未更新**
数据更新规则:每日15:00更新前一天的数据
当前可查询的最新日期:{最新可查询到数据的日期}

是否需要查询{最新可查询到数据的日期}的数据?
```

**示例对话**:

```
用户:查询今天的短剧小红书日报
Agent:⚠️2026-06-16数据尚未更新
      数据更新规则:每日15:00更新前一天的数据
      当前可查询的最新日期:2026-06-14

      是否需要查询2026-06-14的数据?
用户:好的
Agent:(执行 python3 daily_report.py --latest)
```

### 前置校验:分类/关键词(v2.3,先于日期处理)

> 查询前先判断用户输入的关键词/分类是否符合**短剧题材词库**(穿越/霸总/重生/甜宠/悬疑/逆袭/年代/战神/古装/都市/科幻等)。

- **全部不符合**:不请求任何接口(含日期探活),直接提示"关键词不满足短剧查询条件"并**推荐相关分类和关键词**后停止
- **部分不符合(混合词)**:保留有效关键词继续查询,无效关键词自动忽略并提示
- **全部符合**:正常查询

推荐逻辑:优先从无效词中提取包含的题材词(如"穿越重生"→推荐穿越、重生),再补热门题材词。

### 第一步:生成爆款日报

```bash
# 生成最新一期日报(用户确认后执行)
python3 "$SKILL_PATH/assets/daily_report.py" --latest

# 生成指定日期日报(历史日期已有数据,无需确认)
python3 "$SKILL_PATH/assets/daily_report.py" --date 2026-06-10

# 自定义题材查询(用户指定方向,自动校验关键词)
python3 "$SKILL_PATH/assets/daily_report.py" --topics "穿越,霸总,重生,悬疑" --latest

# 订阅 / 取消订阅
python3 "$SKILL_PATH/assets/daily_report.py" --subscribe
python3 "$SKILL_PATH/assets/daily_report.py" --unsubscribe
```

> **查询策略**:默认查询全部短剧内容(pageSize=200),数据不足(<100条)时自动追加热门题材(穿越→霸总→重生→悬疑→甜宠→逆袭),所有题材通过批量接口一次性查询。用户自定义题材时仅使用用户提供的有效题材词,同样批量查询。

> **日期智能判断**:脚本内置 `DATA_UPDATE_HOUR = 15` 常量(每日15:00更新前一天数据),调用接口前自动检测目标日期是否在无数据区间。作为双保险,Agent 在第零步已提前拦截,避免脚本层的交互提示被忽略。

### 第二步:执行创作趋势分析

日报生成后,**必须**基于聚类结果自动执行创作趋势分析:

1. 读取题材聚类结果,选取TOP 5热门题材
2. 分析每个题材的爆款数量、平均互动数据、头部作品特征
3. 识别新兴起量题材(数量少但互动高)
4. 输出结构化创作趋势报告

生成的HTML日报保存在 `~/Downloads/QoderReports/`,自动浏览器打开。终端同步输出题材分类表格 + 创作趋势分析报告。

## 📊 输出格式(强制执行)

> ⛔ **严格执行规则**:
> - 以下模板是**唯一合法输出格式**,禁止任何自由发挥、省略、简化或重新组织
> - 禁止输出模板中未定义的额外内容(如"我来帮你…""以下是…"等口语化文字)
> - 禁止合并、跳过任何板块,即使某板块数据为"暂无"也必须保留该板块标题
> - **每次获取日报后,对话回复必须严格按此模板输出 md 内容,不得包含模板以外的任何文字**

每次运行日报后,对话输出**必须严格**按以下模板原样输出(仅替换 `{...}` 占位符):

```
## 短剧-小红书信息源 · {日期} 日报

**扫描 {N} 部热门短剧,聚类 {M} 个题材方向**

---

### 题材概览

| 题材 | 数量 | 占比 | 爆款亮点 |
|------|------|------|---------|
| #{题材名} | {N}部 | {X}% | 头部作品亮点描述 |
| ... | ... | ... | ... |

---

### 创作趋势分析

**一、新兴起量信号**

- 🔥 **#{题材}** — 仅{N}部但均互动{X}+,描述
(若无新兴题材,输出:暂无新兴起量信号)

**二、爆款标题特征**

| 特征模式 | 出现次数 | 典型案例 | 平均互动 |
|---------|---------|---------|---------|
| {特征1} | {N}次 | 《{标题}》 | {X}w |
| ... | ... | ... | ... |
(若无标题数据,输出:暂无爆款标题数据)

**三、核心达人榜**

| 达人 | 作品数 | 总互动 | 代表作 |
|------|--------|--------|--------|
| @{达人} | {N}部 | {X}w | 《{作品}》 |
| ... | ... | ... | ... |
(若无达人数据,输出:暂无核心达人数据)

**四、题材趋势报告**

**题材**:#{题材1}
**作品数**:{N}部
**平均互动**:{X}w
**头部作品**:《{标题}》-{互动}w

**题材特征**:{描述该题材的共性特征}
**创作建议**:{针对该题材的创作建议}

**五、#{题材2}**

(同上格式)

**六、#{题材3}**

(同上格式)

**七、跨题材对比建议**

- **{题材}** — 建议同步关注{相关题材}的联动创作,观察题材融合趋势
(若无建议,输出:暂无跨题材对比建议)

---

**日报地址**:{HTML文件绝对路径}

> 数据说明:每日15:00更新昨天的数据
```

> 以上格式为**强制规范**,所有字段不可省略,板块标题(一、二、三、四、五、六、七)必须保留。若某模块无数据则在该板块内标注"暂无",不得删除板块本身。

## 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--topics "关键词,..."` | 自定义题材查询,逗号分隔;全部不符合短剧题材词库时不请求接口直接提示+推荐;混合词保留有效词 | 全量查询 |
| `--count N` | 扫描作品数量,满足即停 | `200` |
| `--date YYYY-MM-DD` | 指定日期(超出有效范围/未更新时提示并询问,等待确认;历史日期已有数据无需确认) | 今天 |
| `--start-time` | 自定义开始时间 YYYY-MM-DD HH:MM:SS(覆盖 --date 推算) | — |
| `--end-time` | 自定义结束时间 YYYY-MM-DD HH:MM:SS(覆盖 --date 推算) | — |
| `--latest` | 自动使用最新有数据的日期(用户确认后执行,不扣积分) | — |
| `--output-dir` | 输出目录 | `~/Downloads/QoderReports` |
| `--api-key` | 指定 API Key | — |
| `--subscribe` | 开启每日订阅 | — |
| `--unsubscribe` | 关闭每日订阅 | — |
| `--from-cache` | 使用缓存数据,不扣积分 | — |

## 💬 自定义题材查询场景

除默认短剧日报外,用户可指定任意题材组合进行定向查询与分析:

```bash
# 查询穿越题材热门短剧
python3 "$SKILL_PATH/assets/daily_report.py" --topics "穿越,时空,重生"

# 查询霸总/甜宠题材
python3 "$SKILL_PATH/assets/daily_report.py" --topics "霸总,甜宠,总裁,虐恋"

# 查询悬疑/反转题材
python3 "$SKILL_PATH/assets/daily_report.py" --topics "悬疑,推理,反转,惊悚"
```

**自定义查询逻辑**:
- 查询前先校验关键词/分类是否符合短剧题材词库(穿越/霸总/重生/甜宠/悬疑/逆袭/年代/战神/古装等)
- 全部不满足时**不请求任何接口**,提醒"关键词不满足短剧查询条件"并**推荐相关分类和关键词**,停止
- 混合词场景保留有效关键词继续查询,无效关键词自动忽略并提示
- 查询结果自动去重,题材聚类、趋势分析均基于查询结果生成,与用户关注方向强关联

## 使用场景

### 场景一:短剧创作者选题参考

**角色**:短剧编剧/制作人

**需求**:了解小红书短剧市场的热门题材和爆款趋势,指导选题决策

**使用方式**:
1. 每日确认后执行 `--latest` 获取最新日报
2. 分析题材聚类结果,关注新兴起量信号
3. 参考爆款标题特征和题材趋势报告

**预期收益**:精准把握流量风口,提升选题命中率

---

### 场景二:运营团队竞品监控

**角色**:短剧运营/MCN机构

**需求**:追踪竞品账号在小红书的表现,分析爆款内容特征

**使用方式**:
1. 使用 `--topics` 定向查询竞品所在题材
2. 关注核心达人榜,识别头部竞品账号
3. 开启 `--subscribe` 每日自动攒日报

**预期收益**:及时掌握竞品动态,优化自身运营策略

---

### 场景三:内容趋势分析

**角色**:内容策划/数据分析师

**需求**:分析小红书短剧的内容趋势,为内容规划提供数据支撑

**使用方式**:
1. 结合 `--start-time` 和 `--end-time` 批量分析时间范围数据
2. 利用创作趋势分析的5个维度深度挖掘规律
3. 关注跨题材对比建议,发现题材融合机会

**预期收益**:产出结构化趋势报告,支撑内容战略决策

## 项目架构

### 目录结构

```
短剧-小红书信息源/
├── SKILL.md                      # Skill主文档(本文件)
├── README.md                     # 项目说明文档
├── scripts/                      # 脚本源码
│   └── playlet_xhs_daily.py      # 日报生成脚本(开发版,与assets同步)
├── assets/                       # Skill运行时资源
│   ├── daily_report.py           # 日报生成脚本(运行时使用,v2.3增强版)
│   └── default_cover.png         # 默认封面图(加载失败时的fallback)
└── references/                   # 参考文档
    ├── core_workflow.md          # 核心执行流程、格式模板、日期判断逻辑
    └── examples.md               # 使用示例与常见用法组合
```

### 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 运行环境 | Python 3 | 脚本语言 |
| 数据源 | 红狐Hub API | `X-API-KEY` 请求头鉴权,`source` 字段追踪来源 |
| API端点 | `https://redfox.hk/story/api/parseWork/queryPlayletMsgs` | POST请求 |
| 平台标识 | `platform=3` | 小红书(1=抖音,2=视频号,6=B站) |
| 来源标识 | `source` | `"短剧小红书信息源-GitHub"` |
| 数据存储 | JSON缓存 | `~/.workbuddy/cache/playlet_xhs_data.json` |
| 输出格式 | HTML + 终端Markdown | 深色主题,小红书红(#FF2442) |
| 输出目录 | `~/Downloads/QoderReports` | 可自定义 |

### 数据流转

```
用户请求 → 前置输入校验(分类/关键词/日期) → 日期预检(15:00规则)
  ↓(关键词/分类全部不满足)        ↓(日期未更新/超范围)
不请求接口,直接提示+推荐停止   提示用户并等待确认(禁止自动回退)
  ↓(用户确认后)
API调用(批量查询+重试+去重+排序,数据不足自动扩展题材)
  ↓
题材聚类(关键词匹配)
  ↓
HTML日报生成 + 终端摘要输出
  ↓
创作趋势分析(5个维度)
```

## 常见问答

### 安装相关问题

**Q1: 安装时提示 "未找到 REDFOX_API_KEY 环境变量" 怎么办?**

A: 请按以下步骤检查:
1. 确认 API Key 已正确配置(Windows: `[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "ak_xxx", "User")`)
2. 配置后需**重启终端**使环境变量生效
3. 验证: `echo %REDFOX_API_KEY%` 应输出你的Key值

**Q2: API Key 如何获取?**

A: 前往 [红狐Hub 官网](https://redfox.hk?source=github) 注册账号,登录后在个人中心获取,格式为 `ak_xxxxxxxx`。新注册用户获赠免费积分。

---

### 使用相关问题

**Q3: 数据多久更新一次?**

A: 每日15:00更新前一天的数据。
- 15:00前:最新可用日期 = 前天(T-2)
- 15:00后:最新可用日期 = 昨天(T-1)

**Q4: 查询指定日期提示"数据尚未更新"怎么办?**

A: 目标日期尚未更新时,脚本**不会自动回退**,而是提示当前可查询的最新日期并询问"是否需要查询最新日期的数据?",**等待用户确认后**才执行。这是本技能保留的确认逻辑(与B站版本的自动兜底不同)。

**Q5: 关键词/分类不满足短剧题材词库时怎么办?**

A: 查询前脚本会**先校验关键词/分类**:全部不符合短剧题材词库(如"智能辅助驾驶""火星人"等非题材词)时,**不请求任何接口**,直接提示"关键词不满足短剧查询条件"并**推荐相关分类和关键词**(穿越/霸总/重生/甜宠/悬疑/逆袭等);混合词场景保留有效关键词继续查询。

**Q6: 查询不到数据怎么办?**

A: 可能原因:
1. 目标日期尚无数据(未到15:00更新时间)
2. 关键词在该日期无匹配作品(建议改用题材词或去掉 --topics 查询全部,需确认后执行)
3. API Key权限不足或积分耗尽
4. 网络连接问题

建议先使用 `--from-cache` 检查缓存,或换一个日期尝试。

---

### 故障排除

**Q7: Windows PowerShell 执行报 UnicodeEncodeError?**

A: 脚本输出包含emoji,需设置UTF-8编码:
```powershell
$env:PYTHONIOENCODING='utf-8'
python assets/daily_report.py --latest
```

**Q8: HTML日报中图片加载失败?**

A: 脚本已内置fallback机制,加载失败时自动显示默认封面图(`assets/default_cover.png`)。部分封面图URL使用HEIF格式,脚本会自动转换为JPG格式提高兼容性。

---

### 安全与许可

**Q9: 数据安全如何保障?**

A:
- API Key仅通过环境变量获取,禁止硬编码
- 数据来源唯一:仅使用红狐Hub API,禁止自主采集
- 缓存文件存储在本地 `~/.workbuddy/cache/`

## 📚 参考文档

- [references/core_workflow.md](references/core_workflow.md) — 核心执行流程、输出格式模板、日期判断逻辑、字段映射、平台适配说明、字段映射修正记录、改造验证清单
- [references/examples.md](references/examples.md) — 使用示例与常见用法组合