# AI 生成角色形象与角色动画功能技术方案（2026-04-04）

## 1. 文档目的

为当前项目设计一套“AI 生成角色形象 + AI 生成角色动画”的完整功能方案，目标效果参考 PixelMotion 一类产品的核心体验，但接入方式必须适合当前项目现有的 2D 侧视角色素材体系。

- 用户先输入角色设定词与角色参考图，生成主角色形象
- 也支持用户直接上传现成角色素材
- 角色形象确认后，再基于该形象生成动作动画
- 最终产物不是单纯视频，而是**可回收为项目资产的角色图 / 序列帧 / Sprite Sheet / 元数据**

本方案强调两点：

- **必须能在国内稳定使用**
- **必须能接到本项目现有的角色动画、编辑器、本地 API 和运行时结构**

资料调研时间截至：`2026-04-04`

---

## 2. 先说结论

### 推荐路线

第一版推荐采用**“角色形象工坊 + 动作工坊”**的两段式方案：

1. 先用国内可直接接入的图像模型生成或规范化角色主形象
2. 用户确认主形象后，再基于主形象生成动作视频
3. 最后由项目内本地服务把视频转成序列帧、像素风结果和运行时配置

### 首选模型与平台

首选阿里云百炼一体化方案：

- 角色形象生成：`wan2.7-image-pro` / `wan2.7-image`
- 角色动作生成：`wan2.2-animate-move`
- 高质量换角动作：`wan2.2-animate-mix`
- 说话 / 对口型扩展：`wan2.2-s2v`

原因：

- 官方明确支持**中国内地部署**
- `wan2.2-animate-move` 就是“图像 + 参考视频 -> 输出动作视频”
- `wan2.2-animate-mix` 支持“视频中的人替换成图像中的人”
- 异步任务、轮询、计费、输出格式都比较清晰
- 比旧版 `AnimateAnyone` 路线更适合作为新项目主线

### 第一版功能边界

第一版必须支持：

- 文生角色图
- 图生角色图
- 用户直接上传角色素材
- 角色图预览与重新生成
- 角色动画预览与重新生成
- 与当前项目可扮演角色 / 角色型 NPC 的动作槽位匹配

第一版暂不强求：

- 技能动作一次性全部自动补齐
- 实时运行时生成
- 完全免人工筛选

### 不建议的第一版做法

- 不建议第一版直接做“纯本地端到端视频生成主链”
- 不建议把 AI 生成结果直接塞进运行时即时播放
- 不建议追求“模型直接吐出完美像素序列帧”

原因：

- 第一版最难的不是“生成视频”，而是**角色一致性、动作可控性、像素风稳定性、可复用资产化**
- 当前项目更适合把 AI 放在**资产生产链**里，而不是放在每次运行时战斗里实时生成

---

## 3. 目标效果定义

这里把“类似 PixelMotion 的效果”明确成以下两段式能力。

### 3.1 阶段 A：角色主形象生成

- 用户输入角色形象设定
- 用户可上传 1 到多张角色参考图
- 也支持直接上传已有角色图作为主素材
- 系统输出与当前游戏角色视角相近的主形象图
- 用户可预览、筛选、重新生成，直到确认主形象

### 3.2 阶段 B：角色动作生成

- 基于已确认的主形象生成短动作动画
- 支持上传参考动作视频，或直接选动作模板
- 技能动作不是第一版强制项
- 基础动作槽位不能为空
- 用户可预览、筛选、重新生成，再发布为正式资产

### 3.3 项目内真实产物

- 角色主形象图 `png`
- `mp4/webm` 动作预览视频
- 解帧后的 `png` 序列
- 合并后的 Sprite Sheet
- 动画元数据 `json`
- 角色形象与动画挂接配置

### 3.4 不是第一版目标的内容

- 实时 3D 骨骼动画
- 无人工干预的高质量全自动像素逐帧美术
- 所有技能动作一次性自动补完
- 所有动作都由玩家随手输入文本即时生成

---

## 4. 约束与设计原则

结合当前仓库文档，方案需要遵守下面的原则。

### 4.1 AI 负责内容生成，不负责规则决定

动画生成只负责：

- 动作表现
- 角色演出
- 视觉资产生产

不负责：

- 战斗数值
- 命中逻辑
- 好感 / 背包 / 掉落 / 招募等规则

这与项目现有经验完全一致：**AI 做表达层，本地规则做状态层。**

### 4.2 先做数据建模，再做 UI

功能落地顺序建议严格遵守：

