核心用法
TubeScribe 是一款专为 macOS 设计的 YouTube 视频智能处理工具。用户只需粘贴 YouTube 链接，系统即可自动完成提取、转录、总结和语音合成全流程。核心工作流通过单个子代理（sub-agent）执行七步流水线：提取视频元数据与字幕 → 读取结构化信息 → 生成格式化 Markdown 文档（含参与者表格、段落式总结、带可点击时间戳的关键引用、观众情感分析、精选评论、完整转录）→ 转换为 DOCX → 生成音频摘要 → 清理临时文件 → 打开输出文件夹。
触发方式：用户发送 YouTube URL 或主动要求总结/转录视频时立即启动。采用非阻塞设计，主对话继续的同时后台处理，完成后通过子代理通知告知结果。
显著优点
1. 零成本与隐私优先：无需订阅、API 密钥或外部账户；所有转录、说话人检测和 TTS 处理均在本地完成，无数据上传至第三方服务。
2. 多模态输出：同时生成结构化文档（DOCX/HTML/Markdown）和可收听音频摘要（MP3/WAV），支持批量队列处理和 MLX 加速的语音合成（Apple Silicon 最优）。
3. 智能内容解析：自动识别多说话人场景（访谈/播客）与单说话人内容（教程/讲座），提取观众评论情感与精选高赞评论，时间戳直接链接回视频原位置。
4. 灵活配置：通过 ~/.tubescribe/config.json 可精细调整输出格式、TTS 引擎（mlx/kokoro/系统内置）、语音混合、播放速度及队列行为。
潜在缺点与局限性
- 平台依赖：主要面向 macOS 设计，依赖 Homebrew 生态（
brew install）及 Apple Silicon 优化（MLX 后端）。 - 网络与内容限制：必须联网获取 YouTube 数据；不支持无字幕视频、直播流、私人/年龄限制/区域封锁内容。
- 可选依赖门槛：DOCX 输出需 Pandoc，MP3 需 FFmpeg，评论获取需 yt-dlp，高质量 TTS 需额外安装 mlx-audio 或 Kokoro。
- 长视频超时风险：超过 30 分钟的视频需手动调高子代理超时（默认 600 秒，建议 900 秒）。
适合人群
- 需要快速消化大量 YouTube 内容的研究者、学生、记者与知识工作者
- 偏好本地处理、注重数据隐私的 macOS 用户
- 希望将视频内容转为可编辑文档或便携音频的播客听众与内容创作者
- 拥有 Apple Silicon 设备以充分利用 MLX 加速的用户
常规风险
- 子代理安全约束：已配置严格指令禁止软件安装（pip/brew/curl/venv/二进制下载），若工具缺失会停止并报告，避免系统污染。
- 路径与权限：输出目录默认
~/Documents/TubeScribe，需确保写入权限；配置文件中硬编码路径可能因用户环境差异需调整。 - 队列状态管理：多 URL 并发时需显式检查
--queue-status，否则可能意外并行或阻塞。 - 音频生成依赖：若未安装 FFmpeg，MP3 生成将失败或回退至 WAV；TTS 引擎选择影响音质与速度，需预先配置验证。