OpenMontage：面向视频生产的契约化AI智能体协作平台

1. OpenMontage 是什么？一个被严重低估的开源视频智能体协作平台

OpenMontage 这个名字乍一听像某个影视剪辑软件的副产品，或者某家初创公司悄悄上线的 SaaS 工具。但如果你翻过它的 GitHub 仓库、读过它早期的 RFC（Request for Comments）文档，再对比当前主流的 AI Agent 框架——LangChain 偏重链式调用，CrewAI 强调角色编排，Dify 专注低代码界面——你会发现 OpenMontage 走了一条极其务实又极具前瞻性的路：它不试图做“万能胶水”，而是把视频生产全流程当作一个可拆解、可调度、可验证的智能体协作沙盒。它不是“用 AI 做视频”，而是“让多个专业 AI 智能体，在视频生产的每个环节里，像剧组一样分工、交接、复盘”。

我第一次接触 OpenMontage 是在 2023 年底，当时正为一个教育类短视频项目发愁：脚本生成质量不稳定、分镜逻辑常断裂、配音口型对不上、BGM 风格总和画面情绪冲突。试过把 LLM、TTS、Stable Diffusion、Whisper 全塞进一个 LangChain Chain 里跑，结果是“一锅端”式的脆弱流程——只要 Whisper 识别错一个词，后面所有环节全崩。而 OpenMontage 的设计哲学很朴素：把导演、编剧、美术指导、音效师、剪辑师这些角色，变成可独立部署、可单独测试、可版本回滚的智能体（Agent）。每个 Agent 只负责一件事，但通过标准化的“镜头包”（Shot Package）格式交接工作成果。这个“镜头包”不是简单的 JSON，而是一个包含时间码、视觉描述、音频波形摘要、情感标签、版权元数据的结构化容器。它让 AI 之间的协作，有了影视工业级的交付契约感。

核心关键词 “agentic” 和 “video production” 在这里不是营销话术，而是技术落地的锚点。OpenMontage 的 Agent 不是抽象的“能力封装”，而是绑定具体视频任务的执行单元：ScriptWriterAgent 必须输出符合 ShotList Schema 的 JSON；StoryboardArtistAgent 必须返回带帧率、宽高比、关键帧提示词的 PNG 序列；VoiceDirectorAgent 不仅调 TTS，还要根据台词情绪动态调整语速、停顿、基频偏移，并生成 .lab 格式对齐文件。这种强契约、弱耦合的设计，直接解决了当前 AI 视频工具最大的痛点——不可控的黑箱串联。你不需要祈祷整个 pipeline 别出错，只需要确保每个 Agent 的输入/输出契约被严格遵守，就能实现模块化替换与灰度发布。比如，把默认的 Whisper 替换成更擅长方言识别的 FunASR Agent，只需修改配置文件中的一行 agent_id，无需动任何业务逻辑代码。这正是它被大量独立创作者、小型 MCN 机构悄悄采用的原因：它不追求“一键成片”的幻觉，而是提供一条可调试、可审计、可追责的视频生产流水线。

2. 为什么是 OpenMontage？深度拆解其架构选型背后的硬核逻辑

2.1 拒绝“大模型中心主义”：从 Workflow Orchestrator 到 Agent Orchestrator 的范式迁移

当前绝大多数 AI 视频工具，底层仍是典型的“大模型中心主义”架构：用户输入需求 → LLM 理解并规划 → LLM 调用工具 → LLM 整合结果 → 输出最终视频。这种模式在 Demo 场景下很炫，但在真实生产中问题尖锐：LLM 的规划能力不可靠（尤其对长时序、多模态约束的任务），错误会逐级放大；工具调用缺乏事务性保障（TTS 失败后，前面生成的分镜图就作废）；调试成本极高（你得在 LLM 的 prompt 里埋 log，再解析它的思考链）。OpenMontage 的破局点在于，它把“规划权”从 LLM 手中拿了出来，交给了一个轻量、确定、可编程的Orchestrator。

这个 Orchestrator 不是另一个大模型，而是一个基于 Rust 实现的状态机引擎。它读取的是 YAML 格式的Production Plan，而非自然语言指令。例如，一个简单的“科普短视频”Plan 长这样：

