GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

1

Browse Source
This commit is contained in:
高物
2026-04-23 06:01:00 +08:00
parent 9dc56f0fc0
commit f6046ef658
123 changed files with 7752 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
docs/technical/BIG_FISH_ASSET_PLACEHOLDER_PREVIEW_FIX_2026-04-23.md Normal file
View File

@@ -0,0 +1,134 @@
# 大鱼吃小鱼结果页主图占位预览修复说明 2026-04-23
日期：`2026-04-23`
## 1. 问题现象
在“深海谜境 / 大鱼吃小鱼”结果页中，等级卡片会显示：
1. `主图 已生成`
2. 操作后会出现“已应用主图”感知
但实际结果页看不到角色主图，卡片里只有一张蓝色底图。
## 2. 排查结论
本次沿着“结果页展示 -> API action -> SpacetimeDB procedure -> 资产路径”全链检查后确认：
1. 前端确实成功触发了 `big_fish_generate_level_main_image`
2. SpacetimeDB 侧确实把资产槽位状态写成了 `ready`
3. 但这条链路没有接真实图像模型，也没有接 OSS 真实资产对象
4. 旧实现只回写一个 `/generated-big-fish/...png` 占位 URL
5. 同时仓库里没有实际把这张占位图写到 `public/generated-big-fish/...`
6. 因此前端读到的是一个“看起来像图片地址、实际上没有真实文件”的路径
7. `<img>` 加载失败后，卡片底层蓝色渐变背景暴露出来，于是用户只能看到蓝色图块
## 3. 根因拆解
### 3.1 状态成功过早
`generate_big_fish_asset` 当前最小实现只负责：
1. 写 `asset slot`
2. 写 `prompt snapshot`
3. 标记 `status = ready`
它并不代表真实主图已经生成完成。
### 3.2 预览资源未真正落盘
旧实现会构造：
`/generated-big-fish/{asset_kind}/{level_part}/{seed}.png`
但没有同步在 `public/generated-big-fish/...` 写出对应文件。
### 3.3 结果页直接吃裸 `assetUrl`
Big Fish 结果页主图卡之前直接：
1. 取 `slot.assetUrl`
2. 塞进 `<img src=...>`
一旦文件不存在，就只剩下卡片自己的蓝色渐变背景。
### 3.4 UI 文案误导
旧文案把当前阶段写成：
1. `已生成`
2. `已生成并设为正式资产`
这会让用户自然理解为“真实主图已经出来了”，与当前最小实现不一致。
## 4. 本次修复策略
本轮不直接接真实模型生成，而是先把最小可见闭环补完整。
### 4.1 API action 写出可预览占位图
在 Rust `api-server` 的 Big Fish action 处理中：
1. 复用拼图玩法“写本地可预览占位图”的方式
2. 在调用 `generate_big_fish_asset` 之前，先把 Big Fish 占位图真正写到：
`public/generated-big-fish/...`
3. 保证 SpacetimeDB 里写入的占位 URL 至少对应一个真实可访问文件
### 4.2 结果页改用统一图片渲染组件
Big Fish 结果页主图和背景预览改为：
1. 使用 `ResolvedAssetImage`
2. 统一走现有图片渲染链路
3. 避免后续接 OSS / 旧 generated 路径兼容时再重复返工
### 4.3 状态文案改准
当前还是占位资产阶段，因此把结果页状态文案改为：
1. `占位已生成`
2. `生成并应用占位图`
避免继续把“槽位 ready”误说成“真实主图已完成”。
### 4.4 结果页露出背景预览
除了等级主图卡，本轮顺手把场地背景卡也接上真实预览图渲染，避免出现：
1. 状态显示完成
2. 右侧仍只是一块纯渐变底图
## 5. 修复后的链路语义
修复后 Big Fish 当前资产链路语义明确为：
1. 点击生成
2. `api-server` 先写出本地可访问占位图
3. `spacetime-module` 写正式资产槽位和提示词快照
4. 前端读取 `assetUrl` 并真实渲染预览
也就是说：
1. 当前可以保证“用户看得见”
2. 但仍然不是“真实模型图像生成”
3. 后续真实模型 / OSS worker 接入后，再把占位图链替换成正式资产真相链
## 6. 验收标准
本次修复后需要满足：
1. 结果页等级卡在主图生成后能直接看到真实可加载图片，不再只剩蓝色底图
2. 场地背景生成后右侧卡片能看到真实可加载图片
3. Big Fish 结果页图片渲染统一走现有图片组件，不再直接裸 `<img>` 吃易失路径
4. 当前 UI 文案不再把占位图误称为真实主图
5. 若本地占位图写盘失败，则 action 不能继续回到“ready 成功”状态
## 7. 后续建议
下一阶段继续补 Big Fish 真实资产链时，建议按下面顺序推进：
1. 先引入 Big Fish `asset_object + asset_entity_binding` 正式槽位设计
2. 再接真实图片 / 动作生成 worker
3. 最后把当前 `/generated-big-fish/...` 本地占位路径迁为兼容层，而不是继续作为真相路径

