feat: expand novel IP and production workflows

docs/work-sync/04_短剧引擎/DRAMA_ENGINE_V1.md

@@ -0,0 +1,239 @@
+# 短剧引擎现状与设计 V1
+
+> 文档状态：当前有效  
+> 基线日期：2026-07-15  
+> 适用范围：分集、剧本、动态分镜、视觉资产、视频候选、质量控制与成片合成。
+
+## 1. 当前定位
+
+短剧引擎负责把已确认的故事内容转为可生产镜头，并持续管理人物、场景、表演、声音和后期之间的关系。当前系统同时支持真人/仿真人短剧、原生音频视频和传统“图片 + TTS + 字幕”合成，不应把任何单一模型当成完整导演系统。
+
+## 2. 核心原则
+
+1. 剧情完整度优先于固定镜头数量。
+2. 分镜时长由对白、动作、停顿和转场预算共同决定。
+3. 角色、服装、场景和关键道具必须引用明确资产版本。
+4. 首帧、首尾帧、多图参考和纯文本生成按镜头需要选择。
+5. 视频模型负责画面和可用原生声音，稳定文字 UI、字幕和进度条优先由后期完成。
+6. 表演、运镜、声音和镜头衔接都属于质量评分，不只检查画面清晰度。
+7. 每个付费请求必须保留完整提交参数和实际 Provider。
+
+## 3. 生产对象
+
+| 对象 | 作用 |
+| --- | --- |
+| `Episode` | 分集目标、顺序、状态和质量信息 |
+| `EpisodeScript` | 已确认的单集剧本与版本 |
+| `StoryboardShot` | 镜头时长、动作、对白、运镜、声音、Prompt 和衔接 |
+| `Character` / `GlobalCharacter` | 项目角色与可复用演员资产 |
+| `CharacterState` | 角色在特定时间点的服装、伤势、情绪等状态 |
+| `ProjectVisualAsset` | 场景、道具及其主版本 |
+| `ShotImage` | 首帧、尾帧、关键帧和候选图 |
+| `VideoClip` | 单镜视频候选、实际模型、QC 和选择状态 |
+| `Asset` | 图片、视频、音频、字幕和成品的统一素材记录 |
+| `RenderTask` | 异步任务、重试、成本和人工介入 |
+
+## 4. 标准流程
+
+```mermaid
+flowchart LR
+  Source[连续原文快照] --> Analysis[原著分析合同]
+  Analysis --> Bible[改编圣经合同]
+  Bible --> Episode[分集计划合同]
+  Episode --> Continuity[三集连续性检查]
+  Continuity --> Release[人工放行一集]
+  Release --> Script[单集剧本]
+  Script --> Shot[动态分镜]
+  Shot --> AssetPlan[角色/场景/道具资产计划]
+  AssetPlan --> Prompt[镜头 Prompt]
+  Prompt --> Frame[关键帧/参考图]
+  Frame --> Video[视频候选]
+  Video --> QC[自动 QC]
+  QC --> Select[重试/回退/人工选择]
+  Select --> Compose[字幕/声音/BGM/SFX/转场]
+  Compose --> Render[FFmpeg 成片]
+  Render --> Review[审核与作品库]
+```
+
+`splus_v1` 新项目使用上述结构化写路径。旧项目的 StoryBible、Episode 和历史 Prompt 保持原样，不自动迁移；旧写接口不能向新项目写入。原著分析、改编圣经和分集计划均追加新版本，并保存来源、质量问题和人工确认记录。
+
+## 5. 剧本到分镜
+
+### 5.1 剧本审核
+
+每集应对照来源文本和上下集，检查：
+
+- 核心事实、动机和因果是否保留。
+- 是否为压时长而删掉必要台词或反应。
+- 对白是否像角色在表演，而不是信息段落拼接。
+- 心理旁白、悬疑信息和听觉线索是否服务情绪。
+- 本集钩子、高潮和尾点是否成立。
+
+### 5.2 动态时长
+
+时长估算至少包含：
+
+```text
+对白朗读时间
++ 动作完成时间
++ 反应/停顿时间
++ 运镜落点时间
++ 前后镜衔接余量
+```
+
+模型支持的单次最大时长不是目标时长。台词无法完整说完时，优先延长或按完整戏剧节拍拆镜，禁止靠加速到听不清来硬塞。
+
+### 5.3 分镜字段
+
+单镜至少应明确：
+
+- 当前镜头的戏剧目标。
+- 角色站位、视线、入画和离画方向。
+- 按时间段划分的动作与表演。
+- 逐句台词、说话者、语气和开始时机。
+- 景别、机位、镜头运动和最终落点。
+- 环境声、对白、系统声、SFX 和 BGM 节奏。
+- 与上一镜的接入动作、声音桥或视觉桥。
+- 与下一镜的尾帧、视线、运动方向或声音预埋。
+- 禁止项和资产版本。
+
+## 6. 资产一致性
+
+### 6.1 角色
+
+- 先确定全局角色和当前项目外观版本。
+- 服装、发型、年龄、伤势和持有物由 `CharacterState` 固定。
+- 三视图用于角色母版，不代表每个镜头都应直接上传整张三视图。
+- 同场多人应明确各自参考图和身份，避免参考关系错配。
+
+### 6.2 场景
+
+- 场景主资产应至少覆盖关键方向、空间结构和标志物。
+- 同一连续场景不得仅靠文字重复描述来维持一致性。
+- 对联、牌匾、二维码、屏幕等精确文字内容应由后期层处理，模型画面保留合理空间和时长。
+
+### 6.3 道具
+
+- 剧情证据、武器、手机、银铃、文件等关键道具应有主资产或明确外观约束。
+- 道具在人物手中时要描述持握手、方向、前后位置和动作路径。
+
+## 7. 图像输入模式
+
+| 模式 | 适用情况 | 主要风险 |
+| --- | --- | --- |
+| 纯文本 | 无既有资产、探索性镜头 | 角色和空间漂移最大 |
+| 单首帧 | 同一空间内连续表演、动作可自由发展 | 尾点不可控 |
+| 首尾帧 | 明确起止构图、动作落点或转场接力 | 首尾差异过大时中间形变 |
+| 多图参考 | 同时约束人物、场景、道具，或测试模型参考能力 | 参考权重错配、剧情控制有限 |
+
+选择原则：使用能满足镜头目标的最少参考图。首尾帧需要处于同一时空、同一服装、可连续运动，不能拿两个独立海报硬桥接。
+
+## 8. 视频生成
+
+当前支持：
+
+- 单镜和批量生成。
+- 单首帧、首尾帧和多图参考。
+- 多候选与人工选择。
+- Kling 原生音频、Seedance 等真实视频 Provider。
+- Provider preflight、成本估算和异步轮询。
+
+请求记录应包含：
+
+- 原始业务 Prompt 和最终提交 Prompt。
+- 参考图顺序、资产 ID、用途和临时 URL。
+- 请求时长、比例、分辨率、模型和 Provider 参数。
+- 是否要求原生音频、实际返回音轨。
+- Provider 任务 ID、状态、耗时、成本和失败原因。
+
+特殊对照测试可以按用户要求“原样 Prompt + 指定图片”提交，此时不得自动注入公共润色词；系统应明确标记为 bypass/实验请求，避免污染正式模板结论。
+
+### 8.1 当前统一画幅
+
+- 新生产任务统一使用16:9横屏。
+- 1080P视频固定1920×1080，关键帧固定2560×1440，原生4K固定3840×2160。
+- 新的 Production Contract、Generation Plan、关键帧 Prompt、视频请求和 FFmpeg 合成都读取同一横屏常量。
+- 历史素材与已冻结计划不原地改写；旧镜头重新生成时创建新的16:9计划修订。
+
+### 8.2 Kling 视频角色元素
+
+视频角色元素负责回答“角色是谁、长什么样、使用什么声线”；分镜 Prompt 只负责场景、动作、表演、台词与运镜。
+
+生产步骤：
+
+1. 从已确认角色锚点生成3-8秒身份源视频，默认8秒、1080P、16:9。
+2. 人物正面起始，依次左转约30度、回正、右转约30度并回正；背景与灯光保持中性。
+3. 在 Kling 元素库人工创建视频角色元素；当前不宣称存在已验证的公开创建 API。
+4. 将真实 `element_id`、元素名称、源视频、声线和质检结果导入 `CharacterProviderBinding`。
+5. 质检分达到90后才能审批为正式主元素。
+6. Generation Plan 冻结角色到元素的映射；正式 Omni 请求提交真实 `element_list`。
+7. 新 S+ 镜头缺少任何出场角色的已审批元素时，在付费调用前阻断。
+
+Prompt 内的 `<<<element_n>>>` 与 API `element_list[n]` 必须一一对应。网页端 `@名称` 只用于手工操作，不能冒充已绑定 API 元素。
+
+## 9. 声音设计
+
+声音层包括：
+
+- 角色对白和心理旁白。
+- 机械系统音或非人物提示音。
+- 环境声、拟音和冲击音效。
+- BGM、高潮音乐和转场声音桥。
+- 模型原生音轨、后期 TTS 与补充音频。
+
+系统音必须在 Prompt 中与角色声线分离，说明音色、节奏、响度和播放窗口；仍不稳定时由后期独立音轨替换。字幕仅展示实际说出的台词，不包含角色名、动作说明或生成残留符号。
+
+## 10. 质量控制
+
+自动 QC 至少覆盖：
+
+- 角色身份、脸型、年龄和服装一致性。
+- 场景空间、道具和文字占位是否正确。
+- 动作是否按方向完成，是否出现穿模或多余人物。
+- 台词是否完整、中文是否清楚、声线是否串角色。
+- 嘴型、说话时机和字幕窗口是否协调。
+- 运镜是否服务表演，有无硬切、漂移或无意义运动。
+- 首尾是否能接前后镜。
+- 画质、闪烁、畸变、音量和可播放性。
+
+自动评分用于筛选和重试，不直接等于发布通过。关键镜头和最终成片必须允许人工确认。
+
+## 11. 合成与后期
+
+当前 FFmpeg 链路支持：
+
+- 分辨率、帧率、像素格式和音轨归一。
+- 硬切、淡入淡出、模糊、声音桥等转场。
+- 原生音轨、附加音频、BGM、SFX 和环境音混合。
+- ASS/字幕烧录。
+- UI 提示框、进度条和稳定中文信息层。
+- 无源音轨时的兜底声音。
+
+正式合并流程应输出完整成片，而非只做裸拼接。每次合成需保存镜头顺序、裁剪范围、转场、字幕、UI 和混音参数，以便可重复生成。
+
+## 12. 当前风险
+
+1. 动态分镜、声音和后期策略变化后，部分测试仍使用旧期望。
+2. 真人关键帧和真人合并任务并未全部通过 Worker 执行。
+3. Scene Composer 和原创音乐默认关闭，项目间配置容易产生理解差异。
+4. LipSync 只有抽象，当前真实 Provider 未启用。
+5. Provider 临时参考图公网可达性尚未形成统一 preflight。
+6. 自动字幕、UI 时间点与台词结束边界仍需更多成片回归样本。
+
+## 13. 不可破坏的规则
+
+1. 不删改用户已确认的总剧本事实，分镜只能做可追踪改编。
+2. 不在用户要求原样测试时偷偷注入模板。
+3. 不用未确认的角色或服装锚点替换主资产。
+4. 不把模型生成的乱码文字当作正式 UI。
+5. 不在对白未结束时切镜。
+6. 不把多个候选误当成同一镜重复提交。
+7. 不在没有参数快照的情况下宣称某模型效果优劣。
+
+## 14. 下一阶段
+
+- 建立剧本/分镜逐镜 98+ 审核量表的机器可读版本。
+- 补齐视频合成、字幕和真人任务的 Worker 执行器。
+- 为每次视频调用展示实际路由、参考图和回退链。
+- 增加完整成片 E2E：镜头生成 -> 选择 -> 字幕/UI -> BGM/SFX -> 合并。
+- 将高质量人工评审结果沉淀为可版本化 Prompt 经验，而不是无边界自动追加。