# AI 原生 RPG 模板开场动画 PRD

更新时间：`2026-04-25`

## 0. 文档目的

这份 PRD 用于把 RPG 模板中的“开场动画”从一张静态封面或一段普通介绍，升级成可由 AI 资产链稳定生成、可保存、可预览、可发布、可在开局自动播放的 `15` 秒视频。

本次开场动画采用当前 AI 视频生成更稳定的工程化工作流：

```text
RPG 世界草稿 / 模板锚点
-> 生成 4 张首尾关键帧图
-> 用关键帧 1-2 生成第 1 段 5 秒视频
-> 用关键帧 2-3 生成第 2 段 5 秒视频
-> 用关键帧 3-4 生成第 3 段 5 秒视频
-> 统一规格转码并拼接为 15 秒开场动画
-> 挂回 RPG 模板与作品资产
-> 玩家首次进入 RPG 运行态时播放，结束后进入开局场景
```

这份文档只做产品、数据、生成链路和落地边界设计，不直接改工程代码。

---

## 1. 在线工作流调研结论

### 1.1 为什么不用一次性生成 15 秒长视频

当前主流 AI 视频模型已经能直接生成较长视频，但对游戏开场来说，一次性生成 `15` 秒仍有 4 个风险：

1. 角色、服装、标志物和世界风格容易在中段漂移。
2. 镜头容易自发切换，导致关键叙事信息没有按顺序出现。
3. 第 15 秒无法稳定落到玩家即将进入的开局场景。
4. 失败后重跑成本高，不能只修某一幕。

因此本项目第一版采用“关键帧定锚 + 分段生成 + 后期拼接”的方式。每段只表达一个镜头目标，失败时只重跑对应片段。

### 1.2 可参考的行业能力

调研到的主流能力如下：

| 来源 | 对本项目有用的结论 |
| --- | --- |
| Google Vertex AI Veo | 官方支持上传起始帧与结束帧生成视频，控制视频首尾画面。文档更新时间为 `2026-04-24`。参考：https://docs.cloud.google.com/vertex-ai/generative-ai/docs/video/generate-videos-from-first-and-last-frames |
| Runway Gen-4 | 官方建议 `5` 或 `10` 秒片段，把每次生成视作单一场景，并强调输入图决定起始视觉、提示词重点写运动。参考：https://help.runwayml.com/hc/en-us/articles/39789879462419-Gen-4-Video-Prompting-Guide |
| Kling AI | 首尾帧功能用于上传两张图生成过渡视频，并提示两张图主题和构图越接近，`5` 秒内过渡越稳定；差异太大会触发镜头切换。参考：https://kling.ai/quickstart/ai-video-start-end-frames |
| Luma Ray | 强调关键帧、角色参考和跨镜头连续性，可用于理解“长镜头拆段 + 关键帧控制”的制作方向。参考：https://lumalabs.ai/ray |

### 1.3 对本项目的工作流选择

本项目优先采用如下策略：

1. 用文本模型先从 RPG 模板锚点生成 `openingAnimationBlueprint`。
2. 用图片模型一次性生成 `4` 张统一风格关键帧。
3. 用首尾帧视频模型生成 `3` 个 `5` 秒片段。
4. 用后端 `ffmpeg` 做统一转码、无缝拼接和封面帧提取。
5. 用 OSS + `asset_object` + `asset_entity_binding` 保存最终资产。
6. 前端只展示生成状态、预览视频和开局播放，不承担生成逻辑和视频拼接。

第一版模型供应商不写死在产品逻辑中。国内可用主链优先复用当前 Rust 资产生成链中已有的 Ark / DashScope 配置；如后续接入 Veo、Runway、Kling、Luma，只作为 `provider` 扩展，不改变 RPG 模板数据结构。

---

## 2. 一句话定义

RPG 模板开场动画是一段由 `4` 张叙事关键帧和 `3` 个 `5` 秒 AI 视频片段组成的 `15` 秒多场景冒险开场演出，用于在玩家首次进入作品时快速建立世界观、核心冲突、目标牵引，并自然衔接到开局场景。

