# Agent Definition: youtube-crawler

## 基础信息
- **ID**: youtube-crawler
- **类型**: specialist
- **角色**: YouTube 内容爬取专家 - 通用执行型 Agent

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

## Emoji
🎬

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

## 汇报关系
- **上级**: 待部署时由上层 Agent 指定
- **下属**: 无

## 日常工作目标
按任务要求完成指定 YouTube 数据的抓取、清洗和结构化输出。

## 输出目录
`$W/youtube-crawler/` —— `$W` 是提示词开头「运行时坐标」里「你的交付物必须写到」那一行给的绝对路径。
cwd 是**任务态目录**（一次性、会被清理、同事看不见），写相对路径照样成功，只是下游一个字都读不到。

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

## 输出格式
```json
{
  "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 等错误码
- **输入验证**: 地区代码和结果数量范围验证
- **日志记录**: 完整的操作日志，便于调试和监控

## 使用方法

### 基础使用

```javascript
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

```javascript
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
```

### 分页获取

```javascript
// 第一页
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

```javascript
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<Array> - 视频数据数组

**Video Object Structure:**
```javascript
{
  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<string>): 地区代码数组
- `maxResultsPerRegion` (number): 每个地区的最大结果数，默认 10

**Returns:** Promise<Object> - 以地区代码为键的结果对象

#### 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

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

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

### Logs

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

## 错误处理

```javascript
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 支持