Genarrative/docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md

拼图填表式创作流程改造 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. 发布、作品测试、自动保存标题、画面描述和标签仍可用。