---

## 3. 本次目标

1. RPG 模板必须新增开场动画蓝图，作为世界草稿和发布作品的一部分。
2. 开场动画必须固定为 `4` 张关键帧、`3` 个视频片段、总时长 `15` 秒。
3. 四张关键帧必须分别表达：
   - 第一幕：世界观
   - 第二幕：核心冲突与核心角色出场
   - 第三幕：核心目标
   - 第四幕：衔接开局场景
4. 三段视频必须分别由相邻关键帧作为首尾帧生成：
   - 视频 1：关键帧 1 -> 关键帧 2
   - 视频 2：关键帧 2 -> 关键帧 3
   - 视频 3：关键帧 3 -> 关键帧 4
5. 最终成片必须能在 RPG 作品详情、创作结果页和运行时开局链路中复用。
6. 播放结束后必须进入 RPG 开局场景；如果玩家跳过，也进入同一个开局场景。
7. 开场动画生成失败不能阻断 RPG 发布和进入游戏，必须允许重新生成和无动画降级。
8. 所有生成、拼接、资产落库和状态流转都必须在 Rust 后端完成，禁止回到 `server-node`。

---

## 4. 明确不做

1. 不做一次性长视频生成主链。
2. 不在前端浏览器里拼接视频。
3. 不把功能说明、规则解释默认写进游戏 UI。
4. 不新增独立的“开场动画系统页面”；入口嵌入现有 RPG 创作结果页和模板配置区。
5. 不要求第一版生成配音、字幕、音乐和音效。
6. 不要求运行时根据玩家选择动态改写开场动画。
7. 不在 SpacetimeDB reducer 内调用外部视频模型、OSS 或文件系统。
8. 不兼容 `server-node` 旧生成链；旧实现只允许参考和迁移。

---

## 5. 叙事设计

## 5.1 四幕语义

| 幕 | 关键表达 | 画面职责 | 与 RPG 模板字段关系 |
| --- | --- | --- | --- |
| 第一幕：世界观 | 这个世界是什么样，正在承受什么长期压力 | 展示地貌、文明、时代气质、异常现象或历史伤痕 | 读取 `worldTheme`、`worldHook`、世界线程、主题母题、核心地标 |
| 第二幕：核心冲突与核心角色 | 谁被卷入冲突，冲突以什么形式爆发 | 让可扮演角色或核心 NPC 出场，并露出敌对力量、灾变、追捕、仪式或阵营压迫 | 读取主角、核心 NPC、阵营线、明线冲突 |
| 第三幕：核心目标 | 玩家为什么要开始冒险 | 展示目标物、禁地、远方地标、失落遗物、必须抵达的地点或必须拯救的人 | 读取主线目标、初始任务、关键物件、章节目标 |
| 第四幕：开局衔接 | 玩家即将在哪里醒来、抵达或被迫行动 | 画面落到第一个可操作场景，构图必须可作为游戏开局背景的前导镜头 | 读取开局场景、多幕第一幕背景、初始 NPC |

### 5.2 镜头节奏

| 视频片段 | 时长 | 首尾帧 | 镜头目标 |
| --- | --- | --- | --- |
| `opening_clip_01` | `5s` | 世界观帧 -> 冲突帧 | 从宏观世界推进到冲突爆发，镜头可采用推进、俯冲、穿越云层、掠过地标 |
| `opening_clip_02` | `5s` | 冲突帧 -> 目标帧 | 让核心角色带着冲突压力朝目标靠近，镜头可采用跟随、转身、拔剑、奔跑、法阵亮起 |
| `opening_clip_03` | `5s` | 目标帧 -> 开局场景帧 | 从目标牵引落回玩家即将进入的地点，镜头可采用推门、坠落、醒来、抵达、火光转场 |

### 5.3 提示词原则

