1

docs/technical/CUSTOM_WORLD_ASSET_PROMPT_DEFAULTS_2026-04-24.md

@@ -0,0 +1,54 @@
+# 自定义世界资产 Prompt 与默认描述配置说明（2026-04-24）
+
+## 1. 目标
+
+本说明记录生成世界草稿时，角色形象图像、角色动作视频、每一幕场景背景图像三类资产的默认描述与正式模型 prompt 的配置位置，避免后续继续误改旧 `server-node` 链路。
+
+## 2. 世界草稿默认描述字段
+
+生成世界草稿时，后端会要求模型在角色与幕级剧情结构阶段直接产出资产默认描述字段：
+
+- 角色：`visualDescription`，用于打开角色形象图像生成面板时默认填入角色形象描述框。
+- 角色：`actionDescription`，用于打开角色动作视频生成面板时默认填入各动作描述框；当前每个动作会从同一角色默认动作描述起步，用户切换动作后可分别编辑并缓存。
+- 每一幕：`sceneChapterBlueprints[*].acts[*].backgroundPromptText`，用于打开该幕背景图像生成面板时默认填入场景描述框。
+- 场景：`visualDescription` 只作为旧场景图或没有幕级描述时的兜底，不再从角色 AI 形象生成面板维护场景背景描述。
+
+草稿生成契约位置：
+
+- `server-rs/crates/api-server/src/custom_world_foundation_draft.rs`
+  - `build_custom_world_role_outline_batch_prompt`
+  - `build_custom_world_landmark_seed_batch_prompt`
+  - `build_foundation_draft_user_prompt`
+  - `normalize_scene_act_blueprint`
+
+前端默认框映射位置：
+
+- `src/prompts/customWorldRolePromptDefaults.ts`
+  - `visualPromptText` 优先取 `role.visualDescription`。
+  - `animationPromptText` 优先取 `role.actionDescription`。
+- `src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx`
+  - 角色形象与动作工坊初始化默认文本。
+  - `animationPromptTextByKey` 负责分动作保存动作描述。
+  - 当角色本身已有 `visualDescription/actionDescription` 时，必须优先使用这批世界草稿新生成字段，不能让旧 workflow cache 覆盖当前草稿默认文本。
+- `src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx`
+  - 幕背景图像生成弹窗优先使用 `act.backgroundPromptText`。
+  - 普通场景图像生成弹窗仍可使用 `landmark.visualDescription` 兜底。
+
+## 3. 正式模型 Prompt 配置
+
+正式生成图片或视频时，不直接使用默认描述字段作为完整 prompt，而是在 `server-rs` 继续编译：
+
+- 角色主图：`server-rs/crates/api-server/src/custom_world_asset_prompts.rs`
+  - `build_character_visual_prompt`
+  - 内部使用 `build_master_prompt`
+- 角色动作视频：`server-rs/crates/api-server/src/custom_world_asset_prompts.rs`
+  - `build_character_animation_prompt`
+  - 图生视频分支使用 `build_video_action_prompt`
+- 场景背景图：`server-rs/crates/api-server/src/custom_world_ai.rs`
+  - `build_custom_world_scene_image_prompt`
+
+## 4. 当前约束
+
+- 不再把 `server-node/src/prompts/characterAssetPrompts.ts` 作为主链修改目标。
+- 默认描述字段必须由世界草稿生成阶段写入，前端只负责把字段填入输入框并允许用户编辑。
+- UI 不默认展示规则解释文案，正式约束只进入后端 prompt。