1
This commit is contained in:
@@ -4,11 +4,13 @@
|
||||
|
||||
- [BUSINESS_PROMPT_INVENTORY_2026-04-19.md](./BUSINESS_PROMPT_INVENTORY_2026-04-19.md)：业务中现存提示词的总清单，覆盖后端主链、前端遗留、自定义世界、角色形象生成、场景背景生成与工具链 prompt。
|
||||
- [FUNCTION_SCRIPT_CATALOG_2026-04-04.md](./FUNCTION_SCRIPT_CATALOG_2026-04-04.md)：Function 独立脚本目录与分类速查。
|
||||
- [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)：RPG 创作功能脚本与 RPG 运行时脚本的职责地图，覆盖前端入口、编排、表现、client、`server-rs` 与 SpacetimeDB 侧落点。
|
||||
- [TASK_GENERATION_TRACE_2026-04-08.md](./TASK_GENERATION_TRACE_2026-04-08.md)：任务描述、达成条件与奖励生成链路梳理。
|
||||
- [CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md](./CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md)：自定义世界当前仍依赖哪些模板世界设定的清单。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 需要快速定位 Function 脚本，而不是阅读长篇方案时，优先看这里。
|
||||
- 需要快速判断“RPG 创作链和 RPG 运行时链分别该改哪些脚本”时，优先看 RPG 脚本职责地图。
|
||||
- 需要判断“武侠 / 仙侠模板层”哪些还能删、哪些不能删时，优先看自定义世界模板依赖清单。
|
||||
- 如果要评估 Function 分层是否合理，再配合 `docs/audits/FUNCTION_DESIGN_AUDIT_2026-04-03.md` 一起看。
|
||||
|
||||
@@ -0,0 +1,873 @@
|
||||
# RPG 创作功能与运行时脚本职责地图（2026-04-28）
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份文档只做一件事：
|
||||
|
||||
**把当前仓库里 RPG 创作功能相关脚本，以及 RPG 运行时游戏相关脚本，按真实职责整理成一份可检索的地图。**
|
||||
|
||||
这里的“脚本职责”强调的是：
|
||||
|
||||
1. 哪个脚本是入口。
|
||||
2. 哪个脚本负责状态编排。
|
||||
3. 哪个脚本只负责表现层。
|
||||
4. 哪个脚本负责请求后端。
|
||||
5. 哪个脚本在 `server-rs` 中承接正式业务真相。
|
||||
6. 哪些脚本仍处于兼容桥接层，不应继续扩张。
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前口径
|
||||
|
||||
### 2.1 唯一后端口径
|
||||
|
||||
按当前工程基线，正式后端以 `server-rs` 为准：
|
||||
|
||||
1. HTTP / SSE 门面：`server-rs/crates/api-server/src/`
|
||||
2. 共享契约：`server-rs/crates/shared-contracts/src/`
|
||||
3. SpacetimeDB 模块与领域表/过程：`server-rs/crates/module-*/src/`
|
||||
4. 客户端绑定与调用封装：`server-rs/crates/spacetime-client/src/`
|
||||
|
||||
### 2.2 当前前端口径
|
||||
|
||||
前端已基本按 RPG 域拆成三条主链：
|
||||
|
||||
```text
|
||||
平台入口与创作入口
|
||||
-> RPG 创作链
|
||||
-> RPG 运行时链
|
||||
```
|
||||
|
||||
但当前仍存在一些兼容桥接脚本，例如：
|
||||
|
||||
1. `src/components/rpg-entry/RpgEntryFlowShell.tsx`
|
||||
2. `src/services/rpg-runtime/rpgRuntimeChatClient.ts`
|
||||
3. `server-rs/crates/api-server/src/runtime_story.rs`
|
||||
|
||||
这些文件的职责主要是**兼容旧入口**，不是长期承载复杂逻辑的主战场。
|
||||
|
||||
---
|
||||
|
||||
## 3. 全局总图
|
||||
|
||||
```text
|
||||
平台入口层
|
||||
-> 创作入口 / 运行时入口分流
|
||||
|
||||
RPG 创作链：
|
||||
平台入口
|
||||
-> 创作工作台 / 共创会话
|
||||
-> 结果页
|
||||
-> 实体编辑器 / 角色资产工坊
|
||||
-> 创作域 client
|
||||
-> server-rs custom_world / custom_world_ai / prompt/rpg
|
||||
-> SpacetimeDB custom-world 相关表与过程
|
||||
|
||||
RPG 运行时链：
|
||||
平台入口 / 世界详情 / 继续游戏
|
||||
-> session bootstrap / persistence
|
||||
-> runtime shell / panel router / adventure panel
|
||||
-> runtime story hooks / gateway / client
|
||||
-> functionCatalog / prompt/rpg
|
||||
-> server-rs runtime_story / runtime_chat / runtime_save / story_battles / story_sessions
|
||||
-> shared-contracts + module-runtime + module-story + module-runtime-story-compat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. RPG 创作功能脚本职责
|
||||
|
||||
## 4.1 创作入口与平台分流
|
||||
|
||||
### `src/components/platform-entry/PlatformEntryFlowShell.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 平台入口通用壳层。
|
||||
2. 统一分流 RPG、Big Fish、Puzzle 等不同玩法入口。
|
||||
3. 作为多玩法并列入口的稳定门面。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是当前真正的平台入口壳层。
|
||||
2. RPG 创作和 RPG 运行时入口都先经过这里。
|
||||
|
||||
### `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 平台首页、详情页、创作类型选择、RPG 创作恢复、结果页进入等总编排。
|
||||
2. 协调 RPG 创作 Agent、Big Fish、Puzzle 的进入和返回。
|
||||
3. 连接平台级导航、作品库、公开广场、详情页和创作工作流。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是当前“平台级大编排器”。
|
||||
2. 它不是纯 RPG 文件，但当前 RPG 创作入口真实在这里收口。
|
||||
|
||||
### `src/components/custom-world-home/CustomWorldCreationHub.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 展示 RPG 创作工作台。
|
||||
2. 负责草稿、已发布作品、跨玩法作品卡片的列表层表现。
|
||||
3. 负责“创建新作品”“打开草稿”“进入已发布作品”“体验作品”“删除作品”的入口分发。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是 RPG 创作库的主表现层。
|
||||
2. 它不负责正式生成逻辑，只负责把用户动作抛给上层控制器。
|
||||
|
||||
---
|
||||
|
||||
## 4.2 RPG 共创会话链
|
||||
|
||||
### `src/components/custom-world-agent/CustomWorldAgentWorkspace.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 把 RPG 世界共创会话映射成通用 `CreationAgentWorkspace` 可消费的视图模型。
|
||||
2. 组织世界承诺、玩家幻想、主题边界、核心冲突等锚点展示。
|
||||
3. 提供“发送消息”“快捷动作”“生成底稿”等交互入口。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是 RPG 创作 Agent 会话的前端展示壳层。
|
||||
2. 它负责把领域数据翻译成工作台视图，不负责真正的网络请求。
|
||||
|
||||
### `src/services/rpg-creation/rpgCreationAgentClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 创建 RPG 创作会话。
|
||||
2. 读取会话快照。
|
||||
3. 发送消息、流式发送消息。
|
||||
4. 执行创作动作。
|
||||
5. 读取操作进度和草稿卡详情。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是 RPG 创作 Agent 的主 client 入口。
|
||||
2. 前端所有“会话级创作行为”最终都应该走这里，而不是继续回流到通用 `aiService.ts`。
|
||||
|
||||
### `server-rs/crates/api-server/src/custom_world.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接 RPG 世界库、世界详情、作品发布、取消发布、作品删除等 HTTP 接口。
|
||||
2. 承接创作 Agent session、message、action、operation、card detail 等接口。
|
||||
3. 协调底稿写回、资产生成、结果预览、发布门禁等后端业务。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是当前 RPG 创作后端最大入口文件之一。
|
||||
2. 前端创作会话和作品库的大部分正式请求都在这里收口。
|
||||
|
||||
### `server-rs/crates/api-server/src/custom_world_agent_turn.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接 RPG 共创聊天单轮执行。
|
||||
2. 负责把用户消息、会话状态、锚点内容和输出结构组织成一轮 Agent turn。
|
||||
3. 负责回写消息、操作、阶段进度和结果。
|
||||
|
||||
### `server-rs/crates/api-server/src/custom_world_foundation_draft.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责 RPG 世界底稿生成链。
|
||||
2. 组织底稿结构、草稿写回、阶段进度推进和失败恢复。
|
||||
|
||||
### `server-rs/crates/api-server/src/custom_world_ai.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供 RPG 创作过程中的场景图、场景 NPC、角色、地标等 AI 衍生生成接口。
|
||||
2. 把前端“补实体”“补图”“补角色”动作收口到后端。
|
||||
|
||||
---
|
||||
|
||||
## 4.3 RPG 创作结果页与编辑链
|
||||
|
||||
### `src/components/rpg-creation-result/RpgCreationResultView.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. RPG 创作结果页 façade。
|
||||
2. 只桥接到真实实现，不承载复杂逻辑。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是稳定入口。
|
||||
2. 真正逻辑在 `RpgCreationResultViewImpl.tsx` 及其配套 hooks 内。
|
||||
|
||||
### `src/components/rpg-creation-result/useRpgCreationResultActions.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 管理结果页上的实体新增、删除、局部重生成、最近新增实体高亮等交互。
|
||||
2. 调用 `rpgCreationAssetClient` 生成 playable / story / landmark。
|
||||
3. 协调结果页与编辑器、资产工坊之间的动作状态。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是结果页最核心的动作编排脚本之一。
|
||||
2. “结果页做什么”主要在这里定义，不在纯展示组件里定义。
|
||||
|
||||
### `src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. RPG 实体编辑器 modal 的稳定入口。
|
||||
2. 把复杂表单实现桥接到 `RpgCreationEntityEditorModalImpl.tsx`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是编辑器 façade。
|
||||
2. 后续编辑器拆 section 时应继续改 impl，不要把复杂逻辑塞回 façade。
|
||||
|
||||
### `src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 角色资产工坊 modal 的稳定入口。
|
||||
2. 把角色形象、动作、候选图、动画等细节桥接到真实实现。
|
||||
|
||||
### `src/components/rpg-creation-result/RpgCreationAssetDebugPanel.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 用于查看创作资产链路状态、调试结果页资产问题。
|
||||
2. 服务于结果页调试与排查，而不是普通玩家主流程。
|
||||
|
||||
---
|
||||
|
||||
## 4.4 RPG 创作域 client 分层
|
||||
|
||||
### `src/services/rpg-creation/rpgCreationGenerationClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责“生成 RPG 世界底稿 / profile”。
|
||||
2. 浏览器、SSR、Vitest node 环境统一请求 `/api/runtime/custom-world/profile`。
|
||||
3. 不再动态导入 `src/services/ai.ts`，测试离线能力只能 mock API client。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是“世界底稿生成”的入口 client。
|
||||
2. profile 生成 prompt 与 LLM 编排已经收口到 `server-rs`，前端只保留请求 contract。
|
||||
|
||||
### `src/services/rpg-creation/rpgCreationAssetClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责场景图、角色、地标、场景 NPC、封面图等资产请求。
|
||||
2. 负责历史资产列表读取。
|
||||
3. 给结果页和资产工坊提供统一资产接口。
|
||||
|
||||
### `src/services/rpg-creation/rpgCreationLibraryClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责世界库、作品广场、作品详情、保存、删除、发布、下架。
|
||||
2. 承接 RPG 创作结果进入库与进入广场的正式请求。
|
||||
|
||||
### `src/services/rpg-creation/rpgCreationPreviewAdapter.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 把 Agent session / result preview 转成结果页可消费预览模型。
|
||||
2. 是“生成链结果”和“结果页展示模型”之间的适配层。
|
||||
|
||||
### `src/services/rpg-creation/rpgCreationWorkClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责作品工作台列表和会话删除等工作流外围请求。
|
||||
|
||||
---
|
||||
|
||||
## 4.5 RPG 创作提示词与内容编排脚本
|
||||
|
||||
### 前端提示词目录 `src/prompts/`
|
||||
|
||||
与 RPG 创作直接相关的脚本：
|
||||
|
||||
1. `src/prompts/customWorldPrompts.ts`
|
||||
负责自定义世界生成相关提示词。
|
||||
2. `src/prompts/customWorldEntityActionPrompts.ts`
|
||||
负责实体生成与实体动作提示词。
|
||||
|
||||
说明：
|
||||
|
||||
1. 角色资产工坊默认 prompt 与缓存合并规则已经迁入 Rust，前端不再保留 `customWorldRolePromptDefaults.ts` 主源。
|
||||
|
||||
### Rust 提示词目录 `server-rs/crates/api-server/src/prompt/rpg/`
|
||||
|
||||
与 RPG 创作直接相关的脚本：
|
||||
|
||||
1. `foundation_draft.rs`
|
||||
负责 RPG 世界底稿生成提示词。
|
||||
2. `agent_chat.rs`
|
||||
负责 RPG 共创聊天提示词。
|
||||
3. `role_asset_studio.rs`
|
||||
负责角色资产工坊默认 prompt、legacy prompt 过滤与缓存合并 workflow view。
|
||||
|
||||
说明：
|
||||
|
||||
1. RPG 创作 prompt 已在 Rust 侧按 `rpg/` 子目录收口。
|
||||
2. 创作语义的正式后端提示词应该优先在这里改，而不是散改到路由或 service 中。
|
||||
|
||||
---
|
||||
|
||||
## 4.6 RPG 创作在 SpacetimeDB / 契约层的职责
|
||||
|
||||
### `server-rs/crates/shared-contracts/src/runtime.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供 RPG 创作请求/响应需要复用的共享运行时契约。
|
||||
|
||||
### `server-rs/crates/module-custom-world/src/lib.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接自定义世界作品、会话、发布、草稿等正式模块能力。
|
||||
2. 作为 RPG 创作在 SpacetimeDB 的主要领域模块之一。
|
||||
|
||||
### `server-rs/crates/spacetime-client/src/custom_world.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 为 `api-server` 提供自定义世界相关过程调用和数据读取封装。
|
||||
2. 把 API 层和 SpacetimeDB 模块调用隔开。
|
||||
|
||||
---
|
||||
|
||||
## 5. RPG 运行时游戏脚本职责
|
||||
|
||||
## 5.1 运行时入口与 Session 初始化
|
||||
|
||||
### `src/components/rpg-entry/RpgEntryFlowShell.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 兼容旧 RPG 入口导入路径。
|
||||
2. 真实实现已桥接到 `PlatformEntryFlowShell`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是兼容入口，不是当前主逻辑实现点。
|
||||
2. 如果要改多玩法入口或 RPG 入口主链，应优先看 `platform-entry/`。
|
||||
|
||||
### `src/hooks/rpg-session/useRpgSessionBootstrap.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责 RPG 新开局初始化。
|
||||
2. 负责世界选择、角色确认、初始场景、初始遭遇、初始库存、初始装备、初始 progression 的装配。
|
||||
3. 负责把自定义世界 profile 编译成可运行 `GameState`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是“开始游戏”最关键的前端 session 装配脚本。
|
||||
2. 进入运行态前的本地初始态主要在这里成型。
|
||||
|
||||
### `src/hooks/rpg-session/useRpgSessionPersistence.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责远端快照读取。
|
||||
2. 负责自动存档。
|
||||
3. 负责继续游戏恢复。
|
||||
4. 负责在恢复快照后刷新 runtime story 状态。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是运行时持久化主入口。
|
||||
2. 继续游戏、保存退出、自动存档主要都在这里编排。
|
||||
|
||||
### `src/hooks/rpg-session/useRpgRuntimeSession.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 作为 RPG 主运行态装配器。
|
||||
2. 组合 bootstrap、persistence、combat、npc interaction、runtime story、背景音乐等能力。
|
||||
3. 最终输出 `RpgRuntimeShell` 所需完整 props。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是前端运行时主装配入口。
|
||||
2. 查“为什么运行态拿到这些状态和事件回调”时，应优先看这里。
|
||||
|
||||
---
|
||||
|
||||
## 5.2 运行时 UI 壳层与面板层
|
||||
|
||||
### `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接 RPG 运行态总外壳。
|
||||
2. 装配画布舞台、阶段路由、overlay host、运行时级 UI chrome。
|
||||
3. 保持平台壳层和 RPG 壳层之间的显示切换。
|
||||
|
||||
### `src/components/rpg-runtime-shell/RpgRuntimeStageRouter.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 在平台入口态、选角态、冒险态之间路由。
|
||||
2. 把 session / story / entry 的装配结果分发给对应页面。
|
||||
|
||||
### `src/components/rpg-runtime-panels/RpgRuntimePanelRouter.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 在冒险、角色、背包等主面板间切换。
|
||||
2. 管运行态主 tab 的表现层分发。
|
||||
|
||||
### `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
1. 作为 RPG 冒险主面板。
|
||||
2. 负责展示剧情文本、选项列表、任务状态、战斗状态、资源状态、存档入口等主玩法信息。
|
||||
3. 负责把运行态 story 选项真正落成可点击 UI。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是当前运行时前台最核心的展示脚本之一。
|
||||
2. 它负责表现和 UI 交互，不负责正式状态真相裁决。
|
||||
|
||||
---
|
||||
|
||||
## 5.3 运行时剧情主链
|
||||
|
||||
### `src/hooks/rpg-runtime-story/useRpgRuntimeStory.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 作为 RPG runtime story 顶层装配入口。
|
||||
2. 组合角色聊天流、story controller、story flow。
|
||||
3. 向运行态主链输出 `currentStory`、`displayedOptions`、战斗奖励 UI、NPC UI、任务 UI 等完整剧情交互能力。
|
||||
|
||||
说明：
|
||||
|
||||
1. 前端剧情主链的总入口是它。
|
||||
2. 如果要理解运行时故事层如何被装配，先看这里。
|
||||
|
||||
### `src/hooks/rpg-runtime-story/useRpgRuntimeStoryController.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 管理当前故事、加载态、错误态和故事请求控制。
|
||||
2. 是前端 story 状态层的核心控制器。
|
||||
|
||||
### `src/hooks/rpg-runtime-story/useRpgRuntimeStoryFlow.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责真正的剧情流编排。
|
||||
2. 负责选项刷新、选项点击、NPC 交互、地图旅行、战斗奖励 UI、任务 UI、目标 UI 的组合。
|
||||
|
||||
### `src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责把不同类型的运行时交互分发到对应流程。
|
||||
2. 是运行时“动作入口分发层”。
|
||||
|
||||
### `src/hooks/rpg-runtime-story/useRpgRuntimeNpcInteraction.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责 NPC 聊天、送礼、招募、委托查看等 NPC 交互链。
|
||||
2. 组织 NPC 相关 UI 状态和动作入口。
|
||||
|
||||
### `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 负责前端 runtime story 与后端 runtime story 的网关衔接。
|
||||
2. 负责加载 option catalog、恢复 runtime story、提交 choice。
|
||||
3. 负责把服务端快照桥接回前端可消费状态。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是前端到后端 runtime story 主链的关键边界文件。
|
||||
2. 正式动作解析应该尽量经过这里，而不是在面板里直接组请求。
|
||||
|
||||
### `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 请求 `/api/runtime/story` 的 state 和 action 接口。
|
||||
2. 把服务端 `RuntimeStoryOptionView` 适配成前端 `StoryOption`。
|
||||
3. 负责 sessionId、clientVersion、snapshot 请求结构和响应快照反序列化。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是运行时故事 HTTP client 的主入口。
|
||||
2. “服务端动作解析”和“服务端状态读取”最终都要走这里。
|
||||
|
||||
### `src/services/rpg-runtime/rpgRuntimeChatClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供角色私聊、NPC 单轮聊天、招募对话等聊天能力。
|
||||
2. 当前仍桥接旧 `aiService`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是运行时聊天 client 的兼容收口层。
|
||||
2. 当前属于过渡桥接脚本，后续不应继续扩大旧 `aiService` 的依赖面。
|
||||
|
||||
### `src/services/rpg-runtime/rpgSnapshotClient.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供运行时快照读取、写入、删除能力。
|
||||
2. 给 session persistence 层提供正式持久化接口。
|
||||
|
||||
---
|
||||
|
||||
## 5.4 运行时选项函数与本地规则脚本
|
||||
|
||||
### `src/data/functionCatalog/`
|
||||
|
||||
职责：
|
||||
|
||||
1. 维护运行时 function 的独立定义脚本。
|
||||
2. 按 `state / npc / treasure / flow / panel` 分类收口。
|
||||
3. 统一管理 functionId、动作标题、说明、部分 helper 和运行时定义。
|
||||
|
||||
关键目录：
|
||||
|
||||
1. `src/data/functionCatalog/flow/`
|
||||
负责剧情流程控制型 function。
|
||||
2. `src/data/functionCatalog/npc/`
|
||||
负责 NPC 交互型 function。
|
||||
3. `src/data/functionCatalog/runtimeIndex.ts`
|
||||
负责运行时 function 的统一索引；该文件只依赖各分目录入口，不反向依赖 `functionCatalog/index.ts`，避免模块初始化循环。
|
||||
|
||||
### `src/data/stateFunctions.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 聚合基础状态 function。
|
||||
2. 对运行时 option 做优先级、排序和过滤支撑。
|
||||
|
||||
### `docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md`
|
||||
|
||||
职责：
|
||||
|
||||
1. 作为 function 脚本目录的专项速查文档。
|
||||
2. 如果只想查某个运行时 function 的脚本落点，优先看它。
|
||||
|
||||
---
|
||||
|
||||
## 5.5 运行时提示词脚本
|
||||
|
||||
### 前端 `src/prompts/rpg/`
|
||||
|
||||
关键脚本：
|
||||
|
||||
1. `runtimeStoryPrompts.ts`
|
||||
负责 RPG 运行时剧情和运行时叙事提示词。
|
||||
2. `characterChatPrompts.ts`
|
||||
负责角色私聊提示词。
|
||||
|
||||
### Rust `server-rs/crates/api-server/src/prompt/rpg/`
|
||||
|
||||
关键脚本：
|
||||
|
||||
1. `runtime_chat.rs`
|
||||
负责运行时剧情、NPC 对话、运行时聊天相关提示词。
|
||||
|
||||
说明：
|
||||
|
||||
1. 运行时 prompt 的正式后端组织应优先看 Rust 侧 `prompt/rpg/`。
|
||||
2. 前端 prompt 更多承担适配和兼容角色。
|
||||
|
||||
---
|
||||
|
||||
## 5.6 `server-rs` 中的 RPG 运行时后端职责
|
||||
|
||||
### `server-rs/crates/api-server/src/runtime_story.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 当前作为 RPG runtime story 的后端门面模块。
|
||||
2. 对外导出 `compat` 中的状态读取、动作解析、初始剧情和继续剧情能力。
|
||||
|
||||
说明：
|
||||
|
||||
1. 当前文件本身很薄。
|
||||
2. 真正逻辑在 `runtime_story/compat/` 里。
|
||||
|
||||
### `server-rs/crates/api-server/src/runtime_story/compat/`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接当前 RPG runtime story 的兼容实现。
|
||||
2. 负责 AI、装备动作、任务动作、NPC 动作、表现层 view model 和测试支撑。
|
||||
|
||||
关键脚本：
|
||||
|
||||
1. `ai.rs`
|
||||
负责运行时叙事 AI 相关兼容逻辑。
|
||||
2. `npc_actions.rs`
|
||||
负责 NPC 动作解析。
|
||||
3. `quest_actions.rs`
|
||||
负责任务动作解析。
|
||||
4. `equipment_actions.rs`
|
||||
负责装备和面板动作解析。
|
||||
5. `presentation.rs`
|
||||
负责运行时表现层 view model 编译。
|
||||
6. `game_state.rs`
|
||||
负责兼容态下的状态组织。
|
||||
|
||||
### `server-rs/crates/api-server/src/runtime_chat.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供运行时 NPC 单轮聊天 SSE 接口。
|
||||
2. 负责构建 NPC 对话 prompt。
|
||||
3. 负责 deterministic fallback 回复、建议选项和 function suggestion 回退。
|
||||
|
||||
### `server-rs/crates/api-server/src/runtime_save.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供当前快照读取、写入、删除接口。
|
||||
2. 提供存档归档列表和恢复接口。
|
||||
3. 负责区分正式快照与 preview / test 的临时快照写入语义。
|
||||
|
||||
### `server-rs/crates/api-server/src/runtime_inventory.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接运行时背包状态读取。
|
||||
|
||||
### `server-rs/crates/api-server/src/runtime_profile.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接运行时相关玩家资料、统计、充值中心、钱包流水等外围接口。
|
||||
|
||||
### `server-rs/crates/api-server/src/story_battles.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接故事战斗状态创建、NPC 战斗创建、战斗结算与战斗状态查询。
|
||||
|
||||
### `server-rs/crates/api-server/src/story_sessions.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接 story session 的 begin / continue / state 查询。
|
||||
2. 是运行时故事会话层的重要接口之一。
|
||||
|
||||
### `server-rs/crates/api-server/src/app.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 统一挂接 `api-server` 的 Axum 路由树。
|
||||
2. 把 runtime story、runtime chat、runtime save、story battle、story session 等接口注册到 HTTP 层。
|
||||
|
||||
说明：
|
||||
|
||||
1. 它是路由总装配文件，不是 RPG 运行时业务细节实现文件。
|
||||
|
||||
---
|
||||
|
||||
## 5.7 SpacetimeDB 模块与共享契约层职责
|
||||
|
||||
### `server-rs/crates/shared-contracts/src/runtime_story.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供 RPG 运行时故事域共享契约。
|
||||
|
||||
### `server-rs/crates/shared-contracts/src/runtime.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供运行时快照、创作、资料等通用契约。
|
||||
|
||||
### `server-rs/crates/module-runtime/src/lib.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供运行时快照、保存相关模块基础能力。
|
||||
|
||||
### `server-rs/crates/module-story/src/lib.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供故事会话、故事状态相关模块能力。
|
||||
|
||||
### `server-rs/crates/module-combat/src/lib.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供战斗状态相关模块能力。
|
||||
|
||||
### `server-rs/crates/module-quest/src/lib.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供任务状态、任务推进相关模块能力。
|
||||
|
||||
### `server-rs/crates/module-inventory/src/lib.rs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 提供背包和物品库存相关模块能力。
|
||||
|
||||
### `server-rs/crates/module-runtime-story-compat/src/`
|
||||
|
||||
职责：
|
||||
|
||||
1. 承接当前 runtime story compat 领域逻辑。
|
||||
2. 把战斗、锻造、选项、NPC 支撑、view model 等兼容逻辑收在独立 crate 中。
|
||||
|
||||
关键脚本：
|
||||
|
||||
1. `battle.rs`
|
||||
2. `forge.rs`
|
||||
3. `forge_actions.rs`
|
||||
4. `game_state.rs`
|
||||
5. `npc_support.rs`
|
||||
6. `options.rs`
|
||||
7. `view_model.rs`
|
||||
|
||||
说明：
|
||||
|
||||
1. 这是当前 RPG 运行时兼容逻辑的重要承载层。
|
||||
2. 如果要继续把前端旧本地规则向 Rust 收口，这里是关键迁移落点之一。
|
||||
|
||||
---
|
||||
|
||||
## 6. 支撑 RPG 创作与运行时的工具脚本职责
|
||||
|
||||
这些脚本不直接参与玩法，但直接支撑开发、发布、绑定和检查：
|
||||
|
||||
### `scripts/api-server-maincloud.mjs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 启动当前 Rust API server 主链路开发入口。
|
||||
2. 按仓库约束，后端联调应优先通过它启动。
|
||||
|
||||
### `scripts/generate-spacetime-bindings.mjs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 生成 SpacetimeDB 绑定。
|
||||
2. 支撑前后端契约同步。
|
||||
|
||||
### `scripts/check-encoding.mjs`
|
||||
|
||||
职责：
|
||||
|
||||
1. 检查仓库中文文件编码是否被写坏。
|
||||
2. 修改中文文档或中文注释后应优先运行。
|
||||
|
||||
### `scripts/validate-content.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 做内容结构校验。
|
||||
|
||||
### `scripts/validate-overrides.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 做覆盖项和配置项校验。
|
||||
|
||||
### `scripts/smoke-content.ts`
|
||||
|
||||
职责：
|
||||
|
||||
1. 做内容层 smoke 验证。
|
||||
|
||||
---
|
||||
|
||||
## 7. 当前最值得优先记住的入口脚本
|
||||
|
||||
如果只想快速建立脑图，建议优先记住下面这些文件：
|
||||
|
||||
### RPG 创作链
|
||||
|
||||
1. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
2. `src/components/custom-world-agent/CustomWorldAgentWorkspace.tsx`
|
||||
3. `src/components/rpg-creation-result/useRpgCreationResultActions.ts`
|
||||
4. `src/services/rpg-creation/rpgCreationAgentClient.ts`
|
||||
5. `src/services/rpg-creation/rpgCreationAssetClient.ts`
|
||||
6. `src/services/rpg-creation/rpgCreationLibraryClient.ts`
|
||||
7. `server-rs/crates/api-server/src/custom_world.rs`
|
||||
8. `server-rs/crates/api-server/src/custom_world_ai.rs`
|
||||
|
||||
### RPG 运行时链
|
||||
|
||||
1. `src/hooks/rpg-session/useRpgRuntimeSession.ts`
|
||||
2. `src/hooks/rpg-session/useRpgSessionBootstrap.ts`
|
||||
3. `src/hooks/rpg-session/useRpgSessionPersistence.ts`
|
||||
4. `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx`
|
||||
5. `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx`
|
||||
6. `src/hooks/rpg-runtime-story/useRpgRuntimeStory.ts`
|
||||
7. `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts`
|
||||
8. `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
|
||||
9. `server-rs/crates/api-server/src/runtime_story.rs`
|
||||
10. `server-rs/crates/api-server/src/runtime_chat.rs`
|
||||
11. `server-rs/crates/api-server/src/runtime_save.rs`
|
||||
|
||||
---
|
||||
|
||||
## 8. 当前兼容层与后续阅读建议
|
||||
|
||||
### 8.1 兼容层识别
|
||||
|
||||
下面这些脚本当前更多是兼容门面：
|
||||
|
||||
1. `src/components/rpg-entry/RpgEntryFlowShell.tsx`
|
||||
2. `src/services/rpg-runtime/rpgRuntimeChatClient.ts`
|
||||
3. `server-rs/crates/api-server/src/runtime_story.rs`
|
||||
|
||||
阅读这些文件时要注意：
|
||||
|
||||
1. 如果文件很薄，往往真实逻辑在它桥接到的 impl / compat / platform-entry 目录里。
|
||||
2. 不要把复杂新逻辑继续堆回这些 façade。
|
||||
|
||||
### 8.2 推荐阅读顺序
|
||||
|
||||
如果要继续开发 RPG 创作：
|
||||
|
||||
1. 先看 `PlatformEntryFlowShellImpl.tsx`
|
||||
2. 再看 `CustomWorldAgentWorkspace.tsx`
|
||||
3. 再看 `rpgCreationAgentClient.ts`
|
||||
4. 再看 `custom_world.rs`
|
||||
|
||||
如果要继续开发 RPG 运行时：
|
||||
|
||||
1. 先看 `useRpgRuntimeSession.ts`
|
||||
2. 再看 `useRpgRuntimeStory.ts`
|
||||
3. 再看 `rpgRuntimeStoryGateway.ts`
|
||||
4. 再看 `rpgRuntimeStoryClient.ts`
|
||||
5. 最后看 `server-rs/crates/api-server/src/runtime_story/compat/`
|
||||
|
||||
---
|
||||
|
||||
## 9. 结论
|
||||
|
||||
当前仓库里的 RPG 主链已经基本形成两套脚本地图：
|
||||
|
||||
1. **RPG 创作链**：以平台入口分流、共创会话、结果页编辑、资产工坊、创作域 client、`server-rs` 自定义世界接口为主。
|
||||
2. **RPG 运行时链**：以 session bootstrap、session persistence、runtime shell、runtime story hook、runtime story client、`server-rs` runtime story / runtime chat / runtime save 为主。
|
||||
|
||||
如果后续继续做职责收口，优先方向应该是：
|
||||
|
||||
1. 继续减少 façade 承载业务。
|
||||
2. 继续把前端兼容桥接逻辑向 `server-rs` 和 SpacetimeDB 正式域收口。
|
||||
3. 继续让“创作链”和“运行时链”各自维持清晰入口，而不是重新回到通用大文件。
|
||||
115
docs/reference/RPG_SCRIPT_COMMENTARY_PROGRESS_2026-04-28.md
Normal file
115
docs/reference/RPG_SCRIPT_COMMENTARY_PROGRESS_2026-04-28.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# RPG 脚本中文注释补充进度（2026-04-28）
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份文档用于记录当前仓库里 RPG 相关脚本的中文注释补充进度，避免后续“挨个补充”时重复扫描、重复改同一批文件，或者遗漏运行时主链上的关键脚本。
|
||||
|
||||
当前原则：
|
||||
|
||||
1. 先补职责最核心、状态流最复杂、后续最常被继续修改的脚本。
|
||||
2. 每一批都尽量按完整链路补，不只补单点文件。
|
||||
3. 注释以解释“为什么这样编排”“这一层负责什么边界”为主，不堆砌逐行翻译式废话。
|
||||
|
||||
---
|
||||
|
||||
## 2. 本轮已补充的脚本
|
||||
|
||||
### 2.1 RPG 运行时 session 主链
|
||||
|
||||
1. `src/hooks/rpg-session/useRpgRuntimeSession.ts`
|
||||
2. `src/hooks/rpg-session/useRpgSessionBootstrap.ts`
|
||||
3. `src/hooks/rpg-session/useRpgSessionPersistence.ts`
|
||||
|
||||
本轮重点：
|
||||
|
||||
1. 说明 session 装配器如何组合 bootstrap、story、combat、persistence。
|
||||
2. 说明自定义世界开局场景、首遇 NPC、初始装备与初始物品的装配原因。
|
||||
3. 说明自动存档、继续游戏、手动保存退出的状态边界。
|
||||
|
||||
### 2.2 RPG 运行时 story 主链
|
||||
|
||||
1. `src/hooks/rpg-runtime-story/useRpgRuntimeStory.ts`
|
||||
2. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryController.ts`
|
||||
3. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryFlow.ts`
|
||||
4. `src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.ts`
|
||||
5. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.ts`
|
||||
6. `src/hooks/rpg-runtime-story/storyInteractionCoordinator.ts`
|
||||
7. `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts`
|
||||
|
||||
本轮重点：
|
||||
|
||||
1. 说明 controller、flow、interaction、state 四层的职责切分。
|
||||
2. 说明 NPC 遭遇自动进入交互态、NPC 战斗快照桥接、地图旅行桥接的原因。
|
||||
3. 说明 story reset、story hydration、服务端动作结算的编排边界。
|
||||
|
||||
### 2.3 RPG 运行时 service / client 主链
|
||||
|
||||
1. `src/services/rpg-runtime/rpgRuntimeRequest.ts`
|
||||
2. `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
|
||||
3. `src/services/rpg-runtime/rpgSnapshotClient.ts`
|
||||
|
||||
本轮重点：
|
||||
|
||||
1. 说明 runtime 请求的统一重试策略。
|
||||
2. 说明服务端 `RuntimeStoryOptionView` 到前端 `StoryOption` 的适配原因。
|
||||
3. 说明远端快照读取、写入后为什么要先 rehydrate。
|
||||
|
||||
---
|
||||
|
||||
## 3. 建议的后续补充顺序
|
||||
|
||||
为了保持“按链路读得通”，下一轮建议继续按下面顺序推进：
|
||||
|
||||
### 3.1 运行时 story 子模块
|
||||
|
||||
1. `src/hooks/rpg-runtime-story/storyChoiceCoordinator.ts`
|
||||
2. `src/hooks/rpg-runtime-story/storyChoiceRuntime.ts`
|
||||
3. `src/hooks/rpg-runtime-story/storyRequestCoordinator.ts`
|
||||
4. `src/hooks/rpg-runtime-story/storyRequestRuntime.ts`
|
||||
5. `src/hooks/rpg-runtime-story/storyGenerationState.ts`
|
||||
6. `src/hooks/rpg-runtime-story/storyEncounterState.ts`
|
||||
7. `src/hooks/rpg-runtime-story/storyPresentation.ts`
|
||||
8. `src/hooks/rpg-runtime-story/sessionActions.ts`
|
||||
9. `src/hooks/rpg-runtime-story/progressionActions.ts`
|
||||
10. `src/hooks/rpg-runtime-story/npcInteraction.ts`
|
||||
11. `src/hooks/rpg-runtime-story/inventoryActions.ts`
|
||||
12. `src/hooks/rpg-runtime-story/goalFlow.ts`
|
||||
|
||||
原因：
|
||||
|
||||
1. 这些文件已经紧贴本轮完成的主编排层。
|
||||
2. 它们包含大量“局部规则 + 状态迁移 + UI 结果”的细节，最需要注释解释。
|
||||
|
||||
### 3.2 运行时 UI 与入口层
|
||||
|
||||
1. `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx`
|
||||
2. `src/components/rpg-runtime-shell/RpgRuntimeStageRouter.tsx`
|
||||
3. `src/components/rpg-runtime-panels/RpgRuntimePanelRouter.tsx`
|
||||
4. `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx`
|
||||
5. `src/hooks/rpg-session/useRpgSessionBootstrap.ts` 周边引用组件
|
||||
6. `src/components/rpg-entry/` 目录里的 RPG 运行时入口桥接脚本
|
||||
|
||||
原因：
|
||||
|
||||
1. 主链编排层补完后，再补表现层会更容易写出真正有用的注释。
|
||||
2. 入口层里有兼容 façade，需要明确标出“不要继续堆复杂逻辑”的边界。
|
||||
|
||||
### 3.3 RPG 创作链
|
||||
|
||||
1. `src/services/rpg-creation/` 目录主 client
|
||||
2. `src/components/rpg-creation-result/` 主动作脚本
|
||||
3. `src/components/rpg-creation-editor/` 主编辑链
|
||||
4. `src/components/rpg-creation-asset-studio/` 角色资产工坊链
|
||||
|
||||
原因：
|
||||
|
||||
1. 创作链文件也很多，但当前运行时主链更核心、更常改。
|
||||
2. 等运行时链注释连续后，再切创作链更不容易打断理解。
|
||||
|
||||
---
|
||||
|
||||
## 4. 本轮备注
|
||||
|
||||
1. 本轮以局部补丁方式补注释，没有整文件重写。
|
||||
2. 本轮没有改业务逻辑，只补中文注释和进度文档。
|
||||
3. 后续每补完一批，建议同步更新本文件，保持可追踪。
|
||||
Reference in New Issue
Block a user