生成视频片段时，提示词只描述本段运动，不重复大段设定说明。

每段提示词必须包含：

1. 镜头运动：例如缓慢推进、低空掠过、跟随角色、从远景落到近景。
2. 主体运动：例如角色转身、队伍穿过遗迹、光芒汇聚、风暴逼近。
3. 场景运动：例如云层翻涌、旗帜震动、烛火摇曳、尘土散开。
4. 连续性约束：首帧和尾帧中的角色、服装、标志物、色彩基调保持一致。
5. 游戏开场质感：多场景冒险 RPG、电影感、清晰主体、可读构图。

每段提示词禁止：

1. 同时要求多个互相冲突的镜头切换。
2. 用抽象词替代具体运动。
3. 使用“不出现 / 不要 / 禁止”作为主要约束；应改写成正向描述。
4. 要求模型在 `5` 秒内完成跨时代、跨空间、跨角色的大跳变。

---

## 6. 数据结构设计

## 6.1 RPG 模板新增字段

在 RPG 模板 / 世界 profile 中新增：

```ts
type RpgOpeningAnimationBlueprint = {
  id: string;
  enabled: boolean;
  status: 'not_started' | 'planning' | 'keyframes_generating' | 'clips_generating' | 'stitching' | 'ready' | 'failed';
  version: number;
  provider: string;
  aspectRatio: '16:9';
  totalDurationSec: 15;
  clipDurationSec: 5;
  keyframes: RpgOpeningAnimationKeyframe[];
  clips: RpgOpeningAnimationClip[];
  finalAsset?: RpgOpeningAnimationFinalAsset;
  fallbackPosterAssetId?: string;
  error?: RpgOpeningAnimationError;
  createdAt: string;
  updatedAt: string;
};
```

说明：

1. `enabled` 控制运行时是否播放。
2. `status` 由后端写入，前端只订阅和展示。
3. `provider` 表示真实使用的生成供应商，例如 `ark`、`dashscope`、`veo`、`runway`、`kling`、`luma`。
4. 第一版只支持 `16:9`，移动端播放时做安全裁切，不生成竖版副本。

## 6.2 关键帧对象

```ts
type RpgOpeningAnimationKeyframe = {
  id: string;
  order: 1 | 2 | 3 | 4;
  actRole: 'worldview' | 'conflict_and_role' | 'core_goal' | 'opening_scene_bridge';
  title: string;
  narrativeIntent: string;
  prompt: string;
  negativePrompt?: string;
  sourceAnchorIds: string[];
  assetObjectId?: string;
  previewUrl?: string;
  generationStatus: 'pending' | 'generating' | 'ready' | 'failed';
};
```

字段口径：

1. `title` 只用于后台调试和创作结果页内部管理，不直接作为游戏 UI 文案。
2. `narrativeIntent` 必须写清该帧承担的剧情功能。
3. `sourceAnchorIds` 记录本帧来自哪些模板锚点，便于后续重新生成时保持语义。

## 6.3 视频片段对象

```ts
type RpgOpeningAnimationClip = {
  id: string;
  order: 1 | 2 | 3;
  fromKeyframeId: string;
  toKeyframeId: string;
  durationSec: 5;
  prompt: string;
  providerTaskId?: string;
  assetObjectId?: string;
  previewUrl?: string;
  generationStatus: 'pending' | 'generating' | 'ready' | 'failed';
  technicalProfile: {
    width: number;
    height: number;
    fps: 24 | 25 | 30;
    codec: 'h264';
    container: 'mp4';
  };
};
```

## 6.4 最终资产对象

```ts
type RpgOpeningAnimationFinalAsset = {
  assetObjectId: string;
  playbackUrl: string;
  posterAssetObjectId: string;
  posterUrl: string;
  durationSec: 15;
  width: number;
  height: number;
  fps: 24 | 25 | 30;
  codec: 'h264';
  container: 'mp4';
  clips: string[];
  generatedAt: string;
};
```

---

## 7. 后端生成流程

