youtube-research

YouTube 研究

研究表现突出的 YouTube 视频，借助 AI 分析热门内容，并生成可执行的报告。

前置条件

• TUBELAB_API_KEY 环境变量。请从 https://tubelab.net/settings/api 获取密钥
• GEMINI_API_KEY 环境变量（用于视频分析）
• Python 包 google-genai 和 requests

工作流

步骤 1：创建运行文件夹

mkdir -p youtube-research/$(date +%Y-%m-%d_%H%M%S)

步骤 2：获取频道 ID

读取 .claude/context/youtube-channel.md 获取频道 ID。

步骤 3：获取频道视频

python scripts/get_channel_videos.py CHANNEL_ID --format summary

此操作会返回包含频道视频标题和观看次数的 JSON。

步骤 4：分析频道

分析频道数据，提取：

• keywords：该频道垂直领域的 4 个搜索词
• adjacent-keywords：相同受众会观看的相关主题的 4 个搜索词
• audience：2-3 个受众画像，包括异议、转变和利害关系
• formulas：可复用的标题模板

完整架构和示例输出请参阅 references/channel-analysis-schema.md。

步骤 5：搜索表现突出的内容

使用两组关键词运行搜索：

python .claude/skills/youtube-research/scripts/find_outliers.py \
  --keywords "keyword1" "keyword2" "keyword3" "keyword4" \
  --adjacent-keywords "adjacent1" "adjacent2" "adjacent3" "adjacent4" \
  --output-dir youtube-research/{run-folder} \
  --top 5

此操作会运行两次搜索：

• 直接垂直领域：关键词的观看次数门槛为 5K+
• 相关受众：相关关键词的观看次数门槛为 10K+

输出文件：

• outliers.json - 为视频分析整理格式后的所有表现突出的视频
• report.md - 基础 Markdown 报告
• thumbnails/*.jpg - 视频缩略图
• transcripts/*.txt - 视频转录文本

步骤 6：筛选相关视频以供分析

读取 outliers.json 和 .claude/context/youtube-channel.md 中的用户细分领域。

重要：最多选择 3 个与用户细分领域最相关的视频。按以下条件筛选：

1. 标题相关性：标题包含与用户细分领域／主题相关的关键词
2. 转录文本相关性：如果有转录文本，检查其中是否提及相关主题
3. 直接垂直领域优先：优先选择直接关键词搜索结果，而非相关关键词搜索结果

跳过明显不符合用户内容风格的视频（例如，用户制作教程时，跳过娱乐／视频博客类内容）。

将筛选后的视频写入 {RUN_FOLDER}/filtered-outliers.json：

{
  "outliers": [/* max 3 relevant videos */],
  "filter_reason": "Selected based on relevance to [user's niche]"
}

步骤 7：使用 AI 分析热门视频

python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py \
  --input {RUN_FOLDER}/filtered-outliers.json \
  --output {RUN_FOLDER}/video-analysis.json \
  --platform youtube \
  --max-videos 3

从每个视频中提取：

• 开场吸引技巧及可复用的公式
• 内容结构和章节
• 留存技巧
• CTA 策略

完整输出架构及开场吸引／内容形式类型请参阅 video-content-analyzer 技能。

步骤 8：生成最终报告

读取 {RUN_FOLDER}/outliers.json 和 {RUN_FOLDER}/video-analysis.json，然后生成 {RUN_FOLDER}/report.md。

报告结构：

# YouTube Research Report

Generated: {date}

## Top Performing Hooks

Ranked by engagement. Use these formulas for your content.

### Hook 1: {technique} - {channelTitle}
- **Video**: "{title}"
- **Opening**: "{opening_line}"
- **Why it works**: {attention_grab}
- **Replicable Formula**: {replicable_formula}
- **Views**: {viewCount} | **zScore**: {zScore}
- [Watch Video]({url})

[Repeat for each analyzed video]

## Content Structure Patterns

| Video | Format | Pacing | Key Retention Techniques |
|-------|--------|--------|--------------------------|
| {title} | {format} | {pacing} | {techniques} |

## CTA Strategies

| Video | CTA Type | CTA Text | Placement |
|-------|----------|----------|-----------|
| {title} | {type} | "{cta_text}" | {placement} |

## All Outliers

### Direct Niche
| Rank | Channel | Title | Views | zScore |
|------|---------|-------|-------|--------|
[List direct niche outliers]

### Adjacent Audience
| Rank | Channel | Title | Views | zScore |
|------|---------|-------|-------|--------|
[List adjacent outliers]

## Actionable Takeaways

[Synthesize patterns into 4-6 specific recommendations based on video analysis]

重点提供可执行的洞察。“表现最佳的开场吸引”部分及其可复用公式应重点呈现。

快速参考

完整流程：

RUN_FOLDER="youtube-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && \
python .claude/skills/youtube-research/scripts/find_outliers.py \
  --keywords "k1" "k2" "k3" "k4" \
  --adjacent-keywords "a1" "a2" "a3" "a4" \
  --output-dir "$RUN_FOLDER" --top 5

然后筛选与细分领域相关的表现突出视频（最多 3 个）、运行视频分析并生成报告。

脚本参考

get_channel_videos.py

python .claude/skills/youtube-research/scripts/get_channel_videos.py CHANNEL_ID [--format json|summary]

参数	说明
CHANNEL_ID	YouTube 频道 ID（24 个字符）
--format	json（完整数据）或 summary（用于分析）

find_outliers.py

python .claude/skills/youtube-research/scripts/find_outliers.py --keywords K1 K2 K3 K4 --adjacent-keywords A1 A2 A3 A4 --output-dir DIR [options]

参数	说明
--keywords	直接垂直领域关键词（建议 4 个）
--adjacent-keywords	相关主题关键词（建议 4 个）
--output-dir	输出目录（必填）
--top	每个类别的视频数（默认：5）
--days	向前搜索的天数（默认：30）
--json	同时保存原始 JSON 数据

输出：outliers.json、report.md、thumbnails/、transcripts/

评分算法

视频按以下方式排名：zScore × recency_boost

• zScore：视频超出其频道平均水平的程度
• recency_boost：今天发布的视频为 1.0，每天衰减 5%（最低 0.3×）