短剧-公众号信息源

SKILL.md

---
name: playlet-gzh-feed
description: "短剧-公众号信息源 — 每日扫描公众号短剧爆款文章,按阅读量筛选热门内容,智能聚类题材方向后生成包含封面图、互动数据与创作洞察的HTML日报。支持按题材(穿越/霸总/重生等)、公众号、时间范围定向查询。⚠️数据每日15:00更新前一天数据,目标日期无数据时必须先告知用户并等待确认后才能调用接口,禁止自动获取。当用户需要短剧公众号日报、公众号短剧爆款、短剧热点、短剧创作趋势或自定义题材查询时使用。"
---

# 短剧-公众号信息源

## 📝 简介

短剧-公众号信息源是一款专为短剧创作者和内容运营设计的公众号爆款追踪工具,每日自动扫描公众号短剧内容,按阅读量筛选热门作品,智能聚类题材方向后生成可视化 HTML 日报与创作趋势分析。

通过简单的指令,你可以:
- 🔥 发现当日公众号短剧爆款文章
- 📊 获取按题材智能聚类的热门内容
- 📈 分析爆款标题特征与创作趋势
- 🔔 开启每日订阅,自动产出日报

适用于短剧编剧、内容运营、MCN 机构、公众号号主等需要追踪公众号短剧热点的场景。

> ⚠️ **重要提醒**:数据每日 15:00 更新前一天数据,目标日期无数据时**必须先告知用户并等待确认后才能调用接口**,禁止自动获取。


## ✨ 功能特性

### 🎯 核心功能

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

### ✨ 技术亮点

- ⚡ **批量查询**:所有题材通过批量接口一次性查询,节省接口调用次数
- 🧠 **智能聚类**:9 大题材自动分类(穿越/霸总/重生/悬疑/甜宠/逆袭/年代/战神/古装)
- 🔒 **安全接入**:通过 API Key 鉴权,无需账号密码
- 📅 **日期智能判断**:脚本内置 `DATA_UPDATE_HOUR = 15` 常量,自动检测目标日期有效性
- 💾 **缓存机制**:1 小时有效期,避免重复扣费


## 🔑 安装配置

### 前置条件