1. 定义角色形象与动画资产模型
2. 定义任务状态机与本地 API
3. 打通生成与后处理管线
4. 接编辑器 UI
5. 最后挂到正式运行时

### 4.3 生成结果必须资产化

生成结果不能只停留在“看一下视频”。

必须能沉淀为：

- 角色主形象资源
- 角色动画资源
- 编辑器可复用配置
- 运行时可直接加载的帧集

### 4.4 像素风不直接交给视频模型终态完成

第一版推荐：

- 先生成相对稳定的高分辨率动作视频
- 再做像素化、色板约束、抖动清理、裁切与对齐

而不是直接要求模型“一步到位产出稳定像素逐帧动画”。

原因很简单：

- 直接出像素视频，最容易出现闪烁、轮廓漂移、武器形变、手脚抖动
- 先生成稳定动作，再统一像素化，更适合游戏资产生产

---

## 5. 国内可用技术路线调研结论

## 5.1 主线推荐：阿里云百炼 Wan 系列

### 角色主形象生成

推荐使用：

- `wan2.7-image-pro`
- `wan2.7-image`

原因：

- 同一平台可同时覆盖图像生成与动作生成
- 适合做“文本设定 + 参考图 -> 角色主形象”
- 适合做“已有角色图 -> 风格统一 / 视角纠偏 / 细节重绘”

第一版建议：

- 主图生成优先用 `wan2.7-image-pro`
- 批量快速试错可降到 `wan2.7-image`
- 用户直接上传素材时，不强制重生，只先走规范化与裁切

### 角色动作生成

#### `wan2.2-animate-move`

适合：

- 输入角色主形象 + 参考动作视频
- 生成基础动作片段
- 构建 `idle / run / attack / hurt / die` 等核心动作库

根据阿里云官方文档：

- 支持中国内地部署
- 输出规格为 `720P`
- 时长范围 `2s < 时长 < 30s`
- 标准模式 `15fps`
- 专业模式 `25fps`

#### `wan2.2-animate-mix`

适合：

- 先选定高质量动作模板视频
- 再把模板里的角色替换成当前主形象角色
- 批量生产多个角色的同类动作

#### `wan2.2-s2v`

适合第二阶段能力：

- 角色对话口型
- NPC 说话演出
- 招募 / 剧情特写

### 为什么把阿里云放在第一选择

- 图像与视频链路都能放在同一国内平台
- 接口能力覆盖“主形象生成 -> 动作生成 -> 说话演出”
- 异步任务、计费、结果下载和国内可用性都比较清晰
- 官方已明确给出 `animate-move / animate-mix` 这类更贴近生产的动作驱动方案

### 成本信息

截至调研时间，阿里云官方价格页显示，中国内地部署下：

- `wan2.2-animate-move` 标准模式约 `0.4 元/秒`
- `wan2.2-animate-move` 专业模式约 `0.6 元/秒`

这意味着：

- 一个 `4 秒` 动作片段大致是 `1.6 元` 到 `2.4 元`
- 如果第一版每个角色先做 `6` 个基础动作、每个动作平均 `4 秒`
- 单角色生成成本大致在 `9.6 元` 到 `14.4 元`

## 5.2 增强路线：火山方舟 Seedance 2.0

火山官方资料显示，`Seedance 2.0` 已支持多模态参考生视频，并支持：

- 最多 `9` 张图片
- `3` 段视频
- `3` 段音频
- 最长 `15` 秒生成

这条线更适合：

- 多参考图保持角色一致性
- 更复杂镜头或更长动作段
- 后续做剧情演出、过场或多镜头特写
- 在阿里云主链之外补一条高质量增强通道

但对“第一版角色动作资产生产”来说，它更适合作为增强通道，不建议先做成唯一主依赖。

实现更新（`2026-04-19`）：

- 当前仓库的 `image-to-video` 角色动作生成入口已切到火山方舟 `Seedance`
- 采用双参考图首尾帧方案：图片 1 约束首帧，图片 2 约束尾帧
- 当前请求体中的两张参考图角色分别固定为 `first_frame / last_frame`
- 当前固定参数为 `1:1`、`480p`、`4 秒`、单次 `1` 个视频
- 当前固定动作入口收敛为 `idle / run / attack / die`，不再内置固定 `hurt`
- 提示词里传给视频模型的动作名统一使用英文动作名

实现更新（`2026-04-20`）：

- `run / attack` 是当前固定动作入口里的基础必生成动作
- `idle / die` 改为可选增强动作，不再作为资产完成度硬门槛
- `idle` 缺失时运行时默认使用主图静止
- `die` 缺失时运行时默认播放一段基于主图的向后倒地过渡动画，并通过轻微过冲回落让动作更自然，最终停在翻转倒地姿态
- 技能动作不走固定按钮，但对当前角色 `skills` 中的每个技能都属于必生成动作

