名称： youtube-analytics
描述： "YouTube Data API v3 数据分析工具包。用于分析 YouTube 频道、视频和搜索结果。当用户要求：查看频道数据、分析视频表现、对比频道、搜索视频、获取订阅数、查看互动指标、查找热门视频、获取频道上传内容或分析 YouTube 竞争对手时使用。需要从 Google Cloud Console 获取 YouTube Data API v3 密钥。"

YouTube 数据分析工具包

环境配置

安装依赖：

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 获取您的 API 密钥。

快速开始

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

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

const analysis = await analyzeChannel('UCxxxxxxxx');

或者直接使用 tsx 运行：

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 总结报告。

高级功能函数

独立 API 函数

如需精细控制，可从 API 模块导入特定函数。完整列表（共 13 个函数）及其参数、类型和示例，请参阅 references/api-reference.md。

频道相关函数

视频相关函数

搜索相关函数

结果存储

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

results/
├── channels/       # 频道数据与对比
├── videos/         # 视频数据与分析
├── search/         # 搜索结果
└── summaries/      # 人类可读的 Markdown 总结报告

管理结果

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

// 列出最近的结果
const files = listResults('channels', 10);

// 加载特定结果
const data = loadResult(files[0]);

// 获取某个操作的最新结果
const latest = getLatestResult('channels', 'channel_analysis');

使用技巧

1. 使用频道 ID — 频道 ID 以 UC 开头（例如 UCxxxxxxxx）。您可以在频道 URL 或页面源代码中找到它。
2. 请求总结报告 — 拉取数据后，可以要求生成包含表格和洞察的 Markdown 总结报告。
3. 对比频道 — 使用 compareChannels() 将竞争对手进行并列对比。
4. 批量请求 — 使用 getMultipleChannels() 或 getMultipleVideos() 进行高效的批量查询。
5. 搜索并分析 — searchAndAnalyze() 将搜索与完整的视频统计分析结合在一次调用中完成。