1

docs/technical/RPG_FUNCTION_AND_PROMPT_EDITOR_REORGANIZATION_2026-04-28.md

@@ -0,0 +1,125 @@
+# RPG 选项函数与提示词编辑面整理方案（2026-04-28）
+
+## 背景
+
+当前 RPG 运行时已经把不少选项 function 的定义拆到了 `src/data/functionCatalog/`，但仍存在两个影响编辑效率的问题：
+
+1. `src/data/stateFunctions.ts` 里还残留一批按 `functionId` 分支的运行时文案、优先级与细节逻辑，导致“定义在独立文件，行为还混在总文件里”。
+2. RPG 运行时提示词虽然已经有独立模块，但前端 `src/prompts/` 与 Rust `server-rs/crates/api-server/src/prompt/` 里仍然缺少按 `rpg` 维度统一收口的子目录，编辑提示词时仍要在多个平铺文件里来回找。
+
+用户目标是：
+
+1. RPG 中不同选项 function 拆成独立函数，并且能在同一个脚本中看到所有选项 function 的代码入口。
+2. RPG 中运行时提示词都整理进 `prompt` 文件夹，并把 RPG prompt 脚本整理到更适合专注编辑提示词的结构中。
+
+## 本次落地边界
+
+1. 只整理 RPG 相关的前端运行时 function 与 prompt 结构。
+2. Rust 侧只整理 `server-rs` 的 prompt 模块结构，不兼容 `server-node`。
+3. 不改玩法语义，不重写大段中文提示词正文；优先移动文件、补兼容导出、增加聚合入口。
+4. 不在 UI 里增加说明文案。
+
+## 目标结构
+
+### 前端 RPG prompt
+
+整理为：
+
+```text
+src/prompts/
+├─ customWorldEntityActionPrompts.ts
+├─ customWorldPrompts.ts
+└─ rpg/
+   ├─ index.ts
+   ├─ runtimeStoryPrompts.ts
+   └─ characterChatPrompts.ts
+```
+
+说明：
+
+1. `runtimeStoryPrompts.ts` 承载原 `storyPromptBuilders.ts` 的 RPG 运行时剧情导演、NPC 对话导演、招募对话等提示词。
+2. `characterChatPrompts.ts` 承载原角色面板私聊提示词。
+3. 旧入口 `src/services/prompt.ts` 与 `src/services/characterChatPrompt.ts` 保留兼容转发，避免一次性改调用方。
+4. 角色资产工坊默认 prompt 与缓存合并规则不再放在前端 prompt 目录，统一迁到 `server-rs/crates/api-server/src/prompt/rpg/role_asset_studio.rs`。
+
+### Rust 侧 RPG prompt
+
+整理为：
+
+```text
+server-rs/crates/api-server/src/prompt/
+├─ big_fish.rs
+├─ character_animation.rs
+├─ character_visual.rs
+├─ puzzle_image.rs
+├─ scene_background.rs
+├─ mod.rs
+└─ rpg/
+   ├─ mod.rs
+   ├─ agent_chat.rs
+   ├─ foundation_draft.rs
+   ├─ role_asset_studio.rs
+   └─ runtime_chat.rs
+```
+
+说明：
+
+1. `prompt/rpg/agent_chat.rs` 承载 RPG 共创聊天提示词。
+2. `prompt/rpg/foundation_draft.rs` 承载 RPG 草稿生成提示词。
+3. `prompt/rpg/role_asset_studio.rs` 承载角色资产工坊默认 prompt、legacy prompt 过滤与缓存合并 workflow view。
+4. `prompt/rpg/runtime_chat.rs` 承载 RPG 运行时剧情、NPC 对话、战斗结果叙事等提示词。
+5. 顶层 `prompt/mod.rs` 继续向外导出 RPG 子模块，保证原调用点只做最小修改。
+
+### RPG function 总览
+
+新增一个面向编辑者的聚合入口，用来同时暴露：
+
+1. 所有 RPG function 文档项。
+2. 所有状态类 function source。
+3. 每个状态类 function 的运行时行为处理器入口。
+
+目标是让后续查看时可以先打开一个总览文件，再跳到对应 function 文件，而不是先从 `stateFunctions.ts` 的大 `switch` 里反查。
+
+## 代码落地策略
+
+### 1. function 运行时逻辑继续拆分
+
+把 `src/data/stateFunctions.ts` 中这些按 `functionId` 写死的逻辑继续拆出：
+
+1. 建议 actionText 生成。
+2. detailText 生成。
+3. function priority 计算。
+4. 必要的运行时 definition 微调。
+
+每个状态类 function 文件在保留 `definition + documentation + promptDescription` 的基础上，追加该 function 的运行时处理器。
+
+### 2. 总览脚本
+
+新增聚合入口文件，统一导出：
+
+1. 各域 function 文档。
+2. 状态类 function runtime source。
+3. 便于编辑时查找的数组/映射。
+
+这样“同一个脚本看到所有选项 function 的代码”具体落地为：
+
+1. 先看总览脚本知道有哪些 function。
+2. 每个 function 仍在独立文件维护，避免再次回到一个巨型文件。
+3. 总览脚本只能依赖 `state / npc / treasure / flow / panel` 等分目录入口，不能从 `src/data/functionCatalog/index.ts` 反向导入聚合常量，避免浏览器 ESM 初始化时出现 `Cannot access before initialization`。
+
+## 验证
+
+1. `npm run check:encoding`
+2. `npm run test -- src/services/prompt.test.ts src/hooks/rpg-runtime-story/storyResponseOptions.test.ts`
+3. `npm run typecheck`
+4. 如涉及 Rust prompt 模块编译错误，再补 `cargo check -p api-server`
+
+## 后续编辑约定
+
+1. 想改 RPG 运行时提示词时，优先进入：
+   - 前端：`src/prompts/rpg/`
+   - Rust：`server-rs/crates/api-server/src/prompt/rpg/`
+2. 想改 RPG 选项 function 时，优先进入：
+   - 总览：`src/data/functionCatalog/index.ts`
+   - 状态类分项：`src/data/functionCatalog/state/*.ts`
+3. 后续不要再把 RPG prompt 正文重新塞回 `services`、路由或运行时编排文件。