## 5.3 补充路线：腾讯云相关能力

腾讯云相关接口里，`提交图片跳舞任务` 提供了：

- 图片驱动模板动作
- `EnableSegment`
- `EnableBodyJoins`

优点：

- 内置一定的分割与表演模板能力
- 适合快速产出宣传向动效

限制：

- 更偏模板化表演
- 不够贴近当前项目“侧视战斗角色动作资产”的主需求

因此腾讯路线更适合作为：

- 活动页宣传素材
- 社媒传播素材
- 节日彩蛋动作

## 5.4 自托管 / 私有化预研路线

如果后续希望减少云成本、加强可控性或做私有化部署，可以并行预研以下开源链路。

### 角色一致性

`InstantCharacter`

- 腾讯混元官方开源
- 单图角色保持能力强
- 官方说明支持 tuning-free 的角色保持生成
- 2025-05-14 的更新中提到可在 `22GB VRAM` 以下配合 offload 运行

适合用途：

- 给角色生成多参考图
- 统一角色造型
- 补充云模型前的参考素材标准化

### 姿态驱动视频

`MusePose`

- 官方定义为“Pose-Driven Image-to-Video Framework”
- 很适合做“角色图 + 姿态序列 -> 视频”

但要特别注意：

- 代码是 `MIT`
- 官方训练模型说明为**仅限非商业研究用途**

所以它适合：

- 原型验证
- 内部实验
- 技术可行性预研

不适合直接作为正式商业主链。

### 姿态提取

`DWPose` / `MMPose (RTMPose / RTMW)`

优点：

- 国内可获取
- 社区成熟
- 可做全身关键点提取
- `DWPose` 官方仓库提到已支持 character animation 场景
- `MMPose` 官方项目持续维护 `RTMPose`、`RTMW`

适合用途：

- 动作模板解析
- 参考视频骨架抽取
- 后处理阶段的动作对齐与评分

### 本地视频生成

`HunyuanVideo-1.5`

优点：

- 腾讯官方开源
- 支持 text-to-video 和 image-to-video
- 官方说明最小显存要求可到 `14GB`

适合用途：

- 私有化实验
- 国内 GPU 云机自部署
- 降低部分长尾生成成本

结论：

- **正式产品主链**：优先用国内云 API
- **预研和备份链**：并行建设开源本地链路

---

## 6. 推荐的产品形态

## 6.1 功能名称

建议在编辑器中新增：

- `角色资产工坊`

### 功能入口

- 角色预设编辑器
- NPC 视觉编辑器
- 后续可在角色详情页增加“生成动画”快捷入口

## 6.2 用户流程

### 阶段 A：角色主形象

1. 选择角色或新建角色
2. 输入角色形象设定文本
3. 上传角色参考图，或直接上传已有角色素材
4. 系统给出尺寸 / 裁剪 / 构图校验
5. 提交角色图生成或规范化任务
6. 预览结果
7. 支持“重新生成”“保留当前版本”“设为主形象”

### 阶段 B：角色动作

1. 基于已确认的主形象进入动作工坊
2. 选择要生成的动作槽位
3. 上传参考动作视频，或直接选择动作模板
4. 提交动作生成任务
5. 预览结果
6. 支持“重新生成”“替换此动作”“发布为正式资产”

### 必须满足的体验要求

- 角色图阶段必须可预览、可重新生成
- 动画阶段必须可预览、可重新生成
- 用户可以只上传素材，不一定强制走文生图
- 用户一旦确认主形象，后续动作生成默认锁定该主形象，不再漂移到其他角色风格

## 6.3 动作生成方式

建议支持三种模式：

### A. 模板动作

用户直接选：

- `idle`
- `run`
- `attack`
- `die`

系统自动选择对应参考视频模板。

其中：

- `run / attack` 属于固定必生成动作
- `idle / die` 属于固定可选动作，未生成时走默认兜底

`jump`、`hurt` 这类扩展动作不再作为当前编辑器固定按钮，改为后续扩展动作槽位或手动补齐。

### B. 视频驱动

用户上传参考动作视频，系统抽姿态后再生成角色动作。

### C. 说话 / 对口型

用户上传音频，系统调用 `wan2.2-s2v` 生成说话特写。

### D. 首尾帧约束再生成

对于循环动作或需要收招回正的动作，增加二次再生成模式：

