skill_youtube_crawler.md 4.36 KB

Skill: YouTube 热门视频爬虫

基本信息

  • ID: youtube-crawler
  • 类型: data-collection
  • 版本: 1.0.0
  • 状态: production-ready
  • 目标分数: 95/100 ✅

功能描述

从 YouTube 获取当日最热门视频列表,支持 YouTube Data API v3 和 yt-dlp 降级方案。提供多地区批量获取、JSON/CSV 导出、配额管理等功能。

使用方法

const { YouTubeTrendingCrawler } = require('./youtube_crawler');

// 创建爬虫实例
const crawler = new YouTubeTrendingCrawler({
  apiKey: process.env.YOUTUBE_API_KEY,  // 可选,默认从环境变量读取
  useMock: false,                        // 是否使用 Mock 数据
  timeout: 30000,                        // 请求超时时间
  maxRetries: 3,                         // 最大重试次数
  enableFallback: true                   // 是否启用 yt-dlp 降级
});

// 获取单地区热门视频
const videos = await crawler.get_trending('US', 10);

// 获取多地区热门视频
const results = await crawler.get_multi_region_trending(['US', 'JP', 'KR'], 10);

// 保存为 JSON
await crawler.save_to_json(videos, '/path/to/output.json');

// 保存为 CSV
await crawler.save_to_csv(videos, '/path/to/output.csv');

输入参数

参数 类型 必填 默认值 说明
regionCode string 否 "US" 地区代码 (ISO 3166-1 alpha-2)
maxResults number 否 10 返回数量 (1-50)
videoCategoryId string 否 null 视频分类 ID (如 "10"=Music)
useMock boolean 否 false 是否使用 Mock 数据
apiKey string 否 env.YOUTUBE_API_KEY YouTube Data API Key

输出字段

字段 类型 说明
videoId string YouTube 视频 ID
url string 完整视频链接
title string 视频标题
channelTitle string 频道名称
viewCount number 播放次数
thumbnails object 缩略图对象 (default/medium/high)
publishedAt string 发布时间 (ISO 8601)
categoryId string 视频分类 ID

API 方法

获取单个地区的热门视频。

const videos = await crawler.get_trending('US', 10, '10');
// 返回: [{ videoId, url, title, channelTitle, viewCount, ... }]

批量获取多地区热门视频。

const results = await crawler.get_multi_region_trending(['US', 'JP', 'KR'], 10);
// 返回: { US: [...], JP: [...], KR: [...] }

extract_video_info(apiItem)

从 YouTube API 响应中提取标准化视频信息。

save_to_json(data, filepath)

将视频数据保存为 JSON 文件。

save_to_csv(data, filepath)

将视频数据保存为 CSV 文件。

配置选项

const crawler = new YouTubeTrendingCrawler({
  apiKey: 'your-api-key',      // YouTube Data API Key
  useMock: false,              // 使用 Mock 数据
  timeout: 30000,              // 请求超时 (ms)
  maxRetries: 3,               // 最大重试次数
  enableFallback: true,        // 启用 yt-dlp 降级
  quotaLimit: 10000            // 每日 API 配额限制
});

配额管理

  • 每日配额: 10,000 units
  • mostPopular 请求: 1 unit/次
  • 配额追踪: crawler.quotaUsed, crawler.quotaLimit
  • 剩余配额: crawler.getRemainingQuota()

错误处理

错误码 场景 处理策略
400 请求参数错误 返回验证错误
403 API Key 无效或配额耗尽 自动降级到 yt-dlp
429 速率限制 指数退避重试,再失败则降级

环境变量

export YOUTUBE_API_KEY="your-api-key"     # YouTube Data API Key
export YOUTUBE_CRAWLER_MOCK="1"           # 启用 Mock 模式

依赖

  • Node.js >= 18
  • yt-dlp (可选,用于降级方案)

评分历史

版本 分数 日期 主要改进
v1.0 95/100 2026-04-01 初始版本,类结构重构,完整 benchmark 通过

文件位置

  • 技能代码: system/agents/youtube-crawler/.claude/skills/youtube-crawler/youtube_crawler.js
  • 进化日志: system/templates/youtube-crawler/workspace/evolve/evolution_log.json
  • 测试结果: system/templates/youtube-crawler/workspace/evolve/test_results.json