# Playlet Bili Feed

> B站短剧爆款内容追踪工具，每日自动扫描B站短剧创作内容，按点赞量筛选爆款作品，智能聚类题材后生成可视化HTML日报与创作趋势分析。⚠️查询前脚本先做输入校验：关键词需命中短剧题材词库（topic_keywords 中规定的题材名+全部相关词，如「打脸」命中逆袭题材相关词），命中后直接使用该关键词查询数据；不满足时提醒'关键词不满足查询条件'并推荐相关词，且不发起接口请求。数据每日15:00更新前一天数据，目标日期无数据时必须先告知用户并等待确认后才能调用接口，禁止自动获取。当用户需要查询B站短剧爆款日报、分析短剧题材趋势、查看热门达人表现或生成短剧创作趋势报告时使用。

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

---


# 短剧-B站信息源

## 简介

B站短剧爆款内容追踪工具，每日自动扫描B站短剧创作内容，按点赞量筛选爆款作品，智能聚类题材后生成可视化HTML日报与创作趋势分析。

通过数据驱动的方式，帮助短剧创作者、MCN机构和内容运营人员精准把握B站短剧流量风口。

你可以：
- 📊 每日获取B站短剧爆款榜单
- 🏷️ 自动识别热门题材方向（穿越/霸总/重生/悬疑等）
- 📈 深度分析爆款标题特征与达人表现
- 📄 一键生成深色主题HTML可视化日报

适用于短剧创作者、MCN机构、内容运营人员等需要追踪B站短剧趋势的场景。

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

## 功能特性

### 🎯 核心功能

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

### ✨ 特色亮点

- **⚡ 探活式日期预检**：调用前先用轻量请求(无keyword, pageSize=1)真实探测目标日期是否有数据，替代纯本地时钟推断，自动拦截无效查询，避免浪费API额度
- **🧭 前置输入校验**：查询前先判断用户的分类/关键词是否符合短剧题材词库（题材名+全部相关词，命中后**直接使用该关键词查询数据**）、日期是否在有效查询范围；全部不满足时**不请求任何接口**，直接提醒"关键词不满足查询条件"并推荐相关分类和关键词；混合词保留有效关键词查询
- **🔄 自动回退**：`--latest` 自动向前回退最多7天，找到最近有数据的日期再出日报，彻底告别"查到空就报错"
- **⏸️ 无数据确认制**：查询无匹配数据或全量数据不足时，**不自动扩展题材、不自动降级全量**，提示推荐题材关键词并等待用户确认后再查询
- **🧠 结构化空因**：空结果时明确输出原因（数据源无数据/关键词无匹配/接口异常）并给出下一步建议
- **🎨 B站风格日报**：深色主题 + B站蓝（#00A1D6），封面图懒加载，BV号直链跳转
- **📊 零值隐藏**：互动指标为0时自动隐藏，日报信息更清爽

## 一键安装

### 前置条件

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

### API Key 获取

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

### 环境变量配置

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

| 变量名 | 必填 | 说明 |
|--------|------|------|
| `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）

> 接口调用时通过 `source` 字段（值为 `短剧B站信息源-GitHub`）同步记录来源，无需额外请求保存接口。

## 使用指南

> **详细执行流程、字段映射、HTML规则、指标展示规则**见 [core_workflow.md](references/core_workflow.md)

### 基础使用

#### 1. 日期预检（每次查询前自动执行）

- **前置校验（v2.2）**：先判断日期是否在有效查询范围——格式必须为 YYYY-MM-DD、不能晚于今天；超出范围时提醒"日期超出有效查询范围"并推荐最近可用日期
- **估算起点**：15:00前最新可用日期 = T-2（前天），15:00后 = T-1（昨天）——仅作初始起点
- **真实探活**：脚本会用 `pageSize=1` 不带 keyword 的轻量请求**实际探测**目标日期是否有数据，以接口返回为准（数据源实际更新时间可能晚于15:00）
- **自动兜底（v2.1）**：用户查询的日期未更新或超过查询时间范围时，脚本自动向前回退获取最近时间范围数据，并明确告知用户"当前查询时间未更新或超过查询时间范围，已为您自动获取最近时间范围数据"，无需人工确认
- `--latest` 模式同样自动向前回退（最多7天）定位最近有数据的日期
- 若回退 7 天内均无数据，提示用户稍后再试或联系数据源确认更新状态

#### 2. 生成爆款日报

> 用户：查一下最新的B站短剧日报
>
> 助手：检查日期可用性 → 执行脚本生成日报 → 输出趋势分析

```bash
# 生成最新一期日报（用户确认后，自动跳过无数据日期，不扣积分）
python3 "$SKILL_PATH/scripts/playlet_bili_daily.py" --latest