- `idle`、`run` 这类循环动作，尽量让首尾帧接近
- `attack`、`cast` 这类动作，尽量让末帧回到可接下一个动作的准备姿态

这部分策略参考了你提供的视频方向，即：

- 指定角色一致性
- 首尾帧控制
- 动作视频生成分段处理

---

## 7. 总体技术架构

```mermaid
flowchart LR
    A["编辑器 UI<br/>角色资产工坊"] --> B["本地 API / 任务调度层"]
    B --> C["图像模型适配器<br/>文生图 / 图生图"]
    B --> D["视频模型适配器<br/>动作生成 / 说话生成"]
    C --> E["主形象规范化 Worker<br/>裁切/清底/校验"]
    D --> F["动作后处理 Worker<br/>解帧/稳帧/像素化/打包"]
    E --> G["主形象资产仓库<br/>public/generated-characters"]
    F --> H["动画资产仓库<br/>public/generated-animations"]
    G --> I["角色资产元数据<br/>src/data 或 overrides"]
    H --> I
    I --> J["运行时 CharacterAnimator / GameCanvas"]
```

### 关键原则

- 云模型只负责生成原始视频
- 项目自己掌握后处理和资产组织
- 运行时永远读取项目内标准化资产，不直接依赖第三方视频输出

---

## 8. 推荐生产管线

## 8.1 阶段 A：角色主形象生成

输入包括：

- 角色形象设定文本
- 角色参考图 `1~4` 张
- 或直接上传现成角色素材
- 可选风格限定词
- 可选武器 / 装束 / 发型约束

输出包括：

- `master.png` 主形象图
- `preview/*.png` 候选预览图
- 主形象元数据

### 主形象生成策略

- 文生图时，优先生成与当前项目角色素材视角一致的单人全身图
- 有参考图时，优先做“角色指定 + 风格收敛 + 视角纠偏”
- 用户直接上传素材时，先做校验、裁切、背景清理和尺寸标准化
- 编辑器未上传参考图时，主形象阶段默认附加一张由项目内可扮演角色 idle 帧拼成的风格参考板，用来锁定像素动作角色的轮廓语言、右朝向、体型比例与配色组织，避免模型只放大 Q 版比例却丢掉像素感
- 风格约束优先级里，“像素动作角色感”高于“Q 版比例提示”；比例只允许轻度偏大头，不允许退化成普通软萌插画或儿童绘本风

### 角色视角要求

这里必须贴近当前项目现有角色素材体系，而不是做通用立绘。

建议统一为：

- 2D 侧视动作素材视角
- 单人全身
- 人物基本朝向右侧
- 脚底完整可见
- 武器和关键轮廓完整
- 不做强透视
- 背景尽量干净，方便后续裁切

### 为什么统一朝向右侧

当前项目运行时已经通过镜像处理角色左右朝向，因此主素材应优先只生成一套“面向右侧”的标准版本，避免左右两套素材风格不一致。

## 8.2 主形象输入尺寸与裁剪要求

### 推荐输入规格

- 推荐尺寸：`1024x1536`
- 可接受比例：`2:3` 或 `3:4`
- 最低建议：短边不低于 `768`
- 输出统一标准图：`1024x1536`

### 构图要求

- 角色主体占画面高度约 `70% ~ 85%`
- 头顶保留少量留白
- 脚底必须完整露出
- 画面中只保留单角色
- 不允许大面积前景遮挡

### 上传素材校验规则

- 分辨率过低时拒绝直接进入动画阶段
- 头脚被裁切时要求重新上传
- 背景过复杂时提示先走抠像或重生成
- 参考图角度差异过大时提示用户筛选

## 8.3 阶段 B：角色动作生成

动作生成输入包括：

- 已确认的 `master.png`
- 动作槽位
- 动作模板或参考动作视频
- 可选首尾帧约束
- 可选循环模式

### 主线路由

- 一般动作：`wan2.2-animate-move`
- 高质量换角动作：`wan2.2-animate-mix`
- 说话动作：`wan2.2-s2v`

### 任务策略

每次动作生成都走异步任务：

1. 创建任务
2. 记录 `jobId`
3. 轮询状态
4. 成功后立即下载临时链接结果
5. 进入本地后处理与资产化

## 8.4 动作生成技巧

结合你给出的参考方向，第一版建议把下面几条固化进生成策略。

### 技巧 1：先锁主形象，再做动作

动作生成只能使用已确认的主形象，不能每次动作都重新文生角色图。

### 技巧 2：动作模板优先于纯文本动作描述

对当前项目来说，稳定性优先于想象空间，因此：

- 基础动作优先走模板
- 个性化动作再开放视频驱动

