Video-Gen 项目族交接文档

01 · GitHub 仓库总览

项目族共包含 6 个 Git 仓库，按重要程度排列如下：

02 · 整体架构与技术栈

核心文件

依赖

• FFmpeg 6.0+ — 视频拼接、转场、调色、音频混合的核心
• Python 3.9+ + httpx — 异步 HTTP 调用各 AI API
• Gemini (google-genai) — 图片生成、视觉分析、TTS 兜底
• Suno API — BGM 音乐生成
• ElevenLabs — 高质量 TTS 旁白（优先），Gemini TTS 兜底

设计理念

Director Agent 模式：SKILL.md 定义了一个 "导演 Agent" 的完整行为规范。Agent（Claude/其他 LLM）读取 SKILL.md 后，按 Phase 0→5 顺序与用户交互、调用 CLI 工具、最终交付成品视频。

核心原则：灵活规划 + 稳健执行。规划阶段（Phase 1-3）产出结构化 JSON，执行阶段（Phase 4-5）由 JSON 驱动，确保可复现。

03 · 核心工作流 (Phase 0–5)

视频片段生成 → 音乐生成 → 旁白生成（如有）→ 进入 Phase 5

拼接（自动归一化）→ 旁白插入 → 转场 → 调色 → 配乐混音 → 输出 final.mp4

04 · 后端选择与决策逻辑

四大后端能力对比

场景驱动选择决策表

05 · 降级链路与容错策略

降级路径

Seedance → Kling-Omni 降级要点

这不是简单的字段替换！Seedance 是 scene-level（一次调用生成整个 scene），Kling-Omni 是 shot-level（逐 shot 调用）。降级需要：

1. 保留 storyboard 的创意设计（风格、时长、角色等）
2. 为每个 shot 新增 image_prompt 和 frame_path
3. 先用 Gemini 为每个 shot 生成分镜图
4. 再逐 shot 调用 Kling-Omni API

API 错误类型处理

06 · 中文版 vs 英文版差异

两个版本核心 flow 相同（Phase 0-5），代码完全一致。截至 2026-04-16 SKILL.md 文档已全部对齐。

已对齐项（全部完成）

仍存在的差异（预期差异，无需对齐）

07 · 历史踩坑记录（重点！）

• 高危 Seedance 真人审核不稳定 → content_policy_violation
  Seedance 后端对真人照片的内容审核行为极不稳定：相同的真人参考图，有时通过有时被拒。真人写实风格（visual_style=realistic）+ 角色参考图组合会偶发触发 content_policy_violation。
  ✅ 解决方案：保守策略，realistic + 有参考图 → 统一禁用 Seedance，强制走 Kling-Omni。
• 高危 各 Provider 的真人支持和生成速度差异巨大

  Provider + 后端	真人支持	生成速度	备注
  fal Seedance	✗ 完全不支持	~2 min	速度快但真人一律被拒
  piapi Seedance	时灵时不灵	很慢，成功率低	偶尔通过，不可依赖
  fal Kling-Omni / Kling	✓	~8 min	稳定但等待时间长

  fal 的 Seedance 虽然速度最快，但真人场景完全不可用。piapi 的 Seedance 表现不稳定，实测成功率很低且生成极慢。fal 的 Kling 系列真人支持稳定，但单次生成约 8 分钟，并发时需注意超时设置。
  ✅ 解决方案：真人场景直接走 Kling-Omni（fal），预留 8-10 分钟超时；Seedance 只用于非真人虚构内容，优先走 fal（速度快）。
• 高危 Kling 生成视频经常没有声音（已修复）
  根因：--audio 参数定义为 store_true（默认 False），Agent 不传就是静音。而 Seedance 的 FalSeedanceClient.submit_task 方法签名默认 generate_audio=True 且 CLI 未覆盖，所以 Seedance 天然有声音。这个不对称导致从 Seedance 切到 Kling 后 Agent 不会主动加 --audio，视频就没声了。
  
  更深层问题：storyboard.json 的 audio.enabled 字段在代码里从未被读取（只读了 aspect_ratio），所以即使分镜标了 enabled: true，Kling 调用依然静音。
  ✅ 解决方案（4/16 已修复）：--audio 改为默认开启（default=True），新增 --no-audio 用于显式关闭。所有后端行为统一：默认带声音，不需要声音时用 --no-audio，后续剪辑阶段可去掉音轨。
• 高危 FFmpeg amix 不加 normalize=0 会压爆音量
  FFmpeg 的 amix 滤镜默认开启自动均一化（normalize=1），会把所有音轨音量压到相同水平，导致 BGM 音量与人声一样大，人声被盖掉，最终视频完全不能用。
  ✅ 解决方案：mix_audio() 已硬编码 normalize=0。绝对不能移除。
