1

server-node/src/prompts/characterAssetPrompts.ts

@@ -4,6 +4,25 @@ import {
   getActionTemplateById,
 } from '../../../packages/shared/src/prompts/qwenSprite.js';
 
+/**
+ * 角色资产正式 prompt 主源。
+ *
+ * 这份脚本同时承担两层职责：
+ * 1. 角色卡 -> 默认资产描述文本
+ *    - 产出 visualPromptText / animationPromptText / scenePromptText
+ *    - 这层本质上是在“编译默认描述文本”，不是最终直接发给图像模型的完整 prompt
+ * 2. 默认描述文本 -> 正式模型 prompt
+ *    - buildNpcVisualPrompt / buildNpcAnimationPrompt / buildArkCharacterAnimationPrompt
+ *    - 这层才是正式发给图像 / 动作模型的 prompt 组装入口
+ *
+ * 当前仓库状态需要特别区分：
+ * - 当前自定义世界角色资产工坊默认输入框，实际直接使用前端
+ *   src/prompts/customWorldRolePromptDefaults.ts
+ * - 本文件里的 CHARACTER_PROMPT_BUNDLE_SYSTEM_PROMPT 及其生成接口
+ *   /api/assets/character-prompts/generate 目前仍保留、可用、且有测试覆盖，
+ *   但不是当前资产工坊初始默认值的主链来源
+ * - 当前正式角色主图与动作生成，仍然走本文件里的正式 prompt builder
+ */
 function clampPromptSeedText(value: unknown, maxLength: number) {
   if (typeof value !== 'string') {
     return '';
@@ -39,6 +58,17 @@ export type CharacterPromptBundle = {
   model: string | null;
 };
 
+/**
+ * 当默认描述文本编译接口不可用，或当前环境不走 LLM 编译时，
+ * 用角色卡字段本地拼出一份可直接使用的默认文本 bundle。
+ *
+ * 这份返回值属于“默认描述文本层”：
+ * - visualPromptText: 给角色主图用的默认描述
+ * - animationPromptText: 给动作试片用的默认描述
+ * - scenePromptText: 给角色关联场景用的默认描述
+ *
+ * 它不是最终发给正式图像 / 动作模型的完整 prompt。
+ */
 export function buildFallbackCharacterPromptBundle(params: {
   characterName: string;
   roleKind: string;
@@ -108,6 +138,12 @@ function sanitizePromptBundleValue(
   return normalized || fallback;
 }
 
+/**
+ * 将 LLM 返回的默认文本 bundle 规整成稳定结构。
+ *
+ * 这里只负责兜底、限长和字段补齐，不负责把 bundle 进一步编译成
+ * 正式图像 / 动作生成 prompt。
+ */
 export function sanitizeCharacterPromptBundle(
   value: unknown,
   fallback: CharacterPromptBundle,
@@ -161,6 +197,13 @@ function buildCompactAnimationCharacterBrief(value: string) {
     .join('，');
 }
 
+/**
+ * 默认文本 bundle 的 user prompt。
+ *
+ * 这段文本只用于让 LLM 从角色卡摘要里提炼出
+ * visualPromptText / animationPromptText / scenePromptText 三段默认描述，
+ * 不是正式图像模型或动作模型的 system prompt。
+ */
 export function buildCharacterPromptBundleUserPrompt(params: {
   roleKind: string;
   characterBriefText: string;
@@ -197,6 +240,17 @@ export function buildCharacterPromptBundleUserPrompt(params: {
     .join('\n');
 }
 
+/**
+ * 正式角色主图 prompt 编译入口。
+ *
+ * 输入的 promptText 通常是资产工坊输入框里的“形象描述”文本；
+ * 这里会把它和角色摘要合并，再交给共享层 buildMasterPrompt，
+ * 产出真正发给图像模型的正式 prompt。
+ *
+ * 因此：
+ * - promptText = 默认描述文本层
+ * - buildNpcVisualPrompt 返回值 = 正式图像生成 prompt 层
+ */
 export function buildNpcVisualPrompt(promptText: string, characterBriefText = '') {
   const mergedBrief = [characterBriefText.trim(), promptText.trim()]
     .filter(Boolean)
@@ -207,6 +261,11 @@ export function buildNpcVisualPrompt(promptText: string, characterBriefText = ''
   );
 }
 
+/**
+ * 正式角色主图生成的负向提示词。
+ *
+ * 只服务于图像生成请求，不参与默认描述文本生成。
+ */
 export function buildNpcVisualNegativePrompt() {
   return [
     '正面视角',
@@ -239,6 +298,12 @@ export function buildNpcVisualNegativePrompt() {
   ].join('，');
 }
 
+/**
+ * 连续序列帧方案的正式动作 prompt。
+ *
+ * 这是“图像序列帧”动作生成链路使用的正式 prompt，
+ * 不属于默认描述文本层。
+ */
 export function buildImageSequencePrompt(
   animation: string,
   promptText: string,
@@ -258,6 +323,15 @@ export function buildImageSequencePrompt(
     .join(' ');
 }
 
+/**
+ * 通用动作视频方案的正式动作 prompt。
+ *
+ * 输入的 promptText 是动作描述文本；
+ * 输出的是可以直接提交给动作模型的视频 prompt。
+ *
+ * 当前仓库里它主要服务于非 Ark 的动作视频链路，
+ * 以及某些保留的动作生成策略。
+ */
 export function buildNpcAnimationPrompt(options: {
   animation: string;
   promptText: string;
@@ -309,6 +383,13 @@ export function buildNpcAnimationPrompt(options: {
     .join(' ');
 }
 
+/**
+ * Ark 图生视频动作链路的正式动作 prompt。
+ *
+ * 当前自定义世界角色资产工坊的主动作生成流程，
+ * 最终会走到这个 builder。它会在共享模板的基础上，
+ * 叠加 Ark 所需的首帧 / 尾帧约束与动作英文名约束。
+ */
 export function buildArkCharacterAnimationPrompt(options: {
   animation: string;
   promptText: string;
@@ -359,6 +440,11 @@ export function buildArkCharacterAnimationPrompt(options: {
     .join(' ');
 }
 
+/**
+ * 当正式动作 prompt 触发审核或兼容问题时的保守兜底动作 prompt。
+ *
+ * 这条链路是正式动作生成的降级方案，不参与默认描述文本生成。
+ */
 export function buildFallbackModerationSafeAnimationPrompt(options: {
   animation: string;
   loop: boolean;