- Python 3 运行环境
- 红狐Hub API Key(前往 [红狐Hub 官网](https://redfox.hk/) 注册获取,格式为 `ak_xxxxxxxx`)

### 环境变量配置

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

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

**配置方式**:

- **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` 字段同步记录（值为 `短剧公众号信息源-GitHub`），无需额外请求保存接口。


## 📖 使用指南

### 基础使用

#### 1. 日期有效性预检(必须执行,先于任何接口调用)

> ⛔ **核心规则:未经用户确认,禁止调用任何数据接口,禁止自动执行 `--latest`**

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

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

1. 获取当前系统日期 T 和当前时间,按 15:00 规则计算最新可用日期
2. 判断用户请求的目标日期是否在无数据区间(即 > 最新可用日期)
3. **若目标日期有数据**(≤ 最新可用日期):直接执行第 2 步,无需额外确认
4. **若目标日期无数据**(> 最新可用日期),向用户输出提示并**等待用户明确确认后**才能继续:

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

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

5. 若用户拒绝,则不执行任何接口调用

**示例对话**:

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

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

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

```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),数据不足时自动追加热门题材(穿越→霸总→重生→悬疑→甜宠→逆袭),所有题材通过批量接口一次性查询,无需逐个调用。用户自定义题材时仅使用用户提供的列表,同样批量查询。

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

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

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

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

### 高级使用

#### 自定义题材查询

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

```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 "悬疑,推理,反转,惊悚"
```

**自定义查询逻辑**:
- 用户提供的所有题材通过批量接口一次性查询,无需逐个调用
- 查询结果自动去重,题材聚类、趋势分析均基于查询结果生成

#### 时间范围查询

```bash
# 查询 6 月短剧爆款
python3 "$SKILL_PATH/assets/daily_report.py" \
  --start-time "2026-06-01 00:00:00" \
  --end-time "2026-06-30 23:59:59"

# 查询近 7 天短剧
python3 "$SKILL_PATH/assets/daily_report.py" \
  --start-time "2026-06-10 00:00:00" \
  --end-time "2026-06-17 23:59:59"
```

#### 订阅功能

```bash
# 开启每日订阅 — 日报自动产出并保存至 ~/Downloads/QoderReports/
python3 "$SKILL_PATH/assets/daily_report.py" --subscribe

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

### 命令速查

| 命令/参数 | 功能 | 默认值 |
|----------|------|--------|
| `--latest` | 自动使用最新有数据的日期,跳过无数据区间 | — |
| `--date YYYY-MM-DD` | 指定日期查询(若无数据会提示并询问切换) | 今天 |
| `--topics "题材1,题材2"` | 自定义题材关键词,逗号分隔 | `短剧` |
| `--start-time` | 自定义开始时间 YYYY-MM-DD HH:MM:SS | — |
| `--end-time` | 自定义结束时间 YYYY-MM-DD HH:MM:SS | — |
| `--count N` | 扫描文章数量,满足即停 | `200` |
| `--output-dir` | 输出目录 | `~/Downloads/QoderReports` |
| `--api-key` | 指定 API Key(覆盖环境变量) | — |
| `--subscribe` | 开启每日订阅 | — |
| `--unsubscribe` | 关闭每日订阅 | — |


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

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

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

```
## 短剧-公众号信息源 · {日期} 日报

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

---

### 题材概览

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

---

### 创作趋势分析

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

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

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

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

**三、核心公众号榜**

| 公众号 | 作品数 | 总阅读 | 代表作 |
|--------|--------|--------|--------|
| @{公众号} | {N}篇 | {X}w | 《{作品}》 |
| ... | ... | ... | ... |
(若无公众号数据,输出:暂无核心公众号数据)

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

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

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

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

(同上格式)

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

(同上格式)

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

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

---

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

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

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


## 🎯 使用场景

### 场景一:短剧编剧选题调研

**角色**:短剧编剧

**需求**:了解当前公众号短剧哪些题材最火,为下一部作品选题

**使用方式**:
1. 运行默认日报,查看题材概览和趋势分析
2. 关注新兴起量信号,发现蓝海题材
3. 分析爆款标题特征,学习流量密码

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

---

### 场景二:内容运营日报追踪

**角色**:公众号运营 / MCN 运营

**需求**:每日追踪短剧公众号爆款,形成团队内部情报

**使用方式**:
1. 开启 `--subscribe` 订阅,每日自动产出日报
2. 按题材查询(`--topics "穿越,霸总"`)聚焦团队关注方向
3. 分析核心公众号榜,发现优质对标账号

**预期收益**:建立团队短剧情报体系,驱动内容决策

---

### 场景三:竞品分析

**角色**:品牌方 / 投放经理

**需求**:监测竞品公众号的短剧推广表现

**使用方式**:
1. 用 `--topics` 查询竞品相关关键词
2. 分析竞品题材分布和阅读数据
3. 对比自身与竞品的题材布局差异

**预期收益**:及时调整投放策略,优化内容差异化

---

### 场景四:创作趋势复盘

**角色**:内容总监 / 数据分析师

**需求**:复盘一段时间内的短剧创作趋势变化

**使用方式**:
1. 使用 `--start-time` 和 `--end-time` 查询指定时间段
2. 对比不同日期的题材分布和爆款特征
3. 识别持续增长题材和衰退题材

**预期收益**:掌握中长期趋势,指导内容战略规划


## 🏗️ 项目架构

### 目录结构

```
短剧-公众号信息源/
├── SKILL.md                    # 主文档(Skill 定义)
├── README.md                   # 快速开始指南
├── assets/
│   └── daily_report.py        # 主脚本
├── scripts/
│   └── playlet_gzh_daily.py   # 脚本副本
└── references/
    ├── core_workflow.md       # 核心执行流程、日期预检、输出格式模板、错误处理
    └── examples.md            # 使用示例与常见用法组合
```

### 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 运行环境 | Python 3 | 脚本语言 |
| 数据源 | 红狐Hub API | 公众号短剧数据接口 |
| 鉴权方式 | X-API-KEY | 请求头鉴权 |
| 输出格式 | HTML/CSS | 深色主题可视化日报 |
| 缓存机制 | JSON 文件 | 1 小时有效期 |

### 平台适配说明

本 skill 基于"短剧-抖音信息源"改造,针对公众号平台做了以下核心适配:

| 维度 | 抖音版本 | 公众号版本(本 skill) |
|------|---------|---------------------|
| 平台标识 | `platform: 1` | `platform: 2` |
| 核心指标 | 点赞量(likeCount) | 阅读量(readCount) |
| 账号字段 | userName | accountName |
| 展示指标 | 点赞、评论、分享 | 阅读(👁)、点赞(👍)、分享(↗) |
| 主题色 | 粉色 #FB7299 | 绿色 #07C160 |
| 图标 | 🔗👍⭐ | 👁👍↗ |
| 文件命名 | 短剧抖音日报 | 短剧公众号日报 |
| 缓存文件 | playlet_douyin_data.json | playlet_gzh_data.json |

**核心代码差异**:

```python
# 排序逻辑 — 公众号以阅读量为核心排序指标
# 抖音: unique_items.sort(key=lambda x: x.get("likeCount", 0), reverse=True)
# 公众号: unique_items.sort(key=lambda x: x.get("readCount", 0), reverse=True)

# 文件命名
# 抖音: f"短剧抖音日报_{date_str}.html" / "playlet_douyin_data.json"
# 公众号: f"短剧公众号日报_{date_str}.html" / "playlet_gzh_data.json"
```

**保持一致的部分**:日期预检机制、数据更新规则、批量查询策略、题材聚类算法、去重机制、缓存机制、输出格式模板、订阅功能、创作趋势分析逻辑。

**注意事项**:
1. API 接口使用相同端点 `https://redfox.hk/story/api/parseWork/queryPlayletMsgs`
2. 必须设置 `platform: 2` 才能获取公众号数据
3. 公众号和抖音使用不同的缓存文件,互不干扰


## ❓ 常见问答

### 安装相关

**Q1: API Key 怎么获取?**

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

**Q2: 配置了 API Key 但提示无效?**

A: 请检查:
1. Key 是否已正确复制(前后无空格)
2. Windows 下需重启终端使环境变量生效
3. 确认 Key 格式为 `ak_` 开头

### 使用相关

**Q3: 为什么查询今天的数据提示无数据?**

A: 数据每日 15:00 更新前一天数据。15:00 前最新可查为前天,15:00 后为昨天。脚本会提示最新可查日期并询问是否切换。

**Q4: 可以查询哪些题材?**

A: 脚本内置 9 大题材分类:穿越、霸总、重生、悬疑、甜宠、逆袭、年代、战神、古装。你也可以通过 `--topics` 传入任意自定义关键词。

**Q5: 默认查询和自定义题材查询有什么区别?**

A: 默认查询全部短剧内容(pageSize=200),数据不足时自动追加热门题材;自定义查询仅使用你提供的题材列表,同样批量查询。

### 故障排除

**Q6: 脚本报错 UnicodeEncodeError 怎么办?**

A: Windows 下需设置环境变量 `PYTHONIOENCODING=utf-8`,可在命令前加上 `$env:PYTHONIOENCODING='utf-8';`。

**Q7: 接口返回错误码?**

A: 常见错误码对照:

| 错误码 | 含义 | 解决方式 |
|--------|------|---------|
| 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) — 使用示例与常见用法组合