1

docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md

@@ -2,12 +2,17 @@
 
 ## 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/**`
 
 问题主要有三类：
 
@@ -15,23 +20,40 @@
 2. 同一类 prompt 缺少集中入口，排查系统 prompt / user prompt / repair prompt 成本高。
 3. 老桥接层、测试和新业务链路同时依赖时，迁移成本高，容易出现导出断裂。
 
-这次收口目标不是“重写全部 AI 链路”，而是先把当前后端主链 prompt 收到单独目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。
+这次收口目标不是“重写全部 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
+├─ qwenSpriteSheetToolPrompts.ts
+├─ runtimeItemPrompts.ts
+├─ storyOrchestratorPrompts.ts
+└─ storyPromptBuilders.ts
 ```
 
 当前职责划分：
@@ -54,6 +76,20 @@ server-node/src/prompts/
   - 世界编辑器角色 / 场景实体生成 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. 落地规则
 
@@ -82,12 +118,18 @@ server-node/src/prompts/
 
 ### 3.3 兼容层保留旧导出
 
-本轮对已有纯 prompt builder 文件采取了兼容迁移：
+本轮对已有纯 prompt builder 文件采取了兼容迁移，旧路径保留为薄 re-export：
 
 - `server-node/src/modules/ai/chatPromptBuilders.ts`
 - `server-node/src/modules/ai/storyPromptBuilders.ts`
-
-旧路径现在作为薄 re-export 保留，避免测试、桥接层和旧引用一次性全部断掉。
+- `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 文件，保证兼容性。
 
@@ -95,11 +137,12 @@ server-node/src/prompts/
 
 新增提示词时按下面顺序处理：
 
-1. 先判断是否属于已有领域。
-2. 如果属于已有领域，优先补到对应 `server-node/src/prompts/*.ts`。
-3. 如果是新领域，再新增一个独立 prompt 脚本文件。
-4. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
-5. 至少补一条该 prompt 的调用链测试或现有测试断言。
+1. 先判断属于后端、前端/编辑器还是共享工具层。
+2. 后端正式业务优先补到 `server-node/src/prompts/*.ts`。
+3. 前端/编辑器 prompt 优先补到 `src/prompts/*.ts`。
+4. 可复用的共享资产 prompt 优先补到 `packages/shared/src/prompts/*.ts`。
+5. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
+6. 至少补一条该 prompt 的调用链测试或现有测试断言。
 
 建议命名：
 
@@ -108,7 +151,7 @@ server-node/src/prompts/
 - user prompt：`buildXXXPrompt`
 - 纯文本装配：`buildXXXPromptText`
 
-## 5. 本轮范围与剩余事项
+## 5. 本轮范围与当前状态
 
 本轮已经收口：
 
@@ -119,16 +162,17 @@ server-node/src/prompts/
 - Custom World 主编排
 - Custom World Agent 草稿增补
 - Custom World 编辑器角色 / 场景 / 场景 NPC 生成
+- Character Asset
+- Eight Anchor
+- Scene Image
+- 前端剧情 / 私聊 / 任务 / 物品 prompt 兼容层
+- 编辑器与工具链 prompt 种子
 
-本轮尚未完全收口的内联 prompt 聚集区：
+当前状态：
 
-- `server-node/src/modules/assets/characterAssetRoutes.ts`
-- `server-node/src/services/eightAnchorPromptBuilder.ts`
-
-这两块后续继续沿用同一规则：
-
-- 先抽出 prompt 文本与 builder
-- 再让业务文件只保留参数整理与调用
+- 正式业务 prompt 主源已经集中到 prompt 目录。
+- 旧 `services/`、`tools/`、`components/` 下保留的相关文件主要是兼容层或调用方。
+- 当前没有再发现需要优先继续抽离的大块业务 prompt 正文。
 
 ## 6. 验证方式
 
@@ -138,6 +182,9 @@ server-node/src/prompts/
 - `npm run server-node:test`
 - `npm --prefix server-node run build`
 
-说明：
+本轮实测结果：
 
-- 当前仓库里 `server-node/src/db.test.ts` 仍有一条与新增迁移版本号相关的既有失败，不属于本次 prompt 目录改造引入的问题。
+- `npm run check:encoding` 通过
+- `npm --prefix server-node run build` 通过
+- `npm run build` 通过
+- `npm run server-node:test` 143 项全部通过