version: "1.0" stages: - name: script_generation agent: "scriptwriter-v2" input: {topic: "光合作用", target_audience: "初中生", duration_sec: 90} output_schema: "shotlist_v1" timeout_sec: 120 - name: storyboard agent: "storyboarder-sdxl" input_from: "script_generation.output" output_schema: "storyboard_v1" retry: {max_attempts: 3, backoff: "exponential"} - name: voiceover agent: "voicedirector-coqui" input_from: "script_generation.output" output_schema: "audio_wav_v1" constraints: {max_filesize_mb: 15, sample_rate_hz: 44100}

看到区别了吗？Orchestrator 不理解“光合作用”，它只认 YAML 的字段和 Schema。它的工作就是：按顺序启动 Agent，校验输入是否符合input_schema，等待 Agent 返回结果，用 JSON Schema 验证输出是否符合output_schema，若失败则按策略重试或报错。这种设计带来的好处是颠覆性的：

• 可预测性：Pipeline 的执行路径完全由 YAML 定义，没有“LLM 突然灵光一闪改了分镜顺序”这种意外。
• 可观测性：每个 Stage 的输入、输出、耗时、错误日志都结构化存储，可直接接入 Prometheus + Grafana 做监控。
• 可测试性：你可以为scriptwriter-v2Agent 单独写单元测试，用固定输入验证其输出是否严格符合shotlist_v1Schema，无需启动整个 Pipeline。

我实测过，当把一个原本用 LLM 链式调用的 8 步视频流程迁移到 OpenMontage 架构后，平均成功率从 63% 提升到 92%，单次失败的平均定位时间从 47 分钟缩短到 3.2 分钟。这不是玄学优化，而是把不确定性问题，转化成了确定性的工程问题。

2.2 “Agent” 的重新定义：不是技能集合，而是契约化服务单元

网络热词里充斥着“AI Agent”、“Agent 框架”、“Agent 技能”，但很多项目对 Agent 的定义非常模糊——它可能是一个封装了几个 API 调用的 Python 函数，也可能是一个能自主规划的复杂系统。OpenMontage 对 Agent 的定义极其严苛，它必须满足“四契约”原则：

1. 输入契约（Input Contract）：Agent 必须声明它接受的输入数据结构（JSON Schema），Orchestrator 会在调用前强制校验。例如，storyboarder-sdxlAgent 的输入契约要求必须包含shot_list字段，且每个 shot 必须有prompt,duration_sec,aspect_ratio三个必填项。如果上游 ScriptWriterAgent 少输出了一个aspect_ratio，Orchestrator 直接拒绝调用，而不是让 Agent 自己去 handle null。

2. 输出契约（Output Contract）：Agent 的返回值必须严格符合预定义的输出 Schema。这个 Schema 不是简单描述，而是包含字段类型、枚举值、正则校验的完整 JSON Schema。比如voicedirector-coqui的输出契约规定audio_url字段必须是 HTTPS 开头的 URL，且域名必须在白名单内（防止 Agent 意外返回本地 file:// 路径）。

3. 资源契约（Resource Contract）：Agent 必须声明其运行所需的最小资源（CPU 核心数、GPU 显存、内存）。Orchestrator 的调度器据此进行资源隔离。我见过太多项目，一个 TTS Agent 吃光 GPU 显存，导致后面的图像生成 Agent 直接 OOM。OpenMontage 的调度器会为每个 Agent 分配独立的 cgroup 或 Kubernetes Pod，确保资源不越界。

4. 安全契约（Security Contract）：这是最被忽视，却最关键的契约。Agent 必须声明其网络访问权限（如network: ["https://api.openai.com"]）、文件系统访问范围（如fs: ["/mnt/data/input/", "/mnt/data/output/"]）、以及禁止执行的系统调用（如syscalls: ["execve", "fork"]）。Orchestrator 启动 Agent 时，会通过 seccomp-bpf 或 gVisor 沙箱强制执行这些限制。这意味着，即使你集成一个社区贡献的、未经充分审计的第三方 Agent，它也无法逃逸沙箱去读取你的 SSH 密钥或发起恶意网络请求。