## 7.1 总流程

```text
POST /api/custom-world/:profileId/opening-animation/generate
-> 校验作品归属与 RPG 类型
-> 读取世界 profile / 模板锚点 / 开局场景 / 角色视觉描述
-> 生成 openingAnimationBlueprint 文本计划
-> 生成 4 张关键帧图
-> 生成 3 个首尾帧视频片段
-> 下载远端视频
-> 统一转码为同规格 mp4
-> 拼接为 final opening mp4
-> 提取 poster
-> 上传 OSS
-> 确认 asset_object
-> 绑定到 RPG profile 的 opening-animation 槽位
-> 写回状态 ready
```

## 7.2 生成计划阶段

生成计划由 `api-server` 调用 `platform-llm` 完成，不进入 SpacetimeDB reducer。

输入上下文最少包含：

1. 世界一句话钩子。
2. 主题母题。
3. 明线冲突。
4. 暗线冲突的非剧透摘要。
5. 主角 / 核心 NPC 的视觉描述。
6. 第一个场景章节和开局场景。
7. 初始任务目标。
8. 已有场景图 / 角色图资产 URL。

输出必须是结构化 JSON，至少包含：

1. 四幕 `narrativeIntent`。
2. 四张关键帧图片 prompt。
3. 三段视频 motion prompt。
4. 风格统一约束。
5. 关键角色和标志物连续性约束。

## 7.3 关键帧生成阶段

关键帧生成必须优先复用已有图片生成链：

1. 统一走 Rust `api-server`。
2. 真实请求外部图片服务。
3. 结果落 OSS。
4. 确认 `asset_object`。
5. 绑定槽位：
   - `rpg-opening-keyframe-1`
   - `rpg-opening-keyframe-2`
   - `rpg-opening-keyframe-3`
   - `rpg-opening-keyframe-4`

关键帧生成要求：

1. 分辨率首版固定 `1280x720` 或供应商最接近的 `16:9` 输出。
2. 四张图必须共享同一 `styleSeed / visualBible`。
3. 核心角色在第二幕和第三幕必须保持同一服装、轮廓、武器或标志物。
4. 第四幕必须与开局场景背景语义一致，必要时使用开局场景图作为参考图。

## 7.4 视频片段生成阶段

每段视频生成请求必须显式传入：

1. 首帧图片。
2. 尾帧图片。
3. `5` 秒时长。
4. `16:9` 比例。
5. 本段 motion prompt。
6. 连续性约束。

视频片段槽位：

1. `rpg-opening-clip-1`
2. `rpg-opening-clip-2`
3. `rpg-opening-clip-3`

如果供应商不支持首尾帧：

1. 该供应商不能作为首选主链。
2. 只允许作为内部实验 provider。
3. 不允许把只支持单首帧的结果标记为正式通过。

## 7.5 拼接与转码

后端必须在拼接前统一三段视频规格：

1. 容器：`mp4`
2. 编码：`h264`
3. 像素格式：`yuv420p`
4. 分辨率：`1280x720`
5. 帧率：优先 `24fps`，若供应商固定 `25fps` 或 `30fps`，三段必须统一。
6. 音频：第一版默认无音轨；如供应商返回音频，拼接前静音或统一移除。

拼接后必须提取：

1. `poster`：第 `0.5` 秒或第一张关键帧。
2. `endPoster`：第 `14.5` 秒，用于确认衔接开局场景。
3. `duration`：必须在 `14.5s ~ 15.5s`。

---

## 8. SpacetimeDB 与 Rust 边界

### 8.1 SpacetimeDB 负责

1. 保存 RPG profile 中的开场动画蓝图状态。
2. 保存资产对象与业务槽位绑定关系。
3. 通过 reducer / procedure 更新可订阅状态。
4. 让前端通过订阅或查询拿到当前 `openingAnimationBlueprint`。

### 8.2 SpacetimeDB 不负责

