本文以一个 Agent 驱动的可编程视频生成平台为真实案例,讲清楚搭建一个「视频生成 Agent Web 应用」需要考虑的技术选型维度——尤其是一个 Agent 系统自身的设计选型。适合想从零构建 Agent 应用、或想把 LLM 能力产品化的开发者。
一、先想清楚:这是个什么样的应用
视频生成 Agent 应用,核心不是”把文本转成视频”这种黑盒,而是把 AI 的生成能力翻译成普通人可用的可视化界面。该项目的定位是填补一块空白:
| 纯对话式 AI 视频工具(Runway / Kling / Pika) | 原生可编程视频工具(Remotion / HyperFrames) | |
|---|---|---|
| 特点 | 不可控、难品牌化、无法批量 | 门槛高、需写代码 |
| 问题 | 用户只能”掷骰子” | 普通人用不了 |
该项目想做的,是让用户通过参数和约束,稳定、可控、可复现地产出符合品牌规范的短视频。目标用户是电商运营、知识付费机构、个人 IP、中小品牌市场团队。
这句话决定了整个架构的方向:既然要”可控、可复现、可品牌化”,就不能是”模型端到端生成一段视频”,而必须走结构化中间表示 + 确定性渲染的路线。
二、总体架构:一条流水线
用户界面 (React + Zustand)
↕ 意图描述 + 参数调整
意图理解 → Storyboard Agent(创意推理)
↕ 结构化 JSON
VideoSpec(唯一真相源)
↕ 约束校验 + 二次打磨
素材装配(检索 / 生成 / 上传 / 纯色)
↕ 真实画面写入 spec
Remotion Composition(确定性渲染)
↕
预览播放器 + 真 MP4 导出
整条链路围绕一个核心概念运转:VideoSpec。下面从最关键的设计决策逐层展开。
三、核心数据模型:VideoSpec(单一真相源)
这是整个系统最吃重的设计决策。所有 Agent 的输出、用户的参数调整、渲染引擎的输入,全部汇聚到一份 VideoSpec JSON:
interface VideoSpec {
meta: { scene, duration, aspectRatio, resolution, fps, seed, ... } // 元信息
narrative: { structure, copyStyle, keyMessages, sections[] } // 叙事
visual: { colorPalette, fonts, stylePreset, logoRules, safeArea } // 视觉
motion: { pace, transitionType, textAnimation, cameraMovement } // 动效
audio: { narration, bgm, sfx } // 音频
constraints: SpecConstraint[] // 硬约束
storyboard: StoryboardCard[] // 分镜
}为什么 Spec 是唯一真相源(SSOT):
- 不是黑盒——所有中间产物可审阅、可 diff、可回滚。
- 引擎无关——spec 不含任何 Remotion/HyperFrames 特有代码,未来换渲染引擎不影响结构。
- 版本化——
version+parentVersion支持迭代历史。 - 点号路径寻址——
setByPath("motion.pace", "fast")支持读写任意节点,参数面板直接映射。 - 不可变写入——
structuredClone+ 路径写入返回新对象,天然兼容 React 状态更新。
一句话:先把”产品要什么”沉淀成稳定的数据结构,再让所有 Agent 和引擎围绕它转。 这是”可控制”的技术根基。
四、Agent 怎么选型:多 Agent 协作,而非单模型端到端
这是 Agent 自身最核心的选型决策。该项目没有用”一个大模型搞定一切”,而是设计了四阶段创意管线:
意图 ─▶ ① Storyboard Agent(创意总监,注入抽象创作原则,自主决定每镜头画面与素材策略)
─▶ ② Critic(确定性约束校验 + 构图启发式打分,弱镜头交给模型二次打磨)
─▶ ③ 素材装配(按镜头策略取真实画面:检索 / 文生图 / 上传 / 纯色)
─▶ ④ Schema 校验
为什么拆成多 Agent,而不是单模型端到端:每个 Agent 职责单一、prompt 精准、可独立调试。“创意”和”校验”是两种相反的思维模式,塞进同一个 prompt 会互相打架。
① Storyboard Agent —「创意总监」而非「填表程序」
秘密在于 system prompt 注入的是抽象创作原则,而不是具体模板。比如电商叙事结构:
- Hook:前 1 秒必须有强视觉锤或强冲突文案,否则用户划走
- Problem:放大目标人群真实痛点,制造”说的就是我”的共鸣
- Solution:全片视觉高潮,产品首次亮相,光影质感拉满
- Proof:用数据 / 好评 / 对比建立信任
- CTA:价格大字 + 明确行动指令,必须有强视觉锤
模型负责在原则内发挥创意,但底线不破。每个镜头要决策的维度极多:
| 决策维度 | 说明 |
|---|---|
copy / subtitle / emphasisText | 主标题、副标题、强调词(强调词必须是主标题子串) |
cameraMove | 运镜:static / push-in / push-pull / quick-cut / parallax |
textAnimation | 文字动画:pop / typewriter / fade / rise / stagger / highlight |
transitionOut | 转场:slide / fade / zoom / glitch |
assetStrategy | 画面来源:search / generate / upload / color |
searchQuery / imagePrompt | 英文检索词 / 英文文生图提示词 |
bgmPrompt | BGM 生成提示词(英文 mood / 乐器 / 节奏 / BPM) |
② Critic — 校验不靠 LLM,靠确定性规则
Critic 刻意不依赖 LLM,改用确定性规则:
computeViolations():检查时长精确性、必现元素、禁止元素、品牌色锁定。heuristicWeakness():检查”画面创意缺失""检索词过于宽泛""视觉高潮镜头用纯色”等。refineWeakShots():只把被判弱的镜头交给模型重新推理,而非整条重跑(成本低、速度快)。applyAutoFix():一键确定性修复(重新分配时长、补充缺失元素、清除禁止词、恢复品牌色)。
关键洞察:“创意”和”校验”分开。 校验要确定性、可复现、可调试,交给规则;创意要发散、有灵性,交给模型。
③ 素材装配 — 与 LLM 解耦
素材装配层独立于 LLM 运行。Agent 只输出策略和关键词,装配层负责执行:
- 四策略:search(Pexels 检索)/ generate(文生图)/ upload(用户主图)/ color(纯色兜底)
- 逐级降级:检索失败 → 文生图;文生图失败 → 检索;全部失败 → 纯色
- 并发池:
pool(cards, 3, worker)控制并发为 3,避免打爆上游限流
五、构建 Agent 系统的七个技术设计层面
从系统工程视角,一个生产级 Agent 系统需要覆盖七个层面。这是通用框架,不限于视频生成:
| 层面 | 核心问题 | 该项目的取舍 |
|---|---|---|
| 意图理解层 | 自然语言如何变成结构化指令? | LLM 推理为主 + 规则兜底;上下文注入而非 function calling;输出后守卫(extractJSON + 枚举校验) |
| 认知推理层 | Agent 如何像专家一样思考? | 多 Agent 协作;注入抽象原则;温度控制(创意 0.7–0.9,结构化 0.4) |
| 数据模型层 | 输出如何成为可验证的单一真相源? | VideoSpec + Zod 校验 + 版本化 + 点号路径寻址 |
| 工具与执行层 | 需要调用哪些外部能力? | 策略驱动而非工具调用;服务端代理隔离密钥;并发池 |
| 批评与约束层 | 如何防止”炫但不可用”? | Critic 用确定性规则;弱镜头二次打磨;一键自动修复 |
| 降级与韧性层 | 任一环节失败会怎样? | 逐级降级,绝不崩溃空白;“绝不静默占位” |
| 确定性与可观测层 | 相同输入是否相同输出?故障能否追溯? | 帧号驱动 + 固定种子;Spec 哈希缓存;调用链追踪 |
这七个层面是走一遍 Agent 应用开发都会遇到的,值得作为自查清单。
六、技术选型总表
| 层级 | 选型 | 理由 |
|---|---|---|
| 前端 | React 18 + Vite 5 + Tailwind v4 | 快速热更新、生态成熟 |
| 状态 | Zustand v4 + URL 路由 | URL 是视图唯一真相源,深链/刷新可恢复 |
| Schema 校验 | Zod v3 | TypeScript 原生、编译时类型安全 |
| 渲染引擎 | Remotion v4 | 逐帧确定性、可服务端渲染、Google Fonts 集成 |
| LLM | Agnes AI / 通义千问 | OpenAI 兼容接口、国内可用 |
| 素材检索 | Pexels API | 免费商用、图片 + 视频 |
| 文生图 / 图生视频 | Agnes 全模态网关 | 同一密钥复用 |
| TTS | DashScope CosyVoice | 中文语音质量好 |
| BGM | ElevenLabs / Minimax / Agnes | 多 provider 降级 |
| 字体 | Google Fonts(8 款 CJK) | SIL OFL 商用安全、按需分片 |
几个特别值得说的选型决策:
- 渲染引擎选 Remotion 而非时间驱动的动画库:Remotion 要求逐帧确定性(可服务端渲染、可复现)。所有动画从
useCurrentFrame()+meta.seed派生,不使用Math.random()/Date.now()。anime.js / framer-motion 是时间/事件驱动,与 Remotion 渲染模型不兼容,所以自建了确定性动画组件库(6 种帧号驱动的入场动画)。 - 音频序列化用 data URL 而非 blob URL:服务端渲染进程无法 fetch
blob:URL,data URL 随 spec 序列化。 - 密钥隔离:所有第三方 API Key 只存在于服务端
.env,VITE_前缀才暴露给前端。客户端fetch('/api/xxx')走 Vite 中间件代理,密钥不进 bundle。
七、降级策略:全链路优雅降级
一个 Agent 应用最容易被低估的,是降级设计。该项目的原则是”任一环节失败都能优雅降级,绝不崩溃、绝不白屏”:
LLM 不可用 → 本地规则解析(正则 + 关键词表)
检索失败 → 文生图
文生图失败 → 检索
都失败 → 纯色图形
字体不可达 → 系统字体栈(PingFang / 微软雅黑)
TTS 不可用 → 浏览器语音合成
BGM 不可用 → UI 明确提示配置方式(不静默占位)
核心原则(来自 agent.ts 顶部注释):
任一环节失败都能优雅降级……关键:素材装配与 LLM 解耦——即便走本地兜底,只要配了 Pexels / 文生图 key,产出依然有真实画面。
还有一个很可贵的细节:“绝不静默占位”。功能不可用时不偷偷用占位符糊弄,而是返回 { code: 'NO_KEY' },UI 明确提示用户如何配置。这建立的是用户信任。
八、设计理念总结
整个项目的核心设计哲学,可以概括为三句话:
- Spec 是唯一真相源 — 所有 Agent 输出、用户操作、渲染引擎都围绕 VideoSpec 收敛,不是黑盒。可审阅、可 diff、可回滚。
- 每层都有降级 — LLM → 规则、检索 → 生成、生成 → 检索、全失败 → 纯色,绝不崩溃。功能不可用时不静默占位,UI 明确提示。
- 确定性优先 — 固定种子 + 帧号驱动 + 相同输入相同输出,这是”可复现”的技术保证。
给想搭视频生成 Agent 应用的人,最重要的三条建议:
- 先设计好结构化中间表示(Spec),再谈 Agent 和渲染——这是”可控”的根基。
- 创意与校验分离:创意交给模型,校验交给确定性规则,各自发挥所长。
- 从第一天就做降级设计:Agent 应用链条长、外部依赖多,不降级就是个脆弱的 demo。
本文基于某个内部视频生成 Agent 项目的技术设计文档整理
参考来源
- Remotion — React 程序化视频生成框架
- Zustand — 轻量状态管理库
- Zod — TypeScript Schema 校验库
- Pexels API — 免费商用图片/视频检索
- DashScope CosyVoice — 阿里云 TTS 服务
- ElevenLabs — AI 语音生成平台