这种契约化设计，让 OpenMontage 的 Agent 生态具备了前所未有的健壮性。它不像 LangChain 那样依赖开发者自觉写好 error handling，而是通过架构层强制兜底。一个新加入的 Agent，只要签了这四份“契约”，就能无缝融入现有 Pipeline，无需修改 Orchestrator 一行代码。这也是为什么它能在短短一年内，聚集起超过 47 个高质量的开源 Agent（涵盖脚本、分镜、绘图、配音、字幕、调色、合成等环节），而没有陷入“生态碎片化”的泥潭。

2.3 Rust 作为核心语言：性能、安全与并发的三重必然选择

标题里没提 Rust，但所有看过 OpenMontage 源码的人都会立刻注意到：Orchestrator、Agent Runtime、Schema Validator 这些核心组件，全部用 Rust 编写。这不是为了赶时髦，而是由视频生产场景的硬性需求倒逼出来的必然选择。

首先看性能。视频 Pipeline 的瓶颈往往不在 AI 模型本身（那是 GPU 事），而在 Orchestrator 的调度开销。一个 90 秒的短视频，可能需要生成 30 个分镜、每个分镜生成 4 张图、每张图配 3 种风格的 BGM、再做 5 种字幕样式 A/B 测试……这意味着 Orchestrator 可能要在 1 分钟内调度上千个 Agent 实例。Rust 的零成本抽象和无 GC 特性，让它在高并发调度场景下，内存占用比同等功能的 Go 实现低 40%，P99 延迟稳定在 8ms 以内。我做过压测：当并发 Agent 实例数超过 500 时，Go 版 Orchestrator 的 GC STW 时间开始飙升，导致 Pipeline 整体吞吐量断崖下跌；而 Rust 版则平稳运行，CPU 利用率曲线平滑。

其次是内存安全。视频处理涉及大量二进制数据（图像、音频、视频帧）的解析与转换。一个经典的 C/C++ 内存错误（如 buffer overflow, use-after-free）在传统 Web 服务里可能只是 crash 一次，但在 OpenMontage 的沙箱环境中，它可能被恶意构造的输入触发，成为 Agent 逃逸的入口。Rust 的所有权系统，在编译期就杜绝了这类漏洞。我们团队曾用 AFL 对 OpenMontage 的 PNG 解析模块进行模糊测试，跑了 72 小时，0 个 crash；而用同样方法测试一个 C 写的同类库，15 分钟就爆出 3 个 segfault。这不仅是开发效率问题，更是生产环境的安全底线。

最后是并发模型。视频 Pipeline 天然是异步 I/O 密集型的：Agent 启动后，大部分时间在等待 GPU 计算、网络响应或磁盘 IO。Rust 的 async/await + Tokio 运行时，提供了比 Node.js 更细粒度的协程控制和比 Go 更低的内存开销。更重要的是，Tokio 的spawn和select!宏，让编写超时、重试、取消等复杂控制流变得异常简洁。比如，为一个 Agent 设置“30 秒内必须完成，否则强制 kill 并标记失败”，在 Rust 里就是几行代码；在 Python 的 asyncio 里，你需要手动管理 Future 和 CancelledError，极易出错。

所以，当你看到 “基于 Rust 语言 AI Agent” 这个热词时，不要只把它当作一个技术标签。在 OpenMontage 的语境下，Rust 是它能扛住真实视频生产负载、保证沙箱绝对安全、实现毫秒级调度响应的物理基石。换用任何其他语言，都很难同时满足这三个硬性指标。

3. 核心细节解析：从零搭建一个可运行的 OpenMontage 视频 Pipeline

3.1 环境准备与最小可行部署（5 分钟上手）

OpenMontage 的设计理念是“开箱即用，但绝不妥协”。它不强制你用 Docker Compose 或 Kubernetes，但也绝不推荐你在笔记本上裸跑。官方推荐的最小可行部署方案，是“单机多容器”模式，用 Docker Compose 管理 Orchestrator、Redis（消息队列）、PostgreSQL（元数据存储）和一个基础 Agent（如scriptwriter-gpt4）。这个方案平衡了易用性和生产可用性。

第一步，安装 Docker 和 Docker Compose（v2.20+）。确认你的机器有至少 16GB 内存和一块 NVIDIA GPU（用于后续的图像/视频 Agent）。然后，创建docker-compose.yml：

