kirkluokun YouTube 工具
意图路由
| 用户请求 | 模式 | 执行方式 |
|---|---|---|
| 总结视频 / 视频说了什么 | 摘要 | get_transcript.py → Claude 生成结构化摘要 |
| 问视频里的内容 | 问答 | get_transcript.py → 基于字幕回答 |
| 要完整文字稿 / 逐字转录 | 逐字稿 | youtube_transcript.py（Gemini，含说话人标注） |
| 搜索某主题的视频 / 找视频 | 视频搜索 | video_search.py → 选择 → get_transcript.py → 摘要 |
| 追踪频道 / 关注博主 / 检查更新 | 频道追踪 | channel_tracker.py |
| 提纯文字稿 / 整理播客 / 拆解问答 | 文字稿提纯 | refine_transcript.sh（Gemini CLI 结构化提纯） |
模式一：摘要 / 问答
python3 {baseDir}/scripts/get_transcript.py "https://www.youtube.com/watch?v=VIDEO_ID"
- 依赖
yt-dlp - 输出字幕文本后，由 Claude 生成摘要或回答用户问题
- 适合有 CC 字幕或自动生成字幕的视频
摘要格式：
📹 标题 | 👤 频道 | 📅 发布日期
🎯 核心观点：[1-2句]
💡 关键要点：
- ...
🔑 结论：[行动建议]
模式二：逐字稿
# 短视频（≤10分钟）—— 单次调用
python3 {baseDir}/scripts/youtube_transcript.py "https://www.youtube.com/watch?v=VIDEO_ID"
# 长视频 —— 自动分段转录（默认每 10 分钟一段）
# 如果无法自动检测时长，手动指定：
python3 {baseDir}/scripts/youtube_transcript.py "URL" --duration 2:30:45
# 指定输出路径：
python3 {baseDir}/scripts/youtube_transcript.py "URL" --out /path/to/output.txt
# 自定义分段长度（如每 5 分钟一段）：
python3 {baseDir}/scripts/youtube_transcript.py "URL" --duration 1:20:00 --segment-minutes 5
# 禁用分段，强制单次调用（可能截断）：
python3 {baseDir}/scripts/youtube_transcript.py "URL" --no-segment
- 依赖
GEMINI_API_KEY - 自动分段：视频 > 10 分钟时自动分段转录，每段独立调用 Gemini，最后拼接
- 内置速率限制处理和重试机制
- 输出格式：
说话人: 文字，无时间码 - 第一行为视频标题
- 完成后作为附件发送给用户
模式三：视频搜索闭环
当用户想搜索某个主题的视频并获取内容总结时，执行以下闭环流程：
第一步：搜索视频
python3 {baseDir}/scripts/video_search.py -q "搜索关键词" --num 5
# 中文搜索加上语言参数：
python3 {baseDir}/scripts/video_search.py -q "搜索关键词" --gl cn --hl zh --num 5
# 仅返回 YouTube 视频：
python3 {baseDir}/scripts/video_search.py -q "搜索关键词" --youtube-only
依赖 SERPER_API_KEY（在 .env 文件中配置）。返回 JSON 包含视频标题、URL、频道、时长、描述等。
第二步：展示结果供选择
将搜索结果以表格形式展示给用户：
| # | 标题 | 频道 | 时长 | 日期 |
|---|------|------|------|------|
| 1 | ... | ... | ... | ... |
让用户选择需要深入了解的视频，或基于相关性自动选择最佳结果。
第三步：获取文字稿
对选定的 YouTube 视频获取文字稿：
# 优先方式：通过字幕获取（速度快）
python3 {baseDir}/scripts/get_transcript.py "YOUTUBE_URL"
# 如果无字幕：切换到 Gemini 直接转录
python3 {baseDir}/scripts/youtube_transcript.py "YOUTUBE_URL"
第四步：生成摘要
基于获取的文字稿，使用标准摘要格式生成结构化总结。如果搜索了多个视频，合并生成对比分析报告。
多视频对比格式：
📊 主题：[搜索关键词]
📹 分析了 N 个视频
---
🎬 视频 1：[标题] | 👤 [频道]
🎯 核心观点：...
💡 关键要点：...
🎬 视频 2：[标题] | 👤 [频道]
🎯 核心观点：...
💡 关键要点：...
---
🔀 对比分析：
- 共识：...
- 分歧：...
🔑 综合结论：[行动建议]
视频搜索 CLI 参数
| 参数 | 说明 |
|---|---|
-q, --query |
搜索关键词（必需） |
-n, --num |
返回数量（默认 10） |
--gl |
国家代码（如 cn, us），默认 world |
--hl |
语言代码（如 zh, en），默认 en |
--youtube-only |
仅返回 YouTube 链接 |
模式四：频道追踪
追踪重要 YouTube 频道/博主的视频更新。频道数据持久化存储在 data/ 目录。
添加追踪频道
# 通过 @handle 添加
python3 {baseDir}/scripts/channel_tracker.py add "@3blue1brown" --alias "3B1B数学"
# 通过频道 URL 添加
python3 {baseDir}/scripts/channel_tracker.py add "https://www.youtube.com/@lexfridman" --alias "Lex"
# 通过频道 ID 添加
python3 {baseDir}/scripts/channel_tracker.py add "UCxxxxxx"
查看追踪列表
python3 {baseDir}/scripts/channel_tracker.py list
检查更新
# 检查所有频道更新
python3 {baseDir}/scripts/channel_tracker.py check
# 检查指定频道（可通过名称、别名或 URL）
python3 {baseDir}/scripts/channel_tracker.py check "3B1B数学"
python3 {baseDir}/scripts/channel_tracker.py check "@3blue1brown"
# 指定获取数量
python3 {baseDir}/scripts/channel_tracker.py check --count 10
返回 JSON 包含新视频列表。对于新视频可以自动执行摘要 / 文字稿流程。
移除频道
python3 {baseDir}/scripts/channel_tracker.py remove "3B1B数学"
追踪更新 + 摘要闭环
当用户要求"检查频道更新"并总结新内容时：
- 执行
channel_tracker.py check获取新视频列表 - 对每个新视频调用
get_transcript.py获取字幕 - 生成新视频摘要报告
更新报告格式：
📡 频道更新报告 | 📅 检查时间
---
📺 [频道名] — N 个新视频
🆕 1. [标题] (时长)
🎯 核心观点：...
💡 关键要点：...
🆕 2. [标题] (时长)
🎯 核心观点：...
---
📊 总计：检查了 X 个频道，发现 Y 个新视频
模式五：文字稿提纯
通过 Gemini CLI 对原始字幕进行结构化提纯。特别适合播客、讲座、访谈等长内容。
四种提纯子模式
| 子模式 | 适用场景 | 特点 |
|---|---|---|
general |
通用视频 | 去重去噪 + 分段 + 提取要点 |
podcast |
播客/对话 | 按问答拆解，识别主持人/嘉宾，每个议题独立总结 |
lecture |
讲座/教程 | 按知识点分章，提取概念和定义 |
interview |
访谈/采访 | 按话题轮次，标注发言人立场 |
直接从 YouTube URL 提纯（一步到位）
# 播客模式 — 自动获取字幕 + 按问答拆解
bash {baseDir}/scripts/refine_transcript.sh --url "YOUTUBE_URL" --mode podcast
# 讲座模式
bash {baseDir}/scripts/refine_transcript.sh --url "YOUTUBE_URL" --mode lecture
# 访谈模式
bash {baseDir}/scripts/refine_transcript.sh --url "YOUTUBE_URL" --mode interview
从已有文字稿提纯
# 对已保存的文字稿文件提纯
bash {baseDir}/scripts/refine_transcript.sh --input /path/to/raw_transcript.txt --mode podcast
# 指定输出路径和语言
bash {baseDir}/scripts/refine_transcript.sh --input raw.txt --mode podcast --output refined.md --lang zh
提纯 CLI 参数
| 参数 | 说明 |
|---|---|
--input <文件> |
原始文字稿文件路径 |
--url <URL> |
YouTube URL（自动获取字幕后提纯） |
--output <文件> |
输出路径（默认自动命名到 out/ 目录） |
--mode <模式> |
general / podcast / lecture / interview（默认 general） |
--model <模型> |
Gemini 模型（默认 gemini-3-pro-preview） |
--title <标题> |
视频标题（可选，增强提纯效果） |
--lang <语言> |
输出语言：zh / en / auto（默认 auto） |
与搜索/追踪的完整闭环
搜索 → 提纯闭环：
video_search.py搜索视频get_transcript.py获取字幕refine_transcript.sh --input <字幕文件> --mode podcast提纯
追踪 → 提纯闭环：
channel_tracker.py check发现新视频- 对新视频 URL 执行
refine_transcript.sh --url <URL> --mode podcast
备用方案（yt-dlp 失败时）
使用 MCP YouTube Transcript server（需安装于 /root/clawd/mcp-server-youtube-transcript）：
cd /root/clawd/mcp-server-youtube-transcript && node --input-type=module -e "
import { getSubtitles } from './dist/youtube-fetcher.js';
const result = await getSubtitles({ videoID: 'VIDEO_ID', lang: 'en' });
console.log(JSON.stringify(result, null, 2));
" > /tmp/yt-transcript.json
错误处理
- 视频无字幕 → 告知用户，建议使用逐字稿模式（Gemini 可处理无字幕视频）
yt-dlp不可用 → 切换备用方案GEMINI_API_KEY未设置 → 提示用户配置环境变量SERPER_API_KEY未设置 → 视频搜索功能不可用，提示配置- 频道追踪数据文件损坏 → 自动重建空列表
环境变量
| 变量 | 用途 | 必需 |
|---|---|---|
GEMINI_API_KEY |
Gemini 逐字稿转录 | 逐字稿模式必需 |
SERPER_API_KEY |
视频搜索 | 搜索模式必需 |
在技能目录下创建 .env 文件配置：
GEMINI_API_KEY="your-gemini-key"
SERPER_API_KEY="your-serper-key"