remotion-assembly

口播装配流水线（v3 hub，源自 0715-01 装配 + v3/v4 迭代）

本文件是装配流程 hub：只留流程骨架与路由，板块细则在 references/ 各文件（77 条对比差距的沉淀落点，2026-07-16 深度对比审查后定稿）。

§0 环境就绪检查（每次被唤起先跑这一节，通过了再往下读）

本 skill 的规则要落地，需要一个带底座的 Remotion 工程。不要打印说明让用户自己弄——直接执行下面的检查，缺什么补什么。

检查顺序（逐项跑，全绿才开工）

# 1) 基础运行时
node -v && ffmpeg -version | head -1
# 2) 当前目录是不是 Remotion 工程
[ -f package.json ] && grep -q '"remotion"' package.json && echo "OK: remotion 工程"
# 3) 底座是否齐全（缺任一即不完整）
ls src/design/tokens.ts src/design/motion.ts src/koubo/scenes/shared.tsx \
 scripts/render-service.cjs scripts/qc-master.mjs 2>/dev/null

三种结果的处理

结果	动作
全绿	静默通过，不要向用户汇报环境情况，直接进入装配流程
有工程、缺底座	自动补装，不必问（setup 检测到已是 Remotion 工程时只补 skill/脚本/底座，不覆盖你的代码）：macOS/Linux：bash <(curl -fsSL https://raw.githubusercontent.com/jincheng2026/jc-remotion-skills/master/setup.sh) .Windows（PowerShell）：irm https://raw.githubusercontent.com/jincheng2026/jc-remotion-skills/master/setup.ps1 | iex（已 clone 仓库时直接 node <仓库>/setup.mjs .）
没有工程	问一句再装（npm install 耗时 3-5 分钟、体积可观，属有分量操作，须用户确认目录）：「需要先建一个 Remotion 工程（装依赖约 3-5 分钟），建在哪？默认 ./remotion-koubo-studio」得到答复后：macOS/Linux 用上行 setup.sh 加 <目录> 参数；Windows 用 node <仓库>/setup.mjs <目录>
缺 node / ffmpeg	能自动装就自动装，不要把命令甩给用户（多数环境用系统包管理器装这两个不需要管理员权限）：① macOS 有 brew（command -v brew）→ 告知一句「缺 X，我用 brew 装一下，约几分钟」后直接 brew install <只装缺的>，装完重跑本节② Windows 有 winget → winget install OpenJS.NodeJS Gyan.FFmpeg③ Linux 先试 sudo -n true：免密则 sudo apt install -y nodejs ffmpeg；要密码才把命令给用户跑④ 都不行（如 Mac 没有 Homebrew）→ 给一条官方安装 Homebrew 的命令让用户粘贴到终端（需输一次密码），装完让用户说一声，重跑本节

纪律

• 只在第一次唤起时跑；同一会话内已通过就不再重复检查。
• 全绿时保持沉默——用户要的是剪片，不是环境报告。只有需要装东西时才开口。
• 补装/新建后必须重跑一遍检查确认全绿，再进流程。
• 用户明确说「跳过检查」或「我知道环境没问题」时，尊重用户，直接开工。

§0.1 开工前必读闸（出方案之前跑，与 §0 环境检查同级：不过不许往下走）

本文件是路由 hub，不是内容。 下面这张表是真源清单——出装配方案表之前必须逐个读完，不是「需要时再查」。

必读	管什么
design-system references/motion.md	动效词汇（数字滚动 / 判词砸落 / 条线生长 / 退场 / 净屏）、丝滑五律
design-system references/typography.md	T 档字阶、空档带、主角字比值
design-system references/layout.md	三区坐标、接管机制、安全框
design-system references/specs.md	组件规格表、动效数值表
assembly references/subtitle.md	字幕断句、双语规范、校验闸
assembly references/rhythm.md	节拍密度、退场纪律、密度曲线
assembly references/narrative.md	侧标体系、五能量节点、判词升格
assembly references/selection.md	句型→段型→组件对号表
design-system references/infographic.md	比喻图形化、图表选件（有数据/流程/对比段时必读）

为什么立这道闸（2026-07-27，0727-01 翻车根因第 1 层）：那一版只读了本 hub + tokens.ts + 一个现成 Scene 文件就开工，上面 9 份真源一份没读。后果是整套动效词汇只剩「淡入」一种——数字不滚、判词不砸落、多数段无退场、章间无净屏，而这些全都白纸黑字写在 motion.md 里。

两条附带纪律：

• 禁止拿某个已有 Scene 文件反推规范。一个场景只体现它用到的那部分规则，缺的恰恰是它没用到的——0727-01 就是拿 0724-01 的 Scene02 当模板，那个场景恰好没有数字滚动和 Stamp，于是整片都没有。
• 方案表每段必须写出规则条目号（见 §2 第 2 步）。写不出「依据 motion §7 / narrative §3」这类条目号，就是没读，退回重读。

§0.2 Studio 实时预览默认开启（「路 A」，2026-07-28 用户裁定）

迭代确认的默认手段是 Remotion Studio 热更新，不是渲静帧回看——「改一处→渲帧→读图」的循环只留给闸门验收。

• 开工即起预览：环境检查通过后默认启动 Studio 并打开本片合成给用户看（Claude Code：预览面板起仓库根 .claude/launch.json 的 remotion-studio；通用宿主：npm run dev 后请用户开 http://localhost:3000/Koubo-<片名>）。主组件有铺底粗剪（OffthreadVideo），Studio 里即是完整合成（口播+MG+字幕+SFX 同屏），用户随时播放、拖时间轴。
• 迭代走热更新：改代码后秒级自刷新，字号/位置/颜色/文案类调整让用户在预览里直接看、直接裁定。渲帧（render-service stills/segment）只用于三道闸证据、mg-judge 输入与交付验收——闸门与送审规矩全部不变（送审仍带音效段成片；动效规范自查仍须自己看连续画面，§2.5 第 5 步）。
• 调参面板：新片主组件由 scaffold-koubo.mjs 自动生成 zod schema（qc / subZhSize / subBottom / sfxGain；末尾打印的 Root 注册片段已含 schema+defaultProps）；挂 InfoScrim 时照 src/koubo/Koubo072701.tsx 把 scrimStrength 一并接进 schema，其余参数按片增删。铁律：schema 默认值恒等 tokens／现行裁定值，出片走默认——面板是探索层不是真源，定稿值回写对应真源（字号/底距→tokens.ts；音量档→sfx §4.4 流程），禁把非默认值留在 defaultProps。Root 的 defaultProps 引 token 变量，Studio 报「Can't save default props」是刻意设计（堵住绕过 tokens 存值的路），勿修。zod 版本跟 Remotion 要求锁定（4.0.489 ↔ zod 4.3.6，起 Studio 时的 version mismatch 警告即是校验）。
• 实时播放掉帧属浏览器实时合成的正常现象：判动效手感降 0.5x 或段渲确认。开着 Studio 时起渲，串行纪律不变（#23 并发死锁 + 预警雷区「Studio+still 并发崩」）。进程「0% CPU 静默挂死」先查 iCloud 驱逐（错题 #25 及其 node_modules 变体）。

体系迭代原则（用户 2026-07-16 定调：skill 要不断迭代、不断提高标准和质感）

• 棘轮只进不退：用户裁定过的标准（规格数值、否决项、配声语法）是地板不是天花板——后续段落只能在其上加码，禁止以「上次也这样」为由维持现状。
• 每段必沉淀：段落过审 = 至少一条可迁移 why 进板块文件；翻车 = 错题立案（症状→修法位置）；用户一句「不行/勉强」= 记下改进方向（如：音效「勉强还行」→ 待升商用包）。
• 每片必复盘：换新视频装配前，先扫一遍错题集与各板块「反面案例」，确认新片起点 = 上一片的终点标准。
• 质感对标不封顶：当前基准片只是基线不是终点；发现更高水准的参考随时按词级对比法吸收进规格表。

规则冲突裁决序（两条规则打架时按此自裁，记录后等用户追认）

用户裁定 > 硬约束（三区/占位表/门控/亮面禁裸字）> 语义对齐（说到哪出到哪）> 密度节奏基准 > 美学偏好。 已知裁决实例：对齐优先于净屏（rhythm 1）、图表讲解锚豁免退场纪律（rhythm 4，待大考验证）、快闪列举不触发 case 素材义务（broll 6）。新冲突按序自裁并在方案里显式记录，禁止静默择一。

主会话纪律（0722-01 全流程复盘护栏，2026-07-24 立；详见 my-video/docs/0722-01-全流程踩坑复盘-20260723.md）

一夜返工三次、机器两次卡死，根问题不是执行，是判断与对齐。四条铁律：

1. 采用现成方案 / 写死数值前，先写清「适用条件」。skill 的默认输出（如 gbro 组装动画的慢揭示）只在它自己的语境成立，不会自动适配你的宿主内容——密集口播里慢揭示＝画面永远慢半拍（A1，8 条视频作废）。一个数字管全批＝默认所有条目同构，而它们通常不同构（A2「人物占高 45-60%」一刀切致全身远景失败）。规格要写「什么情况用哪档」（如物件驱动隐喻 45-60% / 人物驱动隐喻近景 65-80%），不是只写一个档。
2. 用户的条件句不是祈使句。「只有 X 才 Y」是给约束不是要 X（A3：用户说「只有全屏 B-roll 才让人物消失」＝人物默认不消失，我读成「B-roll 做成全屏」，深夜返工 1.5h）。歧义术语（「让画面动起来」＝镜头运动 vs 元素运动）先回一句对齐再实现，比猜便宜得多。
3. 验证必须能区分「测了没问题」与「根本没测」。QC「零违规」先核探针覆盖率（错题 #35）；监控长任务盯任务专属信号（该任务自己的会话/产物/进程 PID），别盯全局——0722-01 三次监控误报都是盯错信号（盯到用户自己并行跑的封面任务、拿「文件多久没变」判死活而 Codex 是攒够批量才写盘）；硬红线（无假字/logo/水印）主会话必须独立放大复验，不采信子代理自查口径（C5：07 号自查「四边无假字」实则顶边有字母）。
4. 改版 / 交付即 git 提交。项目是 git 仓库但常年不提交 → v5 场景代码被整屏版覆盖后只能照渲染画面重建、还原度打折（D3）。每完成一版或交付前 git add -A && git commit，代码丢失是全流程唯一不可逆的损失。

底座缺陷补底座或立案，禁只在单段打补丁（错题 #36 InfoScrim：0715-02 就地补丁、缺口一路留到 0722-01 才炸）。

板块路由表（装配各步骤读哪个文件）

板块	文件	管什么
句型选型（第一查询点）	references/selection.md	口播句型→段型→语法指针→组件对号表；主拍三序判据；无匹配出口
无参考研发	references/rd-noref.md	语法缺口+无参考片时的新编排设计：多方案生成→judge panel→用户定稿
参考片复刻（研发模式-A 方法层）	独立 skill remotion-reference-fidelity	有参考片复刻时的保真方法论：scene grammar 六型、词级 beat 表、保真闸；只管「怎么忠实读参考片」，数值一律以各板块真源为准；alpha 透明交付线触发条件也在它（见 §6）
章节叙事	references/narrative.md	侧标体系、红绿阵营、重锤时机、hook/CTA、判词升格
密度节奏	references/rhythm.md	beat 表、每 3-5s 节拍、退场纪律、recap 加重、审计法
字幕	references/subtitle.md	语义断句、英文短句、底衬箱、校验脚本
素材工程	references/broll.md（规则真源）+ 独立执行 skill remotion-broll（判定→采集→验真→选段→嵌入→调色→段渲一条龙，判出真素材段就调它干活）	四级素材优先级（自录屏>官方视频>截图>模拟卡）、视频自采与剪辑管线、punch-in、调色统一
声音	references/audio.md（规则真源）+ 独立执行 skill remotion-sfx（选源→试听板→加工入库→cue 挂载→定量验收，段落配声就调它干活）	SFX 管线、音量规范、母带 loudnorm、定量验收
版式/排印/质感/动效/图表	design-system 的 references/	layout / typography / texture / motion / infographic
错题集（症状→修法索引）	独立 skill remotion-gotchas-index	全文「错题 #NN」（#18/#19/#23/#24/#25 等）的修法位置查这里

工程底座（substrate）：本流程假定 src/design/（tokens/组件/motion/qc 探针/FontGuard）+ src/koubo/scenes/shared.tsx（门控四件套 + Place + qcAllow）已在位——它们是全仓共享底座，新片复用不重建。冷启动无 src/ 时，先按 design-system SKILL「工程底座清单」建底座再进本流程。

新片端到端流程（无参考片：从粗剪+SRT 到成片的通用 checklist）

定位澄清（2026-07-20）：无参考片是常态，有参考片是特例。 常态 = 剪原创口播、无对应参考片，走 references/selection.md 句型语法路线，套已校准的风格规格出方案（本 checklist 即为此写）。有参考片（如 1:1 复刻基准片某片做风格校准）只是特例，用途是校准、验证风格是否学到位；别把「有参考片逐帧对齐」当默认流程。 现有各节多以 0715-01/基准片为实例（那是有参考片可逐帧对齐的校准场景）。没有参考片的自制片走本 checklist——通用流程在此，本片实例细节各归对应板块。有参考片时只在第 4 步前插入「原片 contact sheet 词级对齐」（见 §2 第 3 步 / §2.5 研发模式），其余步骤相同。

1. 输入验收与素材接入（§0 + §0.5）：收粗剪成片 + SRT，按 §0.5 七步把「用户丢进来的两个文件」变成可开工状态（同片检查/落位/字幕草稿/工程骨架/硬编码适配）。ffprobe 定 fps/分辨率，合成参数匹配素材、勿默认 60fps（design-system 错题 #19）；calculateMetadata 代码化。
2. 构图问用户（§1 / layout.md §1）：信息区放左/右不自作主张，抽 3-4 帧看人物站位、用户裁定为准；作者默认信息 MG 放左侧。
3. 通读 SRT 划章节（§2 第 1 步）：按语义转折切 15-20 段，每段选一个主包装点；同时在时间轴标出五能量节点（hook/重锤判词/VS 决算/全片级判词/CTA，见 narrative.md §1）。
4. 按语法出方案（无参考片的核心差异）：没有原片可抄 beat，逐句先查 references/selection.md 句型对号表定段型与主语法（含主拍三序判据），再进指针指向的板块真源取规格——narrative 定叙事骨架与五节点、rhythm 定换拍与峰值、infographic 定比喻图形化、layout 定三区与接管。查表无匹配的句型走 references/rd-noref.md，禁裸设计。产出装配方案表（assembly/<片名>/装配方案.md：时间段｜口播要点｜侧标｜主 MG｜素材缺口），给用户过目确认后才写码。
5. 判研发/生产模式（§2.5）：全段主编排都能在现有语法找到对应 = 全程生产模式（§2.5.1 五阶段）；含新编排模式的段升研发模式逐段循环。
6. 实现 + 三道闸（§2.5）：素材段走 remotion-broll，HUD 段按 layout 测量值写码，配声走 remotion-sfx；每段过 QC 探针→mg-judge→用户终审。
7. 全片章法 pass（§2.6）：色系预算/侧标连续性/节奏密度曲线/SFX 分布/重复元素五项跨段过一遍。
8. 母带链 + 交付（§5/§6）：过母带链（压缩+定量增益+限幅，audio.md 规则 2）后 ffprobe 验时长/音轨/码率；交付带证据（QC 报告+渲帧对比）。交付或返工收尾后更新项目根 STATUS.md 的本片状态行（无则创建；它是跨会话/跨 agent 的状态档，新对话接手全靠它）。

0. 输入规范（用户交付约定）

• 用户给：粗剪成片（气口已剪）+ 配套 SRT。不跑 whisper。
• 交互契约（2026-07-21 用户裁定，铁律级）：用户只供三样——① 粗剪+SRT；② 被点名的素材（B-roll 录屏/截图——AI 先按 broll 规则 2 列清单点名要，或用户主动供）；③ 自然语言裁定与终审反馈（构图方向、听感/手感报时间点）。除此之外不许让用户丢任何文件：装配方案、工坊文档、返工单、cue 表等过程文件全部是内部产物，AI 自建自读自续——返工/续工按 §0.5 第 1 步「同片再入」自动装载未清账项，禁止要求用户搬运、粘贴或复述任何过程文件。
• SRT 时间戳 = 装配唯一基准：enterAt 帧 = SRT 开始秒 × 合成 fps。
• 输入缺 SRT（只有口播文字）时只能出方案级 beat 表：时间列标「估算」，落码前必以真实 SRT 重校；无粗剪可抽帧时构图裁定标「待裁定」。
• 合成 fps/分辨率匹配素材（ffprobe 先查，勿默认 60fps）。若非 1080p@30：规格表/动效帧数/qc-master.mjs 元数据断言须连带改，完整连带清单见 design-system references/motion.md §0（现有整套校准值锁 30fps）。
• 字幕生成与断句规范 → references/subtitle.md。

0.5 素材接入动作清单（新片开工第 0 步：从用户给的 mp4+SRT 到可开工）

0. 环境自检（不过即停，禁绕路，宿主通用）：Bash 写一个测试文件（如 echo ok > assembly/env-check.txt）→ 用读文件手段回读验证可见（Claude=Read 工具）→ 删除。写入不持久或回读看不见 = 会话在沙箱模式执行、后续一切产物都会蒸发（错题 #30：0719-01 测试因此全损）——立刻停下让用户放开写权限（Claude=授权 Bash/编辑；Codex=workspace-write 等），再开工。禁止三种自救绕路：/tmp 软链绕中文路径（路径整体加双引号即可）、自行解除沙箱（dangerouslyDisableSandbox 等任何宿主旗标）、把项目复制到别处干活。文件产物一律用标准写文件手段落盘并回读验证（Claude=Write 工具优先）。
1. 同片检查：ffprobe 时长与 public/footage/ 现有各片比对，±1s 内视为同片 → 问用户「复用旧实现还是当新片重剪」；选重剪则全程不读旧片的 scenes 代码与 assembly/<旧片名>/ 工坊文档（防照抄旧答案、防误覆盖旧片），按新片名走全新流程。同片再入（续工/返工/换素材，2026-07-21 定）：用户说「继续」或只丢来新素材时，自动扫 assembly/<片名>/分段工坊/segments.md 未尽项 + docs/<片名>-返工单*.md 未清账条目，直接列为本轮任务清单开工——禁止等用户贴返工单、复述历史或说明改哪里（§0 交互契约）。
2. 定片名：MMDD-NN（拍摄日期-序号，如 0715-01）；用户指定名从之。
3. 素材落位：粗剪复制进 public/footage/<片名>.mp4；源为 4K 时先转 1080p H264 再入 footage（合成本就 1080p，4K 铺底 OffthreadVideo 解码卡顿会吐重复帧＝成片人物冻帧，0721-01 实锤见错题 #33——在接入步转掉，别等渲出冻帧再返工）；原始 SRT 存档 assembly/<片名>/input/（SRT 是装配唯一基准，必须入库——0715-01 教训：原始 SRT 未入库，只剩生成物无从复核）。用户原文件不动。
4. 验收：§0 的 ffprobe 项 + SRT 三项（UTF-8 可读、时间戳单调、末条结束时间 ≈ 视频时长）+ 烧录字幕检查（ffprobe 之后必做）：ffmpeg 抽任意 1-3 帧 Read 看底部，目视确认粗剪无烧录字幕/水印（0715-02 教训：原交付自带全片烧录字幕、烧进像素无独立字幕流，与精修新字幕重影，到渲染出帧才发现＝白跑一轮 QC；发现即停，请用户供无字幕版或裁定压占）。
5. 字幕草稿：node scripts/srt-to-cues.mjs <存档.srt> <片名> 机械转换出 src/koubo/subtitles-<片名>.ts 草稿（zh=SRT 原文、en 空），再按 subtitle.md 规则 2/3 完成语义重排、错字校对（以口播为准）、英译，check-subs.mjs 零报错才装配。三步是一体的，英译不是可选项——check-subs 现在会拦「en 全空 / 覆盖率 <90%」（2026-07-27 立案：0727-01 只做了重排、77 条 en 全空，成片退化成单行中文，旧版 check-subs 只在 en 非空时校验格式，全空反而静默放行）。真要做单语片显式传 --mono，把「这是决定」和「这是漏做」分开。
6. 工程骨架：node scripts/scaffold-koubo.mjs <片名> <时长秒> 一键生成（字幕轨/音效轨+空 cue 表/主组件/scenes-<片名>/ 目录+占位/工坊段表，音量取现行基线；脚本末尾打印 Root.tsx 注册片段照贴即可）。段文件目录与旧片 scenes/ 隔离——文件锁按片独立防撞名；共享底座仍从 src/koubo/scenes/shared.tsx 引。
7. 换片硬编码两处：render-service 的 COMP_ID/ENTRY 与 qc-master 元数据断言，细则见 §6「换片必改」。

1. 构图与三区版式 → design-system references/layout.md

构图先问用户（0715-01 教训：信息区方向不能自作主张，用户裁定放左）。三区坐标、takeover 素材接管机制（A 级：人物整段退场、不带 PiP；升格时刻靠字号提级+清场+红绿镜像框，B 级压暗已被用户否决）、主角时刻、编组模板全在 layout.md——它是版式唯一真源。

2. 分段方法：先方案后代码（两步走）

1. 通读 SRT 划章节：按语义转折切 15–20 段（开场 hook / 论点 / 案例 / 转场比喻 / 分型递进 / 总结 / 预测 / 片尾），每段选一个「主包装点」。
2. 产出装配方案表（assembly/<片名>/装配方案.md）：时间段 | 口播要点 | 侧标 | 主 MG | **规则依据** | 素材缺口 | 承载模式，给用户过目确认后才写代码。 「规则依据」栏是 §0.1 必读闸的验收凭证（2026-07-27 增设）：每段填出该段主编排所依据的条目号（如 motion §7 数字滚动 / narrative §5 判词升格 / selection 横评句）。填不出条目号 = 那段是凭语感设计的，退回读真源重排——这一栏不是文书工作，是「读没读过」的唯一可查证据（0727-01 的方案表 27 段无一条规则引用，全片动效因此只剩一种淡入）。

B-roll 承载模式必须先问（2026-07-24 用户定，横屏片强制）：划段时标出需要 B-roll/画中画的段。对每个这样的段，若用户没给素材，主动带上我的理解建议问用户：这段要「整屏 B-roll」（人物退场、素材铺满全屏）还是「画中画卡片」承载（人物在场、素材在右区小卡，如 0722-01）？ 承载模式一次定三件事——① 版式：整屏切人物 vs 卡片+人物常驻（layout §2 铁律）；② 分辨率/工具：画中画 720p 够（可用 Grok/gbro 拼贴）、整屏要真 1080p——grok CLI 实测只有 480p/720p 两档做不到，须走 xAI API（grok-imagine-video-1.5 支持 1080p）、真素材或 Sora/Veo/Kling/Seedance（详见 broll SKILL ④）；③ 素材方向：我据此去 AI 生成或请用户/剪辑师找。别自己默认承载模式——0722-01 就因默认做整屏、又比例一刀切，返工两轮。

素材未到位段并行渲染（提速铁律，2026-07-24 用户定）：承载模式与素材方向确认后不阻塞等素材——所有不依赖外部素材的纯 MG 段先全部渲染完毕，只把等 B-roll/画中画的那几个段留占位；素材到位后只补渲那几段、splice 拼回全片（段渲拼回 22s 级，见 §6）。即：素材依赖段与独立段解耦，用户找素材的时间里主会话把能渲的都渲了，最大化并行。 3. 若口播稿源自某条参考视频（翻录/改写），必须先抽原片 contact sheet 逐段对齐（ffmpeg 每 10-15s 一帧拼网格），以原片实际处理为准，不要自由发挥——首次装配 8 处偏差全部来自没先看原片。

2.5 分段对齐工坊（2026-07-16 用户裁定；2026-07-17 增补双模式判据）

研发模式 vs 生产模式（用户点名提速后定，第一性原理：语法已沉淀就不该再考古）：

• 研发模式（本节全流程：密集读帧→方案→多路验证→逐段终审）只用于引入新编排模式的段——判据：该段的主编排在 narrative/rhythm/infographic/specs 现有规则里找不到对应语法。研发模式分 A/B 两条方法路线：有参考片可抽帧 = 研发-A（本节第 2 步读参考帧）；语法缺口且无参考片 = 研发-B，方法本体在 references/rd-noref.md（多方案生成→judge panel 择优→用户定稿→沉淀回写），本节第 2 步对研发-B 不适用。
• 生产模式（模式复用段）：不走逐段循环，走「全段扇出并行 + 集中集成」批量拓扑（五阶段详见 §2.5.1）——判据取反：全段主编排都能在现有规则找到对应语法。哪段 judge 打回率回升 = 该段其实含新模式，单独升回研发模式，不拖累其余段（升级门槛量化＝同段扫批打回 ≥2 次或用户终审返工，见 §2.5.1 阶段 4）。

研发模式逐段循环：

1. 拆段：按内容对齐参考片切几十个片段（章级起步，问题段再细到 beat 级）。多会话并行纪律（2026-07-17 用户指令）：动工前先读 assembly/<片名>/分段工坊/segments.md 段表（本片实例：assembly/0715-01/分段工坊/segments.md）——有占位的段不碰；自己动工先写占位行（会话标识+作用域清单：改哪些文件区块）；渲染/npm 全项目串行（错题 #23/#24），起渲前 pgrep 查场。新片首次进工坊该文件不存在：由主会话初始化——mkdir -p assembly/<片名>/分段工坊/ 后新建 segments.md，套用 0715-01 段表格式（每段一行：段号 | 时间范围 | 主包装点 | 作用域文件 | 占位/认领状态），派工前先建好，子代理只认领不新建。
2. 看参考（词级对齐，2026-07-16 用户裁定）：抽参考片该段密集帧（0.5s/帧）。逐字稿与参考片相同时，用参考片内嵌字幕当对齐轴——每帧自带「他正在念什么」，还原出「念到什么字→出什么 MG」的词级 beat 表，再对我们的 SRT 找同句时间点；对比必须逐帧读图理解（元素规格/联动关系/让位动作），禁止只看文件名或缩略图。先判「真素材段还是手绘 HUD 段」（见 broll.md 总纲），再先测量后写码——从参考帧量出元素占屏比例/字号/位置，禁止目测（seg01 教训：目测=系统性缩水 0.4-0.7 倍）。产出该段《方案》（beat 表+差异诊断+改法+对比截图），给用户过目确认后才动代码。
3. 做：素材段走采集管线，HUD 段按测量值写码。
4. 渲该段：--frames=a-b 十几秒出片；渲前删旧产物防 ○ 缓存。
5. 验收（三道闸，2026-07-16 起；2026-07-27 前置一道静态闸）： ⓪底座复用闸（node scripts/check-scenes.mjs src/koubo/scenes-<片名>）——静态扫场景目录：design/motion 零引用、零退场件（useExit/Exit/ClearOut，motion §1 sev5）各为 FAIL；组件类别低于段数档位（短片 <10 段 3 类 / 长片 5 类）、退场覆盖率 <50%、自建 kit >150 行却零 motion 各报 WARN；末尾打印一张自查清单（数字滚动 / 判词砸落 / 章间净屏 / 动效词汇是否单一），这四项静态扫描查不到，必须自己看连续画面。 （阈值经 2026-07-27 对抗式审查修订：初版的「Breathe 零引用报 WARN」已删除——与 motion §9「新片一律不挂 Breathe」直接冲突；「组件类别 <4 一刀切」已改分档——初版把 0724-01 这个当前质量标杆判成 WARN。改规则前用标杆片实跑验证判别力，是这次立下的规矩。）这道闸查的是「有没有用上底座」，QC 探针和 qc-master 查的是「有没有坏」，两件事不能互相替代：0727-01 全片 25 段自建 323 行 _kit.tsx 重造卡片、动效只有 quad 淡入位移 0，qc-master 照样零 FAIL 零 WARN 放行，用户直接判「动效越来越丑」（2026-07-27 立案）。它最便宜、最早，放在写完段代码、起渲之前跑。 ①QC 探针（node scripts/render-service.cjs qc <起帧> <止帧>）——重叠/字幕净空/最小字号自动断言，报「哪两个元素第几帧重叠多少 px」，零违规才进下一道；咬合位（规则允许的主从压角重叠）用 Place 盒的 qcAllow 白名单豁免。三个代号的落点：Place 定位盒与 qcAllow prop 在 src/koubo/scenes/shared.tsx；QC 探针 QcProbe（逐帧读 [data-qc] 盒判重叠）在 src/design/qc.tsx（错题 #29 讲幽灵重叠假阳与 null 门控修法）。 ②独立质检 agent（mg-judge + references/rubric.md 四维评分卡）——干活的不给自己打分；任一维 <7 打回。 ③用户动态终审——送审带证据（带音效段成片+QC 报告+关键拍对比图；禁无音效中间版送审，真源 remotion-sfx §4.5，0715-02 教训：渲两遍空耗）。 ⚠️ 送审前必须自己先看连续画面（2026-07-27 增设硬约束）：至少段渲一次视频、自己完整看过，再送用户。「动效手感只有用户能验（AI 静帧盲区）」 这句话被 0727-01 用成了免责声明——那一版渲了 21 张静帧、每张都仔细看过、判定合格直接送审，而用户一眼看出的问题（数字不滚动、段间硬切、章间无净屏、全片一种入场动效）全部只存在于时间维度，静帧一张都看不出来。静帧盲区不是「所以交给用户去发现」，是「所以必须自己看动起来的版本」。真正只有用户能定的是审美偏好（这个节奏喜不喜欢），不是规范符合性（有没有按 motion.md 做）——后者是自查义务。 成片级另跑 node scripts/qc-master.mjs <mp4> [期望时长]（黑帧/硬切/解码/元数据/响度）。
6. 沉淀：过审后把该段的设计逻辑（why，不是坐标）写进对应板块文件，让规则可迁移到其他视频。沉淀唯一载体 = skill/板块文件（用户 2026-07-16 裁定）：项目知识、教训、裁定、进度全部进 skill 或工坊文档（segments.md 等），禁止以 AI 长期记忆代替沉淀——记忆跨不了 agent、用户看不见、换会话就漂移；memory 只允许留指向 skill 的薄索引。

2.5.1 生产模式五阶段流程（批量并行 + 集中集成，2026-07-18 seg06-19 实测定型）

模式复用段不逐段循环，走「全段扇出并行实现 → 集中集成」批量拓扑。实测：seg06-19 共 14 段用此流程 ≈2.8h 完成；同 14 段按研发模式 ~2.5h/段需 ≈35h。质量闸门不降，砍掉的是逐段仪式、重复读参考帧、每段各自起渲/tsc 的空转。硬前提两条：① Scene 已拆成一文件一段（「拆文件重构」= 把整片主组件里的每段独立成 src/koubo/scenes/SceneNN.tsx 单文件，好处是「作用域锁=文件锁」——N 路实现员各锁一个 Scene 文件不撞车；背景与收益见 docs/提速方案.md）；② 语法已沉淀（narrative/rhythm/infographic/specs 有对应条目）。缺任一条不能进生产模式（新片若还是单文件大组件，先做拆文件重构再进）。试点豁免（2026-07-21 第一性复盘定）：方案零 rd-noref 段（全部句型查表命中）时跳过试点样板段、全部段一次扇出**——试点阶段的存在理由是「规则不全需先立基线」，规则已全覆盖时基线就是设计系统本身，试点只剩纯串行等待（0721-01 实测试点串行 ~25min）；方案含新模式段时只对新模式段留试点，其余段照常全扇出。

1. Plan-lite（轻方案）：不开方案工坊、不重读参考帧。每段只按已沉淀语法 + 深度对比报告该段条目出一张 beat 表（口播句→视觉增量→组件+侧标+时间），主会话一次性批出全部待做段的 beat，用户过一次目。翻录片有原片 beat 轴就抄，非翻录片直接按语法排（见新片端到端流程第 4 步）。
2. N 路并行实现（禁渲、禁 tsc）：每段派一个实现员（独立执行单元，两端等价：Claude=子代理，Codex=后台 codex exec 子进程；宿主映射见项目 AGENTS.md），各锁一个 scenes/SceneNN.tsx（文件锁不撞车，14 段可 14 路齐开）。实现期硬纪律——不起渲染、不单独跑 tsc：渲染与 npm/tsc 是全项目串行操作（错题 #23/#24），N 路各自起会互撞、排队空转，一律推迟到阶段 3 统一做。实现员只交代码 + 自报改动清单与自主调整项。
3. 集中集成（统一 tsc + 全片 QC + 批量快扫）：全部实现员收工后整包交一个集成员子代理串行跑完——① 全库一次 tsc（一次覆盖 N 段的类型错，比 N 次各跑省时且能抓跨段串扰）；② 全片 QC 探针（render-service.cjs qc 跑关键帧区间，重叠/净空/最小字号自动断言）；③ 批量快扫（渲各段自核帧，一轮扫完 N 段抓明显偏差）。三项串行，QC 零违规才进下一阶段。主会话只读集成员的例外清单，禁亲自逐段读帧/预审段代码（2026-07-21 强制化：0721-01 主会话逐段亲审是 347 轮的主因）——段级质量由 QC 脚本 + 阶段 4 judge 负责，主会话只处理被打回段。
4. judge & fix：单个 mg-judge（独立上下文质检员，禁自审自过；宿主映射：Claude=.claude/agents/mg-judge.md 子代理，Codex=codex exec -i 帧 子进程，同一份 rubric）带 rubric 四维卡扫批（读自核帧+红线清单，不重读参考帧），任一维 <7 或 QC 报违规的段回给对应实现员定点修，修完只重验该段。弹性升级（量化门槛，取代模糊的「明显回升」）：首次被扫批打回 → 只定点修 + 只重验该段，仍在生产模式；同一段被扫批打回 ≥2 次，或该段任一次用户终审返工 → 判定「该段含新模式、超出方案红线覆盖」，把它单独升回研发模式逐段循环（重读参考片抽帧做举一反三），不拖累其余段。
5. 交付审核页：全部段过 QC + judge 后生成一张批量审核页（assembly/<片名>/分段工坊/批量审核页.html 格式：每段挂带音效段成片 + beat 表 + QC 报告 + 关键拍对比图；sfx §4.5：禁无音效中间版），攒多段一次给用户终审——动效手感是 AI 静帧盲区，仍须用户验（三道闸第③闸不省，只是从逐段往返改成批量往返）。

提速纪律（2026-07-21 0721 片实测定账：1.9h 剪 2.1min 片＝主会话自身生成 60%〔337 轮〕+ 渲染空等 25%——瓶颈不在渲染在主会话轮次）： ① 操作批量化：独立工具调用一轮并发发出，禁一步一轮小碎步——每轮都是一次完整思考成本； ② 集成整包下沉：集中集成（tsc+全片 QC+段渲+抽帧自核）可整包交一个集成员子代理串行跑完回汇总，主会话只审结果不亲自逐步跑； ③ 渲染禁空等：起渲一律后台，渲染窗口内并行推进下一阶段（音效挂载/审核页/章法 pass）——实测全片渲 10min 主会话空转是纯浪费； ④ 预览硬编码：预览与审核版渲染一律 RS_HW=1（macOS=VideoToolbox 约 3x；Windows/Linux 由脚本自动探测 NVENC，不可用回退软编，同一开关三平台安全）；libx264 crf15 只用于交付 master。 ⑤ 纯音效改动禁整片重渲（2026-07-21 用户裁定）：走 COMP_ID=<片> node scripts/render-service.cjs audio <已渲视频> --out <输出> 音频增量（实测 4.6min vs 整片 ~35min）；音量类参数先渲 3s 试听段定档；铺底源一律 1080p、交付无 B 帧（错题 #33）。 ⑥ 主会话轮次预算 ≤50 轮/片（2026-07-21 定，基线 347）：五阶段各一个执行包子代理（方案/实现批/集成/音效/母带），主会话只发包、收包、批量审、对用户汇报，禁逐段汇报；超标＝先查哪个阶段没下沉，不是「下次快点」。 ⑦ 全片渲预算 ≤2 次/轮（预览 1+master 1，基线 6 次）：其余验证一律段渲快扫/试听段/音频增量；起第 3 次前必须写得出「哪条画面级改动覆盖全片」；单段修复走 segment-splice 段渲拼回（已建：COMP_ID=<片> node scripts/render-service.cjs splice <起帧> <止帧> <已渲全片.mp4> --out <输出.mp4>，止帧自动吸附关键帧、音轨整条同源 copy、内建帧数/时长/无B帧/音轨md5断言，0721-01 实测 22s vs 全片 ~10min）；无画面改动时 master＝预览渲 remux；元数据 scaffold 一次算准。 ⑧ 并行拓扑（2026-07-21 定）：串行资源只有 tsc/npm、渲染队列、用户确认点，其余默认并行——音效支线前置（cue 草稿=方案产物，已脚本化 node scripts/beat-to-cues.mjs <片名>（见 sfx §4.5），实现期音效员并行只校不编，首次全片渲即带音效）、集成渲染队列边收段边排渲（仅最终 tsc 等全段齐）、字幕∥方案、素材工程∥HUD 实现。 （⑤-⑧ 实测账与完整依赖图 → docs/提速方案.md v2/v3，此处只留硬线。）

2.6 全片章法 pass（跨段一致性，所有段过审后跑一次）

单段都对、连起来不对，是独立盲区（Anthropic 多 agent 系统的 citation pass 同构）。全部段落过用户终审后、合片前，跑一个专职检查：

1. 色系预算曲线：逐段统计高饱和色系数，全片红绿阵营语义不漂移（红=危机绿=生存不得中途互换）。
2. 侧标连续性：章节编号/配色/变体全片一致；DISSOLVED/IMMUNE 系列无断档。
3. 节奏密度曲线：按段统计元素增量频率，锯齿形（有峰有谷）为合格，平坡或持续满编打回；每章有一次 2-4s 整屏峰值插拍（rhythm §2）。注：A 级全屏黑接管已于 2026-07-20 从「每 60-90s 一次」硬指标降为可选，只在真正必要处用（layout §2「默认接管翻转」），此处密度曲线只查整屏插拍节拍，不再强制接管频次。
4. SFX 分布：重锤 ≤2 处/片；连击对应视觉 stagger；无 30s 以上静默区。
5. 重复元素：同一判词/同一图形跨段重复出现的，确认是刻意呼应而非复制粘贴。 产出：全片体检报告（沿用 assembly/<片名>/分段工坊/体检-*.md 格式），违规回段修。

3. 选件与节奏 → references/narrative.md + rhythm.md + infographic.md

叙事骨架（侧标/分页式/案例页/重锤时机）在 narrative.md；节拍密度与退场纪律在 rhythm.md；比喻图形化与图表选件在 design-system references/infographic.md。此处只留两条流程级原则：

• 数字以用户口播为准：翻录稿数字可能与原片不同，一切以 SRT 文本为准。口播未念出的推导值默认不上屏（用口播原相对表述，如「便宜一半」→「-50%」而非推导价）；确需上推导值，方案里标注推导、交用户裁定。
• 装配后必跑节奏密度审计（方法在 rhythm.md）。

4. 工程结构

public/footage/<片名>.mp4          # 素材拷入（OffthreadVideo 铺底，保留音轨）
assembly/<片名>/input/*.srt        # 原始 SRT 存档（装配唯一基准，必须入库）
src/koubo/subtitles-<片名>.ts      # CUES: {start,end,zh,en}[]（srt-to-cues.mjs 草稿 → subtitle.md 规则 2/3 精修）
src/koubo/scenes-<片名>/SceneNN.tsx # 段文件（按片独立目录；共享底座从 scenes/shared.tsx 引）
src/koubo/SubtitleTrack.tsx        # 帧→cue→BilingualSub
src/koubo/<片名主组件>.tsx          # 每章一个 <Sequence from={F(start)}>
assembly/<片名>/装配方案.md         # 方案（先确认）
assembly/<片名>/任务书-codex.md    # 派工任务书（含逐元素时间表）

• Sequence 内 useCurrentFrame 是相对帧：元素 enterAt = (元素秒 − 章节起始秒) × fps。
• 顶层挂一次 FontGuard；SubtitleTrack 放最上层。

5. 声音 → references/audio.md

SFX 合成/挂载/音量/母带链（压缩+定量增益+限幅）/定量验收全在 audio.md（本风格默认无 BGM；可听性验收按 audio.md 规则 1——「≥+6dB」阈值 2026-07-20 起待重标定，先以逐 cue 可听可辨+用户终审为准；BASE_VOL 现基准 0.3-0.55 见规则 8 音量条/sfx §4.4）。

6. 渲染与交付（v3 画质教训，详见 design-system 错题 #08/#09）

• 质量参数已固化 remotion.config.ts：setJpegQuality(100) + setCrf(15)，勿回退默认（jpeg80+crf18 会让 MG 文字边缘出压缩晕影，用户直接感知为「画质差」）。
• 参数调整先渲 5 秒测试段，同帧裁 MG 文字区放大对比，确认后再渲全片。
• 全片渲染（>几分钟）必须 nohup … & disown 脱离会话跑（Windows 用 Start-Process node -ArgumentList … -RedirectStandardOutput <日志> 等价脱离），日志重定向到文件；完成判据=日志出现 + 输出文件 行，不认进程存在性（pgrep 会自匹配误判；Windows 查场用 tasklist /fi "imagename eq node.exe"，同样只作参考）。
• 渲染产物过母带链（压缩 + 定量增益 + 限幅，命令在 references/audio.md 规则 2）后才是交付物。
• 成片唯一出口（2026-07-24 立）：master 过 qc-master 验收后移入顶层 成片库/（命名 MMDD-NN-成片.mp4，非最终版名字带 -vN/-待终审），旧定稿移 renders/_history/；成片不留在 previews/ 或 renders/ 根下散置（用户找不到片的教训）。
• 交付前 ffprobe 验三项：时长与合成一致、音轨存在、码率合理；残片绝不给用户看。
• 交付带证据：修改点渲帧拼对比图（新旧版同帧并排），用户按时间点报问题时能对上号。
• 证据硬门禁：任何「完成」宣称必须附 QC 报告 + 渲帧证据，口头宣称无效（Claude Code 官方 best practices：「没有可跑的 check，你就是验证环」）。
• 高频出帧/段渲用常驻渲染服务 node scripts/render-service.cjs stills|segment|qc（bundle 一次浏览器复用，比 CLI 逐条快数倍）；预览/审核版渲染加 RS_HW=1（macOS=VideoToolbox 约 3x、10M 码率，2026-07-21 实测；非 macOS 自动探测回退），交付 master 不加（保 libx264 crf15 画质）；渲染只按用户/方案确认的范围起（基准片雷区「自动跑 4K render」）。
• 换片必改脚本里的硬编码（冷启动易漏，两处）：
  • scripts/render-service.cjs 的合成 id 默认写死当前片（'Koubo-0715-01'），新片段渲用环境变量覆盖：COMP_ID=Koubo-<片名> node scripts/render-service.cjs …（入口同理 RS_ENTRY；composition 须已在 src/Root.tsx 注册），否则 selectComposition 渲错片。多片并存期换片时建议直接更新默认值防漏。
• scripts/qc-master.mjs 成片验收把元数据断言写死 1920,1080,30/1（搜 1920,1080,30/1）。新片粗剪若非 1080p@30，先改这条断言，否则必报「元数据异常 FAIL」——与 §0『合成 fps/分辨率匹配素材、勿默认 60fps』一致，断言要跟着素材走。换合成 fps 的完整连带清单见 design-system references/motion.md §0。
• 可选：alpha 透明母带交付线（默认走上面的 baked 链，不是它）。当交付物需要透明叠加层而非烤在铺底上的成片时，改走 alpha 模式：合成背景透明 → bash scripts/make-small-alpha-master.sh <ProRes4444源> <HEVC-Alpha输出>（PresetHEVC3840x2160WithAlpha 出 4K 透明 HEVC + verify-alpha.swift 验 alpha 通道）。触发条件与 checker 预览细则见 remotion-reference-fidelity SKILL（alpha-delivery mode）。

7. 与参考片的差距归因（v2→v3 复盘方法论）

两片时长不同时用等比例时间轴对齐：各按相同百分比位置抽 40 帧，配对拼 contact sheet 逐段看。差距按三层归因，逐层判断责任方：

1. 画面底色（拍摄环境/调色）：暗房氛围灯 vs 亮白墙，决定 MG 是「悬浮 HUD」还是「贴墙便利贴」——拍摄侧问题，装配只能靠 scrim 补救，不背这个锅也不要试图全靠后期救。
2. 节奏密度 + 版式胆量（装配侧，references/rhythm.md 审计 + layout.md 主角时刻管）。
3. 声音 + 微动效（装配侧，references/audio.md + motion.md 管）。 先分层再动手，避免把拍摄问题误诊为组件问题瞎调参数。

8. 分工与验收

• 执行下沉、主会话只审（2026-07-17 用户指令；2026-07-22 中立化为宿主无关）：实现/修复/渲染交付类工作一律派独立执行单元（Claude＝Opus 4.8 子代理〔工作流 agent 传 model:'opus'〕或 codex:rescue；Codex＝后台 codex exec 子进程），主会话只负责出方案任务书、审核证据与裁决——不亲自写实现代码。
• 任务书构成：逐元素时间表、硬约束（作用域锁+防撞车纪律）、完成判据（tsc/QC 探针/关键拍自核红线清单）。
• 任务书完成标准固定四条：tsc 不新增报错、指定帧 still 渲染成功、关键实体自核（对该段 SRT 逐一确认人名/数字/判词说到即上屏，对齐 rubric 维度 2 抽查口径）、回报改动清单与自主调整项。
• 派工与监控纪律（0722-01 C 类坑沉淀，任务书里写死这五条）：① 多条目任务一条一个执行单元并行发，禁一个单元串行做全批（会做到一半触发 task_complete 收工，C2）；批量任务写死「逐条回报，未完成不得判定完成」。② 禁阻塞式等待结束回合（「I'll wait for…」＝任务没做完，C6）——要么轮询到产物出现继续做完，要么如实回报卡在哪一步。③ 多执行单元共享 cwd 禁用 --continue 类续会话（会串到别的单元把 A 的成片写进 B 的路径，C4）；交付前全批 md5 去重。④ 监控盯任务专属信号（该任务的产物路径+进程/会话），并先弄清被监控者的写盘节奏（批量攒写的任务不能拿「文件多久没变」判死活）——主会话纪律 3 的派工侧展开。⑤ 任务书明写「发现指令与实测矛盾时按实测回报、不盲从」——0722-01 子代理三次纠正主会话错误指令（精剪方式/QC 误报/分辨率前提）全是对的，质疑通道必须留着。
• 验收方法：每章抽 1 帧（章节中段、元素全部入场后）拼 contact sheet，对照装配方案逐项检查：时间对齐（说到哪出到哪）、位置（块状件在左右两区；跨中区仅限时间轴/流程链/对比条，且 y = 下巴 + 0.70×头高、避开人脸盒，见 layout §1.6/§1.7）、字体（FontGuard 过）、图标（无 emoji/假 logo）。

9. 冷启动实战大考（skill 体系大改后 / 换片前的泛化验证）

问答大考（读 skill 答题）只验「读得懂」；实战大考验「做得出」。触发时机：selection.md/rd-noref 级别的体系改动落盘后，或新片开工前对体系可用性存疑时。

• 素材：一段 300-500 字全新口播（用户写或 AI 按 selection.md 未验证句型扩写后用户审稿），题材刻意混合形态压力最大的句型（如横评为主轴+图表句+步骤句+判词句）；TTS 合成人声 + whisper 出 SRT 凑齐「粗剪+SRT」标准输入。
• 执行：全新会话冷启动（只带 skill 与素材，不带任何项目历史上下文），按端到端流程 8 步跑「排方案→实现→评分」。
• 通过判据（五条）：a) beat 表 ≥80% 拍能溯源到 selection.md/板块条目，无凭语感孤儿拍；b) 语法缺口段正确触发 rd-noref 分支，未硬套或裸设计；c) 三道闸 + rhythm 审计无 8s 级打回；d) 向用户提问只发生在流程规定裁定点（构图/试听/终审），无迷路提问；e) 用户终审一轮内收敛。
• 任一不达标 → 定位是 selection.md 缺行还是 rd-noref 缺步，修真源后复测。语速/情绪档差异大的题材（如冷静拆账）建议做第二轮，防单参考片节奏基准过拟合（密度/SFX 基准均由 356s 单片标定）。