This commit is contained in:
@@ -0,0 +1,315 @@
|
||||
# 图片、视频、动作外部生成手动验证运行手册
|
||||
|
||||
日期：`2026-04-23`
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份文档用于冻结 `验证清单.md` 第四项“图片、视频、动作的生成要真实走到外部服务的生成服务上，而不是用占位符来敷衍”的验证口径。
|
||||
|
||||
本次先解决两个问题：
|
||||
|
||||
1. 当前仓库里“真实外部生成链”和“Stage 1 占位兼容链”同时存在，若不先写清楚，很容易把占位产物误记为通过。
|
||||
2. 现有技术设计文档描述了多条资产链，但没有一份面向人工联调的统一运行手册，导致每次验证都要重新猜入口、猜日志、猜通过标准。
|
||||
|
||||
## 2. 当前结论总览
|
||||
|
||||
截至 `2026-04-23` 当前代码状态，第 4 项仍不能整体直接判定“已通过”，原因是不同资产链状态不同。
|
||||
|
||||
### 2.1 当前已经接入真实外部图片生成的入口
|
||||
|
||||
以下入口当前会真实请求外部图片生成服务，而不是只生成本地占位图：
|
||||
|
||||
1. `Big Fish` 结果页：
|
||||
- `生成背景`
|
||||
- `生成并应用正式图` -> `Lv.x 主图`
|
||||
- `生成并应用正式图` -> `Lv.x 动作工坊`
|
||||
2. `custom world / RPG 创作`：
|
||||
- 场景图生成
|
||||
- 作品封面 AI 生成
|
||||
|
||||
这些入口当前统一会走 Rust `api-server`，并向 DashScope 图片生成接口发起请求，再落到 OSS 与兼容读路径。
|
||||
|
||||
### 2.2 当前仍未完全闭环的入口
|
||||
|
||||
以下入口当前仍不能直接判定为“动作资产全后端闭环”：
|
||||
|
||||
1. 角色资产工坊 `image-sequence`
|
||||
- 当前生成的是服务端 SVG 帧，不是真实外部序列图模型结果。
|
||||
2. 角色资产工坊 `motion-transfer / reference-to-video`
|
||||
- 当前仍未接入真实外部模型主链。
|
||||
3. 角色资产工坊 `image-to-video`
|
||||
- 当前已真实请求 Ark 生成 OSS 草稿区 `preview.mp4`。
|
||||
- 但正式帧抽取和去绿幕仍在前端浏览器完成，再回传后端发布。
|
||||
|
||||
因此：
|
||||
|
||||
1. 第 4 项里“图片真实外部生成”目前可以做人工验证。
|
||||
2. 第 4 项里“视频真实外部生成”已有 `image-to-video` 主链证据，但“动作正式资产全后端闭环”仍需要继续验证与收口，不能把前端抽帧回传链直接记成完全通过。
|
||||
|
||||
## 3. 代码级判定依据
|
||||
|
||||
### 3.1 已接真实外部图片服务的依据
|
||||
|
||||
#### 3.1.1 Big Fish 正式图片链
|
||||
|
||||
`server-rs/crates/api-server/src/big_fish.rs`
|
||||
|
||||
当前 `generate_big_fish_formal_asset(...)` 会执行：
|
||||
|
||||
1. 读取 Big Fish 草稿 prompt
|
||||
2. 调用 `require_big_fish_dashscope_settings(...)`
|
||||
3. 调用 `create_big_fish_text_to_image_generation(...)`
|
||||
4. 向 DashScope `text2image/image-synthesis` 发起异步任务请求
|
||||
5. 下载远端生成图片
|
||||
6. 上传 OSS
|
||||
7. 确认 `asset_object`
|
||||
8. 绑定到 Big Fish 槽位
|
||||
|
||||
这条链已经不是占位图写盘。
|
||||
|
||||
#### 3.1.2 Custom World 场景图与封面图
|
||||
|
||||
`server-rs/crates/api-server/src/custom_world_ai.rs`
|
||||
|
||||
当前 `create_text_to_image_generation(...)` 与 `create_reference_image_generation(...)` 会：
|
||||
|
||||
1. 真实请求 DashScope 图片生成接口
|
||||
2. 轮询任务状态或解析生成结果
|
||||
3. 下载远端图片
|
||||
4. 上传 OSS
|
||||
5. 生成 `asset_object` 与实体绑定
|
||||
|
||||
因此场景图、AI 封面图当前属于“真实外部图片生成”。
|
||||
|
||||
### 3.2 仍未完全闭环的依据
|
||||
|
||||
#### 3.2.1 角色动作资产工坊
|
||||
|
||||
`server-rs/crates/api-server/src/character_animation_assets.rs`
|
||||
|
||||
当前链路现状：
|
||||
|
||||
1. `image-to-video` 已真实请求 Ark 生成视频
|
||||
2. 成功结果会下载并写入 `generated-character-drafts/*/preview.mp4`
|
||||
3. `publish` 当前仍读取前端传入的 `framesDataUrls`
|
||||
4. 前端仍通过 `HTMLVideoElement + canvas` 自行抽帧并做去绿幕
|
||||
|
||||
因此当前状态应判定为“真实外部视频生成主链已完成，但正式动作资产后端闭环尚未完成”。
|
||||
|
||||
## 4. 本次验证范围
|
||||
|
||||
本次人工验证分成两部分。
|
||||
|
||||
### 4.1 可直接操作并验证通过/失败的范围
|
||||
|
||||
1. Big Fish 主图生成是否真实打到 DashScope
|
||||
2. Big Fish 动作工坊静态关键帧图是否真实打到 DashScope
|
||||
3. Big Fish 背景图是否真实打到 DashScope
|
||||
4. Custom World 场景图是否真实打到 DashScope
|
||||
5. Custom World AI 封面图是否真实打到 DashScope
|
||||
|
||||
### 4.2 本次要明确记录为“未通过”的范围
|
||||
|
||||
1. 角色资产工坊 `生成角色形象`
|
||||
2. 角色资产工坊 `生成动作`
|
||||
3. 任何依赖仓库内占位视频或 SVG 帧的动作生成入口
|
||||
|
||||
这些入口本次可以操作，但只能用于确认“当前仍未完全闭环”的具体断点，不能把前端抽帧回传链计入“动作资产全后端闭环”通过证据。
|
||||
|
||||
## 5. 前置条件
|
||||
|
||||
开始验证前，必须同时满足以下条件：
|
||||
|
||||
1. 仓库根目录 `.env.local` 已配置：
|
||||
- `DASHSCOPE_API_KEY`
|
||||
- `ALIYUN_OSS_BUCKET`
|
||||
- `ALIYUN_OSS_ENDPOINT`
|
||||
- `ALIYUN_OSS_ACCESS_KEY_ID`
|
||||
- `ALIYUN_OSS_ACCESS_KEY_SECRET`
|
||||
2. 本机已安装：
|
||||
- `cargo`
|
||||
- `node`
|
||||
- `spacetime`
|
||||
- `ffmpeg`
|
||||
- `ffprobe`
|
||||
3. 本地端口可用或已有可复用 Rust 栈：
|
||||
- Web：`3000`
|
||||
- Rust API：`8082`
|
||||
- SpacetimeDB：`3101`
|
||||
4. 必须使用 Rust 栈，而不是旧 Node 栈。
|
||||
|
||||
说明：
|
||||
|
||||
1. 当前 Vite 前端必须指向 Rust `api-server`，否则会把验证结果混入旧链路。
|
||||
2. 验证时必须能实时查看 Rust `api-server` 日志。
|
||||
|
||||
## 6. 启动方式
|
||||
|
||||
推荐统一使用：
|
||||
|
||||
```powershell
|
||||
npm run dev:rust
|
||||
```
|
||||
|
||||
该命令会完成以下动作：
|
||||
|
||||
1. 启动本地 `SpacetimeDB standalone`
|
||||
2. 发布 `server-rs/crates/spacetime-module`
|
||||
3. 启动 Rust `api-server`
|
||||
4. 启动 Vite Web 开发服务器
|
||||
|
||||
若已有栈在运行，至少确认：
|
||||
|
||||
1. Web 可访问：`http://127.0.0.1:3000`
|
||||
2. Rust API 为当前前端的实际代理目标
|
||||
3. `api-server` 正在输出日志
|
||||
|
||||
## 7. 手动验证入口
|
||||
|
||||
### 7.1 Big Fish 正式图片链
|
||||
|
||||
前端路径：
|
||||
|
||||
1. 打开 `http://127.0.0.1:3000`
|
||||
2. 进入平台创作入口
|
||||
3. 选择 `Big Fish`
|
||||
4. 先完成草稿编译
|
||||
5. 进入结果页
|
||||
6. 在结果页依次操作：
|
||||
- `生成背景`
|
||||
- 打开某个等级的 `主图工坊`，点击 `生成并应用正式图`
|
||||
- 打开某个等级的 `动作工坊`，点击 `生成并应用正式图`
|
||||
|
||||
期望日志特征：
|
||||
|
||||
1. Rust `api-server` 中出现 `provider = dashscope`
|
||||
2. 有 Big Fish 正式图片生成请求
|
||||
3. 有 DashScope 任务创建或轮询相关日志
|
||||
4. 生成成功后出现 OSS 写入或正式路径返回
|
||||
|
||||
前端期望结果：
|
||||
|
||||
1. 资源 URL 不再是 `/generated-big-fish/...`
|
||||
2. 而是 `/generated-big-fish-assets/...`
|
||||
3. 结果页状态显示为 `已生成`，而不是 `占位已生成`
|
||||
|
||||
### 7.2 Custom World 场景图
|
||||
|
||||
前端路径：
|
||||
|
||||
1. 进入 RPG / Custom World 创作流程
|
||||
2. 打开场景或地标编辑入口
|
||||
3. 点击场景图生成相关操作
|
||||
|
||||
期望日志特征：
|
||||
|
||||
1. Rust `api-server` 中出现 `provider = dashscope`
|
||||
2. 有图片生成任务创建与轮询
|
||||
3. 成功后有 OSS 对象写入和读取兼容路径
|
||||
|
||||
前端期望结果：
|
||||
|
||||
1. 返回图片不是本地 SVG 占位
|
||||
2. 保存后场景主图可稳定显示
|
||||
|
||||
### 7.3 Custom World AI 封面图
|
||||
|
||||
前端路径：
|
||||
|
||||
1. 进入作品编辑页
|
||||
2. 打开 `编辑作品封面`
|
||||
3. 选择 `AI 生成作品封面`
|
||||
4. 输入封面氛围提示词
|
||||
5. 点击生成并保存
|
||||
|
||||
期望日志特征：
|
||||
|
||||
1. Rust `api-server` 中出现 `provider = dashscope`
|
||||
2. 有封面图生成任务
|
||||
3. 成功后有 OSS 上传与对象确认日志
|
||||
|
||||
前端期望结果：
|
||||
|
||||
1. 生成结果可预览
|
||||
2. 保存后作品封面更新为正式图
|
||||
|
||||
### 7.4 角色资产工坊反向验证
|
||||
|
||||
前端路径：
|
||||
|
||||
1. 打开任一角色的 AI 资产工坊
|
||||
2. 点击 `生成角色形象`
|
||||
3. 再点击 `生成动作`
|
||||
|
||||
本入口的验证目标不是“通过”，而是确认它当前仍未接真实外部视频/图片服务。
|
||||
|
||||
期望证据：
|
||||
|
||||
1. `生成角色形象` 返回的是 SVG 草稿候选
|
||||
2. `生成动作` 若未导入参考视频，会回退预置占位视频
|
||||
3. 日志或结果模型字段不应被当作真实外部视频生成通过证据
|
||||
|
||||
## 8. 通过标准
|
||||
|
||||
第 4 项只有在以下条件全部满足时，才能勾成通过：
|
||||
|
||||
1. 至少一条图片生成入口已拿到真实外部服务调用证据。
|
||||
2. 至少一条视频或动作生成入口已拿到真实外部服务调用证据。
|
||||
3. 这些证据不能依赖 SVG 占位、仓库内预置视频或本地占位文件。
|
||||
4. 前端结果能与日志中的正式链路一一对应。
|
||||
|
||||
换言之：
|
||||
|
||||
1. 仅图片链通过，不代表第 4 项整体通过。
|
||||
2. 仅 Big Fish 动作工坊生成出一张静态图，也不等于“视频/动作真实生成”通过。
|
||||
|
||||
## 9. 当前预判结论
|
||||
|
||||
按当前代码基线，本次更可能得到以下结论：
|
||||
|
||||
1. 图片真实外部生成：可以拿到通过证据。
|
||||
2. 视频、动作真实外部生成：`image-to-video` 主链已可拿到真实外部视频生成证据，但正式动作资产后端闭环仍需要继续收口。
|
||||
|
||||
因此本次人工验证完成后，建议把第 4 项拆成至少两条独立清单：
|
||||
|
||||
1. 图片生成真实外部服务验证
|
||||
2. 视频生成真实外部服务验证
|
||||
3. 动作正式资产后端闭环验证
|
||||
|
||||
否则会把“已完成的图片链 / 视频生成链”与“仍未完成的正式动作发布后端闭环”混成一个模糊状态。
|
||||
|
||||
## 10. 失败判定与排查
|
||||
|
||||
### 10.1 图片入口失败
|
||||
|
||||
优先看 Rust `api-server` 日志中的错误文本：
|
||||
|
||||
1. `dashscope api key 未配置`
|
||||
- 说明环境变量缺失。
|
||||
2. `构造 DashScope HTTP 客户端失败`
|
||||
- 说明本地网络或 TLS 运行环境异常。
|
||||
3. `读取生成响应失败`
|
||||
- 说明上游请求已发出，但响应解析失败。
|
||||
4. `下载远端图片失败`
|
||||
- 说明上游已生成图片，但下载或签名读链出错。
|
||||
5. OSS 相关错误
|
||||
- 说明生成已成功，但落 OSS 或确认对象失败。
|
||||
|
||||
### 10.2 角色资产工坊“看起来成功”
|
||||
|
||||
若角色工坊前端看起来成功，不应立刻视为通过，需要先核对：
|
||||
|
||||
1. 当前策略是否是 `image-sequence / motion-transfer / reference-to-video`
|
||||
2. 若是 `image-to-video`，`preview.mp4` 是否来自真实 Ark 生成
|
||||
3. 正式发布是否仍要求前端回传 `framesDataUrls`
|
||||
|
||||
若只是“后端出真实视频、前端再抽帧回传”，则只能记为“视频生成主链通过，正式动作发布后端闭环未完成”，不能直接把整条动作资产链记为完全通过。
|
||||
|
||||
## 11. 关联文档
|
||||
|
||||
1. [BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md](./BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md)
|
||||
2. [M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md](./M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md)
|
||||
3. [M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md](./M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md)
|
||||
4. [M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md](./M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md)
|
||||
5. [AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md](./AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md)
|
||||
6. [M6_CHARACTER_ANIMATION_BACKEND_FRAME_EXTRACTION_AND_PUBLISH_STAGE3_2026-04-23.md](./M6_CHARACTER_ANIMATION_BACKEND_FRAME_EXTRACTION_AND_PUBLISH_STAGE3_2026-04-23.md)
|
||||
Reference in New Issue
Block a user