# 生成指定日期日报（历史日期已有数据，无需确认）
python3 "$SKILL_PATH/scripts/playlet_bili_daily.py" --date 2026-06-10
```

> **查询策略**：默认查询全部短剧（pageSize=200），数据不足（<100条）时自动追加热门题材（穿越→霸总→重生→悬疑→甜宠→逆袭），所有题材通过批量接口一次性查询。查询前自动探活目标日期，空结果自动重试1次。

#### 3. 创作趋势分析

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

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

### 高级使用

#### 自定义题材查询

用户可指定任意题材组合进行定向查询与分析：

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

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

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

**自定义查询逻辑**：
- 用户提供的所有题材通过批量接口一次性查询，无需逐个调用
- 查询结果自动去重，题材聚类、趋势分析均基于查询结果生成
- **前置校验（v2.2）**：查询前先判断关键词/分类是否符合短剧题材词库（穿越/霸总/重生/甜宠/悬疑/逆袭/年代/战神/古装等）。不满足时明确提醒"关键词不满足短剧查询条件"，并**推荐相关分类和关键词**（优先从无效词中提取题材词，再补热门题材）
- **无效条件零请求（v2.3）**：关键词/分类全部不符合短剧题材词库时，**不请求任何接口**（含探活），直接提示并推荐后停止；混合词场景保留有效关键词继续查询，无效词自动忽略
- **关键词兜底（v2.1）**：符合题材词但查询后无匹配数据时，脚本自动降级为全量查询获取数据，并明确告知用户"关键词未匹配，已为您自动获取全量数据"，无需人工确认

### 输出格式（强制执行）

> ⛔ **严格执行规则**：
> - 以下模板是**唯一合法输出格式**，禁止任何自由发挥、省略、简化或重新组织
> - 禁止输出模板中未定义的额外内容（如"我来帮你…""以下是…"等口语化文字）
> - 禁止合并、跳过任何板块，即使某板块数据为"暂无"也必须保留该板块标题
> - 日报生成后，对话回复**只能**包含以下内容，不得包含其他任何文字
> - **禁止**在日报末尾追加"📝 写一篇完整执行计划？"等任何执行计划类引导提醒（2026-08-18 用户明确要求移除）

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

```
## 短剧-B站信息源 · {日期} 日报

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

---

### 题材概览

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

---

### 创作趋势分析

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

- 🔥 **#{题材}** — 仅{N}部但均互动{X}+，描述
（若无新兴题材，输出：暂无新兴起量信号）

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

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

**三、核心达人榜**

| 达人 | 作品数 | 总赞 | 代表作 |
|------|--------|------|--------|
| @{达人} | {N}部 | {X}w | 《{作品}》 |
| ... | ... | ... | ... |
（若无达人数据，输出：暂无核心达人数据）

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

**题材**：#{题材1}
**作品数**：{N}部
**平均点赞**：{X}w
**头部作品**：《{标题}》-{点赞}w

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

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

（同上格式）

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

（同上格式）

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

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

---

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

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

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

### 命令速查

