BaoCut 这类把字幕切分和配音合成放在一条流水线里跑的工具，一旦整条流程失败，最常见的问题不是修不好，而是不知道该修哪一段：切分日志和合成日志混在同一个输出里，字幕时间轴坏了会被合成阶段的报错盖住，合成参数错了又会被误认为字幕切得不对，结果只能把整条流程从头重跑。比较稳妥的做法是先把两段拆开：先只跑字幕切分，把中间产物落盘并人工抽查，再用这份中间产物单独触发配音合成；等两段各自稳定后，再考虑用一条命令串起来。

字幕切分和配音合成应当按两个可独立执行、可独立重跑的阶段来组织：切分阶段只产出字幕与时间轴中间文件，合成阶段只读取该中间文件，两个阶段各自写自己的日志。中间产物要落盘保留，不要在同一次运行里被覆盖。判断问题归属时，看失败发生在哪个阶段、日志里出现的是切分阶段还是合成阶段的报错文本、退出码对应的是哪一类错误。这样做的代价是多一次人工抽查，以及需要维护中间产物的目录规范。

只执行字幕切分并保留中间产物

目标是拿到一份可单独检查的干净输出，在进入配音合成之前就能确认字幕本身没有问题。具体命令取决于实际使用的工具，BaoCut 的调用方式需要以其帮助信息或配置项为准；通用的做法是找只跑到切分阶段就停止命令或配置项，例如工具如果支持 `--stage`、`--only` 或独立的子命令，就显式指定为切分；如果只提供配置文件，就把合成相关的开关关掉，只保留切分段落。

下面是通用骨架，参数名需要按实际工具替换：

# 只执行字幕切分，输出目录显式指定，便于后续单独检查
baocut run \
  `--input` ./input/demo.mp4 \
  `--stage` split \
  `--out-dir` ./work/demo/01_split \
  `--log-file` ./work/demo/01_split/split.log

echo "exit=$?"

中间产物建议至少包含三类字段：字幕条目本身（序号、文本、起止时间、时长）、切分依据（对齐到的音频区间、断句位置、语言或标点信息）、以及元信息（输入文件、所用参数、工具版本、生成时间、状态标记）。产物目录按“每次运行一个目录、阶段再分一层子目录”组织，比如 work/<任务名>/01_split/ 放切分结果与日志，work/<任务名>/02_tts/ 放合成结果与日志，中间文件统一叫固定的文件名（如 subtitles.json），方便后续脚本直接引用。

对中间产物做一次人工抽查

人工抽查的目的不是逐条校对全部字幕，而是在进入合成前，用较小成本发现结构性错误。样本量可以按条目总数的规模来定：条数不多时看开头、中间、结尾各若干条；条数很多时按固定间隔抽取，并额外把最长条目、最短条目、时长为零或时长为负的条目单独挑出来看。挑选时优先关注三类位置：开头和结尾（容易丢字或多出空白）、说话人切换或背景音变化处、以及标点密集或语速明显偏快的段落。

需要核对的字段包括：文本是否与音轨内容对应、有没有明显的漏字和串行；起止时间是否单调递增、相邻条目有没有重叠或过大空隙；条目数是否与预期量级接近。发现异常时，处理动作要具体：文本错位通常回到切分参数（断句阈值、最小/最大条目时长）调整；时间轴重叠或倒挂通常是音频采样或偏移问题，先确认输入文件是否被正确解码；条目数明显异常时先判断是切分过碎还是漏切，再决定调整参数还是更换切分方式。抽查不通过，就不要进入合成阶段。

用中间产物单独触发配音合成

这个阶段只读取上一阶段落盘的字幕文件，不再重复执行切分，好处是合成出错时不需要重跑切分。指定中间产物路径时，建议在命令里写明确的文件路径而不是“默认输出目录”，这样同一个合成命令可以指向不同的切分结果，便于对比。

# 用已有的切分产物触发合成，不重新切分
baocut run \
  `--input` ./input/demo.mp4 \
  `--stage` tts \
  `--subtitle` ./work/demo/01_split/subtitles.json \
  `--out-dir` ./work/demo/02_tts \
  `--log-file` ./work/demo/02_tts/tts.log

echo "exit=$?"

重复执行是否覆盖旧的合成产物，取决于 `--out-dir` 里同名的输出文件是否被直接写入。如果工具默认覆盖，建议每次合成先换一个新的输出子目录（例如带上时间戳），或者在同一目录里先归档旧文件；如果工具支持“跳过已存在文件”，也只在确认旧产物与当前中间产物对应时才使用。失败重跑前的清理步骤建议固定为：保留 subtitles.json 不动，删除本次合成目录下的半成品音频和临时片段，确认日志文件是新一次生成的，再执行合成命令。

对比两段日志的失败特征

分开跑之后，判断问题归属最直接的办法是看日志来自哪个阶段、出现了哪类报错。下表是通用对照，实际报错文本以工具输出为准，建议第一次运行时就把真实的报错原文补进这张表。

还有两类容易混淆的情况：一是切分阶段成功但产物字段不全，合成阶段才报“解析失败”，这类错误看日志归属是合成，根因却在切分，因此合成日志里如果出现字幕结构相关报错，要先回看 subtitles.json；二是合成阶段报超时或网络错误，与字幕内容无关，重跑前只需要清理半成品，不必重跑切分。退出状态要和日志正文一起看，返回 0 但有告警的情况需要人工确认输出文件是否真的生成。

把两段串成一条可重跑的命令

串联的前提是两段都已经分别跑通，并且中间产物的字段和路径都稳定。串联方式一般是顺序执行两条命令，前一条失败就中断，避免在半成品字幕上继续合成：

set -e

baocut run `--input` ./input/demo.mp4 `--stage` split \
  `--out-dir` ./work/demo/01_split \
  `--log-file` ./work/demo/01_split/split.log

baocut run `--input` ./input/demo.mp4 `--stage` tts \
  `--subtitle` ./work/demo/01_split/subtitles.json \
  `--out-dir` ./work/demo/02_tts \
  `--log-file` ./work/demo/02_tts/tts.log

set -e 保证切分失败时不会进入合成；如果工具本身支持 && 串联，也可以用 cmd1 && cmd2。串联后仍要保留中间产物：不要在串联脚本里清理 01_split 目录，合成阶段的输入始终指向上一步的落盘文件，这样失败时可以直接把命令拆开单独重跑第二段。串联版上线前做一次一致性检查：用同一份输入分别跑一次分段版和串联版，比较两边的 subtitles.json 条目数与时间轴、最终音频时长和日志中的阶段标记是否一致；如果串联版在合成上拿到的是不同的字幕文件，说明路径引用有问题，应先把路径统一成工作目录下的固定位置。