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

647
docs/technical/ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md
View File

@@ -1,647 +0,0 @@
# 阿里云 NPC 角色形象与动作动画编辑器实验方案（2026-04-07）
## 1. 文档目的
本文不是再写一份泛化的“AI 角色动画大方案”，而是专门回答当前编辑器里要怎么实验这条链路：
- 接入阿里云百炼的文生图、图生图、图生视频、参考视频动作模型
- 以 **NPC 角色形象 + 动作动画资产化** 为目标
- 最终产物仍然要落回当前项目的 `CharacterAssetPanel -> publish -> CharacterAnimator`
本文把方案拆成 4 条实验线：
1. 先文生角色形象图，再图生动作序列帧图并解析
2. 先文生角色形象图，再图生视频
3. 先文生角色形象图，再走“参考视频驱动”的动作模板链
4. 先文生角色形象图，再走“参考生视频 / 剧情演出”链
查阅与核对时间：`2026-04-07`
---
## 1.1 当前实现状态（2026-04-07）
当前仓库已经把下面这些能力接进 `CharacterAssetPanel`：
- 阶段 A：`wan2.7-image-pro / wan2.7-image` 主形象候选生成
- 阶段 B：4 条动作方案都已接入真实模型
- 阶段 C：方案四单独拆成“演出片段”预览区
- 方案三增加了“内置模板库”入口，可直接把项目现有角色序列帧合成为参考视频
- 最近一次主形象任务 / 动作任务状态会回显到编辑器
- 已补动作模板列表接口与视频导入接口
当前实现的本地接口为：
- `POST /api/character-visual/generate`
- `GET /api/character-visual/jobs/:id`
- `POST /api/character-visual/publish`
- `POST /api/animation/generate`
- `GET /api/animation/jobs/:id`
- `GET /api/animation/templates`
- `POST /api/animation/import-video`
- `POST /api/animation/publish`
当前视频后处理采用：
- 模型端生成真实视频
- 浏览器端抽帧、缩放、简单绿幕抠像
- 发布阶段再写入 `public/generated-animations`
也就是说，这份文档里原先一些“推荐下一步”已经落地，但还有一部分“更重的任务化路由”尚未继续拆开。
---
## 2. 当前仓库里的可复用基础
这次实验不应该另起炉灶，因为仓库里已经有 3 个很关键的基础。
### 2.1 编辑器入口已经存在
- 路由 `/character-asset-studio` 已经接到 `PresetEditor`，说明“角色资产工坊”入口是现成的。
- 当前核心页面是 `src/components/preset-editor/CharacterAssetPanel.tsx`。
### 2.2 主形象 / 动作两段式 UI 已经存在
当前 `CharacterAssetPanel` 已经分成：
- 阶段 A：主形象
- 阶段 B：基础动作
- 阶段 C：演出片段
旧版本里生成逻辑确实是本地 mock：
- 主形象候选来自 `buildVisualCandidatesFromSource`
- 动作草稿来自 `buildAnimationClipFromMaster`
现在这层已经被真实模型链路替换，但仍然保留了这些本地能力作为后处理工具：
- 参考视频模板合成
- 视频抽帧
- 简单绿幕抠像
- 生成发布用帧集
### 2.3 本地 API 插件里已经有 DashScope 接入样板
本文撰写时，旧 `scripts/dev-server/localApiPlugins.ts` 里已经接了自定义世界场景图。
截至 `2026-04-19`，该文件已从仓库删除，对应样板能力应改为参考 `server-node/src/modules/assets/**` 与 `server-node/src/modules/ai/**`：
- 默认 DashScope base URL 已经存在
- 已经有异步任务创建、轮询、下载、落盘、写 manifest 的完整样板
这意味着这次实验最合理的做法是：
- 继续沿用 `/api/*` 本地代理模式
- 新增角色图 / 角色动作的 job 路由
- 复用现有的任务轮询和文件落盘思路
---
## 3. 阿里云当前可直接利用的模型能力
基于 2026-04-07 查阅的阿里云官方文档，当前和本实验最相关的是下面几类能力。
| 能力 | 推荐模型 | 适合用途 | 备注 |
| --- | --- | --- | --- |
| 文生图 / 图生图 / 图像编辑 | `wan2.7-image-pro`、`wan2.7-image` | 生成 NPC 主形象图、做风格统一、生成组图候选 | 官方文档明确支持多图参考与组图输出 |
| 图生视频 | `wan2.7-i2v` | 单角色主形象转动作视频 | 支持首帧、首尾帧、续写片段 |
| 参考生视频 | `wan2.7-r2v`、`wan2.6-r2v-flash` | 多参考图/参考视频驱动剧情演出 | 更适合演出，不是最优基础动作线 |
| 图生动作 | `wan2.2-animate-move` | 主形象 + 参考动作视频 -> 标准动作视频 | 动作控制更强，适合模板动作库 |
| 视频换人 | `wan2.2-animate-mix` | 模板视频里的角色替换成 NPC 形象 | 适合动作模板“复刻” |
需要特别说明：
- 方案一会用到 `wan2.7-image-pro` 的组图 / 顺序组图能力，但 **官方并没有把它定义为“动作逐帧模型”**。
- 所以方案一是“利用图像模型能力去逼近动作帧生产”的实验线，不是官方标准动作生产线。
- 方案二、三、四更贴近阿里云官方为视频生成准备的主线能力。
---
## 4. 方案一：文生角色形象图 -> 图生动作序列帧图 -> 解析成动画
## 4.1 目标
直接得到 `png` 帧集，尽量少碰视频编解码。
## 4.2 模型链路
1. 用 `wan2.7-image-pro` 生成 NPC 主形象图
2. 再把主形象图作为参考图输入 `wan2.7-image-pro`
3. 对每个动作槽位生成一组候选图片
4. 打开组图输出，必要时启用 `enable_sequential`
5. 本地按动作顺序解析这些图，写回帧序列
## 4.3 为什么它成立
阿里云图像生成与编辑 API 当前明确支持：
- 文生图
- 图生图
- 多图参考
- 一次输出多张图
- 顺序组图输出 `enable_sequential`
因此可以在编辑器里做这样的实验：
- 输入：主形象图 + 动作描述 + 固定 seed
- 输出：同一动作的一组关键帧候选
- 后处理：按姿态差异、角色一致性、武器完整度排序，补成帧集
## 4.4 编辑器里的具体玩法
建议在当前“阶段 B：基础动作”里加一个策略选项：
- `帧序列实验（图像组图）`
每次动作生成时：
1. 选择动作槽位，如 `idle / run / attack / hurt`
2. 选择目标帧数，如 `4 / 6 / 8`
3. 传入主形象图
4. 拼出动作提示词，例如“同一角色，侧身朝右，单人，全身，武器完整，连续 6 帧，跑步动作，从预备到迈步再到回收”
5. 请求组图结果
6. 本地做帧序评分
7. 生成 `frames/*.png + manifest.json`
## 4.5 优点
- 直接产出图片，天然适合当前项目的帧资产结构
- 不需要先生成视频再解帧
- 某些短动作可以直接人工挑帧，编辑器可控性高
- 对 `idle`、`acquire`、`hurt` 这种短动作实验门槛较低
## 4.6 风险
- 最大风险是帧间一致性，特别容易出现衣摆、武器、手部、头发抖动
- 组图的“顺序性”不等于真正的视频时序连续性
- `run`、`jump`、`dash` 这类长动作很可能不稳定
- 如果没有额外姿态评分和人工筛选，最后帧序会很跳
## 4.7 结论
这是 **低基础设施成本、高人工筛选成本** 的方案。
适合：
- 编辑器里先做原型实验
- 验证 NPC 主形象一致性能不能维持到多帧
- 生成短动作关键帧
不适合直接作为第一版唯一主线。
---
## 5. 方案二：文生角色形象图 -> 图生视频 -> 解帧资产化
## 5.1 目标
先让视频模型负责动作连续性，再由本地后处理把视频转成项目动画资产。
## 5.2 模型链路
1. 用 `wan2.7-image-pro` 生成 NPC 主形象图
2. 用 `wan2.7-i2v` 基于主形象图生成动作视频
3. 下载视频结果
4. 本地抽帧
5. 做裁切、稳帧、像素化、去闪烁
6. 输出序列帧、Sprite Sheet、manifest
## 5.3 方案二里的两种子模式
### A. 首帧生视频
适合：
- `attack`
- `hurt`
- `die`
- `cast`
特点：
- 主形象图作为 `first_frame`
- 文本控制动作
- 最快接入，链路最短
### B. 首尾帧生视频
适合：
- `idle`
- `run`
- 循环站姿
特点：
- `first_frame` 是起始站姿
- `last_frame` 是回正后的收尾姿态
- 更利于做循环动作和回到可衔接状态
## 5.4 编辑器里的具体玩法
建议在“阶段 B：基础动作”里加：
- `图生视频（首帧）`
- `图生视频（首尾帧）`
参数建议：
- 时长：`2s / 3s / 4s`
- 目标 FPS：先统一导入到本地后再重采样
- 循环动作：是否要求首尾近似
- 提示词模板：按动作槽位固化
## 5.5 优点
- 动作连续性通常明显强于方案一
- `wan2.7-i2v` 是官方主线能力，兼容性和迭代空间更好
- 很适合作为当前编辑器的第一条“真实动作生成”主线
- 本地后处理完成后，仍然能回到当前项目的帧资源体系
## 5.6 风险
- 需要稳定的视频后处理链
- 解帧后仍要处理轮廓闪烁、脚底漂移、武器变形
- 主形象复杂时，单图生视频可能会有角色漂移
- 相比方案一，I/O 和处理耗时更高
## 5.7 结论
这是 **最适合作为编辑器第一版正式实验主线** 的方案。
原因：
- 模型能力更贴近官方主线
- 动作连续性通常更稳定
- 生成结果仍可资产化
---
## 6. 方案三：文生角色形象图 -> 参考视频驱动动作模板链
## 6.1 目标
不是只靠文本“想象动作”，而是给动作一个明确模板视频，让模型做可控迁移。
## 6.2 模型链路
推荐两条可选子线：
### A. `wan2.2-animate-move`
输入：
- NPC 主形象图
- 参考动作视频
输出：
- NPC 执行该动作的视频
### B. `wan2.2-animate-mix`
输入：
- NPC 主形象图
- 模板视频
输出：
- 保留模板视频场景/动作，但把角色替换成 NPC
## 6.3 它和方案二的本质区别
方案二是：
- 主形象图 + 文本描述 -> 视频
方案三是：
- 主形象图 + 模板动作视频 -> 视频
因此方案三最大的价值不是“更自由”，而是“更可控”。
## 6.4 编辑器里的具体玩法
在“阶段 B：基础动作”里新增：
- `动作模板库`
每个动作槽位先配一份官方/自制模板：
- `idle_loop`
- `run_side`
- `attack_slash`
- `hurt_back`
- `die_fall`
工作流：
1. 先锁定 NPC 主形象
2. 选择动作槽位
3. 选择一个模板视频
4. 调用 `animate-move` 或 `animate-mix`
5. 下载视频
6. 解帧、稳帧、裁切
7. 发布为该动作槽位正式资产
## 6.5 优点
- 可控性明显高于纯文本图生视频
- 非常适合做“基础动作槽位不能为空”的项目要求
- 一旦模板库建立起来，多角色批量复用效率很高
- 对 `run`、`attack`、`hurt` 这种标准动作尤其友好
## 6.6 风险
- 要先建设动作模板库
- `wan2.2-animate-move` 官方输入更偏“单人清晰主体”，对严格侧视游戏素材要额外测试
- 模板视频如果镜头、背景、构图不统一，后处理成本会增加
- 模板库前期准备成本高于方案二
## 6.7 结论
这是 **最适合做战斗基础动作标准化生产** 的方案。
如果只看“当前项目需要补齐 `idle / run / attack / hurt / die` 这些基础槽位”，方案三的长期价值甚至高于方案二。
建议排序：
- 第一阶段先做方案二跑通链路
- 第二阶段尽快把方案三补成稳定模板库主线
---
## 7. 方案四：文生角色形象图 -> 参考生视频 / 剧情演出链
## 7.1 目标
这条线不是优先服务“战斗基础动作”，而是服务：
- 剧情演出
- 招募演出
- NPC 说话/表态
- 立绘转小段表演视频
## 7.2 模型链路
推荐：
- `wan2.7-r2v`
- 成本敏感或无声短片可考虑 `wan2.6-r2v-flash`
参考生视频支持把图片、视频作为参考条件输入，再结合文本生成视频。
## 7.3 它和方案三的区别
方案三更像：
- 我已经知道动作模板，就要把它迁过去
方案四更像：
- 我给你角色参考和演出参考，请你生成一段新的镜头表达
所以它更适合：
- NPC 出场特写
- 对话演出
- 剧情镜头
- 情绪表演
不适合优先用于：
- 项目所有基础战斗动作槽位
## 7.4 编辑器里的具体玩法
当前已单独拆成：
- `演出片段`
字段建议：
- 角色主形象
- 参考图最多若干张
- 参考视频片段
- 台词或情绪提示
- 是否保留音频
输出：
- `preview.mp4`
- 关键帧截图
- 可选封面图
## 7.5 优点
- 角色一致性上限更高
- 更适合做剧情演出而不是纯动作片段
- 后续和 `CharacterChatModal`、NPC 招募、事件特写更容易联动
## 7.6 风险
- 对当前战斗帧资产体系帮助没有前三条直接
- 更容易产出“好看的视频”，但不一定容易切成稳定序列帧
- 这条线如果过早投入，会稀释基础动作资产生产的主线
## 7.7 结论
这是 **剧情演出增强线**，不建议抢在方案二、三之前做。
---
## 8. 四种方案横向对比
| 方案 | 动作连续性 | 可控性 | 资产化难度 | 适合基础动作 | 适合剧情演出 | 推荐阶段 |
| --- | --- | --- | --- | --- | --- | --- |
| 方案一：组图帧序列 | 低到中 | 中 | 低到中 | 中 | 低 | 研究线 |
| 方案二：图生视频 | 中到高 | 中 | 中到高 | 高 | 中 | 第一阶段主线 |
| 方案三：模板视频驱动 | 高 | 高 | 中到高 | 很高 | 中 | 第一阶段后半 / 第二阶段主线 |
| 方案四：参考生视频 | 中到高 | 中到高 | 高 | 中 | 很高 | 第三阶段增强 |
一句话总结：
- 要最快落地：先做 **方案二**
- 要把基础动作做稳：尽快补 **方案三**
- 要低成本试帧：可以并行试 **方案一**
- 要做剧情镜头：后续再做 **方案四**
---
## 9. 面向当前编辑器的落地状态与下一步
## 9.1 第一轮
这一轮已经完成：
- 阶段 A：`wan2.7-image-pro` 主形象生成
- 阶段 B：`wan2.7-i2v` 图生视频
原因：
- 最少改 UI
- 最快复用当前 `CharacterAssetPanel`
- 最容易复用现已迁入 `server-node` 的 DashScope 异步任务模式
## 9.2 第二轮
这一轮已经完成：
- `图生视频`
- `模板视频驱动`
- `帧序列实验`
并且已经补上：
- 方案三的内置模板库入口
- 方案四的独立“演出片段”区
## 9.3 第三轮
下一步仍然值得继续做的是：
- 把当前同步 `generate` 继续拆成显式 `jobs`
- 把视频导入后处理继续拆成独立 `import-video`
- 给方案三补更多正式模板素材与模板清单管理
- 给方案四补关键帧归档、封面和片段列表
---
## 10. 推荐的编辑器任务路由
当前已落地接口：
- `POST /api/character-visual/generate`
- `GET /api/character-visual/jobs/:id`
- `POST /api/character-visual/publish`
- `POST /api/animation/generate`
- `GET /api/animation/jobs/:id`
- `GET /api/animation/templates`
- `POST /api/animation/import-video`
- `POST /api/animation/publish`
当前职责：
### `POST /api/character-visual/generate`
负责：
- 调 `wan2.7-image-pro`
- 生成主形象候选
- 下载并落盘
- 返回草稿图路径
### `GET /api/character-visual/jobs/:id`
负责：
- 返回最近一次主形象任务状态
- 返回模型、提示词、结果草稿等任务记录
### `POST /api/animation/generate`
负责：
- 按策略调不同模型
- `i2v`
- `animate-move`
- `animate-mix`
- `r2v`
- 返回顺序组图或视频草稿
### `GET /api/animation/jobs/:id`
负责：
- 返回最近一次动作任务状态
- 返回策略、模型、输出草稿路径和错误信息
### `GET /api/animation/templates`
负责：
- 返回方案三内置模板库清单
- 供编辑器选择 `idle_loop / run_side / attack_slash / hurt_back / die_fall`
### `POST /api/animation/import-video`
负责：
- 把浏览器侧生成或上传的视频导入本地草稿目录
- 返回可复用的本地视频路径
### `POST /api/animation/publish`
负责：
- 把草稿帧写入 `public/generated-animations`
- 生成动作 manifest
- 更新 `characterOverrides.json`
### 仍建议后续继续加强的部分
- 把当前“同步 generate + 立即返回结果”继续拆成更完整的异步 job 生命周期
- 给 `import-video` 增加更重的服务端后处理，而不只是导入草稿
- 给模板库补正式素材管理与模板清单编辑
---
## 11. 第一批建议验证的动作
不要一上来就跑全量 12 个基础动作，先验证 4 个最关键动作：
1. `idle`
2. `run`
3. `attack`
4. `hurt`
原因：
- 这 4 个已经能覆盖循环动作、位移动作、攻击动作、受击动作
- 最容易测出“主形象一致性 + 动作连续性 + 贴地稳定性”
---
## 12. 具体推荐结论
如果只给当前编辑器实验一个最务实的建议：
1. **主形象统一先接 `wan2.7-image-pro`**
2. **动作第一条真链路先接方案二：`wan2.7-i2v`**
3. **基础动作标准化的主线尽快切到方案三：`wan2.2-animate-move / animate-mix`**
4. **方案一保留为低成本帧序实验线，方案四保留为剧情演出增强线**
换句话说：
- 方案二负责“尽快跑通”
- 方案三负责“真正稳定生产”
- 方案一负责“低成本试错”
- 方案四负责“后续演出升级”
---
## 13. 资料来源
阿里云官方文档：
- 图像生成与编辑 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)
- 图生视频 API 参考：
[https://help.aliyun.com/zh/model-studio/image-to-video-api-reference/](https://help.aliyun.com/zh/model-studio/image-to-video-api-reference/)
- 参考生视频 API 参考：
[https://help.aliyun.com/zh/model-studio/reference-to-video-api-reference/](https://help.aliyun.com/zh/model-studio/reference-to-video-api-reference/)
- 视频生成总览：
[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-video-to-video-api-reference](https://help.aliyun.com/zh/model-studio/wan-video-to-video-api-reference)
仓库内相关代码与文档：
- `src/components/preset-editor/CharacterAssetPanel.tsx`
- `src/components/preset-editor/characterAssetStudioModel.ts`
- `src/components/preset-editor/characterAssetStudioPersistence.ts`
- `src/routing/appRoutes.tsx`
- `src/services/ai.ts`
- `server-node/src/modules/assets/**`
- `server-node/src/modules/ai/**`
- `docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md`