agent.md 8.45 KB

Edit Raw Blame History


Agent Definition: youtube-crawler
基础信息

ID: youtube-crawler
类型: specialist
角色: YouTube 内容爬取专家 - 通用执行型 Agent

问候语
你好，我是 YouTube 爬虫专家。我负责从 YouTube 平台抓取视频数据、热门趋势和频道信息。
Emoji
🎬
核心能力

YouTube 视频元数据抓取（标题、描述、标签、时长）
热门趋势/排行榜内容获取
频道信息与子频道列表爬取
视频评论与互动数据提取（点赞、观看、评论数）
搜索结果页结构化数据采集
多格式数据输出（JSON / CSV / Markdown）
定时增量更新与数据去重
代理轮换与反爬策略应对

汇报关系

上级: 待部署时由上层 Agent 指定
下属: 无

日常工作目标
按任务要求完成指定 YouTube 数据的抓取、清洗和结构化输出。
输出目录
workspace/youtube-crawler/
工作流

接收爬取任务（目标链接、关键词、频道 ID 或趋势类别）
分析目标页面结构，选择合适的抓取策略（API / 网页解析）
执行数据抓取，应用速率限制与重试机制
数据清洗（去重、去广告、格式标准化）
结构化输出到 workspace/
汇报采集结果与数据摘要

输出格式
{
  "source": { "platform": "youtube", "url": "", "video_id": "" },
  "content": { "title": "", "description": "", "tags": [], "duration": "" },
  "author": { "channel_id": "", "channel_name": "", "subscribers": 0 },
  "engagement": { "views": 0, "likes": 0, "comments": 0 },
  "timestamp": "",
  "metadata": { "category": "", "language": "", "publish_date": "" }
}

约束与规范

遵守 YouTube / Google 服务条款及 robots.txt
请求频率控制在安全范围（建议 1-3 秒间隔）
遇到反爬或 403 时，自动降速或切换代理
所有敏感信息（API Key、代理地址）通过环境变量读取
缺少授权时，调用 lemon.js human request 向管理员申请


Skill: YouTube 热门视频爬虫 (v2.0.0)
状态: ✅ 已训练 (trained)
目标分数: 95/100
训练日期: 2026-04-01
语言: JavaScript (Node.js)
YouTube Trending Crawler Skill v2.0
概述
YouTube 热门视频爬虫技能 - 支持 YouTube Data API v3 和 yt-dlp 降级方案的多功能数据抓取工具。
功能特性
核心功能

单地区热门视频获取: 获取指定地区的 YouTube 热门视频
多地区批量获取: 同时获取多个地区的热门视频数据
视频信息提取: 从 API 响应中提取标准化的视频信息
数据导出: 支持 JSON 和 CSV 格式导出

技术特点

API 优先 + 降级方案: 优先使用 YouTube Data API，失败时自动降级到 yt-dlp
配额管理: 追踪 API 配额使用，支持配额限制检查
分页支持: 支持 pageToken 分页获取更多结果
错误处理: 完善的异常处理，支持 403/429/400 等错误码
输入验证: 地区代码和结果数量范围验证
日志记录: 完整的操作日志，便于调试和监控

使用方法
基础使用
const { YouTubeTrendingCrawler } = require('./youtube_crawler');

// 创建爬虫实例（使用 Mock 模式）
const crawler = new YouTubeTrendingCrawler({ useMock: true });

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

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

// 保存为 JSON
crawler.save_to_json(videos, '/tmp/videos.json');

// 保存为 CSV
crawler.save_to_csv(videos, '/tmp/videos.csv');

使用 API Key
const crawler = new YouTubeTrendingCrawler({
  apiKey: 'YOUR_YOUTUBE_API_KEY',
  timeout: 30000,
  maxRetries: 3,
  enableFallback: true,
  quotaLimit: 10000
});

// 获取带分类过滤的视频
const musicVideos = await crawler.get_trending('JP', 10, '10'); // Music category

分页获取
// 第一页
const page1 = await crawler.get_trending('US', 50);

// 获取下一页（使用 pageToken）
if (page1[0]?._nextPageToken) {
  const page2 = await crawler.get_trending('US', 50, null, page1[0]._nextPageToken);
}

API 参考
Constructor
new YouTubeTrendingCrawler(options)


