Medeo.app 工程实现方法拆解(续篇 2–6 完整整合版)
AI 导读
Medeo.app 工程实现方法拆解(续篇 2–6 完整整合版) 整合内容覆盖:Recipe/DAG、Planner/Locator、渲染与缓存、计费与运营、企业/API、质量门槛、Op 指令集、A/B 与个性化等(章节 11–52 + 附录 2–7)。 工程化:Patch/DSL 体验:渐进式交付 成本:segment cache 稳定:可回放/可回归 商业化:审计/配额 目录(11–20)...
11) Recipe 系统:把“100+ 生成器”工程化成可维护的工作流库
新增入口只新增 recipe 配置;核心引擎与执行管线保持稳定,可 A/B、可运营、可回放。
Recipe 的工程定义
- 输入 Schema:URL / script / slides / assets / language / platform
- 工作流 DAG:解析 → 结构化脚本 → 分镜 → 素材 → 配音 → 字幕 → 混音 → 渲染
- 默认参数:字幕样式、镜头节奏、BGM 音量、转场密度
- 质量门槛:字幕越界、黑屏、响度、时长偏差等硬指标
核心优势
- 入口多不等于代码乱:新增入口≈新增 recipe 配置
- 可 A/B:同输入套不同 recipe 比较留存/导出率/成本
- 可运营:爆款模板沉淀为 recipe,持续迭代默认参数
11.1 Recipe 配置示例
{
"recipe_id": "r_url_to_shorts_v1",
"name": "URL → 9:16 Shorts",
"inputs": {
"url": "string",
"language": "zh-CN",
"target_length_sec": 45,
"tone": "energetic"
},
"defaults": {
"aspect": "9:16",
"fps": 30,
"caption_style": "bold_pop",
"cut_density_per_min": 22,
"bgm_target_lufs": -18,
"vo_target_lufs": -14
},
"dag": [
{"id":"fetch", "type":"fetch_url"},
{"id":"extract", "type":"extract_keypoints", "deps":["fetch"]},
{"id":"script", "type":"write_script", "deps":["extract"]},
{"id":"scenes", "type":"scene_plan", "deps":["script"]},
{"id":"stock", "type":"stock_search", "deps":["scenes"]},
{"id":"tts", "type":"tts_generate", "deps":["script"]},
{"id":"caps", "type":"caption_generate_align", "deps":["tts"]},
{"id":"mix", "type":"mix_audio", "deps":["tts"]},
{"id":"preview", "type":"render_preview", "deps":["stock","caps","mix"]},
{"id":"final", "type":"render_final", "deps":["preview"]}
],
"quality_gates": [
{"rule":"no_black_frames", "threshold": 0},
{"rule":"caption_safe_area_violation", "threshold": 0},
{"rule":"audio_clipping_ratio", "threshold": 0.001}
]
}
12) 模型路由与降级:让系统在峰值、失败与成本压力下仍可交付
为什么必须做 Router
- 不同任务适合不同模型:脚本、字幕、视频生成、一致性需求差异大
- 成本与 SLA:Preview 更重延迟;Final 更重质量
- 峰值排队:动态选择更快/更便宜路径
Router 的输入信号
- 任务类型(TTS/VideoGen/Render/Script)
- 用户层级(tier)与 SLA(preview/final)
- 预算(credits)、队列拥塞、失败率
- 缓存命中可能性(同 prompt / 同资产复用)
12.1 降级阶梯(Fallback Ladder)
VideoGen 失败 / 排队爆炸时:
1) 复用已有素材(stock b-roll)替代生成镜头
2) 降分辨率(preview 先 540p)
3) 缩短片段时长(先出核心段)
4) 使用更快模型(质量稍降)
5) 仅输出静帧 + 动效(Ken Burns / zoom)过渡
13) 协作与多人编辑:从一开始就按“可合并的工程文件”设计
13.1 最小协作能力(建议先做三件事)
- 乐观并发控制(OCC):revision + patch;冲突时 auto-rebase 或 fail-fast
- 锁粒度:可选 scene-level lock(只锁被编辑片段范围)
- Presence:谁在编辑哪段(UI 提示)减少冲突
13.2 Patch 合并策略(简单但好用)
Merge rules (example):
- 字幕样式类字段:可自动合并(last-write-wins)
- 时间线结构类操作(move/split):若目标 clip 已被移动 → 冲突
- 语义编辑(rewrite scene script):若 scene 文本未变 → 自动合并;否则提示用户选择版本
14) 存储与缓存:决定“实时感”和单位成本的关键
14.1 三类存储(建议拆开)
- Project Store:工程文件(JSON/Protobuf),强一致
- Artifact Store:媒体资产(音频/视频/图片),对象存储
- Job Store:任务与 step 状态,支持查询、回溯、对账
14.2 缓存策略(最值钱)
- Segment Cache:渲染分段复用(preview/final 共用)
- Asset Dedup:上传素材 hash 去重
- LLM Plan Cache:相同定位/意图短期复用(慎用)
- Search Cache:stock 检索结果缓存(关键词+风格)
14.3 Render Segment 键设计(示例)
segment_key = sha256(
clip_ids + timing + effects +
asset_hashes + style_hash +
resolution + fps + codec
)
15) 音频链路:旁白、BGM、ducking、响度标准化(决定“专业感”)
15.1 音频管线(典型)
- TTS 生成旁白(含 timing)
- 选择 BGM(节奏/情绪/平台匹配)
- Ducking:旁白出现时压低 BGM
- 响度标准化:目标 LUFS + true peak 限制
- 导出混音轨 + 多轨可选(可编辑)
15.2 质量门槛(建议硬性检查)
- Clipping:削波比例 < 0.1%
- True Peak:不超过 -1 dBTP(平台友好)
- VO vs BGM:旁白段 VO 相对 BGM 至少 +8~12 dB
- 开头 1s:避免突兀(fade in)
15.3 Ducking 伪代码(简化)
// given vo_segments: [{start,end}, ...]
for each frame t:
if t in vo_segments:
bgm_gain = lerp(bgm_gain, target=-12dB, attack=80ms)
else:
bgm_gain = lerp(bgm_gain, target=0dB, release=220ms)
16) 字幕系统:生成、对齐、排版、安全区(短视频爆款必备)
16.1 字幕对齐三种路径
- ASR 对齐:语音→文字(适合真人录音)
- TTS timing:TTS 自带 phoneme/word timing(适合旁白)
- Hybrid:先 TTS timing,再用轻量 ASR 微调(更稳)
16.2 排版规则(建议固化)
- 每行字数限制(中文 10~14)
- 断句优先:标点/语义短语
- 安全区:9:16 顶部/底部 UI 遮挡留白
- 高亮策略:关键词加粗/变色(风格模板)
16.3 Safe Area 规则示例(9:16)
safe_top = 0.10 * height
safe_bottom = 0.18 * height
caption_box.y must be in [safe_top, height - safe_bottom - box.h]
17) API / BFF 设计:支持 WebSocket 进度回推与可恢复任务
17.1 最小接口集合
| 接口 | 用途 | 关键点 |
|---|---|---|
POST /projects | 创建工程 | 返回 project_id + initial revision |
GET /projects/:id | 读取工程 | 支持按 scene/时间范围局部读取 |
POST /projects/:id/patch | 提交 patch | 携带 base_revision;返回 job_id |
POST /jobs/:id/cancel | 取消任务 | 取消传播到子 step;结算 |
GET /jobs/:id | 查询任务状态 | step 列表 + artifacts |
WS /projects/:id/stream | 实时更新 | push revision、progress、preview url |
17.2 WebSocket 事件示例
{
"type": "job_progress",
"project_id": "p_123",
"job_id": "job_88",
"progress": 0.62,
"stage": "render_preview",
"artifacts": [{"type":"video_preview","uri":".../prev.mp4"}],
"revision": 43
}
18) 测试与评估:让“生成系统”可回归、可持续迭代
18.1 回归测试三件套
- Golden Projects:固定输入工程(脚本/素材)
- Deterministic Mode:固定随机种子/固定模型版本
- Diff 工具:时间线 diff、字幕 diff、音频响度 diff
18.2 自动质量评估(可量化)
- 黑屏/空音频检测
- 字幕越界与遮挡检测
- 音频 clipping / LUFS 合规
- 镜头切换节奏分布异常报警
18.3 Timeline Diff 示例(概念)
diff:
- clip_7 start: 11.2s → 10.6s
- clip_7 speed: 1.0 → 1.15
- aud_vo_2 asset: as_tts_21 → as_tts_33
- cap_2 text changed (len 18 → 12)
19) 安全与合规:上传素材、版权与隔离(商业化绕不过)
19.1 最小安全清单
- 上传扫描:病毒/恶意文件、格式白名单
- 租户隔离:artifact 按 user/org 隔离访问控制
- 签名 URL:预览/下载使用短期签名链接
- License 记录:stock 来源、授权信息写入元数据
- 审计日志:谁生成、谁导出、用的什么资产与模型
20) 基础设施与成本:把单位成本压到可持续(规模化必修课)
20.1 成本归因(必做)
- 每个 step 的 usage_report 写入账本
- 按 recipe / 用户层级 / 平台比例统计成本
- 找出成本 Top:通常是 VideoGen 与 Render
20.2 立竿见影的降本策略
- Preview 优先:先低清出结果,减少无效 final
- Segment cache:减少重渲
- 素材复用:尽量 stock + 动效替代重生成
- 队列限流:避免雪崩,优先保证可交付
20.3 “先交付、后精炼”的产能模型
Phase 1: draft (fast, cheap) → 用户确认方向
Phase 2: refine (targeted) → 只对不满意段落做重操作
Phase 3: final export (heavy) → 只在用户点击导出时触发
附录(续):更完整的对象模型与事件溯源(Event Sourcing)
事件溯源建议结构
{
"event_id": "ev_10092",
"project_id": "p_123",
"rev": 43,
"type": "PATCH_APPLIED",
"actor": {"kind":"assistant","id":"sys"},
"ops": ["op_9f31","op_aa02"],
"job_id": "job_88",
"ts": "2026-01-05T10:12:11Z",
"summary": "加快 clip_7,替换旁白并重对齐字幕"
}
常见事件类型
PROJECT_CREATEDASSET_UPLOADEDPATCH_SUBMITTEDPATCH_APPLIEDJOB_STARTEDJOB_CANCELED
STEP_SUCCEEDEDSTEP_FAILEDRENDER_PREVIEW_READYRENDER_FINAL_READYCREDITS_RESERVEDCREDITS_COMMITTED
21) LLM 规划器(Planner):从自然语言到可执行 Patch 的“可控链路”
关键不是让模型更聪明,而是让它在可控轨道上输出:先定位(Locate)再规划(Plan)再校验(Validate)再执行(Execute)。
21.1 Planner 的输入
- User Utterance:本轮用户指令
- Project Digest:工程摘要(脚本/分镜/风格/约束)
- Focused Snapshot:相关时间范围对象列表
- Policies:预算、白名单、品牌/安全规则
- Tooling:可调用工具(locate/search/estimate…)
21.2 Planner 的输出
- Locate Result:模糊语言→scene/clip IDs
- Patch JSON:严格 schema 的 ops 列表
- Human Summary:与 patch 对齐的人话说明
- Cost & Risk:预计 credits/耗时/是否重渲
21.3 多阶段规划(更稳)
Stage A: Normalize
- 规范化结构:{target_range?, target_scene?, change_type, constraints}
Stage B: Locate (tool + rules + LLM)
- 先用索引/规则定位候选,再让 LLM 选择最可能目标
- 输出:target_ids + confidence + fallback question(if needed)
Stage C: Plan
- 生成 patch(ops),每个 op 显式绑定对象 ID
Stage D: Validate & Repair
- schema 校验失败 → 回灌错误让模型修复(最多 N 次)
- 语义校验失败(越界/引用不存在)→ 重定位或请求用户澄清
Stage E: Execute
- 进入 DAG + Queue
Stage F: Summarize
- 同步:改动说明、预览何时可见、最终导出是否额外时间
22) 定位系统(Locator):把“那段/第二点/12 秒”映射到工程对象
现象级体验的隐藏关键:用户永远模糊表达,但系统必须精确命中对象。
22.1 三种定位信号(建议都实现)
时间信号
- “12 秒附近”“开头 5 秒”“结尾那段”
- 映射:timeline range → overlap clips
语义信号
- “第二个观点”“讲原因那段”
- 映射:outline/scene summaries → scene_id
文本信号
- “把‘因此我们…’那句换掉”
- 映射:caption/vo transcript search → segment ids
UI 选择信号(最强)
- 用户点选 clip/caption
- 映射:selected_object_id(直接锁定)
22.2 Locator 工具接口(示例)
{
"type": "locate_targets",
"input": {
"project_id":"p_123",
"query":"把第二个观点那段节奏加快一点",
"hints":{"selected_ids":[], "cursor_time": 11.8}
},
"output": {
"candidates":[
{"type":"scene","id":"s2","range":[6.5,18.0],"score":0.86},
{"type":"clip","id":"clip_7","range":[11.2,14.3],"score":0.63}
],
"best":{"type":"scene","id":"s2"},
"confidence":0.86
}
}
23) 风格系统(Style System):把“好看”变成模板、约束与可复用资产
23.1 Style Token(建议结构化)
- 主题:dark/light、品牌色、对比度
- 字幕:字体/描边/背景条/关键词高亮规则
- 镜头:动效强度、cut 密度、转场类型
- 音频:BGM 类型、ducking、目标 LUFS
23.2 Style Template 的复用
- 平台模板:Shorts/TikTok/Reels(安全区与节奏不同)
- 行业模板:电商/教育/工具测评(字幕与结构不同)
- 品牌模板:企业客户固定片头片尾、字体与色彩
23.3 Style Profile 示例
{
"style_id": "style_bold_pop_v2",
"caption": {
"font": "Inter-Bold",
"stroke_px": 6,
"shadow": true,
"highlight": {"mode":"keyword", "max_per_line":2}
},
"motion": {
"kenburns_strength": 0.35,
"transition": {"type":"whip", "duration_ms":240},
"cut_density_per_min": 24
},
"audio": {
"vo_target_lufs": -14,
"bgm_target_lufs": -18,
"ducking_db": -12,
"duck_attack_ms": 80,
"duck_release_ms": 220
},
"safe_area": {"top": 0.10, "bottom": 0.18}
}
24) Prompt / Tooling:把“提示词”产品化成可审计、可回放、可回归
不要把 prompt 写死在代码里:版本化+回放才能持续迭代。
24.1 Prompt 版本化(建议)
{
"prompt_id": "planner_patch_v6",
"purpose": "Chat → Patch",
"schema": "PatchSchema@1.2",
"system": "你是视频工程规划器,只输出 JSON ...",
"fewshots": ["..."],
"constraints": ["不得输出自然语言", "必须绑定 clip_id", "..."],
"created_at": "2026-01-05",
"owner": "video-platform"
}
24.2 Prompt 回放(Replay)
- 记录:输入 context(脱敏)+ 输出 patch + validator 结果
- 用途:回归测试、事故追溯、A/B 比较
24.3 Tool-first(强推荐)
- 定位/搜索/估算先用工具做硬事实
- LLM 做决策并生成 patch(不要让它“凭空检索/计算”)
25) 内容治理与策略:把风险前置到 Planning 与导出阶段
25.1 最有效的两个位置
- Planning:限制素材来源、模型白名单、内容类型
- Export:final 前做最后检查(字幕/音频/版权元数据)
25.2 最小策略对象(Policy)
- 禁止/限制素材类型与来源
- 敏感词/合规规则(地区/行业)
- 企业品牌约束:字体/颜色/片头片尾
25.3 Policy 示例(概念)
{
"policy_id": "org_brand_policy_01",
"allowed_stock_sources": ["sourceA","sourceB"],
"allowed_models": ["fast_video_v1","hq_video_v2"],
"require_license_metadata": true,
"caption_safe_area_enforced": true,
"banned_terms": ["..."],
"watermark": {"enabled": false}
}
26) 现象级增长飞轮:工程系统如何反哺产品增长
26.1 飞轮 1:模板沉淀 → 更快成功率
- 高频需求提炼 recipe
- recipe 让新用户“第一次就成功”
- 成功率↑ → 留存↑ → 更多数据
26.2 飞轮 2:可回放 → 快速迭代质量
- Patch/Job/Usage 全链路日志
- 定位失败、字幕越界、响度不稳 → 指标化
- 指标驱动迭代 → 质量↑ → 付费↑
26.3 飞轮 3:成本运营 → 更强定价与 SLA
- 掌握每个 recipe 的单位成本与转化率
- 分 tier 提供不同 SLA(preview 优先、final 排队)
- 实现“更便宜/更快/更稳”的组合壁垒
27) 全链路蓝图:把系统拆成可立即开工的模块清单
| 模块 | 最小能力 | 第一版就要做的工程点 |
|---|---|---|
| Project Service | 工程文件 CRUD、revision、局部读取 | 稳定 ID、patch log、冲突检测 |
| Planner Service | Chat → Patch(JSON) | schema 验证、repair、policy 注入 |
| Locator Service | 语义/时间/文本定位 | 索引结构、候选输出、置信度 |
| Orchestrator | DAG、队列、重试、取消 | 幂等、优先级、分阶段扣费 |
| Render Service | Preview/Final、Segment Cache | 脏区间计算、拼接、缓存键 |
| Asset Service | 上传/检索/授权元数据 | hash 去重、签名 URL、隔离 |
| Billing/Credits | 估算、预扣、结算、账本 | usage_report、对账、申诉依据 |
| Observability | 日志/指标/追踪 | 质量门槛、告警、回归集 |
附录(再续):失败模式与防护(Failure Modes)清单
常见失败模式
- 定位错目标 → 改错段
- 字幕越界/被 UI 挡住
- 音频响度不稳、削波
- 渲染缓存失效 → 成本暴涨
- 队列雪崩 → 所有人都慢
- 重试重复扣费 → 争议
对应防护
- Locator + 置信度 + 候选确认
- Quality gate(导出前硬检测)
- 响度标准化 + clipping 检测
- Segment cache + 统一键策略
- 资源池隔离 + 限流 + 优先级
- op_id 幂等 + usage_report 账本
28) 索引与检索:让“找素材/找句子/找片段”像数据库一样快
对话式编辑效率来自“快速定位目标”。依赖:文本索引、时间索引、语义索引三件套。
28.1 必备索引
- Transcript Index:旁白/字幕(倒排 + 时间戳)
- Timeline Range Index:start/end → 对象(interval tree / segment map)
- Scene Semantic Index:scene summary/outline → 向量检索(可选)
28.2 更新时机
- 每次 patch 应用后增量更新“受影响范围”的索引
- digest 异步刷新避免阻塞 UI
- 向量索引延迟更新可接受(只影响语义查找)
28.3 Transcript 索引结构示例
{
"project_id": "p_123",
"utterances": [
{"seg_id":"cap_2","text":"因此我们可以…","start":11.2,"end":14.0},
{"seg_id":"cap_3","text":"接下来讲原因…","start":14.0,"end":18.0}
],
"inverted": {
"因此": ["cap_2"],
"原因": ["cap_3"]
}
}
29) B-roll 选择引擎:比“生成镜头”更省钱、更稳的爆款路径
大量爆款短视频镜头来自 stock + 动效 + 字幕,而不是全程视频生成。
29.1 输入
- Scene summary(这一段讲什么)
- 关键词/实体(产品名、地点、动作)
- 平台风格(快节奏、强对比)
- 版权/来源限制(policy)
29.2 排序打分(可落地)
- semantic_score:语义匹配(标题/标签/摘要)
- quality_score:清晰度、噪点、分辨率
- fit_score:时长、构图适配 9:16
- diversity:避免连续重复画面
- license_ok:授权合规必过
29.3 选择策略:先稳后花
For each scene:
1) try stock_topK (cheap, fast)
2) if no good match → use still image + motion (Ken Burns)
3) if still weak AND user wants "更电影感" → trigger video generation for that scene only
30) 节奏引擎(Pacing Engine):把“好看”变成算法与约束
“爽感”来自节奏:切镜密度、字幕更新频率、动效强度、鼓点对齐。
30.1 可量化节奏指标
- Cut density:每分钟切镜次数
- Avg shot length:镜头平均时长
- Caption refresh rate:字幕更新频率
- Motion intensity:缩放/平移强度
- Beat alignment:切镜对齐鼓点比例(可选)
30.2 节奏策略(模板化)
- Hook 段:更快(1.0~1.6s/镜头)
- Explain 段:中速(1.6~3.0s/镜头)
- CTA 段:再加速 + 强字幕
30.3 Pacing 调整 patch 示例
{
"ops": [
{"op_id":"op_p1","type":"set_pacing_profile","target":{"scene_id":"s1"},
"params":{"avg_shot_len":1.2,"cut_density_per_min":30}},
{"op_id":"op_p2","type":"set_pacing_profile","target":{"scene_id":"s2"},
"params":{"avg_shot_len":2.4,"cut_density_per_min":18}}
]
}
31) 多比例导出(9:16 / 16:9 / 1:1):不是“裁剪”而是“重排版”
多比例如果只是 crop,会导致主体跑出画面、字幕遮挡。正确做法:维护布局层(layout layer)。
31.1 Layout Layer(建议)
- 每个 clip 支持 framing:主体区域/锚点/缩放
- 字幕支持 safe area:不同平台不同边距
- 为不同 aspect 保存 layout 变体
31.2 自动重排版策略
- 识别主体区域(人脸/主体框/显著性)
- 主体保持在安全区内
- 字幕永远不越界
- 必要时背景模糊填充(16:9→9:16 常用)
31.3 Layout patch 示例
{
"ops": [
{"op_id":"op_l1","type":"set_clip_framing",
"target":{"clip_id":"clip_7"},
"params":{
"aspect":"9:16",
"anchor":"center",
"scale":1.25,
"pan":{"x":0.08,"y":-0.02}
}}
]
}
32) 编辑器实现:Timeline UI 如何与 Patch/Job 系统强一致
轨道编辑器是 Project/DSL 的可视化前端:所有编辑都变成 patch,统一走同一条链路。
32.1 三层状态
- Server Truth:后端 project revision(唯一真相)
- Optimistic UI:前端本地预览(立即响应)
- Reconcile:WS 返回新 revision 后对齐(必要时回滚局部)
32.2 必备交互
- 对象选择:selected_ids → 提升 Locator 命中率
- 拖拽/裁剪:实时显示 in/out 与时间范围
- 撤销/重做:基于 patch log(而非只前端)
- 局部预览:只播放当前 scene range
32.3 提交 patch 的典型流程
onUserDragClip(clip_id, newStart):
patch = {base_revision, ops:[{type:"move_clip", target:{clip_id}, params:{start:newStart}}]}
applyOptimistic(patch)
POST /projects/:id/patch
WS receive revision:
if ok → commit optimistic
if conflict → rollback + show diff
33) 性能与体验:端到端要做到“像实时”,工程上要做到“可渐进”
33.1 延迟预算(建议)
- Locate(< 300ms):索引/规则优先
- Plan(1~3s):LLM + schema 校验
- Preview(2~10s):只渲脏区间
- Final(后台):队列 + 断点续渲
33.2 让用户“感到快”的策略
- 先给“我将做什么”的摘要(即时反馈)
- 先出局部预览(哪怕 3 秒)
- 按 step 显示进度(不要假进度)
- 可取消且可恢复(降低挫败感)
33.3 渐进式交付(Progressive Delivery)
t=0s : show plan summary + estimated cost
t=1-3s : preview of changed segment ready
t=3-10s: captions/alignment refined
later : final export ready (notify)
34) 对话式编辑的关键 UX 回路:把不确定性变成“可选择”
34.1 三类不确定性
- 目标不明确(那段是哪段)
- 改动方向不明确(更快=加速还是剪短)
- 质量偏好不明确(更电影感=滤镜/转场/镜头)
34.2 处理方式
- 给候选:A/B 方案 + 预览片段
- 用 patch 解释:清楚写“做了哪些 op”
- 允许撤销:一键回到上一 revision
34.3 A/B 方案输出结构(示例)
{
"options": [
{"label":"A-加速","patch":{...}, "effect":"speed 1.15x, keep content"},
{"label":"B-剪短","patch":{...}, "effect":"remove filler, shorten 2.0s"}
],
"recommend": "A",
"reason": "保持信息完整,节奏更快"
}
附录(续 4):可直接开工的最小 Worker 列表与接口契约
Worker 清单(MVP)
| Worker | 输入 | 输出 | 备注 |
|---|---|---|---|
| stock_search | keywords, constraints | asset_ids ranked | 必须 license_ok |
| tts_generate | text, voice_id | audio + timing | timing 帮字幕对齐 |
| caption_align | timing, text | caption segments | safe area 规则 |
| mix_audio | vo, bgm | mixed track | ducking + loudness |
| render_preview | project range | preview mp4 | 增量 segment cache |
| render_final | full project | final mp4 | 后台任务 |
统一 Step 接口契约(建议)
input:
{
"job_id":"job_88",
"step_id":"step_render_preview_1",
"project_id":"p_123",
"revision": 43,
"params": {...},
"artifacts_in": [{"artifact_id":"..."}],
"policy_id":"org_policy_01"
}
output:
{
"status":"SUCCEEDED",
"artifacts_out":[{"artifact_id":"as_prev_91","type":"video","uri":"..."}],
"metrics":{"latency_ms": 2400},
"usage_report":{"credits": 3.2, "cache_hit": true}
}
35) 供应商与模型抽象(Provider Abstraction):可换、可混用、可审计
35.1 Provider 统一接口
- request:标准化输入(prompt/assets/policy/seed)
- response:标准化输出(artifact/metadata/usage_report)
- errors:标准化错误(quota/timeout/invalid_input/policy_block)
- idempotency_key:避免重试重复计费
35.2 Capabilities(能力声明)
- 分辨率/FPS/最长时长
- 是否支持 ref image / character id
- 是否返回 timing/mask/depth 等辅助信息
- 平均延迟、失败率、成本系数(运营输入)
35.3 Provider Registry 示例
{
"providers": [
{
"id":"video_fast_v1",
"type":"videogen",
"caps":{"max_sec":6,"max_res":"720p","ref_image":false,"fps":[24,30]},
"sla":{"p50_ms":7000,"p95_ms":18000},
"cost":{"credits_per_sec_720p":2.4}
},
{
"id":"video_hq_v2",
"type":"videogen",
"caps":{"max_sec":10,"max_res":"1080p","ref_image":true,"fps":[24,30]},
"sla":{"p50_ms":25000,"p95_ms":60000},
"cost":{"credits_per_sec_1080p":6.8}
}
]
}
36) 一致性(Consistency):角色一致、风格一致、时间一致的抓手
一致性=版本化 + 稳定 ID + 约束 + 缓存 + 可回放。
36.1 三类一致性对象
- Character Profile:char_id → ref_images + embedding_version
- Style Profile:style_id → caption/motion/audio tokens
- Recipe Version:recipe_id@vN → DAG + defaults + gates
36.2 落地机制
- 所有生成请求绑定:char_id / style_id / recipe_version
- 同一对象复用 seed / prompt 模板(可配置)
- 每次 patch 产生 revision,可回滚到任意稳定状态
36.3 一致性指纹(用于缓存/回放/审计)
{
"fingerprint": {
"recipe":"r_url_to_shorts@2",
"style":"style_bold_pop@2",
"character":"char_7@5",
"providers":{"videogen":"video_hq_v2","tts":"tts_vendor_x"},
"seed_policy":"stable_seed",
"policy":"org_policy_01"
}
}
37) 渲染实现细节:从 Project 到 Render Graph / Segment Pipeline
37.1 Render Graph(概念)
Nodes:
- Decode(asset)
- Transform(scale/crop/pan/blur)
- Composite(layers)
- CaptionRender(text, style, safe_area)
- AudioMix(vo, bgm, ducking, loudness)
- Encode(h264/av1, bitrate)
Edges:
- timeline order
- overlay layers
- audio sidechain for ducking
37.2 Segment 切分策略
- 按 scene 切分(语义稳定)
- 转场单独成段(避免污染邻段缓存)
- 字幕/动效变化点切段(减少脏区间扩散)
37.3 Stitch 拼接策略
- segment → concat(视频)
- 音频:分段混音后 concat(或全局一次混音)
- 最终 mux:封装音视频
38) 取消与恢复:让用户敢点“生成”,也敢点“取消”
38.1 Cancel 传播(建议)
- Job.cancel → job_state=CANCELING
- 未开始 step 直接取消
- 运行中 step 尝试中断;不可中断则“完成后丢弃输出”
- 结算:commit 已完成 steps,释放未执行 steps 的 reserve
38.2 Resume 两种路径
- Retry step:对失败 step 重试,复用已完成 artifacts
- Resume final:预览已完成,只恢复 final 导出
38.3 可恢复关键:Artifact Catalog
{
"job_id":"job_88",
"artifacts": [
{"id":"as_tts_33","type":"audio","from_step":"tts","status":"ready"},
{"id":"as_caps_10","type":"captions","from_step":"caps","status":"ready"},
{"id":"as_prev_91","type":"video_preview","from_step":"preview","status":"ready"}
]
}
39) 通知系统:Final 后台跑,但用户不迷路
WS 实时更新 + 离线通知(站内/邮件/Push)闭环。
39.1 通知事件
- preview_ready
- final_ready
- job_failed(可解释原因 + retry)
- credits_low / reserve_failed
39.2 去重与幂等
- event_id 去重
- 同一 job 的 final_ready 只发一次
- 失败通知合并(避免刷屏)
39.3 通知 payload 示例
{
"event":"final_ready",
"project_id":"p_123",
"job_id":"job_88",
"revision": 43,
"assets":[{"type":"final_video","uri":".../final.mp4"}],
"cta":"Open Export"
}
40) 企业与 API:把能力“服务化”,同时保持隔离、审计与 SLA
40.1 企业必备能力
- 组织/成员管理(RBAC)
- 品牌模板(style/policy/intro/outro)
- 审计日志(谁生成、用的什么素材与模型)
- 配额与预算(credits per org / per project)
40.2 API 形态(建议)
- 同步:小任务(脚本/定位/估算)
- 异步:重任务(渲染/视频生成)→ job_id + webhook
- Webhook:final_ready/job_failed 通知
40.3 Webhook 示例
{
"webhook_event":"job_succeeded",
"job_id":"job_88",
"project_id":"p_123",
"revision": 43,
"artifacts":[{"type":"final_video","uri":".../final.mp4"}],
"usage_report":{"credits_committed": 42.6}
}
41) 运营面板(Ops Dashboard):把质量、成本、队列、转化统一到一个地方
41.1 核心视图
生产视图(SLA)
- 队列长度、等待时间(tier 分层)
- preview/final 的 P50/P95
- 失败率与错误 TopN(按 provider/recipe)
成本视图(Unit Economics)
- 每个 recipe 平均 credits
- 缓存命中节省
- 昂贵 steps(VideoGen/Render)占比
质量视图(Quality)
- 字幕越界率、响度不合规率
- 撤销/回滚频率(不满意信号)
- 导出后重编辑比例(初稿不稳信号)
增长视图(Funnel)
- 首次成功率(first draft success)
- preview → final 点击率
- final → export/分享率
附录(续 5):端到端时序图(文字版)
User: "把第二段节奏加快,并把旁白更简洁"
↓
Client:
- send chat message + cursor_time/selected_ids
↓
BFF:
- fetch project digest + snapshot(range) + policy + budget
- call locator → candidates(scene s2)
- call planner → patch(base_rev=43, ops=[...])
- run validator → ok
- run estimator → reserve credits
- create job(job_90) + enqueue
↓
Orchestrator:
- build DAG( tts → caps → preview )
- dispatch steps with priority(tier, preview first)
↓
Workers:
- tts_generate → as_tts_40 + timing + usage
- caption_align → as_caps_12 + usage
- render_preview(DirtyRange) → as_prev_102 + usage
↓
BFF:
- apply patch to project(rev=44)
- WS push: preview_ready + revision=44 + preview uri
↓
User:
- sees preview, asks "再快一点"
- loop again
↓
User clicks Export:
- enqueue render_final
- notify when final_ready
42) 数据契约与 Schema:让系统可扩展、可回归、可协作
42.1 三类核心 Schema
- ProjectSchema:工程文件(timeline/scenes/style/layout)
- PatchSchema:ops 列表与参数(可执行 IR)
- StepContract:worker 输入输出(artifact + usage_report)
42.2 版本策略(建议)
- Schema 号:
Project@1.3/Patch@1.2 - 新增字段只允许 optional + default
- 删除字段:deprecated → removed 两个版本
- 存储层可做读时迁移(read-time migration)
42.3 PatchSchema(片段)示意
{
"PatchSchema": "1.2",
"project_id": "string",
"base_revision": "int",
"ops": [
{
"op_id": "string",
"type": "enum",
"target": "object",
"params": "object",
"cost_hint": "object?"
}
]
}
43) 质量门槛(Quality Gates)工程实现:把“翻车点”变成自动阻断
导出前硬检查:失败则不给 final 或要求修复,最好带自动修复 patch。
43.1 Gate 触发点
- Preview Gate:快速检查(字幕越界、黑屏、空音频)
- Final Gate:完整检查(响度、true peak、版权元数据、分辨率一致性)
43.2 Gate 输出
- pass/fail + evidence(证据)
- repair_suggestion(修复建议)
- auto_repair_patch(可选:自动修复)
43.3 Gate 示例:字幕安全区检查
{
"gate":"caption_safe_area",
"status":"FAIL",
"evidence":[
{"seg_id":"cap_12","time":[8.2,9.6],"box":{"x":0.12,"y":0.86,"w":0.78,"h":0.10},
"violation":"bottom_out_of_safe_area"}
],
"suggestion":"将字幕上移 8% 或缩小字号",
"auto_repair_patch":{
"ops":[{"op_id":"op_fix_1","type":"adjust_caption_layout",
"target":{"track_id":"t_c1"},
"params":{"y_offset":-0.08,"scale":0.95}}]
}
}
44) 自动剪辑策略(Auto-editing):把“默认就好看”固化成规则库
44.1 默认剪辑规则(Playbook)
| 规则 | 触发 | 动作 | 为什么 |
|---|---|---|---|
| Remove Filler | 停顿/赘词多 | 剪掉静默 > 300ms;重对齐字幕 | 节奏立刻提升 |
| Hook Boost | 前 2 秒密度低 | 前置亮点句;提高 cut density;关键词高亮 | 提升留存 |
| Beat Cuts | BGM 鼓点明显 | 切镜对齐鼓点(容差 80ms) | 更“爽” |
| Caption Pop | 关键句出现 | 字幕放大 1.1x + 高亮色 | 信息更清晰 |
| CTA Emphasis | 结尾 CTA | 加速节奏 + 强字幕 + 轻微抖动动效 | 提升转化 |
44.2 Playbook 工程形式
{
"playbook_id":"pb_shorts_default_v3",
"rules":[
{"id":"r1","when":"silence_gt_ms:300","do":["remove_silence","re_align_captions"]},
{"id":"r2","when":"hook_density_low","do":["reorder_hook","increase_cut_density"]},
{"id":"r3","when":"cta_scene","do":["caption_emphasis","motion_boost"]}
]
}
45) 分镜生成(Storyboarding):Scene → Shot 中间层决定可编辑性
分镜层让系统能回答:讲什么、有哪些镜头、镜头对应哪句旁白,从而支持局部重算与语义编辑。
45.1 最小对象
- Scene:语义段落(range + summary + intent)
- Shot:镜头单元(asset binding + motion + duration)
- Bindings:shot ↔ transcript segments ↔ captions
45.2 为什么关键
- “第二个观点那段”→ scene_id
- “这个镜头换冲击力更强的”→ shot_id
- 局部重算:只重做某个 scene/shot
45.3 Storyboard 示例
{
"scene_id":"s2",
"range":[6.5,18.0],
"summary":"解释原因",
"shots":[
{"shot_id":"sh_21","dur":2.0,"asset_pref":"stock","keywords":["原因","分析"],"motion":"zoom_in"},
{"shot_id":"sh_22","dur":2.4,"asset_pref":"stock","keywords":["对比","数据"],"motion":"pan_left"},
{"shot_id":"sh_23","dur":1.8,"asset_pref":"still+motion","keywords":["总结"],"motion":"kenburns"}
],
"bindings":{
"vo_seg_ids":["vo_5","vo_6"],
"cap_seg_ids":["cap_9","cap_10","cap_11"]
}
}
46) 可解释性(Explainability):让用户知道“你到底改了什么”
46.1 人话摘要(与 patch 对齐)
- 目标:Scene s2(6.5s–18.0s)
- 动作:加速 clip_7;删静默;替换旁白文案
- 影响:重对齐字幕;预览更新 11.2s–14.3s
46.2 Diff 可视化(数据层)
- Timeline diff:start/end/speed
- Caption diff:文本变化 + 时间戳变化
- Asset diff:素材替换记录
46.3 Explain payload 示例
{
"revision": 44,
"target": {"scene_id":"s2","range":[6.5,18.0]},
"changes":[
{"type":"speed_change","clip_id":"clip_7","from":1.0,"to":1.15},
{"type":"remove_silence","range":[12.8,13.4]},
{"type":"rewrite_vo","audio_id":"aud_vo_2","delta_chars":-42}
],
"preview_dirty_range":[11.2,14.3]
}
47) 爆款 Playbooks:把“从输入到爆款”的默认策略沉淀成组合包
47.1 URL → 爆款科普 Shorts
- 提取 3 个观点 + 1 句强 Hook(前 2 秒)
- 每观点 1 个反直觉例子(对比)
- 镜头:stock + 动效,切镜 22–28/min
- 字幕:关键词高亮;每行 10–12 字
- 音频:VO -14 LUFS;BGM -18 LUFS + ducking
47.2 脚本 → 工具测评短视频
- 结构:痛点 → 演示 → 对比 → 结论(CTA)
- 镜头:屏幕录制优先;关键步骤放大 + 标注
- 字幕:步骤编号(1/2/3)+ 关键词高亮
- 节奏:演示段稍慢,结论段加速
47.3 电商带货(短平快)
- 前 1 秒:价格/福利/强利益点
- 3 个卖点:每个 2 秒内讲完
- 镜头:产品特写 + 细节(避免重复)
- 字幕:大字号 + 强对比 + 价格突出
47.4 故事叙事(剧情向)
- 冲突前置:10 秒内出现矛盾
- 节奏:冲突段快、铺垫段慢
- 字幕:弱化样式,突出情绪词
- 音频:环境音 + BGM 推情绪(ducking 更柔)
recipe defaults + pacing profile + caption template + audio profile 的组合包。
附录(续 6):自动修复(Auto-repair)策略库示例
质量门槛失败后,尽量自动修复而不是让用户猜怎么改;修复 patch 也要进入版本历史并可撤销。
{
"auto_repairs":[
{
"when":"caption_safe_area_fail",
"fix":[
{"type":"adjust_caption_layout","params":{"y_offset":-0.08}},
{"type":"scale_caption","params":{"scale":0.95}},
{"type":"reduce_caption_chars","params":{"max_chars_per_line":12}}
]
},
{
"when":"audio_clipping_fail",
"fix":[
{"type":"normalize_loudness","params":{"target_lufs":-14}},
{"type":"limit_true_peak","params":{"dbtp":-1.0}}
]
},
{
"when":"black_frames_detected",
"fix":[
{"type":"replace_asset","params":{"strategy":"fallback_stock"}},
{"type":"add_background_fill","params":{"mode":"blur_fill"}}
]
}
]
}
48) Op Catalog:完整的“视频编辑原子操作”集合
Op Catalog 是 DSL 的指令集。建议每个 op 都有:参数 schema、成本估算、undo、dirty range 计算。
48.1 时间线与结构类
[
"insert_clip", "remove_clip", "move_clip", "duplicate_clip",
"trim_clip", "split_clip", "merge_clips",
"set_clip_speed", "set_clip_volume", "set_clip_opacity",
"set_transition", "set_track_order", "set_layer_zindex",
"set_scene_range", "create_scene", "delete_scene"
]
48.2 字幕与文本类
[
"generate_captions", "align_captions", "rewrite_captions",
"set_caption_style", "set_caption_safe_area", "adjust_caption_layout",
"highlight_keywords", "set_caption_language", "translate_captions",
"fix_caption_overflow", "set_caption_animation"
]
48.3 音频类(VO/BGM/SFX)
[
"tts_generate", "replace_voiceover", "rewrite_voiceover_text",
"select_bgm", "replace_bgm", "mix_audio", "set_ducking",
"normalize_loudness", "limit_true_peak", "add_sfx", "remove_sfx",
"fade_in", "fade_out"
]
48.4 视觉动效与布局类
[
"set_clip_framing", "set_pan_zoom", "set_kenburns",
"add_overlay", "remove_overlay", "set_overlay_position",
"add_blur_fill", "set_global_filter", "set_color_grade",
"set_motion_profile", "set_pacing_profile"
]
48.5 生成与资产类(高成本)
[
"stock_search", "replace_asset",
"generate_image_asset", "generate_video_asset",
"regenerate_shot", "regenerate_scene",
"create_character_profile", "update_character_profile",
"lock_character", "lock_style"
]
49) 语义编辑 → 时间线映射:把“改观点/改结构”变成可执行剪辑
三层模型:Script Layer → Storyboard Layer → Timeline Layer,通过 bindings 将语义改动安全落地到局部 patch。
49.1 三层模型
- Script Layer:outline + full_text
- Storyboard Layer:scene/shot(语义到镜头)
- Timeline Layer:tracks/clips(最终渲染)
49.2 映射(Bindings)
- script paragraph → scene_id
- scene_id → shot_ids
- shot_id → clip_ids + vo_seg_ids + cap_seg_ids
49.3 示例:让第二观点更清楚
1) rewrite script for scene s2 (shorter, clearer)
2) tts_generate new VO for s2
3) regenerate captions for s2
4) adjust pacing: slightly slower for s2
5) keep visuals mostly, but add 1 stock shot illustrating key term
Patch ops (high-level):
- rewrite_scene_script(s2)
- replace_voiceover(s2)
- align_captions(s2)
- set_pacing_profile(s2, avg_shot_len=2.6)
- insert_clip(after shot sh_22)
50) Toolchain:从“聊天”到“剪辑”的可扩展工具链
LLM 不应承担检索/计算/索引查询等硬事实工作;应编排工具并输出 patch。
50.1 推荐工具清单(可做内部 SDK)
定位与理解
locate_targetssearch_transcriptsummarize_scenediff_project
估算与校验
estimate_costvalidate_patchcompute_dirty_rangepolicy_check
素材与风格
stock_searchrank_assetsapply_style_templateauto_repair
任务编排
enqueue_jobcancel_jobresume_jobget_job_status
50.2 Tool-first Planner 伪代码
// Planner.run(utterance, project_id)
targets = locate_targets(utterance, hints)
snap = get_project_snapshot(project_id, targets.range)
policy = get_policy(project_id)
cost = estimate_cost(utterance, snap, policy)
patch = llm_generate_patch(utterance, snap, policy, cost)
validate_patch(patch) || patch = llm_repair_patch(errors)
dirty = compute_dirty_range(patch, snap)
job_id = enqueue_job(patch, dirty, priority=tier)
return {patch, job_id, dirty, cost, summary}
51) A/B 实验框架:让 Recipe / Style / Prompt 迭代有数据闭环
现象级产品迭代不是拍脑袋:用实验比较成功率、导出率、成本。
51.1 实验对象(可控变量)
- Recipe 版本(DAG/默认参数)
- Style 模板(字幕/动效/节奏)
- Prompt 版本(planner_patch_v6 vs v7)
- Router 策略(fast-first vs quality-first)
51.2 核心指标
- First Draft Success(首次满意率)
- Preview → Export 转化
- 单位成本(credits/视频分钟)
- 撤销/回滚频率(不满意信号)
51.3 分流结构示例
{
"experiment_id":"exp_recipe_shorts_v2",
"variants":[
{"name":"A","recipe":"r_url_to_shorts@2","style":"bold_pop@2"},
{"name":"B","recipe":"r_url_to_shorts@3","style":"bold_pop@2"}
],
"allocation":{"A":0.5,"B":0.5},
"unit":"user_id",
"start":"2026-01-05",
"metrics":["first_draft_success","export_rate","credits_per_min"]
}
52) 个性化(Personalization):用默认偏好提升成功率
52.1 用户偏好 Profile(建议)
- 常用风格:style_id
- 常用声音:voice_id
- 常用平台:9:16 / 16:9
- 节奏偏好:cut_density_range
- 常用 playbook:pb_shorts_default_v3
52.2 应用策略
- 新项目自动套用(可一键切回默认)
- 低置信度定位/风格选择优先用历史偏好
- 用户手动改动可更新 profile(建议有确认开关)
52.3 Preference Profile 示例
{
"user_id":"u_01",
"defaults":{
"style":"style_bold_pop@2",
"voice":"voice_zh_female_03",
"aspect":"9:16",
"playbook":"pb_shorts_default_v3",
"pacing":{"cut_density_per_min":24}
}
}
附录(续 7):Undo(撤销/重做)策略
撤销/重做若只做前端,会在异步任务/协作/多端下崩溃。建议从 revision rollback 起步。
Undo 两种实现
A) Revision Rollback(推荐)
- 直接回到上一 revision(最稳)
- 代价:需要存快照或可重放事件
B) Inverse Patch(高级)
- 每个 op 生成 inverse op(如 move_clip 的反向 move)
- 代价:实现复杂,需要捕获 pre-state
Inverse Patch 示例(概念)
{
"op":"move_clip",
"target":{"clip_id":"clip_7"},
"params":{"start":10.6},
"inverse":{
"op":"move_clip",
"target":{"clip_id":"clip_7"},
"params":{"start":11.2}
}
}