version: '3.8' services: orchestrator: image: openmontage/orchestrator:v0.8.2 ports: - "8000:8000" environment: - RUST_LOG=info - DATABASE_URL=postgres://postgres:password@db:5432/openmontage - REDIS_URL=redis://redis:6379 - GPU_ENABLED=true volumes: - ./config:/app/config - ./data:/app/data depends_on: - db - redis db: image: postgres:15 environment: - POSTGRES_DB=openmontage - POSTGRES_USER=postgres - POSTGRES_PASSWORD=password volumes: - ./pgdata:/var/lib/postgresql/data redis: image: redis:7-alpine command: redis-server --save 60 1 --loglevel warning volumes: - ./redisdata:/data # 示例：一个轻量级脚本生成 Agent scriptwriter-gpt4: image: openmontage/agent-scriptwriter-gpt4:v0.3.1 environment: - OPENAI_API_KEY=${OPENAI_API_KEY} - AGENT_ID=scriptwriter-gpt4 - ORCHESTRATOR_URL=http://orchestrator:8000 depends_on: - orchestrator

关键点解析：

• GPU_ENABLED=true是必须的，它告诉 Orchestrator 启动时加载 CUDA 支持。即使你暂时不用 GPU Agent，这个 flag 也影响内部 Tensor 处理库的初始化。
• volumes映射了./config和./data。config目录下放你的 Production Plans（YAML 文件），data目录是所有 Agent 输入/输出的共享存储区，必须是 POSIX 兼容的文件系统（NTFS 在 WSL2 下可能有问题）。
• scriptwriter-gpt4Agent 的AGENT_ID必须与你的 Production Plan 中引用的 ID 完全一致，大小写敏感。这是 Agent 发现和注册的唯一标识。

启动命令很简单：

# 创建 config 目录并放入一个 plan mkdir -p config data cp your_plan.yaml config/ # 启动（注意：首次启动会自动初始化数据库） docker compose up -d # 查看日志，确认 Orchestrator 启动成功 docker compose logs -f orchestrator

你会看到类似这样的日志：

orchestrator-1 | INFO openmontage_orchestrator::server: Starting HTTP server on 0.0.0.0:8000 orchestrator-1 | INFO openmontage_orchestrator::agent_registry: Registered agent 'scriptwriter-gpt4' with input_schema 'script_input_v1'

这表示 Orchestrator 已就绪，且成功发现了scriptwriter-gpt4Agent。此时，你的 OpenMontage 系统已经“活”了，可以接收第一个视频生产任务。

3.2 Production Plan 编写：用 YAML 定义你的视频流水线

Production Plan 是 OpenMontage 的灵魂，它既是任务说明书，也是执行蓝图。一个写得好的 Plan，能让整个 Pipeline 像乐高积木一样清晰、可复用。我们以一个“30 秒品牌宣传短视频”为例，拆解其核心要素。

首先，Plan 的顶层结构：

# config/brand_video_plan.yaml version: "1.0" # Plan 版本，用于灰度发布和回滚 metadata: name: "BrandX_Slogan_Video" description: "A 30-second video showcasing BrandX's new slogan 'Think Forward'" author: "your_name" created_at: "2024-06-15" stages: # Stage 1: 脚本生成 - name: "generate_script" agent: "scriptwriter-gpt4" input: topic: "BrandX's new slogan 'Think Forward'" tone: "inspiring, professional" duration_sec: 30 target_audience: "business professionals" output_schema: "shotlist_v1" timeout_sec: 180 retry: max_attempts: 2 backoff: "exponential" jitter: true # Stage 2: 分镜绘制（使用 SDXL） - name: "generate_storyboard" agent: "storyboarder-sdxl" input_from: "generate_script.output" output_schema: "storyboard_v1" timeout_sec: 600 # SDXL 生成较慢，给足时间 resources: gpu_memory_mb: 8000 cpu_cores: 4 memory_mb: 12000 # Stage 3: 配音（使用 Coqui TTS） - name: "generate_voiceover" agent: "voicedirector-coqui" input_from: "generate_script.output" output_schema: "audio_wav_v1" timeout_sec: 300 constraints: max_filesize_mb: 10 sample_rate_hz: 44100 voice: "en_us_001" # Coqui 的声音 ID # Stage 4: 视频合成（FFmpeg） - name: "compose_video" agent: "composer-ffmpeg" input: storyboard: "generate_storyboard.output" audio: "generate_voiceover.output" duration_sec: 30 output_schema: "video_mp4_v1" timeout_sec: 120

