3.5 KiB
世界结果页新增场景与 NPC 生成修复
背景
世界结果页在 Agent 草稿模式下点击“新增场景角色”和“新增场景”时，会走 api-server 的 generate_characters / generate_landmarks 动作：
api-server根据当前draft_profile请求 LLM 生成新增实体。spacetime-module将generatedCharacters / generatedLandmarks写回draft_profile。- 结果页从服务端
resultPreview.preview读取最新世界 profile。
问题
LLM 扩展提示词为了草稿卡片简洁，只要求返回角色的 publicMask / hiddenHook / relationToPlayer / summary，以及场景的 purpose / mood / secret / summary / characterIds。
但结果页与运行时 CustomWorldProfile 读取的是当前完整字段：
- NPC：
description / backstory / personality / motivation / relationshipHooks / tags / initialAffinity - 场景：
description / sceneNpcIds / connections
因此新增实体即使后端动作成功，也可能因为字段缺失或关联字段名不一致，在结果页表现为“生成后没有可用内容 / 场景没有 NPC 关联”。
此外，Agent 结果页生成回调原本只返回 void：当 activeAgentSessionId 失效、服务端没有返回最新 resultPreview，或最新 profile 没有新增实体时，前端只会结束 pending 动画，表现为“点击后闪一下就消失”。
修复方案
本次修复保持“前端只表现，后端负责数据整理”的边界：
- 在
api-server生成实体归一化阶段补齐结果页需要的最小完整字段。 - NPC 将
publicMask / summary映射为description，hiddenHook映射为backstory / motivation，relationToPlayer进入relationshipHooks。 - 场景将
summary / purpose / mood / secret合成description，将characterIds转为sceneNpcIds。 - 保留 LLM 已返回的字段，不覆盖更完整的结构化结果。
- 增加后端单元测试锁定新增 NPC 与场景的 profile 字段契约。
- 前端 Agent 生成回调返回最新 profile；如果没有可用会话或最新 profile 未增加对应实体，结果页显示明确错误，不再静默消失。
验收
generate_characters的 payload 中新增角色必须包含非空description与可用relationshipHooks。generate_landmarks的 payload 中新增场景必须包含非空description，并能把characterIds落为sceneNpcIds。- 结果页继续只消费
resultPreview.preview，不新增前端本地编译分支。 - 结果页点击新增实体后，如果服务端没有回传新增内容，必须展示错误提示。
2026-04-24 追加：可扮演角色结果页空刷新修复
新增可扮演角色报“生成请求已完成，但结果页未收到新增内容”的根因是：api-server 已经把 LLM 生成结果注入 generatedCharacters，但 spacetime-module 缺少 generate_characters / generate_landmarks 的真实落库 executor，action 会进入分派却无法把新增内容写入 draft_profile_json 与 result_preview_json。
本次补齐 SpacetimeDB module executor：
generate_characters(roleType=playable)写入draftProfile.playableNpcs。generate_characters(roleType=story)写入draftProfile.storyNpcs。generate_landmarks写入draftProfile.landmarks。- 每个新增实体同步生成 draft card，并刷新
publish_gate_json / result_preview_json / checkpoints_json / operation / message。
结果页仍只消费服务端 resultPreview.preview；前端不会本地伪造新增角色。