知硕字幕优先视频转写

要解决什么问题

拿到一条视频链接想要文字内容，常见做法是直接丢给 ASR。但多数平台视频本来就带字幕——人工上传的或平台自动生成的——ASR 反而引入专有名词误写、漏字和时间轴漂移。另一个问题是「批量下载」常常一条命令拉走整站音频，开销与合规性都不可控。更隐蔽的坑是：字幕检查失败和「确实没有字幕」在输出里长得一样，脚本于是把登录失效或网络错误当成无字幕，悄悄进入音频下载。

工作方式：字幕优先

核心锚点是原始字幕永不被覆盖。优先级固定为 人工字幕 → 平台自动字幕 → ASR，产出落在 raw/ 里作为证据，AI 整理稿放在别的目录，不能替换它。

每条视频独立走六个步骤：

• 识别来源与权限：记录稳定视频 ID、原 URL 或本地路径、标题和获取时间。
• 检查分支依赖：已有 .srt / .vtt 只需 Python；URL 与批量发现需要 yt-dlp；只有 ASR 分支才需要 ffmpeg 和一个 Whisper 实现。缺少 ASR 依赖不会阻塞本可完成的字幕分支。
• 先列字幕：用 yt-dlp --list-subs 或等价能力列出人工与自动字幕，确认前不下载大音频。
• 获取原始文字：优先人工字幕，其次平台自动字幕；两者都不存在且用户明确允许时，才抽取音频运行 ASR。
• 生成三层资产：raw/ 存原始字幕，clean/ 去掉序号和冗余时间码但保留时间定位，review/ 是给后续 Agent 的任务包，status/ 记录完成、失败、待 ASR 与相对产物路径。
• 抽查与停止：每种来源至少抽查一条视频开头约两分钟的术语、重复与漏字，并把 status/ 里的 human_spot_check 从 pending 更新为 passed 或 needs-review。若「应有字幕」却意外进入音频下载或 ASR，立即停掉整批并排查字幕发现、语言名称、登录状态与工具版本。

批量入口先只做列出与去重，不下载字幕、音频或模型；确认清单后再跑。B 站需要登录时显式加 --cookie-browser chrome，命令输出、状态文件和日志都不得包含 Cookie 内容。模型不在本地时，只有用户明确允许才能加 --allow-model-download。每条视频状态独立记录，可断点续跑。

适用边界

• 只覆盖 B 站、YouTube 与本地视频文件，不因 yt-dlp 列出 extractor 就宣称整站已验证。
• 摘要、课程笔记、选题和 PDF 渲染属于转写验收之后的独立任务，不计入本技能的完成条件。
• 平台自动字幕质量参差，抽查那一步不能省。
• ASR 分支的识别质量取决于所选 Whisper 实现与模型。