| 命令/参数 | 功能 | 默认值 |
|----------|------|--------|
| `--latest` | 自动使用最新有数据的日期（向前回退最多7天，跳过无数据区间） | — |
| `--date YYYY-MM-DD` | 指定日期查询（超出有效范围时提醒+推荐最近日期，未更新时自动回退） | 今天 |
| `--topics "关键词,..."` | 自定义题材查询，逗号分隔（全部不符合题材词时不请求接口直接提示+推荐；混合词保留有效词） | 全量查询 |
| `--count N` | 扫描作品数量，满足即停 | `200` |
| `--start-time` | 自定义开始时间 YYYY-MM-DD HH:MM:SS | — |
| `--end-time` | 自定义结束时间 YYYY-MM-DD HH:MM:SS | — |
| `--output-dir` | 输出目录 | `~/Downloads/QoderReports` |
| `--api-key` | 指定 API Key（覆盖环境变量） | — |
| `--subscribe` | 开启每日订阅 | — |
| `--unsubscribe` | 关闭每日订阅 | — |
| `--from-cache` | 使用缓存数据 | — |

## 使用场景

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

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

**需求**：了解当前B站短剧热门题材和爆款趋势，指导创作方向

**使用方式**：
1. 每日查看短剧日报，关注题材聚类分布
2. 分析爆款标题特征和互动数据
3. 针对新兴起量题材提前布局内容

**预期收益**：精准把握流量风口，提升作品曝光概率

---

### 场景二：MCN 机构内容运营

**角色**：MCN 运营人员

**需求**：追踪旗下达人的短剧内容表现，优化运营策略

**使用方式**：
1. 订阅每日日报，持续追踪B站短剧赛道
2. 通过核心达人榜了解竞品表现
3. 使用自定义题材查询定向分析关注领域

**预期收益**：提升内容运营效率，及时发现潜力达人

---

### 场景三：品牌方/制作方竞品监测

**角色**：短剧制作公司

**需求**：监测竞品短剧在B站的表现数据

**使用方式**：
1. 定期查询目标题材日报
2. 分析竞品爆款作品的标题特征和互动规律
3. 结合跨题材对比建议探索融合创作

**预期收益**：数据驱动内容投资决策，降低试错成本

## 项目架构

### 目录结构

```
短剧-B站信息源/
├── SKILL.md                          # Skill主文档（本文件）
├── scripts/
│   └── playlet_bili_daily.py        # 核心脚本（v2.3.1：前置校验零请求/相关词命中直查/推荐/探活/自动回退/无数据确认制）
└── references/
    ├── core_workflow.md              # 核心执行流程、字段映射、HTML规则
    └── examples.md                   # 使用示例与常见用法组合
```

### 技术栈

| 项目 | 说明 |
|------|------|
| 运行环境 | Python 3 |
| 开发语言 | Python（脚本 `playlet_bili_daily.py`） |
| 数据接口 | HTTP 调用红狐Hub B站短剧API（`queryPlayletMsgs`，`platform=6`） |
| 前端渲染 | HTML 生成日报（B站蓝 `#00A1D6` 主题色，`<img>` 懒加载，BV号直链） |
| 来源标识 | `source: "短剧B站信息源-GitHub"` |

### 数据流转

```
用户查询 → 前置输入校验(关键词命中题材词库-题材名+相关词) → 日期预检(真实探活) → API调用(queryPlayletMsgs) → 数据去重 → 题材聚类 → HTML日报生成 → 浏览器打开
              ↓(关键词/分类全部不满足)            ↓(日期未更新/超范围)       ↓(数据不足)           ↓(关键词无匹配)
       不请求接口,直接提示+推荐停止        自动回退最近有数据日期并告知  提示推荐题材等待确认(不自动扩展)  提示推荐题材等待确认(不自动降级全量)
                                              ↓
                                    终端输出趋势分析报告
```

## 常见问答

### 使用相关

**Q1: 为什么查询"今天"的数据却提示未更新？**

