OpenMontage 深度解析：全球首个开源 Agent 视频制作系统，从架构原理到生产级实战

一、引言：当你的 AI 编程助手变成视频制片人

如果你对 AI 生成视频的印象还停留在「几张静态图配上生硬的缩放动画」或者「一段模糊的、时长只有几秒的诡异片段」，那么 OpenMontage 的出现，可能会彻底改变你的看法。

这不是又一个简单的「文生视频」API 封装工具，而是一个完整的、开源的、由 AI Agent 驱动的视频生产系统。它的核心思想非常直接：你只需要用自然语言描述你想要什么视频，剩下的所有事情——从主题研究、撰写脚本、生成视觉资产、剪辑、配音、配乐，到最终合成渲染——全部交给你的 AI 编程助手（比如 Claude Code、Cursor）去执行。

OpenMontage 在 GitHub 上迅速攀升至 Trending 榜首，被称为「第一个开源的、智能体驱动的视频生产系统」。截至 2026 年 6 月，它拥有：

• 12 条专业制作管线（pipelines）
• 52 个生产工具（tools）
• 500+ Agent 技能（skills）
• 支持 14 个视频生成提供商（FLUX、Veo3、Kling、Runway 等）
• 内置 Remotion 动画引擎 + FFmpeg 渲染管线
• 从完全免费（零 API 密钥）到完整配置（约 $0.69/部广告片）的灵活成本方案

本文将深入拆解 OpenMontage 的三层知识架构、智能体工作流机制、生产级部署路径，以及如何从零开发自己的自定义管线。

二、背景：视频生产的「巴别塔困境」与 Agent 的破局思路

2.1 传统视频生产的工具碎片化问题

在 OpenMontage 出现之前，一个标准的视频制作流程通常需要横跨多个工具：

每个工具都有自己的界面、格式、API，串联这些环节需要大量人工介入。创作一件视频内容，80% 的时间花在了「搬运数据」和「协调格式」上，真正的创意工作反而被挤压到边缘。

2.2 为什么是 AI Agent 破局？

2025-2026 年，AI Agent 生态迎来了爆发式增长。Claude Code、Cursor、GitHub Copilot 等 AI 编程助手已经具备了以下关键能力：

• 理解复杂指令：能够解析自然语言描述的模糊需求，拆解为具体步骤
• 调用工具执行：能够通过代码或 API 操作各种外部工具
• 多阶段规划：能够将一个长期目标拆解为多个阶段，并在每个阶段进行自我审查
• 读写文件系统：能够管理项目中的大量中间资产（脚本、素材、元数据）

这些能力，恰好就是视频制作流程中「人工协调」环节最需要的。OpenMontage 的核心洞察是：我们不需要造一个新的 AI 视频模型，我们只需要把我们手头已有的 AI 编程助手，武装成一名合格的视频制片人。

2.3 OpenMontage 与其他 AI 视频工具的本质区别

三、核心架构：三层知识体系让 Agent 真正「懂」视频制作

3.1 第一层：工具体系（tools/ & pipeline_defs/）—— 解决「有什么」

tools/ 目录包含近 50 个 Python 工具，覆盖了视频生产的完整环节：

# tools/generate_image.py（图像生成）
# tools/generate_video.py（视频生成）
# tools/text_to_speech.py（TTS 配音）
# tools/add_subtitles.py（字幕生成）
# tools/add_music.py（背景音乐）
# tools/enhance_footage.py（素材增强）
# tools/analyze_video.py（视频分析）
# tools/compose_final.py（最终合成）
# ...（共 52 个）

每个工具都是一个标准的 Python 函数，接受明确的输入输出定义，并附带元数据（描述、成本、延迟、质量评分等）：

# tools/generate_image.py 示例
def generate_image(
    prompt: str,
    style: str = "cinematic",
    duration_px: int = 1920,
    provider: str = "auto"  # auto/sdxl/flux/dalle
) -> dict:
    """
    Generate a static image from text prompt.
    
    Returns:
        {
            "path": "/path/to/image.png",
            "provider": "flux",
            "cost_usd": 0.02,
            "quality_score": 0.91
        }
    """
    ...

pipeline_defs/ 目录下的 YAML 文件定义了 12 种视频生产流水线。每条流水线是一个完整的「项目类型剧本」：

# pipeline_defs/documentary_montage.yaml
name: Documentary Montage
description: >
  基于真实库存素材的纪录片式蒙太奇。
  从语义搜索到剪辑合成，全程模拟专业剪辑师思维。

