| name | video-forge |
| tips_exempt | internal quality discipline (continuity contract teaches cats, not users); no new user-facing capability |
| description | 视频制作全链路：素材入库 → 剧本冻结 → 全局配音 → 对齐 → 渲染 → 审查 → 交付。 Use when: 做视频、做 showcase、做教程视频、录屏剪辑、video review、节奏审查。 Not for: 纯代码开发（用 worktree/tdd）、纯文档写作（直接写）、PPT（用 ppt-forge）。 Output: schema 驱动的视频成片 + 多猫审查通过 + 可发布。
|
Video Forge — AI 视频生产线
关联 Feature: F138 Video Studio
技术收敛纪要: 2026-04-05 三猫收敛
核心原则
视频不是一只猫的活，是多猫流水线 + operator素材。 角色按当前 roster 可用猫分配。
- 主执行猫（当前持球猫）：video-spec 编排 + Remotion 渲染 + 对齐集成
- QA/审查猫（跨 family）：音画同步 QA + 事实审查 + schema review
- 视觉把关猫（跨 family）：节奏/调性审查 + 字幕/排版设计 + retiming 风格把关
- operator：素材录制 + 粗标时间点 + 剧本确认 + 审片
铁规矩
- 全局音频，不段级切碎 — TTS 拿完整剧本一口气读完，保住情绪和呼吸感（KD-12）
- 不赌 TTS 原生 timestamps — forced alignment 出时间戳（KD-10）
- 拒绝暴力慢放 — 画面不够时：FREEZE_STYLIZED > B_ROLL > SLOW_MO（KD-14）
- Contract 和 Renderer 解耦 — video-spec JSON 是真相源，Remotion/FFmpeg 是可替换渲染器
两条生产路径
| 路径 B：先脚本后素材 | 路径 A：先素材后配音 |
|---|
| 触发 | "做个 showcase/教程视频" | "这段录屏帮我配个音" |
| 人的输入 | 分镜脚本 + 素材 + 粗标 | 原始视频 + 风格关键词 |
| spec 来源 | 人写 | 模型生成（PySceneDetect + VLM） |
| Phase | Phase 1 主攻 | Phase 3 引入 |
两条路径共享同一套 segment contract + 渲染层。
开局参数（必须声明）
| 参数 | 说明 | 示例 |
|---|
| 类型 | 视频类型 | showcase / 教程 / 攻防战 / 播客 |
| 时长目标 | 成片目标时长 | 60s / 3min / 6-8min |
| 调性 | 整体情绪基调 | 真实生活感 / 高燃极客 / 温馨猫咖 |
| 受众 | 谁看这个视频 | linux.do 社区 / B 站观众 / 内部 |
| 配音方案 | 猫猫配音 / 纯字幕 / 原声 | 单猫旁白 / 多猫声线 / 无配音 |
没有开局参数 = 审查没有标准。开工前必须和operator确认。
场景路由（路径 B）
| 触发 | 场景 | 主导 | 说明 |
|---|
| operator说"做个视频" | A: Brief + 素材盘点 | 主执行猫 | 确认开局参数 + 分镜表 + 素材需求清单 |
| operator确认分镜 | B: 素材入库 | operator录 + 主执行猫压缩归档 | 素材放 docs/videos/{project}/assets/，粗标写 asset-markers.md |
| 素材到齐 | C: video-spec 冻结 | 主执行猫 | 写 video-spec JSON（4 层 segment contract），operator确认 |
| spec 确认 | D: 全局配音 + 对齐 | 主执行猫 | CosyVoice 全局配音 → Qwen3-ForcedAligner → word_timestamps |
| 对齐完成 | E: Remotion 渲染 | 主执行猫 | schema → inputProps → preview render |
| 预览版出来 | F: 审查 Gate | 全部参与猫 + operator | 见下方审查标准 |
| 审查通过 | G: Final Render + 交付 | 主执行猫 | 高质量渲染 + 封面导出 + 发布 |
| operator不满意 | R: Patch Loop | 主执行猫 + 视觉把关猫 | retiming / 重录 / 重写段落 |
审查 Gate（F 场景）
F1: 音画同步审查（QA/审查猫）
| 级别 | 维度 | 判定 |
|---|
| P1 | 配音和画面脱节 | 说到 X 时画面不是 X |
| P1 | 时间戳偏移 | 字幕和声音对不上（>200ms） |
| P1 | 音频断裂 | 段间有不自然的静音或跳跃 |
| P2 | 音量不均 | 原声和配音音量差异大 |
F2: 节奏/调性审查（视觉把关猫）
| 级别 | 维度 | 判定 |
|---|
| P1 | 暴力慢放 | 画面被强行降速拉伸，卡顿拖沓 |
| P1 | 节奏断裂 | 高燃段突然变慢 / 温馨段突然快切 |
| P2 | vibe 不连贯 | 整体情绪没有起承转合 |
| P2 | 字幕风格不一致 | 不同段落字幕样式混乱 |
F3: 内容审查（operator）
| 级别 | 维度 | 判定 |
|---|
| P1 | 事实错误 | 展示的功能/数据不对 |
| P1 | 敏感信息泄露 | 截图里有 token / API key / 私人信息 |
| P2 | 画面选取不佳 | "这段换个更好的片段" |
AI 视频生成（短片段素材）
当素材来源是 AI 生成（而非人工录制）时，使用可用的视频生成工具（如 MCP 提供的 text2video / image2video 能力）。
单段限制
AI 视频生成 API 通常有单次时长限制（如 4-6 秒）。不要试图用一次调用生成完整长视频。
多段生成策略
目标时长超过单次限制时：
- 分镜拆段：按 video-spec 的 segment contract 拆分，每段一个生成任务
- 逐段生成：每段独立 submit → poll → 获取 resultUrl
- 下载素材：将各段视频下载到
docs/videos/{project}/assets/ 目录
- FFmpeg 拼接：按 segment 顺序拼接，注意转场处理
ffmpeg -f concat -safe 0 -i segments.txt -c copy output.mp4
ffmpeg -f concat -safe 0 -i segments.txt -c:v libx264 -crf 23 -c:a aac output.mp4
- 预览拼接结果：用 rich block 内联播放（见「视频预览」章节）
注意事项
- 多段拼接必须过连续性合约（见下方「多段拼接连续性合约」）
- AI 生成的素材视为原始素材，后续配音/对齐/审查流程不变
多段拼接连续性合约
多段生成是正常的。假连续性不是。
拼接前先分类目标输出：
| 类型 | 定义 | 拼接约束 |
|---|
| Montage | 显式多镜头序列 | 异源片段正常；转场可见且有意 |
| Pseudo-one-shot | 伪一镜到底 / 连续动作 | 必须通过连续性检查（见 refs/continuity.md） |
核心边界：concat、xfade、crop、grading 是收尾工具，不是连续性修复工具。源片段不兼容时，后处理可以打磨接缝，但不能把它当作连续性的证明。
Seam Review Gate（多段 pseudo-one-shot 必过）
成片后、final render 前，逐接缝回答 5 问：
- 角色是否仍然是同一个？
- 环境是否仍然是同一个场景？
- 色温是否足够稳定？
- 镜头方向是否连贯？
- 运动是否暗示同一个动作，还是独立片段？
任一项 "否" → 不能宣称 pseudo-one-shot → 走降级路径（见 refs/continuity.md）。
详细的事前预测清单、降级路径和 15s 典型失败案例见 refs/continuity.md。
素材管理规范
目录结构
docs/videos/{project-name}/
├── asset-markers.md ← 素材标注表（operator + 主执行猫共同编辑）
├── video-spec.json ← segment contract（主执行猫生成）
├── voice-script.md ← 配音剧本（主执行猫草稿 + operator确认）
└── assets/ ← 原始素材（gitignore, 仅本地）
├── 1-xxx.mov
├── 2-xxx.mov
└── ...
素材压缩标准（入库前）
ffmpeg -i input.mov -c:v libx264 -crf 23 -c:a aac -b:a 128k output.mp4
粗标格式（operator填）
时间 | 画面内容
0:00 - 0:50 | operator在打字
0:50 - 1:20 | Ragdoll开始回复，1:20 Maine Coon跟上
retiming 策略优先级
当配音长度和画面长度不匹配时，按以下优先级选择策略：
| 优先级 | 策略 | 说明 | 适用场景 |
|---|
| 1 | TRIM | 裁剪多余部分 | 画面比配音长 |
| 2 | FREEZE_STYLIZED | 定格末帧 + 毛玻璃/排版 | 配音比画面长，差距小 |
| 3 | B_ROLL | 插入空镜/截图/动效 | 配音比画面长，差距大 |
| 4 | SLOW_MO | 适度降速（≥0.7x） | 仅当画面本身适合慢放 |
| 5 | LOOP | 往复循环 | 最后手段 |
绝对不允许 <0.7x 的慢放。 如果需要填充超过 30% 的时间差，必须用 B_ROLL 或 FREEZE_STYLIZED。
常见错误
| 错误 | 修正 |
|---|
| TTS 逐段切碎生成 | 完整剧本全局配音，forced alignment 分段 |
| 赌 TTS 原生 timestamps | 用 Qwen3-ForcedAligner / WhisperX |
| 画面不够就暴力慢放 | 按 retiming 优先级处理 |
| 没压缩就用原始素材 | 入库前统一压缩（CRF 23） |
| segment contract 扁平不分层 | 4 层：source/narration/render/control |
| 加速后沿用原始时间轴切段 | 加速会压缩时长，后续段的起始时间必须重新计算。 例：A 段原 130s 以 2x 输出 65s，B 段在 final timeline 从 65s 开始而非 130s。用 output duration 逐段累加，不要用 source timestamps 直接拼 |
| 只加速长等待段忽略短等待 | 分段不够细时，"Thinking"状态可能散落在多个区间里。逐段审素材，把所有等待态都标出来分别处理 |
视频预览（Console 内联播放）
生成的视频必须在 Console 中内联可看，不要只贴 URL 或本地路径。
优先级
- 本地终稿 /
/uploads/... URL → 优先用 kind:"file" rich block，mimeType:"video/mp4"。Web UI 会直接渲染内联 <video> 播放器，并进入 artifact 索引
- 外部直链 URL（如云端生成结果）→ 可直接发
kind:"file"；若你明确要 autoplay muted，再退回 html_widget + <video>
- 只有工作区本地文件、还没可访问 URL → 先放到
/uploads/...，再发 rich block；不要直接贴源码路径
示例：优先用 file rich block
cat_cafe_create_rich_block({
block: JSON.stringify({
id: "video-<唯一标识>",
kind: "file",
v: 1,
url: "/uploads/final-cut.mp4",
fileName: "final-cut.mp4",
mimeType: "video/mp4"
})
})
示例：外部直链需要 autoplay 时再用 html_widget
cat_cafe_create_rich_block({
block: JSON.stringify({
id: "video-<唯一标识>",
kind: "html_widget",
v: 1,
title: "视频标题",
height: 420,
html: "<video controls autoplay muted playsinline style='width:100%;max-width:720px;border-radius:12px'><source src='<resultUrl>' type='video/mp4'></video>"
})
})
注意事项
file rich block 保证的是内联播放器；如果你要强制自动播放，再考虑 html_widget + 外部直链- 本地视频目前没有图片那样的自动发布合约；要想稳定显示，先显式放到
/uploads/...
- 如果
create_rich_block 返回 stale_ignored，说明回调凭据过期（见 #1092），可尝试在消息文本中嵌入 ```cc_rich 格式作为降级
- 多段视频先用 FFmpeg 拼接成完整文件，再用一个 rich block 播放最终版
技术栈
| 层 | 组件 | License |
|---|
| 渲染 | Remotion v4（Phase 1）/ FFmpeg（底层） | Remotion License / LGPL |
| TTS | CosyVoice（已有猫猫声线） | Apache-2.0 |
| 对齐 | Qwen3-ForcedAligner（首选）/ WhisperX（备选） | Apache-2.0 / BSD-2 |
| 队列 | BullMQ（Phase 2 引入） | MIT |
| 切分 | PySceneDetect（Phase 3 路径 A） | BSD-3 |
| VLM | Qwen2.5-VL-3B（Phase 3 路径 A） | Apache-2.0 |
Next Step
路径 B 完整流程跑通后 → quality-gate（自检）→ request-review（QA/审查猫审音画，视觉把关猫审节奏）