关键细节与避坑心得：

• input_fromvsinput：input_from是引用上游 Stage 的输出，input是硬编码的静态参数。务必区分清楚。我踩过的最大坑是，把input_from错写成input，导致 Agent 收到的是空对象，然后静默失败。Orchestrator 日志里只会显示Stage 'compose_video' failed: invalid input schema，不会告诉你哪一行错了。建议用 VS Code 的 YAML 插件，开启 Schema 校验，它会实时高亮语法错误。

• timeout_sec的设定逻辑：不是拍脑袋定的。计算公式是预期耗时 * 2 + 30秒缓冲。例如，SDXL 生成一张图平均 15 秒，一个分镜 4 张图，共 60 秒，那么timeout_sec设为150（60*2+30）比较稳妥。设得太短，正常波动就会触发重试；设得太长，一个卡死的 Agent 会拖垮整个 Pipeline。

• resources的精确性：gpu_memory_mb: 8000不是随便写的。这是根据nvidia-smi查看storyboarder-sdxlAgent 进程的实际显存峰值（通常是 7200MB 左右）再加 10% 余量得出的。Orchestrator 会用nvidia-smi的--query-compute-apps=used_memory命令实时监控，一旦 Agent 显存超限，立即 kill 并标记失败。这比单纯用 Kubernetes 的 resource limits 更精准，因为后者是静态分配，而这里是动态监控。

• constraints的安全意义：max_filesize_mb: 10这个约束，表面看是防大文件占满磁盘，深层作用是防 DoS 攻击。如果一个恶意的voicedirector-coquiAgent（比如被篡改的版本）故意生成 1GB 的 WAV 文件，constraints会让 Orchestrator 在写入前就拒绝该输出，保护存储系统。

写完 Plan，把它放到config/目录下，然后通过 Orchestrator 的 REST API 提交任务：

curl -X POST http://localhost:8000/api/v1/jobs \ -H "Content-Type: application/json" \ -d '{ "plan_name": "brand_video_plan.yaml", "job_metadata": {"project_id": "PRJ-2024-001"} }'

你会收到一个job_id，然后就可以用GET /api/v1/jobs/{job_id}查询状态了。整个过程，你不需要碰一行 Python 或 JavaScript，纯粹是基础设施即代码（IaC）的体验。

3.3 Agent 开发实战：如何为 OpenMontage 贡献一个新 Agent

OpenMontage 的强大，最终体现在它的 Agent 生态。官方提供了openmontage-agent-sdk（Rust crate），但很多开发者更习惯用 Python。好消息是，OpenMontage 对 Agent 的语言没有任何限制，只要它能通过 HTTP 或 gRPC 与 Orchestrator 通信，并遵守四契约。下面，我以开发一个captioner-whisperAgent（自动生成字幕）为例，展示完整流程。

Step 1: 理解契约，定义 Schema首先，查阅 OpenMontage 的 Agent Schema Registry，找到audio_wav_v1（输入）和subtitle_srt_v1（输出）的 JSON Schema。audio_wav_v1要求输入是一个包含url字段的 JSON 对象，指向一个可公开访问的 WAV 文件。subtitle_srt_v1要求输出是一个字符串，内容是标准的 SRT 字幕格式。

Step 2: 创建 Python Agent 项目

mkdir captioner-whisper && cd captioner-whisper pip install fastapi uvicorn whisper torch

Step 3: 编写核心逻辑（main.py）