### 技巧 3：首尾帧控制

对于循环动作：

- `idle`
- `run`

要求首尾姿态尽量接近，方便循环。

对于一次性动作：

- `attack`
- `cast`
- `hurt`
- `die`

要求末帧明确，且必要时生成一个可回收的“收招末帧”。

### 技巧 4：先出高分辨率动作，再转像素资产

不要直接把“像素逐帧稳定性”压给视频模型终态完成，而是：

1. 先出稳定动作视频
2. 再解帧、对齐、像素化、打包

## 8.5 视频后处理与像素化

生成视频拿到后，不直接上线，而是进入后处理流水线。

### 后处理步骤

1. `ffmpeg` 解帧
2. 主体检测与裁切
3. 背景清理 / 抠像
4. 稳帧与重心对齐
5. 去闪烁
6. 像素化降采样
7. 色板收敛
8. 生成 Sprite Sheet
9. 输出动画元数据

### 当前工程的抠像补充策略

针对角色动作视频抽帧后常见的“后段帧出现白底”“角色轮廓残留绿幕像素点”问题，当前工程内的背景清理不再只依赖单一绿幕阈值，而是统一改为以下顺序：

1. 先识别边界连通的可移除背景区域，同时覆盖纯绿色绿幕和高亮低色差白底。
2. 再向主体边缘的半透明软边做一轮有限扩张，把压缩后残留的白边、绿边纳入透明化处理。
3. 最后对贴近透明边缘的像素做去污，优先压掉绿色溢色，并把白边/绿边颜色拉回附近前景主体颜色，减少抽帧后的轮廓发白、发绿。

这样可以避免把角色内部的白色高光、白色装备整体误删，同时能更稳定地清理视频模型在末段帧里偶发的白背景和压缩噪点。

### 像素化策略

推荐做法：

1. 先在较高分辨率上清理主体
2. 再降采样到目标像素尺寸
3. 使用最近邻缩放
4. 锁定调色板
5. 对相邻帧做轻量时序去闪烁

### 第一版目标规格建议

- 中间产物：`512x512` 主体裁切或 `720P` 工作视频
- 运行时成品：`96x96`、`128x128` 或项目当前角色尺寸

## 8.6 资产打包

角色主形象输出：

- `master.png`
- `preview/*.png`
- `visual-manifest.json`

每个动作输出：

- `preview.mp4`
- `frames/*.png`
- `sheet.png`
- `manifest.json`

---

## 9. 推荐的资产数据结构

建议把“角色主形象”和“角色动画”分成两套数据结构。

```ts
export interface GeneratedCharacterVisualAsset {
  id: string;
  characterId: string;
  sourceProvider: 'aliyun-wan' | 'volc-seedance' | 'tencent' | 'local';
  sourceMode: 'text-to-image' | 'image-to-image' | 'upload';
  promptText?: string;
  referenceImagePaths: string[];
  masterImagePath: string;
  previewImagePaths: string[];
  width: number;
  height: number;
  facing: 'right';
  crop: {
    top: number;
    right: number;
    bottom: number;
    left: number;
  };
  locked: boolean;
}
```

```ts
export type BaseAnimationSlot =
  | 'idle'
  | 'acquire'
  | 'attack'
  | 'run'
  | 'jump'
  | 'double_jump'
  | 'jump_attack'
  | 'dash'
  | 'hurt'
  | 'die'
  | 'climb'
  | 'wall_slide';
```

```ts
export interface GeneratedCharacterAnimationAsset {
  id: string;
  characterId: string;
  visualAssetId: string;
  action:
    | BaseAnimationSlot
    | 'cast'
    | 'talk'
    | 'skill1'
    | 'skill2'
    | 'skill3'
    | 'skill4';
  sourceProvider: 'aliyun-wan' | 'volc-seedance' | 'tencent' | 'local';
  sourceMode: 'template' | 'video-drive' | 'audio-drive';
  frameCount: number;
  fps: number;
  loop: boolean;
  frameWidth: number;
  frameHeight: number;
  groundOffsetY: number;
  anchorX: number;
  anchorY: number;
  previewVideoPath: string;
  spriteSheetPath: string;
  framePaths: string[];
  palette?: string[];
  tags?: string[];
}
```

### 目录建议

```text
public/generated-characters/{characterId}/visual/
  master.png
  preview/
  visual-manifest.json

public/generated-animations/{characterId}/{action}/
  preview.mp4
  sheet.png
  manifest.json
  frames/
```

### 元数据建议写入位置

建议不要把所有生成结果直接写死进主预设文件。

更稳的做法：

