# Skill: YouTube 热门视频爬虫 ## 基本信息 - **ID**: youtube-crawler - **类型**: data-collection - **版本**: 1.0.0 - **状态**: production-ready - **目标分数**: 95/100 ✅ ## 功能描述 从 YouTube 获取当日最热门视频列表,支持 YouTube Data API v3 和 yt-dlp 降级方案。提供多地区批量获取、JSON/CSV 导出、配额管理等功能。 ## 使用方法 ```javascript 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) 获取单个地区的热门视频。 ```javascript const videos = await crawler.get_trending('US', 10, '10'); // 返回: [{ videoId, url, title, channelTitle, viewCount, ... }] ``` ### get_multi_region_trending(regionCodes, maxResultsPerRegion, videoCategoryId) 批量获取多地区热门视频。 ```javascript 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 文件。 ## 配置选项 ```javascript 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 | 速率限制 | 指数退避重试,再失败则降级 | ## 环境变量 ```bash 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`