RPG 选项函数与提示词编辑面整理方案（2026-04-28）

背景

当前 RPG 运行时已经把不少选项 function 的定义拆到了 src/data/functionCatalog/，但仍存在两个影响编辑效率的问题：

src/data/stateFunctions.ts 里还残留一批按 functionId 分支的运行时文案、优先级与细节逻辑，导致“定义在独立文件，行为还混在总文件里”。
RPG 运行时提示词虽然已经有独立模块，但前端 src/prompts/ 与 Rust server-rs/crates/api-server/src/prompt/ 里仍然缺少按 rpg 维度统一收口的子目录，编辑提示词时仍要在多个平铺文件里来回找。

用户目标是：

RPG 中不同选项 function 拆成独立函数，并且能在同一个脚本中看到所有选项 function 的代码入口。
RPG 中运行时提示词都整理进 prompt 文件夹，并把 RPG prompt 脚本整理到更适合专注编辑提示词的结构中。

本次落地边界

只整理 RPG 相关的前端运行时 function 与 prompt 结构。
Rust 侧只整理 server-rs 的 prompt 模块结构，不兼容 server-node。
不改玩法语义，不重写大段中文提示词正文；优先移动文件、补兼容导出、增加聚合入口。
不在 UI 里增加说明文案。

目标结构

前端 RPG prompt

整理为：

src/prompts/
├─ customWorldEntityActionPrompts.ts
├─ customWorldPrompts.ts
└─ rpg/
   ├─ index.ts
   ├─ runtimeStoryPrompts.ts
   └─ characterChatPrompts.ts

说明：

runtimeStoryPrompts.ts 承载原 storyPromptBuilders.ts 的 RPG 运行时剧情导演、NPC 对话导演、招募对话等提示词。
characterChatPrompts.ts 承载原角色面板私聊提示词。
旧入口 src/services/prompt.ts 与 src/services/characterChatPrompt.ts 保留兼容转发，避免一次性改调用方。
角色资产工坊默认 prompt 与缓存合并规则不再放在前端 prompt 目录，统一迁到 server-rs/crates/api-server/src/prompt/rpg/role_asset_studio.rs。

Rust 侧 RPG prompt

整理为：

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

说明：

prompt/rpg/agent_chat.rs 承载 RPG 共创聊天提示词。
prompt/rpg/foundation_draft.rs 承载 RPG 草稿生成提示词。
prompt/rpg/role_asset_studio.rs 承载角色资产工坊默认 prompt、legacy prompt 过滤与缓存合并 workflow view。
prompt/rpg/runtime_chat.rs 承载 RPG 运行时剧情、NPC 对话、战斗结果叙事等提示词。
顶层 prompt/mod.rs 继续向外导出 RPG 子模块，保证原调用点只做最小修改。

RPG function 总览

新增一个面向编辑者的聚合入口，用来同时暴露：

所有 RPG function 文档项。
所有状态类 function source。
每个状态类 function 的运行时行为处理器入口。

目标是让后续查看时可以先打开一个总览文件，再跳到对应 function 文件，而不是先从 stateFunctions.ts 的大 switch 里反查。

代码落地策略

1. function 运行时逻辑继续拆分

把 src/data/stateFunctions.ts 中这些按 functionId 写死的逻辑继续拆出：

建议 actionText 生成。
detailText 生成。
function priority 计算。
必要的运行时 definition 微调。

每个状态类 function 文件在保留 definition + documentation + promptDescription 的基础上，追加该 function 的运行时处理器。

2. 总览脚本

新增聚合入口文件，统一导出：

各域 function 文档。
状态类 function runtime source。
便于编辑时查找的数组/映射。

这样“同一个脚本看到所有选项 function 的代码”具体落地为：

先看总览脚本知道有哪些 function。
每个 function 仍在独立文件维护，避免再次回到一个巨型文件。
总览脚本只能依赖 state / npc / treasure / flow / panel 等分目录入口，不能从 src/data/functionCatalog/index.ts 反向导入聚合常量，避免浏览器 ESM 初始化时出现 Cannot access before initialization。

验证

npm run check:encoding
npm run test -- src/services/prompt.test.ts src/hooks/rpg-runtime-story/storyResponseOptions.test.ts
npm run typecheck
如涉及 Rust prompt 模块编译错误，再补 cargo check -p api-server

后续编辑约定

想改 RPG 运行时提示词时，优先进入：
- 前端：src/prompts/rpg/
- Rust：server-rs/crates/api-server/src/prompt/rpg/
想改 RPG 选项 function 时，优先进入：
- 总览：src/data/functionCatalog/index.ts
- 状态类分项：src/data/functionCatalog/state/*.ts
后续不要再把 RPG prompt 正文重新塞回 services、路由或运行时编排文件。

5.0 KiB Raw Blame History Unescape Escape