A: 数据每日15:00更新前一天的数据（实际更新时间可能延迟）。15:00前最新可用日期为前天，15:00后为昨天。**无需手动处理**——查询日期未更新或超过查询时间范围时，脚本会自动向前回退获取最近时间范围数据，并明确告知"当前查询时间未更新或超过查询时间范围，已为您自动获取最近时间范围数据"；也可使用 `--latest` 直接定位最近有数据的日期。

**Q2: 如何查询特定题材的短剧？**

A: 使用 `--topics` 参数，多个题材用逗号分隔，如 `--topics "穿越,霸总,重生"`。所有题材批量一次性查询，无需逐个调用。查询前脚本会**先校验关键词/分类**：符合短剧题材词库（穿越/霸总/重生/悬疑/甜宠/逆袭等）才参与查询；全部不符合时**不请求任何接口**，直接提醒"关键词不满足短剧查询条件"并**推荐相关分类和关键词**，混合词场景保留有效关键词查询。

**Q3: 日报生成在哪里？**

A: 默认保存在 `~/Downloads/QoderReports/` 目录，文件名格式为 `短剧B站日报_YYYY-MM-DD.html`，生成后自动在浏览器打开。

**Q4: 如何开启/关闭每日订阅？**

A: 使用 `--subscribe` 开启每日自动产出，`--unsubscribe` 关闭。

### 故障排除

**Q5: 脚本运行报 UnicodeEncodeError 怎么办？**

A: Windows PowerShell 的 GBK 编码问题。执行前设置环境变量：`$env:PYTHONIOENCODING='utf-8'`，然后重新运行脚本。

**Q6: 提示"未找到 REDFOX_API_KEY 环境变量"？**

A: 请按"一键安装"章节配置环境变量。Windows 用户配置后需**重启终端**才能生效。

**Q7: HTML日报中图片加载不出来？**

A: B站CDN（hdslb.com）无防盗链限制，通常不会出现此问题。若遇到请检查网络连接或图片URL是否过期。

### B站短剧改造说明（从抖音版迁移）

**Q8: B站版本与抖音版本有哪些差异？**

A: 主要改造点如下：

| 改造项 | 抖音版本 | B站版本 |
|-------|---------|--------|
| platform参数 | 1 | 6 |
| 主题色 | #FB7299（粉） | #00A1D6（蓝） |
| 链接格式 | douyin.com/video/{id} | bilibili.com/video/{BV号} |
| 文件名 | 短剧抖音日报 | 短剧B站日报 |
| 图片防盗链 | 需referrerpolicy | 无需（B站CDN无限制） |
| 展示指标 | 播放/点赞/评论 | 分享/点赞/评论（零值隐藏） |
| url字段 | 有效 | None（用BV号拼接） |

**字段映射详情**见 [core_workflow.md](references/core_workflow.md)

### 验证清单

- [x] 脚本语法正确（py_compile通过）
- [x] API接口地址已更新为B站
- [x] platform参数已改为6（B站）
- [x] photoId是BV号格式，用于拼接链接
- [x] readCount有真实数据，但不展示
- [x] shareCount展示为分享数
- [x] likeCount作为主排序指标
- [x] url字段为None，用BV号拼接bilibili.com链接
- [x] coverUrl为B站CDN（hdslb.com），无需referrerpolicy
- [x] HTML主题色改为B站蓝（#00A1D6）
- [x] 指标展示：分享/点赞/评论（零值隐藏）
- [x] 链接格式：bilibili.com/video/{BV号}
- [x] source字段：短剧B站信息源-GitHub

### 获取帮助

如有其他问题，可通过项目 GitHub 仓库提交 Issue。

## 📚 参考文档

- [core_workflow.md](references/core_workflow.md) — 核心执行流程、字段映射、HTML规则、指标展示规则、与抖音差异对比
- [examples.md](references/examples.md) — 使用示例与常见用法组合