Genarrative/docs/audits/CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md

角色资产 Prompt 链路审计（2026-04-20）

更新时间：2026-04-20

0. 本次审计回答什么问题

本次只回答角色资产相关的 4 个问题：

1. characterAssetPrompts.ts 里的 visualPromptText 和 animationPromptText，是不是“生成角色形象 / 动作形象的默认描述”。
2. 生成角色形象的系统提示词在哪个文件，生成默认角色形象描述文本的提示词在哪个文件。
3. 生成角色动作的系统提示词在哪个文件，生成默认角色动作描述文本的提示词在哪个文件。
4. 当前链路里是否存在冗余流程、保留接口或无效代码。

---

1. 先说结论

结论不是“只有一套 prompt”，而是：

当前角色资产链路仍然有两层 prompt，但“默认描述文本”已经统一成单一主源。

1.1 默认描述文本层

这层的目标是：

先给资产工坊里的输入框一个默认可编辑文本。

这层不直接拿去生成图片或动作视频。

当前实际主链来源：

• src/prompts/customWorldRolePromptDefaults.ts

它会把角色已有字段映射成：

• visualPromptText
• animationPromptText
• scenePromptText

其中：

• visualPromptText 优先取 visualDescription
• animationPromptText 优先取 actionDescription
• scenePromptText 优先取 sceneVisualDescription

这层是默认描述文本，不是正式图像模型 prompt。

1.2 正式模型 prompt 层

这层的目标是：

把“默认描述文本”进一步编译成正式给图像模型 / 动作模型的完整 prompt。

当前主链来源：

• server-node/src/prompts/characterAssetPrompts.ts
• packages/shared/src/prompts/qwenSprite.ts

也就是说：

1. 前端先有一段短文本
2. 后端再用正式 prompt builder 把它扩成模型真正使用的完整 prompt

---

2. 角色形象生成链路

2.1 生成角色形象的系统提示词在哪

如果这里问的是“正式生成角色主图时，真正控制模型输出方向的 prompt 主源在哪”，答案是：

• server-node/src/prompts/characterAssetPrompts.ts
• packages/shared/src/prompts/qwenSprite.ts

更准确说：

1. buildNpcVisualPrompt
   • 文件：server-node/src/prompts/characterAssetPrompts.ts
   • 作用：把短描述文本和角色摘要合并
2. buildMasterPrompt
   • 文件：packages/shared/src/prompts/qwenSprite.ts
   • 作用：提供正式的角色主图 prompt 骨架

最终角色形象正式生成请求使用的是：

• buildNpcVisualPrompt(...)

调用位置：

• server-node/src/modules/assets/characterAssetRoutes.ts

即：

角色主图正式生成的系统提示词主链，不在前端默认值文件，而在后端 characterAssetPrompts.ts + 共享 qwenSprite.ts。

2.2 生成默认角色形象描述文本的提示词在哪

当前资产工坊默认输入框实际使用：

• src/prompts/customWorldRolePromptDefaults.ts

这不是 LLM system prompt，而是本地字段映射规则。

换句话说，当前页面上的默认“形象描述”主要来自：

• role.visualDescription
• 或回退到 role.description

---

3. 角色动作生成链路

3.1 生成角色动作的系统提示词在哪

当前正式动作生成主链在：

• server-node/src/prompts/characterAssetPrompts.ts
• packages/shared/src/prompts/qwenSprite.ts

其中分两类：

1. buildArkCharacterAnimationPrompt
   • 当前图生视频动作链路主入口
2. buildNpcAnimationPrompt
   • 通用动作视频 prompt builder
3. buildImageSequencePrompt
   • 连续帧方案动作 prompt builder
4. buildVideoActionPrompt
   • 共享动作模板骨架，在 packages/shared/src/prompts/qwenSprite.ts

当前主动作链路更偏向：

• buildArkCharacterAnimationPrompt

调用位置：

• server-node/src/modules/assets/characterAssetRoutes.ts

3.2 生成默认角色动作描述文本的提示词在哪

当前资产工坊真实默认“动作描述”来源：

• src/prompts/customWorldRolePromptDefaults.ts

规则是：

• 优先 actionDescription
• 回退 combatStyle

这仍然是默认描述文本层，不是最终动作模型 prompt。

---

4. characterAssetPrompts.ts 里的 visualPromptText / animationPromptText 到底是什么

这两个字段容易混淆，因为它们名字里带 Prompt。

但当前工程里它们更准确的定位是：

“默认描述文本 bundle 字段名”，不是最终图像模型请求体里的最终 prompt 名称。

也就是：

• visualPromptText
  • 在 UI 里更像“角色形象描述默认文本”
  • 之后会再被编译进正式图像 prompt
• animationPromptText
  • 在 UI 里更像“角色动作描述默认文本”
  • 之后会再被编译进正式动作 prompt

所以对你的问题可以直接回答为：

是，它们在当前语义上确实可以看作“默认角色形象 / 动作描述文本”。

