# Playlet Douyin Feed

> 短剧-抖音信息源 — 每日扫描抖音短剧爆款内容,按点赞量筛选热门短剧,智能聚类题材方向后生成包含封面、互动数据与创作洞察的HTML日报。支持按题材(穿越/霸总/重生等)、达人、时间范围定向查询。⚠️查询前脚本先做输入校验：关键词需命中短剧题材词库（topic_keywords 中规定的题材名+全部相关词，如「打脸」命中逆袭题材相关词），命中后直接使用该关键词查询数据；不满足时提醒'关键词不满足查询条件'并推荐相关词，且**不发起接口请求**；查询无匹配数据或全量数据不足时先询问用户是否按推荐题材重新查询，确认后才可查询（不自动扩展、不自动降级全量）。日期超出有效查询范围时提醒并自动回退最近有数据日期，无需用户确认。当用户需要短剧抖音日报、抖音短剧爆款、短剧热点、短剧创作趋势或自定义题材查询时使用。

- Skill: `redfox-data/playlet-douyin-feed` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds add redfox-data/playlet-douyin-feed`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redfox-data/playlet-douyin-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-douyin-feed

---


# 短剧-抖音信息源

## 简介

短剧-抖音信息源是一款专为短剧创作者和MCN运营人员设计的抖音爆款内容追踪工具,每日自动扫描抖音短剧创作内容,按点赞量筛选爆款作品,智能聚类题材后生成HTML可视化日报。

通过简单的自然语言指令,你可以:
- 📊 获取每日抖音短剧爆款榜单与题材分布
- 🏷️ 自动聚类穿越/霸总/重生/悬疑等题材方向
- 📈 生成创作趋势分析报告(爆款标题特征、核心达人榜、新兴起量信号)
- 🔔 开启每日订阅,日报自动产出

适用于**短剧创作者选题、MCN机构运营、题材趋势研究**等需要每日追踪抖音短剧热点的场景。

> **重要**：数据每日15:00更新前一天数据（实际可能延迟，以脚本真实探活为准）。查询前脚本先做输入校验：关键词需命中短剧题材词库（`topic_keywords` 中规定的**题材名+全部相关词**，如「打脸」命中逆袭题材相关词），**命中后直接使用该关键词查询数据**；不满足时提醒"关键词不满足查询条件"并推荐相关词，**不发起接口请求**。**无数据确认制**：查询无匹配数据或全量数据不足时，禁止自动发起任何额外查询（禁止自动降级全量、禁止自动扩展题材），先展示推荐题材关键词并询问用户，用户确认后才可发起查询；日期超出有效查询范围时提醒并自动回退最近有数据日期，无需用户确认。

## 功能特性

### 🎯 核心功能

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

### ✨ 特色亮点

- ⚡ **探活式日期预检**：调用前先用轻量请求(无keyword, pageSize=1)真实探测目标日期是否有数据，替代纯本地时钟推断，自动拦截无效查询，避免浪费API额度
- 🧭 **前置输入校验**：查询前先判断用户的分类/关键词是否符合短剧题材词库（题材名+全部相关词，命中后**直接使用该关键词查询数据**）、日期是否在有效查询范围；**不满足时提醒"关键词不满足查询条件"并推荐相关分类和关键词，不发起接口请求**
- 🔄 **自动回退**：`--latest` 自动向前回退最多7天，找到最近有数据的日期再出日报，彻底告别"查到空就报错"
- ⏸️ **无数据确认制**：查询无匹配数据或全量数据不足时，**不自动扩展题材、不自动降级全量**，提示推荐题材关键词并等待用户确认后再查询
- 🧠 **结构化空因**：空结果时明确输出原因（数据源无数据/关键词无匹配/接口异常）并给出下一步建议
- 🏷️ **智能题材聚类**：内置9大题材关键词库(穿越/霸总/重生/悬疑/甜宠/逆袭/年代/战神/古装)，自动识别归类
- 📊 **创作趋势报告**：自动分析新兴起量信号、爆款标题特征、核心达人榜
- 🎨 **HTML深色主题日报**：封面图+互动数据+作品直链，美观直观，自动浏览器打开
- 💰 **API积分优化**：批量查询+1小时缓存+探活拦截，节省接口调用额度

## 一键安装

### 前置条件

- 已安装 Python 3 运行环境
- 获取红狐Hub API Key

### API Key 获取

数据查询接口通过请求头 `X-API-KEY` 鉴权,Key 从环境变量 `REDFOX_API_KEY` 获取。

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

### 环境变量配置

| 变量名 | 必填 | 说明 |
|--------|------|------|
| `REDFOX_API_KEY` | 是 | 红狐Hub API 访问密钥,格式 `ak_xxxxxxxx` |

**配置方式**:

- **macOS/Linux**:将 `export REDFOX_API_KEY=<值>` 追加到 `~/.zshrc` 或 `~/.bashrc`,然后 `source` 使其生效
- **Windows**:`[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "<值>", "User")`(需重启终端)
- 配置后验证:`echo $REDFOX_API_KEY`(macOS/Linux)或 `echo %REDFOX_API_KEY%`(Windows)


## 使用指南

### 基础使用

#### 1. 查询每日短剧爆款日报

直接告诉助手你想查看的日报:

> 用户:查询今天的短剧抖音日报
>
> 助手:(执行 `--latest`，脚本自动回退定位最近有数据的日期，输出日报 + 题材概览 + 创作趋势分析)

> **日期预检规则**：查询前先做前置校验——分类/关键词不符合短剧题材词库时提醒"关键词不满足查询条件"并推荐相关词，**不发起接口请求**；日期超出有效查询范围或未更新时，脚本自动向前回退获取最近时间范围数据，并明确告知"当前查询时间未更新或超过查询时间范围，已为您自动获取最近时间范围数据"。

#### 2. 按题材定向查询

指定你关注的题材方向:

> 用户:查询穿越题材的短剧
>
> 助手:(生成穿越题材定向日报 + 趋势分析)

#### 3. 查询历史日期

> 用户:查询6月10日的短剧日报
>
> 助手:(历史日期已有数据,直接生成日报)

### 高级使用

#### 4. 多题材组合查询

```bash
python3 scripts/playlet_douyin_daily.py --topics "穿越,霸总,重生" --latest
```

#### 5. 按时间范围查询

```bash
python3 scripts/playlet_douyin_daily.py \
  --start-time "2026-06-01 00:00:00" \
  --end-time "2026-06-30 23:59:59"
