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

日期：`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. 结果页状态显示为 `已生成`，而不是 `占位已生成`
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](./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)