1

packages/shared/src/contracts/story.ts

@@ -170,6 +170,7 @@ export type NpcChatDialogueRequest<
   context: TContext;
   topic: string;
   resultSummary: string;
+  npcInitiatesConversation?: boolean;
 };
 
 export type NpcChatTurnRequest<
@@ -195,6 +196,7 @@ export type NpcChatTurnRequest<
   dialogue?: TConversationTurn[];
   playerMessage: string;
   npcState: TNpcState;
+  npcInitiatesConversation?: boolean;
   questOfferContext?: {
     state: TQuestOfferState;
     encounter: TQuestOfferEncounter;

packages/shared/src/prompts/qwenSprite.ts

@@ -1,3 +1,20 @@
+/**
+ * 共享 sprite / 角色资产正式 prompt 模板。
+ *
+ * 这份脚本属于“正式模型 prompt 模板层”，不负责从角色卡里挑默认文本。
+ * 它的定位是：
+ * - 给后端角色主图生成链路提供标准主图 prompt 骨架
+ * - 给后端角色动作视频生成链路提供标准动作 prompt 骨架
+ *
+ * 当前角色资产主链中的关系是：
+ * 1. 前端或后端先拿到一段较短的描述文本
+ * 2. server-node/src/prompts/characterAssetPrompts.ts
+ *    再调用本文件 buildMasterPrompt / buildVideoActionPrompt
+ *    把短描述扩成正式给模型吃的 prompt
+ *
+ * 因此本文件不要承载“角色卡字段挑选”或“UI 默认值”职责，
+ * 只维护共享的正式 prompt 骨架与动作模板。
+ */
 export type QwenSpriteActionTemplateId =
   | 'idle'
   | 'run'
@@ -106,6 +123,13 @@ export function getActionTemplateById(id: QwenSpriteActionTemplateId) {
   );
 }
 
+/**
+ * 正式角色主图 prompt 骨架。
+ *
+ * 输入应该是一段已经整理好的角色摘要或视觉描述，
+ * 这里会把它嵌进统一的 sprite 资产约束中，
+ * 输出真正发给图像模型的完整 prompt。
+ */
 export function buildMasterPrompt(characterBrief: string) {
   return [
     '单人，2D 横版游戏角色标准设定图，主体完整可见，底部轮廓完整，身体比例稳定，轮廓清楚，适合后续制作 sprite sheet 动画。',
@@ -122,6 +146,13 @@ export function buildMasterPrompt(characterBrief: string) {
     .join('\n');
 }
 
+/**
+ * 正式动作视频 prompt 骨架。
+ *
+ * 输入应该是已经整理好的动作细节与角色摘要，
+ * 这里负责统一拼装成 sprite 动作生成所需的正式 prompt，
+ * 包括视角、像素风格、动作模板、绿幕约束等。
+ */
 export function buildVideoActionPrompt(options: {
   actionTemplate: QwenSpriteActionTemplate;
   actionDetailText: string;