# 自定义世界资产 Prompt 与默认描述配置说明（2026-04-24）

## 1. 目标

本说明记录生成世界草稿时，角色形象图像、角色动作视频、每一幕场景背景图像三类资产的默认描述与正式模型 prompt 的配置位置，避免后续继续误改旧 `server-node` 链路。

## 2. 世界草稿默认描述字段

生成世界草稿时，后端会要求模型在角色与幕级剧情结构阶段直接产出资产默认描述字段：

- 角色：`visualDescription`，用于打开角色形象图像生成面板时默认填入角色形象描述框。
- 角色：`actionDescription`，用于打开角色动作视频生成面板时默认填入各动作描述框；当前每个动作会从同一角色默认动作描述起步，用户切换动作后可分别编辑并缓存。
- 角色：`sceneVisualDescription`，用于描述角色常出现或关联的场景画面。三个角色默认描述字段必须在角色 outline 阶段同一次模型调用中产出；若模型遗漏，只允许后端本地兜底补字段，不再额外发起独立修复模型调用。
- 每一幕：`sceneChapterBlueprints[*].acts[*].backgroundPromptText`，用于打开该幕背景图像生成面板时默认填入场景描述框。
- 场景：`visualDescription` 只作为旧场景图或没有幕级描述时的兜底，不再从角色 AI 形象生成面板维护场景背景描述。
- 场景：`actNPCNames`、`connectedLandmarkNames`、`entryHook` 必须在关键场景生成阶段同一次模型调用中产出，并由原场景解析链路写入 `landmarks` 与幕级 `primaryNpcId / oppositeNpcId / encounterNpcIds`；不再使用独立的场景网络补全提示词。旧草稿中的 `sceneNpcNames` 仅作为兼容读取兜底，不作为新生成字段。

草稿生成契约位置：

- `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`
  - 只拼入用户可见的 `promptText` / `visualPromptText`，不再拼入 `characterBriefText` 或角色摘要字段。
- 角色动作视频：`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。

## 5. 自动草稿素材回写约束

- 世界草稿自动素材生成与草稿页手动生成使用同一套 `server-rs/crates/api-server/src/custom_world_ai.rs` 场景图接口和 OSS/SpacetimeDB 资产持久化链路。
- 自动批量生成幕背景时，后端必须把已成功生成的 `backgroundImageSrc/backgroundAssetId/generatedScenePrompt/generatedSceneModel` 写回 `sceneChapterBlueprints[*].acts[*]`，不能因为同批某一幕失败而丢弃已成功图片。
- 某一幕连续重试仍失败时，只允许在该幕写入 `backgroundGenerationError` 作为诊断字段；只要至少一幕成功，草稿仍应完成并让前端展示成功图片。
- 只有全部幕背景均失败时，才把“生成幕背景图失败”作为草稿素材阶段失败原因保存。
- Rust 服务实际生图模型读取 `DASHSCOPE_SCENE_IMAGE_MODEL` / `DASHSCOPE_COVER_IMAGE_MODEL` / `DASHSCOPE_REFERENCE_IMAGE_MODEL`；兼容旧 `DASHSCOPE_IMAGE_MODEL`，避免 `.env.example` 中配置了模型但服务端仍使用硬编码模型。
- 自动草稿幕背景不能把 `backgroundPromptText` 直接作为最终 `prompt` 传给 DashScope；它必须像草稿页手动生成一样，把幕级描述作为 `userPrompt`，并用同一个地点对象的 `name/description` 作为场景上下文，再由 `build_custom_world_scene_image_prompt` 统一拼入世界名、世界摘要、风格、玩家目标、场景名、场景描述和负面词。用户不修改默认描述直接点生成时，手动生成与自动草稿生成的正式生图上下文必须一致。
- 自动草稿幕背景的默认尺寸必须与草稿页手动生成默认尺寸一致，当前统一为 `1280*720`；不能在自动链路中单独改成 `1600*900`，否则同一 prompt 在同一模型下也可能因供应商尺寸支持或耗时不同而表现不一致。
- 批量自动生图失败日志必须保留 `AppError.details.message` 中的供应商真实原因，不能只记录 `AppError.message()` 的 HTTP 泛化文案，否则排查时只能看到“上游服务请求失败”，无法确认是尺寸、模型、限流、超时还是内容审核失败。