186 lines
5.9 KiB
Markdown
186 lines
5.9 KiB
Markdown
# 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/components/**`
|
||
|
||
问题主要有三类：
|
||
|
||
1. 业务逻辑和 prompt 文本混写，改提示词时容易顺手改坏运行时逻辑。
|
||
2. 同一类 prompt 缺少集中入口，排查系统 prompt / user prompt / repair prompt 成本高。
|
||
3. 老桥接层、测试和新业务链路同时依赖时，迁移成本高，容易出现导出断裂。
|
||
|
||
这次收口目标不是“重写全部 AI 链路”，而是把当前正式业务 prompt 主源收到独立目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。
|
||
|
||
## 2. 新目录
|
||
|
||
本轮落地后的目录：
|
||
|
||
```text
|
||
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
|
||
├─ 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/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/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 项全部通过
|