- 主形象文件放 `public/generated-characters`
- 资产文件放 `public/generated-animations`
- 角色挂接关系放 `src/data/characterOverrides.json`
- 必要时再扩展一份 `src/data/characterAnimationOverrides.json`

这样更符合当前仓库的 override 体系。

---

## 10. 与当前项目代码结构的接入建议

## 10.1 运行时层

当前项目已经有：

- `src/components/CharacterAnimator.tsx`
- `src/types/characters.ts`

建议改造方式：

### `CharacterAnimator.tsx`

从当前“按文件夹拼单帧路径”的方式，扩成两层：

1. 现有手工动画资源
2. 新增 AI 生成动画资源

运行时优先级建议：

1. 角色 override 的生成动画
2. 角色原始 `animationMap`
3. 默认回退动画

另外建议固定规则：

- 生成主形象默认只保留“面向右”的标准动作资产
- 左向由运行时继续使用镜像处理
- 不单独维护左右两套 AI 素材

### `src/types/characters.ts`

建议给 `Character` 增加可选字段：

```ts
generatedVisualAssetId?: string;
generatedAnimationSetId?: string;
generatedAnimationOverrides?: Partial<Record<AnimationState, string>>;
```

## 10.2 编辑器层

建议新增组件：

- `src/components/CharacterAssetStudio.tsx`

核心职责：

- 角色形象生成 Tab
- 动作生成 Tab
- 主形象预览与锁定
- 动作预览与替换
- 提交生成
- 查看任务状态
- 一键发布到角色动画覆盖配置

### 为什么不要直接塞进现有 `NpcVisualEditor`

因为这会把：

- 外观编辑
- 动作生产
- 资产后处理
- 发布流程

全部混在一起，后期会迅速失控。

更合理的方式是：

- `NpcVisualEditor` 继续管静态形象
- `CharacterAssetStudio` 负责“主形象 + 动画”资产工坊

## 10.3 本地 API 层

自 `2026-04-19` 起，旧 `scripts/dev-server/localApiPlugins.ts` 已从仓库删除。  
当前角色视觉与动画相关 `/api/*` 能力应统一落到 `server-node/src/modules/assets/**` 与 `server-node/src/modules/ai/**`，不再复用旧 Vite 本地插件链路。

建议新增：

- `/api/character-visual/jobs`
- `/api/character-visual/jobs/:id`
- `/api/character-visual/publish`
- `/api/animation/jobs`
- `/api/animation/jobs/:id`
- `/api/animation/templates`
- `/api/animation/publish`

### 建议职责

`POST /api/animation/jobs`

- 创建生成任务
- 写入本地任务记录
- 触发第三方模型请求

`POST /api/character-visual/jobs`

- 创建角色主形象生成任务
- 保存设定词、参考图路径和上传素材信息
- 触发图像模型或规范化流程

`POST /api/character-visual/publish`

- 将选中的主形象设为角色标准主形象
- 写入 visual manifest
- 更新角色 override

`GET /api/animation/jobs/:id`

- 返回任务状态
- 返回进度、错误信息、结果地址

`GET /api/animation/templates`

- 返回动作模板列表

`POST /api/animation/publish`

- 触发后处理
- 生成 Sprite Sheet
- 写入 `manifest`
- 更新角色动画 override

---

## 11. 后端任务状态机设计

建议任务状态机如下：

```text
draft
-> queued
-> submitting
-> provider_pending
-> provider_running
-> downloading
-> post_processing
-> review_ready
-> published
-> failed
```

### 为什么需要 `review_ready`

因为这类资产生成不适合“生成完自动上线”。

必须给编辑器操作者一次人工确认机会，检查：

- 动作是否稳定
- 武器是否丢失
- 轮廓是否漂移
- 是否需要重生一版

---

## 12. 动作集要求与模板设计

这里必须与当前项目可扮演角色 / 角色型 NPC 的动作槽位对齐。

### 12.1 基础动作槽位必须非空

第一版要求以下动作能力按“必生成 / 可选兜底”拆开：

当前编辑器固定生成入口补充说明（`2026-04-19`）：

- 固定按钮只保留 `idle / run / attack / die`
- `hurt` 不再作为固定生成按钮
- 如果运行时仍需 `hurt` 资源，应通过后续扩展动作槽位或手动补齐

