douyin-hot-trend

---
name: douyin-hot-trend
description: 专注于获取抖音最新的热榜数据，每小时更新，包含热点事件、热度值和跳转链接；支持查询近7天、近30天历史热榜，并支持订阅定时推送。
---

# 抖音热榜

## 简介

抖音热榜是一款实时追踪抖音平台热点趋势的数据工具，对接 [红狐Hub](https://redfox.hk/) 数据 API，每小时更新热榜内容，并提供创作者视角的深度分析。

通过简单的自然语言指令，你可以：

- 📊 **实时热榜查询**：每 60 分钟抓取抖音 TOP 50 榜单，同步热度值与跳转链接
- 📅 **历史热榜回溯**：覆盖近 7 天、近 30 天历史数据，支持按日期与关键词检索
- 🔀 **热榜数据对比**：对比任意两个时间点（如昨天 vs 今天）的热榜变化
- 💡 **深度洞察分析**：从创作者视角提供选题机会、标题套路与趋势预判
- 🔔 **个性化订阅**：支持每小时或每日定时推送热榜数据

适用于内容创作者、短视频运营、MCN 机构、品牌营销人员等需要追踪抖音热点、寻找创作灵感、制定内容策略的场景。

**技术基础**：Python 3.x + `requests` 库，通过 红狐Hub APIKey获取数据。

---

## 功能特性

### 🎯 核心功能

- **📊 实时热榜**：获取抖音当前 TOP 50 热榜，每小时刷新，展示排名、热度值、话题标题和跳转链接
- **📅 历史回溯**：支持查询近 7 天或近 30 天历史热榜，最长覆盖 30 天
- **💡 创作者洞察**：自动生成选题机会分析、标题套路拆解、趋势预判与行动建议
- **📄 可视化报告**：一键生成紫色极简风格 HTML 页面，支持导出 PDF，每条记录可点击跳转
- **🔔 订阅推送**：支持每小时或每日定时推送，自动追踪热点变化

### ✨ 特色亮点

- **⚡ 自然语言交互**：输入「今日热榜」「近7天热榜」等即可查询，无需记忆命令参数
- **🔒 三级鉴权回退**：API Key 优先从环境变量读取，自动回退到 Shell 配置文件
- **✅ 数据一致性**：表格、洞察、HTML、PDF 全链路数据一致，不做加工或美化
- **🎬 创作者视角**：每条洞察都回答「怎么用」，给出可执行的行动建议

---

## 一键安装

### 前置条件

- 已安装 Python 3.x 及 `requests` 库
- 已注册 [红狐Hub官网](https://redfox.hk/login) 账号并获取 API Key（格式 `ak_xxxxxxxx`）
- 新注册用户将获赠免费积分，可立即开始使用

### 安装方式

#### 方式一：WorkBuddy（龙虾）技能安装（推荐）

1. 将 `douyin-hot-trend` 技能文件夹复制到 WorkBuddy 的 skills 目录下
2. 在 WorkBuddy 对话中直接说「抖音热榜」或「今日热榜」，Agent 将自动加载本技能
3. 配置 API Key（见下方「环境变量配置」）
4. 安装 Python 依赖：

```bash
pip install requests
```

#### 方式二：Cursor / 其他 Agent 环境手动安装

1. 将技能文件夹放置到对应环境的 skills 目录
2. 确保 Agent 可读取 `SKILL.md` 与 `references/core_workflow.md`
3. 配置 `REDFOX_API_KEY` 环境变量
4. 执行 `pip install requests`

### 环境变量配置

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

**配置方式**（任选其一）：

```bash
# 方式一：直接设置环境变量（推荐）
export REDFOX_API_KEY=ak_xxxxxxxx

# 方式二：写入 Shell 配置文件（~/.bashrc / ~/.bash_profile / ~/.zshrc）
echo 'export REDFOX_API_KEY=ak_xxxxxxxx' >> ~/.bashrc
source ~/.bashrc
```

若未配置环境变量，技能将自动从 Shell 配置文件读取；若仍未获取到，会在运行时提示配置。

**在 WorkBuddy 中配置 Key**：可在系统环境变量中设置 `REDFOX_API_KEY`，或在 Shell 配置文件中写入后重启 WorkBuddy，无需在每次对话中手动传入。

---

## 使用指南

### 基础使用

#### 1. 查看实时热榜

告诉助手你想查看当前抖音热点：

> **用户**：抖音热榜
> **助手**：为您展示抖音实时热榜 TOP 20（含排名、热度值、话题链接），并附创作者洞察报告。

#### 2. 查看历史热榜

查询指定时间范围的历史数据：

> **用户**：近7天热榜
> **助手**：为您展示近 7 天抖音历史热榜，支持按日期回溯热点演变。

> **用户**：4月15日热榜
> **助手**：为您查询 4 月 15 日当天的热榜数据。

#### 3. 加载完整榜单

默认展示 TOP 20，可继续加载至 TOP 50：

> **用户**：继续加载
> **助手**：为您展示 TOP 21–50，并生成包含完整 TOP 50 的 HTML 报告。

### 高级使用

#### 1. 创作者洞察

热榜展示后自动输出深度分析：

> **用户**：今日热榜
> **助手**：（展示表格后）输出爆款选题机会、标题套路破解、趋势预判与行动建议。

#### 2. 热榜对比

对比两个时间点的热榜变化：

> **用户**：对比昨天和今天的热榜
> **助手**：为您对比两日热榜排名与热度变化，标注新进榜与掉榜话题。

#### 3. 订阅推送

设置定时自动推送：

> **用户**：订阅每日热榜推送
> **助手**：已设置每日推送，将在指定时间自动推送 TOP 50 完整热榜数据。

> **用户**：取消订阅
> **助手**：已取消定时推送。

#### 4. 生成报告

每次查询自动生成可视化报告：

> **用户**：今日热榜
> **助手**：（查询完成后）已生成 HTML 页面与 PDF 文件，数据与表格展示完全一致，支持点击跳转。

### 常用指令速查

| 指令 | 功能 |
|------|------|
| 抖音热榜 / 今日热榜 | 查询实时热榜 TOP 20 |
| 昨日热榜 | 查询昨日热榜 |
| 近7天热榜 | 查询近 7 天历史热榜 |
| 近30天热榜 | 查询近 30 天历史热榜 |
| X月X日热榜 | 查询指定日期热榜 |
| 继续加载 / 加载更多 | 加载 TOP 21–50 完整榜单 |
| 订阅每日/每小时推送 | 设置定时推送 |
| 取消订阅 | 停止定时推送 |

---

## 使用场景

### 场景一：内容创作者找选题

**角色**：抖音短视频创作者

**需求**：每天快速了解平台热点，找到适合自己赛道的创作方向

**使用方式**：
1. 每天早晨说「今日热榜」，获取最新热点
2. 查看创作者洞察报告，获取选题建议和标题公式
3. 直接套用可迁移选题，快速产出内容

**预期收益**：缩短选题时间，提高内容命中率

---

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

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

**需求**：监控平台热点趋势，为旗下达人提供选题指导和内容策略

**使用方式**：
1. 订阅每日热榜推送，自动获取最新热点
2. 查看历史热榜，分析热点演变规律
3. 将洞察报告分享给达人团队，指导内容创作

**预期收益**：提升团队内容策略的时效性和精准度

---

### 场景三：品牌营销热点借势

**角色**：品牌营销经理

**需求**：及时发现可借势的热点话题，制定蹭热点营销方案

**使用方式**：
1. 关注每日热榜，筛选与品牌调性匹配的热点
2. 分析趋势预判，提前布局内容
3. 导出 HTML/PDF 报告，用于团队沟通和方案汇报

**预期收益**：提升品牌热点的响应速度和借势效果

---

### 场景四：短视频运营学习研究

**角色**：短视频运营新手

**需求**：学习爆款内容的创作规律，提升运营能力

**使用方式**：
1. 定期查看热榜和创作者洞察
2. 学习标题套路和情绪触发词
3. 模仿可迁移选题进行练习

**预期收益**：快速建立内容 sense，掌握爆款创作方法论

---

## 项目架构

### 目录结构

```
douyin-hot-trend/
├── SKILL.md                          # 技能说明文档（当前文件）
├── references/
│   └── core_workflow.md              # Agent 核心工作流指令
├── scripts/
│   ├── hotspot_fetcher.py            # 热榜数据获取脚本
│   └── gen_douyin_hot_html.py        # HTML 可视化报告生成脚本
└── assets/
    └── douyin_hot_trend_template.html # HTML 页面模板
```

### 核心模块说明

| 模块 | 文件 | 职责 |
|------|------|------|
| 数据获取 | `hotspot_fetcher.py` | 调用 红狐Hub API 获取抖音热榜 JSON，支持实时与历史查询 |
| 报告生成 | `gen_douyin_hot_html.py` | 将热榜数据渲染为紫色极简风格 HTML，支持导出 PDF |
| 页面模板 | `douyin_hot_trend_template.html` | 独立 HTML 模板，支持占位符快速替换生成 |

### 技术栈

| 类别 | 说明 |
|------|------|
| 运行环境 | Python 3.x |
| HTTP 请求 | 原生 `requests` 库 |
| 认证方式 | `X-API-KEY` 请求头，三级回退（环境变量 → Shell 配置 → 提示配置） |
| 数据来源 | [红狐Hub API](https://redfox.hk/) |
| 部署平台 | WorkBuddy / Cursor 等 Agent 环境 |


## 常见问答

### 安装相关问题

**Q1: 运行时提示「缺少 REDFOX_API_KEY 配置」怎么办？**

A: 请按以下步骤排查：
1. 确认已注册 红狐Hub 账号并在个人中心获取 API Key
2. 设置环境变量：`export REDFOX_API_KEY=ak_xxxxxxxx`
3. 或写入 Shell 配置文件后执行 `source ~/.bashrc` 使其生效
4. 确认 API Key 格式正确，以 `ak_` 开头

**Q2: 需要安装哪些 Python 依赖？**

A: 仅需 `requests` 库：`pip install requests`

**Q3: 如何在 WorkBuddy（龙虾）中启用本技能？**

A: 将技能文件夹放入 WorkBuddy 的 skills 目录，配置好 `REDFOX_API_KEY` 后，在对话中说「抖音热榜」即可触发。Agent 将按 `references/core_workflow.md` 执行完整工作流。

---

### 使用相关问题

**Q4: 热榜数据多久更新一次？**

A: 每小时更新一次。每次查询都会调用 API 获取最新数据，不依赖本地缓存。

**Q5: 可以查询多久之前的历史数据？**

A: 最长支持查询近 30 天的历史热榜。超过 30 天的数据暂不支持。


---

### 故障排除

**Q6: API 调用失败怎么办？**

A: 请按以下顺序排查：
1. 检查网络连接，确认可以访问 `https://redfox.hk`
2. 确认 API Key 未过期，账户积分是否充足
3. 检查环境变量：`echo $REDFOX_API_KEY`
4. 稍后重试，API 服务可能存在临时波动

**Q7: 订阅推送没有收到怎么办？**

A: 确认订阅已成功设置。如需重新设置，说「取消订阅」后重新订阅。如仍有问题，检查WorkBuddy等系统的自动化任务是否正常运行。

**Q8: HTML 报告预览不成功或显示空白怎么办？**

A: 请按以下方式处理：
1. 确认 HTML 文件已成功生成（脚本会输出 `✅ 已生成` 提示）
2. 直接双击打开交付的 HTML 文件，用 Chrome/Edge 浏览器查看，不依赖WorkBuddy等系统内置预览
3. 若文件已交付但内置预览空白，属于已知限制——Windows 中文用户名路径可能导致预览组件兼容性问题，直接用浏览器打开即可正常显示

---

### 安全与许可

**Q9: API Key 如何安全存储？**

A: 建议通过环境变量或 Shell 配置文件存储，不要将 Key 写入代码仓库或公开分享。本技能支持三级鉴权回退，优先读取环境变量，避免在对话中明文传递。

**Q10: 数据来源与使用许可？**

A: 热榜数据来自 [红狐Hub](https://redfox.hk/) 官方 API，使用时须遵守 红狐Hub 平台服务条款及抖音平台相关规定。本技能仅作数据展示与分析辅助，不保证数据的商业用途合规性。

---

### 获取帮助

如有其他问题，可通过以下方式获取帮助：

- 📖 查阅 Agent 执行参考：`references/core_workflow.md`
- 🌐 红狐Hub 官网：[https://redfox.hk](https://redfox.hk/)
- 📧 联系 红狐Hub 平台客服获取 API 相关问题支持

---

**Agent 执行参考**：完整的操作步骤、输出格式、数据规则等执行层指令，请查阅 `references/core_workflow.md`。