管道执行约定

面向实现处理器、持久化和恢复逻辑的贡献者。用户需要了解的文件传递及失败行为见工作流指南。

处理器结果约定

媒体处理器共享输出规划、顺序执行和单文件跳过结果的构造。音频提取、元数据、缩略图 及 remux 的单输入任务使用第一个输出覆盖；批量任务要求每个输入对应一个输出，或 完全省略输出。ASS 与 DanmakuFactory 则严格按选中的视频/XML 输入匹配输出。 命名及空字符串的含义仍由各处理器决定。

音频提取、元数据、缩略图和 remux 通过共享驱动器暂存后统一发布：任务的每个输出先写入 临时文件，整批一起发布，因此批量处理中途失败或取消时不会发布任何文件，某一项的输出也 不可能覆盖另一项的输入。ASS 保留自己的产物匹配循环，使用相同的暂存发布机制。 源文件仍在发布成功后删除，跳过的源文件会保留。输出、成功/跳过输入和日志保持输入顺序， 现有元数据格式不变。批量任务会报告已处理项目的输入和输出大小总和。

处理器报告部分输入失败时，即使其余输入已处理完成，该任务（以及所在的工作流步骤）也会 失败，错误信息会列出每个失败的输入。已发布的文件保留在磁盘和任务的产物历史中，重试时 会跳过它们继续。rclone 移动或百度网盘上传中途失败时，会按文件分别记录结果，而不是把所有 文件都记为失败。复制和移动步骤会拒绝两个会落到同一目标文件名的输入；录制时长短于所请求 时间点时，缩略图步骤会改用第一帧。

路径机制共享文件系统解析，同时保留不同策略：ASS 命令路径保持词法形式；remux 解析已存在的相对命令路径，并进行尽力解析及 Windows/macOS 大小写折叠比较。 暂存输出验证检查原生文件身份（包括硬链接），通过父目录解析尚不存在的输出文件， 并传播 I/O 错误。传输处理器仍在源文件可能被消耗前记录大小，仅将确认不存在的输入 视为先前已完成的传输。

重启时恢复弹幕分段

恢复流程将已存储的 XML 输出与视频分段关联：把视频路径的扩展名替换为 .xml 后，必须与已存储的 XML 路径匹配。不会根据标题数字或媒体输出 ID 推断分段索引。如果没有匹配分段，或不同分段索引对应同一个 XML 路径， 该 XML 输出会被跳过并记录警告。恢复数据库时应保持原始视频与 XML 路径 记录一致；无法匹配的历史文件不会被自动分配分段或重新执行配对处理。

错误处理

配对分段和会话完成管道先接收视频输入，再接收弹幕输入。会话完成输入按分段序号排序， 配对输入保留收集顺序。每个视频对应哪个弹幕文件会按分段记录为管道的会话配对， 随管道本身保存，每个步骤都能读取，重启或重试后同样可用。字幕转换和烧录只在同一分段内配对： 某个分段没有弹幕文件时，该分段的视频不会加字幕，也不会影响后续分段的配对。 每个字幕在一个任务中只烧录一次；同一任务中同一录制文件的第二个副本会被原样传递并记录说明。 录制文件旁不再写入任何文件；旧版本留下的 _inputs.json 文件已不再使用，可以删除。

正常完成与重启恢复都会按 DAG 定义顺序收集叶子步骤输出，保留每个路径的首次出现， 在 Windows 和 macOS 上进行大小写折叠比较。缺少叶子记录或输出数组无效时，恢复会保留有效输出， 同时报告未完整完成。重复完成同一步骤不会再创建下游任务，也不会再次增加 DAG 的已完成步骤数。

Delete、rclone 和 BaiduPCS 的重试等待时间按指数增长，但每次最多等待 30 秒， 极端配置值也遵循此上限；重试次数仍按配置执行。FFmpeg 两种上游时间戳字段 对外都转换为毫秒单位的 out_time_ms。

禁用覆盖时，暂存输出在 Windows、Linux 和 macOS 上使用原生的禁止替换发布， 因此不支持硬链接的文件系统仍可发布文件，且不会覆盖竞争写入的目标。 既不支持禁止替换发布、也不支持硬链接的平台会返回错误。处理器被放弃后，临时文件 会在异步工作线程之外尽力清理；正常发布会等待提交或回滚完成。字幕和字体路径中的 单引号与滤镜图分隔符无需用户额外转义。

• 快速失败（Fail-fast）：某个步骤失败时，只取消直接或间接依赖它的步骤。独立分支上的步骤继续运行并正常完成；工作流保持进行中并把该失败记录为错误，直到没有步骤在运行时才标记为失败。重试只会重新运行失败和被取消的步骤。
• 重试：可以手动或自动重试失败步骤。重试会先检查每个要重新启动的任务，再修改任何数据；若重新启动中途出错，工作流会带着重试错误再次失败，并保持可重试。被取消但从未创建任务的步骤所在的工作流同样可以重试。启动时，若某个运行中的步骤的任务早已失败或被取消，其工作流会被标记为失败，以便重试。
• 日志：每个步骤都会保存执行日志，便于排查问题。

重试和重启恢复会保留任务已有的步骤耗时、日志计数、文件大小信息及产物历史。 开始新的尝试不会重复写入以前的日志。处理器运行前会先保存当前处理器信息； 如果保存失败或已有执行信息无效，任务会停止处理并报告失败，不会替换原始信息。 完成和失败更新也会保留额外的已存储执行信息字段。

产物历史可能包含先前尝试已经发布的文件，后续失败不会删除这些文件。 处理器负责管理自己暂存的临时输出，清理限制见上文。