| 动作能力                        | 是否必填 | 建议来源                                                   |
| ------------------------------- | -------- | ---------------------------------------------------------- |
| `run`                           | 必填     | 模板生成                                                   |
| `attack`                        | 必填     | 模板生成                                                   |
| `skills[*].actionPreviewConfig` | 必填     | 技能编辑面板逐个生成                                       |
| `idle`                          | 可选     | 模板生成；缺失时默认主图静止                               |
| `die`                           | 可选     | 模板生成；缺失时默认主图向后倒地过渡动画，带轻微过冲回落，最终停在翻转倒地姿态 |

这里“必填”指的是：

- `run / attack` 必须能挂到一套可播放资产
- 角色当前每个技能都必须有可播放的 `actionPreviewConfig`
- `idle / die` 不再进入“缺失即阻塞发布”的判断
- 运行时表现仍然不能空白；`idle / die` 的缺口由默认兜底承接

### 12.2 技能动作改为“按角色已配技能强制”

第一版不再要求预留整套固定技能枚举，但要求：

- 当前角色 `skills` 数组里的每个技能都要补出 `actionPreviewConfig`
- 技能动作继续在技能编辑面板逐个生成，不并入固定四按钮

策略建议：

- 先补 `run / attack`
- 再逐个补当前角色已有技能动作
- `idle / die` 作为可选增强按需要补
- 投射物与特效优先继续复用当前项目已有素材与技能特效系统

### 12.3 第一阶段优先模板

先优先做这些高价值模板：

| 模板     | 推荐时长 | 是否循环 | 说明           |
| -------- | -------- | -------- | -------------- |
| `idle`   | 2s-4s    | 是       | 微动作、呼吸   |
| `run`    | 2s-3s    | 是       | 固定侧向       |
| `attack` | 2s-4s    | 否       | 近战基础攻击   |
| `jump`   | 1s-2s    | 否       | 起跳与空中姿态 |
| `die`    | 2s-4s    | 否       | 倒下或消散     |

### 12.4 不建议第一阶段就重投入的动作

- 大幅转身
- 超复杂武器连击
- 多角色交互动作
- 高速镜头切换
- 技能专属长表演

因为这些动作对一致性、模板匹配和后处理都更不友好。

---

## 13. 质量门槛与验收指标

## 13.1 视觉验收

- 主形象与当前项目角色素材视角一致，属于侧视动作素材而不是正面立绘
- 主形象默认朝向右侧，便于运行时镜像
- 角色身份一致，不出现明显换脸换装
- 武器 / 头饰 / 发型不随机消失
- 帧间轮廓稳定，无明显闪烁
- 脚底位置稳定，不出现贴地漂浮
- 像素化后轮廓仍然清楚

## 13.2 资产验收

- 主形象可以预览、重新生成、锁定
- 能成功生成 `sheet.png + manifest.json`
- `CharacterAnimator` 能正常播放
- `groundOffsetY` 可配置
- 动作帧数和 fps 可配置

## 13.3 性能验收

- 编辑器任务提交不阻塞主线程
- 后处理可以异步完成
- 运行时只读本地标准化资源，不发起第三方请求

---

## 14. 风险与对应策略

## 14.1 风险：角色一致性不稳

应对：

- 输入图先标准化
- 同一角色固定一组主参考图
- 为同一角色缓存已验证过的参考素材
- 必要时先用 `InstantCharacter` 补一组一致性参考图

## 14.2 风险：像素风闪烁严重

应对：

- 先高分辨率清理，再统一像素化
- 引入调色板锁定
- 对轮廓做时序平滑
- 允许编辑器端手动剔除异常帧

## 14.3 风险：云模型成本扩张

应对：

- 第一版限制动作模板数量
- 默认走 `wan-std`
- 只有“确认发布”才保留产物
- 对同样输入做结果缓存

## 14.4 风险：供应商变更或配额受限

应对：

- Provider Adapter 抽象化
- 阿里云为主，火山为增强，开源为备份
- 不把第三方返回结构直接耦合到前端

## 14.5 风险：合规问题

应对：

- 加入上传素材声明
- 仅允许项目内资产或已授权素材进入生产链
- 保留任务日志、来源、发布时间和操作人

---

## 15. 成本与资源预估

## 15.1 第一阶段推荐配置

- 先支持 `6` 个基础动作
- 每次动作生成先采用 `4 秒` 左右模板
- 默认使用阿里云 `wan2.2-animate-move` 标准模式

### 估算

按官方价格 `0.4 元/秒` 粗估：

- 单动作 `4 秒`：约 `1.6 元`
- 单角色 `6` 动作：约 `9.6 元`
- `20` 个角色：约 `192 元`

这还不含失败重试，但对编辑器工具链原型阶段是可控的。

## 15.2 本地算力需求

如果只走云生成：

