1

docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md

@@ -0,0 +1,143 @@
+# 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`
+
+问题主要有三类：
+
+1. 业务逻辑和 prompt 文本混写，改提示词时容易顺手改坏运行时逻辑。
+2. 同一类 prompt 缺少集中入口，排查系统 prompt / user prompt / repair prompt 成本高。
+3. 老桥接层、测试和新业务链路同时依赖时，迁移成本高，容易出现导出断裂。
+
+这次收口目标不是“重写全部 AI 链路”，而是先把当前后端主链 prompt 收到单独目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。
+
+## 2. 新目录
+
+本轮新增目录：
+
+```text
+server-node/src/prompts/
+├─ chatPromptBuilders.ts
+├─ customWorldAgentPrompts.ts
+├─ customWorldEntityPrompts.ts
+├─ customWorldOrchestratorPrompts.ts
+├─ customWorldSceneNpcPrompts.ts
+├─ questPrompts.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
+
+## 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 文件采取了兼容迁移：
+
+- `server-node/src/modules/ai/chatPromptBuilders.ts`
+- `server-node/src/modules/ai/storyPromptBuilders.ts`
+
+旧路径现在作为薄 re-export 保留，避免测试、桥接层和旧引用一次性全部断掉。
+
+对于 `runtimeQuestModule.ts`、`runtimeItemModule.ts` 这类被桥接层直接引用的模块，本轮保留原导出名，通过 re-export 指向新 prompt 文件，保证兼容性。
+
+## 4. 后续新增 prompt 的写法
+
+新增提示词时按下面顺序处理：
+
+1. 先判断是否属于已有领域。
+2. 如果属于已有领域，优先补到对应 `server-node/src/prompts/*.ts`。
+3. 如果是新领域，再新增一个独立 prompt 脚本文件。
+4. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
+5. 至少补一条该 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 生成
+
+本轮尚未完全收口的内联 prompt 聚集区：
+
+- `server-node/src/modules/assets/characterAssetRoutes.ts`
+- `server-node/src/services/eightAnchorPromptBuilder.ts`
+
+这两块后续继续沿用同一规则：
+
+- 先抽出 prompt 文本与 builder
+- 再让业务文件只保留参数整理与调用
+
+## 6. 验证方式
+
+本轮调整后建议至少执行：
+
+- `npm run check:encoding`
+- `npm run server-node:test`
+- `npm --prefix server-node run build`
+
+说明：
+
+- 当前仓库里 `server-node/src/db.test.ts` 仍有一条与新增迁移版本号相关的既有失败，不属于本次 prompt 目录改造引入的问题。