• 高危 Seedance scene-level 分镜图误用在 Kling-Omni shot-level 链路
  Seedance 的分镜图是 scene-level（一张图覆盖多 shots），Kling-Omni 需要 shot-level（每 shot 一张图）。如果在 Seedance → Kling-Omni 降级时直接复用 Seedance 的 scene 分镜图，会导致所有 shots 画面雷同。
  ✅ 解决方案：Phase 4 启动前有链路一致性检查，检测 Kling-Omni 的 shot 是否都有 image_prompt 和 frame_path。不通过会回退到 Phase 3 重写。
• 高危 Seedance 降级到 Kling-Omni 不能做简单字段迁移
  Seedance 一次 API 调用生成整个 scene（智能切镜），降级到 Kling-Omni 后需要逐 shot 调用，必须重新走完整流程：为每个 shot 设计 image_prompt → 生成分镜图 → 逐 shot 调用 API。不能简单替换 backend 字段。
  ✅ 解决方案：保留创意设计，按 Omni 标准重新规划每个 shot 的 image_prompt、frame_path，重新走 Omni 流程。
• 中 一致性漂移："垂杨柳" → "古树" → "老树"
  LLM 生成多个 shots 时，关键场景元素的描述会发生语义漂移。比如 spatial_setting 是"垂杨柳树下"，到后面的 shots 就变成"古树下""老树旁"。这不是关键词匹配能抓到的问题，需要语义理解。
  ✅ 解决方案：Phase 3 Step 4 的自动一致性 Review 会检测并修复这类漂移。
• 中 参考图尺寸不合规导致 API 报错
  各后端对参考图尺寸有要求。太小（<720px）导致生成质量差，太大（>2048px）直接被 API 拒绝。
  ✅ 解决方案：Phase 4 执行前自动检查并 resize（最小边 → 1280px，最大边 → 2048px），添加 _resized 后缀。
• 中 音乐生成不传 --creative 导致用默认风格
  video_gen_tools.py music 如果不传 --creative 参数，不会读取 creative.json 里的 music.prompt 和 music.style，生成的音乐和视频风格完全不搭。
  ✅ 解决方案：SKILL.md 已明确要求必须传 --creative creative/creative.json。
• 中 concat 不传 --storyboard 导致宽高比错误
  video_gen_editor.py concat 需要从 storyboard.json 读取 aspect_ratio 来确定输出尺寸。不传会用默认值，最终视频可能被拉伸。
  ✅ 解决方案：SKILL.md 已明确要求 concat 必须传 --storyboard。
• 中 Veo3 时长只支持 4/6/8s 枚举，不能传其他值
  Veo3 不像 Seedance（4-15s 任意整数），只接受 4、6、8 三个固定值。传 5s 或 10s 会报错。
  ✅ 解决方案：validate 命令会检查 Veo3 的时长是否为枚举值。两个版本均已将 Veo3 标记为 Deprecated。
• 中 Seedance 时长必须在 4-15s 范围，超出会静默失败
  如果 scene 总时长超过 15s 或低于 4s，Seedance API 不会明确报错，而是返回异常结果或超长等待后超时。
  ✅ 解决方案：validate 命令专门检查 Seedance 的 scene 总时长范围。
• 低 Gemini 生成参考图时，重要人物应放在 --reference 列表的最后
  多参考图调用 Gemini 生成分镜图时，--reference 列表中靠后的图片权重更高。主角参考图放前面可能导致配角面部特征抢占主角。
  ✅ 解决方案：SKILL.md 的 Path B 章节已明确"参考图顺序很重要，重要人物放后面"。
• 低 视频片段拼接时音轨丢失
  部分 AI 生成的视频片段带同期声/音效，如果拼接时不保护原始音轨，这些音频会丢失。无声片段和有声片段混合时可能导致音画不同步。
  ✅ 解决方案：editor 的 concat 已实现音频保护，无声片段自动补静音轨。
• 低 fal vs piapi 引用格式不同
  Seedance 的两个 provider 引用图片的格式不同：fal 用 @Image1（大写 I），piapi 用 @image1（小写 i）。写错大小写会导致图片引用失效。
  ✅ 解决方案：工具层已做自动转换，Agent 统一用 @Image1 即可。
• 中 API 文件上传复杂 — 图片走 base64，视频必须先传 URL
  所有视频生成 API 的文件上传机制都比较复杂。图片可以 base64 编码后本地直接上传（工具层已封装）；但视频文件只能以公开可读的 URL 形式传入，不支持本地路径或 base64。因此需要一个文件托管服务，先将视频上传拿到 URL，再传给 API。
  ✅ 解决方案：video-understanding 仓库中有完整的文件上传代码示例（FileService 上传 → 获取 URL → 传给 Gemini 分析），可直接参考。

