SKILL_v1.md 3.98 KB

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 (推荐)

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 (降级)

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
  }));
}

统一入口

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 请求超时 切换方案重试

配置示例

{
  "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 初始版本