YouTube Analytics

# YouTube Analytics Toolkit

## 设置

安装依赖：

```bash cd scripts && npm install ```

通过在项目根目录中创建 `.env` 文件来配置凭据：

``` YOUTUBE_API_KEY=AIzaSy...your-api-key YOUTUBE_DEFAULT_MAX_RESULTS=50 ```

**前提条件**：一个已启用 YouTube Data API v3 的 Google Cloud 项目。从 [Google Cloud Console](https://console.cloud.google.com/apis/credentials) 获取您的 API 密钥。

## 快速开始

| 用户说 | 调用的函数 | |-----------|-----------------| | "分析这个 YouTube 频道" | `analyzeChannel(channelId)` | | "比较这两个频道" | `compareChannels([id1, id2])` | | "这个视频的表现如何？" | `analyzeVideo(videoId)` | | "在 YouTube 上搜索 [主题]" | `searchAndAnalyze(query)` | | "获取这个频道的统计数据" | `getChannelStats(channelId)` | | "获取这个视频的观看次数" | `getVideoStats(videoId)` | | "查找关于 [主题] 的频道" | `searchChannels(query)` | | "显示该频道的最新上传" | `getChannelVideos(channelId)` |

通过从 `scripts/src/index.ts` 导入来执行函数：

```typescript import { analyzeChannel, searchAndAnalyze } from './scripts/src/index.js';

const analysis = await analyzeChannel('UCxxxxxxxx'); ```

或直接使用 tsx 运行：

```bash npx tsx scripts/src/index.ts ```

## 工作流模式

每次分析都遵循三个阶段：

### 1. 分析

运行 API 函数。每次调用都会访问 YouTube Data API 并返回结构化数据。

### 2. 自动保存

所有结果都会自动作为 JSON 文件保存到 `results/{category}/`。文件命名模式： - 命名结果：`{sanitized_name}.json` - 自动生成：`YYYYMMDD_HHMMSS__{operation}.json`

### 3. 汇总

分析完成后，读取保存的 JSON 文件并在 `results/summaries/` 中创建包含数据表格、比较和见解的 markdown 汇总。

## 高级函数

| 函数 | 用途 | 获取内容 | |----------|---------|----------------| | `analyzeChannel(channelId)` | 完整的频道分析 | 频道信息、最新视频、每个视频的平均观看量 | | `compareChannels(channelIds)` | 比较多个频道 | 并排比较订阅者、观看量、视频数量 | | `analyzeVideo(videoId)` | 视频表现分析 | 观看量、点赞数、评论数、点赞率、评论率 | | `searchAndAnalyze(query, maxResults?)` | 搜索 + 统计 | 带有完整视频统计数据的搜索结果 |

## 独立 API 函数

为了进行精细控制，请从 API 模块导入特定函数。请参阅 [references/api-reference.md](references/api-reference.md) 获取包含参数、类型和示例的 13 个 API 函数的完整列表。

### 频道函数

| 函数 | 用途 | |----------|---------| | `getChannel(channelId)` | 获取完整的频道详情 | | `getChannelStats(channelId)` | 获取简化的统计数据（订阅者、观看量、视频数量） | | `getMultipleChannels(channelIds)` | 批量获取多个频道 |

### 视频函数

| 函数 | 用途 | |----------|---------| | `getVideo(videoId)` | 获取完整的视频详情 | | `getVideoStats(videoId)` | 获取简化的统计数据（观看量、点赞数、评论数） | | `getMultipleVideos(videoIds)` | 批量获取多个视频 | | `getChannelVideos(channelId)` | 获取频道的最新上传 |

### 搜索函数

| 函数 | 用途 | |----------|---------| | `searchVideos(query, options?)` | 搜索视频 | | `searchChannels(query, options?)` | 搜索频道 |

## 结果存储

结果会自动保存到 `results/`，结构如下：

``` results/ ├── channels/ # Channel data and comparisons ├── videos/ # Video data and analyses ├── search/ # Search results └── summaries/ # Human-readable markdown summaries ```

### 管理结果

```typescript import { listResults, loadResult, getLatestResult } from './scripts/src/index.js';

// List recent results const files = listResults('channels', 10);

// Load a specific result const data = loadResult(files[0]);

// Get most recent result for an operation const latest = getLatestResult('channels', 'channel_analysis'); ```

## 提示

1. **使用频道 ID** — 频道 ID 以 `UC` 开头（例如 `UCxxxxxxxx`）。您可以在频道 URL 或页面源代码中找到它们。 2. **请求汇总** — 拉取数据后，请求一份包含表格和见解的 markdown 汇总。 3. **比较频道** — 使用 `compareChannels()` 并排对标竞争对手。 4. **批量请求** — 使用 `getMultipleChannels()` 或 `getMultipleVideos()` 进行高效的批量查找。 5. **搜索 + 分析** — `searchAndAnalyze()` 在一次调用中结合了搜索和完整的视频统计数据。