stages:
  - name: research
    tools: [web_search, semantic_search_pexels]
    checkpoint: true  # 人工审核点
    approval_required: false

  - name: asset_curation
    tools: [clip_analysis, semantic_filter, rank_by_relevance]
    checkpoint: true
    approval_required: true  # 关键创意决策需要人工批准

  - name: script
    tools: [llm_rewrite, format_checker]
    checkpoint: false

  - name: assembly
    tools: [ffmpeg_concat, add_subtitles, add_music]
    checkpoint: false

  - name: render
    tools: [ffmpeg_encode, quality_check]
    checkpoint: true
    approval_required: true

success_criteria:
  min_duration: 90  # 秒
  max_duration: 300
  no_slideshow_risk: true  # 必须有运动画面
  audio_level_db: -14 to -8

这 12 条流水线涵盖了主流视频类型：

3.2 第二层：技能体系（skills/）—— 解决「怎么用」

skills/ 目录包含 120+ 个 Markdown 技能文件，这是 OpenMontage 最独特的创新之一。它将「视频制作专业知识」封装为 AI Agent 可读的指令集。

<!-- skills/pipelines/research.md -->
# 研究阶段（Research Stage）

## 阶段目标
在正式制作前，全面收集与主题相关的资料，
确保脚本有深度、素材有广度。

## 关键步骤
1. **主题分解**：将主主题拆解为 3-5 个子话题
2. **多源搜索**：
   - YouTube：搜索相关视频获取视觉灵感
   - Reddit：了解大众讨论和真实观点
   - 学术资料：arXiv、维基百科获取准确性保障
3. **竞争分析**：搜索同类视频，找出差异化切入点
4. **素材预判**：提前识别可能的高质量素材镜头

## 可用工具
- `web_search`：通用搜索
- `youtube_search`：视频灵感
- `arxiv_search`：学术支撑

## 产出物
- `research_summary.md`：包含关键事实、引用、视觉方向
- `asset_mood_board.md`：素材风格参考

## 自审清单
- [ ] 至少覆盖 3 个不同角度
- [ ] 有具体数据/引用支撑核心论点
- [ ] 确认了主要素材的可用性

skills/ 目录结构：

skills/
├── pipelines/          # 流水线各阶段导演指南
│   ├── research.md
│   ├── script.md
│   ├── asset_generation.md
│   ├── editing.md
│   ├── render.md
│   └── review.md
├── creative/           # 创意技巧库
│   ├── pacing.md        # 节奏控制
│   ├── transition_style.md  # 转场风格
│   └── music_matching.md   # 音乐匹配
├── tools/              # 各工具使用规范
│   ├── ffmpeg_advanced.md
│   ├── remotion_basics.md
│   └── tts_providers.md
└── quality/            # 质量标准
    ├── slideshow_detector.md
    ├── audio_normalization.md
    └── frame_validator.md

这相当于给 AI Agent 配备了一套完整的「职业培训教材」。它不仅告诉 Agent「用什么工具」，更告诉它「在什么场景下用什么工具、以什么顺序用、产出物应该是什么样子」。

3.3 第三层：知识包（.agents/skills/）—— 解决「为什么」

.agents/skills/ 目录包含 47 个外部技术知识包，深度讲解底层技术原理。当某个工具声明它依赖某个 Layer 3 技能时，AI Agent 会先去阅读相关知识文档，理解工具背后的原理，从而做出更合理的决策。

<!-- .agents/skills/stable_diffusion_depth.md -->
# Stable Diffusion 进阶：深度理解采样器与图像一致性

## 采样器选择指南
| 采样器 | 速度 | 质量 | 适合场景 |
|--------|------|------|---------|
| Euler | 快 | 中 | 快速草稿 |
| DPM++ 2M Karras | 中 | 高 | 精细创作 |
| DDIM | 慢 | 最高 | 风格一致性要求高 |

## CFG 参数的本质
CFG 控制生成图像与提示词的「贴合度」：
- 1-5：更创造性，但可能偏离主题
- 7-9：平衡点，OpenMontage 默认值
- 10-15：高度忠实，但可能过饱和

## 批量生成策略
使用相同的 seed + 不同的 prompt可以实现：
- 系列图像（场景一致、变化丰富）
- 角色多角度（面部一致性通过 refiner 控制）

三层架构的设计哲学：让 AI Agent 的每一步操作都有据可依、有标准可循、有知识可查。这不是简单的「工具调用」，而是将人类视频制作经验系统化、知识化后，灌输给 AI Agent。

四、智能体工作流：端到端制片周期深度解析

4.1 整体流程：一个「自主 + 受控」的制片循环

用户指令
    │
    ▼