1. 不调用外部模型。
2. 不下载视频。
3. 不执行 `ffmpeg`。
4. 不访问 OSS。
5. 不在 reducer 里生成随机非确定性内容。

### 8.3 Rust api-server 负责

1. 编排 LLM 计划、图片生成、视频生成、转码拼接。
2. 管理异步任务轮询。
3. 处理 OSS 上传与下载。
4. 调用 SpacetimeDB procedure 写入最终状态和资产绑定。
5. 对前端提供 HTTP / SSE 生成进度。

这条边界必须遵守 SpacetimeDB 规则：reducer 是确定性事务，不能把外部 I/O 放进去。

---

## 9. 前端嵌入设计

## 9.1 创作结果页

入口位置：

1. 复用 RPG 创作结果页现有资产区。
2. 增加一个“开场动画”资产槽。
3. 点击槽位打开独立面板，不在当前卡片下方展开。

面板能力：

1. 预览最终 `15` 秒视频。
2. 展示四张关键帧缩略图。
3. 展示三段视频状态。
4. 支持重新生成全部。
5. 支持只重生某张关键帧，并自动标记相关视频片段需要重生。
6. 支持只重生某段视频。
7. 支持禁用开场动画。

UI 约束：

1. 不展示大段功能说明。
2. 状态用短标签和进度表达。
3. 移动端优先：关键帧横向滑动，视频预览保持 `16:9`。
4. 按钮使用图标 + 短文本，避免规则说明型文案。

## 9.2 RPG 模板发布

发布时校验：

1. 如果 `enabled = true`，则 `finalAsset` 必须存在且可读取。
2. 如果生成失败，发布不阻断，但自动写入 `enabled = false` 并保留错误状态。
3. 发布后的作品详情页可展示开场动画 poster，但不强制自动播放。

## 9.3 运行时开局播放

播放时机：

```text
玩家点击开始游戏 / 继续进入新开局
-> 完成角色选择
-> 初始化 RPG session
-> 若 openingAnimation.enabled 且 finalAsset 可用
-> 播放开场动画
-> 播放结束或跳过
-> 进入开局场景
```

规则：

1. 同一个存档只自动播放一次。
2. 玩家跳过后必须记录 `openingAnimationPlayed = true`。
3. 继续游戏不自动播放，除非玩家从作品详情页手动预览。
4. 视频加载失败时直接进入开局场景。
5. 移动端播放必须提供明显的跳过按钮，但不写说明段落。

---

## 10. 状态机

```text
not_started
-> planning
-> keyframes_generating
-> clips_generating
-> stitching
-> ready

任意生成阶段
-> failed
-> planning / keyframes_generating / clips_generating
```

关键规则：

1. 重生关键帧 1，会使视频 1 失效。
2. 重生关键帧 2，会使视频 1 和视频 2 失效。
3. 重生关键帧 3，会使视频 2 和视频 3 失效。
4. 重生关键帧 4，会使视频 3 失效。
5. 重生某段视频后必须重新拼接最终成片。
6. 最终成片 ready 后，旧版本资产不能立即删除，至少保留最近 `2` 个版本用于回滚。

---

## 11. API 设计

### 11.1 生成开场动画

```http
POST /api/custom-world/:profileId/opening-animation/generate
```

请求：

```json
{
  "mode": "full",
  "provider": "auto",
  "forceRegenerate": false
}
```

返回：

```json
{
  "jobId": "opening_anim_job_xxx",
  "status": "planning"
}
```

### 11.2 重生关键帧

```http
POST /api/custom-world/:profileId/opening-animation/keyframes/:keyframeId/regenerate
```

### 11.3 重生视频片段

```http
POST /api/custom-world/:profileId/opening-animation/clips/:clipId/regenerate
```

### 11.4 查询状态

```http
GET /api/custom-world/:profileId/opening-animation
```

返回当前 `RpgOpeningAnimationBlueprint`。

### 11.5 订阅进度

```http
GET /api/custom-world/:profileId/opening-animation/jobs/:jobId/stream
```