6
docs/technical/BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
View File

@@ -11,14 +11,14 @@
1. 平台创作入口选择大鱼吃小鱼玩法
2. Agent 会话创建、消息提交和 SSE 兼容返回
3. 基于 4 个高杠杆锚点编译玩法草稿
4. 结果页生成等级主图、等级动作、场地背景的正式资产槽位
4. 结果页生成等级主图、等级动作、场地背景的正式资产槽位，并同步提供可预览资源
5. 发布校验
6. 启动测试运行态
7. 后端推进摇杆输入、刷怪、吞噬收编、三合一、屏外清理和胜负裁决
## 2. 本轮明确不做
1. 不接入真实图片 / 动作模型调用，只生成可预览的占位资产引用与冻结提示词快照。
1. 不在本文件内展开正式图片模型链、OSS 真相链和占位兼容层的细节；相关正式出图方案以 `BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md` 为准。
2. 不新增 WebSocket 依赖；首版运行态使用 `POST input + GET snapshot` 的有限 HTTP 辅助接口，后续再升级长连接。
3. 不把 Big Fish 写回 `custom_world`、`rpgCreation` 或 RPG runtime 旧语义。
4. 不新增作品市场、排行榜、复盘、局外成长、PvP。
@@ -141,7 +141,7 @@
说明：
1. `submit_big_fish_message` 只做 deterministic 锚点补全，不调用 LLM。
2. `generate_big_fish_asset` 只写正式资产槽位和提示词快照，真实模型生成后续由 AI/OSS worker 替换。
2. `generate_big_fish_asset` 的槽位写入语义允许 `api-server` 传入正式 `asset_url`；若未传则回退为占位路径，保证最小链与正式链共存。
3. `submit_big_fish_input` 每次至少推进 1 个后端 tick，前端不能本地裁决。
4. 运行态所有“持续时间”语义按真实秒数累计，前端即使摇杆静止也要持续以当前输入心跳驱动后端推进，避免刷怪与屏外 `3` 秒清理依赖手速或提交频率。

168
docs/technical/BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md Normal file
View File

@@ -0,0 +1,168 @@
# 大鱼吃小鱼正式图片生成接入方案 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. 不修改现有占位图路径的兼容职责。

2
docs/technical/README.md
View File

@@ -56,6 +56,8 @@
- [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md)：冻结 `M5` Agent `message submit / operation query` 的 deterministic 最小闭环，明确同步写入 user/assistant 消息、`process_message` operation 与 session 进度推进规则。
- [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md)：冻结 `M5` Agent `/messages/stream` 的最小兼容 SSE facade，明确复用 Stage 7 的同步写表逻辑，只输出当前前端真实消费的 `reply_delta / session / done / error` 事件。
- [BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md](./BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md)：冻结大鱼吃小鱼玩法本轮最小完整落地方案，明确 `module-big-fish`、SpacetimeDB 表 / procedure、Axum facade、前端接入和运行态规则边界。
- [BIG_FISH_ASSET_PLACEHOLDER_PREVIEW_FIX_2026-04-23.md](./BIG_FISH_ASSET_PLACEHOLDER_PREVIEW_FIX_2026-04-23.md)：记录大鱼吃小鱼结果页“状态成功但只看到蓝色底图”的根因，冻结占位图真实写盘、结果页预览渲染与文案收口方案。
- [BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md](./BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md)：冻结 Big Fish 从“占位可见”升级到“模型正式出图”的 Rust 落地方案，明确复用 DashScope + OSS + `asset_object` 真相链、新的 `/generated-big-fish-assets/*` 兼容路径，以及 Big Fish 槽位写入语义调整。
- [PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md](./PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md)：冻结拼图玩法本轮最小完整落地方案，明确 `module-puzzle`、SpacetimeDB 表 / procedure、Axum facade、前端接入，以及交换 / 合并 / 拖动 / 拆分 / 下一关推荐边界。
- [UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md](./UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md)：冻结所有创作品类 Agent 聊天 UI 与对话进度管理统一框架，明确品类差异只保留锚点映射、提示词/话术和 action。
- [RUST_API_SERVER_SSE_INFRASTRUCTURE_DESIGN_2026-04-22.md](./RUST_API_SERVER_SSE_INFRASTRUCTURE_DESIGN_2026-04-22.md)：冻结 `server-rs/crates/api-server` 的 SSE 使用口径，明确统一使用 Axum 内建 `Sse<Event>`，不再保留自定义 `sse.rs` 模块。