1.3 目录结构与产物管理
1.3 目录结构与产物管理
本节摘要：本节给流水线立第三块地基：产物管理。先给出「一条片子一个项目目录」的模板：配置在根、中间产物在 build 分段子目录、成片在 deliver，三层互不污染；完成标记放 build/status，与 1.1 节的执行器衔接。再讲命名与版本：产物文件带内容版本（v1、v2），制品带时间戳，两者分离，「改了什么」永远可回答。最后讲可复现性：一条片子由 project.json 一个配置文件驱动，同样的配置加同样的输入应当产出同样的成片——为此要把随机性（种子、日期、模型版本）全部显式写进配置。本节没有算法，但决定了流水线半年后还能不能维护。
学习目标
- 按模板搭出一条片子的项目目录，说出三层的职责边界。
- 为产物文件设计带版本与带时间戳的两套命名，并说清适用场景。
- 用一个配置文件驱动全流程，列出必须显式化的三类随机源。
- 区分可再生产物与不可再生产物，设计归档策略。
一、一条片子一个项目目录
目录模板如下（本书所有示例默认在这个结构里运行）：
my-video/ ├── project.json # 一条片子的唯一配置入口 ├── idea.md # 一句想法的原始记录（脚本段输入） ├── build/ # 全部中间产物（可再生） │ ├── 01_script/ # 剧本 JSON 各版本 │ ├── 02_storyboard/ # 分镜 JSON 各版本 │ ├── 03_assets/ # 素材包与生成任务清单 │ ├── 04_clips/ # 每镜一条片段 mp4 │ ├── 05_timeline/ # 时间线 JSON 与视频轨 │ ├── 06_audio/ # 配音与音效（后半本启用） │ ├── 07_subs/ # 字幕文件 │ └── status/ # 各段完成标记（1.1 节的执行器读这里） └── deliver/ # 成片与交付物（不可再生，只进不改） ├── rainbow_v1.mp4 └── compliance.txt # 合规清单（第 4.2 节）
三条边界规则：build 里的东西随时可以整目录删掉重造；deliver 里的东西一旦产生只追加不覆盖；project.json 是唯一允许「人手改」的全局文件。段的编号前缀（01 到 07）与执行顺序一致，新人打开目录就能读出流水线的形状。
这套目录不必每次手敲，固化成一个十几行的脚手架（纯标准库）：
# new_project.py —— 从模板落出一条片子的项目目录（纯标准库） import json from pathlib import Path STAGES = ["01_script", "02_storyboard", "03_assets", "04_clips", "05_timeline", "06_audio", "07_subs", "status"] def scaffold(root_name): root = Path(root_name) for stage in STAGES: (root / "build" / stage).mkdir(parents=True, exist_ok=True) (root / "deliver").mkdir(exist_ok=True) (root / "idea.md").write_text("一句话想法：", encoding="utf-8") config = {"title": root_name, "pipeline": {}, "seeds": {}, "budget": {}} (root / "project.json").write_text( json.dumps(config, ensure_ascii=False, indent=2), encoding="utf-8") print("项目目录已就绪：%s" % root) if __name__ == "__main__": scaffold("my-video")
脚手架的三个要点：模板长在代码里，每条新片子零手工建目录，结构漂移从源头杜绝；status 与七个加工段子目录同时创建，执行器第一跑就有地方落完成标记；project.json 的最小骨架同步落下，第三部分讲的配置驱动从第一秒就开始生效。
目录也不是一次建完就静止的，它随流水线推进逐段生长。三个时间点的切面对照（产物名为示意）：
| 时间点 | build 里新增 | status 里新增 | deliver 里新增 |
|---|---|---|---|
| 脚本与分镜过审 | 01_script 与 02_storyboard 的各版本 JSON | script.done、storyboard.done | 无 |
| 生成段跑完 | 04_clips 的每镜片段加 failures.json | render.done | 无 |
| 剪辑导出收口 | 05_timeline 的时间线 JSON 与视频轨 | timeline.done、export.done | 时间戳成片加 compliance.txt |
对着时间点读目录，能读出流水线的进度：status 的完成标记是执行器的红绿灯，build 各子目录的非空与否是加工段的脚印，deliver 的文件列表则是交付历史的台账。项目复盘与排障（见本节第五部分）都从这张切面表起步。
二、命名与版本
两类产物的命名需求不同，用两套规约：
| 产物类型 | 命名规约 | 示例 | 理由 |
|---|---|---|---|
| 契约与内容产物 | 名称加内容版本 | storyboard.v2.json、shot_101.mp4 | 版本号承载「第几稿」，diff 友好 |
| 最终制品与日志 | 名称加时间戳 | rainbow_20261016T1412.mp4 | 时间戳承载「何时生成」，避免覆盖 |
内容版本在每次人工修改或重新生成后递增，旧版本不删——分镜 v2 被否掉时还能退回 v1。镜头片段以镜头号命名（shot_101.mp4），重跑生成段就是原地覆盖，幂等性由命名保证。一个常见错误是把版本号写进目录名（如 build_v2/），这会让执行器的路径约定全部失效：版本属于文件，不属于目录。
两套命名的健康形态与事故形态，用一次目录列表就能对照：
# bash —— 健康目录与事故目录的对照（产物名为示意） ls build/04_clips # shot_101.mp4 shot_102.mp4 shot_201.mp4 failures.json ls my-video_v2/build/04_clips # （执行器只认 project.json 里的固定路径 build/，这个目录永远无人读取）
事故形态的代价不在磁盘空间，在认知：任何人在两套目录之间选错一次，后续所有对账都要重来。版本进文件名、目录永远只有一套，这条纪律值得在团队里零容忍地执行。
三、可复现性：配置驱动一条片子
目标是「同一份 project.json 加同一个 idea.md，跑出同一条成片」。为此，所有影响产出的参数都要显式进配置：
# project_config.py —— project.json 的结构示意（一条片子一个配置） project = { "title": "六十秒看懂：彩虹为什么是弧形", "pipeline": { "script_model": "结构化输出模型代号（以你的供应商为准）", "tts_provider": "cloud", "video_provider": "api", # 或 "local"，见第 3.3 节 "resolution": [1920, 1080], "fps": 30, }, "seeds": { "script": 20261016, # 文本生成种子（供应商支持时） "image": 101, # 文生图种子 "video": 202, # 视频生成种子 }, "budget": {"currency": "USD", "max_spend": 5}, }
必须显式化的三类随机源：模型侧随机（温度、种子——能固定的固定，不能固定的记录请求标识）；环境侧漂移（模型版本、供应商接口版本，记进配置的备注字段）；时间侧引用（「今天」这类词在脚本段就要替换成具体日期，否则两周后重跑剧情都会变）。完全可复现在云 API 侧只能逼近、不能保证——供应商模型会更新；但对「客户问起上周那版为什么和这版不一样」的场景，配置里记下的请求标识就是答案的起点。
# bash —— 一条片子从配置到成片的标准入口 python run_stage.py # 全流程（跳过已完成段） python run_stage.py render # 只重跑生成段及其后未完成段
四、中间产物的分级与清理
build 目录会越长越大，清理前先分级：
| 级别 | 内容 | 再生成本 | 处置 |
|---|---|---|---|
| 契约产物 | 剧本、分镜、时间线 JSON | 低（有配置即可） | 小而关键，永久保留并进版本管理 |
| 生成产物 | 片段 mp4、配音 wav | 高（花过 API 的钱） | 成片交付后归档压缩，不轻易删 |
| 派生产物 | 拼接中间文件、日志、缓存 | 低（本地算力） | 随时可清，脚本一键重建 |
经验法则：花过钱的产物按钱处置，花过时间的产物按时间处置。生成片段是整条流水线最贵的中间产物（第 10 章后半本会算账），删它之前先确认对应分镜版本再也不会回退。归档时把「分镜 JSON 版本、生成参数、种子」与片段打包在一起存——脱离了参数的片段是无法复现的孤儿。
五、常见问题与排查
目录与产物层的故障症状五花八门，根因却高度集中。排查表：
| 症状 | 常见根因 | 处置 |
|---|---|---|
| 执行器重跑了已完成的段 | status 标记被误删，或标记文件名与段名枚举不一致 | 对齐标记命名枚举，恢复标记后重跑 |
| 剪辑段拿到旧片段 | 覆盖式重跑没有真正执行，旧片段残留 | 按镜头号原地覆盖，核对文件修改时间 |
| 找不到上周交付的那版成片 | deliver 被当成工作目录反复覆盖 | 制品一律时间戳命名，只进不改 |
| 两条片子的产物混在一起 | 两个项目共用一个 build | 一条片子一个项目目录，从脚手架新建 |
| 重跑结果与上次对不上 | 种子、模型版本、日期引用未进配置 | 按三类随机源补记录，重跑前先 diff 配置 |
两个高频追问。「build 整目录删了重造，失败记录也要删吗？」——删之前先把 failures.json 与生成参数打包归档：片段可以再生，但「哪些任务失败过、为什么失败」的记录是花钱买来的经验，应随归档保留。「版本管理管到什么粒度？」——契约产物（剧本、分镜、时间线 JSON）进版本管理，生成片段走归档压缩，deliver 制品靠时间戳自证；三者机制不同，不要混用一套。
本节要点回顾
- 目录三层：配置在根、中间产物在 build 分段、成片在 deliver 只进不改。
- 两套命名：内容产物带内容版本，最终制品带时间戳；版本属于文件不属于目录。
- 可复现性靠配置驱动：模型参数、种子、时间引用三类随机源全部显式化。
- 产物分级处置：花过钱的归档、花时间的保留、纯派生的一键重建。
至此总论三章凑齐：契约、JSON、目录。下一章进入第一个真模块——让大模型把一句想法稳定地变成剧本与分镜 JSON。