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 方法
get_trending(regionCode, maxResults, videoCategoryId)
获取单个地区的热门视频。
const videos = await crawler.get_trending('US', 10, '10');
// 返回: [{ videoId, url, title, channelTitle, viewCount, ... }]
get_multi_region_trending(regionCodes, maxResultsPerRegion, videoCategoryId)
批量获取多地区热门视频。
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