```

#### 6. 开启每日订阅

```bash
python3 scripts/playlet_douyin_daily.py --subscribe
```

#### 7. 使用缓存数据

```bash
python3 scripts/playlet_douyin_daily.py --from-cache
```

### 常用命令速查

| 命令 | 功能 |
|------|------|
| `--latest` | 生成最新一期日报(自动向前回退最多7天定位最近有数据的日期) |
| `--date YYYY-MM-DD` | 生成指定日期日报(未更新时自动回退最近有数据的日期) |
| `--topics "关键词"` | 自定义题材查询(逗号分隔;不满足短剧题材词时提醒+推荐,不请求接口) |
| `--count N` | 扫描作品数量(默认200) |
| `--subscribe` | 开启每日订阅 |
| `--unsubscribe` | 关闭每日订阅 |
| `--from-cache` | 使用缓存数据(1小时内有效) |
| `--output-dir` | 自定义输出目录 |

### 完整参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--topics` | 自定义题材关键词,逗号分隔。查询前先校验是否命中短剧题材词库（题材名+全部相关词，命中后直接使用该关键词查询），不满足时提醒+推荐相关词并**不请求接口**。默认查询全部短剧,数据不足时提示推荐题材并等待确认(**不自动扩展**);所有题材通过批量接口查询 | `短剧` |
| `--count` | 扫描作品数量,满足即停 | `200` |
| `--date` | 指定日期 YYYY-MM-DD(未更新或超范围时自动回退最近有数据的日期) | 今天 |
| `--start-time` | 自定义开始时间 YYYY-MM-DD HH:MM:SS(覆盖 --date 推算) | — |
| `--end-time` | 自定义结束时间 YYYY-MM-DD HH:MM:SS(覆盖 --date 推算) | — |
| `--latest` | 自动向前回退最多7天，定位最近有数据的日期，跳过无数据区间，不扣积分 | — |
| `--output-dir` | 输出目录 | `~/Downloads/QoderReports` |
| `--api-key` | 指定 API Key | — |
| `--subscribe` | 开启每日订阅 | — |
| `--unsubscribe` | 关闭每日订阅 | — |