┌─────────────────────────────────────────────┐
│  1. 解析与规划（Parse & Plan）               │
│     - 匹配流水线（Pipeline Matching）         │
│     - 阶段拆分（Stage Decomposition）         │
│     - 资源预判（Resource Planning）           │
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────┐
│  2. 分阶段执行（Stage Execution）            │
│     - 读取阶段指南（skills/pipelines/*.md）  │
│     - 调用工具（tools/*.py）                 │
│     - 自我审查（Review Check）                │
└─────────────────────────────────────────────┘
    │
    ▼ (循环每个阶段)
┌─────────────────────────────────────────────┐
│  3. 检查点保存（Checkpoint）                │
│     - JSON 快照（含决策日志）                │
│     - 人工审批点（Approval Gate）            │
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────┐
│  4. 渲染与质检（Render & QA）               │
│     - 预合成验证（Pre-compose Check）        │
│     - FFmpeg 编码                            │
│     - 渲染后自审（Post-render Review）        │
└─────────────────────────────────────────────┘
    │
    ▼
最终视频 + 完整审计日志

4.2 智能决策：评分制提供商选择器

当 Agent 需要选择一个工具提供商时（比如图像生成用哪个 API），它使用内置的多维度评分器：

# 内置评分维度（7 个）
PROVIDER_SCORING_DIMENSIONS = [
    "task_match",      # 任务匹配度（0-1）
    "output_quality",  # 输出质量评分（历史数据）
    "cost_efficiency", # 成本效率（美元/单位）
    "latency",         # 响应延迟（秒）
    "reliability",     # 服务稳定性（uptime %）
    "safety",          # 内容安全过滤
    "context_window"   # 上下文窗口大小
]

def score_provider(provider: str, task: dict) -> float:
    scores = {dim: get_dimension_score(provider, dim, task)
               for dim in PROVIDER_SCORING_DIMENSIONS}
    weights = get_task_weights(task["type"])  # 不同任务权重不同
    return sum(scores[d] * weights[d] for d in scores)

# 示例：动画解说任务 vs 纪录片蒙太奇
animation_weights = {
    "task_match": 0.30,
    "output_quality": 0.25,
    "cost_efficiency": 0.20,
    "latency": 0.10,
    "reliability": 0.10,
    "safety": 0.03,
    "context_window": 0.02
}

documentary_weights = {
    "task_match": 0.25,
    "output_quality": 0.30,
    "cost_efficiency": 0.15,
    "latency": 0.05,
    "reliability": 0.15,
    "safety": 0.05,
    "context_window": 0.05
}

所有决策都会写入审计日志：

{
  "decision_id": "img_provider_001",
  "timestamp": "2026-06-27T10:00:00Z",
  "decision_type": "provider_selection",
  "context": {
    "task": "generate_key_visual",
    "pipeline": "animated_explainer",
    "scene": "intro"
  },
  "options_scored": [
    {"provider": "flux", "score": 0.847, "reasoning": "高任务匹配度+合理成本"},
    {"provider": "dalle3", "score": 0.791, "reasoning": "质量高但成本过高"},
    {"provider": "sdxl_local", "score": 0.723, "reasoning": "免费但质量不稳定"}
  ],
  "selected": "flux",
  "confidence": 0.847,
  "alternatives_considered": true
}

4.3 质量关卡：如何杜绝「PPT 式幻灯片」

这是 OpenMontage 最实用的工程创新之一。传统的 AI 视频生成方案最大的质量问题，就是输出「只是图片轮播 + 缩放动画」，毫无视频感。OpenMontage 为此设计了三道质量关卡：

关卡 1：预合成验证（Pre-compose Check）

在正式渲染前，Agent 会运行一套验证逻辑：

def pre_compose_validator(storyboard: Storyboard) -> ValidationResult:
    issues = []

    # 检查 1：运动镜头覆盖率
    motion_ratio = count_motion_shots(storyboard) / len(storyboard.scenes)
    if motion_ratio < 0.4:
        issues.append({
            "severity": "error",
            "type": "slideshow_risk",
            "message": f"运动镜头比例仅 {motion_ratio:.0%}，低于 40% 阈值",
            "suggestion": "将部分静态图替换为视频片段"
        })

    # 检查 2：转场多样性
    transitions = [s.transition for s in storyboard.scenes]
    unique_transitions = len(set(transitions))
    if unique_transitions < 3:
        issues.append({
            "severity": "warning",
            "type": "transition_repetition",
            "message": f"仅 {unique_transitions} 种转场，可能单调",
            "suggestion": "引入淡入淡出、模糊切换等更多转场"
        })

    # 检查 3：时长合理性
    total_duration = sum(s.duration for s in storyboard.scenes)
    if total_duration < 30:
        issues.append(...)
    if total_duration > 600:
        issues.append(...)

    # 检查 4：叙事逻辑
    narrative_coherence = score_narrative_flow(storyboard)
    if narrative_coherence < 0.6:
        issues.append(...)

    return ValidationResult(pass=len([i for i in issues if i["severity"] == "error"]) == 0,
                           issues=issues)

关卡 2：渲染后帧验证（Post-render Frame Validation）

def post_render_validator(output_path: str) -> QAReport:
    report = QAReport()

    # ffprobe 验证文件完整性
    probe = run_ffprobe(output_path)
    report.integrity = probe["format"]["duration"] > 0

    # 关键帧采样检查（黑屏/花屏）
    sample_frames = extract_key_frames(output_path, n=10)
    for frame in sample_frames:
        brightness = calculate_brightness(frame)
        if brightness < 10 or brightness > 245:
            report.add_issue("anomalous_frame", frame)

    # 音频电平检查
    audio_levels = analyze_audio_levels(output_path)
    if max(audio_levels) < -40:
        report.add_issue("silent_audio")

    # 字幕准确性（可选）
    if has_subtitles(output_path):
        subtitle_coverage = check_subtitle_coverage(output_path)
        report.subtitle_ok = subtitle_coverage > 0.95

    return report

关卡 3：AI 自审（Agent Self-Review）

<!-- skills/quality/self_review.md -->
## 渲染后自审阶段

Agent 需要对最终成片进行「观众视角」的审核：

1. **节奏审查**：观看全片，标记「拖沓区」和「仓促区」
2. **情感曲线**：评估情绪是否随叙事推进有合理起伏
3. **信息密度**：确认关键信息有足够停留时间（≥3秒）
4. **风格一致性**：视觉风格、音乐风格是否统一

如果发现问题：
- 小问题（节奏轻微不均）→ 自动微调时长
- 中等问题（某片段质量不佳）→ 重新生成该片段
- 大问题（整体方向偏离）→ 回退到上一检查点，重新审批

4.4 两种视频路径：AI 生成 vs. 真实素材

OpenMontage 最令人惊艳的特性之一，是它提供了两条截然不同的视频生产路径：

路径 A：AI 生成图像 + 动画（低成本 / 零 API 方案）

自然语言需求
    │
    ▼
Stable Diffusion / FLUX 生成图像序列
    │
    ▼
Remotion 动画引擎（添加运动效果）
    │
    ▼
物理引擎模拟（重力、碰撞、流动）
    │
    ▼
FFmpeg 编码 + 字幕 + 配音
    │
    ▼
成品视频

核心工具链：

# 图像生成 → Remotion 动画 → 物理模拟 → FFmpeg 合成
generate_image(prompt="太空站对接场景", style="photorealistic")
  ↓
remotion_add_parallax(image, depth_map, speed=1.5)
  ↓
remotion_add_physics(scene, gravity=True, particles=True)
  ↓
ffmpeg_concat_with_transitions(frames, transitions=["fade", "whip_pan"])
  ↓
add_tts(script, voice="professional_narrator")
  ↓
add_background_music(mood="epic", avoid_vocals=True)

路径 B：真实库存素材剪辑（颠覆性 / 真正免费方案）

自然语言需求
    │
    ▼
CLIP 语义搜索（Pexels, Archive.org, NASA, WikiMedia）
    │
    ▼
构建真实视频片段素材库（基于语义相似度）
    │
    ▼
Agent 像剪辑师一样挑选、剪辑、排列镜头
    │
    ▼
AI 生成配音 / 字幕
    │
    ▼
成品视频（100% 真实运动画面）

这是 OpenMontage 最具颠覆性的设计——你可以在不花一分钱 API 调用费的情况下，产出一部由真实运动画面构成的纪录片式短片。CLIP 模型（OpenAI 的对比语言-图像预训练模型）负责语义层面的素材匹配，确保选中的视频片段与叙事主题高度相关。

五、从零到生产：环境搭建与首个视频实战

5.1 基础环境准备

OpenMontage 依赖三个核心环境：

# 1. Python 3.10+（使用 pyenv 管理）
pyenv install 3.12.0
pyenv local 3.12.0
python --version  # Python 3.12.0

# 2. FFmpeg（最关键依赖，macOS 用 Homebrew）
brew install ffmpeg
ffmpeg -version  # 确认安装成功

# 3. Node.js 18+（Remotion 需要）
brew install node
node --version  # v22.x.x
npm --version

5.2 一键安装（推荐）

git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

make setup 会自动：

1. 创建 Python 虚拟环境（venv/）
2. 安装 Python 依赖（pip install -r requirements.txt）
3. 安装 Node.js 依赖（npm install，Remotion 部分）
4. 初始化配置文件（config.yaml）
5. 下载预训练模型（首次运行可能需要）

如果 make setup 失败，逐个排查：

# 常见问题 1：Python 版本不对
pyenv versions                    # 查看已安装版本
pyenv install 3.12.0             # 如未安装

# 常见问题 2：FFmpeg 缺失
which ffmpeg || brew install ffmpeg

# 常见问题 3：npm install 失败（网络问题）
export NPM_REGISTRY=https://registry.npmmirror.com
npm install

# 常见问题 4：Remotion 许可
npx remotion license    # 如需付费功能

5.3 配置文件详解

# config.yaml
agent:
  provider: "claude-code"   # claude-code | cursor | copilot
  model: "claude-sonnet-4"  # 模型选择
  approval_mode: "smart"    # auto | smart | manual
  # smart 模式：低风险决策自动通过，高风险创意决策需人工批准

pipelines:
  default: "animated_explainer"
  available:
    - animated_explainer
    - documentary_montage
    - character_animation
    # ...

providers:
  image_generation:
    primary: "flux"        # 默认提供商
    fallback: "sdxl_local" # 备用方案
    budget_mode: true      # 开启成本控制

  video_generation:
    primary: "runway"
    quality_threshold: 0.85

  tts:
    primary: "elevenlabs"
    voice_presets:
      narrator: "professional_male"
      character: "young_female"
    free_fallback: "azure_tts"  # 免费备用

  music:
    primary: "epidemic_sound"
    free_only: true        # 强制只用免费音乐源

assets:
  free_sources:
    - pexels
    - archive_org
    - nasa
    - wikimedia_commons

  clip_model: "openai/CLIP-ViT-B/32"  # 语义搜索用的模型

quality:
  min_motion_ratio: 0.4    # 运动镜头最低占比
  slideshow_threshold: 0.3  # 超过此值触发警告
  max_cost_per_video: 5.0  # 美元，超出则降级方案

5.4 首次运行：制作你的第一个视频

第一步：在 AI 编码助手中安装 OpenMontage 技能

# 克隆到你的 AI 助手的 skills 目录
git clone https://github.com/calesthio/OpenMontage.git \
  ~/.claude/skills/openmontage

第二步：告知 AI 你的需求

# prompts/first_video.md

你是一个专业视频制作人。请使用 OpenMontage 技能，
为我的 YouTube 频道制作一个 2 分钟的动画解说视频。

主题：黑洞是如何形成的
风格：科普纪录片风格，适合科学爱好者
配音：男声，专业感
目标观众：18-35岁科学爱好者
片头：需要包含频道 Logo
片尾：包含订阅引导

请执行以下步骤：
1. 选择合适的流水线（animated_explainer）
2. 进行主题研究
3. 撰写脚本
4. 生成视觉资产
5. 剪辑合成
6. 添加配音和音乐
7. 最终渲染

每个关键阶段完成后请向我确认。

第三步：AI Agent 执行并等待审批

[Agent] 已选择「动画解说」流水线（animated_explainer）
[Agent] 开始研究阶段...
[Agent] 搜索 YouTube 相关视频 12 部
[Agent] 检索 arXiv 最新黑洞形成论文 5 篇
[Agent] ✓ 研究完成。已生成 research_summary.md

⏸️  检查点 #1 - 需要您审批
阶段：研究总结
产出物：research_summary.md
发现：黑洞形成有 3 种主要机制，请确认最关注哪一种：
  A. 恒星坍缩（大质量恒星死亡）
  B. 中子星碰撞合并
  C. 原始黑洞（宇宙早期形成）

请回复 A/B/C，或输入「继续」由您决定。
> 

第四步：查看中间产物并继续

审批通过后，Agent 会继续执行后续阶段。每个阶段的产出物（脚本分镜、素材选择、编辑时间线）都会保存到 output/project_name/ 目录：

output/blackhole_formation/
├── 00_research/
│   ├── research_summary.md
│   └── asset_mood_board.md
├── 01_script/
│   ├── script_draft.md
│   ├── approved_script.md      # 经您批准的版本
│   └── shot_list.yaml         # 分镜表
├── 02_assets/
│   ├── images/                 # 生成的图像
│   ├── footage/                # 下载的视频片段
│   └── audio/
│       ├── narration.mp3       # TTS 配音
│       └── background_music.mp3
├── 03_editing/
│   ├── timeline.json           # FFmpeg 时间线
│   └── review_approved.json
├── 04_render/
│   ├── raw_assembly.mp4       # 未压缩版本
│   └── final_1080p.mp4        # 最终成品
├── 05_qa/
│   └── qa_report.json         # 质检报告
└── decision_log.jsonl         # 完整决策审计日志

六、自定义管线开发：构建你的专属视频工厂

6.1 为什么需要自定义管线？

OpenMontage 的 12 条预设管线虽然覆盖面广，但每个创作团队的需求都是独特的：

• 电商团队可能需要「多产品展示 + 促销字幕 + 结尾 CTA」的专属流程
• 教育机构可能需要「分步骤演示 + 代码高亮 + 知识卡片」的教程管线
• 品牌方可能需要「广告语植入 + 品牌色规范 + 多尺寸输出」的标准化流程

6.2 自定义管线开发四步法

步骤 1：定义管线规范

# pipeline_defs/ecommerce_product_showcase.yaml
name: E-commerce Product Showcase
description: >
  电商产品展示视频。包含产品特写、开箱、功能演示、
  场景使用、促销 CTA 等标准化模块。

stages:
  - name: product_analysis
    description: 分析产品卖点，提取 3-5 个核心亮点
    tools: [web_search_product, llm_analyze]
    checkpoint: false

  - name: asset_planning
    description: 规划各模块所需素材
    tools: [generate_product_image, search_lifestyle_footage]
    checkpoint: true
    approval_required: true
    # 审批要点：确认核心卖点选择是否正确

  - name: filming_script
    description: 撰写分镜脚本
    tools: [llm_write_script, format_checker]
    checkpoint: true
    approval_required: true
    # 审批要点：脚本是否涵盖所有卖点，时间是否合适

  - name: asset_generation
    description: 生成/获取所有视觉资产
    tools: [generate_image, download_video, enhance_footage]
    checkpoint: false

  - name: editing
    description: 剪辑合成
    tools: [ffmpeg_concat, add_promo_overlay, add_cta_card]
    checkpoint: true
    approval_required: false

  - name: multi_format_render
    description: 多尺寸输出（横版/竖版/方形）
    tools: [ffmpeg_scale_square, ffmpeg_scale_portrait]
    checkpoint: false

success_criteria:
  min_duration: 30
  max_duration: 120
  includes_cta: true
  aspect_ratios: [16:9, 9:16, 1:1]

步骤 2：编写专用技能文件

<!-- skills/pipelines/ecommerce_filming_script.md -->
# 电商产品展示 - 分镜脚本规范

## 固定结构（不可省略）
每个视频必须包含以下标准化模块：

1. **Hook（前 3 秒）** [必需]
   - 痛点切入：「还在为 XXX 烦恼？」
   - 或效果展示：「使用前 vs 使用后」
   - 要求：引起共鸣，留住观众

2. **产品介绍（5-10 秒）** [必需]
   - 产品名称 + 核心定位
   - 一句话价值主张

3. **核心卖点展示（每个 8-15 秒）** [3-5 个]
   - 卖点标题（6 字以内）
   - 视觉演示（图片/视频）
   - 简短旁白（15-20 字）

4. **使用场景（5-10 秒）** [必需]
   - 生活方式类真实素材
   - 避免过度摆拍感

5. **促销 CTA（最后 5 秒）** [必需]
   - 价格信息（如有）
   - 行动号召：「立即购买」「点击链接」
   - 品牌 Logo 露出

## 时长分配参考（60 秒视频）
- Hook: 3秒 (5%)
- 产品介绍: 8秒 (13%)
- 卖点展示×3: 36秒 (60%)
- 场景: 8秒 (13%)
- CTA: 5秒 (8%)

## 脚本模板
```markdown
## [钩子] (0:00 - 0:03)
[画面]：痛点场景 / 效果对比
[旁白]：还在为{痛点}烦恼？

## [产品] (0:03 - 0:11)
[画面]：产品全景 + Logo
[旁白]：今天给大家介绍{产品名}——{一句话定位}

## [卖点1] (0:11 - 0:24)
[画面]：卖点1对应素材
[旁白]：{卖点1：15-20字描述}

...（重复卖点2、3）

## [场景] (0:40 - 0:48)
[画面]：生活场景素材
[旁白]：{场景化描述}

## [CTA] (0:48 - 0:53)
[画面]：产品 + 促销信息 + 行动按钮
[旁白]：{促销语}，立即{行动}

**步骤 3：注册管线**

```bash
# 将新管线注册到系统
cd OpenMontage
./register_pipeline.py --file pipeline_defs/ecommerce_product_showcase.yaml

# 验证注册
./list_pipelines.py
# 输出应包含：ecommerce_product_showcase

步骤 4：使用自定义管线

# 在 AI 编码助手中执行
export OPENMONTAGE_PIPELINE=ecommerce_product_showcase

# 告知 AI
请使用 OpenMontage 的 ecommerce_product_showcase 管线，
为我们的 {产品名} 制作一个 45 秒的产品展示视频。

6.3 自定义工具开发示例

当你发现 OpenMontage 的工具箱里没有你需要的功能时，可以自己添加：

# tools/generate_product_diagram.py
"""
产品功能对比图表生成工具
适用于：电商详情页、产品对比视频
"""

import matplotlib.pyplot as plt
import matplotlib
matplotlib.use('Agg')  # 无头模式

def generate_product_diagram(
    features: list[str],
    our_scores: list[float],
    competitor_scores: list[float],
    our_label: str = "我们的产品",
    competitor_label: str = "竞品",
    style: str = "modern"
) -> dict:
    """
    生成产品功能对比雷达图或柱状图。

    Args:
        features: 功能列表（如 ["性能", "价格", "易用性"]）
        our_scores: 我方评分（0-10）
        competitor_scores: 竞品评分（0-10）
        style: 图表风格（modern | minimal | bold）

    Returns:
        {
            "path": "/path/to/diagram.png",
            "resolution": "1920x1080",
            "format": "PNG"
        }
    """

    fig, ax = plt.subplots(figsize=(12, 7), dpi=160)

    x = range(len(features))
    width = 0.35

    colors = {
        "our": "#4F46E5",      # 品牌蓝
        "competitor": "#9CA3AF" # 灰色
    }

    if style == "modern":
        bars1 = ax.bar([i - width/2 for i in x], our_scores,
                       width, label=our_label,
                       color=colors["our"], alpha=0.9)
        bars2 = ax.bar([i + width/2 for i in x], competitor_scores,
                       width, label=compet_label,
                       color=colors["competitor"], alpha=0.7)

    ax.set_xlabel('Features', fontsize=12)
    ax.set_ylabel('Score (0-10)', fontsize=12)
    ax.set_title('Product Comparison', fontsize=14, fontweight='bold')
    ax.set_xticks(x)
    ax.set_xticklabels(features, fontsize=11)
    ax.legend()
    ax.set_ylim(0, 10.5)
    ax.grid(axis='y', alpha=0.3)

    # 添加分数标签
    for bar in bars1:
        height = bar.get_height()
        ax.text(bar.get_x() + bar.get_width()/2., height,
                f'{height:.1f}',
                ha='center', va='bottom', fontsize=10, fontweight='bold')

    plt.tight_layout()
    output_path = f"/tmp/product_comparison_{uuid.uuid4().hex[:8]}.png"
    plt.savefig(output_path, dpi=160, bbox_inches='tight',
                facecolor='white', edgecolor='none')
    plt.close(fig)

    return {
        "path": output_path,
        "resolution": "1920x1120",
        "format": "PNG",
        "dimensions": (1920, 1120)
    }


# 在 tools/registry.py 中注册
TOOL_REGISTRY = {
    # ... 现有工具 ...
    "generate_product_diagram": {
        "file": "tools/generate_product_diagram.py",
        "function": "generate_product_diagram",
        "category": "asset_generation",
        "cost_estimate": 0.0,      # 本地计算，零成本
        "requires_api": False,
        "metadata": {
            "description": "生成产品功能对比图表",
            "languages": ["matplotlib"],
            "output_format": "PNG"
        }
    }
}

七、生产级部署：规模化运营的工程考量

7.1 成本控制策略

OpenMontage 提供了灵活的降本路径：

7.2 批量生产流水线

当你需要同时生产大量视频（如每天生产 10 条 YouTube Shorts）时：

# scripts/batch_production.py
from concurrent.futures import ThreadPoolExecutor
from openmontage import PipelineRunner

def batch_produce(video_specs: list[dict], max_parallel: int = 3):
    """
    批量生产视频。

    Args:
        video_specs: 视频规格列表
            [{
                "topic": "黑洞形成",
                "duration": 60,
                "pipeline": "animated_explainer",
                "approval_mode": "auto"  # 批量模式自动审批低风险决策
            }]
        max_parallel: 最大并行数（建议 ≤3，避免 API 限流）
    """

    with ThreadPoolExecutor(max_workers=max_parallel) as executor:
        futures = []
        for spec in video_specs:
            future = executor.submit(
                PipelineRunner.run,
                topic=spec["topic"],
                pipeline=spec["pipeline"],
                config=spec.get("config", {}),
                approval_mode=spec.get("approval_mode", "auto")
            )
            futures.append((spec["topic"], future))

        results = []
        for topic, future in futures:
            try:
                result = future.result(timeout=600)  # 10分钟超时
                results.append({"topic": topic, "status": "success", **result})
            except Exception as e:
                results.append({"topic": topic, "status": "error", "error": str(e)})

        return results

7.3 多平台分发

# scripts/distribute.py
def distribute_video(
    video_path: str,
    platforms: list[str],
    captions: dict[str, str]  # 平台 → 标题映射
):
    """
    一键分发到多个平台
    """
    outputs = {}

    for platform in platforms:
        if platform == "youtube":
            # YouTube：1080p，完整标题 + 描述 + 标签
            output = f"output/youtube_{Path(video_path).stem}.mp4"
            ffmpeg_scale(video_path, output, "1920x1080")
            youtube_upload(output, title=captions["youtube"]["title"],
                          description=captions["youtube"]["description"])
            outputs["youtube"] = output

        elif platform == "tiktok":
            # TikTok：9:16 竖版，水印去除
            output = f"output/tiktok_{Path(video_path).stem}.mp4"
            ffmpeg_scale(video_path, output, "1080x1920",
                        strip_watermark=True)
            tiktok_upload(output, title=captions["tiktok"]["title"])
            outputs["tiktok"] = output

        elif platform == "xiaohongshu":
            # 小红书：1:1 方形，标题字幕
            output = f"output/xhs_{Path(video_path).stem}.mp4"
            ffmpeg_scale(video_path, output, "1080x1080",
                        add_title_overlay=True)
            outputs["xiaohongshu"] = output

    return outputs

八、局限性与挑战：务实的工程视角

8.1 当前局限性

尽管 OpenMontage 带来了激动人心的突破，我们也需要客观看待它的局限性：

1. AI 视频质量仍有差距

目前主流 AI 视频生成（Runway Gen-3、Kling 1.5、Veo 3）的效果与 Sora 相比仍有差距。对于追求极致视觉效果的广告/电影项目，OpenMontage 目前更适合作为「预制版本」而非「最终成片」。

2. 自主 Agent 的不确定性

虽然 OpenMontage 的检查点机制降低了风险，但 AI Agent 在执行复杂任务时仍可能出现「跑偏」的情况——比如选择了一个与主题无关的视频片段，或生成了质量不稳定的图像。建议所有创意决策保持人工审批节点。

3. 版权与合规风险

真实素材路径虽然免费，但 Pexels、Archive.org 等素材库各有不同的许可证。使用前务必检查每个素材的许可证类型（CC-BY、CC0、商业授权等）。对于商业项目，建议建立素材许可证管理系统。

4. 渲染资源要求

Remotion 动画和 FFmpeg 高质量编码都需要 GPU 资源。如果追求快速迭代，建议使用配备独立显卡的工作站，或将渲染任务分发到云端（如 Modal、Google Colab）。

8.2 未来趋势

OpenMontage 的出现，折射出了几个重要趋势：

1. AI 工具从「单点能力」走向「系统整合」：下一个十年的 AI 工具竞争，不在于单个模型有多强，而在于系统整合能力有多高效
2. 编程助手成为多模态 Agent 的入口：Claude Code、Cursor 等编程助手积累的复杂任务执行能力，正在向视频、音频、3D 等领域溢出
3. 开源与闭源的格局重构：当开源工具能够以接近零成本实现过去需要万元级软件包才能完成的工作时，传统商业软件的护城河将被大幅侵蚀
4. 「视频内容民主化」进入深水区：从「每个人都能做视频」到「每个人都能低成本、大规模、个性化地制作视频」，这是内容产业真正意义上的范式转变

九、总结：AI 视频制作的工程化时刻

OpenMontage 不仅仅是一个技术项目，它是 AI 视频制作走向工程化、标准化的一个标志性事件。

它的核心贡献可以归结为三点：

第一，它证明了「AI Agent + 专业知识库 = 可信的视频制片人」这条路径是可行的。 通过三层知识架构（工具 → 技能 → 知识包），OpenMontage 让 AI Agent 不再是盲目调用 API 的工具，而是真正理解视频制作内在逻辑的「数字制片人」。

第二，它打开了「零成本高质量视频」的想象空间。 真实素材路径 + CLIP 语义搜索的组合，让任何人都不花一分钱 API 费用，就能制作纪录片级别的视频蒙太奇。这对于独立创作者、小团队来说意义重大。

第三，它提供了一个高度可扩展的平台架构。 12 条预设管线 + 完全开放的自定义管线开发机制，让 OpenMontage 成为一个「视频工厂操作系统」，任何人都可以在其上构建自己的垂直领域解决方案。

如果说 2023-2024 年是「AI 生成图像」的元年，2024-2025 年是「AI 生成视频」的元年，那么 2026 年正在成为「AI 视频工程化」的元年——而 OpenMontage，正站在这个元年最前沿的开源实验场上。

立即体验：

git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

把这件事做起来，比任何文字描述都更有说服力。