Genarrative/docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md

Prompt 目录收口方案（2026-04-19）

1. 这次调整解决什么问题

此前提示词分散在多个后端、前端和工具文件里：

• server-node/src/modules/ai/**
• server-node/src/modules/quest/**
• server-node/src/modules/runtime-item/**
• server-node/src/services/customWorld*.ts
• server-node/src/services/eightAnchorPromptBuilder.ts
• server-node/src/modules/assets/characterAssetRoutes.ts
• src/services/**
• src/tools/qwenSpriteSheetToolModel.ts
• src/components/**

问题主要有三类：

1. 业务逻辑和 prompt 文本混写，改提示词时容易顺手改坏运行时逻辑。
2. 同一类 prompt 缺少集中入口，排查系统 prompt / user prompt / repair prompt 成本高。
3. 老桥接层、测试和新业务链路同时依赖时，迁移成本高，容易出现导出断裂。

这次收口目标不是“重写全部 AI 链路”，而是把当前正式业务 prompt 主源收到独立目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。

2. 新目录

本轮落地后的目录：

packages/shared/src/prompts/
└─ qwenSprite.ts

server-node/src/prompts/
├─ characterAssetPrompts.ts
├─ chatPromptBuilders.ts
├─ customWorldAgentPrompts.ts
├─ customWorldEntityPrompts.ts
├─ customWorldOrchestratorPrompts.ts
├─ customWorldSceneNpcPrompts.ts
├─ eightAnchorPrompts.ts
├─ questPrompts.ts
├─ runtimeItemPrompts.ts
├─ storyOrchestratorPrompts.ts
└─ storyPromptBuilders.ts

src/prompts/
├─ characterChatPrompts.ts
├─ customWorldEntityActionPrompts.ts
├─ customWorldOrchestratorPrompts.ts
├─ customWorldPrompts.ts
├─ customWorldRolePromptDefaults.ts
├─ questPrompts.ts
├─ qwenSpriteSheetToolPrompts.ts
├─ runtimeItemPrompts.ts
├─ storyOrchestratorPrompts.ts
└─ storyPromptBuilders.ts

当前职责划分：

• chatPromptBuilders.ts
  • 角色私聊 / NPC 聊天 / 招募对话 prompt
• storyPromptBuilders.ts
  • 主剧情 system prompt 与 user prompt builder
• storyOrchestratorPrompts.ts
  • 剧情语言修复 prompt
• questPrompts.ts
  • 任务意图 system prompt 与 user prompt builder
• runtimeItemPrompts.ts
  • 运行时物品意图 system prompt 与 user prompt 文本装配
• customWorldOrchestratorPrompts.ts
  • 自定义世界主编排 JSON 生成与 repair prompt
• customWorldAgentPrompts.ts
  • 世界草稿 JSON prompt、补角色 / 补地点 prompt
• customWorldEntityPrompts.ts
  • 世界编辑器角色 / 场景实体生成 prompt
• customWorldSceneNpcPrompts.ts
  • 世界编辑器场景 NPC 生成 prompt
• characterAssetPrompts.ts
  • 角色主图 / 动作试片 / 角色关联场景 prompt
• eightAnchorPrompts.ts
  • 八锚点状态推断、模式规则与正式单轮共创 prompt
• src/prompts/customWorldPrompts.ts
  • 自定义世界分阶段生成 prompt 与场景背景图 prompt
• src/prompts/qwenSpriteSheetToolPrompts.ts
  • 精灵图工具主词 / 分镜词 / 修帧词 / 负面词
• src/prompts/customWorldRolePromptDefaults.ts
  • 角色资产工作台默认 prompt 种子
• src/prompts/customWorldEntityActionPrompts.ts
  • 编辑器技能动作 prompt
• packages/shared/src/prompts/qwenSprite.ts
  • 共享资产层的基础角色 prompt 模板

3. 落地规则

3.1 业务模块只做两件事

1. 整理运行时上下文
2. 调用 server-node/src/prompts/** 下的脚本输出 prompt

不要在业务模块里继续直接内联大段 system prompt / repair prompt / user prompt 模板文本。

3.2 Prompt 文件只放文本相关职责

允许放：

• system prompt 常量
• user prompt builder
• repair prompt builder
• prompt 专用的文本摘要函数

不建议放：

• 运行时状态 mutation
• 仓储读写
• HTTP 处理
• 与 prompt 无关的领域推导

3.3 兼容层保留旧导出

本轮对已有纯 prompt builder 文件采取了兼容迁移，旧路径保留为薄 re-export：

• server-node/src/modules/ai/chatPromptBuilders.ts
• server-node/src/modules/ai/storyPromptBuilders.ts
• server-node/src/services/eightAnchorPromptBuilder.ts
• src/services/prompt.ts
• src/services/characterChatPrompt.ts
• src/services/questPrompt.ts
• src/services/runtimeItemAiPrompt.ts
• src/tools/qwenSpriteSheetToolModel.ts
• src/components/asset-studio/customWorldRolePromptDefaults.ts
• packages/shared/src/assets/qwenSprite.ts

对于 runtimeQuestModule.ts、runtimeItemModule.ts 这类被桥接层直接引用的模块，本轮保留原导出名，通过 re-export 指向新 prompt 文件，保证兼容性。

4. 后续新增 prompt 的写法

新增提示词时按下面顺序处理：

1. 先判断属于后端、前端/编辑器还是共享工具层。
2. 后端正式业务优先补到 server-node/src/prompts/*.ts。
3. 前端/编辑器 prompt 优先补到 src/prompts/*.ts。
4. 可复用的共享资产 prompt 优先补到 packages/shared/src/prompts/*.ts。
5. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
6. 至少补一条该 prompt 的调用链测试或现有测试断言。

建议命名：

• system prompt：XXX_SYSTEM_PROMPT
• repair prompt：buildXXXRepairPrompt
• user prompt：buildXXXPrompt
• 纯文本装配：buildXXXPromptText

5. 本轮范围与当前状态

本轮已经收口：

• Story
• Chat
• Quest
• Runtime Item
• Custom World 主编排
• Custom World Agent 草稿增补
• Custom World 编辑器角色 / 场景 / 场景 NPC 生成
• Character Asset
• Eight Anchor
• Scene Image
• 前端剧情 / 私聊 / 任务 / 物品 prompt 兼容层
• 编辑器与工具链 prompt 种子

当前状态：

• 正式业务 prompt 主源已经集中到 prompt 目录。
• 旧 services/、tools/、components/ 下保留的相关文件主要是兼容层或调用方。
• 当前没有再发现需要优先继续抽离的大块业务 prompt 正文。

6. 验证方式

本轮调整后建议至少执行：

• npm run check:encoding
• npm run server-node:test
• npm --prefix server-node run build

本轮实测结果：

• npm run check:encoding 通过
• npm --prefix server-node run build 通过
• npm run build 通过
• npm run server-node:test 143 项全部通过