# 大鱼吃小鱼草稿生成链路修复 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 草稿，而不是直接报错或写入空草稿。