# 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/
│  ├─ agent_chat.rs
│  ├─ image.rs
│  └─ mod.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`、路由或运行时编排文件。