Genarrative/docs/technical/ASSET_EXTERNAL_GENERATION_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md

图片、视频、动作外部生成手动验证运行手册

日期：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. 启动方式

推荐统一使用：

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. 结果页状态显示为 已生成，而不是 占位已生成
4. Lv.x 主图 与 idle_float / move_swim 正式图若下载结果为 PNG，后端会在写 OSS 前复用 RPG 角色主图透明背景 alpha 后处理；生成背景 不走该处理

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
2. M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md
3. M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md
4. M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md
5. AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
6. M6_CHARACTER_ANIMATION_BACKEND_FRAME_EXTRACTION_AND_PUBLISH_STAGE3_2026-04-23.md