# 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`，才允许前端回退到更弱的字段或缓存文本。