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

大鱼吃小鱼正式图片生成接入方案 2026-04-23

日期：2026-04-23

1. 文档目的

在 2026-04-23 早些时候，我们已经修复了 Big Fish 结果页“显示已生成但只能看到蓝色底图”的问题，先让占位图真正可见。

这份文档继续冻结下一步方案：把 Big Fish 结果页从“占位可见”升级为“模型正式出图”，并且复用仓库现有的 Rust 图片生成与 OSS 真相链，不再为 Big Fish 单独发明一套新资产系统。

2. 当前问题复盘

上一阶段虽然解决了“看不见图”的问题，但本质仍是占位链：

1. api-server 先写本地 public/generated-big-fish/* 占位 PNG。
2. spacetime-module 把 big_fish_asset_slot.status 写成 ready。
3. asset_url 写的是 /generated-big-fish/...。
4. 结果页能看到图片，但那只是占位预览，不是真实模型图。

这意味着：

1. 用户在结果页看到的“主图 / 动作 / 背景”仍不是正式资产。
2. ready 语义对 Big Fish 来说仍然偏弱，只表示“槽位上已有可预览资源”，不等同于“模型正式资产已落 OSS 真相链”。

3. 本次目标

本次把以下三类 Big Fish 资产切到正式图片生成链：

1. level_main_image
2. level_motion
3. stage_background

当前只接“正式静态图片生成”，不在这一轮扩视频、逐帧序列或动作 manifest。

原因是：

1. Big Fish 结果页当前只消费单个 assetUrl。
2. 运行态和结果页目前都按静态图预览设计。
3. 先把正式主图链闭合，比提前引入一套未被消费的视频协议更稳。

4. 统一真相链

Big Fish 正式图片生成统一复用现有 Rust 主链：

1. api-server 根据 Big Fish 草稿 prompt 调用 DashScope 文生图。
2. Rust 下载远端图片二进制。
3. Rust 上传到私有 OSS。
4. Rust 调用 confirm_asset_object 确认正式对象。
5. Rust 调用 bind_asset_object_to_entity 绑定 Big Fish 业务槽位。
6. Rust 再调用 Big Fish procedure，把 big_fish_asset_slot.asset_url 写成正式兼容路径。
7. 前端继续通过 ResolvedAssetImage 和 /api/assets/read-url 消费图片。

5. 路径策略

5.1 占位路径继续保留

占位图路径继续保持：

/generated-big-fish/*

它只代表：

1. 本地开发态占位可见资源。
2. 旧的最小预览兼容层。

5.2 正式图片使用新前缀

正式 Big Fish 图片统一写到新的 OSS legacy 兼容前缀：

/generated-big-fish-assets/*

这样可以同时满足：

1. 与仓库现有 /generated-* 兼容代理体系一致。
2. 不会被前端继续误判成占位图。
3. 后续可继续通过 LegacyAssetPrefix、/api/assets/read-url、ResolvedAssetImage 复用现有链路。

6. SpacetimeDB 语义调整

6.1 Big Fish 资产生成输入补充 asset_url

当前 BigFishAssetGenerateInput 只有：

1. asset_kind
2. level
3. motion_key
4. generated_at_micros

这会导致 procedure 无法知道 API 层是否已经拿到了正式 OSS 兼容路径。

因此本次补充：

1. asset_url: Option<String>

6.2 槽位写入规则

build_generated_asset_slot(...) 改为：

1. 若输入提供 asset_url，则直接写正式路径。
2. 若输入未提供 asset_url，才回退为 /generated-big-fish/... 占位路径。

这样做的原因是：

1. 允许同一个 Big Fish procedure 兼容“占位生成”和“正式生成”两种调用方式。
2. 不需要为了正式图片再新增一条平行 procedure。

7. Big Fish 与 asset_object 的绑定语义

Big Fish 不新增专门资产表，继续复用：

1. asset_object
2. asset_entity_binding

绑定原则：

1. entity_kind 使用 Big Fish 会话实体语义。
2. entity_id 使用 session_id。
3. slot 使用稳定可重建的槽位名。

推荐槽位命名：

1. level_main_image:level-{n}
2. level_motion:level-{n}:{motion_key}
3. stage_background

这样做可以：

1. 与 big_fish_asset_slot 一一对应。
2. 让后续真正做“重新生成覆盖旧资产”时有稳定槽位。

8. 前端识别语义

当前 BigFishResultView 仍用路径前缀判断是否为占位图：

1. 包含 /generated-big-fish/ -> 占位已生成
2. 否则 -> 已生成

本轮先保留这个最小判定方式，原因是：

1. 正式图片会改走 /generated-big-fish-assets/。
2. 前端无需立即扩 contract 字段也能正确显示状态。

长期建议仍然是给 Big Fish 资产槽位补显式来源字段，但这不阻塞本轮正式出图。

9. 本轮验收标准

完成后需要满足：

1. big_fish_generate_level_main_image 会实际触发模型生成，并返回正式 Big Fish 图片。
2. big_fish_generate_level_motion 会实际触发模型生成，并返回静态动作预览图。
3. big_fish_generate_stage_background 会实际触发模型生成，并返回正式背景图。
4. SpacetimeDB 中对应 big_fish_asset_slot.asset_url 不再是 /generated-big-fish/*，而是 /generated-big-fish-assets/*。
5. 结果页状态从“占位已生成”切到“已生成”。
6. /generated-big-fish-assets/* 能通过 Rust 同源代理正确读取 OSS 私有对象。
7. cargo check -p api-server
8. cargo check -p module-big-fish
9. cargo check -p spacetime-module
10. spacetime generate
11. cargo check -p spacetime-client
12. npm run check:encoding

10. 本轮明确暂不做

1. 不做视频动作生成。
2. 不做序列帧 manifest。
3. 不新增 Big Fish 专属资产数据库表。
4. 不把 Big Fish 结果页改成复杂工作流编辑器。
5. 不修改现有占位图路径的兼容职责。