# 短剧-公众号信息源 - 核心工作流程

## 执行流程总览

1. **第零步**:日期有效性预检(必须执行,先于任何接口调用)
2. **第一步**:生成爆款日报(调用脚本)
3. **第二步**:执行创作趋势分析(基于脚本输出)

---

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

> ⛔ **核心规则:未经用户确认,禁止调用任何数据接口,禁止自动执行 `--latest`**
>
> **绝对不能**在用户未确认的情况下自动执行脚本获取数据。

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

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

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

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

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

5. **等待用户明确确认后**,才能执行第一步(带 `--latest` 参数)
6. 若用户拒绝,则不执行任何接口调用

**示例对话**:

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

---

### 题材概览

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

---

### 创作趋势分析

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

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

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

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

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

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

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

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

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

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

(同上格式)

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

(同上格式)

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

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

---

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

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

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

---

## 输入解析

用户输入支持以下几种方式:

| 输入方式 | 示例 | 解析参数 |
|---------|------|---------|
| 查询默认短剧日报 | "查询今天的短剧公众号日报" | `--latest` |
| 按题材查询 | "穿越题材的短剧" | `topics="穿越"` |
| 按时间查询 | "6月的短剧爆款" | `start_time="2026-06-01 00:00:00", end_time="2026-06-30 23:59:59"` |
| 组合查询 | "穿越题材6月短剧" | `topics="穿越", start_time/end_time` |
| 指定日期 | "6月10日的短剧日报" | `date="2026-06-10"` |

## 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--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` | 自动使用最新有数据的日期,跳过无数据区间,不扣积分 | — |
| `--output-dir` | 输出目录 | `~/Downloads/QoderReports` |
| `--api-key` | 指定 API Key | — |
| `--subscribe` | 开启每日订阅 | — |
| `--unsubscribe` | 关闭每日订阅 | — |
| `--from-cache` | 使用缓存数据,避免重复调用接口 | — |

### topics(题材类型)

热门题材包括但不限于:

| 题材 | 说明 | 典型关键词 |
|------|------|-----------|
| 穿越 | 穿越时空题材 | 穿越、时空、古代、现代 |
| 霸总 | 霸道总裁题材 | 霸总、总裁、豪门 |
| 重生 | 重生逆袭题材 | 重生、回到、逆袭 |
| 悬疑 | 悬疑推理题材 | 悬疑、推理、反转、惊悚 |
| 甜宠 | 甜蜜宠溺题材 | 甜宠、恋爱、撒糖 |
| 逆袭 | 逆袭成长题材 | 逆袭、翻身、打脸 |

#### 平台固定为公众号

本skill专注于公众号平台短剧内容,platform固定为 `2`(公众号)。
接口调用时通过 `source` 字段同步记录,值为 `短剧公众号信息源-GitHub`。

## 日期处理逻辑

当用户提到时间时,自动转换为 `yyyy-MM-dd HH:mm:ss` 格式:

| 用户输入 | 转换结果 |
|---------|---------|
| "今天" | `startTime=今日00:00:00, endTime=今日23:59:59` |
| "昨天" | `startTime=昨日00:00:00, endTime=昨日23:59:59` |
| "本周" | `startTime=周一00:00:00, endTime=周日23:59:59` |
| "6月" | `startTime=2026-06-01 00:00:00, endTime=2026-06-30 23:59:59` |
| "近7天" | `startTime=7天前, endTime=当前时间` |

## 题材聚类规则

脚本自动根据文章标题和标签进行题材聚类:

1. **关键词匹配**:根据题材关键词库匹配文章题材
2. **多标签处理**:一篇文章可能属于多个题材,按主题材归类
3. **未知题材**:无法识别的归类为"其他"
4. **动态调整**:每日题材分类由当日内容动态决定,不固化

## 创作趋势分析逻辑

**新兴起量信号识别**:
- 题材文章数 < 10 但平均阅读 > 5w
- 或单篇文章阅读 > 20w

**爆款标题特征提取**:
- 统计高频词汇(前20个)
- 识别标题模式(如"重生之XX"、"XX霸总"等)
- 计算各模式的平均阅读数据

**核心公众号评选**:
- 按文章数排序(≥3篇)
- 同文章数按总阅读排序
- 展示TOP 10公众号

## 公众号字段映射

与抖音版本相比,公众号版本的核心字段调整:

| 抖音字段 | 公众号字段 | 说明 |
|---------|-----------|------|
| userName | accountName | 账号名称字段 |
| likeCount | readCount (排序依据) | 公众号以阅读量为核心指标 |
| 点赞量(主) | 阅读量(主) | 排序和展示的核心指标变更 |
| platform: 1 | platform: 2 | 平台标识符变更 |
| 短剧抖音日报 | 短剧公众号日报 | 输出文件命名 |

## 缓存机制

- 缓存路径:`~/.workbuddy/cache/playlet_gzh_data.json`
- 缓存时间:1 小时
- 使用 `--from-cache` 参数可使用缓存数据

## 常见错误处理

| 错误码 | 错误信息 | 处理方式 |
|--------|---------|---------|
| 1002 | 每页条数不能超过200 | 自动限制 page_size ≤ 200 |
| 3106 | 缺少 API Key | 提示用户配置 REDFOX_API_KEY |
| 3107 | API Key 无效 | 检查 Key 格式和有效性 |
| 3108 | 请求过于频繁 | 等待后重试 |
| 3109 | 今日调用次数达上限 | 提示用户次日再试 |
| 3201 | 积分不足 | 提示用户充值积分 |