playlet-xhs-feed

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

短剧-小红书信息源

简介

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

通过红狐Hub API,你可以:

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

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

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

⛔ 输出规范:日报生成后,对话回复必须严格按照输出模板输出 md 内容,禁止任何自由发挥、省略或口语化文字。详见 references/core_workflow.md 中的终端输出格式规范。

功能特性

🎯 核心功能

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

✨ 特色亮点

• ⚡ 智能日期判断:脚本内置 DATA_UPDATE_HOUR = 15 常量,调用接口前自动检测目标日期是否在无数据区间
• 📱 小红书适配:作品链接自动拼接 xiaohongshu.com/explore/{photoId},互动数据为0的字段自动隐藏
• 🔒 安全可靠:API Key通过环境变量 REDFOX_API_KEY 获取,禁止硬编码

一键安装

前置条件

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

安装步骤

1. 获取 API Key

前往 红狐Hub 官网 注册,登录后在个人中心获取,格式为 ak_xxxxxxxx。新注册用户获赠免费积分。

2. 配置环境变量

macOS/Linux:

echo 'export REDFOX_API_KEY=ak_xxxxxxxx' >> ~/.zshrc
source ~/.zshrc

Windows(PowerShell):

[Environment]::SetEnvironmentVariable("REDFOX_API_KEY", "ak_xxxxxxxx", "User")

配置后需重启终端使环境变量生效。

3. 验证配置

# macOS/Linux
echo $REDFOX_API_KEY

# Windows
echo %REDFOX_API_KEY%

环境变量配置

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

使用指南

基础使用

1. 生成最新日报

python3 assets/daily_report.py --latest

执行流程:

1. 自动计算最新可用日期(15:00规则)
2. 查询全部短剧内容(pageSize=200)
3. 题材聚类+生成HTML日报
4. 自动浏览器打开

⚠️ 日期预检规则:若目标日期无数据,必须先告知用户并等待确认后才能执行。

2. 查询指定日期

python3 assets/daily_report.py --date 2026-06-10

历史日期已有数据,无需确认,直接查询。

3. 自定义题材查询

# 穿越题材
python3 assets/daily_report.py --topics "穿越,时空,重生"

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

高级使用

1. 自定义时间范围

python3 assets/daily_report.py \
  --start-time "2026-06-10 08:00:00" \
  --end-time "2026-06-15 20:00:00"

2. 使用缓存数据

python3 assets/daily_report.py --from-cache

从 ~/.workbuddy/cache/playlet_xhs_data.json 加载,缓存有效期1小时,不扣积分。

3. 开启每日订阅

python3 assets/daily_report.py --subscribe

日报自动保存至 ~/Downloads/QoderReports/,文件名:短剧小红书日报_YYYY-MM-DD.html。

4. 指定输出目录

python3 assets/daily_report.py --latest --output-dir "/Users/xxx/Desktop/Reports"

常用命令速查

命令	功能
--latest	自动使用最新有数据的日期,跳过无数据区间
--date YYYY-MM-DD	指定日期查询(历史日期无需确认)
--topics "词1,词2"	自定义题材关键词,逗号分隔
--count N	扫描作品数量,默认200
--from-cache	使用缓存数据,不扣积分
--subscribe	开启每日订阅
--unsubscribe	关闭每日订阅
--start-time / --end-time	自定义时间范围
--output-dir	自定义输出目录
--api-key	指定API Key

使用场景

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

角色:短剧编剧/制作人

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

使用方式:

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/                       # Skill运行时资源
│   ├── daily_report.py           # 日报生成脚本(运行时使用)
│   └── 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=视频号)
来源标识	source	"短剧小红书信息源-GitHub"
数据存储	JSON缓存	~/.workbuddy/cache/playlet_xhs_data.json
输出格式	HTML + 终端Markdown	深色主题,小红书红(#FF2442)
输出目录	~/Downloads/QoderReports	可自定义

核心模块说明

模块	文件	职责
API调用	fetch_playlet_data()	批量查询题材数据,自动去重排序
题材聚类	cluster_by_topic()	9大题材关键词匹配+自动归类
HTML生成	generate_html_report()	深色主题日报,互动数据为0时隐藏
日期计算	calculate_latest_date()	15:00规则自动推算可用日期
缓存管理	load_cache()/save_cache()	1小时有效期,基于photoId去重

数据流转

用户请求 → 日期预检(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 官网 注册账号,登录后在个人中心获取,格式为 ak_xxxxxxxx。新注册用户获赠免费积分。

---

使用相关问题

Q3: 数据多久更新一次?

A: 每日15:00更新前一天的数据。

• 15:00前:最新可用日期 = 前天(T-2)
• 15:00后:最新可用日期 = 昨天(T-1)

Q4: 查询不到数据怎么办?

A: 可能原因:

1. 目标日期尚无数据(未到15:00更新时间)
2. API Key权限不足或积分耗尽
3. 网络连接问题

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

---

故障排除

Q5: Windows PowerShell 执行报 UnicodeEncodeError?

A: 脚本输出包含emoji,需设置UTF-8编码:

$env:PYTHONIOENCODING='utf-8'
python assets/daily_report.py --latest

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

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

---

安全与许可

Q7: 数据安全如何保障?

A:

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

📚 参考文档

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

---

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

短剧-小红书信息源

📝 简介

每日自动扫描小红书短剧创作内容,按互动量筛选爆款作品,智能聚类题材后生成HTML日报。同步提供创作趋势分析,帮助短剧创作者把握流量风口。

重要:数据每日15:00更新前一天数据,目标日期无数据时禁止自动调用接口,必须先告知用户并等待确认。

⛔ 输出规范:日报生成后,对话回复必须严格按照「📊 输出格式」模板输出 md 内容,禁止任何自由发挥、省略或口语化文字。

✨ 功能特性

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

🔑 鉴权

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

API Key 获取:前往 红狐Hub 官网 注册,登录后在个人中心获取,格式为 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 字段（固定值 "短剧小红书信息源-GitHub"）同步记录,无需额外请求保存接口。

🔄 工作流程

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

⛔ 核心规则:未经用户确认,禁止调用任何数据接口,禁止自动执行 --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)

第一步:生成爆款日报

# 生成最新一期日报(用户确认后,自动跳过无数据日期,不扣积分)
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/,自动浏览器打开。终端同步输出题材分类表格 + 创作趋势分析报告。

⛔ 强制输出规则:日报生成后,对话回复必须严格按照下方「📊 输出格式」模板输出 md 内容,禁止任何自由发挥、省略、简化或口语化文字。模板是唯一合法输出格式。

📊 输出格式(强制执行)

⛔ 严格执行规则:

• 以下模板是唯一合法输出格式,禁止任何自由发挥、省略、简化或重新组织
• 禁止输出模板中未定义的额外内容(如"我来帮你…""以下是…"等口语化文字)
• 禁止合并、跳过任何板块,即使某板块数据为"暂无"也必须保留该板块标题
• 每次获取日报后,对话回复必须严格按此模板输出 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	扫描作品数量,满足即停	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	关闭每日订阅	—
--no-open	已移除 生成后始终自动预览	—

💬 自定义题材查询场景

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

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

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

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

自定义查询逻辑:

• 用户提供的所有题材通过批量接口一次性查询,无需逐个调用
• 查询结果自动去重,题材聚类、趋势分析均基于查询结果生成,与用户关注方向强关联

📚 参考文档

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