from fastapi import FastAPI, HTTPException, BackgroundTasks from pydantic import BaseModel import requests import tempfile import os import whisper app = FastAPI(title="Captioner-Whisper Agent") # 加载模型（全局，避免每次请求都加载） model = whisper.load_model("base") # 根据 GPU 选择 small/base/large class AudioInput(BaseModel): url: str # 来自 audio_wav_v1 Schema class SubtitleOutput(BaseModel): srt_content: str # 符合 subtitle_srt_v1 Schema @app.post("/process", response_model=SubtitleOutput) async def process_audio(input_data: AudioInput): try: # 1. 下载音频（Orchestrator 保证 url 是可信的） response = requests.get(input_data.url, timeout=30) response.raise_for_status() # 2. 保存到临时文件（Agent 必须自己管理文件生命周期） with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as f: f.write(response.content) temp_path = f.name # 3. 调用 Whisper result = model.transcribe(temp_path, language="en", fp16=False) # fp16=False 防止 CPU 推理出错 # 4. 格式化为 SRT srt_lines = [] for i, segment in enumerate(result["segments"], 1): start = int(segment["start"] * 1000) end = int(segment["end"] * 1000) text = segment["text"].strip() srt_lines.append(f"{i}") srt_lines.append(f"{format_time(start)} --> {format_time(end)}") srt_lines.append(text) srt_lines.append("") # 空行 # 5. 清理临时文件 os.unlink(temp_path) return SubtitleOutput(srt_content="\n".join(srt_lines)) except Exception as e: # 关键：所有异常必须包装成 HTTPException，让 Orchestrator 能捕获 raise HTTPException(status_code=500, detail=f"Whisper processing failed: {str(e)}") def format_time(ms): """将毫秒转为 SRT 时间格式 HH:MM:SS,mmm""" total_seconds = ms // 1000 hours = total_seconds // 3600 minutes = (total_seconds % 3600) // 60 seconds = total_seconds % 60 milliseconds = ms % 1000 return f"{hours:02d}:{minutes:02d}:{seconds:02d},{milliseconds:03d}"

Step 4: Dockerize 并注册创建Dockerfile：

FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . # 关键：设置环境变量，让 Orchestrator 能发现它 ENV AGENT_ID=captioner-whisper ENV AGENT_INPUT_SCHEMA=audio_wav_v1 ENV AGENT_OUTPUT_SCHEMA=subtitle_srt_v1 ENV AGENT_RESOURCES='{"cpu_cores": 2, "memory_mb": 4000}' EXPOSE 8000 CMD ["uvicorn", "main:app", "--host", "0.0.0.0:8000", "--port", "8000"]

构建并运行：

docker build -t my-captioner . docker run -d --name captioner-whisper \ -e ORCHESTRATOR_URL=http://host.docker.internal:8000 \ # Mac/Windows 用 host.docker.internal, Linux 用宿主机 IP -p 8001:8000 \ my-captioner

Step 5: 验证与调试Orchestrator 会自动发现新 Agent（通过健康检查端点/health）。你可以在 Orchestrator 日志里看到：

INFO openmontage_orchestrator::agent_registry: Discovered new agent 'captioner-whisper' at http://172.17.0.3:8000

然后，修改你的 Production Plan，在compose_videoStage 之后，加上：

- name: "add_subtitles" agent: "captioner-whisper" input_from: "generate_voiceover.output" output_schema: "subtitle_srt_v1" timeout_sec: 300

提交任务，观察日志。如果失败，docker logs captioner-whisper会直接显示 Whisper 的报错，比如CUDA out of memory，这时你就知道要调整AGENT_RESOURCES里的memory_mb了。

实操心得：

• 永远不要信任输入 URL：虽然 Orchestrator 会做初步校验，但你的 Agent 必须自己做requests.get的 timeout 和raise_for_status()，防止恶意 URL 导致进程 hang 住。
• 临时文件是雷区：务必用tempfile.NamedTemporaryFile(delete=False)，并在处理完后os.unlink()。我见过太多 Agent 因为没清理临时文件，几天就把磁盘撑爆。
• 模型加载是性能关键：whisper.load_model()很慢，必须放在main.py的 global scope，而不是process_audio函数里。否则每个请求都重新加载，QPS 直接归零。

4. 实操过程全记录：从 Plan 提交到成品视频交付的 7 个关键环节

4.1 Job 提交与初始校验：Orchestrator 的第一道防火墙

当你执行curl -X POST http://localhost:8000/api/v1/jobs ...提交一个新 Job 时，Orchestrator 并不会立刻启动 Agent。它会先进行一套严格的、毫秒级的静态校验，这是整个 Pipeline 稳定性的基石。

1. Plan 存在性校验：Orchestrator 会检查config/目录下是否存在你指定的plan_name文件。如果不存在，直接返回404 Not Found。这一步看似简单，但避免了因拼写错误导致的“静默失败”。

2. YAML 语法校验：用serde_yaml解析 YAML，任何语法错误（如缩进错误、冒号后少空格）都会被捕捉，并返回详细的错误位置（行号、列号）。这是比 Python 的yaml.safe_load()更友好的错误提示。

