核心用法
youtube-transcript 是一个专为超长 YouTube 视频（>1小时）设计的全自动转录翻译工作流。其核心价值在于解决大语言模型单次会话无法处理完整视频字幕的技术瓶颈，通过子代理（Sub-Agent）分块处理机制实现超长内容的可靠翻译。
典型使用场景：
- 提取 YouTube 视频完整字幕（verbatim，逐字稿）
- 将英文访谈/播客/演讲翻译为中文
- 处理超过1000行字幕的超长视频
- 生成带执行摘要和关键指标表格的格式化文档
技术架构：采用三层流水线设计——主会话负责任务拆分与协调，子代理执行500行分块翻译，最后合并输出。集成 DownSub API 获取字幕源数据，可选对接 zhiyan MCP 生成在线文档。
显著优点
1. 突破上下文限制：通过子代理机制将超长视频拆分为可管理的块，避免单会话token溢出
2. 质量管控机制：强制校验字幕语言字段（仅接受 en/en-auto），防止错抓小语种轨道
3. 结构化输出：自动生成执行摘要（3-5 bullet points）和关键指标表格，提升信息获取效率
4. 成本可控：子代理设有30分钟/$2的预算硬限制，防止意外超额消耗
5. 流式写入：采用分块追加写入而非全量加载，降低内存压力
潜在缺点与局限性
- 外部依赖强：必须持有有效的 DownSub API Key（Bearer token格式），且该服务为第三方商业API，存在服务稳定性风险
- 仅限英译中：当前工作流硬编码为英文→中文方向，不支持其他语言对
- 无实时能力：需等待完整字幕下载后才能启动翻译，无法边播边译
- 格式单一：输出为纯Markdown，缺乏 SRT/VTT 等专业字幕格式支持
- 子代理黑箱：分块翻译在子代理中完成，主会话难以实时监控进度或中途干预
适合人群
- 研究人员：需要消化大量英文长视频访谈/学术演讲
- 内容运营：批量处理海外播客、发布会等素材
- 语言学习者：获取带时间戳的逐字稿对照学习
- 商业分析师：提取财报电话会、投资者日等关键数据
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| API密钥泄露 | DownSub token 需妥善保管 | 建议配置于 secrets，避免硬编码 |
| 翻译质量波动 | 长视频分块可能导致上下文断裂 | 子代理提示词强制 verbatim 翻译，保留原文结构 |
| 小语种误识别 | 多语言视频可能抓到错误字幕轨道 | 前置 `lang` 字段校验，非 `en` 则中断 |
| 子代理超时 | 极长视频可能超出30分钟预算 | 用户可手动调高预算或分段提交 |
| 服务依赖 | DownSub 或 `zhiyan` 服务中断 | 设计降级路径：直接输出本地 `.md` 文件 |