search-youtube

YouTube 研究

多平台视频研究工具包。提供两种模式：工具包（单项操作）和研究（自主搜索到综合的流水线）。所有操作都通过单个 CLI 执行： ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py。

运行 python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py <subcommand> --help 可查看任何子命令的完整参数说明。

工具包模式

调用单个子命令以执行特定操作。当用户请求某项具体操作（字幕、搜索、元数据、音频、频道扫描）时，默认使用此模式。

搜索

查找符合查询条件的视频。返回包含元数据的结构化结果。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py search "<query>" --count 10

添加筛选条件以缩小结果范围：--min-duration 600（秒）、--after 20250101（YYYYMMDD）、 --min-views 50000。筛选会在获取结果后于客户端执行，因此工具会自动多获取一些结果作为补偿。默认输出为 JSON；添加 -f text 可获得便于阅读的文本。

字幕

下载并清理字幕，生成适合大模型处理的文本。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript "<url>"

默认将清理后的正文输出到 stdout。添加 --timestamps 可生成带时间提示的 SRT。 添加 --save -t <topic> 可将内容保存到 ~/youtube-research/<topic>/。使用 --lang all 可在下载前列出可用字幕语言。回退顺序：人工字幕，然后是自动生成字幕。若请求的语言没有字幕，则退出码为 4。

元数据

提取完整视频信息，不下载视频。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py metadata "<url>"

返回：标题、说明、频道、时长、章节、观看/点赞次数、标签、可用字幕语言、缩略图 URL。添加 --playlist 可列出播放列表中的条目。

音频

以指定格式下载音频。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py audio "<url>" --audio-format mp3 -t <topic>

保存到 ~/youtube-research/<topic>/audio/。支持的格式：mp3、m4a、opus、wav。 始终保存到磁盘（音频不能输出到 stdout）。成功时会打印文件路径。

频道

扫描频道内容。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py channel "<url-or-@handle>" --limit 20

支持的标签页：--tab videos（默认）、shorts、streams、playlists。使用 --after/--before（YYYYMMDD）筛选。使用 --sort views 可按观看次数从高到低排序。

批量处理

除 search 外，任何子命令都可接受 --batch <file>（或使用 --batch - 从 stdin 读取）以处理多个 URL。每行一个 URL；以 # 或 ; 开头的行会被跳过。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript --batch urls.txt --save -t <topic>

研究模式

当用户要求使用 YouTube 作为信息来源来“研究”“调查”或“了解”某个主题时，启用此模式。这是一条自适应的多轮发现流水线，专为小众和新兴主题设计，因为热门视频往往无法充分覆盖这类主题。

第 1 轮：发散式搜索

生成 4-6 个查询变体，覆盖该主题的不同角度：

• 工具/概念的确切名称（例如，"openclaw"）
• 工具 + 生态系统背景（例如，"openclaw claude code"）
• 工具要解决的问题（例如，"claude code documentation framework"）
• 工作流/演示角度（例如，"openclaw walkthrough demo"）
• 适用时，使用替代名称、缩写或常见拼写错误

为每个查询变体同时启动一个 Task Agent，分别运行：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py search "<query-variant>" --count 15

收集所有结果，并按视频 ID 去重。目标是在所有线程中获得 30-50 个不重复的候选视频。

第 1 轮评估：优先关注小众领域的启发式标准

对于小众、新兴或处于技术前沿的话题，以下信号可以预测内容质量：

正向信号（采用这些标准）：

• 标题明确提及工具或概念（而不是“2025 年顶级 AI 工具”）
• 频道规模较小（订阅人数 < 50K）——对于新技术，实践者往往会在教育工作者发现该话题之前发布内容
• 描述具体且技术性强（提及代码、配置、架构或命令）
• 内容结构清晰：包含章节、时间戳或详细描述
• 上传日期较近

负向信号（在小众话题中视为警示信号）：

• 观看次数 > 100K——对于范围狭窄的话题，这通常意味着内容面向初学者或带有标题党性质
• 全新工具的标题中出现“初学者教程”／“完整指南”
• 大型综合类频道覆盖许多互不相关的话题

从合并后的候选池中选出 6-10 个候选项。记录哪些频道的结果最出色——这些频道是第 2 轮的目标。

第 2 轮：发掘频道并优化搜索

对于第 1 轮中出现优质结果的每个频道，浏览其近期视频：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py channel "<channel-url>" --limit 20

还要使用第 1 轮优质结果的标题或描述中出现的具体术语，执行 1-2 次优化后的搜索查询。将任何新候选项加入候选池。

**质量关卡：**如果第 1 轮候选项质量较差（标题泛泛、全是高观看量的综合类内容，或没有专门讨论该话题的内容），请向用户说明情况，并使用重新拟定的查询词再进行一轮搜索，然后再处理文字稿。

第 3 轮：确认并转录

从扩充后的候选池中，按照第 1 轮的标准选出 4-7 个视频。先提取元数据以确认相关性，再开始下载：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py metadata "<url>"

并行下载文字稿——每个视频始终启动一个 Task agent，即使只有 2 个视频也如此：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript "<url>" --save -t <topic>

阅读每份文字稿，并综合研究结果撰写报告。如果 YouTube 来源之间说法不一致或问题仍未得到解答，请使用 WebSearch 或 brave-cli 交叉核实说法或补充信息。

研究报告格式

以结构化的 Markdown 报告呈现综合结果：

• 标题，以及一段概述研究问题的摘要
• 主要发现（3-7 条要点，概述所有来源中最重要的结论）
• 来源之间的共识（多部视频都证实的内容）
• 存在分歧的观点（来源相互矛盾之处，并注明来源）
• 独到见解（个别视频提及、其他来源未重复的要点）
• 覆盖盲区（所有来源共同遗漏的内容）
• 来源表格：所用视频的标题、频道、时长和 URL

将具体说法归属到相应来源视频。如果文字稿保留了时间戳，请一并注明。将所有文字稿保存在对应话题目录下，以供日后参考。报告结构示例请参阅 examples/research-report.md。

研究流程组合

请参阅 references/cli-reference.md，了解使用标准 Unix 工具串联子命令的管道模式（搜索 → jq → 批量获取文字稿）。

错误恢复

退出代码	含义	恢复操作
0	成功	—
1	用法错误	检查 --help 以确认正确语法
2	未找到 yt-dlp	告知用户安装：pip install yt-dlp
3	网络／下载错误	检查 URL 是否有效；对于私有／受限内容，尝试使用 --cookies <browser>
4	没有结果	对于文字稿：尝试使用 --lang all 列出可用语言。对于搜索：扩大查询范围或移除筛选条件

平台说明

处理非 YouTube URL，或 yt-dlp 命令在不熟悉的平台上以退出代码 3 失败时，请加载 references/platforms.md。YouTube 是主要平台，但任何 yt-dlp 支持的 URL 均可使用（Vimeo、Twitter、Twitch 等）。

提取文字稿后，请阅读输出并向用户总结要点，除非用户只要求原始输出。