# 拼图填表式创作流程改造 2026-04-29

## 背景

拼图创作入口不再使用 Agent 对话收集题材锚点。新流程只让玩家填写两个字段：拼图标题、画面描述。画面描述支持上传参考图。玩家确认后直接进入草稿生成进度页，后续草稿生成、首图生成、正式图选择、结果页编辑和发布沿用现有后端编排。

## 入口表单

1. 拼图标题为必填字段，保存到 `seedText`，同时作为 `levelName` 的优先来源。
2. 画面描述为必填字段，保存到 `pictureDescription`，同时作为 `summary` 和首图生成 prompt 的优先来源；支持多行文本，后端解析不得截断首行之后的内容。
3. 参考图为可选字段，保存到 `referenceImageSrc`。表单支持本地图片上传为 Data URL；草稿首图生成时直接传入现有拼图图生图接口。
4. 表单确认后前端先创建拼图 session，再立即执行 `compile_puzzle_draft`，并传入 `promptText = pictureDescription`、`referenceImageSrc`。
5. 表单提交 payload 需要在前端创作流程中暂存，生成进度页失败重试时必须继续携带同一份画面描述与参考图。
6. 入口不再展示拼图 Agent 聊天气泡、快捷补齐或多锚点卡片；新建拼图时必须清空旧 session，只有从当前生成进度页返回表单时保留本轮内容。

## 锚点映射

拼图模式锚点收口为两个玩家输入源：

| 新字段 | 落地字段 | 说明 |
| --- | --- | --- |
| 拼图标题 | `themePromise.value`、`levelName`、`creatorIntent.themePromise` | 作为题材承诺与关卡名称的真相源 |
| 画面描述 | `visualSubject.value`、`summary`、首图 `promptText` | 作为画面主体与生图 prompt 的真相源 |

兼容旧结构时仍保留 `visualMood`、`compositionHooks`、`tagsAndForbidden` 字段，但它们不再由 Agent 问答收集：

1. `visualMood` 固定标记为系统推断，值为“清晰、适合拼图切块”。
2. `compositionHooks` 固定标记为系统推断，值为“主体轮廓、色块分区、局部细节”。
3. `tagsAndForbidden` 根据拼图标题和画面描述生成 3 到 6 个题材标签；禁忌只保留通用图像约束，不写入 UI。

生成进度页的“当前拼图信息”只展示玩家输入锚点：拼图标题、画面描述。题材标签仅作为草稿结果页内容展示，不在进度页混入旧五锚点结构。

## 后端编译

1. `CreatePuzzleAgentSessionRequest` 新增 `pictureDescription` 与 `referenceImageSrc`，但不改 SpacetimeDB 表结构。
2. api-server 创建 session 时把标题和画面描述合成 `seedText` 传入 SpacetimeDB；SpacetimeDB reducer 只做确定性锚点生成，不接触图片或外部服务。
3. `compile_puzzle_draft_with_initial_cover` 新增首图 prompt 和参考图参数。若前端传入画面描述，则首图生成直接使用这段文本；若传入参考图，则走现有 DashScope 图生图链路。
4. 图片生成仍在 api-server 内完成，遵守 SpacetimeDB reducer 不做网络 I/O 的约束。

## 结果页

拼图草稿结果页不再区分 Tab，合并为一个可滚动列表页，内容顺序固定为：

1. 关卡名称。
2. 画面预览。
3. 画面描述。
4. 重新生成画面按钮。
5. 题材标签。

画面描述区域不再展示候选图实际 prompt 或“请生成一张适合……”之类内部提示词模块。参考图入口保留在画面描述编辑区域内，便于重新生成时继续带入。结果页编辑画面描述时必须同步更新 `summary`，确保自动保存、作品测试、发布和重新生成画面使用同一份描述。

## 验收

1. 从拼图创作入口只能看到标题、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择。
3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图。
4. 结果页为单列表，顺序符合上文要求，不展示 Tab 和内部实际 prompt。
5. 发布、作品测试、自动保存标题、画面描述和标签仍可用。