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

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

背景

拼图创作入口不再使用 Agent 对话收集题材锚点。新流程让玩家填写作品名称、作品描述、画面描述三类信息，其中画面描述只服务首关画面生成与关卡画面语义，不再作为作品详情页的作品描述。画面描述支持上传参考图。玩家确认后直接进入草稿生成进度页，后续草稿生成、首图生成、正式图选择、结果页编辑和发布沿用现有后端编排。

入口表单

2026-04-30 初始表单草稿保存补充

1. 玩家在创作页点击“拼图”入口时，前端必须立即创建一个新的拼图 Agent session，并同步生成一条 publicationStatus = draft 的拼图作品卡；此时不触发 compile_puzzle_draft，不生成图片，不进入生成进度页。

2. 新 session 的 seedText 允许为空；SpacetimeDB 侧用空锚点和空表单草稿初始化，不得把默认题材文案写入玩家草稿字段。

3. 初始表单输入自动保存到 session 的 draft_json 与 puzzle_work_profile 投影。保存字段只包含 workTitle、workDescription、pictureDescription、可推断标签和一个 generationStatus = idle 的默认关卡；参考图只保存在当前前端会话内，不落入 SpacetimeDB。

4. 玩家在生成草稿前退出，再次从创作中心点击这条拼图草稿时，必须恢复到填表页，并回填之前自动保存的作品名称、作品描述和画面描述；只有执行 compile_puzzle_draft 且生成结果页草稿后，草稿入口才进入结果页。

5. 表单自动保存走 save_puzzle_form_draft action，不消耗陶泥币，不生成图片，不改变 stage = collecting_anchors；生成草稿按钮仍单独触发 compile_puzzle_draft 并进入进度页。

6. 点击拼图入口始终创建新草稿，不复用上一次未完成 session；恢复旧草稿只通过“我的创作”中的草稿卡进入。

7. 作品名称为必填字段，保存到 workTitle，兼容写入旧 seedText，同时作为作品级 workTitle 的真相源。

8. 作品描述为必填字段，保存到 workDescription，作为作品详情页、作品列表和发布资料中的 summary 真相源。

9. 画面描述为必填字段，保存到 pictureDescription，只作为首关画面生成 prompt、首关 pictureDescription 和关卡命名输入，不再覆盖作品描述。

10. 参考图为可选字段，保存到 referenceImageSrc。表单支持本地图片上传为 Data URL；草稿首图生成时直接传入现有拼图图生图接口。

11. 表单确认后前端先创建拼图 session，再立即执行 compile_puzzle_draft，并传入 promptText = pictureDescription、referenceImageSrc。

12. 表单提交 payload 需要在前端创作流程中暂存，生成进度页失败重试时必须继续携带同一份作品名称、作品描述、画面描述与参考图。

13. 生成进度页的“当前拼图信息”必须优先读取这份表单 payload，而不是读取 session 中旧 Agent 锚点或编译后的关卡名，避免用户确认后看到的标题、作品描述、画面描述发生漂移。

14. compile_puzzle_draft action 必须显式携带 workTitle、workDescription、pictureDescription、promptText 与 referenceImageSrc。seedText 只作为 SpacetimeDB 旧表结构兼容载体，不能成为前端生成页展示和失败重试的唯一来源。

15. 入口不再展示拼图 Agent 聊天气泡、快捷补齐或多锚点卡片；新建拼图时必须清空旧 session，只有从当前生成进度页返回表单时保留本轮内容。

锚点映射

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

新字段	落地字段	说明
作品名称	themePromise.value、workTitle、旧 levelName 兼容字段、creatorIntent.themePromise	作为作品名称与题材承诺真相源
作品描述	workDescription、旧 summary 兼容字段	作为作品详情页描述、列表描述和发布描述真相源
画面描述	visualSubject.value、levels[0].pictureDescription、首图 promptText	作为首关画面主体、首图生成 prompt 和首关关卡命名输入

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

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

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

草稿数据结构

拼图草稿从单关卡字段升级为作品级信息与关卡列表并存：

