YouTube 转录工具 (YouTube Transcript)

从 YouTube 视频下载转录稿（字幕/隐藏式字幕）。适用于手动创建和自动生成的转录稿。无需 API 密钥或浏览器——直接使用 YouTube 的 InnerTube API。

首次运行时获取视频元数据和封面图像，并缓存原始数据以便快速重新格式化。

脚本目录 (Script Directory)

脚本位于 scripts/ 子目录中。{baseDir} = 此 SKILL.md 文件的目录路径。解析 ${BUN_X} 运行时：如果安装了 bun → bun；如果 npx 可用 → npx -y bun；否则建议安装 bun。将 {baseDir} 和 ${BUN_X} 替换为实际值。

用法 (Usage)

# 默认：带时间戳的 Markdown（英语）(Default: markdown with timestamps - English)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# 指定语言（优先级顺序）(Specify languages - priority order)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# 无时间戳 (Without timestamps)
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# 带章节分割 (With chapter segmentation)
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# 带说话人识别（需要 AI 后处理）(With speaker identification - requires AI post-processing)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT 字幕文件 (SRT subtitle file)
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# 翻译转录稿 (Translate transcript)
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# 列出可用转录稿 (List available transcripts)
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# 强制重新获取（忽略缓存）(Force re-fetch - ignore cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

选项 (Options)

输入格式 (Input Formats)

接受以下任何形式作为视频输入：

• 完整 URL：https://www.youtube.com/watch?v=dQw4w9WgXcQ
• 短 URL：https://youtu.be/dQw4w9WgXcQ
• 嵌入 URL：https://www.youtube.com/embed/dQw4w9WgXcQ
• Shorts URL：https://www.youtube.com/shorts/dQw4w9WgXcQ
• 视频 ID：dQw4w9WgXcQ

输出格式 (Output Formats)

输出目录 (Output Directory)

youtube-transcript/
├── .index.json                          # 视频 ID → 目录路径映射（用于缓存查找）(Video ID → directory path mapping - for cache lookup)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # 视频元数据（标题、频道、描述、时长、章节等）(Video metadata - title, channel, description, duration, chapters, etc.)
    ├── transcript-raw.json              # 来自 YouTube API 的原始转录稿片段（已缓存）(Raw transcript snippets from YouTube API - cached)
    ├── transcript-sentences.json        # 句子分段的转录稿（按标点分割，合并跨片段）(Sentence-segmented transcript - split by punctuation, merged across snippets)
    ├── imgs/
    │   └── cover.jpg                    # 视频缩略图 (Video thumbnail)
    ├── transcript.md                    # Markdown 转录稿（由句子生成）(Markdown transcript - generated from sentences)
    └── transcript.srt                   # SRT 字幕（由原始片段生成，如果使用 --format srt）(SRT subtitle - generated from raw snippets, if --format srt)

• {channel-slug}：频道名称，短横线命名法 (Channel name in kebab-case)
• {title-full-slug}：完整视频标题，短横线命名法 (Full video title in kebab-case)

--list 模式仅输出到标准输出（不保存文件）。

缓存 (Caching)

首次获取时，脚本保存：

• meta.json — 视频元数据、章节、封面图像路径、语言信息 (video metadata, chapters, cover image path, language info)
• transcript-raw.json — 来自 YouTube API 的原始转录稿片段（{ text, start, duration }[]）(raw transcript snippets from YouTube API – { text, start, duration }[])
• transcript-sentences.json — 句子分段的转录稿（{ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]），按句子结束标点（.?!…。？！ 等）分割，时间戳按字符长度比例分配，支持 CJK 文本合并 (sentence-segmented transcript – { text, start: "HH:mm:ss", end: "HH:mm:ss" }[], split by sentence-ending punctuation (.?!…。？！ etc.), timestamps proportionally allocated by character length, CJK-aware text merging)
• imgs/cover.jpg — 视频缩略图 (video thumbnail)

同一视频的后续运行使用缓存数据（无网络调用）。使用 --refresh 强制重新获取。如果请求不同的语言，缓存会自动刷新。

SRT 输出（--format srt）从 transcript-raw.json 生成。文本/Markdown 输出使用 transcript-sentences.json 以获得自然的句子边界。

工作流 (Workflow)

当用户提供 YouTube URL 并希望获取转录稿时：

1. 如果用户未指定语言，首先使用 --list 运行，以显示可用选项
2. 默认：使用 --chapters --speakers 运行，以获得最丰富的输出（章节 + 说话人识别）
3. 脚本自动保存缓存数据 + 输出文件，并打印文件路径
4. 对于 --speakers 模式：脚本保存原始文件后，按照下面的说话人识别工作流进行后处理，添加说话人标签

当用户只需要封面图像或元数据时，使用任何选项运行脚本也会缓存 meta.json 和 imgs/cover.jpg。

当重新格式化同一视频时（例如，先文本后 SRT），缓存数据被重用——无需重新获取。

章节与说话人工作流 (Chapter & Speaker Workflow)

章节 (--chapters)

脚本从视频描述中解析章节时间戳（例如 0:00 介绍 (Introduction)），按章节边界分割转录稿，将片段分组为可读段落，并保存为带目录的 .md 文件。无需进一步处理。

如果描述中没有章节时间戳，转录稿将输出为分组段落，不带章节标题。

说话人识别 (--speakers)

说话人识别需要 AI 处理。脚本输出一个原始的 .md 文件，包含：

• 包含视频元数据的 YAML 前置元数据（标题、频道、日期、封面、语言）(YAML frontmatter with video metadata – title, channel, date, cover, language)
• 视频描述（用于提取说话人姓名）(Video description – for speaker name extraction)
• 来自描述的章节列表（如果可用）(Chapter list from description – if available)
• SRT 格式的原始转录稿（预计算开始/结束时间戳，令牌高效）(Raw transcript in SRT format – pre-computed start/end timestamps, token-efficient)

脚本保存原始文件后，生成一个子智能体（使用更便宜的模型如 Sonnet 以提高成本效率）来处理说话人识别：

1. 读取已保存的 .md 文件
2. 读取 {baseDir}/prompts/speaker-transcript.md 中的提示模板
3. 按照提示处理原始转录稿：
   • 使用视频元数据识别说话人（标题 → 嘉宾，频道 → 主持人，描述 → 姓名）(Identify speakers using video metadata – title → guest, channel → host, description → names)
   • 从对话流、问答模式及上下文线索检测说话人轮次 (Detect speaker turns from conversation flow, question-answer patterns, and contextual cues)
   • 分割成章节（使用描述中的章节，否则根据主题变化创建）(Segment into chapters – use description chapters if available, else create from topic shifts)
   • 使用 **说话人姓名：** 标签格式化，段落分组（2-4 句），以及 [HH:MM:SS → HH:MM:SS] 时间戳 (Format with **Speaker Name:** labels, paragraph grouping – 2-4 sentences, and [HH:MM:SS → HH:MM:SS] timestamps)
4. 用处理后的转录稿覆盖 .md 文件（保留 YAML 前置元数据）(Overwrite the .md file with the processed transcript – keep the YAML frontmatter)

当使用 --speakers 时，--chapters 是隐含的——处理后的输出始终包含章节分割。

错误情况 (Error Cases)