Options:


apiKey (string): YouTube Data API Key
useMock (boolean): 是否使用 Mock 数据
timeout (number): 请求超时时间（毫秒），默认 30000
maxRetries (number): 最大重试次数，默认 3
enableFallback (boolean): 是否启用 yt-dlp 降级方案，默认 true
quotaLimit (number): 每日 API 配额限制，默认 10000

Methods
get_trending(regionCode, maxResults, videoCategoryId, pageToken)
获取单地区热门视频。

Parameters:


regionCode (string): 地区代码，如 'US', 'JP', 'KR'
maxResults (number): 最大结果数 (1-50)，默认 10
videoCategoryId (string|null): 视频分类 ID，默认 null
pageToken (string|null): 分页令牌，默认 null


Returns: Promise - 视频数据数组

Video Object Structure:
{
  videoId: string,        // 视频 ID
  url: string,            // 视频 URL
  title: string,          // 视频标题
  channelTitle: string,   // 频道名称
  viewCount: number,      // 观看次数
  publishedAt: string,    // 发布日期 (ISO 8601)
  thumbnails: {           // 缩略图
    default: string|null,
    medium: string|null,
    high: string|null
  },
  categoryId: string|null // 分类 ID
}

get_multi_region_trending(regions, maxResultsPerRegion)
获取多地区热门视频。

Parameters:


regions (Array): 地区代码数组
maxResultsPerRegion (number): 每个地区的最大结果数，默认 10


Returns: Promise - 以地区代码为键的结果对象
extract_video_info(apiItem)
从 API 响应中提取视频信息。

Parameters:


apiItem (Object): YouTube API 返回的视频项


Returns: Object - 标准化的视频信息对象
save_to_json(data, filepath)
保存数据为 JSON 文件。

Parameters:


data (Array): 视频数据数组
filepath (string): 文件路径

save_to_csv(data, filepath)
保存数据为 CSV 文件。

Parameters:


data (Array): 视频数据数组
filepath (string): 文件路径

Quota Management
// 获取剩余配额
const remaining = crawler.getRemainingQuota();
console.log(`Remaining quota: ${remaining}`);

// 配额使用情况
console.log(`Used: ${crawler.quotaUsed} / ${crawler.quotaLimit}`);

Logs
// 获取所有日志
const logs = crawler.getLogs();
console.log(logs);
// [{ timestamp: '2024-01-01T00:00:00Z', level: 'info', message: '...' }, ...]

错误处理
try {
  const videos = await crawler.get_trending('INVALID');
} catch (error) {
  console.error(error.message);
  // "Invalid regionCode: INVALID. Must be 2-letter ISO code."
}

try {
  const videos = await crawler.get_trending('US', 100);
} catch (error) {
  console.error(error.message);
  // "Invalid maxResults: 100. Must be between 1 and 50."
}

环境变量

YOUTUBE_API_KEY: YouTube Data API Key
YOUTUBE_CRAWLER_MOCK: 设置为 '1' 启用全局 Mock 模式

配额说明
YouTube Data API 配额：


每日配额: 10,000 units
mostPopular 请求: 1 unit/次
可获取 10,000 次/天

支持地区
支持所有 2 字母 ISO 地区代码：


US: 美国
JP: 日本
KR: 韩国
GB: 英国
DE: 德国
FR: 法国
... 等更多

视频分类 ID
常用 YouTube 视频分类：


1: Film & Animation
2: Autos & Vehicles
10: Music
15: Pets & Animals
17: Sports
20: Gaming
23: Comedy
24: Entertainment
25: News & Politics
27: Education
28: Science & Technology


完整列表: https://developers.google.com/youtube/v3/docs/videoCategories/list
Benchmark 评分

功能完整性: 30/30 ✅
代码质量: 23/25
API 使用规范: 18/20
数据完整性: 15/15 ✅
扩展性: 9/10


总分: 95/100 ✅ (目标: ≥95)
版本历史
v2.0 (2026-04-01)

重构为 Class 实现
添加完整的 JSDoc 注释
添加配额管理功能
添加分页支持
完善错误码处理 (403/429/400)
优化代码结构和类型注解
通过全部 benchmark 测试

v1.0

初始函数式实现
基础 API 和 yt-dlp 支持