但需要补一句：

它们不是最终一步的正式模型系统提示词，而是正式模型 prompt 的上游输入。

---

5. 当前真实调用链

5.1 当前资产工坊页面初始默认值主链

当前真实主链：

1. 角色对象已有字段进入前端
2. src/prompts/customWorldRolePromptDefaults.ts
3. CustomWorldRoleAssetStudioModal.tsx
4. 输入框初始值：
   • visualPromptText
   • animationPromptText

这条链：

• 快
• 本地可控
• 不依赖额外一次 LLM 调用

5.2 当前正式角色主图生成主链

1. 前端把输入框里的 visualPromptText 提交到后端
2. server-node/src/prompts/characterAssetPrompts.ts
   • buildNpcVisualPrompt
3. packages/shared/src/prompts/qwenSprite.ts
   • buildMasterPrompt
4. 图像模型正式生成

5.3 当前正式角色动作生成主链

1. 前端把输入框里的 animationPromptText 提交到后端
2. server-node/src/prompts/characterAssetPrompts.ts
   • buildArkCharacterAnimationPrompt
   • 或 buildNpcAnimationPrompt
   • 或 buildImageSequencePrompt
3. packages/shared/src/prompts/qwenSprite.ts
   • buildVideoActionPrompt
4. 动作模型正式生成

---

6. 冗余流程与当前问题

6.1 默认描述文本双链已收口

此前默认描述文本同时存在：

1. 前端本地字段映射
2. 后端 bundle 编译接口

本轮已经统一为：

• src/prompts/customWorldRolePromptDefaults.ts

也就是：

默认描述文本现在只有一条真实主源。

对应变化：

1. 不再保留后端独立的默认 bundle 编译接口。
2. 不再保留前端对应的 bundle 生成 API 壳层。
3. server-node/src/prompts/characterAssetPrompts.ts 只保留正式模型 prompt builder。

判断：

默认描述文本层的双份真相已经被消除。

6.2 scenePromptText 结构存在，但当前资产工坊没有完整承接

当前这套链路里：

• customWorldRolePromptDefaults.ts 会返回 scenePromptText
• characterAssetPrompts.ts 也会返回 scenePromptText

但当前资产工坊 UI 里并没有完整对应输入框链路。

这说明：

场景描述文本在结构层存在，但在当前角色资产工坊里没有形成完整的用户可编辑闭环。

6.3 共享模板与工具模板存在相似实现，但职责不同

仓库里同时有：

• packages/shared/src/prompts/qwenSprite.ts
• src/prompts/qwenSpriteSheetToolPrompts.ts

它们都提供类似的主图 / 动作模板能力。

但当前定位不同：

• packages/shared/src/prompts/qwenSprite.ts
  • 正式角色资产主链共享模板
• src/prompts/qwenSpriteSheetToolPrompts.ts
  • Qwen 工具链 prompt

它们不是同一条业务主链里的重复实现，但确实容易让人误读为“双份正式模板”。

判断：

这是“职责上可解释，但认知上高混淆”的并行模板，不建议现在直接删，但需要文档明确边界。

6.4 当前没有证据说明正式主图 / 动作 prompt builder 是无效代码

以下 builder 当前都有正式调用点：

• buildNpcVisualPrompt
• buildNpcVisualNegativePrompt
• buildArkCharacterAnimationPrompt
• buildNpcAnimationPrompt
• buildImageSequencePrompt

因此它们不能算“无效代码”。

真正已经被清理掉的保留链路，是此前未接入主 UI 的默认 bundle 接口：

• CHARACTER_PROMPT_BUNDLE_SYSTEM_PROMPT
• buildCharacterPromptBundleUserPrompt
• /api/assets/character-prompts/generate

这套链路已经不再保留在当前仓库主线中。

---

7. 本次建议

如果后续要继续收口，建议按顺序处理：

1. 继续以前端本地映射作为默认描述文本唯一主源。
2. 对 scenePromptText 做完整承接，不要继续停留在结构存在但 UI 不消费的状态。
3. 继续保留 packages/shared/src/prompts/qwenSprite.ts 与工具链 prompt 分层，但在文档里强制写清“正式主链 / 工具链”边界。

---

8. 本次审计覆盖文件

• server-node/src/prompts/characterAssetPrompts.ts
• packages/shared/src/prompts/qwenSprite.ts
• server-node/src/modules/assets/characterAssetRoutes.ts
• src/prompts/customWorldRolePromptDefaults.ts
• src/components/CustomWorldRoleAssetStudioModal.tsx
• src/components/asset-studio/characterAssetWorkflowPersistence.ts
• src/prompts/qwenSpriteSheetToolPrompts.ts

---

9. 一句话版结论

一句话总结就是：

当前角色资产系统把“默认描述文本”和“正式模型 prompt”拆成了两层，这是合理的；默认描述文本层已经统一为前端本地映射单一主源，当前剩余主要问题不再是双主源，而是 scenePromptText 仍未形成完整 UI 闭环。