# Skill: YouTube 热门视频爬虫 ## 基本信息 - **ID**: youtube-crawler - **类型**: data-collection - **版本**: 1.0.0 - **状态**: training - **目标分数**: 95/100 ## 功能描述 从 YouTube 获取当日最热门视频列表,支持 API 和降级方案。 ## 输入参数 | 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | regionCode | string | 否 | "US" | 地区代码 (ISO 3166-1 alpha-2) | | videoCategoryId | string | 否 | null | 视频分类 ID | | maxResults | integer | 否 | 10 | 返回数量 (1-50) | | useApi | boolean | 否 | true | 优先使用 API | ## 输出字段 | 字段 | 类型 | 说明 | |------|------|------| | videoId | string | YouTube 视频 ID | | url | string | 完整视频链接 | | title | string | 视频标题 | | channelTitle | string | 频道名称 | | viewCount | integer | 播放次数 | | thumbnail | string | 高清封面 URL | | publishedAt | string | 发布时间 (ISO 8601) | ## 实现方案 ### 方案 1: YouTube Data API v3 (推荐) ```javascript async function getTrendingVideosAPI({ regionCode = 'US', maxResults = 10, apiKey }) { const url = 'https://www.googleapis.com/youtube/v3/videos'; const params = new URLSearchParams({ part: 'snippet,statistics', chart: 'mostPopular', regionCode, maxResults: Math.min(Math.max(1, maxResults), 50), key: apiKey }); const response = await fetch(`${url}?${params}`); if (!response.ok) { throw new Error(`API error: ${response.status}`); } const data = await response.json(); return data.items.map(item => ({ videoId: item.id, url: `https://youtube.com/watch?v=${item.id}`, title: item.snippet.title, channelTitle: item.snippet.channelTitle, viewCount: parseInt(item.statistics.viewCount, 10), thumbnail: item.snippet.thumbnails.high?.url || item.snippet.thumbnails.default?.url, publishedAt: item.snippet.publishedAt })); } ``` ### 方案 2: yt-dlp (降级) ```javascript async function getTrendingVideosYTDLP({ regionCode = 'US', maxResults = 10 }) { // 使用 yt-dlp 命令行 const { execSync } = require('child_process'); const url = regionCode === 'US' ? 'https://www.youtube.com/feed/trending' : `https://www.youtube.com/feed/trending?gl=${regionCode}`; const cmd = `yt-dlp --flat-playlist --playlist-end ${maxResults} -J "${url}"`; const output = execSync(cmd, { encoding: 'utf-8', timeout: 30000 }); const data = JSON.parse(output); return data.entries.map(entry => ({ videoId: entry.id, url: entry.webpage_url || `https://youtube.com/watch?v=${entry.id}`, title: entry.title, channelTitle: entry.uploader, viewCount: entry.view_count || 0, thumbnail: entry.thumbnail, publishedAt: entry.upload_date ? `${entry.upload_date.slice(0,4)}-${entry.upload_date.slice(4,6)}-${entry.upload_date.slice(6,8)}T00:00:00Z` : null })); } ``` ### 统一入口 ```javascript async function getTrendingVideos(options) { const { useApi = true, apiKey, ...rest } = options; if (useApi && apiKey) { try { return await getTrendingVideosAPI({ ...rest, apiKey }); } catch (error) { console.warn('API failed, falling back to yt-dlp:', error.message); } } return await getTrendingVideosYTDLP(rest); } ``` ## 错误处理 | 错误码 | 场景 | 处理策略 | |--------|------|----------| | 400 | 请求参数错误 | 返回 validation error | | 401/403 | API Key 无效 | 自动降级到 yt-dlp | | 429 | 配额超限 | 自动降级到 yt-dlp | | 500+ | 服务器错误 | 重试 3 次后降级 | | timeout | 请求超时 | 切换方案重试 | ## 配置示例 ```json { "youtube-crawler": { "apiKey": "${YOUTUBE_API_KEY}", "defaultRegion": "US", "maxResults": 10, "cacheMinutes": 15 } } ``` ## 依赖 - Node.js ≥ 16 - yt-dlp (可选,用于降级方案) - YOUTUBE_API_KEY 环境变量 (可选) ## 评分历史 | 版本 | 分数 | 日期 | 主要改进 | |------|------|------|----------| | v1.0 | TBD | 2026-04-01 | 初始版本 |