- 本地只需要承担解帧、裁切、像素化、打包
- 普通开发机即可承担

如果要并行预研自托管链：

- `HunyuanVideo-1.5` 官方说明最低显存约 `14GB`
- `InstantCharacter` 的 offload 路线可在 `22GB` 以下显存运行

所以：

- 正式主链先不要求团队成员都配高显存 GPU
- 私有化实验再单独准备 Linux + CUDA 机器

---

## 16. 实施计划

## Phase 1：最小可用版本（推荐 1 周）

目标：

- 跑通“角色设定 / 上传素材 -> 主形象确认 -> 动作模板 -> 预览视频 -> 解帧 -> Sprite Sheet”

内容：

- 接角色主形象生成 / 规范化 API
- 接阿里云 `wan2.2-animate-move`
- 增加角色主形象任务创建与查询 API
- 增加任务创建与查询 API
- 增加本地后处理脚本
- 新增 `CharacterAssetStudio` 原型页

## Phase 2：发布与运行时接入（推荐 1 周）

目标：

- 让主形象与生成结果可以正式替换角色资产

内容：

- 生成 `visual-manifest.json`
- 生成 `manifest.json`
- 扩展 `CharacterAnimator.tsx`
- 增加主形象 override
- 增加角色动画 override
- 加预览与发布流程

## Phase 3：说话与剧情演出（推荐 1 周）

目标：

- 支持 NPC / 角色说话表演

内容：

- 接入 `wan2.2-s2v`
- 增加口型特写产线
- 适配聊天 / 招募 / 剧情特写场景

## Phase 4：增强与备份链（按需）

内容：

- 接火山 `Seedance 2.0`
- 预研 `InstantCharacter + DWPose + MusePose + HunyuanVideo`
- 做多供应商路由与失败兜底

---

## 17. 最终推荐方案

如果只保留一句话，推荐如下：

**用阿里云图像 + 视频能力搭一条“先锁定角色主形象，再生成基础动作”的两段式生产链：角色主形象统一成贴近当前游戏侧视素材的标准图，动作阶段再按现有可扮演角色动作槽位生成并补齐基础动作，最后由项目本地后处理转成像素化序列帧和 Sprite Sheet，接入现有 `CharacterAnimator` 与 override 体系。**

这条路线最符合当前项目的三个现实条件：

- 项目是像素演出驱动，不是纯视频产品
- 项目强调 AI 与本地规则分层
- 项目需要的是“可维护的角色资产生产链”，不是一次性的炫技 Demo

---

## 18. 资料来源

以下资料均为本次方案撰写时实际查阅的主要来源：

- 阿里云百炼视频生成总览：
  [https://help.aliyun.com/zh/model-studio/use-video-generation/](https://help.aliyun.com/zh/model-studio/use-video-generation/)
- 阿里云图像生成与编辑 API：
  [https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference](https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference)
- 阿里云 `wan2.2-animate-move` API：
  [https://help.aliyun.com/zh/model-studio/wan-animate-move-api](https://help.aliyun.com/zh/model-studio/wan-animate-move-api)
- 阿里云视频生成用户指南（含图生视频与首尾帧相关能力入口）：
  [https://help.aliyun.com/zh/model-studio/user-guide/video-generation](https://help.aliyun.com/zh/model-studio/user-guide/video-generation)
- 阿里云模型价格页：
  [https://help.aliyun.com/document_detail/2840918.html](https://help.aliyun.com/document_detail/2840918.html)
- 火山方舟 Seedance 2.0 资料：
  [https://developer.volcengine.com/articles/7606009619928449070](https://developer.volcengine.com/articles/7606009619928449070)
- 腾讯云混元图片跳舞任务：
  [https://cloud.tencent.com/document/api/1616/107784](https://cloud.tencent.com/document/api/1616/107784)
- Tencent Hunyuan `InstantCharacter`：
  [https://github.com/Tencent-Hunyuan/InstantCharacter](https://github.com/Tencent-Hunyuan/InstantCharacter)
- `MusePose`：
  [https://github.com/TMElyralab/MusePose](https://github.com/TMElyralab/MusePose)
- `DWPose`：
  [https://github.com/IDEA-Research/DWPose](https://github.com/IDEA-Research/DWPose)
- `MMPose`：
  [https://github.com/open-mmlab/mmpose](https://github.com/open-mmlab/mmpose)
- `HunyuanVideo-1.5`：
  [https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5](https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5)
- 用户提供的动作生成技巧参考：
  [https://www.bilibili.com/video/BV1LpiYBVE8V/](https://www.bilibili.com/video/BV1LpiYBVE8V/)