youtube-to-markdown

YouTube 转 Markdown

多个视频：每次处理一个视频，按顺序进行。不要并行提取。 按顺序执行所有步骤，无需征求用户同意。使用 TodoWrite 跟踪进度。

步骤 0：检查是否已提取

python3 ./check_existing.py "<YOUTUBE_URL>" "<output_directory>"

完整性检查：

• 如果 summary_valid: false：向用户显示问题，并询问“文件不完整：[issues]。是否重新处理？”。如果是，则继续执行步骤 1。
• 如果 transcript_valid: false：询问用户；如果用户同意，则重新运行步骤 2–3、7–9。
• 如果 comments_valid: false：询问用户；如果用户同意，则重新运行评论分析。

如果返回 exists: true 且所有有效性字段均为 true：读取并遵循 UPDATE_MODE.md 中的更新工作流。

步骤 1：提取数据（元数据、描述、章节）

python3 extract_data.py "<YOUTUBE_URL>" "<output_directory>"

创建：youtube_{VIDEO_ID}metadata.md、youtube{VIDEO_ID}description.md、youtube{VIDEO_ID}_chapters.json

重要：如果你询问要提取哪种语言的转录文本，请勿将其翻译成英语，并要求子 Agent 也不要翻译。只有在用户要求使用不同于原文的语言时，才进行翻译。

步骤 2：提取转录文本

首选方法（如果有转录文本）

如果视频语言为 en，则直接继续。如果是非英语，请询问用户要下载哪种语言的版本。

python3 extract_transcript.py "<YOUTUBE_URL>" "<output_directory>" "<LANG_CODE>"

创建：youtube_{VIDEO_ID}_transcript.vtt

重要：所有文件输出必须使用步骤 2 中识别出的语言。如果语言不是英语，请明确指示所有子 Agent 保留原语言。

如果视频设为私有、受年龄限制或有地区限制，下载可能会失败。

后备方法（仅当无法获取转录文本时）

询问用户：“没有可用的转录文本。是否使用 Whisper 转录？

• Mac/Apple Silicon：如果已安装，则使用 MLX Whisper（速度更快，参见 SETUP_MLX_WHISPER.md）
• 所有平台：回退到 OpenAI Whisper（需要：brew install openai-whisper 或 pip3 install openai-whisper）”

python3 extract_transcript_whisper.py "<YOUTUBE_URL>" "<output_directory>"

脚本会在 Mac 上自动检测 MLX Whisper，并在可用时使用；否则使用 OpenAI Whisper。

步骤 3：去除转录文本中的重复内容

根据步骤 1 的输出设置 BASE_NAME（youtube_{VIDEO_ID}）

python3 ./deduplicate_vtt.py "<output_directory>/${BASE_NAME}_transcript.vtt" "<output_directory>/${BASE_NAME}_transcript_dedup.md" "<output_directory>/${BASE_NAME}_transcript_no_timestamps.txt"

步骤 4：添加自然段落分隔

与步骤 5 并行执行。

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_transcript_no_timestamps.txt
CHAPTERS: <output_directory>/${BASE_NAME}_chapters.json
OUTPUT: <output_directory>/${BASE_NAME}_transcript_paragraphs.txt

Analyze INPUT and identify natural paragraph break line numbers.

Read CHAPTERS. If it contains chapters, use chapter timestamps as primary break points.

Target ~500 chars per paragraph. Find natural break points at topic shifts or sentence endings.

Write to OUTPUT in format:
15,42,78,103,...

python3 ./apply_paragraph_breaks.py "<output_directory>/${BASE_NAME}_transcript_dedup.md" "<output_directory>/${BASE_NAME}_transcript_paragraphs.txt" "<output_directory>/${BASE_NAME}_transcript_paragraphs.md"

步骤 5：总结转录文本

与步骤 4 并行执行。

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_transcript_no_timestamps.txt
OUTPUT: <output_directory>/${BASE_NAME}_summary.md
FORMATS: ./summary_formats.md

1. Classify content type:
   - TIPS: gear reviews, rankings, "X ways to...", practical advice lists
   - INTERVIEW: podcasts, conversations, Q&A, multiple perspectives
   - EDUCATIONAL: concept explanations, analysis, "how X works"
   - TUTORIAL: step-by-step instructions, coding, recipes

2. Analyze content structure:
   - Identify meaningful content units (topic shifts, argument structure, narrative breaks)
   - If single continuous topic, omit content unit headers
   - Skip ads, sponsors, self-promotion ("like and subscribe", merch, etc.)
   - Merge content spanning ad breaks if thematically connected

3. Read FORMATS file and use format for detected content type. Target <10% of transcript bytes.


ACTION REQUIRED: Use the Write tool NOW to save output to OUTPUT file. Do not ask for confirmation.

步骤 6：审阅并精简摘要

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_summary.md
OUTPUT: <output_directory>/${BASE_NAME}_summary_tight.md
FORMATS: ./summary_formats.md

You are an adversarial copy editor. Cut fluff, enforce quality.

Rules:
- Read FORMATS - the format has been selected based on the content type - preserve format and do not count a reason to squeeze more from budget.
- Byte budget: <10% of transcript bytes
- Hidden Gems: Remove if duplicates main content
- Tightness: Cut filler words, compress verbose explanations, prefer lists over prose

Preserve original language - do not translate.

ACTION REQUIRED: Use the Write tool NOW to save output to OUTPUT file. Do not ask for confirmation.

步骤 7：清理语音转录瑕疵

task_tool:

• subagent_type: "general-purpose"
• model: "haiku"
• prompt:

Read <output_directory>/${BASE_NAME}_transcript_paragraphs.md and clean speech artifacts.

Tasks:
- Remove fillers (um, uh, like, you know)
- Fix transcription errors
- Add proper punctuation
- Reduce or add implicit words to improve flow
- Preserve natural voice and tone
- Keep timestamps at end of paragraphs

ACTION REQUIRED: Use the Write tool NOW to save output to <output_directory>/${BASE_NAME}_transcript_cleaned.md. Do not ask for confirmation.

步骤 8：添加主题标题

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_transcript_cleaned.md
OUTPUT: <output_directory>/${BASE_NAME}_transcript.md

Read the INPUT file. Add markdown headings.

Read <output_directory>/${BASE_NAME}_chapters.json:
- If contains chapters: Use chapter names as ### headings at chapter timestamps, add #### headings for subtopics
- If empty: Add ### headings where major topics change

ACTION REQUIRED: Use the Write tool NOW to save output to OUTPUT file. Do not ask for confirmation.

步骤 9：创建输出文件

python3 finalize.py "${BASE_NAME}" "<output_directory>"

脚本使用模板创建两个最终文件：包含元数据和摘要的摘要文件，以及包含描述和转录文本的转录文件。删除中间工作文件。

输出：

• youtube - {title} ({video_id}).md - 主要摘要
• youtube - {title} - transcript ({video_id}).md - 描述和转录文本

使用 --debug 标志可保留中间工作文件以供检查。

步骤 10：评论分析

如果 youtube-comment-analysis 技能可用，则使用相同的 YouTube URL 和输出目录运行。