SSE 事件：

1. `planning`
2. `keyframe_ready`
3. `clip_ready`
4. `stitching`
5. `ready`
6. `error`

---

## 12. 工程落地阶段

### 阶段 1：文档与契约冻结

1. 确认 `RpgOpeningAnimationBlueprint` 字段。
2. 确认资产槽位命名。
3. 确认 provider 抽象。
4. 确认运行时只播放一次的状态字段。

验收：

1. 文档字段可直接编码。
2. 前后端对同一 JSON contract 无歧义。

### 阶段 2：后端计划与关键帧生成

1. `api-server` 生成四幕计划。
2. 接入图片生成。
3. 关键帧落 OSS 和 `asset_object`。
4. profile 写回关键帧状态。

验收：

1. 能在结果页看到四张真实生成图。
2. 第四张图语义上能衔接开局场景。

### 阶段 3：首尾帧视频生成

1. 三段视频真实请求外部模型。
2. 每段固定 `5` 秒。
3. 每段落 OSS。
4. 支持失败重试与单段重生。

验收：

1. 三段视频都不是占位视频。
2. 每段首尾画面与对应关键帧一致。

### 阶段 4：拼接发布与运行时播放

1. 后端统一转码。
2. 拼接成 `15` 秒成片。
3. 提取 poster。
4. RPG 运行态首次开局播放。
5. 播放结束或跳过进入开局场景。

验收：

1. 最终视频时长在 `14.5s ~ 15.5s`。
2. 播放后进入的场景与第四幕一致。
3. 同一存档不会重复自动播放。

---

## 13. 质量验收标准

### 13.1 叙事验收

1. 第一幕不用字幕也能看出世界类型和主要气质。
2. 第二幕能看出冲突正在发生，并且核心角色可被识别。
3. 第三幕能看出玩家即将追求的目标。
4. 第四幕能自然落到开局场景，不像另一个无关地点。
5. 四幕之间存在视觉连续性，不是四张无关插图。

### 13.2 视频验收

1. 三段均为真实外部生成结果。
2. 每段约 `5` 秒。
3. 拼接后无明显黑帧、重复帧、尺寸跳变。
4. 主体没有严重形变、闪烁、消失。
5. 核心角色在第二、第三幕保持可识别一致。
6. 移动端播放不裁掉核心主体。

### 13.3 工程验收

1. 所有生成任务由 Rust `api-server` 编排。
2. 资产落 OSS，并有 `asset_object` 记录。
3. 业务实体通过槽位绑定读取资产。
4. SpacetimeDB reducer 不包含外部 I/O。
5. 前端刷新后仍能恢复生成状态。
6. 生成失败有可重试状态，不写入假成功。

---

## 14. 风险与降级

| 风险 | 降级策略 |
| --- | --- |
| 关键帧风格不一致 | 用同一 visual bible、参考图和角色视觉描述重生四张图 |
| 首尾帧差异过大导致视频硬切 | 调整相邻关键帧构图，使主体、视角、色彩更接近 |
| 第二幕角色漂移 | 使用角色主形象作为参考图，并在第二、第三幕共享角色约束 |
| 视频生成超时 | 单段失败只重试该段，不重跑全流程 |
| 拼接后有黑帧 | 后端转码时强制统一 fps、分辨率、像素格式 |
| 移动端加载慢 | poster 先显示，视频懒加载；失败直接进开局场景 |
| 供应商审核失败 | 后端生成更保守的原创 prompt 重试一次，仍失败则标记 failed |

---

## 15. 后续扩展

1. 增加背景音乐和环境音，但不改变四帧三段主链。
2. 为移动端生成 `9:16` 竖版裁切版本。
3. 支持百梦主手动上传某张关键帧，再生成相邻视频。
4. 支持发布后版本化替换开场动画。
5. 支持用第四幕直接生成开局场景动态背景。
6. 支持把开场动画拆出的关键帧回流为作品详情页轮播素材。