YouTube 摘要 是做什么的？
流程：获取转录 -> 阅读全部内容 -> 编写结构化 Markdown 摘要 -> 渲染 PDF。
scripts/fetch_transcript.py 处理第一步，scripts/md_to_pdf.py 处理最后一步。你负责在中间编写摘要。
1. 访问：仅限于用户已经可以观看的内容
- 公开和不公开列出的视频无需登录。始终首先尝试无 cookie 的下载方式。
- 私有或会员专享视频会使脚本退出并显示
NEEDS_SIGNIN。你只能通过从用户的浏览器（该浏览器中 用户的账号已被授予访问权限）读取 cookie 来继续。- 询问用户使用哪个浏览器（以及配置文件，如果他们使用多个），然后传递
--browser。Cookies 代表了他们的凭证。 - 告知用户，yt-dlp 的文档警告，自动化使用已登录账号可能导致其被限速或封禁。对于他们自己的上传内容，使用 YouTube Studio 下载或 Google 导出是零风险的替代方案，脚本也接受由此产生的本地文件。
- 询问用户使用哪个浏览器（以及配置文件，如果他们使用多个），然后传递
- 切勿尝试绕过隐私设置、地区限制、DRM 或付费墙，也绝不使用他人的账号。如果用户的账号无法观看该视频，请说明情况并停止。
- 即使在使用了
--browser的情况下，如果显示“此视频为私有视频”，通常意味着有访问权限的账号不是浏览器默认登录的账号。建议使用--browser chrome:"Profile 2"，或者在一个新的浏览器配置文件中使用该账号登录。
2. 获取转录（分离模式：长视频需要较长时间）
使用持久的工作文件夹，而非会话临时目录（会话临时目录可能在任务进行中被清空）：~/youtube-summaries/<video-id-or-file-stem>/。
以分离模式启动任务，使其在会话结束后仍能继续运行：
OUT=~/youtube-summaries/<id>; mkdir -p "$OUT"
nohup python3 -I ~/.claude/skills/youtube-summary/scripts/fetch_transcript.py "<url-or-file>" \
--out "$OUT" [--browser chrome] [--lang en|auto] [--force-audio] [--audio mp3|m4a|wav] \
> "$OUT/run.log" 2>&1 &!
然后使用后台 Bash until 循环进行等待，而非轮询，例如：
until grep -qE '^(DONE|FAILED|NEEDS_SIGNIN)' "$OUT/status"; do sleep 15; done; cat "$OUT/status"。
脚本的作用：
- 探测元数据，然后使用手动字幕，若没有则回退到自动字幕；
- 若无字幕，则下载音频并在 Apple Silicon 上使用 mlx-whisper large-v3-turbo（其他平台使用 openai-whisper）进行转录。如果没有安装 ffmpeg，它会使用
imageio-ffmpeg获取； - 去除 Whisper 的静默幻听（例如“谢谢你。”）以及自动字幕中的重复内容；
- 将
transcript.txt写为每 2 分钟一段的[h:mm]段落格式，并生成meta.json。
耗时：在配备 8GB 内存的 M 系列 Mac 上，转录时长约为音频时长的 4-5 分钟，外加下载时间。告知用户预期的等待时间，如果他们询问进度，则报告下载百分比或 run.log 中的最后时间戳。
当自动字幕质量较差时（如音乐、口音重、语言错误），请使用 --force-audio。对于非英语视频，请使用 --lang auto。
音频提取： 当用户想要音频本身时，请传递 --audio mp3（或 m4a/wav）参数，例如用户说“给我 mp3”、“提取音频”、需要播客版本或离线收听。文件将以 <title>.<format> 格式保存在 $OUT 中，其路径会记录在 meta.json 的 audio_file 字段中。如果字幕可用，仍会将其用于转录，因此请求音频不会强制进行缓慢的转录。如果用户只想要音频而不要摘要，则在此步骤后停止并报告文件路径。
3. 阅读全部内容，然后进行总结
阅读完整的 transcript.txt；用户通常想要每一个细节。当文本超过约 6 万字时，按顺序分块阅读，并在每个块中做笔记，然后再开始撰写摘要。
用自己的话编写 $OUT/summary.md：这是一份摘要，不是转录文本。可以使用简短引用，但不要大段逐字照搬。默认结构（根据视频内容调整章节）：
# <Video title>
| | |
|---|---|
| 视频 | <title> |
| 频道 | <channel> |
| 链接 | <url> |
| 时长 | <duration> |
| 演讲者 | <only names actually stated in the video> |
| 转录来源 | <manual captions / auto captions / local Whisper transcription> |
## 1. 概览
- 5-8 个要点：视频涵盖的内容和主要结论
## 时间线
| 时间 | 主题 |
|---|---|
| 0:00 | ... |
## 2. <按视频顺序，每个章节/主题作为一个部分>
### <子主题>
- 每一个具体事实、数字、名称、定义、示例、步骤、警告和建议
- 演示和操作指南需编号；比较使用表格
## 关键事实/要点
| 项目 | 值 |
## 关于本摘要的说明
> 转录是如何生成的；你纠正的听错术语；演讲者说错的内容（附上更正）；任何听不清或不确定的地方。
为什么这样设计：时间线帮助读者跳转到视频的特定位置；表格收集了人们日后会搜索的事实；说明部分则让你对转录错误保持坦诚。语音转文字会曲解产品名称和术语，请根据上下文修正并列出修正内容。核实演讲者说错的事实，而不是简单重复。
保持正文有据可查：Notes 部分以上的所有内容都应来自转录文本或 meta.json。读者将文档视为视频内容的记录，因此你碰巧知道的与视频相关的信息（如演讲者的真实身份、拍摄地点、历史背景）不应出现在正文中，即使你非常确定。如果此类背景信息确实有帮助，请将其放在 Notes 中并标注为“视频外信息”。切勿使用视频中未提到的姓名或代词。如果视频描述与内容无关（重复或垃圾描述很常见），请忽略它并在 Notes 中说明。
根据视频长度调整文档篇幅。仅在长文档开始新的主要部分时使用 <!-- pagebreak -->（例如，数小时直播流的每个章节），切勿在封面表格后使用。一个 2 分钟的片段应只占一到两页。
4. 渲染并检查 PDF
uv run ~/.claude/skills/youtube-summary/scripts/md_to_pdf.py "$OUT/summary.md" "$OUT/<Title>.pdf"
将第 1 页和一页内容密集的页面渲染为 PNG，并在报告前查看它们：
uvx --with pypdfium2 --with pillow python -c "..."。
然后给用户提供：
- PDF 的绝对路径和页数；
- 3-5 行的概述；
- 任何注意事项：自动生成的字幕、听不清的部分。
音频文件可能很大。提及这一点，让用户决定是否删除它。
故障排除
- 针对公开视频出现
Sign in to confirm you're not a bot/ HTTP 403 错误：等待并重试。如果持续出现，则是 IP 或速率限制问题。不要循环重试。 - yt-dlp JS 运行时警告：当 Deno 不可用时，脚本会传递
--js-runtimes node。需要 Node 22+。 - 没有转录文字，或转录内容充满无意义内容：检查语言（
--lang auto），或使用--force-audio重新运行。