### 工作流程

> 详细执行流程(日期预检规则、脚本调用、强制输出格式模板、题材聚类规则、创作趋势分析逻辑)请参阅 [core_workflow.md](references/core_workflow.md)

工作流程分为三步:

1. **第零步 — 输入与日期预检**:前置校验关键词是否命中短剧题材词库（题材名+全部相关词，命中后直接查询；不满足时提醒+推荐，**不请求接口**）；日期按15:00规则估算起点后，用轻量请求**真实探活**目标日期是否有数据，无数据时自动向前回退最近有数据的日期。**查询无匹配数据或数据不足时，先展示推荐题材关键词并询问用户，用户确认后才可发起查询（无数据确认制）**
2. **第一步 — 生成爆款日报**:执行 `playlet_douyin_daily.py` 脚本，支持 `--latest`、`--date`、`--topics` 等参数
3. **第二步 — 执行创作趋势分析**:基于聚类结果自动分析TOP 5题材、爆款标题特征、核心达人榜，输出结构化趋势报告

### 自定义题材查询

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

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

# 查询霸总/甜宠题材
python3 scripts/playlet_douyin_daily.py --topics "霸总,甜宠,总裁,虐恋"

# 查询悬疑/反转题材
python3 scripts/playlet_douyin_daily.py --topics "悬疑,推理,反转,惊悚"
```

**自定义查询逻辑**:
- **前置校验（v2.3）**：查询前先判断关键词是否命中短剧题材词库（`topic_keywords` 中规定的**题材名+全部相关词**，如「打脸」命中逆袭题材相关词、「总裁」命中霸总题材相关词）。**命中后直接使用该关键词查询数据**；不满足时明确提醒"关键词不满足短剧查询条件"，并**推荐相关分类和关键词**（优先从无效词中提取题材词，再补热门题材），且**不发起接口请求**，引导用户改用推荐词查询
- **无效词自动忽略**：混合词场景下保留有效关键词继续查询，无效关键词自动忽略并提示；全部无效时**不请求接口**，直接停止并推荐相关词
- **无数据确认制（v2.3）**：用户指定的关键词/题材无匹配数据时，**禁止自动降级为全量查询**、禁止自动扩展题材，先提示推荐题材关键词并询问用户，用户确认后才可发起查询
- 用户提供的所有题材通过批量接口一次性查询,无需逐个调用
- 查询结果自动去重,题材聚类、趋势分析均基于查询结果生成,与用户关注方向强关联

**题材关键词速查**:

| 题材类型 | 典型关键词 |
|---------|-----------|
| 穿越 | 穿越、时空、古代、现代、回到 |
| 霸总 | 霸总、总裁、豪门、冷酷 |
| 重生 | 重生、逆袭、回到、翻盘 |
| 悬疑 | 悬疑、推理、反转、惊悚、谜案 |
| 甜宠 | 甜宠、恋爱、撒糖、甜蜜、宠溺 |
| 逆袭 | 逆袭、翻身、打脸、崛起 |

## 使用场景

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

**角色**:短剧编剧/导演

**需求**:了解当前哪些题材和标题模式最容易出爆款

**使用方式**:
1. 每日查询短剧爆款日报,查看题材概览
2. 重点关注「新兴起量信号」和「爆款标题特征」
3. 结合自身优势选择题材方向

**预期收益**:精准把握流量风口,提升作品爆款概率

---

### 场景二:MCN机构运营管理

**角色**:MCN运营总监

**需求**:追踪旗下达人和竞品在抖音短剧赛道的表现

**使用方式**:
1. 查看「核心达人榜」了解头部达人动态
2. 按题材定向查询,分析各赛道竞争格局
3. 开启每日订阅,日报自动推送

**预期收益**:提升运营决策效率,及时捕捉市场变化

---

### 场景三:题材趋势研究

**角色**:内容分析师/投研人员

**需求**:系统性分析抖音短剧题材分布和趋势变化

**使用方式**:
1. 按时间范围查询(如月度数据),观察题材占比变化
2. 对比多个题材的互动数据和增长趋势
3. 分析「跨题材对比建议」,发现融合机会

**预期收益**:形成数据驱动的趋势判断,支撑投资决策

---

### 场景四:日常内容追踪

**角色**:短剧爱好者/行业关注者

**需求**:每天快速了解抖音短剧热点,无需手动分析

**使用方式**:
1. 开启订阅 `--subscribe`
2. 每日自动生成日报,保存在 `~/Downloads/QoderReports/`

**预期收益**:零成本追踪行业动态,省时省力

## 项目架构

### 目录结构

```
短剧-抖音信息源/
├── SKILL.md                           # Skill核心说明文档
├── scripts/
│   └── playlet_douyin_daily.py       # 日报生成脚本(含题材聚类+HTML生成)
├── references/
│   ├── core_workflow.md              # 核心工作流程+输出格式+聚类规则+趋势分析
│   └── examples.md                   # 使用示例与常见用法组合
└── assets/
```

### 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 运行环境 | Python 3 | 脚本执行环境 |
| 数据接口 | 红狐Hub API | 抖音短剧创作数据,RESTful接口 |
| 鉴权方式 | X-API-KEY | 请求头鉴权,环境变量配置 |
| 输出格式 | HTML(深色主题) | 自动浏览器打开,响应式设计 |
| 缓存策略 | JSON本地缓存 | 1小时有效期,路径 `~/.workbuddy/cache/` |

### 核心模块

- **playlet_douyin_daily.py**:主执行脚本,集成API调用、题材聚类、HTML日报生成、创作趋势分析,支持日期智能判断(15:00规则)、批量查询去重、浏览器自动预览

## 常见问答

### 安装相关

**Q: 提示 "缺少 API Key" 怎么办?**

A: 请确认已正确配置环境变量 `REDFOX_API_KEY`:
1. 前往 [红狐Hub](https://redfox.hk?source=github) 注册并获取 API Key(格式 `ak_xxxxxxxx`)
2. Windows:`[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "ak_xxx", "User")`
3. 重启终端后验证:`echo %REDFOX_API_KEY%`

**Q: API Key 无效或过期?**

A: 登录红狐Hub个人中心检查Key状态,确认Key未过期且账户积分充足。

### 使用相关

**Q: 数据什么时候更新?**

A: 每日15:00更新前一天的数据（实际可能延迟，以脚本真实探活为准）。15:00前最新可查为前天,15:00后为昨天。

**Q: 查询时提示"数据尚未更新"?**

A: 脚本会自动向前回退获取最近时间范围数据，并明确告知"当前查询时间未更新或超过查询时间范围，已为您自动获取最近时间范围数据"，无需手动处理。

**Q: 支持哪些题材查询?**

A: 内置9大题材(穿越/霸总/重生/悬疑/甜宠/逆袭/年代/战神/古装),同时支持任意自定义关键词查询。但查询前会先校验关键词是否符合短剧题材词库，不满足时提醒+推荐相关词，**不请求接口**，避免浪费API额度。

**Q: 如何节省API积分?**

A: 使用 `--from-cache` 复用1小时内缓存;使用 `--latest` 自动回退到有数据的日期;探活式预检拦截无数据日期;关键词不满足题材词库时不发起接口请求。

### 故障排除

**Q: 脚本报错 "UnicodeEncodeError: 'gbk' codec"?**

A: Windows终端编码问题,执行前设置环境变量:`$env:PYTHONIOENCODING="utf-8"`

**Q: HTML日报没有自动打开?**

A: 确认系统默认浏览器已正确设置,日报文件始终保存在 `~/Downloads/QoderReports/` 目录下,可手动打开。

**Q: API常见错误码?**

| 错误码 | 说明 | 解决方式 |
|--------|------|---------|
| 1002 | 每页条数超过200 | 脚本已自动限制,无需处理 |
| 3106 | 缺少API Key | 配置环境变量 `REDFOX_API_KEY` |
| 3107 | API Key无效 | 检查Key格式和有效性 |
| 3108 | 请求过于频繁 | 等待后重试 |
| 3109 | 今日调用达上限 | 次日再试 |
| 3201 | 积分不足 | 前往红狐Hub充值 |

## 参考文档

- [core_workflow.md](references/core_workflow.md) — 核心执行流程、输出格式模板、日期判断逻辑、题材聚类规则、创作趋势分析逻辑
- [examples.md](references/examples.md) — 使用示例与常见用法组合