06-configuration-and-failure-recovery

配置与失败恢复

article-slide-video 的设计强调可恢复和可审计。每个阶段写入固定文件，调度器通过这些文件判断下一步能否继续，以及失败后应该从哪里重跑。

输出目录策略

article-slide-video 读取自身根目录的 env.json：

{
  "ARTICLE_SLIDE_VIDEO_OUTPUT_ROOT": "~/ai-artifacts/article-slide-video"
}

默认输出路径是：

ARTICLE_SLIDE_VIDEO_OUTPUT_ROOT/<输入文件名或安全主题名>/

用户明确指定输出目录时，指定值覆盖默认策略。

所有中间产物和交付物都必须写入这个目录，包括口播稿、规划、HTML、音频、视频、字幕、封面、QA 帧和报告。

配置分布

每个依赖外部参数的原子 Skill 都读取自己的 env.json，运行时同名环境变量可以覆盖默认值。

这种设计避免把所有配置集中到调度器里，也让每个 Skill 可以独立运行和测试。

典型配置来源：

• article-slide-video/env.json：输出根目录。
• bytedance-tts/env.json：TTS 接口、音色、模型、采样率等。
• slide-video-delivery/env.json：视频尺寸、封面尺寸、FFmpeg、Playwright、imagegen 相关参数。

凭据边界

BYTE_TTS_API_KEY 必须由运行时环境变量提供，不写入仓库产物，也不能输出到日志。

TTS 阶段只把正文发送给接口，slide_id、时间线、静音停顿和最终 manifest 都在本地处理。

封面生成可能使用 imagegen。交付 Skill 只把非空的 OPENAI_BASE_URL 和 OPENAI_API_KEY 注入 imagegen 子进程，不把凭据写入交付物或日志。

失败恢复原则

失败后不默认从头重跑，而是根据产物边界定位失败阶段。

常见恢复方式：

• voiceover.md 不存在或内容不对：回到 voiceover-editor。
• 分页或停顿不合理：回到 slide-narration-planner，重新生成 narration-plan.json。
• 幻灯片画面不对：只重做 HTML deck 和 deck-manifest.json。
• TTS 请求失败或音色不对：只重跑 bytedance-tts。
• slide_id 集合不一致：回到产生错误 ID 的阶段修复，不能继续合成。
• 字幕样式或烧录失败：只重跑字幕生成和烧录。
• 封面失败：只重做对应封面和报告状态。
• QA 帧发现错页或溢出：只修复 deck，再重跑渲染、视频和 QA。

校验闸门

进入下一阶段前应尽量使用明确校验，而不是凭经验继续：

• voiceover.md 存在且非空。
• narration-plan.json 是 schema version 1，且有非空 slides。
• 所有 slide_id 和 segment_id 唯一。
• break_after 不超过 0.5s。
• deck-manifest.json 的 entry 是安全相对路径。
• deck.html 实现 window.__SLIDE_VIDEO__.showSlide。
• tts-manifest.json 与 deck 的 slide_id 集合一致。
• voiceover.wav 存在且与 manifest 对应。
• delivery-report.json 的所有状态都更新为 passed。

为什么这种恢复方式重要

文章转视频通常包含外部 API、浏览器渲染、FFmpeg、图片生成和人工检查。任何一个阶段失败都可能消耗较长时间。如果没有落盘契约，失败后只能重新执行整个流程。

当前设计把每个阶段的输入输出固定下来，让失败恢复变成局部操作：保留已经通过的产物，只重跑受影响的阶段。这既节省时间，也降低二次生成带来的内容漂移。