1. PuzzleResultDraft.workTitle：作品名称，旧 levelName 只作为兼容字段同步为当前主关卡名称或作品名称。
2. PuzzleResultDraft.workDescription：作品描述，旧 summary 只作为兼容字段同步为作品描述。
3. PuzzleResultDraft.themeTags：作品标签，仍限制 3 到 6 个。
4. PuzzleResultDraft.levels[]：关卡列表。每个关卡包含 levelId、levelName、pictureDescription、candidates、selectedCandidateId、coverImageSrc、coverAssetId、generationStatus。
5. 首次草稿生成时必须创建一个默认关卡，levelId = puzzle-level-1，pictureDescription = 表单画面描述，首图生成后直接写入该关卡。
6. 关卡名称由后端基于画面描述和图片语义输入生成；无可用语义时按题材标签与序号兜底，禁止继续直接使用作品名称作为关卡名称。
7. 旧草稿或旧作品缺少 levels 时，读取层必须由旧 levelName、summary、coverImageSrc、candidates 补出一个兼容关卡，避免历史草稿无法打开。

后端编译

1. CreatePuzzleAgentSessionRequest 新增 workTitle、workDescription、pictureDescription 与 referenceImageSrc，但不改 SpacetimeDB 表结构。
2. api-server 创建 session 时把作品名称、作品描述和画面描述合成 seedText 传入 SpacetimeDB；SpacetimeDB reducer 只做确定性锚点生成，不接触图片或外部服务。
3. compile_puzzle_draft_with_initial_cover 新增首图 prompt 和参考图参数。若前端传入画面描述，则首图生成直接使用这段文本；若传入参考图，则走现有 DashScope 图生图链路；生成结果写入默认第一关。
4. 首图文生图 prompt 由 api-server 拼接固定拼图约束后统一压缩到 500 字符以内，避免玩家长画面描述触发 DashScope 参数非法；进度页和结果页仍展示玩家原始画面描述，不展示压缩后的内部 prompt。
5. 图片生成仍在 api-server 内完成，遵守 SpacetimeDB reducer 不做网络 I/O 的约束。
6. 参考图以 Data URL 进入 POST /api/runtime/puzzle/agent/sessions 和 POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions，这两条路由必须单独放宽 JSON body 上限；不要放大全局默认 body limit。
7. 前端仍应优先压缩参考图；后端 body 上限只用于容纳合理尺寸的单张参考图，超大原图不应直接落入 SpacetimeDB 或作为作品字段持久化。
8. 作品更新接口 PUT /api/runtime/puzzle/works/{profileId} 必须支持作品信息和关卡列表一起写入，前端自动保存不得只写旧单关字段。
9. StartPuzzleRunRequest 新增可选 levelId。详情页或草稿结果页单独体验某关时传入目标关卡，后端从作品/草稿的 levels 中选取该关卡生成运行态。
10. ExecutePuzzleAgentActionRequest 必须保留 pictureDescription 字段。表单直达生成时，compile_puzzle_draft 优先用 pictureDescription 作为首图 prompt，再回退到旧 promptText；避免生成页展示的是玩家画面描述，但后端实际用作品名称或旧摘要出图。
11. compile_puzzle_draft 中的图片上游失败不得映射成 400 BAD_REQUEST。DashScope 返回 InvalidParameter 或任务失败时，api-server 统一按 502 UPSTREAM_ERROR 暴露，并在 details.message 中保留“拼图图片生成失败：...”的业务原因，避免生成页只显示“请求参数不合法”。
12. compile_puzzle_draft 前置陶泥币预扣失败不得映射成 400 BAD_REQUEST。余额不足返回 409 CONFLICT，SpacetimeDB procedure 不可用、绑定不匹配、钱包服务异常等统一按 502 UPSTREAM_ERROR 暴露，并在 details.message 中保留真实钱包错误。

结果页

拼图草稿结果页分为两个 Tab：

1. 拼图关卡列表：默认展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、重新生成画面，并支持单独体验该关卡。
2. 作品信息：展示并编辑作品名称、作品描述、作品标签。

画面描述区域不再展示候选图实际 prompt 或“请生成一张适合……”之类内部提示词模块。参考图入口保留在画面描述编辑区域内，便于重新生成时继续带入。结果页编辑关卡画面描述时只同步该关卡 pictureDescription；作品描述只在作品信息 Tab 编辑，作品详情页不得再回退使用画面描述。

验收

1. 从拼图创作入口只能看到作品名称、作品描述、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择。
3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图；作品详情页展示玩家作品描述。
4. 结果页包含“拼图关卡”和“作品信息”两个 Tab；关卡列表默认至少一关，支持新增、删除和进入关卡详情。
5. 关卡详情页支持重新生成画面和单独体验该关卡。
6. 发布、作品测试、自动保存作品名称、作品描述、作品标签和关卡列表仍可用。