1
This commit is contained in:
@@ -24,4 +24,8 @@
|
||||
|
||||
- PC 端使用更明确的 `xl:grid`、固定信息侧栏和更小间距，让主内容首屏承载更多信息。
|
||||
- 卡片在 PC 端降低无效高度，操作按钮与状态信息尽量同行展示。
|
||||
- 作品卡片底部统计标签必须保留在卡片圆角范围内，不能为了压缩高度让标签贴边或被 `overflow-hidden` 裁掉。
|
||||
- 卡片正文摘要优先缩短行数来给底部标签留空间；当标题、摘要或标签变长时，允许卡片自然增高。
|
||||
- RPG 作品卡片点击行为按作品状态分流：草稿统一继续创作，已发布作品进入详情或世界；不要只依赖 `sourceType` 判断草稿可打开性。
|
||||
- 整张作品卡片需要由卡片根节点承载点击与键盘打开能力，避免透明绝对定位按钮在真实浏览器中被判定不可见，导致自动化和用户点击不稳定。
|
||||
- 保留现有 `platform-*` 视觉体系，避免引入新的 UI 系统。
|
||||
|
||||
@@ -23,3 +23,7 @@
|
||||
- 只需要读一份时，优先看 `PROJECT_WORK_EXPERIENCE_PLAYBOOK`。
|
||||
- 做 UI 改动时，把本目录和根目录的 `UI_CODING_STANDARD.md` 对照着看。
|
||||
- 做运行时流程改动时，把本目录和 `docs/audits/engineering/README.md` 一起看，能更快发现风险边界。
|
||||
|
||||
## 近期专项记录
|
||||
|
||||
- [RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md](./RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md)：记录 RPG 底稿阶段角色主形象与场景背景图并行生成约束。
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# RPG 幕背景默认描述来源修正 2026-04-24
|
||||
|
||||
## 背景
|
||||
|
||||
草稿编辑器中“AI 生成幕背景”的“画面内容描述”曾出现类似“温馨员工宿舍第1幕背景；玩家入职后的首个落脚处；玩家会在温馨员工宿舍接住这一章的开场入口。”的默认文本。这类文本不是大模型直接写出的画面描述，而是前端或后端在缺少 `backgroundPromptText` 时，把地点名、幕标题、摘要规则句拼接出来的兜底文案。
|
||||
|
||||
## 落地约束
|
||||
|
||||
1. 幕背景图的默认画面描述必须来自草稿生成链路里的关键场景生成步骤，字段源为 `landmarks[*].actBackgroundPromptTexts[*]`。
|
||||
2. `sceneChapterBlueprints[*].acts[*].backgroundPromptText` 只承接上述幕级大模型产物，不再用 `title`、`summary`、地点描述或规则句拼接。
|
||||
3. 如果大模型漏产某一幕描述，后端规范化只保留空字符串，让后续生图前的 `backgroundPromptText` 校验暴露底稿质量问题，不能伪造可用默认文本。
|
||||
4. 前端编辑器 sanitize 只展示已有 `act.backgroundPromptText`；缺失时留空，不能在 UI 层重新拼接默认描述。
|
||||
5. 手动打开 AI 生成面板时，若字段为空，可由用户输入，但系统默认不替用户生成规则句。
|
||||
|
||||
## 当前实现
|
||||
|
||||
- `server-rs/crates/api-server/src/custom_world_foundation_draft.rs` 的关键场景框架 prompt 要求 LLM 为每个地点生成 3 条 `actBackgroundPromptTexts`。
|
||||
- 草稿合成阶段通过 `build_scene_chapter_blueprints_from_landmarks` 把这些幕级描述写入 `sceneChapterBlueprints[*].acts[*].backgroundPromptText`。
|
||||
- `normalize_scene_act_blueprint` 不再把缺失描述补成“标题 + 摘要 + 通用场景背景”格式。
|
||||
- `src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx` 不再用地点名、幕标题和 `actSummary` 生成 `backgroundPromptText` fallback。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- 新草稿中每一幕的 `backgroundPromptText` 应该像自然的画面描述，包含主体、前中远景、站位空间、氛围识别点。
|
||||
- 不应再出现“第1幕背景；玩家会在……”这类明显拼接句。
|
||||
- 如果 LLM 漏掉 `actBackgroundPromptTexts`，生成幕背景图阶段应失败并提示缺少 `backgroundPromptText`，而不是静默使用拼接文案。
|
||||
@@ -0,0 +1,32 @@
|
||||
# RPG 底稿图片并行生成说明 2026-04-24
|
||||
|
||||
## 背景
|
||||
|
||||
RPG 草稿生成进入底稿素材阶段后，角色主形象与场景幕背景图都依赖同一份结构化底稿，但二者之间没有数据依赖。旧流程先生成所有角色主形象，再生成场景背景图，导致用户需要串行等待两类图片任务。
|
||||
|
||||
## 落地约束
|
||||
|
||||
1. 角色主形象与场景背景图必须在 API 编排层并行发起，且类内每个角色、每一幕背景也必须同时调用生图接口，不能只做到“角色大类”和“背景大类”并行。这里的场景背景图指 `sceneChapterBlueprints[*].acts[*]` 中每一幕的 `backgroundImageSrc`，不是世界封面图，也不是只按章节或地点生成一张图。
|
||||
2. SpacetimeDB reducer 只负责持久化操作进度和底稿写入，不承载外部 LLM / 图片生成调用。
|
||||
3. 生图前必须已经有文本设定：角色主形象使用角色对象的 `visualDescription`；幕背景图使用对应幕的 `backgroundPromptText`。缺字段时应中断并暴露底稿质量问题，不能退回 `description`、`summary` 或通用兜底词直接生图。
|
||||
4. 并行分支各自基于同一份底稿副本写入素材字段，完成后只合并背景图生成产物字段，避免覆盖角色图片字段或其他草稿内容。
|
||||
5. 单个大类失败仍按原有失败语义终止底稿写入，保留“生成角色主形象失败”和“生成幕背景图失败”的进度提示。
|
||||
|
||||
## 当前实现
|
||||
|
||||
- `server-rs/crates/api-server/src/custom_world.rs` 在 `spawn_custom_world_draft_foundation_job` 中使用 `tokio::join!` 同时执行：
|
||||
- `generate_draft_foundation_role_visuals`
|
||||
- `generate_draft_foundation_act_backgrounds`
|
||||
- 角色分支使用 `JoinSet` 把所有角色主形象任务一次性投递，返回后再按角色位置写入 `imageSrc` 与 `generatedVisualAssetId`。
|
||||
- 背景分支使用 `JoinSet` 把 `sceneChapterBlueprints[*].acts[*]` 的每一幕背景任务一次性投递，返回后写入 `backgroundImageSrc`、`backgroundAssetId`、`generatedScenePrompt`、`generatedSceneModel`。
|
||||
- `merge_generated_act_backgrounds` 只把背景图字段合并回角色分支副本，再进入后续草稿卡编译和 SpacetimeDB 写入。
|
||||
- 幕背景 prompt 同时兼容 `backgroundPromptText`、`scenePromptText`、`visualPromptText`、`promptText`、`imagePromptText`、`backgroundPrompt`、`visualPrompt`，避免 LLM 输出字段别名导致整批背景图被误判缺失。
|
||||
- 每个角色主形象、每一幕背景图都必须独立自动重试，单项最多尝试 3 次。任一单项超过 3 次仍失败时，后台任务必须把 operation 标记为 `failed` 并停止写入草稿卡，避免生成“缺主图 / 缺背景图”的可进入世界档案。
|
||||
- 中止前必须持久化已经成功生成的部分底稿到会话 `draftProfile`，不能因为某个角色或某一幕失败而丢掉其它已生成的 `imageSrc / generatedVisualAssetId / backgroundImageSrc / backgroundAssetId`。
|
||||
- 前端 `CharacterAnimator` 对带 `generatedVisualAssetId` 但尚无 `animationMap` 的自定义角色，所有状态优先渲染生成主图；只有真正发布了动作集后才按动作帧播放，避免运行或战斗状态回落到模板 sprite。
|
||||
|
||||
## 后续注意
|
||||
|
||||
如果后续图片供应商出现强限流，再在网关层做队列或供应商侧限流；不要在 RPG 底稿编排层恢复逐张串行，否则会重新退化成多张图片总耗时累加。
|
||||
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# RPG 角色形象描述数据链路核查 2026-04-24
|
||||
|
||||
## 结论
|
||||
|
||||
草稿生成阶段会让大模型为每个可扮演角色和场景角色生成 `visualDescription`，该字段是角色主形象生成和资产工坊“形象描述”输入框的同一份默认文本来源。
|
||||
|
||||
本次核查发现前端 `normalizeCustomWorldProfileRecord` 曾在规范化 `playableNpcs` / `storyNpcs` 时丢弃 `visualDescription`、`actionDescription`、`sceneVisualDescription`。因此后端草稿 JSON 中有大模型生成的文字，但草稿进入前端编辑器后，资产工坊可能只能回退到 `description`，用户看不到真正的角色形象文字描述。
|
||||
|
||||
## 数据链路
|
||||
|
||||
1. 后端草稿生成：`server-rs/crates/api-server/src/custom_world_foundation_draft.rs`
|
||||
- 角色框架名单 prompt 要求 LLM 输出 `visualDescription`、`actionDescription`、`sceneVisualDescription`。
|
||||
- `visualDescription` 定义为打开角色形象图像生成面板时默认填入的角色形象描述。
|
||||
2. 后端角色主形象生成：`server-rs/crates/api-server/src/custom_world.rs`
|
||||
- `generate_draft_foundation_role_visuals` 从角色对象读取 `visualDescription`。
|
||||
- 缺失时直接失败，提示不能在角色形象设定文本生成前生图。
|
||||
- 生图成功只写回 `imageSrc` 和 `generatedVisualAssetId`，不会覆盖 `visualDescription`。
|
||||
3. 草稿持久化：草稿 profile JSON 保留角色对象字段，`visualDescription` 应与图片字段一起进入保存载荷。
|
||||
4. 前端规范化：`src/data/customWorldLibrary.ts`
|
||||
- `normalizePlayableNpc` / `normalizeStoryNpc` 必须保留三类资产描述字段。
|
||||
5. 资产工坊展示：`src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx`
|
||||
- modal 用角色对象构造 `baseRole`。
|
||||
- `buildDefaultRolePromptBundle(baseRole)` 优先把 `role.visualDescription` 转成 `visualPromptText`。
|
||||
- `RpgCreationRoleVisualSection` 的“形象描述” TextArea 展示 `visualPromptText`。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- 草稿生成完毕后，打开某个角色的资产工坊，应在“形象描述”框看到 LLM 生成的 `visualDescription`。
|
||||
- 如果角色有 `visualDescription`，缓存中的旧 `visualPromptText` 不应覆盖它。
|
||||
- 如果角色缺 `visualDescription`，才允许前端回退到更弱的字段或缓存文本。
|
||||
Reference in New Issue
Block a user