GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prune stale docs and update .hermes content

Browse Source 
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
高物
2026-05-15 06:24:07 +08:00
parent 2eded08bc7
commit 3cb3efb4d0
708 changed files with 4033 additions and 142328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

635
docs/prd/AI_CHARACTER_VISUAL_ANIMATION_MVP_PRD_2026-04-04.md
View File

@@ -1,635 +0,0 @@
# AI 角色形象与角色动画 MVP PRD
更新时间：`2026-04-19`
## 0. 一句话结论
本次 MVP 要做的不是一个泛化的“AI 动画平台”，而是一个能直接服务当前项目角色资产生产的最小闭环：
1. 用户先输入角色形象设定并上传参考图，或直接上传现成角色素材
2. 系统生成或规范化出一张**符合当前游戏侧视角色素材视角**的主形象图
3. 用户确认主形象后，再为该角色生成与当前项目可扮演角色动作槽位匹配的基础动作集
4. 用户可预览、重新生成，并最终发布为当前仓库可直接读取的角色资产
一句话说：
**MVP 先解决“怎么稳定产出能进游戏的角色主形象和基础动作”，而不是先追求所有技能动作和复杂演出。**
---
## 1. 背景
当前仓库已经有：
- 可扮演角色与角色型 NPC
- `CharacterAnimator` 运行时播放链路
- 角色预设与 override 机制
- 本地 API 插件机制
- NPC 静态形象编辑器
但当前缺少一条可用的角色资产生产链：
1. 角色主形象仍依赖手工素材整理
2. 动作资产缺少“从角色设定到可播放动作集”的编辑器闭环
3. 没有把“AI 生成结果”稳定沉淀为当前项目的标准角色资源
因此本期 MVP 的目标不是重做运行时战斗系统，而是补齐：
- 主形象生产
- 基础动作生产
- 预览与重新生成
- 发布到现有角色资源体系
---
## 2. MVP 要解决的问题
## 2.1 用户侧问题
当前如果想给项目新增一个角色，成本很高：
- 要先准备适合当前游戏视角的主形象
- 再补动作资源
- 还要手工整理资源目录和配置
MVP 要把这件事改成一个编辑器工作流。
## 2.2 项目侧问题
当前项目并不适合把 AI 直接放进运行时实时生成动作，因为：
- 运行时需要稳定、可回放、可测试的资源
- 战斗和剧情都依赖固定动作槽位
- 生成结果如果不资产化，会让维护成本失控
所以 MVP 的正确方向是：
**把 AI 用在编辑器里的资产生产链，而不是运行时即时生成。**
---
## 3. MVP 目标
## 3.1 产品目标
提供一个最小可用的“角色资产工坊”，满足以下闭环：
1. 生成或上传角色主形象
2. 预览并重选角色主形象
3. 基于主形象生成基础动作
4. 预览并重选动作结果
5. 发布为当前项目可直接使用的角色资源
## 3.2 技术目标
MVP 必须满足：
1. 只依赖国内可用模型与服务
2. 只生成当前项目能消费的标准资产
3. 不改动现有战斗规则与剧情规则
4. 生成结果必须走本地后处理与发布流程
5. 运行时只读本地标准化资产
## 3.3 成功标准
当以下条件同时成立时，视为 MVP 成功：
1. 编辑器里可以完成“主形象 -> 基础动作 -> 发布”闭环
2. 发布后的角色能被当前 `CharacterAnimator` 播放
3. 基础动作槽位不存在空映射
4. 用户可以对主形象和动作分别进行重新生成
---
## 4. 非目标
本期不做：
1. 不做运行时实时动画生成
2. 不做怪物动画生成链路
3. 不做通用 NPC 群像流水线
4. 不做技能动作全自动补齐
5. 不做批量生产多个角色的自动流水线
6. 不做多供应商路由调度
说明：
- 本期只先做好**单角色、单次编辑器操作**的最小闭环
- 技能动作可后续补，但**基础动作槽位不能为空**
---
## 5. 目标用户与使用场景
## 5.1 目标用户
- 项目策划
- 项目美术 / 技术美术
- 负责角色内容生产的开发者
## 5.2 核心使用场景
### 场景 A：新建角色
用户输入角色设定词、参考图，生成当前项目风格可用的主形象和基础动作。
### 场景 B：已有角色素材导入
用户已有一张角色图，希望快速裁切、规范化，并继续生成基础动作。
### 场景 C：已有角色动作质量不满意
用户不改主形象，只重新生成单个或多个动作槽位。
---
## 6. MVP 用户流程
## 6.1 阶段 A：主形象生成 / 导入
1. 用户选择角色
2. 输入角色形象设定文本
3. 上传角色参考图，或直接上传现成角色素材
4. 系统做尺寸、裁剪、构图校验
5. 提交生成或规范化任务
6. 返回多个候选预览图
7. 用户可：
- 预览
- 重新生成
- 设为当前主形象
## 6.2 阶段 B：基础动作生成
1. 用户基于已确认主形象进入动作页
2. 系统展示当前基础动作槽位状态
3. 用户选择：
- 直接使用动作模板
- 上传参考动作视频
4. 提交动作生成任务
5. 生成完成后进入动作预览
6. 用户可：
- 保留结果
- 重新生成单动作
- 替换当前动作
## 6.3 阶段 C：发布
只有在基础动作槽位全部有有效资源时，才允许发布。
发布后：
1. 写入主形象资源
2. 写入动画资源
3. 生成 manifest
4. 更新角色 override / 映射关系
---
## 7. 主形象阶段需求
## 7.1 输入方式
MVP 支持三种主形象输入方式：
1. 文生图
- 用户输入形象设定
2. 图生图
- 用户输入形象设定并上传参考图
3. 直接上传素材
- 用户上传已有角色图，不强制重新生成
## 7.2 视角要求
主形象必须贴近当前项目现有角色素材体系：
- 2D 侧视动作素材视角
- 单人全身
- 人物朝向右侧
- 脚底完整可见
- 武器和关键轮廓完整
- 不做正面立绘
- 不做强透视镜头
这是硬约束，不是美术建议。
原因：
- 当前项目运行时通过镜像处理左右朝向
- 如果主形象不是侧视动作素材视角，后续动作生成和运行时挂接都会失真
## 7.3 尺寸与裁剪要求
推荐规格：
- 推荐输入：`1024x1536`
- 可接受比例：`2:3` 或 `3:4`
- 最低建议：短边 `>= 768`
- 统一输出标准图：`1024x1536`
构图要求：
- 角色主体占画面高度约 `70% ~ 85%`
- 头顶保留少量留白
- 脚底必须完整露出
- 背景尽量简单
- 只允许单角色
## 7.4 主形象阶段交互要求
用户必须可以：
- 查看候选结果
- 放大预览
- 丢弃某个候选
- 基于同样输入重新生成
- 选择一个候选作为主形象
用户不能直接跳过主形象确认进入动作阶段，除非已经锁定主形象。
---
## 8. 动作阶段需求
## 8.1 基础动作槽位要求
MVP 必须与当前项目可扮演角色动作槽位对齐。
当前落地实现补充约束（`2026-04-20`）：
- 角色资产工坊固定生成入口仍为 `idle / run / attack / die`
- `run / attack` 是固定基础必生成动作
- `idle / die` 改为固定可选动作，不再作为发布硬门槛
- `idle` 未生成时默认直接使用主图静止显示
- `die` 未生成时默认播放一段基于主图的向后倒地过渡动画，并最终停在翻转倒地姿态
- 角色已配置的每个技能，都必须在技能编辑面板里补出对应动作预览
- 图生视频默认走火山方舟 `Seedance` 首尾帧方案
- 接口请求体中的两张参考图分别固定为 `first_frame / last_frame`
- 固定参数为 `1:1`、`480p`、`4 秒`、单次 `1` 个视频
- 提示词中的动作名统一传英文动作名
第一版动作生成按下面两层规则落地：
| 类别 | 动作槽位 | 是否必填 | 备注 |
| -------- | ------------------------------- | -------- | -------------------------------------------------- |
| 基础动作 | `run` | 必填 | 角色移动主循环动作 |
| 基础动作 | `attack` | 必填 | 角色普通攻击主动作 |
| 技能动作 | `skills[*].actionPreviewConfig` | 必填 | 当前角色每个已配置技能都要有独立动作资源 |
| 可选动作 | `idle` | 可选 | 缺失时默认走主图静止待机 |
| 可选动作 | `die` | 可选 | 缺失时默认走主图向后倒地过渡动画，最终停在翻转倒地姿态 |
这里“必生成”指的是：
- `run / attack` 必须最终指向可播放资源
- 每个已配置技能都必须带独立 `actionPreviewConfig`
- 发布判定不再要求 `idle / die` 一定存在动画映射
- 运行时仍然不能出现无可用表现；`idle / die` 的缺口由默认兜底承担
## 8.2 技能动作要求
本期不再要求把整套固定技能枚举一次性自动补齐，但对“角色当前实际配置的技能”改为必做：
- 不要求预先把 `skill1 / skill2 / skill3 / skill4` 这套历史枚举全部补满
- 只要求当前角色 `skills` 数组里的每个技能都生成独立动作预览
- 技能动作生成入口继续放在技能编辑面板逐个处理，不塞进固定四按钮里
结论：
- 技能动作从“固定枚举可选”调整为“按角色已配技能必做”
- 固定基础动作收敛为 `run / attack`
- `idle / die` 保留为可选增强动作
## 8.3 动作生成方式
MVP 支持两种方式：
1. 模板动作生成
- 用户选择动作模板
2. 参考视频驱动
- 用户上传参考动作视频
优先级：
- 基础动作优先走模板
- 个性化动作再用参考视频驱动
## 8.4 动作阶段交互要求
用户必须可以：
- 查看每个动作槽位当前状态
- 单独预览某个动作
- 单独重新生成某个动作
- 保留某些已满意动作，只重生其余动作
- 在所有基础动作齐全后再发布
---
## 9. 生成策略约束
## 9.1 角色一致性优先
动作生成阶段只能使用已锁定的主形象，不允许每个动作重新随机生成角色外观。
## 9.2 首尾帧控制
参考用户提供的视频方向，MVP 固化以下策略：
### 循环动作
- `idle`
- `run`
要求首尾姿态尽量接近，便于循环。
### 一次性动作
- `attack`
- `jump_attack`
- `die`
要求末帧清晰，不与下一动作切换冲突。
## 9.3 高分辨率生成，低分辨率落地
MVP 不要求模型直接输出最终像素逐帧。
正确流程是：
1. 生成较稳定的高分辨率动作视频
2. 本地解帧、对齐、清理
3. 再转成当前项目可用的像素化资产
---
## 10. 技术方案边界
## 10.1 模型选择
MVP 统一采用国内可用的阿里云百炼方案：
- 主形象生成：`wan2.7-image-pro` / `wan2.7-image`
- 动作生成：`wan2.2-animate-move`
- 高质量换角动作：`wan2.2-animate-mix`
选择理由：
1. 国内可用
2. 图像和动作链路在同一平台
3. 便于 MVP 先收敛到单平台实现
## 10.2 本地后处理
MVP 必须包含本地后处理：
1. 解帧
2. 主体裁切
3. 背景清理
4. 稳帧
5. 像素化
6. 打包 Sprite Sheet
7. 输出 manifest
## 10.3 运行时边界
运行时不直接请求第三方模型接口。
运行时只读取：
- 主形象标准资源
- 动画标准资源
- override / manifest 配置
---
## 11. MVP 数据与接口
## 11.1 角色主形象资源
建议最小结构：
```ts
type GeneratedCharacterVisualAsset = {
id: string;
characterId: string;
sourceMode: 'text-to-image' | 'image-to-image' | 'upload';
masterImagePath: string;
previewImagePaths: string[];
width: number;
height: number;
facing: 'right';
locked: boolean;
};
```
## 11.2 角色动画资源
```ts
type GeneratedCharacterAnimationAsset = {
id: string;
characterId: string;
visualAssetId: string;
action: string;
frameCount: number;
fps: number;
loop: boolean;
spriteSheetPath: string;
framePaths: string[];
previewVideoPath: string;
};
```
## 11.3 最小接口
建议新增：
- `POST /api/character-visual/jobs`
- `GET /api/character-visual/jobs/:id`
- `POST /api/character-visual/publish`
- `POST /api/animation/jobs`
- `GET /api/animation/jobs/:id`
- `GET /api/animation/templates`
- `POST /api/animation/publish`
职责：
### `POST /api/character-visual/jobs`
- 创建主形象生成或规范化任务
### `GET /api/character-visual/jobs/:id`
- 查询主形象任务状态与结果
### `POST /api/character-visual/publish`
- 锁定主形象并写入主形象 manifest
### `POST /api/animation/jobs`
- 创建动作生成任务
### `GET /api/animation/jobs/:id`
- 查询动作任务状态与结果
### `GET /api/animation/templates`
- 返回动作模板列表
### `POST /api/animation/publish`
- 发布动作资源并更新动画映射
---
## 12. 与当前仓库的接入点
第一批建议接入：
- `src/components/CharacterAnimator.tsx`
- `src/types/characters.ts`
- `src/data/characterOverrides.json`
- `server-node/src/modules/assets/**`
建议新增：
- `src/components/CharacterAssetStudio.tsx`
- `src/data/characterAnimationOverrides.json`
- 角色主形象 manifest 读取逻辑
- 动画 manifest 读取逻辑
运行时优先级建议：
1. 角色 AI 生成动画 override
2. 角色原始 `animationMap`
3. 默认回退动画
---
## 13. 验收标准
## 13.1 主形象验收
1. 用户可以通过文生图 / 图生图 / 直接上传素材三种方式得到主形象
2. 主形象视角符合当前项目侧视角色素材要求
3. 主形象可预览、可重新生成、可锁定
## 13.2 动作验收
1. 所有基础动作槽位均有有效资源
2. 用户可以单独预览和重新生成某个动作
3. 发布后动作能被当前 `CharacterAnimator` 播放
## 13.3 资产验收
1. 发布后可生成主形象资源目录
2. 发布后可生成动画资源目录
3. 可生成对应 manifest / override 映射
## 13.4 体验验收
1. 用户不需要手工整理最终资源目录
2. 用户不需要每次都从头重做全部动作
3. 主形象和动作两阶段都可回看和重生
---
## 14. 风险与对策
## 14.1 风险：主形象视角不稳定
对策：
- 把“侧视、朝右、全身、脚底完整”作为硬校验
- 不合格结果不允许直接进入动作阶段
## 14.2 风险：动作循环不自然
对策：
- `idle`、`run` 强制使用循环模板优先
- 引入首尾帧接近度校验
## 14.3 风险：基础动作槽位过多，MVP 开发压力大
对策：
- 允许 `acquire`、`double_jump`、`wall_slide` 等少数槽位由近似动作衍生
- 但运行时最终槽位仍必须非空
## 14.4 风险：生成成本过高
对策：
- 先只支持单角色编辑
- 基础动作优先模板化
- 仅对不满意动作单独重生
---
## 15. MVP 开发顺序
## 阶段 1：主形象闭环
目标：
- 跑通主形象生成 / 上传 / 预览 / 锁定
产出：
- `CharacterAssetStudio` 的主形象页
- 主形象任务 API
- 主形象 manifest
## 阶段 2：基础动作闭环
目标：
- 跑通单动作生成、预览与替换
产出：
- 动作任务 API
- 动作模板列表
- 预览与重新生成流程
## 阶段 3：基础动作补齐与发布
目标：
- 让必生成动作全部就绪，并为 `idle / die` 提供明确默认兜底
产出：
- 动作状态面板
- 发布逻辑
- override / manifest 写入
## 阶段 4：运行时接入
目标：
- 让发布后的角色直接在现有运行时播放
产出：
- `CharacterAnimator` 读取生成动画能力
- 角色 override 映射接入
---
## 16. 最终结论
对当前仓库来说，最可落地的 MVP 不是“先做一个很强的 AI 动画系统”，而是：
1. 先固定角色主形象生产流程
2. 再固定基础动作生产流程
3. 只补能进当前项目运行时的最小动作集
4. 把预览、重新生成和发布做完整
这样做的价值在于：
- 范围可控
- 路径清晰
- 能真正进入当前仓库
- 后续可以在此基础上再加技能动作、剧情演出和多供应商增强路线