用途：面向内容策略，帮你发现某细分领域正在起量的视频、扫描竞品频道、按热度排名并拉取字幕做分析，可与 Instagram、X 的同类雷达配合使用。
主要能力与用法： 1）主题搜索与排名（默认无需 Key）：python3 scripts/yt_search.py "<query>" --limit 15 按播放量排名；加 --by velocity 按播放增速（播放量/上传天数）排名，更适合发现正在上升的新视频，该选项会自动启用 --enrich；--enrich 补充上传日期、点赞、评论、频道订阅数；--json 输出结构化 JSON 供后续处理。 2）扫描竞品频道：python3 scripts/yt_search.py --handles "channelA,channelB" --limit 10 --by velocity --enrich，拉取各频道最新视频并排名，handle 可带或不带 @。 3）频道基线：在 references/watchlist.json 维护长期跟踪的频道（随附模板），可一次性对该列表整体运行雷达；新增频道可用 yt-dlp 将视频/链接解析出频道信息后追加到 channels[]。 4）视频字幕：bash scripts/yt_transcript.sh "<youtube_url|id>" [text|json]，走 TranscriptAPI.com v2（付费，注册送 100 免费额度），需设置 TRANSCRIPT_API_KEY，或把 Key 放到 ~/.claude/skills/yt-research/secrets/transcript-api-key。返回纯文本加元数据，每次成功计 1 额度；401 为 Key 错误，402 为额度不足，404 为视频无字幕。 5）可选官方路径：--api 使用 YouTube Data API v3，读取环境变量 YOUTUBE_API_KEY，需在 Google Cloud 启用该 API 并创建 Key，每日免费配额 10,000 单位。
输出与解读：默认输出编号列表，包含播放量、每日增速、时长、标题、频道与链接；--json 输出对象数组。新视频高增速代表话题正在上升，老视频高绝对播放量属常青内容，可对比优胜者的格式、标题与长度，并用字幕提取结构与要点。
限制：yt-dlp 仅能访问公开数据，无法获取他人频道的私密分析；--enrich 与 --by velocity 会逐视频请求，列表大时较慢，建议分批运行；自己频道的私密数据需 OAuth（YouTube Analytics API），属另一套配置。