08 · 潜在风险与待解决项

09 · 周边工具链

video-gen-test — 自动化测试框架

• 用途：批量测试分镜设计能力，验证后端选择策略
• 执行方式：/video-gen-test 或 /video-gen-test --cases 1,3,5
• 测试范围：Phase 0-3（到分镜设计为止，不执行实际生成）
• 并发：最多同时 3 个 Agent，每个 Case 10 分钟超时
• 自动回答：所有交互问题预设答案（电影感/30s/9:16/AI生成BGM/不要旁白/AI生成参考图）
• 输出：~/vico-test-results/{timestamp}/report.html
• 测试用例文件：/Users/taylor.zhoush/Documents/Obsidian Vault/自动测试case.md
• 素材基础路径：/Users/taylor.zhoush/Downloads/00-素材库/测试集/

video-agent-monitor — 多媒体 Skill 监控

• 用途：定期检索 GitHub / Skillhub / Clawhub 上的新项目/Skill
• 覆盖领域：视频生成、图像生成、TTS 语音、音乐生成
• 输出：reports/ 目录下的 today.md / all-projects-list.md / index.html
• 触发：/AI媒体监控 或 /check media agents，也可定时执行

video-understanding — AI 视频拉片工具

• 用途：用 Gemini 深度分析视频内容，提取镜头语言，产出专业剧本
• 触发方式：/video-understanding <视频URL或本地路径>，或说"拉片""分析视频""解析这个视频"
• 支持模型：gemini-3.1-pro-preview（最强）/ gemini-2.5-pro（默认）/ gemini-2.5-flash（快速）
• 核心流程：配置检查 → 视频上传（本地文件时）→ Gemini 分析 → 剧本输出
• 产出：分幕剧本（人物表 + 拉片要点 + 对白/OS + 动作描述 + 镜头语言总结）
• 与 video-gen 联动：/video-gen ~/video-understanding-projects/{project}/output/script.md
• API 配置：MIGOO_API_KEY + MIGOO_BASE_URL（必需），FILE_SERVICE_URL（可选，本地视频上传）

video-gen-veo3 — Veo3 独立版（已归档）

• 早期独立开发的纯 Veo 3.1 Fast 版本
• Veo3 在主仓库中已标记 Deprecated，不再作为可用后端
• 曾有独有特性：Veo3 原生音频生成、4k 分辨率支持
• 不再维护，仅作为历史参考

10 · API Keys 与环境变量

所有 key 既可以通过环境变量设置，也可以通过 config.json 持久化（setup --set-key 命令）。config.json 不应提交到 Git。

11 · 项目文件结构

Skill 仓库结构

video-gen/ (or video-gen-en/)
├── SKILL.md                    # Skill 定义（Phase 0-5 全流程）
├── video_gen_tools.py          # API 调用 CLI 工具
├── video_gen_editor.py         # FFmpeg 剪辑 CLI 工具
├── config.json                 # API Key 持久化（不进 Git）
└── reference/
    ├── storyboard-spec.md      # 分镜规范、JSON 格式
    ├── prompt-guide.md         # Prompt 编写规范
    ├── backend-guide.md        # 后端选择决策树
    ├── consistency-guide.md    # 一致性审查规范
    └── api-reference.md        # CLI 参数速查

运行时项目目录

~/video-gen-projects/{project_name}_{timestamp}/
├── state.json                  # 项目状态（Phase 进度）
├── personas.json               # 角色注册表
├── materials/
│   └── personas/               # 角色参考图
├── analysis/
│   └── analysis.json           # 素材分析结果
├── creative/
│   ├── creative.json           # 创意方案（含 backend_selection）
│   └── decision_log.json       # 决策记录
├── storyboard/
│   └── storyboard.json         # 分镜脚本
├── generated/
│   ├── frames/                 # 生成的分镜图
│   ├── videos/                 # 生成的视频片段
│   ├── music/                  # 生成的音乐
│   └── narration/              # 生成的旁白
└── output/
    └── final.mp4               # 最终视频

12 · 常见问题 FAQ

python video_gen_tools.py check    # 检查依赖和 API key
python video_gen_tools.py setup    # 查看所有 provider 状态

# 跑所有 Case
/video-gen-test

# 只跑指定 Case
/video-gen-test --cases 1,3,5

{
  "seedance_disabled": true,         // 是否禁用 Seedance
  "preferred_backend": "kling-omni", // 推荐后端
  "reason": "真人参考图会触发 Seedance content_policy_violation"
}