1

docs/experience/BIG_FISH_DRAFT_GENERATION_CHAIN_FIX_2026-04-28.md

@@ -0,0 +1,80 @@
+# 大鱼吃小鱼草稿生成链路修复 2026-04-28
+
+## 背景
+
+大鱼吃小鱼玩法的结果页已经具备等级卡、主图工坊、动作工坊和背景工坊，但当前 `big_fish_compile_draft` 只是把锚点交给 `module-big-fish` 的 `compile_default_draft(...)` 做静态模板拼装。
+
+这会导致两个直接问题：
+
+1. 草稿编译虽然能成功进入结果页，但每一级实体只会拿到非常概括的模板文本，无法真正产出“实体名称、文字描述、形象描述、待机动作描述、移动动作描述”这一组首稿。
+2. 主图和动作工坊默认提示词没有绑定到一份足够细的草稿真相源，动作面板只能看到合并后的 `motionPromptSeed`，会表现成“草稿生成一带而过，所有内容都没有正常生成”。
+
+## 本次修复口径
+
+### 1. 每级等级蓝图必须补齐的文本字段
+
+大鱼吃小鱼每一级 `level blueprint` 在保留原有字段的同时，新增并持久化下面这些文本真相：
+
+1. `textDescription`
+   - 当前等级实体的正文文字描述。
+   - 用于结果页等级卡和后续重生成时的人类可读设定底稿。
+2. `visualDescription`
+   - 当前等级实体的形象描述。
+   - 主图工坊默认输入内容直接取这份字段。
+3. `idleMotionDescription`
+   - 当前等级待机动作描述。
+   - `idle_float` 动作工坊默认输入内容直接取这份字段。
+4. `moveMotionDescription`
+   - 当前等级移动动作描述。
+   - `move_swim` 动作工坊默认输入内容直接取这份字段。
+
+### 2. 默认提示词流转规则
+
+草稿生成、结果页工坊和正式资产生成统一按下面口径流转：
+
+1. 草稿编译阶段先产出上述结构化文本字段。
+2. 主图工坊默认文案：
+   - 优先显示 `visualDescription`
+   - `visualPromptSeed` 作为主图正式生图提示词的冻结快照，可由 `visualDescription` 组合生成
+3. 动作工坊默认文案：
+   - `idle_float` 优先显示 `idleMotionDescription`
+   - `move_swim` 优先显示 `moveMotionDescription`
+   - `motionPromptSeed` 继续保留为动作方向总提示词摘要，但具体动作正式生图必须显式拼入动作位对应描述
+4. 草稿阶段生成的正式主图、动作图和后续重生成，都只能读取同一份 `draft.levels[*]` 真相，前端不得本地拼接新的设定文案。
+
+### 3. 编译策略
+
+`big_fish_compile_draft` 需要升级为：
+
+1. `api-server` 先调用 LLM 做结构化草稿编译。
+2. 若 LLM 成功，则把完整 `draft_json` 写回 SpacetimeDB。
+3. 若 LLM 不可用、返回非法 JSON 或字段缺失，则退回 `compile_default_draft(...)` 的 deterministic fallback。
+
+这样可以同时保证：
+
+1. 正常环境下草稿不再只是模板壳。
+2. 模型偶发失败时不会打断结果页主链。
+3. SpacetimeDB reducer 不承担外部网络调用，仍然符合后端边界。
+
+## 落地范围
+
+本次修复涉及：
+
+1. `server-rs/crates/module-big-fish`
+2. `server-rs/crates/spacetime-module`
+3. `server-rs/crates/spacetime-client`
+4. `server-rs/crates/shared-contracts`
+5. `server-rs/crates/api-server`
+6. `packages/shared/src/contracts/bigFish.ts`
+7. `src/components/big-fish-result/BigFishResultView.tsx`
+
+## 验收口径
+
+修复后需要满足下面这些观察结果：
+
+1. 点击“生成草稿”后，`draft.levels[*]` 不再只有空泛模板，而是每级都带名称、文字描述、形象描述、待机动作描述、移动动作描述。
+2. 打开主图工坊时，默认文本来自当前等级的 `visualDescription`。
+3. 打开待机动作工坊时，默认文本来自当前等级的 `idleMotionDescription`。
+4. 打开移动动作工坊时，默认文本来自当前等级的 `moveMotionDescription`。
+5. 资产槽位 `promptSnapshot` 与对应动作位 / 主图位的默认提示词一致。
+6. LLM 不可用时仍然能生成一版可用 fallback 草稿，而不是直接报错或写入空草稿。