3. Schema 兼容性校验：Orchestrator 会遍历 Plan 中每一个 Stage 的agent字段，查询其注册信息，确认该 Agent 的input_schema是否与当前 Stage 的input或input_from所引用的上游输出 Schema 兼容。例如，如果generate_script的输出 Schema 是shotlist_v1，而generate_storyboard的input_schema是shotlist_v2，校验就会失败，返回422 Unprocessable Entity并明确指出不兼容的字段。

4. 资源可行性校验：Orchestrator 会汇总所有 Stage 的resources声明，计算总需求（CPU、内存、GPU 显存），并与当前集群的可用资源池进行比对。如果总需求超过了docker-compose分配的资源上限，Job 会被拒绝，而不是启动后才发现资源不足。

这个校验过程通常在 50ms 内完成。只有全部通过，Orchestrator 才会为这个 Job 创建一个唯一的job_id，并将其状态置为PENDING，写入 PostgreSQL。此时，你调用GET /api/v1/jobs/{job_id}，会看到：

{ "job_id": "job_abc123", "status": "PENDING", "plan_name": "brand_video_plan.yaml", "created_at": "2024-06-15T10:30:45Z", "stages": [ {"name": "generate_script", "status": "WAITING"}, {"name": "generate_storyboard", "status": "WAITING"}, ... ] }

提示：这个PENDING状态是极有价值的调试信号。如果你的 Job 卡在这里超过 10 秒，说明问题一定出在 Plan 校验环节，而不是 Agent 执行环节。你应该立刻检查 Orchestrator 日志，而不是去查 Agent 的日志。

4.2 Stage 执行与状态流转：一个 Stage 的生命周期详解

以generate_scriptStage 为例，它的状态流转是理解 OpenMontage 工作原理的核心。

1. WAITING → QUEUED：Orchestrator 的调度器（Scheduler）检测到generate_script的前置条件（无）已满足，且资源充足，便将其状态更新为QUEUED，并将其放入 Redis 的stage_queue:generate_script列表中。

2. QUEUED → RUNNING：一个专门的Worker进程（由 Orchestrator 启动）监听这个列表。它取出 Stage，向scriptwriter-gpt4Agent 的/process端点发送 POST 请求，携带序列化后的input数据。一旦请求发出，Stage 状态变为RUNNING。

3. RUNNING → SUCCEEDED / FAILED：Worker 会等待 Agent 的响应。如果 Agent 在timeout_sec内返回 200 OK 且响应体符合output_schema，Worker 将响应体解析、存入 PostgreSQL，并更新 Stage 状态为SUCCEEDED。如果 Agent 返回非 200 状态码（如 500），或响应体无法通过 Schema 校验，Worker 会记录错误详情，并更新状态为FAILED。

4. SUCCEEDED → WAITING (下游)：当generate_script成功后，Orchestrator 的事件处理器（Event Processor）会触发一个StageSucceeded事件。它会扫描所有input_from: "generate_script.output"的下游 Stage（这里是generate_storyboard），将它们的状态从WAITING更新为QUEUED，从而驱动 Pipeline 向前流动。

这个状态机是完全透明的。你可以随时GET /api/v1/jobs/{job_id}/stages获取所有 Stage 的当前状态、耗时、错误信息。例如，如果generate_storyboard失败了，响应体里会包含：

{ "name": "generate_storyboard", "status": "FAILED", "error": "HTTP status 500 from agent 'storyboarder-sdxl': CUDA out of memory", "duration_ms": 60234, "retries": 2 }

注意：retries: 2表示这个 Stage 已经重试了 2 次（按 Plan 中的retry.max_attempts: 2设置），下次就不会再重试了。这是 OpenMontage 对“失败”的明确定义：不是无限重试，而是按契约执行。

4.3 输入/输出数据流：data/目录下的秘密世界

所有 Agent 的输入和输出，都通过data/目录进行交换。这不是一个简单的共享文件夹，而是一个精心设计的数据总线。

• 输入数据：Orchestrator 在调用 Agent 前，会将input或input_from的数据，序列化为 JSON，写入data/{job_id}/{stage_name}/input.json。同时，如果input包含一个url字段（如audio_wav_v1），Orchestrator 会下载该资源，保存为data/{job_id}/{stage_name}/input.bin，并在input.json中将url