Merge branch 'codex/dev' into codex/backend-rewrite-spacetimedb
# Conflicts: # docs/technical/README.md # server-node/src/modules/assets/qwenSpriteRoutes.ts # src/components/CustomWorldResultView.test.tsx # src/components/CustomWorldResultView.tsx # src/components/custom-world-agent/CustomWorldAgentDraftDetailPanel.tsx # src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx # src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx # src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx # src/components/rpg-entry/RpgEntryCharacterSelectView.tsx # src/components/rpg-entry/RpgEntryHomeView.tsx # src/services/apiClient.ts # src/tools/QwenSpriteSheetTool.tsx
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
# Agent 对话框与结果页精修职责边界修正
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 结论
|
||||
|
||||
本次修正把“Agent 对话框”和“结果页精修”重新拆清楚：
|
||||
|
||||
1. `CustomWorldAgentWorkspace` 只负责八锚点信息收集、八锚点进度展示、八锚点完成后的“整理世界底稿”动作。
|
||||
2. “精修”不是 Agent 对话框里的概念，不再通过 Agent 建议动作进入角色、地点、世界总卡的局部修整。
|
||||
3. 已经生成底稿的草稿，从创作中心点击后进入结果页继续完善。
|
||||
4. 尚未生成底稿的草稿，从创作中心点击后才恢复 Agent 对话框继续补齐八锚点。
|
||||
5. 结果页负责成稿后的编辑、补全、进入世界前确认和自动保存，并通过 `sync_result_profile` 回写到当前 Agent session。
|
||||
|
||||
一句话：
|
||||
|
||||
**Agent 收八锚点，结果页做精修。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么要修正
|
||||
|
||||
旧实现把 `object_refining` 草稿卡片显示成“继续精修”，但点击后直接恢复 Agent 工作区。
|
||||
|
||||
这个行为会让用户产生两个误解：
|
||||
|
||||
1. 以为精修是 Agent 对话框里的下一阶段。
|
||||
2. 以为 Agent 对话框不仅负责收集八锚点，还负责后续对象级编辑。
|
||||
|
||||
这和当前产品边界不一致。Agent 对话框应该保持轻量，只用于拿到足够稳定的八锚点输入；对象、场景、封面、世界档案的修整都应该在结果页完成。
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前落地规则
|
||||
|
||||
### 3.1 创作中心草稿点击分流
|
||||
|
||||
`custom-world/works` 返回 `agent_session` 草稿后，前端按草稿是否已有底稿内容分流：
|
||||
|
||||
1. `playableNpcCount <= 0 && landmarkCount <= 0`
|
||||
- 视为八锚点仍未整理成底稿。
|
||||
- 点击进入 `agent-workspace`。
|
||||
2. `playableNpcCount > 0 || landmarkCount > 0`
|
||||
- 视为已有可编辑底稿。
|
||||
- 点击读取对应 Agent session，编译为 `CustomWorldProfile`，进入 `custom-world-result`。
|
||||
|
||||
### 3.2 Agent 对话框动作边界
|
||||
|
||||
Agent 会话建议动作只保留：
|
||||
|
||||
1. 总结当前设定 / 总结当前世界底稿。
|
||||
2. 八锚点准备完成后的“整理一版世界底稿”。
|
||||
|
||||
不再在 Agent 会话快照里继续生成或兼容展示：
|
||||
|
||||
1. `refine_focus_target`
|
||||
2. “精修角色”
|
||||
3. “继续补地点”
|
||||
4. “先看世界总卡”
|
||||
|
||||
旧 session 快照如果仍带有 `refine_focus_target`，服务端兼容层会过滤掉，避免旧数据把精修入口重新塞回 Agent 对话框。
|
||||
|
||||
### 3.3 结果页精修边界
|
||||
|
||||
Agent 来源结果页不再是冻结预览态。
|
||||
|
||||
当前允许在结果页继续进行成稿精修，包括：
|
||||
|
||||
1. 编辑世界信息。
|
||||
2. 编辑角色、场景、封面等对象档案。
|
||||
3. 删除或调整已有对象。
|
||||
4. 自动保存到作品草稿。
|
||||
5. 进入世界前通过 `sync_result_profile` 写回 Agent session。
|
||||
|
||||
为了保持主链简洁，Agent 来源结果页仍不重新打开“通过 Agent 对话精修对象”的入口。
|
||||
|
||||
---
|
||||
|
||||
## 4. 对历史文档口径的覆盖
|
||||
|
||||
这份文档覆盖 [AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md](./AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md) 中“Agent 来源结果页冻结为预览态”的阶段性口径。
|
||||
|
||||
新的主口径是：
|
||||
|
||||
1. Agent 来源结果页可以编辑，因为精修本来就应该发生在结果页。
|
||||
2. 需要收紧的是 Agent 对话框，不是结果页。
|
||||
3. 结果页编辑后仍必须同步回 Agent session，保持进入世界前的数据真相源一致。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收标准
|
||||
|
||||
本次修正完成后应满足：
|
||||
|
||||
1. 创作中心已有底稿草稿按钮文案为“继续完善”，点击进入结果页。
|
||||
2. 创作中心未成稿草稿按钮仍为“继续创作”，点击进入 Agent 对话框。
|
||||
3. Agent 对话框不出现“精修角色 / 补地点 / 看世界总卡”类对象精修入口。
|
||||
4. Agent 来源结果页可以打开编辑弹窗进行精修。
|
||||
5. 返回创作从结果页回到创作中心，不回到 Agent 对话框。
|
||||
119
docs/technical/AGENT_DRAFT_RESULT_ASSET_MERGE_FIX_2026-04-21.md
Normal file
119
docs/technical/AGENT_DRAFT_RESULT_ASSET_MERGE_FIX_2026-04-21.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Agent 草稿结果页资产合并修复 2026-04-21
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 问题现象
|
||||
|
||||
当前创作流程里，用户在“生成草稿”后反馈：
|
||||
|
||||
1. 角色主图没有稳定出现在结果页
|
||||
2. 场景背景图有时可见，有时角色图缺失
|
||||
3. 自动保存后的作品库条目里，分幕图可能已经存在，但场景角色主图仍为空
|
||||
|
||||
## 2. 本次真实排查结论
|
||||
|
||||
本轮不是单一的“没写数据库”问题，而是 `agent draft -> result profile` 桥接层存在一类更隐蔽的集合漂移问题。
|
||||
|
||||
排查后确认：
|
||||
|
||||
1. 最新 `custom_world_sessions.payload_json` 里的 `draftProfile.storyNpcs[].imageSrc` 已经存在
|
||||
2. 最新 `draftProfile.sceneChapters[].acts[].backgroundImageSrc` 也已经存在
|
||||
3. 对应图片文件也真实存在于仓库根 `public/` 下
|
||||
4. 最新 `custom_world_profiles.payload_json` 里，分幕图通常已保存成功
|
||||
5. 但场景角色主图可能仍为空
|
||||
|
||||
根因在于：
|
||||
|
||||
1. 结果页桥接层在 `draftProfile.legacyResultProfile` 存在时，仍把 `legacyResultProfile` 视为主列表
|
||||
2. 旧逻辑只会按 `id` 把 `draftProfile` 里的图片字段回贴到 `legacyResultProfile`
|
||||
3. 一旦后续草稿精修导致 `draftProfile` 的角色集合、角色 id 或角色命名发生漂移
|
||||
4. 旧 `legacyResultProfile` 就会继续主导结果页和自动保存对象列表
|
||||
5. 最新角色主图虽然已在 `draftProfile` 里生成完成，但会因为匹配失败而被整批吞掉
|
||||
|
||||
这类问题在场景角色上最明显，因为角色集合最容易在后续精修中替换。
|
||||
|
||||
## 3. 修复策略
|
||||
|
||||
本轮在：
|
||||
|
||||
- `src/services/customWorldAgentDraftResult.ts`
|
||||
|
||||
调整桥接规则：
|
||||
|
||||
1. `legacyResultProfile` 仍保留，继续提供运行时富字段
|
||||
2. 但角色、场景、分幕等对象集合不再默认由 `legacyResultProfile` 主导
|
||||
3. 最新 `draftProfile` 成为结果页对象列表的主来源
|
||||
4. `legacyResultProfile` 只负责给命中的对象补运行时富字段
|
||||
5. 匹配优先级为：
|
||||
- 先按 `id`
|
||||
- 再按名称兜底
|
||||
|
||||
具体规则：
|
||||
|
||||
1. `playableNpcs`：以最新 draft 集合为主，legacy 只补富字段与旧运行时字段
|
||||
2. `storyNpcs`：同上，避免旧角色列表吞掉新角色主图
|
||||
3. `sceneChapterBlueprints`：以最新 draft 幕列表为主，legacy 只补章节/幕已有运行时字段
|
||||
4. `landmarks`：优先更新最新 draft 命中的场景对象，但保留 legacy 中未被命中的剩余运行时场景，避免丢连接与残留信息
|
||||
5. `camp`：保留 legacy 基础信息，但优先取 draft 最新图片字段
|
||||
|
||||
## 4. 修复后的链路意义
|
||||
|
||||
修复后：
|
||||
|
||||
1. 草稿自动资产服务生成的角色主图不会再因为旧 `legacyResultProfile` 的角色集合过时而丢失
|
||||
2. 分幕图继续可以稳定进入结果页与自动保存
|
||||
3. 作品库自动保存时，结果页编译出的 profile 更接近“当前草稿真实快照”，而不是历史 legacy 快照
|
||||
|
||||
## 5. 新增验证
|
||||
|
||||
本轮补了前端桥接测试：
|
||||
|
||||
- `src/services/customWorldAgentDraftResult.test.ts`
|
||||
|
||||
新增验证点：
|
||||
|
||||
1. 当 `draftProfile.storyNpcs` 与 `legacyResultProfile.storyNpcs` 集合漂移时
|
||||
2. 结果页仍应优先展示最新 draft 角色
|
||||
3. 最新角色主图与最新分幕图不能被旧 legacy 快照吞掉
|
||||
|
||||
## 6. 当前状态
|
||||
|
||||
本轮修复后，本地已验证：
|
||||
|
||||
1. `src/services/customWorldAgentDraftResult.test.ts`
|
||||
2. `src/components/CustomWorldResultView.test.tsx`
|
||||
3. `src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx`
|
||||
4. `npm run check:encoding`
|
||||
|
||||
均通过。
|
||||
|
||||
## 7. 后续建议
|
||||
|
||||
这次问题再次说明：
|
||||
|
||||
1. `legacyResultProfile` 继续长期作为结果页主列表来源风险很高
|
||||
2. 只做“按 id 回贴图片字段”在对象集合会漂移的链路里不够稳
|
||||
3. 后续如果继续推进后端单一真相源，应优先把结果页对象集合完全改为服务端最新 compile/preview 结果，而不是继续让前端桥接层承担最终裁决
|
||||
|
||||
---
|
||||
|
||||
## 8. 2026-04-21 补充：新建共创会话 500 根因
|
||||
|
||||
后续联调里又发现一条与资产合并无关、但会直接阻断创作入口的后端问题：
|
||||
|
||||
1. 点击“创建新 RPG 游戏”时，`POST /api/runtime/custom-world/agent/sessions` 返回 `500`
|
||||
2. 表面上前端只看到“服务器内部错误”，实际根因在路由层
|
||||
|
||||
本次补查确认：
|
||||
|
||||
1. `server-node/src/routes/customWorldAgent.ts` 这组路由内部直接使用 `request.userId!`
|
||||
2. 但路由文件本身在 `2026-04-21` 修复前没有挂 `requireJwtAuth(...)`
|
||||
3. 结果是 HTTP 请求虽然带了登录 token，但 `request.userId` 并不会被注入
|
||||
4. 后端继续拿 `undefined` 作为 `userId` 创建 / 读取 agent session，最终在仓储写库阶段触发 `500`
|
||||
|
||||
修复方式：
|
||||
|
||||
1. 在 `createCustomWorldAgentRoutes(...)` 顶部统一补上 `router.use(requireJwtAuth(context.config, context.userRepository))`
|
||||
2. 让 session 创建、读取、发消息、执行 action、读取 operation / card 详情全部走同一层鉴权注入
|
||||
|
||||
这次补丁的意义不是新增功能，而是把 `custom-world agent` 路由和其他 `rpg-entry / rpg-profile / rpg-runtime` 受保护接口重新对齐，避免再出现“路由里依赖 `request.userId`，但入口没挂鉴权”的低层断线问题。
|
||||
@@ -0,0 +1,119 @@
|
||||
# 创作流程草稿/图片/动作自动保存数据库检查 2026-04-21
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次检查范围
|
||||
|
||||
本次检查只聚焦当前创作流程里下面这条链路：
|
||||
|
||||
`结果页前端编辑 -> 自动保存 -> Agent session 主链同步 -> 作品库落库`
|
||||
|
||||
重点核对三类内容：
|
||||
|
||||
1. 草稿文本类修改
|
||||
2. 生成后的角色图片、地点图片、分幕图
|
||||
3. 角色动作相关资产字段
|
||||
|
||||
## 2. 当前实际自动保存链路
|
||||
|
||||
当前前端主入口在：
|
||||
|
||||
- `src/components/game-shell/PreGameSelectionFlow.tsx`
|
||||
|
||||
实际行为如下：
|
||||
|
||||
1. 结果页编辑统一通过 `onProfileChange` 更新 `generatedCustomWorldProfile`
|
||||
2. 当结果页停留在 `custom-world-result` 阶段时，前端会对 profile 做防抖自动保存
|
||||
3. 如果当前结果页来源是 `agent-draft`，自动保存前会先执行 `sync_result_profile`
|
||||
4. `sync_result_profile` 完成后，前端不直接保存旧内存 profile，而是优先保存“从最新 session 重编译出的 profile”
|
||||
5. 作品库保存最终走 `PUT /api/runtime/custom-world-library/:profileId`
|
||||
6. Express 后端通过 `runtimeRepository.upsertCustomWorldProfile(...)` 把 profile 写入 `custom_world_profiles.payload_json`
|
||||
|
||||
所以数据库层本身是有正常落库能力的。
|
||||
|
||||
## 3. 本次检查前确认成立的部分
|
||||
|
||||
以下能力在本次检查前已经成立：
|
||||
|
||||
1. 结果页普通草稿字段编辑会触发自动保存
|
||||
2. 自动保存会真正调用后端作品库接口并更新数据库
|
||||
3. 返回创作、进入世界两条路径也会优先同步 Agent session
|
||||
4. `legacyResultProfile` 已作为阶段一桥接快照保留在 session 中
|
||||
|
||||
## 4. 本次发现的真实风险
|
||||
|
||||
风险不在数据库写入本身，而在：
|
||||
|
||||
`sync_result_profile -> session 重编译结果页 profile`
|
||||
|
||||
此前 `sync_result_profile` 只回写：
|
||||
|
||||
1. 基础摘要字段
|
||||
2. `legacyResultProfile`
|
||||
|
||||
但没有把结果页里已经确认过的资产字段同步回 foundation draft 对应节点。
|
||||
|
||||
这会导致一个阶段性风险：
|
||||
|
||||
1. 用户在结果页换了新的角色图
|
||||
2. 或者结果页里刚确认了新的动作资产字段
|
||||
3. 或者结果页里刚确认了新的地点图、分幕图
|
||||
4. 自动保存前前端先做一次 session 同步
|
||||
5. 同步完成后又从 session 重编译结果页 profile
|
||||
6. 重编译过程会把 draft 层旧资产字段再次并入结果 profile
|
||||
|
||||
这样就可能出现：
|
||||
|
||||
**数据库自动保存成功了，但保存进去的是“被旧 draft 资产字段回退过的版本”，不是用户刚在结果页看到的最新图/动作。**
|
||||
|
||||
## 5. 本轮修复
|
||||
|
||||
本轮在：
|
||||
|
||||
- `server-node/src/services/customWorldAgentOrchestrator.ts`
|
||||
|
||||
补了一个收窄修复：
|
||||
|
||||
1. `sync_result_profile` 仍然保持阶段一边界，不做整套 runtime -> foundation draft 反解
|
||||
2. 但会按相同 id，把结果页里已确认的资产字段同步回 draft 层已有对象
|
||||
3. 同步范围包括：
|
||||
- 角色 `imageSrc`
|
||||
- 角色 `generatedVisualAssetId`
|
||||
- 角色 `generatedAnimationSetId`
|
||||
- 角色 `animationMap`
|
||||
- 地点 `imageSrc`
|
||||
- 分幕 `backgroundImageSrc`
|
||||
- 分幕 `backgroundAssetId`
|
||||
|
||||
这样后续再从 session 重编译结果页 profile 时，最新资产字段不会再被旧 draft 值回退。
|
||||
|
||||
## 6. 验证补充
|
||||
|
||||
本轮补了服务端测试：
|
||||
|
||||
- `server-node/src/services/customWorldAgentPhase4.test.ts`
|
||||
|
||||
新增验证点：
|
||||
|
||||
1. `sync_result_profile` 后，最新角色主图会写回 draft
|
||||
2. 最新角色动作资产字段会写回 draft
|
||||
3. 最新地点图会写回 draft
|
||||
4. 最新分幕图会写回 draft
|
||||
|
||||
## 7. 结论
|
||||
|
||||
截至本轮修复后，当前创作流程里：
|
||||
|
||||
1. 草稿文本修改可以自动保存到数据库
|
||||
2. 结果页中确认后的角色图、地点图、分幕图可以随自动保存稳定进入数据库
|
||||
3. 角色动作相关资产字段可以随 session 同步和自动保存稳定保留
|
||||
|
||||
但仍需注意：
|
||||
|
||||
1. 当前仍是阶段一兼容链路，核心桥接字段仍然是 `legacyResultProfile`
|
||||
2. 正式发布链 `publish_world` 还没有在当前阶段打通
|
||||
3. 前端仍依赖 `buildCustomWorldProfileFromAgentDraft()` 作为 session -> 结果页兼容编译层
|
||||
|
||||
因此本轮结论是：
|
||||
|
||||
**当前“前端修改 -> 自动保存 -> 数据库”主链可用；本次已补上图片与动作资产在 session 重编译阶段的回退风险。**
|
||||
212
docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md
Normal file
212
docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# Agent 结果页深度编辑回写主链方案（阶段一）
|
||||
|
||||
更新时间：`2026-04-20`
|
||||
|
||||
## 1. 这次阶段一先改什么
|
||||
|
||||
这次阶段一不做结果页只读化。
|
||||
|
||||
结果页继续保留当前已经可用、而且用户已经满意的这些能力：
|
||||
|
||||
1. 结果页继续允许深度编辑世界设定
|
||||
2. 结果页继续允许编辑角色、场景、营地、封面
|
||||
3. 结果页继续允许直接新增角色与地点
|
||||
4. 结果页继续保留当前已有的浏览、自动保存、进入世界体验
|
||||
|
||||
这次真正要补的是：
|
||||
|
||||
**把结果页里产出的完整 `CustomWorldProfile`，同步回 `Agent session`，让结果页编辑不再游离在主链之外。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前真正的问题
|
||||
|
||||
当前链路里，结果页虽然还能深度编辑，但数据职责是分裂的：
|
||||
|
||||
```text
|
||||
Agent session
|
||||
-> 前端 buildCustomWorldProfileFromAgentDraft()
|
||||
-> 结果页本地 profile
|
||||
-> 结果页继续深度编辑
|
||||
-> 自动保存到 custom-world-library
|
||||
-> 进入世界
|
||||
```
|
||||
|
||||
这里最大的问题不是“结果页能编辑”，而是：
|
||||
|
||||
1. 结果页编辑后的最新世界结构，没有稳定回写到 `Agent session`
|
||||
2. 用户从结果页返回 Agent 工作区后，session 侧仍可能停留在较旧的草稿状态
|
||||
3. “结果页当前看到的世界”“Agent session 当前保存的草稿”“作品库里自动保存的 profile”可能不是同一份东西
|
||||
4. 进入世界时如果直接吃当前前端内存态，也会继续放大这个分叉
|
||||
|
||||
所以阶段一要解决的是：
|
||||
|
||||
**结果页仍然是深度编辑器，但它编辑的是 Agent 主链里的当前结果快照，不是脱链的本地副本。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 阶段一目标状态
|
||||
|
||||
阶段一把链路先收成下面这样：
|
||||
|
||||
```text
|
||||
Agent session
|
||||
-> 前端 buildCustomWorldProfileFromAgentDraft() 生成结果页初始 profile
|
||||
-> 用户在结果页继续深度编辑 profile
|
||||
-> 前端调用新的 Agent action，把完整结果 profile 同步回 session
|
||||
-> session 保留：
|
||||
- 当前 foundation draft
|
||||
- 当前 legacyResultProfile 结果快照
|
||||
- 重编译后的 draftCards / assetCoverage / suggestedActions
|
||||
-> 自动保存与进入世界都优先基于已同步的 session 结果快照执行
|
||||
```
|
||||
|
||||
这一步仍然是过渡态，不是最终态。
|
||||
|
||||
因为：
|
||||
|
||||
1. 阶段一还不打通 `publish_world`
|
||||
2. 阶段一也不把结果页改造成完全原生的 draft 编辑器
|
||||
3. 阶段一允许继续保留 `draftProfile.legacyResultProfile` 作为兼容桥接字段
|
||||
|
||||
但至少要做到：
|
||||
|
||||
**结果页的深度编辑，必须进入 Agent session 的单一主链。**
|
||||
|
||||
---
|
||||
|
||||
## 4. 阶段一具体实现边界
|
||||
|
||||
## 4.1 新增 Agent action：`sync_result_profile`
|
||||
|
||||
阶段一新增一个面向结果页的 Agent action：
|
||||
|
||||
```ts
|
||||
{ action: 'sync_result_profile'; profile: CustomWorldProfileRecord }
|
||||
```
|
||||
|
||||
用途只有一个：
|
||||
|
||||
把结果页当前完整 `CustomWorldProfile` 快照同步回 `CustomWorldAgentSessionRecord`。
|
||||
|
||||
它不是发布动作，也不是世界编译动作。
|
||||
它只是把结果页当前编辑结果认回主链。
|
||||
|
||||
---
|
||||
|
||||
## 4.2 服务端写回策略
|
||||
|
||||
服务端接到 `sync_result_profile` 后，按下面规则处理：
|
||||
|
||||
1. 读取当前 session
|
||||
2. 取当前 `draftProfile`
|
||||
3. 保留当前 draft 层已有的结构化字段：
|
||||
- `playableNpcs / storyNpcs / landmarks / camp`
|
||||
- `factions / threads / chapters / sceneChapters`
|
||||
- `worldHook / playerPremise / openingSituation / iconicElements`
|
||||
- 以及现有资产、scene chapter 等字段
|
||||
4. 把结果页传来的完整 `CustomWorldProfile` 写入 `draftProfile.legacyResultProfile`
|
||||
5. 对于 draft 层里本来就和结果页一一对应、且结果页已经改动的字段，同步覆盖基础摘要字段：
|
||||
- `name`
|
||||
- `subtitle`
|
||||
- `summary`
|
||||
- `tone`
|
||||
- `playerGoal`
|
||||
- `majorFactions`
|
||||
- `coreConflicts`
|
||||
6. 重新编译 `draftCards`
|
||||
7. 重建 `assetCoverage`
|
||||
8. 刷新 `suggestedActions`
|
||||
9. 写入 action result message 和 checkpoint
|
||||
|
||||
这里故意不在阶段一做“把完整 runtime profile 反解成一整套全量 foundation draft 结构”的大重构。
|
||||
|
||||
原因是：
|
||||
|
||||
1. 结果页当前已经支持很多深度编辑字段
|
||||
2. 如果现在硬做全量反编译，最容易把场景章节、多幕、资产字段写坏
|
||||
3. 阶段一应该先保证“结果页编辑不脱链”，而不是一次性重做所有模型映射
|
||||
|
||||
---
|
||||
|
||||
## 4.3 前端触发策略
|
||||
|
||||
前端只在 `customWorldResultViewSource === 'agent-draft'` 时走这条同步链。
|
||||
|
||||
具体规则：
|
||||
|
||||
1. 结果页 profile 每次发生变化时，继续允许本地即时更新
|
||||
2. 但在自动保存前，先把 profile 通过 `sync_result_profile` 同步到 Agent session
|
||||
3. 返回创作时，如果要重新读 Agent 草稿，也应优先以最新 session 为准
|
||||
4. 点击“进入世界”时，先拉取最新 session，再重新 `buildCustomWorldProfileFromAgentDraft()`，避免吃到旧的前端缓存 profile
|
||||
|
||||
这样阶段一就能做到：
|
||||
|
||||
1. 结果页编辑体验不变
|
||||
2. Agent session 成为结果页编辑后的可恢复真相源
|
||||
3. 自动保存、返回创作、进入世界三条路都围绕同一份 session-backed 结果快照
|
||||
|
||||
---
|
||||
|
||||
## 5. 阶段一明确不做什么
|
||||
|
||||
这次阶段一明确不做：
|
||||
|
||||
1. 不关闭结果页当前已有的编辑器能力
|
||||
2. 不删除结果页当前已有的 AI 新增角色/地点能力
|
||||
3. 不打通 `publish_world`
|
||||
4. 不把 `legacyResultProfile` 直接删掉
|
||||
5. 不把结果页整个改写成只操作 draft card 的新系统
|
||||
6. 不把旧 `custom-world/sessions` 链在本阶段直接物理移除
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收标准
|
||||
|
||||
阶段一做完后，至少要满足下面这些结果：
|
||||
|
||||
1. Agent 草稿结果页继续保持当前深度编辑体验不变
|
||||
2. 结果页发生编辑后，Agent session 中能看到同步后的最新结果快照
|
||||
3. 从结果页返回创作后，不会明显回退到较旧的草稿态
|
||||
4. 点击“进入世界”时，会优先使用最新 session 重新编译结果，而不是只依赖前端旧内存态
|
||||
5. 自动保存到作品库的 profile 与当前 session 结果快照保持一致
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话结论
|
||||
|
||||
阶段一不是收掉结果页，而是把结果页继续保留为深度编辑器，同时补上一条正式的 session 回写链，让它不再游离在 Agent 主链之外。
|
||||
|
||||
---
|
||||
|
||||
## 8. 2026-04-20 实际落地结果
|
||||
|
||||
本轮已经按阶段一目标完成下面这些收口：
|
||||
|
||||
1. 前端结果页自动保存时，若当前来源是 `agent-draft`，会先执行 `sync_result_profile`
|
||||
2. `sync_result_profile` 完成后，自动保存不再直接写旧的前端内存 profile，而是优先保存从最新 session 重新 `buildCustomWorldProfileFromAgentDraft()` 得到的结果快照
|
||||
3. 点击“进入世界”时，仍会先同步 session，再基于最新 session 重编译 profile 后进入世界
|
||||
4. 点击“返回创作”时，也会先做一次结果页到 session 的同步兜底，再返回 Agent 工作区
|
||||
5. 为避免用户刚从结果页返回工作区又被自动重开逻辑顶回结果页，前端补了一层显式返回抑制标记
|
||||
6. 服务端 `sync_result_profile` 现已按阶段一边界收窄为“保留 foundation draft 结构，只更新基础摘要字段和 `legacyResultProfile`”，没有提前做整套 runtime -> draft 反解
|
||||
|
||||
这意味着阶段一当前已经把下面三条路径收回到同一条 session 主链：
|
||||
|
||||
1. 自动保存到作品库
|
||||
2. 返回 Agent 工作区继续创作
|
||||
3. 从结果页直接进入世界
|
||||
|
||||
## 9. 本轮仍然保留的阶段性边界
|
||||
|
||||
这次落地后，仍然保留文档原先约定的过渡边界：
|
||||
|
||||
1. 结果页深度编辑能力不做收缩
|
||||
2. `draftProfile.legacyResultProfile` 继续作为兼容桥接字段保留
|
||||
3. `publish_world` 仍未在这一轮打通
|
||||
4. 前端仍然使用 `buildCustomWorldProfileFromAgentDraft()` 作为 session -> 结果页的兼容编译层
|
||||
|
||||
所以下一阶段如果要继续推进，重点应转向：
|
||||
|
||||
1. 降低前端对 legacy profile 编译桥接的依赖
|
||||
2. 继续把发布链路收口到 Agent session / service 侧
|
||||
3. 逐步缩减结果页直改 legacy profile 的历史职责
|
||||
@@ -0,0 +1,74 @@
|
||||
# Agent 结果页与平台入口收口方案（阶段二）
|
||||
|
||||
更新时间：`2026-04-20`
|
||||
|
||||
## 1. 阶段二目标
|
||||
|
||||
阶段一已经把 Agent 结果页编辑快照同步回 session 主链。阶段二不继续扩大结果页编辑能力，而是把入口和职责继续收紧：
|
||||
|
||||
1. 平台“创作”入口统一读取 `custom-world/works` 聚合列表
|
||||
2. Agent 草稿和已保存作品在同一个入口里展示
|
||||
3. 草稿点击后恢复 Agent session，已保存作品点击后进入作品详情
|
||||
4. Agent 结果页不再暴露“继续在结果页补世界结构”的新增入口
|
||||
|
||||
一句话目标：
|
||||
|
||||
**让用户从平台创作入口能稳定找回草稿和作品，同时让结果页更像收口预览，而不是另一套编辑器。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 本阶段不做什么
|
||||
|
||||
阶段二明确不做：
|
||||
|
||||
1. 不物理删除旧 `custom-world/sessions` 链
|
||||
2. 不打通 `publish_world`
|
||||
3. 不重做结果页 UI
|
||||
4. 不删除已保存作品的继续编辑入口
|
||||
5. 不把结果页整体改成只读
|
||||
|
||||
这些事项留给后续阶段继续拆。
|
||||
|
||||
---
|
||||
|
||||
## 3. 平台入口落地规则
|
||||
|
||||
平台“创作”Tab 改为优先展示 `listCustomWorldWorks()` 的聚合结果：
|
||||
|
||||
1. `agent_session` 类型展示为草稿，可点击恢复 Agent 工作区
|
||||
2. `published_profile` 类型展示为作品，可点击进入作品详情
|
||||
3. 聚合接口失败时保留现有作品库 `myEntries` 兜底
|
||||
4. 不新增平行页面，复用已有 `CustomWorldCreationHub`
|
||||
|
||||
这样用户不再需要依赖隐藏 sessionId 或旧作品库入口才能找回创作。
|
||||
|
||||
---
|
||||
|
||||
## 4. 结果页职责收口规则
|
||||
|
||||
Agent 来源结果页继续保留：
|
||||
|
||||
1. 浏览世界、角色、场景
|
||||
2. 自动保存
|
||||
3. 返回 Agent 工作区
|
||||
4. 进入世界
|
||||
|
||||
Agent 来源结果页本阶段收紧：
|
||||
|
||||
1. 不再显示直接新增可扮演角色、场景角色、场景的入口
|
||||
2. 不再把“去 Agent 调整设定”设计成结果页内部继续补世界结构
|
||||
3. 如需继续调整，返回 Agent 工作区
|
||||
|
||||
已保存作品的结果页仍保持现有编辑能力，避免破坏作品库已有体验。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收标准
|
||||
|
||||
阶段二完成后应满足：
|
||||
|
||||
1. 平台“创作”Tab 能看到 Agent 草稿和已保存作品的统一列表
|
||||
2. 点击 Agent 草稿能恢复对应 Agent 工作区
|
||||
3. 点击已保存作品能进入原有作品详情
|
||||
4. Agent 结果页不再显示直接新增角色/地点的入口
|
||||
5. 已保存作品的结果页编辑能力不受影响
|
||||
148
docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md
Normal file
148
docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# Agent 结果页旧链降级与预览冻结方案（阶段三）
|
||||
|
||||
更新时间：`2026-04-20`
|
||||
|
||||
## 1. 阶段三目标
|
||||
|
||||
阶段一已经把结果页编辑同步回 Agent session 主链。
|
||||
|
||||
阶段二已经把平台“创作”入口统一到 `custom-world/works` 聚合列表，并收紧了 Agent 结果页里的新增入口。
|
||||
|
||||
阶段三不继续扩功能，而是继续做两件事：
|
||||
|
||||
1. 让旧 pipeline 在主入口里进一步降级，不再和 Agent 主链抢“草稿”职责
|
||||
2. 让 Agent 来源结果页进一步冻结为“预览/收口层”，不再继续承担 legacy profile 直改编辑器职责
|
||||
|
||||
一句话目标：
|
||||
|
||||
**把还在和 Agent 主链并行的旧职责继续降级，避免系统自己和自己打架。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前剩余问题
|
||||
|
||||
虽然阶段一、二已经把主链收紧了不少，但当前还保留两个明显的并行口：
|
||||
|
||||
### 2.1 创作中心里旧 library 草稿仍可能继续冒充主草稿
|
||||
|
||||
当前 `listCustomWorldWorkSummaries()` 会把 runtime library 里的所有 profile 都折成 `published_profile` 类型返回。
|
||||
|
||||
这意味着：
|
||||
|
||||
1. `visibility = 'draft'` 的 library 草稿仍会继续出现在创作中心
|
||||
2. 创作中心里同时存在：
|
||||
- Agent session 草稿
|
||||
- library 草稿
|
||||
- 已发布作品
|
||||
3. 用户看到的“草稿”概念仍然可能混成两套
|
||||
|
||||
阶段三需要明确：
|
||||
|
||||
**创作中心主入口只认 Agent session 草稿 和 已发布作品，不再继续把 library draft 当主草稿展示。**
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Agent 结果页仍能继续打开旧 legacy 编辑器
|
||||
|
||||
当前 Agent 来源结果页虽然已经不再暴露“新增角色/新增地点”入口，但仍然保留下面这些旧编辑链：
|
||||
|
||||
1. 点击世界概述/基本设定仍能打开 legacy world editor
|
||||
2. 点击角色、场景、封面仍能继续进入旧 profile 编辑弹窗
|
||||
3. 这些编辑器本质上仍然是在改 legacy `CustomWorldProfile`
|
||||
|
||||
这会带来两个问题：
|
||||
|
||||
1. Agent 结果页继续像一套“旧编辑器”
|
||||
2. “去 Agent 调整设定”和“结果页直接改 legacy profile”两条路仍然并行存在
|
||||
|
||||
阶段三需要明确：
|
||||
|
||||
**Agent 来源结果页继续保留浏览、自动保存、返回创作、进入世界，但不再继续承担 legacy profile 深编辑职责。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 阶段三落地规则
|
||||
|
||||
## 3.1 创作中心只展示两类主入口内容
|
||||
|
||||
`custom-world/works` 在阶段三只保留下面两类条目：
|
||||
|
||||
1. `agent_session`
|
||||
- 统一视为草稿
|
||||
- 点击后恢复 Agent 工作区
|
||||
2. `published_profile`
|
||||
- 统一视为已发布作品
|
||||
- 点击后进入现有作品详情
|
||||
|
||||
明确不再把下面这类内容继续塞进创作中心主入口：
|
||||
|
||||
1. library 中 `visibility = 'draft'` 的兼容草稿
|
||||
|
||||
这些兼容草稿仍然保留在作品库/详情链路里，不在本阶段物理删除，但不再继续占创作中心“草稿主入口”。
|
||||
|
||||
---
|
||||
|
||||
## 3.2 Agent 来源结果页冻结为预览态
|
||||
|
||||
当 `customWorldResultViewSource === 'agent-draft'` 时，结果页阶段三继续保留：
|
||||
|
||||
1. 浏览世界信息
|
||||
2. 浏览角色、地点、场景结构
|
||||
3. 自动保存
|
||||
4. 返回 Agent 工作区
|
||||
5. 进入世界
|
||||
|
||||
同时阶段三进一步收紧：
|
||||
|
||||
1. 不再打开世界/角色/场景/封面的 legacy 编辑弹窗
|
||||
2. 不再提供删除角色、删除场景等旧 profile 直改入口
|
||||
3. Agent 来源结果页上的对象卡统一作为“查看详情”预览卡使用
|
||||
|
||||
已保存作品的结果页编辑能力继续保留，不在本阶段收缩，避免破坏已有作品库编辑体验。
|
||||
|
||||
---
|
||||
|
||||
## 3.3 结果页同步动作只在真的发生差异时执行
|
||||
|
||||
阶段一补的 `sync_result_profile` 仍然保留，但阶段三补一个行为约束：
|
||||
|
||||
1. 如果当前 Agent 结果页 profile 和最新 session 重编译结果签名一致
|
||||
2. 那么返回创作、进入世界、自动保存前不再重复触发一次 `sync_result_profile`
|
||||
|
||||
目的不是省接口，而是明确：
|
||||
|
||||
**结果页同步是“有改动才回写”的主链动作，不是每次离开页面都机械重放。**
|
||||
|
||||
---
|
||||
|
||||
## 4. 阶段三明确不做什么
|
||||
|
||||
这次阶段三明确不做：
|
||||
|
||||
1. 不物理删除旧 `custom-world/sessions` 相关服务与兼容代码
|
||||
2. 不打通 `publish_world`
|
||||
3. 不把前端 `buildCustomWorldProfileFromAgentDraft()` 兼容编译层移除
|
||||
4. 不删除 `draftProfile.legacyResultProfile`
|
||||
5. 不收缩已保存作品的 legacy 编辑器能力
|
||||
|
||||
阶段三只做主入口降级与 Agent 结果页职责冻结，不做更大的模型替换。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收标准
|
||||
|
||||
阶段三完成后应满足：
|
||||
|
||||
1. 创作中心不再把 library draft 兼容作品继续显示为“草稿主入口”
|
||||
2. 创作中心里只保留 Agent 草稿和已发布作品两类主入口内容
|
||||
3. Agent 来源结果页不再能继续打开 legacy 世界/角色/场景编辑弹窗
|
||||
4. 已保存作品结果页编辑能力不受影响
|
||||
5. Agent 结果页在未发生改动时，返回创作/进入世界/自动保存不会重复触发无意义的 `sync_result_profile`
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话结论
|
||||
|
||||
阶段三不是删除兼容层，而是把它们继续降级到不会抢主流程职责的位置上：
|
||||
|
||||
**创作中心只认 Agent 草稿和已发布作品，Agent 结果页只负责预览与收口，不再继续充当旧编辑器。**
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,84 @@
|
||||
# 创作链路重构工作包 A 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 A：命名规范与目录骨架**，约束如下：
|
||||
|
||||
1. 先建立 RPG 创作域的新命名落点。
|
||||
2. 先提供 façade 和 barrel，不迁移主流程行为。
|
||||
3. 不提前修改工作包 B 到 H 的大块业务逻辑。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 前端目录骨架
|
||||
|
||||
已新增以下目录与 façade：
|
||||
|
||||
1. `src/components/game-shell/rpg-creation-flow/`
|
||||
2. `src/components/rpg-creation-result/`
|
||||
3. `src/components/rpg-creation-editor/`
|
||||
4. `src/services/rpg-creation/`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. `RpgCreationShell` 继续桥接旧的 `PreGameSelectionFlow`。
|
||||
2. `RpgCreationResultView` 继续桥接旧的 `CustomWorldResultView`。
|
||||
3. `RpgCreationEntityEditorModal` 继续桥接旧的 `CustomWorldEntityEditorModal`。
|
||||
4. `rpgCreation*Client` 继续桥接 `aiService.ts`、`storageService.ts`、`customWorldCoverAssetService.ts`。
|
||||
5. `rpgCreationPreviewAdapter` 继续桥接旧的前端草稿编译函数，明确它只是过渡层。
|
||||
|
||||
## 2.2 后端目录骨架
|
||||
|
||||
已新增以下 RPG 创作域 façade：
|
||||
|
||||
1. `server-node/src/routes/rpgCreationAgentRoutes.ts`
|
||||
2. `server-node/src/routes/rpgWorldWorksRoutes.ts`
|
||||
3. `server-node/src/routes/rpgWorldLibraryRoutes.ts`
|
||||
4. `server-node/src/routes/rpgWorldGalleryRoutes.ts`
|
||||
5. `server-node/src/services/RpgAgentOrchestrator.ts`
|
||||
6. `server-node/src/services/RpgAgentSessionStore.ts`
|
||||
7. `server-node/src/services/RpgWorldPreviewCompiler.ts`
|
||||
8. `server-node/src/services/RpgWorldWorkSummaryService.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. Agent route 与 orchestrator/session store 先用新命名 façade 对齐。
|
||||
2. works/library/gallery 路由先建立空骨架和基础 path 常量，避免下一轮迁移继续回落到旧命名。
|
||||
3. `RpgWorldPreviewCompiler` 先桥接旧 `runtimeProfile.ts` 编译能力，为工作包 G 的目录化拆分预留落点。
|
||||
|
||||
## 2.3 共享契约骨架
|
||||
|
||||
已新增以下共享契约入口：
|
||||
|
||||
1. `packages/shared/src/contracts/rpgAgentAnchors.ts`
|
||||
2. `packages/shared/src/contracts/rpgAgentDraft.ts`
|
||||
3. `packages/shared/src/contracts/rpgAgentSession.ts`
|
||||
4. `packages/shared/src/contracts/rpgAgentActions.ts`
|
||||
5. `packages/shared/src/contracts/rpgCreationPreview.ts`
|
||||
6. `packages/shared/src/contracts/rpgCreationWorkSummary.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. 会话、动作、作品摘要先从旧 `customWorldAgent.ts` 做类型级兼容导出。
|
||||
2. `rpgAgentDraft.ts` 先把 foundation draft、draft card 等草稿相关类型收口成独立入口，给工作包 H 后续物理拆分预留稳定导入点。
|
||||
3. `packages/shared/src/index.ts` 已补上对 RPG 草稿契约骨架的根导出，避免后续工作包继续回退到旧 `customWorldAgent.ts` 取类型。
|
||||
4. `rpgCreationPreview.ts` 明确标记当前 preview 仍是 legacy profile 兼容载体，避免误认为 preview contract 已经完成。
|
||||
|
||||
## 3. 本次没有做的事
|
||||
|
||||
以下内容仍保持原状，留给后续工作包：
|
||||
|
||||
1. 没有拆 `PreGameSelectionFlow.tsx` 内部编排。
|
||||
2. 没有拆 `CustomWorldResultView.tsx`、`CustomWorldEntityEditorModal.tsx`、`CustomWorldRoleAssetStudioModal.tsx` 内部 section。
|
||||
3. 没有把 `runtimeRoutes.ts` 中的 works/library/gallery 真正迁出。
|
||||
4. 没有改 `customWorldAgentOrchestrator.ts`、`customWorldAgentSessionStore.ts`、`runtimeProfile.ts` 的内部职责。
|
||||
5. 没有改变任何线上行为或接口语义。
|
||||
|
||||
## 4. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 B 可以直接把平台壳层 hooks 落到 `src/components/game-shell/rpg-creation-flow/`。
|
||||
2. 工作包 C 可以直接把结果页与编辑器 section 落到新目录，而不用先讨论命名。
|
||||
3. 工作包 D 可以直接从 `rpgCreation*Client` 开始迁移导入链。
|
||||
4. 工作包 E、F、G、H 可以基于 `RpgAgent*`、`RpgWorld*`、`rpg*` 契约骨架继续拆分，而不需要再回头统一首轮命名。
|
||||
@@ -0,0 +1,106 @@
|
||||
# 创作流程链路重构工作包 B 完成记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本轮目标
|
||||
|
||||
工作包 B 聚焦前端平台壳层与流程编排拆分，本轮目标是把平台壳层从“大编排文件”收口成“页面壳层 + 独立 hooks / coordinator”：
|
||||
|
||||
1. `PreGameSelectionFlow.tsx` 退化为兼容入口。
|
||||
2. `RpgCreationShellImpl.tsx` 只保留 stage 切换、组件装配、视觉级 loading / error。
|
||||
3. 平台 bootstrap、session controller、operation polling、detail navigation、result autosave、enter-world 逻辑全部迁入 `src/components/game-shell/rpg-creation-flow/` 新目录。
|
||||
4. 保证现有交互测试继续通过，不引入主链行为回退。
|
||||
|
||||
---
|
||||
|
||||
## 2. 已完成内容
|
||||
|
||||
### 2.1 旧入口已退化为兼容层
|
||||
|
||||
`src/components/game-shell/PreGameSelectionFlow.tsx` 现在只保留：
|
||||
|
||||
1. 旧类型导出兼容：`PreGameSelectionFlowProps`、`SelectionStage`
|
||||
2. 旧组件名兼容：`PreGameSelectionFlow`
|
||||
3. 对新实现 `RpgCreationShellImpl` 的桥接
|
||||
|
||||
这样现有调用方和测试仍可继续走旧路径，不会因为命名迁移立即破坏主链。
|
||||
|
||||
### 2.2 新目录已承接真实实现与流程 hooks
|
||||
|
||||
已新增或更新以下文件：
|
||||
|
||||
1. `src/components/game-shell/rpg-creation-flow/RpgCreationShellImpl.tsx`
|
||||
2. `src/components/game-shell/rpg-creation-flow/RpgCreationShell.tsx`
|
||||
3. `src/components/game-shell/rpg-creation-flow/index.ts`
|
||||
4. `src/components/game-shell/rpg-creation-flow/rpgCreationFlowTypes.ts`
|
||||
5. `src/components/game-shell/rpg-creation-flow/rpgCreationFlowShared.ts`
|
||||
6. `src/components/game-shell/rpg-creation-flow/useRpgCreationPlatformBootstrap.ts`
|
||||
7. `src/components/game-shell/rpg-creation-flow/useRpgCreationSessionController.ts`
|
||||
8. `src/components/game-shell/rpg-creation-flow/useRpgCreationAgentOperationPolling.ts`
|
||||
9. `src/components/game-shell/rpg-creation-flow/useRpgCreationDetailNavigation.ts`
|
||||
10. `src/components/game-shell/rpg-creation-flow/useRpgCreationResultAutosave.ts`
|
||||
11. `src/components/game-shell/rpg-creation-flow/useRpgCreationEnterWorld.ts`
|
||||
|
||||
其中：
|
||||
|
||||
1. `RpgCreationShell.tsx` 已不再桥接旧 `PreGameSelectionFlow`，而是直接桥接 `RpgCreationShellImpl.tsx`。
|
||||
2. `index.ts` 已开始从新目录导出 `SelectionStage`，为后续调用迁移准备统一出口。
|
||||
|
||||
### 2.3 平台编排已全部拆入独立 coordinator
|
||||
本轮已经把原 `PreGameSelectionFlow` / `RpgCreationShellImpl` 中的主链编排拆到以下 hook：
|
||||
|
||||
1. `useRpgCreationPlatformBootstrap.ts`
|
||||
- 平台首页 works / library / gallery / history / save / dashboard 拉取
|
||||
- 浏览历史写入与存档恢复
|
||||
2. `useRpgCreationSessionController.ts`
|
||||
- Agent session 创建 / 恢复
|
||||
- 消息流、action 执行、草稿生成态与结果页自动打开
|
||||
3. `useRpgCreationAgentOperationPolling.ts`
|
||||
- Agent operation 轮询
|
||||
- 完成态 session 刷新与失败兜底
|
||||
4. `useRpgCreationDetailNavigation.ts`
|
||||
- 作品详情、创作作品恢复、草稿结果页打开
|
||||
- 详情页发布 / 下架 / 删除
|
||||
5. `useRpgCreationResultAutosave.ts`
|
||||
- 结果页自动保存
|
||||
- `sync_result_profile` 协调
|
||||
- 保存签名去重与延时保存
|
||||
6. `useRpgCreationEnterWorld.ts`
|
||||
- 进入世界前的最终草稿同步
|
||||
|
||||
当前 `RpgCreationShellImpl.tsx` 只保留：
|
||||
|
||||
1. hooks 组合
|
||||
2. stage 级视图切换
|
||||
3. 组件 props 装配
|
||||
4. 视觉级 loading / error 展示
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前状态判断
|
||||
|
||||
工作包 B 已达到执行方案中的验收口径：
|
||||
|
||||
1. `PreGameSelectionFlow.tsx` 只剩兼容导出与新壳层桥接。
|
||||
2. `RpgCreationShellImpl.tsx` 不再直接持有平台请求编排、operation 轮询、自动保存或进入世界同步细节。
|
||||
3. 平台侧主链已经切成壳层 + hooks / coordinator。
|
||||
4. 现有 `PreGameSelectionFlow.agent.interaction.test.tsx` 的 14 个场景全部通过。
|
||||
|
||||
---
|
||||
|
||||
## 4. 本轮刻意未做
|
||||
|
||||
1. 还没有物理删除 `PreGameSelectionFlow.tsx`，当前继续保留旧入口兼容层，避免影响并行工作包的调用路径。
|
||||
2. 还没有让所有调用方统一显式改走 `RpgCreationShell` 新入口，当前仍允许旧入口桥接到新壳层。
|
||||
3. 还没有把结果页 preview 数据源从前端兼容 adapter 切到服务端正式 preview contract；当前仍使用 `rpgCreationPreviewAdapter` 作为阶段性兼容层，这属于后续工作包 G / H 与 Phase 3 范围。
|
||||
4. 还没有清理所有 legacy 兼容导出与 façade，当前优先稳定主链与测试口径。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验证结果
|
||||
|
||||
1. `npx eslint "src/components/game-shell/PreGameSelectionFlow.tsx" "src/components/game-shell/rpg-creation-flow/*.ts" "src/components/game-shell/rpg-creation-flow/*.tsx"`
|
||||
2. `npx vitest run src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx`
|
||||
3. `npm run check:encoding`
|
||||
|
||||
以上检查在本轮修改后均已通过。
|
||||
@@ -0,0 +1,106 @@
|
||||
# 创作链路重构工作包 D 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 D：前端 custom world client 收口**，约束如下：
|
||||
|
||||
1. 把创作链主路径依赖的 custom world 请求从 `aiService.ts`、`storageService.ts` 中迁入 `src/services/rpg-creation/`。
|
||||
2. 首轮允许旧 service 兼容导出，追加清理轮必须删除已无调用方的旧命名导出。
|
||||
3. 不改后端接口语义，不扩写结果页 UI 逻辑，不借机重构工作包 B / C 的内部状态编排。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 RPG 创作域请求基座已独立
|
||||
|
||||
已新增以下请求基座文件：
|
||||
|
||||
1. `src/services/rpg-creation/rpgCreationRuntimeClient.ts`
|
||||
2. `src/services/rpg-creation/rpgCreationRequestHelpers.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. runtime 读写重试策略不再散落在 `storageService.ts` 内部，而是作为 RPG 创作域专属 runtime client 复用。
|
||||
2. Agent SSE、POST JSON 请求辅助能力收口到 `rpgCreationRequestHelpers.ts`，避免再把流式解析细节写回通用 service。
|
||||
|
||||
## 2.2 五类 rpgCreation client 已持有真实请求实现
|
||||
|
||||
以下 client 已不再桥接旧 service，而是直接持有真实网络实现：
|
||||
|
||||
1. `src/services/rpg-creation/rpgCreationAgentClient.ts`
|
||||
2. `src/services/rpg-creation/rpgCreationWorkClient.ts`
|
||||
3. `src/services/rpg-creation/rpgCreationLibraryClient.ts`
|
||||
4. `src/services/rpg-creation/rpgCreationAssetClient.ts`
|
||||
5. `src/services/rpg-creation/rpgCreationGenerationClient.ts`
|
||||
|
||||
本轮已完成的具体收口：
|
||||
|
||||
1. Agent session 创建、读取、消息发送、消息流、action 执行、operation 查询、card detail 查询已经正式迁入 `rpgCreationAgentClient.ts`。
|
||||
2. works 列表查询已经正式迁入 `rpgCreationWorkClient.ts`。
|
||||
3. library / publish / unpublish / gallery / gallery detail 已经正式迁入 `rpgCreationLibraryClient.ts`。
|
||||
4. 结果页与编辑器依赖的场景图、场景 NPC、可扮演角色、场景角色、场景生成请求已经正式迁入 `rpgCreationAssetClient.ts`。
|
||||
5. `generateCustomWorldProfile()` 已正式迁入 `rpgCreationGenerationClient.ts`，世界生成入口也已进入 RPG 创作域 client。
|
||||
6. `src/services/rpg-creation/index.ts` 已收口为 RPG 命名导出，创作主链不再从 barrel 暴露 `createCustomWorldAgentSession / listCustomWorldWorks / upsertCustomWorldProfile` 等旧命名入口。
|
||||
|
||||
## 2.3 旧 service 兼容导出已删除
|
||||
|
||||
追加清理轮已完成以下删除：
|
||||
|
||||
1. `src/services/aiService.ts` 不再 re-export RPG 创作 Agent / works / 结果页生成接口，继续只服务 story/chat 等通用 AI 运行时能力。
|
||||
2. `src/services/storageService.ts` 已物理删除，运行时存档、设置、资料、浏览历史能力已迁入 `src/services/rpg-entry/` 与 `src/services/rpg-runtime/`。
|
||||
3. `rpgCreationAgentClient.ts`、`rpgCreationWorkClient.ts`、`rpgCreationLibraryClient.ts`、`rpgCreationAssetClient.ts` 已删除 `CustomWorld*` 兼容具名导出，只保留 `Rpg*` 主命名。
|
||||
4. 源码扫描已确认不再存在 `createCustomWorldAgentSession / executeCustomWorldAgentAction / listCustomWorldWorks / upsertCustomWorldProfile` 等旧主链函数引用。
|
||||
|
||||
## 2.4 主链调用已开始直接使用 RPG 创作域 client
|
||||
|
||||
本轮已把以下主链入口切到 `src/services/rpg-creation/`：
|
||||
|
||||
1. `src/components/rpg-entry/useRpgCreationSessionController.ts`
|
||||
2. `src/components/rpg-entry/useRpgCreationResultAutosave.ts`
|
||||
3. `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`
|
||||
4. `src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx`
|
||||
5. 新增世界生成入口 `generateRpgWorldProfile()` 通过 `src/services/rpg-creation/` barrel 暴露，后续新代码不必再从旧 `aiService.ts` 进入。
|
||||
|
||||
配套收口：
|
||||
|
||||
1. 结果页与编辑器相关测试 mock 已改到 `rpgCreationAssetClient`，不再盯住 `aiService.ts` 的兼容层。
|
||||
2. `CustomWorldResultView.test.tsx`、`CustomWorldEntityEditorModal.test.tsx` 已改为直接消费 `RpgCreationResultView / RpgCreationEntityEditorModal` 新入口，不再通过旧组件 façade。
|
||||
|
||||
## 2.5 本轮验证结果
|
||||
|
||||
已完成以下针对性验证：
|
||||
|
||||
1. `npm run test -- src/services/rpg-creation/rpgCreationGenerationClient.test.ts src/services/storageService.test.ts src/components/CustomWorldEntityEditorModal.test.tsx src/components/CustomWorldResultView.test.tsx src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx`
|
||||
2. `npm run check:encoding`
|
||||
|
||||
验证结果：
|
||||
|
||||
1. 上述 5 组定向测试全部通过。
|
||||
2. 编码检查通过，未写坏中文文件。
|
||||
|
||||
追加清理轮已完成以下验证：
|
||||
|
||||
1. `npm run test -- src/services/rpg-creation/rpgCreationPreviewAdapter.test.ts src/components/CustomWorldResultView.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`
|
||||
结果：通过，`42` 项测试全部通过。
|
||||
2. `npm run test -- src/services/rpg-creation/rpgCreationGenerationClient.test.ts`
|
||||
结果：通过，`2` 项测试全部通过。
|
||||
3. `npm run check:encoding`
|
||||
结果：通过，`1929` 个文件编码检查通过。
|
||||
4. 源码扫描确认 `src / packages / server-node` 中不再存在本轮删除的旧主链函数与旧组件入口符号引用。
|
||||
|
||||
## 3. 本次刻意未做的事
|
||||
|
||||
以下内容明确留给后续工作包，不在本轮越界处理：
|
||||
|
||||
1. 没有改后端 works/library/gallery/agent route 的语义与 contract。
|
||||
2. 没有拆 `PreGameSelectionFlow.tsx` 内部编排；这部分仍属于工作包 B。
|
||||
3. 没有继续物理拆散 `RpgCreationEntityEditorShared.tsx`；这部分仍属于工作包 C 后续细拆。
|
||||
4. 没有强行重命名历史数据结构类型，例如 `CustomWorldProfile` 与 runtime contract response 名称；这些仍是现有契约类型，不等同于旧脚本依赖。
|
||||
5. 没有删除旧 `src/services/ai.ts` 中的 legacy 世界生成实现；它已不在当前 RPG 创作主链 client 上，后续应按独立 dead code 批次评估。
|
||||
|
||||
## 4. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 B 后续拆平台壳层时，可以直接从 `src/services/rpg-creation/` 消费 Agent / works / library / gallery 请求，不必继续回到旧 service 文件找接口。
|
||||
2. 工作包 C 后续继续拆结果页和编辑器时，资产生成请求已经有稳定的 RPG 创作域入口。
|
||||
3. 后续清理 `aiService.ts`、`storageService.ts` 时，创作链主路径已经完成真实迁出，不会再被“通用 service 同时承载创作域请求”拖住。
|
||||
@@ -0,0 +1,150 @@
|
||||
# 创作链路重构工作包 E 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次落实 `CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 E：后端 Agent 编排拆分**，并严格遵守这一轮的写入边界：
|
||||
|
||||
1. 只改后端应用服务层，不动前端壳层。
|
||||
2. 先把 `customWorldAgentOrchestrator.ts` 从“大分支调度 + 派生状态重建 + 结果回写细节”里拆薄。
|
||||
3. 补齐 action executor 真实落点与 `supportedActions` 主链字段，但不在这一轮顺手重构 session store 和 runtime compiler。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 orchestrator 已退化为应用服务 façade
|
||||
|
||||
本轮后，`server-node/src/services/customWorldAgentOrchestrator.ts` 的职责开始收口为：
|
||||
|
||||
1. session 级入口方法保留。
|
||||
2. 创建 operation 记录。
|
||||
3. 调用 action registry 拿到执行计划。
|
||||
4. 把消息轮转、foundation 生成、实体生成、角色资产同步等主链事务串起来。
|
||||
|
||||
这轮明确移出的内容：
|
||||
|
||||
1. `action -> executor` 的分支校验和分发。
|
||||
2. `sync_result_profile` 的字段回写细节。
|
||||
3. 多个 action 共用的 draftCards / assetCoverage / suggestedActions / qualityFindings 派生重建逻辑。
|
||||
|
||||
## 2.2 已新增 action registry 与 executor 目录，并完成真实执行迁移
|
||||
|
||||
已新增：
|
||||
|
||||
1. `server-node/src/services/customWorldAgentActionRegistry.ts`
|
||||
2. `server-node/src/services/customWorldAgentActionExecutors/index.ts`
|
||||
3. `server-node/src/services/customWorldAgentActionExecutors/types.ts`
|
||||
|
||||
本轮收口结果：
|
||||
|
||||
1. registry 统一处理 `draft_foundation`、`update_draft_card`、`sync_result_profile`、`generate_characters`、`generate_landmarks`、`generate_role_assets`、`sync_role_assets` 的可用性校验。
|
||||
2. `publish_world`、`generate_scene_assets`、`sync_scene_assets`、`expand_long_tail`、`revert_checkpoint` 已完成真实 executor 装配，不再只是 registry 层面的“已声明但未开放”动作。
|
||||
3. `lock_cards`、`unlock_cards`、`regenerate_scope` 仍统一通过 registry 返回禁用原因，不再继续堆在 orchestrator 分支里。
|
||||
4. `customWorldAgentActionExecutors/` 已补 `draftFoundationExecutor.ts`、`updateDraftCardExecutor.ts`、`syncResultProfileExecutor.ts`、`generateCharactersExecutor.ts`、`generateLandmarksExecutor.ts`、`generateRoleAssetsExecutor.ts`、`syncRoleAssetsExecutor.ts`、`generateSceneAssetsExecutor.ts`、`syncSceneAssetsExecutor.ts`、`expandLongTailExecutor.ts`、`publishWorldExecutor.ts`、`revertCheckpointExecutor.ts`，真实 action 执行已从 orchestrator 物理迁入目录。
|
||||
5. `customWorldAgentActionExecutors/helpers.ts` 与 `executorShared.ts` 已收口 action_result / summary message 构造、operation 更新和 session 读取共用逻辑，避免 executor 间重复堆样板代码。
|
||||
|
||||
## 2.3 已新增 message turn / suggested action / snapshot / quality gate / result sync service
|
||||
|
||||
已新增：
|
||||
|
||||
1. `server-node/src/services/customWorldAgentMessageTurnService.ts`
|
||||
1. `server-node/src/services/customWorldAgentSuggestedActionService.ts`
|
||||
2. `server-node/src/services/customWorldAgentSnapshotBuilder.ts`
|
||||
3. `server-node/src/services/customWorldAgentQualityGateService.ts`
|
||||
4. `server-node/src/services/customWorldAgentResultSyncService.ts`
|
||||
|
||||
本轮收口结果：
|
||||
|
||||
1. `CustomWorldAgentMessageTurnService` 已接管 session 初始派生状态与 message turn 的真实执行，`customWorldAgentOrchestrator.ts` 只保留 façade 委托。
|
||||
1. `CustomWorldAgentSuggestedActionService` 统一维护 `foundation_review`、`object_refining`、`visual_refining` 的建议动作生成，不再散落在 orchestrator 和 session compatibility。
|
||||
2. `CustomWorldAgentSnapshotBuilder` 统一承接 message turn、foundation draft、结果页回写、角色/地点追加、角色资产同步后的派生字段重建。
|
||||
3. `CustomWorldAgentQualityGateService` 已形成独立 finding 入口，当前先输出角色缺失、地点缺失、玩家目标缺失、角色资产待补齐、场景资产待补齐等基础 gate finding。
|
||||
4. `CustomWorldAgentResultSyncService` 接管了 `sync_result_profile` 的字段回写细节，明确这一轮只允许“摘要 + 资产确认结果 + legacyResultProfile 快照”回写进 draft profile。
|
||||
|
||||
## 2.4 `supportedActions` 已接入 session snapshot 主链
|
||||
|
||||
这一轮已把 registry 产出的能力矩阵正式装配到 `CustomWorldAgentSessionSnapshot.supportedActions`：
|
||||
|
||||
1. `createSession`、`getSessionSnapshot`、stream message 完成态、各 action 完成后的 session 拉取都会返回真实 `supportedActions`。
|
||||
2. `supportedActions` 的启用状态按 session 当前阶段与草稿可用性计算，不再由前端根据 action 字面量自行猜测。
|
||||
3. 具体 payload 校验仍保留在 action 执行阶段，能力矩阵只表达“当前阶段是否允许发起这类动作”。
|
||||
|
||||
## 2.5 action 主链行为保持不变，但派生状态已开始统一
|
||||
|
||||
这一轮没有改变现有 action contract，也没有新增前端依赖字段，但已经把以下重复派生逻辑统一改走 snapshot builder：
|
||||
|
||||
1. `draft_foundation`
|
||||
2. `update_draft_card`
|
||||
3. `sync_result_profile`
|
||||
4. `generate_characters`
|
||||
5. `generate_landmarks`
|
||||
6. `generate_role_assets`
|
||||
7. `sync_role_assets`
|
||||
8. message turn 结束后的 stage / suggested actions / quality findings / asset coverage 重建
|
||||
|
||||
这意味着：
|
||||
|
||||
1. 后续新增 action 时，不必再复制一整段 `draftCards + assetCoverage + suggestedActions + recommendedReplies` patch 拼装代码。
|
||||
2. `qualityFindings` 已开始成为真实后端派生字段，而不只是 session store 中的空占位。
|
||||
3. `sync_result_profile` 的边界已经能单独测试和继续收缩。
|
||||
|
||||
## 2.6 工作包 E 第三轮已补齐的真实闭环
|
||||
|
||||
本轮把工作包 E 前两轮遗留的 5 个动作补成了真实后端闭环：
|
||||
|
||||
1. `generate_scene_assets`
|
||||
已通过 `CustomWorldAgentAssetBridgeService.buildSceneAssetStudioContext()` 打通场景图工坊上下文准备，支持营地与地点单场景进入。
|
||||
2. `sync_scene_assets`
|
||||
已通过 `applySceneAssetPublishResult()` 写回营地/地点正式场景图，并同步刷新对应 `sceneChapters[].acts` 的背景图与背景资产 ID。
|
||||
3. `expand_long_tail`
|
||||
已接入实体生成服务与 snapshot builder，能真实追加长尾角色、地点并把阶段推进到 `long_tail_review`。
|
||||
4. `publish_world`
|
||||
已改为走 `CustomWorldAgentPublishingService + RpgWorldProfileRepository` 主链，正式把 draft session 编译、写入并发布到作品库。
|
||||
5. `revert_checkpoint`
|
||||
已依赖 checkpoint snapshot 元数据与 `restoreCheckpoint()` 主链完成真实回滚，不再只是开放 action 名称。
|
||||
|
||||
这一轮同时补齐了 4 个关键收口：
|
||||
|
||||
1. 发布链已经统一改走 `CustomWorldAgentPublishingService`，`customWorldAgentOrchestrator.ts`、`customWorldAgentActionExecutors/index.ts`、`publishWorldExecutor.ts` 与 `server.ts` 的注入口径已经对齐；作者展示名优先走 `resolveAuthorDisplayName`，同时保留 `userRepository` 兼容兜底。
|
||||
2. `publish_world` 的 readiness 与正式发布已经收口到同一个服务，`profileId` 固定优先沿用 legacy 结果页 ID，否则回退为 `agent-draft-${sessionId}`，避免发布产物继续使用临时时间戳。
|
||||
3. `buildCheckpointSnapshot()` 已接入 `draft_foundation`、`update_draft_card`、`sync_result_profile`、`generate_characters`、`generate_landmarks`、`sync_role_assets`、`sync_scene_assets`、`expand_long_tail`、`publish_world` 等关键 executor，checkpoint 现在保存的是真正可恢复的派生快照，而不是只记一段残缺 patch。
|
||||
4. `rebuildRoleAssetCoverage()` 已补营地 / 地点正式场景资产 fallback 汇总，并收口为“只有真实正式场景图已存在时才补 standalone summary”，这样 `sync_scene_assets` 写回后的 camp/landmark asset coverage 在 snapshot 重建、works 读模型与 checkpoint 回放里都不会丢失，也不会误伤 phase3 自动资产回归。
|
||||
|
||||
## 2.7 本轮验证结果
|
||||
|
||||
已完成以下验证：
|
||||
|
||||
1. `npm --prefix server-node run build`
|
||||
2. `npm --prefix server-node run test -- customWorldAgentPhase3.test.ts customWorldAgentActionRegistry.test.ts customWorldAgentPhase5.test.ts`
|
||||
|
||||
本轮重点关注的回归范围：
|
||||
|
||||
1. `customWorldAgentActionRegistry.test.ts`
|
||||
2. `customWorldAgentPhase3.test.ts`
|
||||
3. `customWorldAgentPhase5.test.ts`
|
||||
4. `publish_world`
|
||||
5. `generate_scene_assets / sync_scene_assets`
|
||||
6. `expand_long_tail`
|
||||
7. `revert_checkpoint`
|
||||
|
||||
验证结果：
|
||||
|
||||
1. `server-node` 构建通过。
|
||||
2. 定向回归通过，共 `208` 项测试全部通过。
|
||||
3. Phase 3 与 Phase 5 已同时确认通过，说明这轮对 `sceneAssets` fallback summary 的收口没有打坏前序自动资产链。
|
||||
|
||||
## 3. 本次刻意未做的事
|
||||
|
||||
以下内容明确留给后续工作包或下一轮工作包 E，不在本轮越界处理：
|
||||
|
||||
1. 还没有进入 Phase 4 的“进入世界统一走发布态 gate”收口，当前这轮只完成了发布动作本身的后端闭环。
|
||||
2. 还没有改 `customWorldAgentSessionStore.ts` 内部 compatibility / snapshot 输出结构，这部分仍属于工作包 F。
|
||||
3. 还没有把 result preview 正式接到 `resultPreview` 主链字段，这部分仍需要和工作包 G / H 协作。
|
||||
4. 旧 `customWorldAgentPublishGateService.ts` 与 `customWorldAgentPublishService.ts` 仍作为历史兼容文件保留，但工作包 E 主链已经不再走它们；这一轮没有继续做物理删除与引用清扫，避免越界碰到 Phase 4/Phase 5 之外的兼容入口。
|
||||
|
||||
## 4. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 F 可以在不碰 orchestrator 大分支的前提下，继续拆 session/store/repository。
|
||||
2. 工作包 G 可以直接围绕 `CustomWorldAgentResultSyncService` 和 `CustomWorldAgentQualityGateService` 对接服务端 preview compiler 与 publish gate。
|
||||
3. 工作包 H 可以基于已落地的 `supportedActions`、action registry 和 quality gate 继续推进 preview contract 与 contract tests。
|
||||
4. 后续继续拆 action executor 时，已经有 `customWorldAgentActionExecutors/` 目录和注册表，不需要再回到 orchestrator 里重新铺路。
|
||||
@@ -0,0 +1,92 @@
|
||||
# 创作链路重构工作包 F 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次落实 `CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 F：后端 session/store/repository 拆分**，约束如下：
|
||||
|
||||
1. 不改动现有主链接口与行为语义。
|
||||
2. 保留 `customWorldAgentSessionStore.ts`、`runtimeRepository.ts`、`customWorldWorkSummaryService.ts` 作为兼容 façade。
|
||||
3. 把 session 兼容补齐、session 持久化、profile 持久化、works 读模型组装从大文件中物理拆出。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 session store 内部分层
|
||||
|
||||
已新增以下 RPG Agent session 拆分文件：
|
||||
|
||||
1. `server-node/src/services/rpg-agent-session-store/rpgAgentSessionRecord.ts`
|
||||
2. `server-node/src/services/rpg-agent-session-store/rpgAgentSessionCompatibility.ts`
|
||||
3. `server-node/src/services/rpg-agent-session-store/rpgAgentSessionFactory.ts`
|
||||
4. `server-node/src/services/rpg-agent-session-store/rpgAgentSessionRepositoryAdapter.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. `customWorldAgentSessionStore.ts` 继续保留旧类名和旧方法签名。
|
||||
2. sessionId 前缀、snapshot 输出结构、operation/checkpoint 写入语义保持兼容。
|
||||
3. 旧 session 的兼容补齐逻辑集中收口到 `rpgAgentSessionCompatibility.ts`，不再继续堆在 store 主文件里。
|
||||
4. `customWorldAgentSessionStore.ts` 已正式改为依赖 `RpgAgentSessionRepositoryPort`，phase2~5 与 works 集成测试也已切到新的 session 仓储端口。
|
||||
|
||||
## 2.2 custom world 仓储从 runtime 大仓储中拆出
|
||||
|
||||
已新增以下 RPG 世界仓储文件：
|
||||
|
||||
1. `server-node/src/repositories/RpgAgentSessionRepository.ts`
|
||||
2. `server-node/src/repositories/RpgWorldProfileRepository.ts`
|
||||
3. `server-node/src/repositories/rpgWorldRepositoryShared.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. `RuntimeRepositoryPort` 继续保留兼容 façade，但 `context.ts`、`server.ts`、`runtimeRoutes.ts`、同步脚本已开始直接注入并使用 `RpgAgentSessionRepository`、`RpgWorldProfileRepository`。
|
||||
2. `runtimeRepository.ts` 内的 custom world session/profile/gallery SQL 已改成委托新仓储。
|
||||
3. `runtimeRepository.ts` 继续只保留 runtime 快照、设置、浏览历史、档案等通用能力，以及少量尚未迁走的快照同步编排。
|
||||
|
||||
## 2.3 works 读模型拆分
|
||||
|
||||
已新增以下 works 读模型相关文件：
|
||||
|
||||
1. `server-node/src/services/RpgWorldWorkCoverResolver.ts`
|
||||
2. `server-node/src/services/RpgWorldWorkSummaryAssembler.ts`
|
||||
3. `server-node/src/services/RpgWorldWorkSummaryService.ts`
|
||||
|
||||
并将：
|
||||
|
||||
1. `server-node/src/services/customWorldWorkSummaryService.ts`
|
||||
|
||||
退化为兼容入口，仅负责桥接新 `RpgWorldWorkSummaryService`。
|
||||
|
||||
当前策略：
|
||||
|
||||
1. works service 只保留服务入口，不再内嵌标题、摘要、封面、资产覆盖率等全部组装细节。
|
||||
2. 草稿封面与发布态封面解析统一走 resolver，避免后续重复理解封面规则。
|
||||
3. 草稿态与发布态 work summary 的字段语义保持不变，继续支持“继续创作”和“进入世界”入口判定。
|
||||
4. `runtimeRoutes.ts` 中的 works/library/gallery 路由已切到 `rpgWorldWorkSummaryService` 与 `rpgWorldProfileRepository` 直接注入，不再经由 `runtimeRepository` 中转 custom world 读模型。
|
||||
|
||||
## 3. 验证结果
|
||||
|
||||
本次已完成以下定向回归：
|
||||
|
||||
1. 运行 `node --test --test-concurrency=1 --import tsx src/services/customWorldAgentPhase2.test.ts src/services/customWorldAgentPhase3.test.ts src/services/customWorldAgentPhase4.test.ts src/services/customWorldAgentPhase5.test.ts src/services/customWorldWorkSummaryService.integration.test.ts`
|
||||
2. 以上 21 个 custom world / agent / works 相关测试全部通过。
|
||||
|
||||
同时确认：
|
||||
|
||||
1. 全量 `npx tsc -p server-node/tsconfig.json --noEmit` 当前仍被仓库里既有的跨模块类型问题阻塞。
|
||||
2. 这些全量类型错误大多与本工作包无关，因此本轮仍以 custom world 定向测试通过作为主验证口径。
|
||||
3. 工作包 F 本轮新增的 `RpgWorldWorkSummaryService.ts`、新仓储注入链和测试 helper，未在定向回归中引入新的行为回归。
|
||||
|
||||
## 4. 当前兼容保留项
|
||||
|
||||
以下内容属于阶段性兼容保留，不再视为工作包 F 未完成项：
|
||||
|
||||
1. `RuntimeRepositoryPort` 仍保留 custom world 相关兼容方法，避免一次性冲击 story/runtime 其他调用方。
|
||||
2. `customWorldAgentSessionStore.ts`、`customWorldWorkSummaryService.ts` 仍保留旧文件名 façade，后续统一命名治理时再清理。
|
||||
3. runtime 快照同步与 custom world profile 自动回写的进一步解耦，仍留待后续围绕 `runtimeRepository.ts` 继续收口。
|
||||
|
||||
## 5. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 E 可以在不继续挤压 `customWorldAgentSessionStore.ts` 的情况下，把 orchestrator 的 result sync / snapshot builder 接到更清晰的 session 持久化边界。
|
||||
2. 工作包 G 后续若需要让 preview compiler / publish gate 落库，不必再继续往 `runtimeRepository.ts` 堆 custom world SQL。
|
||||
3. 工作包 H 已能直接围绕 `rpg-agent-session-store/`、`RpgWorldWorkSummaryAssembler.ts`、`RpgWorldWorkSummaryService.ts` 与新仓储端口补充更细粒度回归，而不必穿透大文件。
|
||||
4. 后续若继续拆 route 命名或清理旧 façade，已有 `context -> server -> runtimeRoutes -> script -> tests` 的新仓储注入链可直接复用。
|
||||
@@ -0,0 +1,92 @@
|
||||
# 创作链路重构工作包 G 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次落实 `CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 G：后端 preview compiler 与 runtime profile 目录化**，并把目录化拆分推进到文档目标结构：
|
||||
|
||||
1. 先把 `runtimeProfile.ts` 退化成兼容 façade。
|
||||
2. 把 `runtime-profile/` 真正拆成 `normalize/build/schema/creatorIntentBridge` 等独立模块。
|
||||
3. 把服务端 result preview compiler 从 foundation draft 流程中抽出独立入口。
|
||||
4. 不直接改路由层，不直接接前端结果页。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 runtime profile 已完成目录化完整拆分
|
||||
|
||||
已完成以下结构调整：
|
||||
|
||||
1. 新增 `server-node/src/modules/custom-world/runtime-profile/index.ts` 作为目录入口。
|
||||
2. 原 `server-node/src/modules/custom-world/runtimeProfile.ts` 已退化为兼容 façade，只负责 re-export。
|
||||
3. `server-node/src/modules/custom-world/runtime-profile/runtimeProfileCompiler.ts` 已退化为兼容 façade，不再承载主实现。
|
||||
4. 已新增并落地以下目标模块：
|
||||
1. `normalizeShared.ts`
|
||||
2. `normalizeRole.ts`
|
||||
3. `normalizeLandmark.ts`
|
||||
4. `normalizeSceneChapter.ts`
|
||||
5. `normalizeCamp.ts`
|
||||
6. `buildCompiledProfile.ts`
|
||||
7. `buildAttributeSchema.ts`
|
||||
8. `creatorIntentBridge.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. 先保证旧导入路径不失效，避免放大工作包 G 首轮改动范围。
|
||||
2. 新代码优先改走 `runtime-profile/` 目录入口。
|
||||
3. `runtimeProfile.ts` 与 `runtimeProfileCompiler.ts` 后续只允许继续收缩，不再接受新增主逻辑。
|
||||
|
||||
## 2.2 服务端 preview compiler 已从 foundation draft 流程中抽出
|
||||
|
||||
已完成以下收口：
|
||||
|
||||
1. `server-node/src/services/RpgWorldPreviewCompiler.ts` 不再只是别名导出，已提供：
|
||||
1. `buildRpgWorldPreviewProfile()`
|
||||
2. `normalizeRpgWorldPreviewProfile()`
|
||||
3. `buildRpgWorldPreviewEnvelope()`
|
||||
4. `normalizeRpgWorldPreviewEnvelope()`
|
||||
2. `packages/shared/src/contracts/rpgCreationPreview.ts` 已补 `RpgCreationPreviewSource`，把 preview 来源语义显式化。
|
||||
3. `customWorldAgentFoundationDraftService.ts` 已把 LLM foundation draft 主生成链改成“直接组装 foundation draft + 单独保留 `legacyResultProfile` 兼容快照”，不再通过 preview compiler 反解草稿主字段。
|
||||
|
||||
这轮的边界变化是：
|
||||
|
||||
1. foundation draft 主字段已经不再依赖“先编 legacy runtime profile，再转回 draft”的双重编译。
|
||||
2. `legacyResultProfile` 仍保留，但只作为结果页兼容快照，不再主导 foundation draft 生成。
|
||||
3. “服务端 preview 编译入口”继续独立存在，并在 Phase 5 后补上 `rpgCreationPreviewProfileBuilder.ts`，统一承接 preview 与 publish 的兼容合并规则。
|
||||
4. preview source 已在 Phase 5 后正式收口为 `session_preview`，不再继续沿用兼容期的 `legacy_custom_world_profile` 标记。
|
||||
|
||||
## 2.3 已补最小测试与目录化回归验证
|
||||
|
||||
本次新增：
|
||||
|
||||
1. `server-node/src/services/RpgWorldPreviewCompiler.test.ts`
|
||||
2. `server-node/src/services/customWorldAgentFoundationDraftService.test.ts`
|
||||
|
||||
当前覆盖重点：
|
||||
|
||||
1. 验证 preview compiler 可以输出服务端兼容预览 envelope。
|
||||
2. 验证 envelope 的 `source` 保持为 `session_preview`。
|
||||
3. 验证 preview profile 仍保留 runtime 编译生成的关键字段，例如 `scenarioPackId`、`campaignPackId`。
|
||||
4. 验证 Phase 5 新增的 preview builder 可以在服务端保留 `legacyResultProfile` 富字段并合并最新草稿资产。
|
||||
5. 验证 foundation draft service 的 LLM 路径已经直接生成 draft 主字段，不再依赖 preview compiler 反解。
|
||||
6. 验证 `runtimeProfile.ts` façade 在目录化拆分后仍保持旧调用兼容。
|
||||
|
||||
本轮额外验证已通过：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `node --test --test-concurrency=1 --import tsx server-node/src/services/customWorldAgentFoundationDraftService.test.ts server-node/src/modules/custom-world/runtimeProfile.test.ts server-node/src/services/RpgWorldPreviewCompiler.test.ts`
|
||||
|
||||
## 3. 本次刻意没有做的事
|
||||
|
||||
以下内容仍留给后续阶段：
|
||||
|
||||
1. 还没有让 `RpgWorldPreviewCompiler` 输出真正独立于 legacy profile 的 preview view model。
|
||||
2. 还没有把 `RpgWorldPreviewCompiler` 的 preview 载体从当前 runtime-profile 兼容对象升级成真正独立的 preview view model。
|
||||
3. `legacyResultProfile` 仍保留为兼容快照，结果页与自动保存链还没有完全脱离 legacy profile 富字段。
|
||||
4. 还没有删除 `runtimeProfile.ts`、`runtimeProfileCompiler.ts` 这两个兼容 façade。
|
||||
|
||||
## 4. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 E 可以围绕 `RpgWorldPreviewCompiler` 继续补 result sync / snapshot builder 的 preview 接口。
|
||||
2. 工作包 H 可以基于 `RpgCreationPreviewEnvelope` 继续细化正式 preview contract 和 contract tests。
|
||||
3. Phase 3 把结果页切到服务端 preview 时，已经有稳定的后端编译入口和目录化 normalize/build 模块，不需要再回头拆 `runtimeProfile.ts` 大文件。
|
||||
@@ -0,0 +1,137 @@
|
||||
# 创作链路重构工作包 H 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次落实 `CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 H：共享契约与测试基建**，约束如下：
|
||||
|
||||
1. 把 RPG 创作域共享契约从“类型别名骨架”推进到“真实定义 + 兼容出口”。
|
||||
2. 补齐可复用的 fixture，避免前后端测试继续各自复制一套假数据。
|
||||
3. 补齐 unit / contract / integration / regression 最小闭环，不越界重构 UI、路由和仓储主逻辑。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 共享契约已完成物理拆分与兼容收口
|
||||
|
||||
本轮已把以下文件从工作包 A 的骨架态推进为真实定义：
|
||||
|
||||
1. `packages/shared/src/contracts/rpgAgentAnchors.ts`
|
||||
2. `packages/shared/src/contracts/rpgAgentDraft.ts`
|
||||
3. `packages/shared/src/contracts/rpgAgentActions.ts`
|
||||
4. `packages/shared/src/contracts/rpgAgentSession.ts`
|
||||
5. `packages/shared/src/contracts/rpgCreationPreview.ts`
|
||||
6. `packages/shared/src/contracts/rpgCreationWorkSummary.ts`
|
||||
|
||||
本轮收口重点：
|
||||
|
||||
1. `rpgAgent*` 与 `rpgCreation*` 文件不再只是从旧 `customWorldAgent.ts` 做类型别名转发，而是承载真实契约定义。
|
||||
2. `rpgAgentSession.ts` 已显式加入 `supportedActions?` 与 `resultPreview?` 可选字段，为工作包 E/G 后续正式接入 registry 与服务端 preview compiler 预留稳定契约入口。
|
||||
3. `rpgCreationPreview.ts` 已补 `source / generatedAt / qualityFindings / blockers`，把“预览载体”和“预览来源/质量门槛”拆开。
|
||||
4. `rpgCreationWorkSummary.ts` 已收口 works 列表稳定字段，明确 `canResume / canEnterWorld` 的读模型语义。
|
||||
|
||||
## 2.2 旧 `customWorld*` 契约已补齐兼容分文件
|
||||
|
||||
本轮没有直接删除旧入口，而是把旧命名收口成“聚合出口 + 分文件兼容层”：
|
||||
|
||||
1. 当前旧 `customWorldAgent.ts` 不再承载主定义，而是统一聚合：
|
||||
- `customWorldAgentAnchors.ts`
|
||||
- `customWorldAgentDraft.ts`
|
||||
- `customWorldAgentActions.ts`
|
||||
- `customWorldAgentSession.ts`
|
||||
- `customWorldResultPreview.ts`
|
||||
- `customWorldWorkSummary.ts`
|
||||
2. 现有前后端直接导入 `customWorldAgent.ts` 的代码不需要在本轮一起大改，避免把工作包 H 扩成全仓导入迁移。
|
||||
3. 后续工作包可以逐步把新代码改到 `rpgAgent* / rpgCreation*` 路径；如果暂时仍需旧命名，也可以先切到更细的兼容分文件，而不是继续依赖单一大聚合文件。
|
||||
|
||||
## 2.3 已补共享 fixture，总线样本开始统一
|
||||
|
||||
本轮新增：
|
||||
|
||||
1. `packages/shared/src/contracts/rpgCreationFixtures.ts`
|
||||
|
||||
当前已提供并复用的样本包括：
|
||||
|
||||
1. 八锚点 fixture
|
||||
2. foundation draft fixture
|
||||
3. session snapshot fixture
|
||||
4. preview envelope fixture
|
||||
5. published profile fixture
|
||||
6. library entry fixture
|
||||
7. works response fixture
|
||||
|
||||
这些样本的作用是：
|
||||
|
||||
1. 前端 contract test、后端 integration test、后续 preview/compiler 回归可以共用同一批样本。
|
||||
2. 避免继续在各测试文件里手写不一致的 session/profile/works 假数据。
|
||||
3. 把工作包 H 文档中要求的“最小 eight-anchor / preview / published profile / works 样本”先落成统一入口。
|
||||
|
||||
## 2.4 已补 unit / contract / integration / regression 最小闭环
|
||||
|
||||
本轮新增测试：
|
||||
|
||||
1. `packages/shared/src/contracts/rpgContracts.test.ts`
|
||||
2. `server-node/src/services/customWorldWorkSummaryService.integration.test.ts`
|
||||
3. `server-node/src/services/RpgWorldPreviewCompiler.fixture.test.ts`
|
||||
4. `server-node/src/services/RpgWorldWorkSummaryAssembler.fixture.test.ts`
|
||||
5. `server-node/src/services/customWorldAgentActionRegistry.test.ts`
|
||||
6. `server-node/src/services/customWorldAgentResultSyncService.test.ts`
|
||||
|
||||
同时补充：
|
||||
|
||||
1. `vitest.config.ts` 已把 `packages/shared/src/**/*.test.ts` 纳入前端 Vitest 测试入口。
|
||||
2. shared contract test 当前覆盖：
|
||||
- session fixture、preview fixture、published profile fixture、works/library fixture 对齐关系
|
||||
- `supportedActions` 能力矩阵样本
|
||||
- 旧命名兼容分文件的类型消费
|
||||
- 角色动作资产、分幕背景、works 门槛字段不会在 fixture 演进时悄悄回退
|
||||
3. server unit / regression test 当前覆盖：
|
||||
- preview compiler 可以直接消费 shared fixture
|
||||
- works assembler 输出与 shared works fixture 保持一致
|
||||
- 角色主图、动作集、分幕背景资产字段在 normalize / assemble 后仍能保留
|
||||
- action registry 的 capability enable/disable 与 payload validate/normalize
|
||||
- result sync service 只回写摘要与匹配资产，不让 runtime-only 结构反向污染 foundation draft
|
||||
4. server integration test 当前验证共享 fixture 可以被 `customWorldWorkSummaryService` 正常消费，并输出和共享 works 响应样本一致的草稿/发布条目。
|
||||
|
||||
## 2.5 根导出已补齐
|
||||
|
||||
本轮已把：
|
||||
|
||||
1. `packages/shared/src/contracts/rpgCreationFixtures.ts`
|
||||
2. `packages/shared/src/contracts/customWorldAgent.ts`
|
||||
|
||||
接入：
|
||||
|
||||
1. `packages/shared/src/index.ts`
|
||||
|
||||
这样后续前端和后端若要消费共享 fixture 或新契约，不需要再回退到旧单文件入口。
|
||||
|
||||
## 3. 本次验证结果
|
||||
|
||||
已完成以下定向验证：
|
||||
|
||||
1. `npm run test -- packages/shared/src/contracts/rpgContracts.test.ts`
|
||||
2. `node --test --test-concurrency=1 --import tsx src/services/customWorldAgentActionRegistry.test.ts src/services/customWorldAgentResultSyncService.test.ts src/services/customWorldWorkSummaryService.integration.test.ts src/services/RpgWorldPreviewCompiler.fixture.test.ts src/services/RpgWorldWorkSummaryAssembler.fixture.test.ts`
|
||||
3. `npm run check:encoding`
|
||||
|
||||
验证重点：
|
||||
|
||||
1. shared 契约样本可直接通过 Vitest 执行。
|
||||
2. preview compiler、works assembler、works service 三层都可以直接消费 shared fixture，不需要额外复制一套测试数据。
|
||||
3. 中文文档与代码文件经过编码检查，没有把文本写坏。
|
||||
|
||||
## 4. 本次刻意未做的事
|
||||
|
||||
以下内容明确留给后续工作包或下一轮继续推进：
|
||||
|
||||
1. 还没有把仓库里所有 `customWorldAgent.ts` 旧导入物理迁成 `rpgAgent* / rpgCreation*` 新导入。
|
||||
2. 还没有让后端 session snapshot 真正填充 `supportedActions`。
|
||||
3. 还没有让服务端 preview compiler 真正把 `resultPreview` 写入主链 snapshot。
|
||||
4. 没有改 UI、路由、数据库仓储或 orchestrator 主逻辑，严格控制在 shared contracts 与测试基建写入边界内。
|
||||
|
||||
## 5. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 E 可以直接复用 `supportedActions` 契约入口，把 action registry 的真实能力矩阵接进 session snapshot。
|
||||
2. 工作包 G 可以直接复用 `resultPreview` 和 `RpgCreationPreviewEnvelope`，继续把服务端 preview compiler 接回主链。
|
||||
3. 后续前后端测试都可以从 shared fixture 取样本，不需要继续维护多套彼此漂移的 session/profile 假数据。
|
||||
4. 旧命名导入可以先切到兼容分文件，再逐步替换到 `rpg*` 新契约，迁移路径更平滑。
|
||||
36
docs/technical/CREATION_PAGE_MOBILE_UI_FIX_2026-04-21.md
Normal file
36
docs/technical/CREATION_PAGE_MOBILE_UI_FIX_2026-04-21.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# 创作页移动端 UI 修复记录
|
||||
|
||||
日期：`2026-04-21`
|
||||
|
||||
## 问题定位
|
||||
|
||||
本轮修复只处理创作页表现层，不新增创作流程。
|
||||
|
||||
当前移动端问题主要来自三处：
|
||||
|
||||
1. 平台页在 `platformTab === 'create'` 时直接渲染 `CustomWorldCreationHub`，绕过了 `PlatformHomeView` 的移动端外壳，导致底部 Tab 栏没有挂载。
|
||||
2. 创作中心内部仍混用 `pixel-*` 九宫格样式、`bg-black/*`、`text-white`、`border-white/*` 等暗色 Tailwind 类，亮色主题下会出现深色块和低对比文字。
|
||||
3. 创作中心根节点自带 `h-full overflow-y-auto`，放回平台页后容易与平台页主滚动区抢滚动权，手机上会显得布局混乱。
|
||||
|
||||
## 落地约束
|
||||
|
||||
1. 创作页仍复用现有平台首页，不新增页面和新系统。
|
||||
2. 移动端底部 Tab 必须始终由 `PlatformHomeView` 统一渲染，创作页只作为 `create` Tab 的内容。
|
||||
3. 创作中心内部不再使用深色硬编码作为默认底色，普通卡片、筛选 Tab、空状态和按钮统一使用 `platform-*` token。
|
||||
4. 创作中心不再自建整页滚动，只把内容交给平台页主滚动区，避免嵌套滚动。
|
||||
5. UI 中不增加规则说明类文案，只保留必要入口、状态和作品信息。
|
||||
|
||||
## 编码方案
|
||||
|
||||
1. 在 `PlatformHomeView` 增加可选的 `createTabContent`，让当前 Agent 创作中心接回平台页统一外壳。
|
||||
2. `PreGameSelectionFlow` 不再在 `platformTab === 'create'` 时绕过 `PlatformHomeView`，而是把 `CustomWorldCreationHub` 作为创作 Tab 内容传入。
|
||||
3. `CustomWorldCreationHub` 改为无内部整页滚动的内容容器，标题、返回、计数、错误、加载骨架都使用平台 token。
|
||||
4. `CustomWorldCreationStartCard` 与 `CustomWorldWorkCard` 从像素暗色面板切换为平台卡片样式，保留游戏化主视觉但跟随亮暗主题。
|
||||
5. `CustomWorldWorkTabs` 改用 `platform-tab`，并保持横向滚动与清晰选中态。
|
||||
|
||||
## 验收要点
|
||||
|
||||
1. 手机宽度下进入“创作”后，底部“首页 / 创作 / 存档 / 我的”Tab 始终可见。
|
||||
2. 亮色主题下创作页默认卡片不出现大面积黑色底板。
|
||||
3. 创作页只有平台页主内容区滚动，底部 Tab 不随作品列表滚走。
|
||||
4. 桌面端仍可通过左侧平台导航进入创作页。
|
||||
@@ -0,0 +1,115 @@
|
||||
# Agent 创作流四阶段收口检查与旧链清理边界
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
补充修正：`2026-04-21` 本文档的“草稿恢复优先回 Agent 工作区”和“Agent 来源结果页冻结为预览收口层”属于阶段性收口口径，已被 [AGENT_DIALOG_AND_RESULT_REFINEMENT_BOUNDARY_2026-04-21.md](./AGENT_DIALOG_AND_RESULT_REFINEMENT_BOUNDARY_2026-04-21.md) 覆盖。当前主口径是：Agent 对话框只收集八锚点，已有底稿的草稿从创作中心进入结果页继续完善。
|
||||
|
||||
## 1. 结论先行
|
||||
|
||||
当前这条 Agent 创作流已经完成阶段一到阶段三的主要收口。
|
||||
|
||||
阶段四中的“文档清理”已经开始做，但还没有形成独立、完整的新主链审计闭环。
|
||||
|
||||
因此这轮可以执行的清理现在有两类：
|
||||
|
||||
1. 删除已经不再从当前主入口可达的旧 `custom-world/sessions` 世界生成链
|
||||
2. 删除已经完全脱离 `CustomWorldAgentWorkspace` 主链、只剩孤立互相引用与自测覆盖的 `custom-world-agent` 旧面板
|
||||
3. 保留仍在服务 `Agent session` 主链或已保存作品兼容编辑体验的底层能力
|
||||
|
||||
这轮不做：
|
||||
|
||||
1. 不删 `Agent session` 的底层持久化能力
|
||||
2. 不删已保存作品结果页的 legacy 编辑器兼容能力
|
||||
3. 不删 `custom-world/works` 聚合入口
|
||||
|
||||
---
|
||||
|
||||
## 2. 阶段完成度
|
||||
|
||||
### 2.1 阶段一
|
||||
|
||||
已完成。
|
||||
|
||||
证据：
|
||||
|
||||
1. 结果页新增了 `sync_result_profile`
|
||||
2. 结果页编辑后的快照可以回写到 `Agent session`
|
||||
3. 自动保存、返回创作、进入世界都优先走 session 主链
|
||||
|
||||
### 2.2 阶段二
|
||||
|
||||
已完成。
|
||||
|
||||
证据：
|
||||
|
||||
1. 平台创作入口已切到 `custom-world/works`
|
||||
2. 草稿恢复优先回 Agent 工作区
|
||||
3. Agent 结果页不再继续新增旧编辑入口
|
||||
|
||||
### 2.3 阶段三
|
||||
|
||||
已完成。
|
||||
|
||||
证据：
|
||||
|
||||
1. 创作中心不再把 library draft 当主草稿入口
|
||||
2. Agent 来源结果页冻结为预览收口层
|
||||
3. 重复同步动作已收敛为有差异才执行
|
||||
|
||||
### 2.4 阶段四
|
||||
|
||||
未完全完成。
|
||||
|
||||
原因：
|
||||
|
||||
1. 文档清理已经开始，但还没有完整收束到单一结论文档
|
||||
2. 旧 `custom-world/sessions` 生成链已经完成物理清理，但与之相关的审计/PRD/知识图谱文档仍需继续统一口径
|
||||
3. `custom-world-agent` 孤岛面板已经完成第二轮物理清理，但阶段四文档总收口仍未完全覆盖所有历史 PRD 口径
|
||||
|
||||
---
|
||||
|
||||
## 3. 本轮允许删除的旧链
|
||||
|
||||
允许删除：
|
||||
|
||||
1. `src/services/aiService.ts` 里的旧 `custom-world/sessions` 请求函数
|
||||
2. `server-node/src/routes/runtimeRoutes.ts` 里的旧 `custom-world/sessions` 路由
|
||||
3. `server-node/src/services/customWorldGenerationService.ts`
|
||||
4. 与这条旧链对应的测试
|
||||
5. `server-node/src/services/customWorldSessionStore.ts`
|
||||
6. `src/components/custom-world-agent/CustomWorldAgentLockBar.tsx`
|
||||
7. `src/components/custom-world-agent/CustomWorldAgentQuickActions.tsx`
|
||||
8. `src/components/custom-world-agent/CustomWorldAgentSummaryPanel.tsx`
|
||||
9. `src/components/custom-world-agent/CustomWorldAgentIntentSummaryPanel.tsx`
|
||||
10. `src/components/custom-world-agent/CustomWorldAgentClarificationPanel.tsx`
|
||||
11. `src/components/custom-world-agent/CustomWorldAgentDraftDetailPanel.tsx`
|
||||
12. `src/components/custom-world-agent/CustomWorldDraftCardDetailModal.tsx`
|
||||
13. `src/components/custom-world-agent/CustomWorldDraftEditPanel.tsx`
|
||||
14. `src/components/custom-world-agent/CustomWorldGenerateEntityModal.tsx`
|
||||
15. 仅为上述孤岛面板存在的对应测试文件
|
||||
|
||||
不允许删除：
|
||||
|
||||
1. `server-node/src/repositories/runtimeRepository.ts` 中被 Agent session 复用的 session 持久化能力
|
||||
2. `src/services/aiService.ts` 里仍在使用的 `generateCustomWorldProfile` 及其现代封装
|
||||
3. 已保存作品结果页仍在使用的 legacy 编辑器兼容能力
|
||||
4. `src/components/custom-world-agent/CustomWorldAgentWorkspace.tsx` 及其仍在主链上的 5 个子模块：
|
||||
- `CustomWorldAgentHeader`
|
||||
- `EightAnchorProgressBar`
|
||||
- `CustomWorldAgentOperationBanner`
|
||||
- `CustomWorldAgentThread`
|
||||
- `CustomWorldAgentComposer`
|
||||
|
||||
---
|
||||
|
||||
## 4. 删除完成后的判断标准
|
||||
|
||||
如果旧链清理成功，应满足：
|
||||
|
||||
1. `src/services/aiService.ts` 不再暴露旧 `custom-world/sessions` 请求函数
|
||||
2. `server-node/src/routes/runtimeRoutes.ts` 不再挂旧 session 路由
|
||||
3. `server-node/src/services/customWorldSessionStore.ts` 与 `server-node/src/services/customWorldGenerationService.ts` 已物理删除
|
||||
4. 仓库里不再有主流程可达的旧世界生成入口
|
||||
5. `CustomWorldAgentWorkspace.tsx` 只保留当前正式主链需要的 5 个子模块
|
||||
6. 与旧 Agent 草稿面板相关的孤岛 UI 与自测不再继续占据正式目录注意力
|
||||
7. Agent 主链与已保存作品编辑链仍然可用
|
||||
@@ -26,10 +26,6 @@
|
||||
- `GET /api/assets/character-animation/jobs/:taskId`
|
||||
- `POST /api/assets/character-animation/import-video`
|
||||
- `GET /api/assets/character-animation/templates`
|
||||
- `POST /api/assets/qwen-sprite/master`
|
||||
- `POST /api/assets/qwen-sprite/sheet`
|
||||
- `POST /api/assets/qwen-sprite/frame-repair`
|
||||
- `POST /api/assets/qwen-sprite/save`
|
||||
|
||||
---
|
||||
|
||||
@@ -50,7 +46,6 @@
|
||||
- 状态行为覆盖保存
|
||||
- 角色主形象生成、发布与任务查询
|
||||
- 角色动作生成、导入、发布、模板读取与任务查询
|
||||
- Qwen 精灵主图、精灵表、修帧与资产保存
|
||||
|
||||
---
|
||||
|
||||
|
||||
85
docs/technical/EDITOR_ENTRY_CLEANUP_2026-04-21.md
Normal file
85
docs/technical/EDITOR_ENTRY_CLEANUP_2026-04-21.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# 主流程外编辑器入口清理说明（2026-04-21）
|
||||
|
||||
日期：`2026-04-21`
|
||||
|
||||
## 1. 文档目标
|
||||
|
||||
记录本轮对“挂在主流程路由外的旧编辑器入口”和“仍把这些入口当现役能力的残留说明”做的收口，避免后续开发再次把历史入口误判成正式能力。
|
||||
|
||||
---
|
||||
|
||||
## 2. 本轮清理结论
|
||||
|
||||
本轮确认后，当前前端正式入口只保留游戏主流程：
|
||||
|
||||
- `src/routing/appRoutes.tsx` 仅保留 `game`
|
||||
|
||||
本轮删除或收口的对象：
|
||||
|
||||
- 独立前端工具路由 `qwen-sprite-tool`
|
||||
- 仅服务该独立入口的前端页面 `src/tools/QwenSpriteSheetTool.tsx`
|
||||
- 仅服务该独立入口的工具模型与持久化封装
|
||||
- 仅服务该独立入口的后端路由 `server-node/src/modules/assets/qwenSpriteRoutes.ts`
|
||||
- 路由测试里把旧编辑器 / 独立工具入口当作现役分支的断言
|
||||
- README、经验文档、类型检查配置中已经失效的旧编辑器文件引用
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么可以删除
|
||||
|
||||
本轮删除对象满足下面几个条件：
|
||||
|
||||
1. 不在当前玩家主流程中可达
|
||||
2. 没有继续嵌入正式创作主链
|
||||
3. 当前仓库已有主流程内嵌的替代能力
|
||||
4. 保留它们只会继续制造“看起来还能进、实际上已经不走”的假入口
|
||||
|
||||
其中需要特别区分的是：
|
||||
|
||||
- `src/editor/shared/editorApiClient.ts`
|
||||
- `server-node/src/modules/editor/editorRoutes.ts`
|
||||
- `src/components/CustomWorldEntityEditorModal.tsx`
|
||||
- `src/components/CustomWorldNpcVisualEditor.tsx`
|
||||
- `src/components/CustomWorldRoleAssetStudioModal.tsx`
|
||||
|
||||
这些仍然服务当前主流程内嵌编辑能力，因此本轮不删除。
|
||||
|
||||
---
|
||||
|
||||
## 4. 当前保留的编辑能力边界
|
||||
|
||||
当前保留的是“嵌入主流程的编辑能力”，不是“独立编辑器站点”：
|
||||
|
||||
- 自定义世界实体编辑
|
||||
- 自定义世界角色形象编辑
|
||||
- 主流程内的角色资产工坊模态
|
||||
- 与这些能力配套的 `/api/editor/*` 与 `/api/assets/character-*` 接口
|
||||
|
||||
后续如果还要新增编辑能力，应优先：
|
||||
|
||||
1. 先确认是否真的需要独立入口
|
||||
2. 默认优先接回主流程模态或正式创作链
|
||||
3. 如果只是内部工具，不要长期挂在正式前端路由里
|
||||
|
||||
---
|
||||
|
||||
## 5. 本轮同步更新
|
||||
|
||||
本轮已同步更新：
|
||||
|
||||
- `README.md`
|
||||
- `docs/experience/CODEX_PAST_WORK_EXPERIENCE_SUMMARY.md`
|
||||
- `src/routing/appRoutes.tsx`
|
||||
- `src/routing/appRoutes.test.ts`
|
||||
- `server-node/src/app.ts`
|
||||
- `tsconfig.typecheck-guardrails.json`
|
||||
|
||||
---
|
||||
|
||||
## 6. 后续建议
|
||||
|
||||
后续继续清理时，优先沿着这条规则推进：
|
||||
|
||||
1. 先识别是否还在主流程可达
|
||||
2. 再判断是否仍有正式嵌入点
|
||||
3. 若只剩文档、测试、兼容判断或独立路由壳，直接成批收口
|
||||
@@ -0,0 +1,188 @@
|
||||
# 前端逻辑后移实施方案（2026-04-21）
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 目标
|
||||
|
||||
本方案只回答一件事：
|
||||
|
||||
**怎样把当前仍残留在前端的正式运行时逻辑、正式会话真相与正式生成编排，继续收回到 Express 后端。**
|
||||
|
||||
这份文档不是泛泛而谈的方向说明，而是直接面向本轮与后续几轮编码落地的实施基线。
|
||||
|
||||
---
|
||||
|
||||
## 2. 本轮确定的硬边界
|
||||
|
||||
根据仓库约束与当前审计结果，本轮继续冻结以下边界：
|
||||
|
||||
1. 前端只负责表现、输入采集、临时 UI 状态与服务端结果渲染。
|
||||
2. 后端负责正式鉴权、正式会话、正式运行时快照、正式任务生成、正式运行时物品意图生成、正式自定义世界生成。
|
||||
3. `codex/backend-rewrite-spacetimedb` 目标分支的鉴权仍以服务端签发 JWT、前端 Bearer token 携带为准；本轮合入不采用 `codex/dev` 的 access cookie 会话方案。
|
||||
4. 浏览器内不再把浏览历史作为本地正式真相，不再保留正式 quest / runtime item / custom world 生成编排。
|
||||
5. 运行时主链必须继续向“前端提交意图，后端解释快照并返回展示模型”收敛。
|
||||
|
||||
---
|
||||
|
||||
## 3. 现状拆分
|
||||
|
||||
当前残留问题已经收敛为三批：
|
||||
|
||||
### 3.1 第一批：正式真相仍在前端
|
||||
|
||||
1. `src/services/apiClient.ts`
|
||||
- 浏览器当前仍保存 access token，并在请求层拼接 `Authorization: Bearer ...`
|
||||
- 该链路在 `codex/backend-rewrite-spacetimedb` 仍是既定正式实现，不再按 cookie access session 改写
|
||||
2. `src/services/authService.ts`
|
||||
- 登录、微信绑定、回调消费流程都要与 JWT/Bearer 方案保持一致，避免混入 access cookie 分支语义
|
||||
3. `src/components/game-shell/PreGameSelectionFlow.tsx`
|
||||
- 浏览历史仍是本地写入 + 后端回填的双真相
|
||||
4. `src/services/platformBrowseHistory.ts`
|
||||
- 维护浏览历史本地存储、迁移标记与同步状态
|
||||
|
||||
### 3.2 第二批：运行时主链仍依赖前端预写快照
|
||||
|
||||
1. `src/hooks/story/runtimeStoryCoordinator.ts`
|
||||
- 在请求 runtime state / runtime action 前，仍先 `PUT /runtime/save/snapshot`
|
||||
2. `src/hooks/story/npcEncounterActions.ts`
|
||||
- 待接委托的“更换任务”“放弃任务”仍由前端正式结算
|
||||
|
||||
### 3.3 第三批：正式生成编排仍残留在浏览器
|
||||
|
||||
1. `src/services/questDirector.ts`
|
||||
2. `src/services/runtimeItemAiDirector.ts`
|
||||
3. `src/services/aiService.ts` 的 custom world profile 生成入口
|
||||
4. `src/services/ai.ts` 中仍保留的浏览器侧 legacy AI orchestration
|
||||
|
||||
---
|
||||
|
||||
## 4. 分批实施策略
|
||||
|
||||
## 4.1 第一批：先收正式真相
|
||||
|
||||
### 鉴权
|
||||
|
||||
目标状态：
|
||||
|
||||
1. 后端继续通过 JWT 承载 access token，并只从 `Authorization: Bearer ...` 读取当前访问身份。
|
||||
2. 前端请求层继续负责保存、刷新和携带 access token；公开请求与静默探测不得误清正式 token。
|
||||
3. access cookie 会话方案不进入 `codex/backend-rewrite-spacetimedb`，避免和目标分支已有 JWT 方案并存。
|
||||
|
||||
本批涉及：
|
||||
|
||||
1. `server-node/src/routes/authRoutes.ts`
|
||||
2. `server-node/src/middleware/auth.ts`
|
||||
3. `src/services/apiClient.ts`
|
||||
4. `src/services/authService.ts`
|
||||
5. `src/components/auth/AuthGate.tsx`
|
||||
|
||||
### 浏览历史
|
||||
|
||||
目标状态：
|
||||
|
||||
1. 浏览历史唯一真相在 `runtimeRepository`。
|
||||
2. 前端不再保留本地浏览历史、迁移标记、同步标记。
|
||||
3. 浏览历史只通过 `storageService` 读取和写入。
|
||||
|
||||
本批涉及：
|
||||
|
||||
1. `src/components/game-shell/PreGameSelectionFlow.tsx`
|
||||
2. `src/components/game-shell/PlatformHomeView.tsx`
|
||||
3. `src/services/storageService.ts`
|
||||
4. `src/services/platformBrowseHistory.ts`
|
||||
|
||||
## 4.2 第二批：把 runtime story 快照解释权收回后端
|
||||
|
||||
目标状态：
|
||||
|
||||
1. 前端不再通过单独的 `PUT /runtime/save/snapshot` 预写快照再触发动作。
|
||||
2. runtime state / runtime action 允许前端提交当前快照上下文，由后端内部决定是否写入、如何解释、何时持久化。
|
||||
3. NPC 待接委托的 replace / abandon / accept 全部走后端 runtime action。
|
||||
|
||||
建议实施方式：
|
||||
|
||||
1. 扩展 `packages/shared/src/contracts/story.ts`
|
||||
- `RuntimeStoryActionRequest` 增加可选 `snapshot`
|
||||
- 新增 `RuntimeStoryStateRequest`
|
||||
2. 新增 `POST /api/runtime/story/state/resolve`
|
||||
3. `storyActionService` 内部统一处理“请求携带快照上下文时的服务端同步”
|
||||
4. 把 `npc_chat_quest_offer_replace` / `npc_chat_quest_offer_abandon` 接到后端 runtime action
|
||||
|
||||
## 4.3 第三批：把正式生成编排收成后端唯一出口
|
||||
|
||||
目标状态：
|
||||
|
||||
1. `questDirector` 只保留轻量 SDK。
|
||||
2. `runtimeItemAiDirector` 只保留轻量 SDK。
|
||||
3. custom world profile 正式生成走后端 route。
|
||||
4. 浏览器侧 `src/services/ai.ts` 不再承担正式浏览器主链。
|
||||
|
||||
建议实施方式：
|
||||
|
||||
1. `server-node/src/routes/runtimeRoutes.ts`
|
||||
- 补 `custom-world/profile` 正式 route
|
||||
2. `src/services/aiService.ts`
|
||||
- custom world 入口改走后端
|
||||
3. `src/services/questDirector.ts`
|
||||
- 只请求 `/api/runtime/quests/generate`
|
||||
4. `src/services/runtimeItemAiDirector.ts`
|
||||
- 只请求 `/api/runtime/items/runtime-intent`
|
||||
|
||||
---
|
||||
|
||||
## 5. 本轮落地范围
|
||||
|
||||
本轮优先完成以下内容：
|
||||
|
||||
1. 鉴权维持 `codex/backend-rewrite-spacetimedb` 既有 JWT/Bearer 方案，不合入 `codex/dev` 的 access cookie 访问认证。
|
||||
2. 浏览历史从前端本地真相后移到后端唯一真相。
|
||||
3. custom world profile 正式生成入口补齐后端 route，并把前端收成 SDK。
|
||||
4. `questDirector` / `runtimeItemAiDirector` 收缩为前端 SDK。
|
||||
5. runtime story contract 开始补“随请求提交快照上下文”的后端承接能力，并把 NPC 待接委托 replace / abandon 接到后端。
|
||||
|
||||
### 5.1 已完成
|
||||
|
||||
1. `codex/backend-rewrite-spacetimedb` 本轮保留 JWT access token + refresh cookie 组合方案，不合入 access cookie 写入与读取链路。
|
||||
2. 浏览历史已收敛为后端唯一真相，前端不再维护正式本地 browse history 链。
|
||||
3. runtime story 已支持随请求提交 snapshot，由后端内部解释与持久化。
|
||||
4. NPC 待接委托 `replace / abandon / accept` 已以后端 runtime action 为准。
|
||||
5. custom world profile 浏览器正式入口已改走后端 route。
|
||||
6. `questDirector` / `runtimeItemAiDirector` 已收缩为前端 SDK，不再承担正式浏览器编排。
|
||||
7. NPC 招募正式结算已迁到后端：
|
||||
- 前端只负责招募对白展示与 release 目标选择
|
||||
- 后端负责 `npcStates / companions / roster / currentEncounter / storyHistory` 正式结算
|
||||
- 满员换队招募已由后端承接
|
||||
|
||||
### 5.2 剩余未完成
|
||||
|
||||
1. `src/services/ai.ts` 仍保留 legacy fallback / test 能力，尚未彻底压缩出正式浏览器主链。
|
||||
2. 仍需继续审视是否存在其他 NPC / 运行时分支，把正式状态裁决留在前端。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收标准
|
||||
|
||||
### 第一批验收
|
||||
|
||||
1. 浏览器继续保存 access token，并由 `fetchWithApiAuth` 稳定拼接 `Authorization: Bearer ...`。
|
||||
2. 401 刷新链只在已发送 Bearer token 时触发，并且刷新响应必须返回新的 JWT。
|
||||
3. 浏览历史仅通过远端接口读写。
|
||||
4. `src/services/platformBrowseHistory.ts` 不再是正式链路依赖。
|
||||
|
||||
### 第二批验收
|
||||
|
||||
1. `runtimeStoryCoordinator.ts` 不再在动作前独立 `PUT /runtime/save/snapshot`。
|
||||
2. `NPC` 待接委托 replace / abandon / accept 都以后端返回结果为准。
|
||||
|
||||
### 第三批验收
|
||||
|
||||
1. `questDirector.ts` 与 `runtimeItemAiDirector.ts` 不再保留正式 fallback orchestration。
|
||||
2. custom world profile 的浏览器正式入口不再直接 import legacy `./ai`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话结论
|
||||
|
||||
这轮迁移的重点不是“把几个 helper 挪到 server-node 目录”，而是：
|
||||
|
||||
**把前端里仍然承担正式真相、正式运行时解释和正式生成编排的那一层职责，继续收回到 Express 后端。**
|
||||
@@ -150,10 +150,11 @@ JWT 现状：
|
||||
- `POST /api/custom-world/scene-image`
|
||||
- `POST /api/runtime/story/initial`
|
||||
- `POST /api/runtime/story/continue`
|
||||
- `POST /api/runtime/custom-world/sessions`
|
||||
- `GET /api/runtime/custom-world/sessions/:sessionId`
|
||||
- `POST /api/runtime/custom-world/sessions/:sessionId/answers`
|
||||
- `GET /api/runtime/custom-world/sessions/:sessionId/generate/stream`
|
||||
- `POST /api/runtime/custom-world/agent/sessions`
|
||||
- `GET /api/runtime/custom-world/agent/sessions/:sessionId`
|
||||
- `POST /api/runtime/custom-world/agent/sessions/:sessionId/messages`
|
||||
- `POST /api/runtime/custom-world/agent/sessions/:sessionId/actions`
|
||||
- `GET /api/runtime/custom-world/works`
|
||||
- `POST /api/runtime/chat/character/suggestions`
|
||||
- `POST /api/runtime/chat/character/summary`
|
||||
- `POST /api/runtime/chat/character/reply/stream`
|
||||
@@ -183,10 +184,6 @@ JWT 现状：
|
||||
- `GET /api/assets/character-animation/jobs/:taskId`
|
||||
- `POST /api/assets/character-animation/import-video`
|
||||
- `GET /api/assets/character-animation/templates`
|
||||
- `POST /api/assets/qwen-sprite/master`
|
||||
- `POST /api/assets/qwen-sprite/sheet`
|
||||
- `POST /api/assets/qwen-sprite/frame-repair`
|
||||
- `POST /api/assets/qwen-sprite/save`
|
||||
|
||||
编辑器与资产接口门禁：
|
||||
|
||||
@@ -227,9 +224,7 @@ Custom World：
|
||||
编辑器与资产工具层：
|
||||
|
||||
- `src/editor/shared/editorApiClient.ts`
|
||||
- `src/editor/shared/useJsonSave.ts`
|
||||
- `src/components/preset-editor/characterAssetStudioPersistence.ts`
|
||||
- `src/tools/qwenSpriteSheetToolPersistence.ts`
|
||||
|
||||
## 10. 当前 Vite 角色
|
||||
|
||||
|
||||
@@ -11,7 +11,6 @@
|
||||
- `server-node/src/services/eightAnchorPromptBuilder.ts`
|
||||
- `server-node/src/modules/assets/characterAssetRoutes.ts`
|
||||
- `src/services/**`
|
||||
- `src/tools/qwenSpriteSheetToolModel.ts`
|
||||
- `src/components/**`
|
||||
|
||||
问题主要有三类：
|
||||
@@ -50,7 +49,6 @@ src/prompts/
|
||||
├─ customWorldPrompts.ts
|
||||
├─ customWorldRolePromptDefaults.ts
|
||||
├─ questPrompts.ts
|
||||
├─ qwenSpriteSheetToolPrompts.ts
|
||||
├─ runtimeItemPrompts.ts
|
||||
├─ storyOrchestratorPrompts.ts
|
||||
└─ storyPromptBuilders.ts
|
||||
@@ -82,8 +80,6 @@ src/prompts/
|
||||
- 八锚点状态推断、模式规则与正式单轮共创 prompt
|
||||
- `src/prompts/customWorldPrompts.ts`
|
||||
- 自定义世界分阶段生成 prompt 与场景背景图 prompt
|
||||
- `src/prompts/qwenSpriteSheetToolPrompts.ts`
|
||||
- 精灵图工具主词 / 分镜词 / 修帧词 / 负面词
|
||||
- `src/prompts/customWorldRolePromptDefaults.ts`
|
||||
- 角色资产工作台默认 prompt 种子唯一主源
|
||||
- `src/prompts/customWorldEntityActionPrompts.ts`
|
||||
@@ -127,7 +123,6 @@ src/prompts/
|
||||
- `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`
|
||||
|
||||
|
||||
@@ -676,7 +676,7 @@ PixelMotion 很关键的一点，不是要求 16 帧都完美，而是允许修
|
||||
### 13.4 推荐目录结构
|
||||
|
||||
```text
|
||||
pixelmotion-qwen/
|
||||
pixelmotion-workflow/
|
||||
refs/
|
||||
master.png
|
||||
pose_board_run.png
|
||||
|
||||
@@ -30,11 +30,39 @@
|
||||
- [M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md](./M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md)：冻结 M6 剩余的 STS 与服务端上传 helper 落地口径，明确当前上传主链为服务器上传 OSS，Web 端只负责签名读下载。
|
||||
- [AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md](./AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md)：冻结 `POST /api/assets/objects/confirm` 从 Axum 通过 Rust SDK 调用 `SpacetimeDB procedure` 的最小落地方案，明确本地 server、数据库名、procedure/reducer 分工与 `spacetime-client` 边界。
|
||||
- [ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md](./ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md)：冻结已确认 `asset_object` 绑定到业务实体槽位的首版 reducer/procedure、通用 `asset_entity_binding` 表与 Axum facade。
|
||||
- [FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md](./FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md)：把鉴权、浏览历史、runtime story 快照、NPC 待接委托与正式生成编排继续后移到 Express 后端的实施方案与验收口径。
|
||||
- [REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md](./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md)：落实工程清理审计第一阶段后的仓库噪音清理范围、忽略规则闭合点与后续约束。
|
||||
- [PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md](./PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md)：后端提示词收口到 `server-node/src/prompts/` 的目录方案、兼容策略与后续新增规则。
|
||||
- [CUSTOM_WORLD_DRAFT_GENERATION_FAILURE_ANALYSIS_AND_FIX_2026-04-20.md](./CUSTOM_WORLD_DRAFT_GENERATION_FAILURE_ANALYSIS_AND_FIX_2026-04-20.md)：世界草稿生成失败后等待页误显示为“卡在编译草稿卡”的根因拆解、主链与增强链路边界，以及本次修复策略。
|
||||
- [CUSTOM_WORLD_AUTO_ASSET_VISIBILITY_FIX_2026-04-20.md](./CUSTOM_WORLD_AUTO_ASSET_VISIBILITY_FIX_2026-04-20.md)：世界草稿里“资产已生成但结果页看不到”的根因拆解，包含角色主形象展示、分幕背景露出和 fallback 资源格式修复。
|
||||
- [CUSTOM_WORLD_PHASE4_COUNT_SEMANTICS_ALIGNMENT_2026-04-20.md](./CUSTOM_WORLD_PHASE4_COUNT_SEMANTICS_ALIGNMENT_2026-04-20.md)：Phase4 新增角色/地点后草稿作品卡数量统计与测试断言的语义对齐说明。
|
||||
- [AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md](./AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md)：阶段一保持结果页深度编辑能力不变，同时把结果页完整世界快照同步回 Agent session 主链的方案说明。
|
||||
- [AGENT_RESULT_PROFILE_SYNC_PHASE2_2026-04-20.md](./AGENT_RESULT_PROFILE_SYNC_PHASE2_2026-04-20.md)：阶段二把平台创作入口统一到聚合作品列表，并收紧 Agent 结果页的新增入口职责边界。
|
||||
- [AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md](./AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md)：阶段三继续降级旧 pipeline，让创作中心只认 Agent 草稿与已发布作品，并把 Agent 结果页冻结为预览收口层。
|
||||
- [AGENT_DIALOG_AND_RESULT_REFINEMENT_BOUNDARY_2026-04-21.md](./AGENT_DIALOG_AND_RESULT_REFINEMENT_BOUNDARY_2026-04-21.md)：修正 Agent 对话框与结果页职责边界，明确 Agent 只收集八锚点，已有底稿的精修进入结果页完成。
|
||||
- [CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md](./CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md)：对照当前优化计划核查四阶段完成度，并明确这轮只允许物理删除旧 `custom-world/sessions` 世界生成链，不误伤 Agent 主链与已保存作品兼容编辑链。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)：梳理当前创作入口到结果页自动保存再到进入世界的全链前后端脚本地图，并给出文件级重构拆分方案、目标分层与阶段验收标准。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)：梳理当前 RPG 从平台入口、继续游戏、角色选择到营地开场、冒险运行态与 runtime story 后端结算的全链脚本地图，并给出 RPG 专属命名规范、目标分层和可并行执行的工作包。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_A_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_A_PROGRESS_2026-04-21.md)：记录 RPG 进入游戏与运行时链路工作包 A 已完成的新目录骨架、前后端 façade、按域路由 path 常量与兼容仓储入口。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_B_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_B_PROGRESS_2026-04-21.md)：记录工作包 B 已完成的前端 RPG 入口壳层真实迁移、`rpg-entry` 新入口 hooks 收口，以及旧 `game-shell` / `rpg-creation-flow` 路径降级为兼容层的状态。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_C_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_C_PROGRESS_2026-04-21.md)：记录工作包 C 已完成的 `rpg-session` 主链迁移、snapshot / save archive client 收口、旧 `useGame*` 降级为兼容 façade，以及定向回归结果。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_D_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_D_PROGRESS_2026-04-21.md)：记录工作包 D 已完成的前端运行态 shell / stage router / panel router 真实迁移、AdventurePanel section 拆分，以及旧 `GameShell*` 热点降级为兼容桥的现状。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_F_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_F_PROGRESS_2026-04-21.md)：记录 RPG 进入游戏与运行时链路工作包 F 已完成的后端 route 真正拆边界、`app.ts` 新域挂载、旧 `runtimeRoutes` / `storyActionRoutes` 兼容降级，以及定向路由回归验证结果。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md)：记录工作包 E 已完成的前端 runtime story 主链真实迁移、NPC 交互与 gateway/client 收口、旧入口兼容降级，以及定向回归验证结果。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md)：记录工作包 G 已完成的后端 runtime session / action service 物理迁移、新域原语导出、旧热点兼容降级，以及定向 runtime story 回归验证结果。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md)：记录工作包 H 已完成的 RPG 运行时仓储拆分、shared runtime contract 分文件、旧 `story.ts` façade 兼容与定向回归结果。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PARALLEL_BATCH_AUDIT_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PARALLEL_BATCH_AUDIT_2026-04-21.md)：对照执行计划逐项复核第一批与第二批并行工作的真实落地状态，记录本轮确认到的测试合流收口遗漏与文档索引补齐结果。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PHASE3_CLOSURE_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PHASE3_CLOSURE_2026-04-21.md)：记录 RPG 执行计划第三批收口已完成的前端新域主链接回、后端新仓储接线、shared contract 直连收紧、旧兼容脚本物理删除，以及明确未扩到 UI 和无关历史文档的边界。
|
||||
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_OLD_SCRIPT_REMOVAL_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_OLD_SCRIPT_REMOVAL_2026-04-21.md)：记录 RPG 主链旧 `GameShell`、`useGame*`、`hooks/story`、`runtimeRoutes`、`modules/story/*`、`contracts/story.ts` 脚本的物理删除范围、残留依赖扫描和定向验证结果。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_A_PROGRESS_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_A_PROGRESS_2026-04-21.md)：记录创作链路重构工作包 A 已落地的 RPG 创作域目录骨架、兼容 façade，以及补齐后的共享契约骨架入口。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md)：记录工作包 E 已完成的后端 Agent 编排拆分、executor 物理迁移、发布链切到 `CustomWorldAgentPublishingService`、checkpoint 真快照、场景资产 coverage 收口，以及 Phase3/Phase5 定向回归结果。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md)：记录工作包 H 已完成的共享契约物理拆分、旧命名兼容分文件、统一 fixture，以及 shared contract test / preview compiler / works assembler / works service 回归基建。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_B_PROGRESS_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_B_PROGRESS_2026-04-21.md)：记录工作包 B 已完成的前端平台壳层编排拆分、平台 hooks / coordinator 接入、旧入口兼容保留，以及交互回归验证结果。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_F_PROGRESS_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_F_PROGRESS_2026-04-21.md)：记录工作包 F 已完成的后端 session/store/repository 拆分、works 读模型 service 收口、route/context 直接注入新仓储，以及定向 custom world 回归验证结果。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_D_PROGRESS_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_D_PROGRESS_2026-04-21.md)：记录工作包 D 已完成的前端 custom world client 真正迁出、旧 service 兼容降级，以及平台壳层/结果页测试切换到 `rpgCreation` 域入口的现状。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md)：记录工作包 G 已完成的 runtime profile 目录化、服务端 preview compiler 收口，以及 foundation draft 主生成链与 preview 编译边界的直接拆开。
|
||||
- [CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md#93-工作包-c前端结果页与编辑器拆分](./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md#93-%E5%B7%A5%E4%BD%9C%E5%8C%85-c%E5%89%8D%E7%AB%AF%E7%BB%93%E6%9E%9C%E9%A1%B5%E4%B8%8E%E7%BC%96%E8%BE%91%E5%99%A8%E6%8B%86%E5%88%86)：记录工作包 C 已完成的结果页壳层拆分、编辑器目标分发与 mapper 收口、角色资产工坊 section/workflow 拆分，以及仍保留的阶段性 shared 实现边界。
|
||||
- [CREATION_PAGE_MOBILE_UI_FIX_2026-04-21.md](./CREATION_PAGE_MOBILE_UI_FIX_2026-04-21.md)：创作页移动端底部 Tab、亮色主题 token 与滚动权责修复记录。
|
||||
- [TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md](./TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md)：把外部仓库 TXT 模式完整迁入当前项目的冻结边界、模块映射、分阶段计划与验收清单。
|
||||
- [NODE_BACKEND_MODULE_AND_API_INDEX.md](./NODE_BACKEND_MODULE_AND_API_INDEX.md)：由 `server-node/src/manifest/backendCapabilityManifest.ts` 生成的 Node 后端模块职责、挂载面与接口索引，后续新增模块/接口时同步更新这一份。
|
||||
- [NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md](./NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md)：当前 Node 运行时后端的技术栈、入口、鉴权、存储与接口知识图谱。
|
||||
|
||||
@@ -0,0 +1,999 @@
|
||||
# RPG 进入游戏与运行时链路重构执行方案
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 0. 文档目标
|
||||
|
||||
本文只处理一件事：
|
||||
|
||||
**把当前 RPG 玩法从“平台入口/继续游戏/世界详情开始游戏”到“角色选择/营地开场/冒险运行态/runtime story 后端动作结算”的整条前后端脚本链路，整理成一份可以直接指导后续并行重构的执行方案。**
|
||||
|
||||
本轮不直接修改业务玩法，不新增需求，只明确：
|
||||
|
||||
1. 当前链路上的真实脚本地图
|
||||
2. 当前命名、目录、边界和可读性问题
|
||||
3. 面向 RPG 类型游戏的专属命名规范
|
||||
4. 目标分层与文件级拆分建议
|
||||
5. 可同时并行推进的工作包与阶段验收标准
|
||||
|
||||
同时补充一条必须冻结的执行约束：
|
||||
|
||||
**本次以及后续按本文推进的 RPG 链路重构，只允许调整脚本结构、命名、职责边界、数据流和兼容 façade，不允许修改任何前端交互界面设计。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 范围与依据
|
||||
|
||||
### 1.1 本文覆盖的 RPG 进入游戏链路
|
||||
|
||||
```text
|
||||
平台首页 / 作品详情 / 继续游戏
|
||||
-> 选择世界或恢复存档
|
||||
-> 角色选择
|
||||
-> 初始化 GameState / Snapshot / Session
|
||||
-> 营地开场
|
||||
-> 冒险运行态 shell
|
||||
-> 冒险面板 / 角色面板 / 背包面板
|
||||
-> runtime story 选项解析与动作结算
|
||||
-> 服务端快照持久化 / 状态回写 / 继续游戏恢复
|
||||
```
|
||||
|
||||
### 1.2 本文主要依据
|
||||
|
||||
1. `docs/prd/AI_NATIVE_SCENE_CHAPTER_GAMEPLAY_PRD_AND_EXECUTION_PLAN_2026-04-08.md`
|
||||
2. `docs/design/SCENE_CHAPTER_LOOP_AND_FIRST_ENTRY_CHAPTER_QUEST_DESIGN_2026-04-08.md`
|
||||
3. `docs/experience/CURRENT_GAME_FULL_FLOW_PLAYTEST_REPORT_2026-04-07.md`
|
||||
4. `docs/technical/RUNTIME_STORY_BACKEND_BOUNDARY_MIGRATION_2026-04-19.md`
|
||||
5. `docs/technical/FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md`
|
||||
6. `docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md`
|
||||
|
||||
### 1.3 本文刻意不覆盖的链路
|
||||
|
||||
本文不处理以下内容：
|
||||
|
||||
1. RPG 创作流程链
|
||||
2. Agent 八锚点共创流程
|
||||
3. 自定义世界结果页编辑器内部资产工坊链
|
||||
4. 非 RPG 平台公共功能的全面改造
|
||||
|
||||
这些内容已有独立文档，本文只关注**进入 RPG 运行态之后的主玩法链**。
|
||||
|
||||
### 1.4 前端界面冻结约束
|
||||
|
||||
本次重构对前端界面的约束必须写死：
|
||||
|
||||
1. 不修改任何前端交互界面设计。
|
||||
2. 不修改现有页面的视觉层级、主布局结构、按钮位置、tab 组织、弹窗/独立面板的出现方式。
|
||||
3. 不以“顺手优化体验”为理由调整入口页、选角页、冒险页、角色页、背包页的交互路径。
|
||||
4. 重构允许做的事情只包括：脚本重命名、目录迁移、hook/service 拆分、view model 收口、后端路由与服务拆分、兼容 façade 搭建。
|
||||
5. 如果个别脚本拆分必须调整 props 传递或组件装配方式，最终渲染结果与交互结果必须和当前版本保持一致。
|
||||
6. 任何会影响 UI 结构、交互节奏、面板开合形式的改动，都不属于本文工作范围，必须另开设计文档与实现任务。
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前链路真实脚本地图
|
||||
|
||||
## 2.1 前端入口与进入世界链
|
||||
|
||||
| 文件 | 当前职责 | 当前问题 |
|
||||
| --- | --- | --- |
|
||||
| `src/App.tsx` | 应用入口，直接挂载 `useGameShellRuntime()` 与 `GameShellRuntime` | 入口极薄，但把“平台入口 + RPG 运行态”全部抽象成 `GameShell`，命名过泛 |
|
||||
| `src/hooks/useGameShellRuntime.ts` | 串起 `useGameFlow`、`useGamePersistence`、`useStoryGeneration`、同伴与音乐逻辑，组装整套运行时 props | 已经是事实上的 RPG 主流程装配器，但命名仍像通用 shell |
|
||||
| `src/hooks/useGameFlow.ts` | 世界选择、角色确认、`GameState` 初始化、营地遭遇创建 | 负责“进入游戏”的核心初始化，但文件名过泛，且把世界选择、选角、开局初始化混在一起 |
|
||||
| `src/hooks/useGamePersistence.ts` | 远端快照加载、自动存档、保存退出、继续游戏恢复 | 快照加载、存档写入、恢复后 runtime story 刷新耦合在同一 hook 中 |
|
||||
| `src/components/game-shell/PreGameSelectionFlow.tsx` | 平台首页、详情页、存档继续、创作入口、进入世界前流程壳层 | 仍承载过多平台级编排，不只负责 RPG 进入游戏链 |
|
||||
| `src/components/game-shell/PlatformHomeView.tsx` | 平台首页、继续游戏、公开广场、存档/个人 tab 表现层 | 视觉层文件过大，且“平台首页”与“RPG 进入游戏入口”没有显式命名边界 |
|
||||
| `src/components/game-shell/PlatformWorldDetailView.tsx` | 世界详情与“开始游戏/继续创作/发布”等操作 | `开始游戏` 是 RPG 入口动作，但当前文件名和职责仍偏平台通用详情页 |
|
||||
| `src/components/game-shell/CharacterSelectionFlow.tsx` | 角色选择、角色自定义草稿、确认进入营地 | 已是纯 RPG 选角页面，但命名仍是泛化 `SelectionFlow` |
|
||||
|
||||
## 2.2 前端运行态壳层与面板链
|
||||
|
||||
| 文件 | 当前职责 | 当前问题 |
|
||||
| --- | --- | --- |
|
||||
| `src/components/game-shell/GameShellRuntime.tsx` | 运行态最外层 shell，装配画布、主内容、各种 overlay | 同时承担平台主题外壳和 RPG 运行态外壳，命名与职责都偏泛 |
|
||||
| `src/components/game-shell/GameShellMainContent.tsx` | 根据 `worldType / playerCharacter / selectionStage` 在平台、选角、冒险面板三种主阶段间切换 | 实际上是 RPG 主阶段路由器，但文件名没有表达“入口阶段切换” |
|
||||
| `src/components/game-shell/GameShellStoryPanels.tsx` | 冒险/角色/背包三个主标签切换，挂载 `AdventurePanel`、`CharacterPanel`、`InventoryPanel` | 运行态主面板路由器与 tab 容器混在一起 |
|
||||
| `src/components/AdventurePanel.tsx` | 冒险主面板、对话流、选项区、任务/设置/统计 overlay、NPC 聊天输入、奖励面板 | 单文件过大，是当前前端 RPG 运行时最大热点之一 |
|
||||
| `src/components/game-shell/useGameShellRuntimeViewModel.ts` | 运行态视图模型、可见状态、过场、统计、对话指示器 | 负责运行态展示编排，但仍以 `GameShell` 泛名承载 |
|
||||
| `src/components/game-shell/useGameShellViewModel.ts` | overlay/modal/选中实体/selectionStage 的壳层状态 | 进入游戏前与进入游戏后 UI 状态混在一起，命名不够领域化 |
|
||||
|
||||
## 2.3 前端剧情运行时协调链
|
||||
|
||||
| 文件 | 当前职责 | 当前问题 |
|
||||
| --- | --- | --- |
|
||||
| `src/hooks/useStoryGeneration.ts` | 运行态故事主入口，拼装 runtime controller、goal session、interaction coordinator | 事实上的 RPG 叙事运行时入口，但命名过于抽象 |
|
||||
| `src/hooks/story/useStoryRuntimeController.ts` | 当前故事、AI 错误、故事请求入口、fallback story 和 commit 动作 | 浏览器 AI 请求与服务端 runtime story 共同挂在同一 controller 上 |
|
||||
| `src/hooks/story/useStoryFlowCoordinator.ts` | 汇总 goal option、interaction、session 行为，输出完整故事流程能力 | 多层 coordinator 套娃，可读性差 |
|
||||
| `src/hooks/story/useStoryGoalSessionCoordinator.ts` | 任务领奖、重置 story、恢复 story、地图移动 | 任务会话动作与 story 生命周期控制混在一起 |
|
||||
| `src/hooks/story/useStoryInteractionCoordinator.ts` | 选择分发、NPC 交互、宝藏交互、背包动作、战斗奖励、聊天输入 | 交互中心职责太重，是第二个热点文件 |
|
||||
| `src/hooks/story/npcEncounterActions.ts` | NPC 聊天、切磋、委托接受/替换/放弃、服务端 runtime action、聊天 UI 细节 | 依然是巨型多职责文件，且混合 UI 组装、状态更新、服务端请求 |
|
||||
| `src/hooks/story/runtimeStoryCoordinator.ts` | 继续游戏后恢复 runtime story、状态解析、server action 调用 | 是前端对接服务端 runtime story 的真正 gateway，但命名像临时协调器 |
|
||||
| `src/hooks/story/storyRequestCoordinator.ts` | AI 故事请求参数编排、server option catalog 决策 | 与 runtime story 主链存在交叉语义，边界不直观 |
|
||||
| `src/hooks/story/sessionActions.ts` | 地图移动、任务奖励、story reset/hydrate | “session action” 命名过泛，而且同时处理 quest/chapter/story 三类状态 |
|
||||
|
||||
## 2.4 前端 service / client 链
|
||||
|
||||
| 文件 | 当前职责 | 当前问题 |
|
||||
| --- | --- | --- |
|
||||
| `src/services/storageService.ts` | 存档、设置、个人看板、浏览历史、作品库、继续游戏、世界详情 | RPG 快照/存档接口与平台资料/作品库接口混在一个通用 client 中 |
|
||||
| `src/services/runtimeStoryService.ts` | `/api/runtime/story` 的状态读取、动作提交、story moment 转换 | 已接近 RPG 专属 client，但文件名仍偏通用 |
|
||||
| `src/services/aiService.ts` | 初始剧情/续写、角色聊天、NPC 聊天、runtime item、quest、custom world 共创接口 | RPG 运行时 AI、角色聊天、创作 Agent 接口混在一起，领域过宽 |
|
||||
|
||||
## 2.5 后端路由与运行时主链
|
||||
|
||||
| 文件 | 当前职责 | 当前问题 |
|
||||
| --- | --- | --- |
|
||||
| `server-node/src/server.ts` | 组装 `AppContext`，注入 runtimeRepository、customWorldAgentOrchestrator 等依赖 | 依赖对象过于集中，RPG 运行态缺少显式模块边界 |
|
||||
| `server-node/src/app.ts` | 注册 `/api/auth`、`/api/runtime/story`、`/api` 等总路由 | RPG 进入世界链、平台路由、编辑器路由全部在总 app 中汇合，语义不够清晰 |
|
||||
| `server-node/src/routes/runtimeRoutes.ts` | 资料、存档、浏览历史、作品库、runtime AI、世界生成等大杂糅路由 | 当前后端最大热点之一，平台资料与 RPG runtime 接口强耦合 |
|
||||
| `server-node/src/modules/story/storyActionRoutes.ts` | runtime story 状态读取、动作结算 | 路由层本身还算薄，但命名仍然过于通用 |
|
||||
| `server-node/src/modules/story/storyActionService.ts` | runtime story 状态/动作主应用服务，拼接 combat、npc、quest、treasure、LLM story | 是当前后端 RPG 运行时主热点，承担过多动作路由和 story 组装细节 |
|
||||
| `server-node/src/modules/story/runtimeSession.ts` | runtime snapshot 归一化、option 构建、viewModel 编译、legacy currentStory 构建、rawGameState 同步 | 运行态编译中心过重，加载器、编译器、同步器、兼容层全部混在一起 |
|
||||
| `server-node/src/modules/npc/npcInteractionService.ts` | NPC help/chat/fight/spar/recruit 等动作结算 | 与 runtime story 仍存在大量双向耦合 |
|
||||
| `server-node/src/modules/quest/questStoryActionService.ts` | 委托接受、交付、待接委托读取与结算 | 已承担正式 quest 语义，但入口仍埋在 storyActionService 下游 |
|
||||
| `server-node/src/repositories/runtimeRepository.ts` | 快照、存档列表、看板、浏览历史、作品库、会话等持久化读写 | 仓储过大，按技术分组而不是按 RPG 领域分组 |
|
||||
| `server-node/src/modules/runtime/runtimeSnapshotHydration.ts` | 存档/gameState/currentStory 归一化、迁移补丁、默认值填充 | 既承担快照迁移，又承担业务字段补齐，是基础设施与领域逻辑混合点 |
|
||||
| `packages/shared/src/contracts/story.ts` | 前后端 runtime story / npc chat / quest / runtime item 等共享契约 | RPG 运行时契约体量过大，story/action/state/chat 混放，难以独立演进 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前结构性问题
|
||||
|
||||
## 3.1 命名没有体现“这是 RPG 进入游戏主链”
|
||||
|
||||
当前主链上充满以下泛化命名：
|
||||
|
||||
1. `GameShell`
|
||||
2. `MainContent`
|
||||
3. `SelectionFlow`
|
||||
4. `runtimeRoutes`
|
||||
5. `storyActionService`
|
||||
6. `sessionActions`
|
||||
|
||||
这些命名的问题不是“不好看”，而是：
|
||||
|
||||
1. 无法一眼区分平台入口、RPG 进入游戏、RPG 运行态
|
||||
2. 无法一眼看出文件属于前端壳层、状态协调器、还是后端应用服务
|
||||
3. 后续非 RPG 流程接入时，很容易继续误复用这些泛化热点文件
|
||||
|
||||
## 3.2 平台入口与 RPG 进入游戏链混在一起
|
||||
|
||||
`PreGameSelectionFlow.tsx` 当前同时承担：
|
||||
|
||||
1. 平台首页
|
||||
2. 详情页
|
||||
3. 存档恢复
|
||||
4. 创作入口
|
||||
5. 进入世界
|
||||
|
||||
这会导致：
|
||||
|
||||
1. 任何平台改动都可能碰到 RPG 进入游戏主链
|
||||
2. 任何 RPG 进入游戏改动都要穿过平台杂项状态
|
||||
3. 文件变成事实上的超大编排中心
|
||||
|
||||
## 3.3 `GameState` 初始化、快照恢复、运行态切入没有明确分层
|
||||
|
||||
`useGameFlow.ts`、`useGamePersistence.ts`、`useGameShellRuntime.ts` 当前共同承担：
|
||||
|
||||
1. 新开局初始化
|
||||
2. 世界选择
|
||||
3. 角色选择
|
||||
4. 自动存档
|
||||
5. 继续游戏恢复
|
||||
6. runtime story 恢复刷新
|
||||
|
||||
结果是：
|
||||
|
||||
1. “进入游戏前的 session bootstrap”与“进入游戏后的自动持久化”没有明确边界
|
||||
2. 继续游戏逻辑很难单独替换或扩展
|
||||
3. 任何存档策略变更都容易影响开局链
|
||||
|
||||
## 3.4 前端剧情运行时协调层过多，职责分散却仍然耦合
|
||||
|
||||
当前前端 story 主链至少经过：
|
||||
|
||||
1. `useStoryGeneration`
|
||||
2. `useStoryRuntimeController`
|
||||
3. `useStoryFlowCoordinator`
|
||||
4. `useStoryGoalSessionCoordinator`
|
||||
5. `useStoryInteractionCoordinator`
|
||||
6. `npcEncounterActions`
|
||||
7. `runtimeStoryCoordinator`
|
||||
|
||||
问题在于：
|
||||
|
||||
1. 层数多，但不是稳定分层，而是热点文件之间互相穿透
|
||||
2. 有些层是 view model，有些层是 action dispatcher，有些层是 server gateway，命名看不出来
|
||||
3. 浏览器 AI 续写链与服务端 runtime story 链还没有完全收口为两个明确通道
|
||||
|
||||
## 3.5 后端路由层过于“大 runtime 大入口”
|
||||
|
||||
`runtimeRoutes.ts` 当前同时覆盖：
|
||||
|
||||
1. profile dashboard
|
||||
2. browse history
|
||||
3. save archives
|
||||
4. custom world library/gallery
|
||||
5. custom world profile generation
|
||||
6. runtime story 外围 AI 接口
|
||||
7. runtime item / quest 生成接口
|
||||
|
||||
这会导致：
|
||||
|
||||
1. RPG 进入游戏链难以抽出独立模块
|
||||
2. 平台资料接口和 RPG runtime 接口一起变更时风险高
|
||||
3. route 文件越来越像“后端总控清单”
|
||||
|
||||
## 3.6 `runtimeSession.ts` 是当前后端最大可读性瓶颈之一
|
||||
|
||||
这个文件当前同时做了：
|
||||
|
||||
1. snapshot 载入
|
||||
2. rawGameState 归一化
|
||||
3. option interaction 构建
|
||||
4. battle option 编译
|
||||
5. NPC option 编译
|
||||
6. viewModel 编译
|
||||
7. legacy currentStory 兼容输出
|
||||
8. rawGameState 回写同步
|
||||
|
||||
这会直接造成：
|
||||
|
||||
1. 新增动作时很难判断应该改哪里
|
||||
2. 任何小调整都容易触碰多个职责
|
||||
3. 单测难以按职责拆开
|
||||
|
||||
## 3.7 持久化仓储按技术堆叠，没有按 RPG 域拆开
|
||||
|
||||
`runtimeRepository.ts` 把：
|
||||
|
||||
1. snapshot
|
||||
2. save archives
|
||||
3. settings
|
||||
4. dashboard
|
||||
5. browse history
|
||||
6. custom world library
|
||||
7. custom world sessions
|
||||
|
||||
全部堆在一起。
|
||||
|
||||
对 RPG 进入游戏链来说，至少应该显式分开：
|
||||
|
||||
1. 运行时快照
|
||||
2. 存档归档
|
||||
3. 平台资料
|
||||
4. 世界库/详情
|
||||
|
||||
否则“继续游戏链”与“平台资料链”永远无法清晰拆边界。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目标分层架构
|
||||
|
||||
## 4.1 目标原则
|
||||
|
||||
后续重构必须统一遵守 7 条原则：
|
||||
|
||||
1. **平台入口只负责进入 RPG，会话真相不留在页面壳层。**
|
||||
2. **世界选择、角色选择、新开局、继续游戏恢复属于 RPG session 入口域。**
|
||||
3. **进入世界后的运行态壳层、冒险面板、story runtime 网关必须显式分层。**
|
||||
4. **前端只保留展示状态、输入状态、UI 过场状态；正式快照、正式动作、正式 story option 以后端为准。**
|
||||
5. **后端 route / application service / compiler / repository 必须按 RPG 域拆开，不再扩大“大 runtime 单文件”。**
|
||||
6. **所有新命名都要显式表达“这是 RPG 类型游戏专属流程”，不能继续依赖 `GameShell / runtime / flow` 这类泛化词。**
|
||||
7. **重构期间严格冻结前端交互界面设计，脚本重组不能改变任何页面结构与交互表现。**
|
||||
|
||||
## 4.2 目标链路
|
||||
|
||||
```text
|
||||
RPG 平台入口壳层
|
||||
-> RPG session bootstrap
|
||||
-> RPG 角色选择
|
||||
-> RPG 运行态 shell
|
||||
-> RPG 运行态面板路由
|
||||
-> RPG runtime story gateway
|
||||
-> RPG runtime story routes
|
||||
-> RPG runtime action/state services
|
||||
-> RPG runtime session loader/compiler
|
||||
-> RPG snapshot repository / save archive repository
|
||||
```
|
||||
|
||||
## 4.3 推荐目录骨架
|
||||
|
||||
### 前端
|
||||
|
||||
```text
|
||||
src/
|
||||
├─ components/
|
||||
│ ├─ rpg-entry/
|
||||
│ ├─ rpg-runtime-shell/
|
||||
│ ├─ rpg-runtime-panels/
|
||||
│ └─ rpg-runtime-overlays/
|
||||
├─ hooks/
|
||||
│ ├─ rpg-session/
|
||||
│ └─ rpg-runtime-story/
|
||||
└─ services/
|
||||
├─ rpg-entry/
|
||||
└─ rpg-runtime/
|
||||
```
|
||||
|
||||
### 后端
|
||||
|
||||
```text
|
||||
server-node/src/
|
||||
├─ routes/
|
||||
│ ├─ rpg-entry/
|
||||
│ ├─ rpg-profile/
|
||||
│ └─ rpg-runtime/
|
||||
├─ modules/
|
||||
│ └─ rpg-runtime-story/
|
||||
├─ services/
|
||||
│ ├─ rpg-entry/
|
||||
│ └─ rpg-runtime/
|
||||
└─ repositories/
|
||||
├─ rpg-entry/
|
||||
└─ rpg-runtime/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. RPG 专属命名规范
|
||||
|
||||
## 5.1 命名根
|
||||
|
||||
后续进入游戏与运行态链统一使用以下命名根：
|
||||
|
||||
1. `rpgEntry`
|
||||
- 平台首页、详情页、世界进入、角色选择、继续游戏入口
|
||||
2. `rpgSession`
|
||||
- 新开局、继续游戏恢复、快照 persistence、开局 bootstrap
|
||||
3. `rpgRuntime`
|
||||
- 游戏内 shell、tab、面板、overlay、view model
|
||||
4. `rpgRuntimeStory`
|
||||
- story state/action client、gateway、route、service、compiler
|
||||
5. `rpgProfile`
|
||||
- dashboard、browse history、save archive 等玩家资料域
|
||||
|
||||
## 5.2 命名规则
|
||||
|
||||
1. React 组件文件统一使用 `Rpg...` 前缀。
|
||||
2. hooks 统一使用 `useRpg...` 前缀。
|
||||
3. 前端 client/gateway/adapter 统一使用 `rpg...` 小驼峰前缀。
|
||||
4. 后端 route 使用 `rpg...Routes.ts`。
|
||||
5. 后端应用服务使用 `Rpg...Service.ts`。
|
||||
6. 后端编译器/装配器使用 `Rpg...Compiler.ts` / `Rpg...Assembler.ts`。
|
||||
7. 后端仓储使用 `Rpg...Repository.ts`。
|
||||
8. 共享契约文件优先拆成 `rpgEntry...`、`rpgRuntimeStory...`、`rpgProfile...`。
|
||||
|
||||
## 5.3 命名禁忌
|
||||
|
||||
后续重构中禁止继续新增以下主命名：
|
||||
|
||||
1. `GameShell*`
|
||||
2. `PreGame*`
|
||||
3. `SelectionFlow*`
|
||||
4. `runtimeRoutes.ts` 这种单文件总入口命名
|
||||
5. `storyActionService.ts` 这种过宽的单域名
|
||||
6. `sessionActions.ts`、`flowCoordinator.ts`、`manager.ts`、`helper.ts` 作为主业务模块名
|
||||
|
||||
## 5.4 关键文件重命名建议
|
||||
|
||||
| 当前文件 | 目标命名 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `src/components/game-shell/PreGameSelectionFlow.tsx` | `src/components/rpg-entry/RpgEntryFlowShell.tsx` | 平台进入世界与选角前阶段壳层 |
|
||||
| `src/components/game-shell/PlatformHomeView.tsx` | `src/components/rpg-entry/RpgEntryHomeView.tsx` | RPG 平台首页 |
|
||||
| `src/components/game-shell/PlatformWorldDetailView.tsx` | `src/components/rpg-entry/RpgEntryWorldDetailView.tsx` | 世界详情与开始游戏入口 |
|
||||
| `src/components/game-shell/CharacterSelectionFlow.tsx` | `src/components/rpg-entry/RpgEntryCharacterSelectView.tsx` | RPG 选角页 |
|
||||
| `src/hooks/useGameFlow.ts` | `src/hooks/rpg-session/useRpgSessionBootstrap.ts` | 新开局/世界选择/角色确认 |
|
||||
| `src/hooks/useGamePersistence.ts` | `src/hooks/rpg-session/useRpgSessionPersistence.ts` | 自动存档/继续游戏恢复 |
|
||||
| `src/hooks/useGameShellRuntime.ts` | `src/hooks/rpg-session/useRpgRuntimeSession.ts` | RPG 主运行态装配器 |
|
||||
| `src/components/game-shell/GameShellRuntime.tsx` | `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx` | 运行态总外壳 |
|
||||
| `src/components/game-shell/GameShellMainContent.tsx` | `src/components/rpg-runtime-shell/RpgRuntimeStageRouter.tsx` | 平台/选角/冒险阶段切换 |
|
||||
| `src/components/game-shell/GameShellStoryPanels.tsx` | `src/components/rpg-runtime-panels/RpgRuntimePanelRouter.tsx` | 冒险/角色/背包主标签路由 |
|
||||
| `src/components/AdventurePanel.tsx` | `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx` | 冒险主面板 |
|
||||
| `src/hooks/useStoryGeneration.ts` | `src/hooks/rpg-runtime-story/useRpgRuntimeStory.ts` | 前端 story 运行态主入口 |
|
||||
| `src/hooks/story/useStoryRuntimeController.ts` | `src/hooks/rpg-runtime-story/useRpgRuntimeStoryController.ts` | 当前 story 与请求控制 |
|
||||
| `src/hooks/story/useStoryFlowCoordinator.ts` | `src/hooks/rpg-runtime-story/useRpgRuntimeStoryFlow.ts` | story 主编排 |
|
||||
| `src/hooks/story/useStoryInteractionCoordinator.ts` | `src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.ts` | runtime 交互分发 |
|
||||
| `src/hooks/story/npcEncounterActions.ts` | `src/hooks/rpg-runtime-story/useRpgRuntimeNpcInteraction.ts` | NPC 交互与聊天动作 |
|
||||
| `src/hooks/story/runtimeStoryCoordinator.ts` | `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts` | 前端到后端 runtime story 网关 |
|
||||
| `src/services/runtimeStoryService.ts` | `src/services/rpg-runtime/rpgRuntimeStoryClient.ts` | `/api/runtime/story` client |
|
||||
| `src/services/storageService.ts` | 拆成 `rpgProfileClient.ts` / `rpgEntryLibraryClient.ts` / `rpgSnapshotClient.ts` | 按领域拆 client |
|
||||
| `server-node/src/routes/runtimeRoutes.ts` | 拆成 `rpgProfileRoutes.ts` / `rpgEntryRoutes.ts` / `rpgRuntimeAiRoutes.ts` / `rpgWorldLibraryRoutes.ts` | 拒绝单文件总路由 |
|
||||
| `server-node/src/modules/story/storyActionRoutes.ts` | `server-node/src/routes/rpg-runtime/rpgRuntimeStoryRoutes.ts` | runtime story 专属路由 |
|
||||
| `server-node/src/modules/story/storyActionService.ts` | `RpgRuntimeStoryActionService.ts` + `RpgRuntimeStoryStateService.ts` | 动作结算与状态读取拆开 |
|
||||
| `server-node/src/modules/story/runtimeSession.ts` | `RpgRuntimeSessionLoader.ts` + `RpgRuntimeOptionCompiler.ts` + `RpgRuntimeSnapshotSync.ts` | 按职责拆分 |
|
||||
| `server-node/src/repositories/runtimeRepository.ts` | `RpgRuntimeSnapshotRepository.ts` 等多个仓储 | 按领域拆仓储 |
|
||||
| `packages/shared/src/contracts/story.ts` | 拆成 `rpgRuntimeStory.ts` / `rpgRuntimeChat.ts` / `rpgRuntimeAction.ts` | 契约拆分 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 前端重构拆分方案
|
||||
|
||||
## 6.1 RPG 入口壳层拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`PreGameSelectionFlow.tsx` 当前同时承担平台首页、详情页、进入世界、存档恢复与部分创作入口逻辑。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
保留一个极薄的 `RpgEntryFlowShell.tsx`，只负责：
|
||||
|
||||
1. 入口阶段切换
|
||||
2. 装配子页面
|
||||
3. loading / error 壳层
|
||||
|
||||
从当前文件拆出：
|
||||
|
||||
1. `useRpgEntryBootstrap.ts`
|
||||
2. `useRpgEntryNavigation.ts`
|
||||
3. `useRpgEntrySaveResume.ts`
|
||||
4. `useRpgEntryLibraryDetail.ts`
|
||||
5. `RpgEntryHomeView.tsx`
|
||||
6. `RpgEntryWorldDetailView.tsx`
|
||||
7. `RpgEntryCharacterSelectView.tsx`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. 入口壳层不再直接操作作品库、浏览历史、看板的多路加载细节。
|
||||
2. 入口壳层不再直接处理“继续游戏后刷新 runtime story”的逻辑。
|
||||
3. 创作入口与 RPG 进入世界入口要显式分段，不再共享大文件。
|
||||
4. 页面视觉结构、按钮布局、tab 形式和独立面板交互方式保持不变。
|
||||
|
||||
## 6.2 RPG session bootstrap / persistence 拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`useGameFlow.ts` 与 `useGamePersistence.ts` 共同承担了开局初始化、世界进入、存档自动保存和恢复。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议拆出：
|
||||
|
||||
1. `useRpgSessionBootstrap.ts`
|
||||
2. `useRpgCharacterEntry.ts`
|
||||
3. `useRpgSnapshotPersistence.ts`
|
||||
4. `useRpgContinueGame.ts`
|
||||
5. `rpgSnapshotClient.ts`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. 新开局初始化与继续游戏恢复是两条显式流程。
|
||||
2. `GameState` 初始化逻辑不再和自动存档逻辑放在同一 hook 里。
|
||||
3. 存档自动保存不再直接夹带 UI 层状态决策。
|
||||
4. 脚本拆分后不改变用户看到的进入游戏流程和交互顺序。
|
||||
|
||||
## 6.3 RPG 运行态 shell 与面板拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`GameShellRuntime.tsx`、`GameShellMainContent.tsx`、`GameShellStoryPanels.tsx`、`AdventurePanel.tsx` 共同组成了一个过于耦合的壳层群。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议形成：
|
||||
|
||||
1. `RpgRuntimeShell.tsx`
|
||||
2. `RpgRuntimeStageRouter.tsx`
|
||||
3. `RpgRuntimePanelRouter.tsx`
|
||||
4. `RpgAdventurePanel.tsx`
|
||||
5. `RpgRuntimeOverlayHost.tsx`
|
||||
6. `useRpgRuntimeShellViewModel.ts`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. 运行态最外层壳层只管布局、背景、过场和 overlay host。
|
||||
2. 主阶段路由器只管“平台/选角/冒险”的分流。
|
||||
3. 面板路由器只管“冒险/角色/背包”的主 tab 分流。
|
||||
4. `AdventurePanel` 内部继续按“story 区 / option 区 / overlay 区”拆 section。
|
||||
5. 不重做任何面板样式、信息层次和交互布局，拆分只发生在脚本内部。
|
||||
|
||||
## 6.4 前端 runtime story 主链拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
前端 runtime story 主链层数太多，但边界并不稳定。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议收成四层：
|
||||
|
||||
1. `useRpgRuntimeStory.ts`
|
||||
- 作为唯一对上输出入口
|
||||
2. `useRpgRuntimeStoryState.ts`
|
||||
- 管当前 story、loading、error、hydration
|
||||
3. `useRpgRuntimeInteractionFlow.ts`
|
||||
- 分发 NPC / 战斗 / 宝藏 / 任务 / 地图动作
|
||||
4. `rpgRuntimeStoryGateway.ts`
|
||||
- 只负责和后端 runtime story client 交互
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. 浏览器侧 AI 续写逻辑与 server runtime story 逻辑必须显式分离。
|
||||
2. `npcEncounterActions.ts` 中的 UI 细节和正式动作结算必须拆开。
|
||||
3. 任何 `resolveServerRuntimeChoice(...)` 都应只通过统一 gateway 入口调用。
|
||||
4. 交互按钮、对话区、输入区和奖励展示的前端交互形式保持现状不变。
|
||||
|
||||
## 6.5 前端 service/client 收口方案
|
||||
|
||||
### 当前问题
|
||||
|
||||
`storageService.ts` 与 `aiService.ts` 的领域过宽。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议新增：
|
||||
|
||||
1. `src/services/rpg-entry/rpgEntryLibraryClient.ts`
|
||||
2. `src/services/rpg-entry/rpgProfileClient.ts`
|
||||
3. `src/services/rpg-runtime/rpgSnapshotClient.ts`
|
||||
4. `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
|
||||
5. `src/services/rpg-runtime/rpgRuntimeChatClient.ts`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. `storageService.ts` 逐步降级为兼容 façade。
|
||||
2. `aiService.ts` 逐步只保留通用 AI 与创作域 client，不继续承接 RPG runtime story 主链。
|
||||
3. 进入游戏链不能再依赖过宽的通用 client 文件。
|
||||
|
||||
---
|
||||
|
||||
## 7. 后端重构拆分方案
|
||||
|
||||
## 7.1 route 层拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`runtimeRoutes.ts` 过重，平台资料、作品库和 RPG runtime 都在一起。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议拆成：
|
||||
|
||||
1. `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
|
||||
2. `server-node/src/routes/rpg-entry/rpgEntrySaveRoutes.ts`
|
||||
3. `server-node/src/routes/rpg-entry/rpgWorldLibraryRoutes.ts`
|
||||
4. `server-node/src/routes/rpg-runtime/rpgRuntimeStoryRoutes.ts`
|
||||
5. `server-node/src/routes/rpg-runtime/rpgRuntimeAiAssistRoutes.ts`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. RPG 进入游戏链相关接口必须从“大 runtime 总路由”中抽离。
|
||||
2. `app.ts` 中要能一眼看出平台资料、世界库、runtime story 的路由边界。
|
||||
3. route 层继续保持薄，不直接承载 story 业务决策。
|
||||
|
||||
## 7.2 runtime story service 拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`storyActionService.ts` 当前同时承担状态读取、动作结算、LLM story 包装和 snapshot 持久化。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议拆为：
|
||||
|
||||
1. `RpgRuntimeStoryStateService.ts`
|
||||
2. `RpgRuntimeStoryActionService.ts`
|
||||
3. `RpgRuntimeCombatActionService.ts`
|
||||
4. `RpgRuntimeNpcActionService.ts`
|
||||
5. `RpgRuntimeStoryPresentationCompiler.ts`
|
||||
6. `RpgRuntimeStorySnapshotCommitService.ts`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. 状态读取与动作结算分开。
|
||||
2. 各子域动作要能各自单测，不再全部挂在一个 service 里。
|
||||
3. LLM 二次包装 story 文本不能继续散在动作服务主文件中。
|
||||
|
||||
## 7.3 `runtimeSession.ts` 目录化拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`runtimeSession.ts` 已经集中了太多运行时编译职责。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议新增目录：
|
||||
|
||||
```text
|
||||
server-node/src/modules/rpg-runtime-story/session/
|
||||
├─ RpgRuntimeSessionLoader.ts
|
||||
├─ RpgRuntimeEncounterNormalizer.ts
|
||||
├─ RpgRuntimeOptionCompiler.ts
|
||||
├─ RpgRuntimeBattleOptionCompiler.ts
|
||||
├─ RpgRuntimeNpcOptionCompiler.ts
|
||||
├─ RpgRuntimeViewModelCompiler.ts
|
||||
├─ RpgRuntimeLegacyStoryAdapter.ts
|
||||
└─ RpgRuntimeSnapshotSync.ts
|
||||
```
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. loader、compiler、legacy adapter、snapshot sync 必须物理拆开。
|
||||
2. “是否生成 legacy currentStory”要成为单独兼容层，而不是散落在核心编排里。
|
||||
3. interaction 语义编译要可单测、可扩展。
|
||||
|
||||
## 7.4 repository 拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`runtimeRepository.ts` 不是 RPG 进入游戏链友好的结构。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议拆成：
|
||||
|
||||
1. `RpgRuntimeSnapshotRepository.ts`
|
||||
2. `RpgSaveArchiveRepository.ts`
|
||||
3. `RpgProfileDashboardRepository.ts`
|
||||
4. `RpgBrowseHistoryRepository.ts`
|
||||
5. `RpgWorldLibraryRepository.ts`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. snapshot、save archive 与资料型仓储分离。
|
||||
2. 世界库详情读取与运行时快照读写不再耦合在同一仓储。
|
||||
3. 后续“继续游戏”链可以只依赖 snapshot/save archive 仓储。
|
||||
|
||||
## 7.5 shared contract 拆分
|
||||
|
||||
### 当前问题
|
||||
|
||||
`packages/shared/src/contracts/story.ts` 已经过大。
|
||||
|
||||
### 目标拆分
|
||||
|
||||
建议拆为：
|
||||
|
||||
1. `rpgRuntimeStoryAction.ts`
|
||||
2. `rpgRuntimeStoryState.ts`
|
||||
3. `rpgRuntimeChat.ts`
|
||||
4. `rpgRuntimeQuestAssist.ts`
|
||||
|
||||
### 关键要求
|
||||
|
||||
1. runtime story 主链契约要能独立演进，不被 NPC chat / quest / item 附属能力拖累。
|
||||
2. 前后端只在必要范围共享契约，减少大而全文件。
|
||||
|
||||
---
|
||||
|
||||
## 8. 可并行重构工作包
|
||||
|
||||
本次执行计划必须拆成多个可以同时推进的工作部分。
|
||||
|
||||
总原则如下：
|
||||
|
||||
1. 每个工作包只负责一组明确文件。
|
||||
2. 每个工作包先建新目录和 façade，再迁真实调用，再清旧层。
|
||||
3. 同一阶段允许并行，但禁止多人同时大改同一热点主文件。
|
||||
|
||||
## 8.1 工作包 A：RPG 命名规范与目录骨架
|
||||
|
||||
### 目标
|
||||
|
||||
先建立 RPG 进入游戏链的新命名与目录落点。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. `src/components/rpg-entry/`
|
||||
2. `src/components/rpg-runtime-shell/`
|
||||
3. `src/components/rpg-runtime-panels/`
|
||||
4. `src/hooks/rpg-session/`
|
||||
5. `src/hooks/rpg-runtime-story/`
|
||||
6. `src/services/rpg-entry/`
|
||||
7. `src/services/rpg-runtime/`
|
||||
8. `server-node/src/routes/rpg-*/`
|
||||
9. `server-node/src/modules/rpg-runtime-story/`
|
||||
10. `server-node/src/repositories/rpg-*/`
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 只建目录、入口 façade、导出索引和基础命名规范。
|
||||
2. 不负责大规模迁移老逻辑。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
无，可立即开始。
|
||||
|
||||
## 8.2 工作包 B：前端 RPG 入口壳层拆分
|
||||
|
||||
### 目标
|
||||
|
||||
把平台首页/详情页/继续游戏/进入世界从 `PreGameSelectionFlow.tsx` 拆出来。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. `PreGameSelectionFlow.tsx`
|
||||
2. `PlatformHomeView.tsx`
|
||||
3. `PlatformWorldDetailView.tsx`
|
||||
4. `CharacterSelectionFlow.tsx`
|
||||
5. 入口阶段相关新 hooks
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 只改前端入口链。
|
||||
2. 不改后端接口语义。
|
||||
3. 不拆运行态冒险面板。
|
||||
4. 不修改任何前端交互界面设计。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
依赖工作包 A 的目录骨架。
|
||||
|
||||
## 8.3 工作包 C：前端 session/bootstrap/persistence 拆分
|
||||
|
||||
### 目标
|
||||
|
||||
把 `useGameFlow.ts`、`useGamePersistence.ts`、`useGameShellRuntime.ts` 收成 RPG session 域。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. `useGameFlow.ts`
|
||||
2. `useGamePersistence.ts`
|
||||
3. `useGameShellRuntime.ts`
|
||||
4. `storageService.ts` 中 snapshot/save archive 相关调用入口
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 主要改 session bootstrap、自动存档、继续游戏恢复。
|
||||
2. 不改 AdventurePanel UI。
|
||||
3. 不改后端 storyActionService 语义。
|
||||
4. 不修改任何前端交互界面设计。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
依赖工作包 A，可与 B、D、F、G、H 并行。
|
||||
|
||||
## 8.4 工作包 D：前端运行态 shell 与面板拆分
|
||||
|
||||
### 目标
|
||||
|
||||
把 `GameShellRuntime.tsx`、`GameShellMainContent.tsx`、`GameShellStoryPanels.tsx`、`AdventurePanel.tsx` 拆成 RPG runtime shell 体系。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. 运行态 shell
|
||||
2. 主阶段路由器
|
||||
3. 面板路由器
|
||||
4. 冒险主面板 section
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 主改组件与 view model。
|
||||
2. 不改 runtime story 后端协议。
|
||||
3. 不改平台入口链。
|
||||
4. 不修改任何前端交互界面设计。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
依赖工作包 A，可与 B、C、E、F、G、H 并行。
|
||||
|
||||
## 8.5 工作包 E：前端 runtime story 与 NPC 交互链拆分
|
||||
|
||||
### 目标
|
||||
|
||||
把多层 story coordinator 收成稳定的 RPG runtime story 结构。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. `useStoryGeneration.ts`
|
||||
2. `useStoryRuntimeController.ts`
|
||||
3. `useStoryFlowCoordinator.ts`
|
||||
4. `useStoryGoalSessionCoordinator.ts`
|
||||
5. `useStoryInteractionCoordinator.ts`
|
||||
6. `npcEncounterActions.ts`
|
||||
7. `runtimeStoryCoordinator.ts`
|
||||
8. `runtimeStoryService.ts`
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 只改前端 runtime story 主链。
|
||||
2. 不拆平台首页和世界详情壳层。
|
||||
3. 不直接修改后端动作语义。
|
||||
4. 不修改任何前端交互界面设计。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
依赖工作包 A，可与 B、C、D、F、G、H 并行。
|
||||
|
||||
## 8.6 工作包 F：后端 route 边界拆分
|
||||
|
||||
### 目标
|
||||
|
||||
把 `runtimeRoutes.ts` 与 `storyActionRoutes.ts` 按 RPG 域拆边界。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. `app.ts`
|
||||
2. `runtimeRoutes.ts`
|
||||
3. `storyActionRoutes.ts`
|
||||
4. 新 `rpgProfileRoutes.ts`
|
||||
5. 新 `rpgEntry...Routes.ts`
|
||||
6. 新 `rpgRuntimeStoryRoutes.ts`
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 只调整路由组织和 façade。
|
||||
2. 不重写下游全部 service 逻辑。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
依赖工作包 A，可与 B、C、D、E、G、H 并行。
|
||||
|
||||
## 8.7 工作包 G：后端 runtime session / action service 拆分
|
||||
|
||||
### 目标
|
||||
|
||||
把 `storyActionService.ts` 与 `runtimeSession.ts` 目录化拆开。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. `storyActionService.ts`
|
||||
2. `runtimeSession.ts`
|
||||
3. `npcInteractionService.ts`
|
||||
4. `questStoryActionService.ts`
|
||||
5. 新 action service / compiler / adapter 文件
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 主改后端运行时 story 主链。
|
||||
2. 不改前端入口与 UI。
|
||||
3. 不负责仓储拆分。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
依赖工作包 A，可与 B、C、D、E、F、H 并行。
|
||||
|
||||
## 8.8 工作包 H：仓储、契约与测试基建
|
||||
|
||||
### 目标
|
||||
|
||||
把 snapshot/profile/library 仓储与 shared contract 收成独立层，并补齐测试。
|
||||
|
||||
### 负责范围
|
||||
|
||||
1. `runtimeRepository.ts`
|
||||
2. `runtimeSnapshotHydration.ts`
|
||||
3. `packages/shared/src/contracts/story.ts`
|
||||
4. runtime story / snapshot / continue game 相关测试
|
||||
|
||||
### 写入边界
|
||||
|
||||
1. 只负责仓储、契约、fixture、测试。
|
||||
2. 不直接改前端 UI。
|
||||
3. 不重写 route 层。
|
||||
|
||||
### 前置依赖
|
||||
|
||||
依赖工作包 A，可与 B、C、D、E、F、G 并行。
|
||||
|
||||
## 8.9 推荐并行顺序
|
||||
|
||||
```text
|
||||
第一批并行：
|
||||
工作包 A
|
||||
|
||||
第二批并行：
|
||||
工作包 B + 工作包 C + 工作包 D + 工作包 E + 工作包 F + 工作包 G + 工作包 H
|
||||
|
||||
第三批收口：
|
||||
把 B~H 的 façade 接回主链
|
||||
-> 联调继续游戏 / 开始游戏 / 角色选择 / 冒险 runtime / 存档恢复
|
||||
-> 清理旧命名与兼容导出
|
||||
```
|
||||
|
||||
## 8.10 并行协作约束
|
||||
|
||||
1. 工作包 B 独占 `PreGameSelectionFlow.tsx`、`PlatformHomeView.tsx`、`PlatformWorldDetailView.tsx`、`CharacterSelectionFlow.tsx`。
|
||||
2. 工作包 C 独占 `useGameFlow.ts`、`useGamePersistence.ts`、`useGameShellRuntime.ts`。
|
||||
3. 工作包 D 独占 `GameShellRuntime.tsx`、`GameShellMainContent.tsx`、`GameShellStoryPanels.tsx`、`AdventurePanel.tsx`。
|
||||
4. 工作包 E 独占 story runtime hooks 与 `runtimeStoryService.ts`。
|
||||
5. 工作包 F 独占 `runtimeRoutes.ts`、`storyActionRoutes.ts`、`app.ts`。
|
||||
6. 工作包 G 独占 `storyActionService.ts`、`runtimeSession.ts` 与相关 runtime story modules。
|
||||
7. 工作包 H 独占 `runtimeRepository.ts`、`runtimeSnapshotHydration.ts` 与 shared runtime story contracts。
|
||||
|
||||
---
|
||||
|
||||
## 9. 分阶段落地计划
|
||||
|
||||
## Phase 0：冻结命名与边界口径
|
||||
|
||||
### 目标
|
||||
|
||||
先冻结“RPG 入口链 / RPG session / RPG runtime / RPG runtime story / RPG profile”五类命名边界。
|
||||
|
||||
### 验收标准
|
||||
|
||||
1. 后续新增文件不再继续进入 `GameShell*`、`runtimeRoutes.ts`、`storyActionService.ts` 这类旧热点。
|
||||
2. 团队对文件落点和命名根达成一致。
|
||||
3. 团队对“脚本重构不改前端交互界面设计”的冻结边界达成一致。
|
||||
|
||||
## Phase 1：目录骨架与前端入口拆分
|
||||
|
||||
### 目标
|
||||
|
||||
先建立目录骨架，并把进入游戏前的前端壳层从大文件中拆开。
|
||||
|
||||
### 验收标准
|
||||
|
||||
1. 平台首页/详情页/选角能落到 `rpgEntry` 目录。
|
||||
2. `PreGameSelectionFlow.tsx` 退化为兼容壳层或 façade。
|
||||
3. 页面视觉结构与交互方式和当前线上版本保持一致。
|
||||
|
||||
## Phase 2：session/bootstrap/persistence 收口
|
||||
|
||||
### 目标
|
||||
|
||||
把“新开局/继续游戏/自动存档/恢复 runtime story”从组件与面板层抽离。
|
||||
|
||||
### 验收标准
|
||||
|
||||
1. `useGameFlow.ts`、`useGamePersistence.ts` 不再是直接主入口命名。
|
||||
2. 继续游戏与自动存档都能走独立 session hook。
|
||||
3. 用户看到的开始游戏/继续游戏交互顺序不变。
|
||||
|
||||
## Phase 3：运行态 shell 与 runtime story 主链拆分
|
||||
|
||||
### 目标
|
||||
|
||||
把冒险运行态 UI 壳层与 runtime story 协调层分别重构。
|
||||
|
||||
### 验收标准
|
||||
|
||||
1. `AdventurePanel.tsx` 不再是大一统主热点。
|
||||
2. 前端 runtime story 主链收成 3~4 个稳定层级，而不是多层 coordinator 套娃。
|
||||
3. 冒险态界面布局、tab 交互与 overlay 呈现方式不变。
|
||||
|
||||
## Phase 4：后端 route / service / compiler / repository 目录化
|
||||
|
||||
### 目标
|
||||
|
||||
把后端“大 runtime route + 大 storyActionService + 大 runtimeSession + 大 runtimeRepository”按 RPG 域拆开。
|
||||
|
||||
### 验收标准
|
||||
|
||||
1. `runtimeRoutes.ts` 退化为 façade 或被拆空。
|
||||
2. `storyActionService.ts` 只保留兼容导出。
|
||||
3. `runtimeSession.ts` 只保留 façade 或兼容导出。
|
||||
4. `runtimeRepository.ts` 不再承载全部 RPG 资料与快照职责。
|
||||
5. 前端交互界面设计在整个后端重构阶段保持零变更。
|
||||
|
||||
## Phase 5：兼容层清理
|
||||
|
||||
### 目标
|
||||
|
||||
在主链稳定后清理旧命名与旧 façade。
|
||||
|
||||
### 验收标准
|
||||
|
||||
1. 进入游戏主链只剩 RPG 专属命名文件。
|
||||
2. `GameShell*` 与 `runtimeRoutes.ts` 不再是主链真实入口。
|
||||
3. 文档、契约、测试口径一致。
|
||||
|
||||
---
|
||||
|
||||
## 10. 验收标准
|
||||
|
||||
本次重构方案最终要达成以下结果：
|
||||
|
||||
1. 从“平台首页/详情页开始游戏”到“进入 RPG 运行态”的脚本链能一眼看出前端入口、session、runtime、story 的层级。
|
||||
2. 进入游戏主链不再依赖过于泛化的 `GameShell / runtime / flow` 命名。
|
||||
3. 前端自动存档、继续游戏恢复、runtime story server gateway 具备独立文件边界。
|
||||
4. 后端 route、runtime story service、session compiler、snapshot repository 分层清晰。
|
||||
5. 所有新主文件都以 RPG 域命名，不再继续扩大旧热点文件。
|
||||
6. 整个重构过程不改变任何前端交互界面设计，用户可见交互保持一致。
|
||||
|
||||
---
|
||||
|
||||
## 11. 结论
|
||||
|
||||
当前 RPG 进入游戏后的主玩法链，真正的问题不是单点 bug，而是：
|
||||
|
||||
**平台入口、会话初始化、运行态壳层、前端 runtime story 协调链、后端 route 总入口、后端 runtime session 编译器和仓储层同时过重，而且命名没有体现“这是 RPG 专属主链”。**
|
||||
|
||||
后续正确的重构方向不是继续在 `GameShell`、`runtimeRoutes.ts`、`storyActionService.ts` 这些热点文件上打补丁，而是把主链收成：
|
||||
|
||||
**RPG 入口域 -> RPG session 域 -> RPG runtime shell 域 -> RPG runtime story 域 -> RPG snapshot / profile 域**
|
||||
|
||||
只有这样，这条“开始游戏 -> 进入运行态 -> 推进剧情 -> 自动存档 -> 继续游戏”的链路，才会真正具备后续可读、可扩、可并行维护的工程形态。
|
||||
@@ -0,0 +1,107 @@
|
||||
# RPG 进入游戏与运行时链路旧脚本删除收口记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本轮继续按 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 收口，目标只有一个：
|
||||
|
||||
**在新 `rpg-entry`、`rpg-session`、`rpg-runtime-shell`、`rpg-runtime-panels`、`rpg-runtime-story` 主链已经接回后，物理删除旧 RPG 入口与运行态脚本，并确认源码和当前后端构建产物不再依赖旧路径。**
|
||||
|
||||
本轮不改 UI 布局、不改按钮位置、不改 tab 组织、不改弹层交互方式，也不把历史审计文档里的旧文件名当成运行时代码依赖处理。
|
||||
|
||||
## 2. 已删除旧脚本范围
|
||||
|
||||
前端旧入口与旧兼容层已从源码中移除：
|
||||
|
||||
1. `src/components/game-shell/`
|
||||
2. `src/components/game-shell/rpg-creation-flow/`
|
||||
3. `src/components/AdventurePanel.tsx`
|
||||
4. `src/hooks/story/`
|
||||
5. `src/hooks/useGameFlow.ts`
|
||||
6. `src/hooks/useGamePersistence.ts`
|
||||
7. `src/hooks/useGameShellRuntime.ts`
|
||||
8. `src/hooks/useStoryGeneration.ts`
|
||||
9. `src/services/runtimeStoryService.ts`
|
||||
10. `src/services/storageService.ts`
|
||||
|
||||
后端与共享契约旧入口已从源码中移除：
|
||||
|
||||
1. `server-node/src/routes/runtimeRoutes.ts`
|
||||
2. `server-node/src/modules/story/runtimeSession.ts`
|
||||
3. `server-node/src/modules/story/storyActionRoutes.ts`
|
||||
4. `server-node/src/modules/story/storyActionService.ts`
|
||||
5. `packages/shared/src/contracts/story.ts`
|
||||
|
||||
## 3. 新主链落点
|
||||
|
||||
删除旧脚本后，RPG 主链只允许继续落在以下新域：
|
||||
|
||||
1. 前端入口：`src/components/rpg-entry/`
|
||||
2. 前端 session：`src/hooks/rpg-session/`
|
||||
3. 前端运行态 shell：`src/components/rpg-runtime-shell/`
|
||||
4. 前端运行态面板：`src/components/rpg-runtime-panels/`
|
||||
5. 前端 runtime story：`src/hooks/rpg-runtime-story/`
|
||||
6. 前端 client：`src/services/rpg-entry/`、`src/services/rpg-runtime/`
|
||||
7. 后端 route：`server-node/src/routes/rpg-entry/`、`server-node/src/routes/rpg-profile/`、`server-node/src/routes/rpg-runtime/`
|
||||
8. 后端 runtime story：`server-node/src/modules/rpg-runtime-story/`
|
||||
9. 后端仓储：`server-node/src/repositories/rpg-entry/`、`server-node/src/repositories/rpg-profile/`、`server-node/src/repositories/rpg-runtime/`
|
||||
10. 共享契约：`packages/shared/src/contracts/rpgRuntimeStoryAction.ts`、`packages/shared/src/contracts/rpgRuntimeStoryState.ts`、`packages/shared/src/contracts/rpgRuntimeChat.ts`、`packages/shared/src/contracts/rpgRuntimeQuestAssist.ts`
|
||||
|
||||
## 4. 残留依赖检查
|
||||
|
||||
本轮使用旧路径和旧入口名扫描源码与当前后端构建产物，确认以下路径不存在且没有运行时代码引用：
|
||||
|
||||
1. `src/components/game-shell`
|
||||
2. `src/hooks/story`
|
||||
3. `src/hooks/useGameFlow.ts`
|
||||
4. `src/hooks/useGamePersistence.ts`
|
||||
5. `src/hooks/useGameShellRuntime.ts`
|
||||
6. `src/hooks/useStoryGeneration.ts`
|
||||
7. `src/services/runtimeStoryService.ts`
|
||||
8. `src/services/storageService.ts`
|
||||
9. `server-node/src/routes/runtimeRoutes.ts`
|
||||
10. `server-node/src/modules/story/runtimeSession.ts`
|
||||
11. `server-node/src/modules/story/storyActionRoutes.ts`
|
||||
12. `server-node/src/modules/story/storyActionService.ts`
|
||||
13. `packages/shared/src/contracts/story.ts`
|
||||
|
||||
补充处理：
|
||||
|
||||
1. `npm --prefix server-node run build` 已重新生成当前 `server-node/dist/server.cjs`。
|
||||
2. 旧的忽略产物 `server-node/dist/server.js` 与 `server-node/dist/server.js.map` 是 `2026-04-18` 遗留 bundle，仍包含旧路径 sourcemap，本轮已定点删除，避免本地误跑旧构建。
|
||||
3. 当前 `server-node/dist/` 只保留 `server.cjs` 与 `server.cjs.map`，旧主入口路径扫描无命中。
|
||||
|
||||
## 5. 本轮补丁
|
||||
|
||||
本轮额外修正了迁移后测试 prop 类型不一致的问题：
|
||||
|
||||
1. `src/components/rpg-runtime-panels/RpgAdventurePanel.npcChat.test.tsx`
|
||||
2. `src/components/rpg-runtime-panels/RpgAdventurePanel.test.tsx`
|
||||
|
||||
`npcChatQuestOfferUi.replacePendingOffer` 在新面板类型中是同步布尔返回，测试 mock 已从 `async () => false` 改为 `() => false`，避免旧异步 mock 继续伪装成兼容层行为。
|
||||
|
||||
## 6. 验证结果
|
||||
|
||||
已通过：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `npm --prefix server-node run build`
|
||||
3. `npx vitest run src/components/rpg-runtime-panels/RpgAdventurePanel.npcChat.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.test.tsx src/services/rpg-runtime/rpgRuntimeStoryClient.test.ts src/components/rpg-entry/RpgEntryCharacterSelectView.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx src/components/rpg-runtime-shell/useRpgRuntimeShellViewModel.test.ts src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.test.ts src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.test.ts`
|
||||
|
||||
定向前端回归结果：`8` 个测试文件、`37` 个测试通过。
|
||||
|
||||
未完全通过但不属于本轮 RPG 旧脚本删除阻塞：
|
||||
|
||||
1. `npm run typecheck`
|
||||
- 剩余错误集中在 `packages/shared/src/contracts/rpgCreationFixtures.ts`、`src/components/auth/AccountModal.test.tsx`、`src/data/customWorldLibrary.ts`、`src/services/customWorldCover.test.ts`。
|
||||
- 本轮已清掉 `RpgAdventurePanel*.test.tsx` 中与迁移相关的 `Promise<boolean>` 类型错误。
|
||||
2. `npm --prefix server-node run test`
|
||||
- RPG runtime story、RPG entry save、RPG world library、RPG profile route 等相关测试通过。
|
||||
- 剩余失败为 `custom world agent` HTTP 相关 `12` 个用例返回 `500 !== 200`，属于创作链/Agent 链路问题，不属于本轮 RPG 旧脚本删除范围。
|
||||
|
||||
## 7. 结论
|
||||
|
||||
当前 RPG 进入游戏与运行时主链已经不再依赖旧 `GameShell`、`useGame*`、`useStoryGeneration`、`hooks/story`、`runtimeStoryService`、`runtimeRoutes`、`modules/story/*`、`contracts/story.ts` 脚本。
|
||||
|
||||
后续如果继续开发 RPG 入口、运行态、runtime story 或存档恢复，只应扩展新 `rpg-*` 目录与分文件契约，不应重新创建旧路径 façade。
|
||||
@@ -0,0 +1,132 @@
|
||||
# RPG 进入游戏与运行时链路重构第一批第二批并行工作复核记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 复核目标
|
||||
|
||||
本次复核只做一件事：
|
||||
|
||||
**对照 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md`，检查第一批并行与第二批并行工作是否存在遗漏、未完成收口或仍停留在“看起来已完成但工程状态未闭合”的问题。**
|
||||
|
||||
执行边界保持如下：
|
||||
|
||||
1. 只检查工作包 A 到 H 是否达到各自文档声明的落地状态。
|
||||
2. 只补齐确认属于本次重构范围的遗漏项。
|
||||
3. 不顺手扩展 UI、玩法、协议或无关模块。
|
||||
|
||||
## 2. 复核范围
|
||||
|
||||
本次逐项核对了以下内容：
|
||||
|
||||
1. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md`
|
||||
2. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_A_PROGRESS_2026-04-21.md`
|
||||
3. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_B_PROGRESS_2026-04-21.md`
|
||||
4. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_C_PROGRESS_2026-04-21.md`
|
||||
5. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_D_PROGRESS_2026-04-21.md`
|
||||
6. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md`
|
||||
7. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_F_PROGRESS_2026-04-21.md`
|
||||
8. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md`
|
||||
9. `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md`
|
||||
10. 前端 `rpg-entry`、`rpg-session`、`rpg-runtime-shell`、`rpg-runtime-panels`、`rpg-runtime-story` 新域真实实现
|
||||
11. 后端 `routes/rpg-*`、`modules/rpg-runtime-story`、`repositories/rpg-*` 新域真实实现
|
||||
12. shared contract 分文件与兼容 façade
|
||||
13. 与工作包 E / F / G / H 直接相关的定向测试与工作树状态
|
||||
|
||||
## 3. 复核结论
|
||||
|
||||
## 3.1 第一批并行结论
|
||||
|
||||
第一批并行只包含工作包 A。
|
||||
|
||||
复核结果：
|
||||
|
||||
1. 工作包 A 要求的目录骨架、façade、barrel 与按域命名落点已经建立。
|
||||
2. 工作包 A 没有发现需要继续补做的编码遗漏。
|
||||
3. 当前 A 的剩余内容本来就属于后续工作包 B 到 H 的真实迁移，不属于遗漏。
|
||||
|
||||
结论：
|
||||
|
||||
**第一批并行无新增遗漏项。**
|
||||
|
||||
## 3.2 第二批并行总体结论
|
||||
|
||||
对照工作包 B 到 H 的进度文档与实际主链代码，当前状态如下：
|
||||
|
||||
1. 工作包 B：`rpg-entry` 已承接真实入口实现，旧 `game-shell` / `rpg-creation-flow` 路径已降级为兼容层。
|
||||
2. 工作包 C：`rpg-session` 已承接真实 session / persistence 主链，`storageService.ts` 已退化为兼容转发层。
|
||||
3. 工作包 D：`rpg-runtime-shell` 与 `rpg-runtime-panels` 已承接真实实现，旧 `GameShell*` / `AdventurePanel` 已降级为兼容入口。
|
||||
4. 工作包 E：前端 runtime story 主链已迁入 `rpg-runtime-story`，但测试工作树存在未收口的合流状态。
|
||||
5. 工作包 F：`app.ts` 已按 `rpgProfile / rpgEntry / rpgRuntimeStory / rpgRuntimeAiAssist` 挂载新域路由，旧 `runtimeRoutes.ts` 已降级。
|
||||
6. 工作包 G：后端 runtime story action / state / session 真实实现已迁入 `modules/rpg-runtime-story`，旧热点已退化为兼容导出。
|
||||
7. 工作包 H：仓储、shared contract 与定向测试基建已落到新域命名与分文件结构。
|
||||
|
||||
结论：
|
||||
|
||||
**第二批并行的主链改造基本已经完成，本轮确认到的真实遗漏主要集中在“工程收口状态”而不是“功能未落地”。**
|
||||
|
||||
## 4. 本轮确认的遗漏项
|
||||
|
||||
## 4.1 工作包 E 相关测试文件仍处于未解决合流状态
|
||||
|
||||
复核时发现：
|
||||
|
||||
1. `src/hooks/story/npcEncounterActions.test.ts` 的文件内容已经切到 `../rpg-runtime-story/rpgRuntimeStoryGateway` 新路径。
|
||||
2. 但 Git 索引仍把该文件标记为 `UU`，说明这份并行工作没有真正完成收口。
|
||||
|
||||
这会导致：
|
||||
|
||||
1. 工作包 E 虽然逻辑上已完成迁移，但工程状态仍不能算完全闭合。
|
||||
2. 后续继续判断第二批并行是否完成时，会被未解决合流状态误判为仍未完成。
|
||||
|
||||
## 4.2 后端总测试文件仍保留同一轮并行改动的未解决合流状态
|
||||
|
||||
复核时发现：
|
||||
|
||||
1. `server-node/src/app.test.ts` 仍处于 `UU` 状态。
|
||||
2. 该文件中的两侧改动并不冲突：
|
||||
- 一侧是把微信登录测试的 cookie 解析统一改成 `readCookieValue(...)`
|
||||
- 另一侧是补充 custom world agent SSE enriched session 回归测试
|
||||
3. 当前文件内容已经同时包含两侧结果，但索引没有完成正式收口。
|
||||
4. 合并后还残留了一个未被使用的 `accessCookie` 中间变量，属于典型的合流尾巴。
|
||||
|
||||
这同样属于：
|
||||
|
||||
**不是功能缺失，而是并行工作未彻底收口。**
|
||||
|
||||
## 4.3 技术文档索引未完整登记本轮工作包文档
|
||||
|
||||
复核时发现：
|
||||
|
||||
1. `docs/technical/README.md` 已登记 A、D、E、F、G、H 的进度文档。
|
||||
2. 但缺少工作包 B 与工作包 C 的进度文档入口。
|
||||
3. 这会让后续按文档索引回溯第二批并行工作时出现“文档已存在但目录索引缺失”的信息断层。
|
||||
|
||||
这属于文档收口遗漏，应当在本轮一并补齐。
|
||||
|
||||
## 5. 本轮补齐动作
|
||||
|
||||
本轮只补以下缺口：
|
||||
|
||||
1. 清理 `server-node/src/app.test.ts` 中合流后残留的未使用变量，保留两侧都应保留的测试结果。
|
||||
2. 将 `src/hooks/story/npcEncounterActions.test.ts` 作为工作包 E 已确认的正确内容进行正式收口。
|
||||
3. 将 `server-node/src/app.test.ts` 作为同轮并行改动的正确合并结果进行正式收口。
|
||||
4. 更新 `docs/technical/README.md`，补齐工作包 B、工作包 C 与本复核文档入口。
|
||||
|
||||
## 6. 本轮明确没有做的事
|
||||
|
||||
为了避免过度开发，本轮没有继续做以下事情：
|
||||
|
||||
1. 没有继续拆 UI 组件。
|
||||
2. 没有继续清理旧兼容 façade。
|
||||
3. 没有额外重构任何 route / service / repository。
|
||||
4. 没有调整任何前端交互界面设计。
|
||||
5. 没有顺手处理与本次 RPG 并行重构无直接关系的其他噪音文件。
|
||||
|
||||
## 7. 复核后状态结论
|
||||
|
||||
在本轮补齐之后，可以对第一批与第二批并行工作给出如下结论：
|
||||
|
||||
1. 第一批并行没有发现新增遗漏。
|
||||
2. 第二批并行的主链功能改造已经基本齐备。
|
||||
3. 本轮确认并补齐的遗漏主要是测试合流收口与文档索引缺口。
|
||||
4. 当前不需要继续扩大改造范围，后续可以按执行计划进入第三批统一收口。
|
||||
@@ -0,0 +1,191 @@
|
||||
# RPG 进入游戏与运行时链路重构第三批收口记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **第三批收口**，严格遵守以下边界：
|
||||
|
||||
1. 把第二批工作包 B 到 H 已完成的新域 façade 真正接回主链。
|
||||
2. 对照执行计划逐项检查“开始游戏 / 继续游戏 / 角色选择 / 冒险 runtime / 存档恢复”是否仍残留旧命名真实依赖。
|
||||
3. 只清理确认属于 RPG 主链的新域反向依赖与未接线仓储，不扩到创作链、UI 设计或玩法语义。
|
||||
|
||||
## 2. 本次完成的第三批收口
|
||||
|
||||
## 2.1 前端运行态主链不再反向依赖旧 `GameShell` 热点
|
||||
|
||||
本轮把以下真实实现从旧 `game-shell` 命名下摘回 `rpg-runtime-shell`：
|
||||
|
||||
1. `src/components/rpg-runtime-shell/RpgRuntimeCanvasStage.tsx`
|
||||
2. `src/components/rpg-runtime-shell/rpgRuntimeLoaders.tsx`
|
||||
3. `src/components/rpg-runtime-shell/useRpgSceneTransitionModel.ts`
|
||||
|
||||
同时完成以下主链接线：
|
||||
|
||||
1. `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx` 直接使用 `RpgRuntimeCanvasStage`
|
||||
2. `src/components/rpg-runtime-shell/RpgRuntimeOverlayHost.tsx` 直接使用 `rpgRuntimeLoaders`
|
||||
3. `src/components/rpg-runtime-shell/useRpgRuntimeShellViewModel.ts` 直接使用 `useRpgSceneTransitionModel`
|
||||
4. `src/components/rpg-runtime-panels/RpgRuntimePanelRouter.tsx` 直接从 `rpg-runtime-shell` 读取 `PanelLoadingFallback`
|
||||
|
||||
当前结果：
|
||||
|
||||
1. 运行态主链真实实现已经不再依赖旧 `GameShellCanvasStage`、`GameShellLoaders`、`useSceneTransitionModel`。
|
||||
2. 旧 `game-shell` 文件只保留兼容 re-export，不再作为 RPG 运行态真实落点。
|
||||
|
||||
## 2.2 前端入口域主链不再反向依赖旧平台展示 helper
|
||||
|
||||
本轮把以下入口域通用展示能力收回 `rpg-entry`：
|
||||
|
||||
1. `src/components/rpg-entry/RpgEntryBrandLogo.tsx`
|
||||
2. `src/components/rpg-entry/rpgEntryWorldPresentation.ts`
|
||||
3. `src/components/rpg-entry/RpgEntryCreationTypeModal.tsx`
|
||||
|
||||
并完成以下主链接线：
|
||||
|
||||
1. `RpgEntryHomeView.tsx` 改为直接使用 `RpgEntryBrandLogo` 与 `rpgEntryWorldPresentation`
|
||||
2. `RpgEntryWorldDetailView.tsx` 改为直接使用 `rpgEntryWorldPresentation`
|
||||
3. `RpgEntryFlowShellImpl.tsx` 改为直接使用 `RpgEntryCreationTypeModal`
|
||||
|
||||
当前结果：
|
||||
|
||||
1. `rpg-entry` 真实实现不再依赖旧 `PlatformBrandLogo`、`platformWorldPresentation`、`PlatformCreationTypeModal`。
|
||||
2. 旧 `game-shell` 对应文件只保留兼容导出。
|
||||
|
||||
## 2.3 工作包 H 新仓储已真正接回后端 RPG 主链
|
||||
|
||||
本轮把工作包 H 中已建立但尚未接回主链的新仓储正式注入 `AppContext`：
|
||||
|
||||
1. `rpgProfileDashboardRepository`
|
||||
2. `rpgBrowseHistoryRepository`
|
||||
3. `rpgSaveArchiveRepository`
|
||||
4. `rpgRuntimeSnapshotRepository`
|
||||
|
||||
并完成以下主链接线：
|
||||
|
||||
1. `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
|
||||
- 资料看板、钱包流水、游玩统计走 `rpgProfileDashboardRepository`
|
||||
- 浏览历史走 `rpgBrowseHistoryRepository`
|
||||
- 设置读写走 `rpgProfileDashboardRepository`
|
||||
2. `server-node/src/routes/rpg-entry/rpgEntrySaveRoutes.ts`
|
||||
- snapshot 读写删除走 `rpgRuntimeSnapshotRepository`
|
||||
- save archive 列表与恢复走 `rpgSaveArchiveRepository`
|
||||
3. `server-node/src/routes/rpg-runtime/rpgRuntimeStoryRoutes.ts`
|
||||
- runtime story 状态读取与动作结算走 `rpgRuntimeSnapshotRepository`
|
||||
|
||||
当前结果：
|
||||
|
||||
1. `rpgProfile`、`rpgEntrySave`、`rpgRuntimeStory` 主链已经不再直接把大 `runtimeRepository` 当作唯一注入边界。
|
||||
2. 工作包 H 的新仓储不再停留在“命名骨架已存在但主链未接线”的状态。
|
||||
|
||||
## 2.4 新域 shared contract 进一步脱离旧 `story.ts` façade
|
||||
|
||||
本轮继续把 RPG 新主链中的 shared contract 直接切到分文件：
|
||||
|
||||
1. `server-node/src/routes/rpg-runtime/rpgRuntimeStoryRoutes.ts`
|
||||
- 改为直接使用 `rpgRuntimeStoryState.ts`
|
||||
2. `server-node/src/routes/rpg-runtime/rpgRuntimeAiAssistRoutes.ts`
|
||||
- 改为直接使用 `rpgRuntimeChat.ts`、`rpgRuntimeQuestAssist.ts`
|
||||
3. `server-node/src/modules/rpg-runtime-story/RpgRuntimeSessionDomain.ts`
|
||||
- 改为直接使用 `rpgRuntimeStoryAction.ts`
|
||||
- snapshot 类型改为使用 `RpgRuntimeSavedSnapshot`
|
||||
4. `server-node/src/modules/rpg-runtime-story/RpgRuntimeStoryActionDomain.ts`
|
||||
- runtime story request/response 类型改为直接使用 `rpgRuntimeStoryState.ts`
|
||||
- snapshot 仓储端口改为使用 `RpgRuntimeSnapshotRepositoryPort`
|
||||
|
||||
当前结果：
|
||||
|
||||
1. RPG 新域主链已经显著减少对旧 `packages/shared/src/contracts/story.ts` façade 的反向依赖。
|
||||
2. `story.ts` 继续保留兼容职责，但不再是第三批已收口主链的真实首选入口。
|
||||
|
||||
## 2.5 补齐世界库主链接线遗漏
|
||||
|
||||
代码级复核后，本轮额外补齐了第三批范围内一个真实遗漏：世界库主链虽然已经有 `rpg-entry` 路由和 `RpgWorldLibraryRepository`，但此前并未完整接回主链。
|
||||
|
||||
本次补齐包括：
|
||||
|
||||
1. `server-node/src/context.ts` 与 `server-node/src/server.ts`
|
||||
- 正式注入 `rpgWorldLibraryRepository`
|
||||
2. `server-node/src/routes/rpg-entry/rpgWorldLibraryRoutes.ts`
|
||||
- 作品库/广场/详情/发布/下架/删除等读写改为直接走 `rpgWorldLibraryRepository`
|
||||
- `rpgWorldProfileRepository` 继续保留给 Agent 发布链与发布服务使用
|
||||
3. `src/services/rpg-entry/rpgEntryLibraryClient.ts`
|
||||
- 改为直接承接 `/api/runtime/custom-world-library` 与 `/api/runtime/custom-world-gallery` 请求
|
||||
- 不再反向依赖旧 `storageService.ts` 兼容层
|
||||
4. `src/services/rpg-entry/rpgEntryLibraryClient.test.ts`
|
||||
- 补齐入口世界库 client 的定向回归
|
||||
|
||||
当前结果：
|
||||
|
||||
1. “平台首页 / 世界详情 / 开始游戏”所依赖的世界库链路，现在已经和 save/profile 一样真正回到 `rpg-entry` + `rpg-entry repository` 主链。
|
||||
2. 第三批范围内不再残留“新命名已建好，但真实主链仍穿旧兼容层/旧仓储”的世界库遗漏。
|
||||
|
||||
## 3. 老代码物理删除补充
|
||||
|
||||
根据后续收口要求，本轮在主链稳定后继续删除旧兼容层，不再让 RPG 入口与运行态链路通过旧脚本名兜底。
|
||||
|
||||
已删除的旧前端入口包括：
|
||||
|
||||
1. `src/components/AdventurePanel.tsx`
|
||||
2. `src/components/game-shell/*`
|
||||
3. `src/components/game-shell/rpg-creation-flow/*`
|
||||
4. `src/hooks/useGameFlow.ts`
|
||||
5. `src/hooks/useGamePersistence.ts`
|
||||
6. `src/hooks/useGameShellRuntime.ts`
|
||||
7. `src/hooks/useStoryGeneration.ts`
|
||||
8. `src/services/runtimeStoryService.ts`
|
||||
9. `src/services/storageService.ts`
|
||||
|
||||
已删除的旧后端与共享契约入口包括：
|
||||
|
||||
1. `server-node/src/routes/runtimeRoutes.ts`
|
||||
2. `server-node/src/modules/story/runtimeSession.ts`
|
||||
3. `server-node/src/modules/story/storyActionService.ts`
|
||||
4. `server-node/src/modules/story/storyActionRoutes.ts`
|
||||
5. `packages/shared/src/contracts/story.ts`
|
||||
|
||||
同步完成的主链迁移包括：
|
||||
|
||||
1. `RpgEntryFlowShellImpl.tsx` 直接使用 `src/components/rpg-entry/useRpgCreation*` hooks，不再反向依赖 `game-shell/rpg-creation-flow`。
|
||||
2. runtime story client 测试迁到 `src/services/rpg-runtime/rpgRuntimeStoryClient.test.ts`。
|
||||
3. profile / world library 路由测试迁到 `src/services/rpg-entry/rpgEntryClients.routing.test.ts`。
|
||||
4. 冒险面板测试迁到 `src/components/rpg-runtime-panels/RpgAdventurePanel*.test.tsx`。
|
||||
5. `AdventurePanelOverlays` 子模块改名并迁到 `src/components/rpg-runtime-panels/RpgAdventurePanelOverlays.tsx`。
|
||||
6. 后端与前端 shared contract import 已切到 `rpgRuntimeChat.ts`、`rpgRuntimeQuestAssist.ts`、`rpgRuntimeStoryAction.ts`、`rpgRuntimeStoryState.ts`。
|
||||
|
||||
本轮仍然刻意没有继续扩大到以下内容：
|
||||
|
||||
1. 没有重命名历史审计、旧 PRD、旧技术方案中作为历史记录出现的旧文件名。
|
||||
2. 没有继续拆分 `runtimeRepository.ts` 剩余实现。
|
||||
3. 没有改 UI 布局、按钮位置、tab 组织、弹层方式或任何用户可见交互设计。
|
||||
4. 没有清理与本执行计划无关的创作链旧文件；只删除 RPG 入口 / 运行态链路已经不再依赖的旧脚本。
|
||||
|
||||
## 4. 本轮检查后确认的未扩范围
|
||||
|
||||
为了避免过度开发，本轮明确没有继续扩到以下内容：
|
||||
|
||||
1. 没有继续改 UI 布局、按钮位置、tab 组织、弹层方式或任何用户可见交互设计。
|
||||
2. 没有继续拆分 `runtimeRepository.ts` 剩余实现，也没有扩大到更多仓储接口重命名。
|
||||
3. 没有顺手清理历史文档里的旧文件名引用，只更新本次执行收口文档。
|
||||
|
||||
## 5. 第三批遗漏复核结论
|
||||
|
||||
对照执行计划中的第三批要求，本轮确认如下：
|
||||
|
||||
1. **把 B 到 H 的 façade 接回主链**：已完成
|
||||
- 前端 `rpg-entry`、`rpg-runtime-shell`、`rpg-runtime-panels`
|
||||
- 后端 `rpg-profile`、`rpg-entry-save`、`rpg-runtime-story`
|
||||
2. **联调继续游戏 / 开始游戏 / 角色选择 / 冒险 runtime / 存档恢复**：本轮已把这些链路上的主注入边界和真实落点接回新域
|
||||
3. **清理旧命名与兼容导出**：已完成主链级清理，并按本次补充要求物理删除旧兼容脚本
|
||||
|
||||
当前仍保留但不计为遗漏的部分：
|
||||
|
||||
1. 历史审计、旧 PRD、旧技术方案中仍会提到旧文件名，这是历史记录，不代表运行时代码依赖。
|
||||
2. `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx` 仍保持原交互结构，只做脚本路径与命名收口。
|
||||
|
||||
## 6. 结论
|
||||
|
||||
在“不改 UI、不改玩法、不扩到创作链执行方案”的前提下，本轮已经完成 RPG 执行计划中的第三批主链收口：
|
||||
|
||||
1. 新域真实实现已经接回前后端主链。
|
||||
2. RPG 主链对旧 `GameShell` / `runtimeRoutes` / `story.ts` façade 的真实依赖已经删除。
|
||||
3. 复核中发现并补齐了世界库主链接线遗漏后，当前没有再发现属于本次第三批范围、且必须继续补做的遗漏项。
|
||||
@@ -0,0 +1,101 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 A 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 A：RPG 命名规范与目录骨架**，严格遵守以下边界：
|
||||
|
||||
1. 先建立 RPG 进入游戏链的新目录与命名落点。
|
||||
2. 先补 façade、barrel、path 常量和按域仓储入口，不提前迁移主流程逻辑。
|
||||
3. 不修改现有前端交互界面设计，不提前实现工作包 B 到 H 的真实拆分。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 前端目录骨架
|
||||
|
||||
已新增以下前端目录与兼容 façade：
|
||||
|
||||
1. `src/components/rpg-entry/`
|
||||
2. `src/components/rpg-runtime-shell/`
|
||||
3. `src/components/rpg-runtime-panels/`
|
||||
4. `src/hooks/rpg-session/`
|
||||
5. `src/hooks/rpg-runtime-story/`
|
||||
6. `src/services/rpg-entry/`
|
||||
7. `src/services/rpg-runtime/`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. `RpgEntryFlowShell` 先桥接当前真实存在的 `src/components/game-shell/rpg-creation-flow/RpgCreationShell.tsx`，不再依赖已删除的旧 `PreGameSelectionFlow.tsx`。
|
||||
2. `RpgEntryHomeView`、`RpgEntryWorldDetailView`、`RpgEntryCharacterSelectView` 继续桥接旧平台首页、世界详情和选角视图。
|
||||
3. `RpgRuntimeShell`、`RpgRuntimeStageRouter`、`RpgRuntimePanelRouter`、`RpgAdventurePanel`、`RpgRuntimeOverlayHost` 继续桥接旧 `GameShell*` 与 `AdventurePanel` 组件。
|
||||
4. `useRpgSessionBootstrap`、`useRpgSessionPersistence`、`useRpgRuntimeSession` 继续桥接 `useGameFlow`、`useGamePersistence`、`useGameShellRuntime`。
|
||||
5. `useRpgRuntimeStory`、`useRpgRuntimeStoryController`、`useRpgRuntimeStoryFlow`、`useRpgRuntimeInteractionFlow`、`useRpgRuntimeNpcInteraction`、`rpgRuntimeStoryGateway` 继续桥接旧 story runtime hooks 与 gateway。
|
||||
|
||||
## 2.2 前端 service/client 骨架
|
||||
|
||||
已新增以下 service/client 落点：
|
||||
|
||||
1. `src/services/rpg-entry/rpgEntryLibraryClient.ts`
|
||||
2. `src/services/rpg-entry/rpgProfileClient.ts`
|
||||
3. `src/services/rpg-runtime/rpgSnapshotClient.ts`
|
||||
4. `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
|
||||
5. `src/services/rpg-runtime/rpgRuntimeChatClient.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. `rpgEntryLibraryClient` 继续桥接 `storageService.ts` 中的世界库、世界广场与发布相关接口。
|
||||
2. `rpgProfileClient` 继续桥接资料看板、浏览历史、设置与继续游戏归档相关接口。
|
||||
3. `rpgSnapshotClient` 继续桥接快照读写接口。
|
||||
4. `rpgRuntimeStoryClient` 继续桥接 `/api/runtime/story` 的旧 client。
|
||||
5. `rpgRuntimeChatClient` 继续桥接 `aiService.ts` 中的角色聊天、NPC 对话与招募对话接口。
|
||||
|
||||
## 2.3 后端目录骨架
|
||||
|
||||
已新增以下后端目录与 façade：
|
||||
|
||||
1. `server-node/src/routes/rpg-entry/`
|
||||
2. `server-node/src/routes/rpg-profile/`
|
||||
3. `server-node/src/routes/rpg-runtime/`
|
||||
4. `server-node/src/modules/rpg-runtime-story/`
|
||||
5. `server-node/src/repositories/rpg-entry/`
|
||||
6. `server-node/src/repositories/rpg-profile/`
|
||||
7. `server-node/src/repositories/rpg-runtime/`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. `createRpgProfileRoutes()`、`createRpgEntrySaveRoutes()`、`createRpgWorldLibraryRoutes()`、`createRpgRuntimeAiAssistRoutes()` 当前只提供空路由骨架与稳定 path 常量。
|
||||
2. `createRpgRuntimeStoryRoutes()` 继续桥接旧 `createStoryActionRoutes()`，确保 runtime story 路由已经有新命名落点。
|
||||
3. `RpgRuntimeStoryActionService`、`RpgRuntimeSessionLoader`、`RpgRuntimeOptionCompiler`、`RpgRuntimeSnapshotSync` 继续桥接旧 `storyActionService.ts` 与 `runtimeSession.ts`。
|
||||
4. `RpgRuntimeSnapshotRepository`、`RpgSaveArchiveRepository`、`RpgProfileDashboardRepository`、`RpgWorldLibraryRepository` 先以委托 runtimeRepository 的方式建立按域命名仓储入口。
|
||||
|
||||
## 3. 本次没有做的事
|
||||
|
||||
以下内容仍保持原状，留给后续工作包：
|
||||
|
||||
1. 没有改 `GameShellMainContent.tsx`、`GameShellRuntime.tsx`、`AdventurePanel.tsx` 的内部实现。
|
||||
2. 没有拆 `useGameFlow.ts`、`useGamePersistence.ts`、`useGameShellRuntime.ts` 的真实逻辑。
|
||||
3. 没有拆 `useStoryGeneration.ts`、`npcEncounterActions.ts`、`runtimeStoryCoordinator.ts` 的内部职责。
|
||||
4. 没有改 `server-node/src/app.ts`、`server-node/src/routes/runtimeRoutes.ts`、`server-node/src/modules/story/storyActionService.ts`、`server-node/src/modules/story/runtimeSession.ts` 的真实挂载与内部逻辑。
|
||||
5. 没有补 shared contract 新文件，本轮执行方案的工作包 A 范围未把共享契约骨架列为必做项，因此保持到工作包 H 统一收口。
|
||||
6. 没有修改任何前端交互界面设计。
|
||||
|
||||
## 4. 验证与现状说明
|
||||
|
||||
本轮已执行：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
|
||||
验证结果：
|
||||
|
||||
1. 编码检查通过。
|
||||
2. 全量 `npm run typecheck` 当前未通过，但失败项主要来自工作树中已存在的并行修改与历史类型问题。
|
||||
3. 本轮已修正新 façade 中对已删除旧入口 `PreGameSelectionFlow.tsx` 的失效导入，当前 `RpgEntryFlowShell` 已改为桥接真实存在的 `rpg-creation-flow` 入口。
|
||||
|
||||
## 5. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 B 可以直接把平台入口与选角真实实现落到 `src/components/rpg-entry/`，而不必再次讨论命名与目录。
|
||||
2. 工作包 C 可以直接把 session/bootstrap/persistence 的调用方迁到 `src/hooks/rpg-session/` 与 `src/services/rpg-runtime/`。
|
||||
3. 工作包 D 可以直接让运行态壳层与面板消费 `rpg-runtime-shell`、`rpg-runtime-panels` 新入口。
|
||||
4. 工作包 E 可以直接把 story runtime 与 NPC 交互迁到 `src/hooks/rpg-runtime-story/` 和 `src/services/rpg-runtime/`。
|
||||
5. 工作包 F、G、H 可以直接基于 `server-node/src/routes/rpg-*`、`server-node/src/modules/rpg-runtime-story/`、`server-node/src/repositories/rpg-*/` 继续做真实迁移，而不用重新搭第一层命名骨架。
|
||||
@@ -0,0 +1,108 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 B 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 B：前端 RPG 入口壳层拆分**，严格遵守以下边界：
|
||||
|
||||
1. 只改前端入口链，不改后端接口语义。
|
||||
2. 只处理平台首页、世界详情、继续游戏、进入世界、选角相关入口壳层与入口 hooks。
|
||||
3. 不拆运行态冒险面板，不修改任何前端交互界面设计。
|
||||
|
||||
## 2. 本次已完成内容
|
||||
|
||||
## 2.1 `rpg-entry` 已成为真实入口目录
|
||||
|
||||
以下文件现在承载真实实现，不再只是 façade：
|
||||
|
||||
1. `src/components/rpg-entry/RpgEntryFlowShell.tsx`
|
||||
2. `src/components/rpg-entry/RpgEntryFlowShellImpl.tsx`
|
||||
3. `src/components/rpg-entry/RpgEntryHomeView.tsx`
|
||||
4. `src/components/rpg-entry/RpgEntryWorldDetailView.tsx`
|
||||
5. `src/components/rpg-entry/RpgEntryCharacterSelectView.tsx`
|
||||
6. `src/components/rpg-entry/rpgEntryTypes.ts`
|
||||
7. `src/components/rpg-entry/rpgEntryShared.ts`
|
||||
|
||||
这意味着当前 RPG 平台入口、详情页和选角页的真实物理落点已经从旧 `game-shell` 命名转入 `rpg-entry` 域，满足执行方案里“平台首页/详情页/选角能落到 `rpgEntry` 目录”的验收要求。
|
||||
|
||||
## 2.2 入口相关 hooks 已补齐到 `rpg-entry`
|
||||
|
||||
本轮新增或迁入以下入口域 hooks：
|
||||
|
||||
1. `src/components/rpg-entry/useRpgEntryBootstrap.ts`
|
||||
2. `src/components/rpg-entry/useRpgEntryLibraryDetail.ts`
|
||||
3. `src/components/rpg-entry/useRpgEntryNavigation.ts`
|
||||
4. `src/components/rpg-entry/useRpgEntrySaveResume.ts`
|
||||
5. `src/components/rpg-entry/useRpgEntryCharacterSelect.ts`
|
||||
|
||||
其中：
|
||||
|
||||
1. `useRpgEntryBootstrap` 负责平台 works / library / gallery / history / save / dashboard 拉取与继续游戏恢复入口。
|
||||
2. `useRpgEntryLibraryDetail` 负责详情页打开、作品详情读取、继续创作入口、发布/下架/删除动作。
|
||||
3. `useRpgEntryNavigation` 收口入口阶段跳转，避免壳层里继续散落匿名 `setSelectionStage(...)`。
|
||||
4. `useRpgEntrySaveResume` 明确“继续游戏”动作入口。
|
||||
5. `useRpgEntryCharacterSelect` 补齐选角页回退与确认动作的入口域命名。
|
||||
|
||||
## 2.3 旧 `game-shell` / `rpg-creation-flow` 路径已降级为兼容层
|
||||
|
||||
以下旧文件已改为兼容 re-export，不再持有真实实现：
|
||||
|
||||
1. `src/components/game-shell/PlatformHomeView.tsx`
|
||||
2. `src/components/game-shell/PlatformWorldDetailView.tsx`
|
||||
3. `src/components/game-shell/CharacterSelectionFlow.tsx`
|
||||
4. `src/components/game-shell/rpg-creation-flow/RpgCreationShell.tsx`
|
||||
5. `src/components/game-shell/rpg-creation-flow/RpgCreationShellImpl.tsx`
|
||||
6. `src/components/game-shell/rpg-creation-flow/rpgCreationFlowTypes.ts`
|
||||
7. `src/components/game-shell/rpg-creation-flow/rpgCreationFlowShared.ts`
|
||||
8. `src/components/game-shell/rpg-creation-flow/useRpgCreationPlatformBootstrap.ts`
|
||||
9. `src/components/game-shell/rpg-creation-flow/useRpgCreationDetailNavigation.ts`
|
||||
|
||||
兼容策略如下：
|
||||
|
||||
1. 旧命名继续导出，避免并行工作包与现有测试断开。
|
||||
2. 真实实现统一回落到 `rpg-entry`。
|
||||
3. 本轮不清理 legacy façade，只让它们退化成稳定桥接层。
|
||||
|
||||
## 2.4 主链调用方已接回 `rpg-entry`
|
||||
|
||||
本轮已把主入口相关调用改为直接消费 `rpg-entry`：
|
||||
|
||||
1. `src/components/game-shell/GameShellMainContent.tsx`
|
||||
2. `src/components/game-shell/useGameShellViewModel.ts`
|
||||
3. `src/components/rpg-entry/index.ts`
|
||||
|
||||
当前结果：
|
||||
|
||||
1. 主阶段路由器 lazy import 已直接走 `RpgEntryFlowShell` 与 `RpgEntryCharacterSelectView`。
|
||||
2. `SelectionStage` 类型已从 `rpg-entry` 暴露，不再依赖旧 `rpg-creation-flow` 作为主命名根。
|
||||
3. 旧路径仍可用，但已经不再是主链真实入口。
|
||||
|
||||
## 3. 对照执行方案的完成判断
|
||||
|
||||
工作包 B 本轮已完成以下计划项：
|
||||
|
||||
1. 已把平台首页/详情页/继续游戏/进入世界从旧 `PreGameSelectionFlow` 所属旧命名体系中收进 `rpg-entry` 域。
|
||||
2. 已让 `rpg-entry` 成为真实实现目录，而不是只保留 façade。
|
||||
3. 已补齐入口阶段相关新 hooks。
|
||||
4. 已让旧路径退化为兼容桥接层。
|
||||
5. 没有修改任何前端交互界面设计。
|
||||
|
||||
当前仍刻意保留的边界：
|
||||
|
||||
1. 没有拆运行态冒险面板，这属于工作包 D。
|
||||
2. 没有改 session/bootstrap/persistence 主逻辑，这属于工作包 C。
|
||||
3. 没有改后端接口语义与 route/service 边界，这属于工作包 F/G/H。
|
||||
4. 没有提前清理所有 legacy re-export，本轮以稳定主链为先。
|
||||
|
||||
## 4. 验证与遗漏核查
|
||||
|
||||
本轮需要重点核查的遗漏项已经逐项确认：
|
||||
|
||||
1. `RpgEntryFlowShell` 不再桥接旧实现，已直接使用 `rpg-entry` 目录下的真实壳层。
|
||||
2. `PlatformHomeView`、`PlatformWorldDetailView`、`CharacterSelectionFlow` 的旧路径已不再持有真实实现。
|
||||
3. `GameShellMainContent` 已直接 lazy import `rpg-entry` 新入口。
|
||||
4. `SelectionStage` 已从 `rpg-entry` 作为主出口暴露。
|
||||
5. 复核时补齐了一个第二批收口遗漏：`RpgEntryFlowShellImpl`、`useRpgEntryBootstrap`、`useRpgEntryLibraryDetail` 这些 `rpg-entry` 真实实现已改为直接消费 `rpg-entry` 新域 client，不再反向依赖旧 `storageService.ts` 作为主链入口。
|
||||
|
||||
本轮未执行全量 `typecheck`，原因是工作树存在并行改动与未解决冲突文件；但已把本工作包范围内最容易遗漏的主链接线点和兼容层路径全部补齐。
|
||||
@@ -0,0 +1,115 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 C 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 C：前端 session / bootstrap / persistence 拆分**，严格遵守以下边界：
|
||||
|
||||
1. 把 `useGameFlow.ts`、`useGamePersistence.ts`、`useGameShellRuntime.ts` 的真实实现收进 `rpg-session` 域。
|
||||
2. 把 snapshot / save archive 相关 client 从 `storageService.ts` 抽到 `src/services/rpg-runtime/`、`src/services/rpg-entry/`。
|
||||
3. 旧文件只保留兼容导出，不再继续承载主实现。
|
||||
4. 不修改 AdventurePanel UI，不修改后端 story 动作语义，不修改任何前端交互界面设计。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 `rpg-session` 主实现已承接 session 链
|
||||
|
||||
本轮已把以下真实实现迁入新域目录：
|
||||
|
||||
1. `src/hooks/rpg-session/useRpgSessionBootstrap.ts`
|
||||
2. `src/hooks/rpg-session/useRpgSessionPersistence.ts`
|
||||
3. `src/hooks/rpg-session/useRpgRuntimeSession.ts`
|
||||
4. `src/hooks/rpg-session/rpgSessionTypes.ts`
|
||||
|
||||
落地结果：
|
||||
|
||||
1. `useRpgSessionBootstrap` 现在直接承载世界选择、角色确认、新开局 `GameState` 初始化逻辑。
|
||||
2. `useRpgSessionPersistence` 现在直接承载自动存档、继续游戏恢复、远端快照拉取与 runtime story 恢复刷新。
|
||||
3. `useRpgRuntimeSession` 现在直接组合 bootstrap / persistence / story / combat / companion 等链路，成为主运行态装配入口。
|
||||
|
||||
## 2.2 旧 `useGame*` 文件已退化为兼容 façade
|
||||
|
||||
以下旧文件已不再承载主实现，只保留兼容导出：
|
||||
|
||||
1. `src/hooks/useGameFlow.ts`
|
||||
2. `src/hooks/useGamePersistence.ts`
|
||||
3. `src/hooks/useGameShellRuntime.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. 旧调用方仍可继续工作，避免影响并行工作包。
|
||||
2. 正式主入口已经切到 `useRpgRuntimeSession`。
|
||||
3. `BottomTab` 类型已从 `rpg-session` 域提供，避免继续绑在旧 hook 文件上。
|
||||
|
||||
## 2.3 snapshot / save archive client 已迁到新域
|
||||
|
||||
本轮已把快照与继续游戏归档的真实请求实现迁入：
|
||||
|
||||
1. `src/services/rpg-runtime/rpgRuntimeRequest.ts`
|
||||
2. `src/services/rpg-runtime/rpgSnapshotClient.ts`
|
||||
3. `src/services/rpg-entry/rpgProfileClient.ts`
|
||||
|
||||
落地结果：
|
||||
|
||||
1. `rpgSnapshotClient` 现在直接承载 `/api/runtime/save/snapshot` 的读取、写入、删除。
|
||||
2. `rpgProfileClient` 现在直接承载设置、个人资料、浏览历史、继续游戏归档相关请求。
|
||||
3. `storageService.ts` 已退化为兼容转发层，不再继续作为 snapshot / save archive 主实现落点。
|
||||
|
||||
## 2.4 主入口与直接类型依赖已切换
|
||||
|
||||
本轮已更新以下直接调用点：
|
||||
|
||||
1. `src/App.tsx` 改为直接使用 `useRpgRuntimeSession`
|
||||
2. `src/components/game-shell/types.ts`
|
||||
3. `src/components/game-shell/GameShellMainContent.tsx`
|
||||
4. `src/components/game-shell/GameShellStoryPanels.tsx`
|
||||
|
||||
当前状态：
|
||||
|
||||
1. 运行态主入口已经不再直接依赖 `useGameShellRuntime`。
|
||||
2. `GameShell` 相关组件仍保持 UI 与结构不变，只调整了 session 域导入路径。
|
||||
|
||||
## 2.5 测试补齐
|
||||
|
||||
本轮补齐或切换了以下定向测试：
|
||||
|
||||
1. `src/hooks/runtimeAuthGuards.test.tsx`
|
||||
2. `src/hooks/useGameFlow.customWorld.test.tsx`
|
||||
3. `src/services/rpg-entry/rpgProfileClient.test.ts`
|
||||
4. `src/services/rpg-runtime/rpgSnapshotClient.test.ts`
|
||||
|
||||
目的：
|
||||
|
||||
1. 覆盖 `rpg-session` 新 hook 的远端鉴权守卫行为。
|
||||
2. 覆盖自定义世界进入世界后的 bootstrap 初始化结果。
|
||||
3. 覆盖迁入新域后的 browse history / save archive / snapshot 路由请求。
|
||||
|
||||
## 3. 本次没有做的事
|
||||
|
||||
以下内容仍保持原状，留给后续工作包：
|
||||
|
||||
1. 没有拆 `AdventurePanel.tsx`、`GameShellRuntime.tsx`、`GameShellMainContent.tsx` 的内部 UI 组织。
|
||||
2. 没有拆 `useStoryGeneration.ts`、`npcEncounterActions.ts`、`runtimeStoryCoordinator.ts` 的 runtime story 内部职责。
|
||||
3. 没有修改后端 `storyActionService.ts`、`runtimeSession.ts` 或任何路由组织。
|
||||
4. 没有修改平台入口/世界详情/选角页面的视觉结构、按钮位置、tab 组织和独立面板交互方式。
|
||||
|
||||
## 4. 验证与检查
|
||||
|
||||
本轮应执行并记录：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `npx vitest run src/hooks/runtimeAuthGuards.test.tsx src/hooks/useGameFlow.customWorld.test.tsx src/services/rpg-entry/rpgProfileClient.test.ts src/services/rpg-runtime/rpgSnapshotClient.test.ts src/services/storageService.test.ts`
|
||||
|
||||
重点核查点：
|
||||
|
||||
1. 主入口是否已经切到 `useRpgRuntimeSession`。
|
||||
2. `useGameFlow.ts`、`useGamePersistence.ts`、`useGameShellRuntime.ts` 是否只剩兼容导出。
|
||||
3. `storageService.ts` 是否已不再承载 snapshot / save archive 的真实实现。
|
||||
4. 是否没有改动任何前端界面结构与交互表现。
|
||||
|
||||
## 5. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 B / D 可以继续消费 `rpg-session` 新域入口，而不必再从旧 `useGame*` 文件接主逻辑。
|
||||
2. 工作包 E 可以只关注 runtime story 链，不必再同时承担 session / persistence 主实现迁移。
|
||||
3. 后续清理旧命名时，可以直接删除 `useGame*` 兼容层，而不会再触发大规模逻辑回迁。
|
||||
@@ -0,0 +1,130 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 D 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 D：前端运行态 shell 与面板拆分**，严格遵守以下边界：
|
||||
|
||||
1. 把 `GameShellRuntime.tsx`、`GameShellMainContent.tsx`、`GameShellStoryPanels.tsx`、`AdventurePanel.tsx` 的真实实现迁入 `rpg-runtime-shell` 与 `rpg-runtime-panels`。
|
||||
2. 旧 `GameShell*` 与 `AdventurePanel` 保留兼容桥接，不在这一轮硬删旧路径。
|
||||
3. 不改平台入口链、不改 runtime story 后端协议、不改任何前端交互界面设计。
|
||||
4. 冒险主面板只做最小必要的 section 拆分，不额外扩散成更多与工作包 D 无关的重构。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 RPG 运行态 shell 已承接真实实现
|
||||
|
||||
以下文件已从 façade 升级为真实实现：
|
||||
|
||||
1. `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx`
|
||||
2. `src/components/rpg-runtime-shell/RpgRuntimeStageRouter.tsx`
|
||||
3. `src/components/rpg-runtime-shell/RpgRuntimeOverlayHost.tsx`
|
||||
4. `src/components/rpg-runtime-shell/useRpgRuntimeShellViewModel.ts`
|
||||
5. `src/components/rpg-runtime-shell/useRpgRuntimeOverlayState.ts`
|
||||
6. `src/components/rpg-runtime-shell/types.ts`
|
||||
|
||||
本轮完成的真实迁移包括：
|
||||
|
||||
1. `App.tsx` 主入口已经改为直接挂载 `RpgRuntimeShell`，不再把旧 `GameShellRuntime` 当作真实主入口。
|
||||
2. `RpgRuntimeShell` 已承接运行态总外壳、画布舞台、主阶段路由、overlay host 装配。
|
||||
3. `RpgRuntimeStageRouter` 已承接平台入口 / 角色选择 / 冒险运行态三阶段切换。
|
||||
4. `RpgRuntimeOverlayHost` 已承接角色面板浮层、背包浮层、冒险实体详情、营地、地图、角色聊天与 NPC 交互弹层。
|
||||
5. `useRpgRuntimeShellViewModel` 已承接运行态 overlay 状态、过场可见态、统计数据和 scene transition choice 包装。
|
||||
6. `useRpgRuntimeOverlayState` 已把旧 `useGameShellViewModel` 的壳层状态迁入 RPG 域命名。
|
||||
|
||||
## 2.2 RPG 主面板路由与冒险主面板已承接真实实现
|
||||
|
||||
以下文件已从 façade 升级为真实实现：
|
||||
|
||||
1. `src/components/rpg-runtime-panels/RpgRuntimePanelRouter.tsx`
|
||||
2. `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx`
|
||||
|
||||
本轮完成的真实迁移包括：
|
||||
|
||||
1. `RpgRuntimePanelRouter` 已承接冒险 / 角色 / 背包三主标签切换。
|
||||
2. `RpgAdventurePanel` 已成为真实冒险主面板实现，不再只是桥接旧 `AdventurePanel`。
|
||||
3. 冒险主面板按执行计划要求显式拆成了三个主 section：
|
||||
- story section：剧情展示区与对话流
|
||||
- choice section：按钮区、快捷入口、NPC 输入框
|
||||
- overlay section：任务/设置/统计/奖励等独立面板挂载
|
||||
4. 拆分后保持了原有 UI 结构、按钮位置、浮层方式和交互顺序不变。
|
||||
5. 同时修正了冒险面板测试里要求隐藏的说明文本，避免迁移后把 `detailText` 重新暴露到 UI 中。
|
||||
|
||||
## 2.3 旧热点文件已降级为兼容桥接层
|
||||
|
||||
以下旧热点文件已不再承载真实实现，只保留兼容入口：
|
||||
|
||||
1. `src/components/game-shell/GameShellRuntime.tsx`
|
||||
2. `src/components/game-shell/GameShellMainContent.tsx`
|
||||
3. `src/components/game-shell/GameShellStoryPanels.tsx`
|
||||
4. `src/components/game-shell/GameShellOverlays.tsx`
|
||||
5. `src/components/AdventurePanel.tsx`
|
||||
6. `src/components/game-shell/useGameShellRuntimeViewModel.ts`
|
||||
7. `src/components/game-shell/useGameShellViewModel.ts`
|
||||
8. `src/components/game-shell/types.ts`
|
||||
|
||||
当前策略：
|
||||
|
||||
1. 旧 `GameShell*` 路径继续可被现有调用与测试引用。
|
||||
2. 旧 hook / type 文件继续对外提供兼容别名，避免并行工作流马上失效。
|
||||
3. 真实运行态主链已经切到 `rpg-runtime-shell` 与 `rpg-runtime-panels`，旧热点不再继续扩大职责。
|
||||
|
||||
## 2.4 为兼容迁移补齐的新类型出口
|
||||
|
||||
为了避免本轮迁移造成旧桥接和 barrel 断裂，本轮额外补齐了以下类型出口：
|
||||
|
||||
1. `RpgRuntimeShellProps`
|
||||
2. `RpgRuntimeShellViewModelResult`
|
||||
3. `RpgEntryHomeViewProps`
|
||||
4. `RpgEntryWorldDetailViewProps`
|
||||
|
||||
这些改动只用于保证工作包 D 新目录可以作为真实调用入口和兼容桥的稳定目标，不属于额外功能开发。
|
||||
|
||||
## 3. 本次刻意未做的事
|
||||
|
||||
以下内容明确保持到其他工作包，不在本轮越界处理：
|
||||
|
||||
1. 没有改平台入口链编排；`rpg-entry` 的真实拆分仍属于工作包 B。
|
||||
2. 没有改 session/bootstrap/persistence 语义；这部分仍属于工作包 C。
|
||||
3. 没有改 runtime story hooks、NPC 交互主链与后端协议；这部分仍属于工作包 E 及后续后端工作包。
|
||||
4. 没有重做 AdventurePanel 内部更细粒度的卡片/子面板组件树，只做执行计划明确要求的三段 section 拆分。
|
||||
5. 没有删除旧 `GameShell*` 文件，只把它们降级为兼容桥，避免影响并行工作流。
|
||||
6. 没有调整任何用户可见的布局、按钮位置、tab 组织或弹窗/独立面板出现方式。
|
||||
|
||||
## 4. 验证结果
|
||||
|
||||
本轮已完成以下验证：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `npx vitest run src/components/AdventurePanel.test.tsx src/components/AdventurePanel.npcChat.test.tsx src/components/game-shell/useGameShellRuntimeViewModel.test.ts src/components/CustomWorldEntityEditorModal.test.tsx`
|
||||
3. 针对本工作包改动路径执行 `tsc` 定向筛查
|
||||
|
||||
验证结果：
|
||||
|
||||
1. 编码检查通过。
|
||||
2. 上述 4 组定向测试全部通过。
|
||||
3. 针对本轮改动路径的类型筛查无新增报错。
|
||||
4. 全量 `tsc` 仍然存在其他工作流文件的并行类型噪音，但未命中本轮工作包 D 改动文件。
|
||||
|
||||
## 5. 对工作包 D 完成度的复核
|
||||
|
||||
对照执行计划中的工作包 D 目标，本轮已完成：
|
||||
|
||||
1. 运行态 shell 的真实迁移。
|
||||
2. 主阶段路由器的真实迁移。
|
||||
3. 主面板路由器的真实迁移。
|
||||
4. 冒险主面板的真实迁移。
|
||||
5. 冒险主面板按 section 显式分段。
|
||||
6. 旧热点文件降级为兼容桥。
|
||||
|
||||
仍刻意保留、但不属于遗漏的部分：
|
||||
|
||||
1. 更细粒度的 AdventurePanel 子组件继续保留在单文件内部。
|
||||
2. 旧文件兼容导出尚未清理。
|
||||
3. 运行态 story hooks / gateway 仍在工作包 E 路径中继续演进。
|
||||
4. 本轮复核已补齐一个收口遗漏：`rpg-runtime-shell` / `rpg-runtime-panels` 真实实现所依赖的 story UI 类型，现已直接从 `hooks/rpg-runtime-story` 导入，不再反向依赖旧 `useStoryGeneration.ts` 兼容入口。
|
||||
|
||||
结论：
|
||||
|
||||
**工作包 D 在“不改 UI、不改后端协议、禁止过度开发”的前提下已经完整落地，当前没有遗漏的必做项。**
|
||||
@@ -0,0 +1,112 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 E 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 E：前端 runtime story 与 NPC 交互链拆分**，严格遵守以下边界：
|
||||
|
||||
1. 把前端 runtime story 主链真实迁到 `src/hooks/rpg-runtime-story/` 与 `src/services/rpg-runtime/`。
|
||||
2. 把 `useStoryGeneration.ts`、`useStoryRuntimeController.ts`、`useStoryFlowCoordinator.ts`、`useStoryGoalSessionCoordinator.ts`、`useStoryInteractionCoordinator.ts`、`npcEncounterActions.ts`、`runtimeStoryCoordinator.ts`、`runtimeStoryService.ts` 的正式实现从旧命名入口迁出。
|
||||
3. 保留旧 `story/*` 与 `runtimeStoryService.ts` 兼容导出，避免误伤其他并行工作包。
|
||||
4. 不改任何前端交互界面设计，不改后端动作语义，不新增玩法。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 RPG runtime story 主链真实迁移
|
||||
|
||||
已把以下真实实现迁入 RPG 域目录：
|
||||
|
||||
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/useRpgRuntimeStoryState.ts`
|
||||
5. `src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.ts`
|
||||
6. `src/hooks/rpg-runtime-story/useRpgRuntimeNpcInteraction.ts`
|
||||
7. `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts`
|
||||
|
||||
本轮完成后：
|
||||
|
||||
1. `useRpgRuntimeStory` 已成为前端 runtime story 顶层装配入口，不再只是 façade。
|
||||
2. `useRpgRuntimeStoryController` 负责 story 状态、AI 请求与提交动作。
|
||||
3. `useRpgRuntimeStoryFlow` 负责 option 展示、交互流和 story/session 状态流收口。
|
||||
4. `useRpgRuntimeStoryState` 负责 reset、hydrate、地图跳转与 quest UI 收口。
|
||||
5. `useRpgRuntimeInteractionFlow` 负责宝箱、背包、NPC、story choice 正式分发。
|
||||
6. `useRpgRuntimeNpcInteraction` 负责 NPC 对话、待接委托、战斗后续对话重开与服务端 NPC 动作派发。
|
||||
7. `rpgRuntimeStoryGateway` 负责 option catalog 拉取、继续游戏恢复与服务端 runtime choice 结算。
|
||||
|
||||
## 2.2 runtime story client 真实迁移
|
||||
|
||||
已把 `/api/runtime/story` 的真实 client 实现迁入：
|
||||
|
||||
1. `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
|
||||
|
||||
本轮完成后：
|
||||
|
||||
1. `rpgRuntimeStoryClient` 不再桥接旧 `runtimeStoryService.ts`，而是成为真实请求实现。
|
||||
2. `runtimeStoryService.ts` 降级为兼容导出层。
|
||||
3. `getRpgRuntimeStoryState`、`resolveRpgRuntimeStoryAction`、`resolveRpgRuntimeStoryMoment`、`isRpgRuntimeServerFunctionId`、`shouldUseRpgRuntimeServerOptions` 已成为新域主能力。
|
||||
|
||||
## 2.3 主调用链已接回 RPG 域
|
||||
|
||||
本轮已把以下主链与 helper 入口切到 RPG 域实现：
|
||||
|
||||
1. `src/hooks/rpg-session/useRpgRuntimeSession.ts` 改为直接使用 `useRpgRuntimeStory`
|
||||
2. `src/hooks/story/storyRequestCoordinator.ts` 改为消费 `loadRpgRuntimeOptionCatalog` 与 `shouldUseRpgRuntimeServerOptions`
|
||||
3. `src/hooks/story/choiceActions.ts` 改为消费 `isRpgRuntimeServerFunctionId`
|
||||
4. `src/hooks/story/storyChoiceRuntime.ts` 改为消费 `resolveRpgRuntimeChoice`
|
||||
5. `src/hooks/story/inventoryActions.ts` 改为消费 `resolveRpgRuntimeChoice`
|
||||
6. `src/hooks/story/npcInteraction.ts` 改为消费 `resolveRpgRuntimeChoice`
|
||||
7. `src/hooks/useTreasureFlow.ts` 改为消费 `resolveRpgRuntimeChoice`
|
||||
|
||||
这意味着工作包 E 范围内的前端 runtime story 正式结算主链，已经不再依赖旧 `runtimeStoryService.ts` 与旧 `runtimeStoryCoordinator.ts` 的真实实现。
|
||||
|
||||
## 2.4 兼容层处理
|
||||
|
||||
以下旧文件现已降级为兼容导出，不再承载正式实现：
|
||||
|
||||
1. `src/hooks/useStoryGeneration.ts`
|
||||
2. `src/hooks/story/useStoryRuntimeController.ts`
|
||||
3. `src/hooks/story/useStoryFlowCoordinator.ts`
|
||||
4. `src/hooks/story/useStoryGoalSessionCoordinator.ts`
|
||||
5. `src/hooks/story/useStoryInteractionCoordinator.ts`
|
||||
6. `src/hooks/story/npcEncounterActions.ts`
|
||||
7. `src/hooks/story/runtimeStoryCoordinator.ts`
|
||||
8. `src/services/runtimeStoryService.ts`
|
||||
|
||||
保留这些兼容层的原因：
|
||||
|
||||
1. 避免一次性改动所有 UI 与测试引用，降低并行工作冲突。
|
||||
2. 让工作包 D、C 仍能通过旧导入继续编译，再逐步切到新域命名。
|
||||
3. 明确“主实现已迁移、旧入口只兼容”的工程状态，避免后续继续扩大旧热点文件。
|
||||
4. 复核时已补齐一批主链收口点：`RpgRuntimeStageRouter`、`RpgRuntimeOverlayHost`、`RpgRuntimePanelRouter`、`RpgAdventurePanel` 及其直连组件的 story UI 类型导入，现已直接消费 `hooks/rpg-runtime-story` 新域出口，旧 `useStoryGeneration.ts` 仅保留兼容角色。
|
||||
|
||||
## 3. 本次没有做的事
|
||||
|
||||
以下内容仍保持原状，留给其他工作包：
|
||||
|
||||
1. 没有修改 `AdventurePanel.tsx`、`GameShellMainContent.tsx`、`GameShellStoryPanels.tsx` 的 UI 结构。
|
||||
2. 没有重做任何对话区、奖励区、输入区、overlay 的交互形式。
|
||||
3. 没有修改后端 runtime story route / service / compiler 语义。
|
||||
4. 没有清理所有旧 UI 组件对 `useStoryGeneration.ts` 的类型导入，本轮只保证旧入口已退化为兼容层。
|
||||
5. 没有删除旧兼容文件，避免误伤其他并行中的工作包。
|
||||
|
||||
## 4. 验证结果
|
||||
|
||||
本轮已执行：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `npx vitest run src/services/runtimeStoryService.test.ts src/hooks/story/runtimeStoryCoordinator.test.ts src/hooks/story/storyRequestCoordinator.test.ts src/hooks/story/choiceActions.test.ts src/hooks/story/storyChoiceRuntime.test.ts src/hooks/story/npcEncounterActions.test.ts`
|
||||
|
||||
验证结果：
|
||||
|
||||
1. 编码检查通过。
|
||||
2. 工作包 E 直接相关的 6 个测试文件、44 条测试全部通过。
|
||||
3. 运行时 option catalog、runtime choice、NPC 交互、待接委托、背包动作与本地/服务端分流逻辑均完成回归。
|
||||
4. 复核补跑 `src/services/rpg-entry/rpgProfileClient.test.ts`、`src/services/rpg-runtime/rpgSnapshotClient.test.ts`、`src/services/runtimeStoryService.test.ts`、`src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx` 共 33 条定向测试，全部通过。
|
||||
|
||||
## 5. 对后续工作包的直接收益
|
||||
|
||||
1. 工作包 D 后续如果继续拆 runtime panel 与 adventure panel，可以直接消费 `useRpgRuntimeStory` 与 `rpg-runtime-story` 域类型，不必再穿旧 `story` 目录。
|
||||
2. 工作包 C 与 session/persistence 链路已经可以直接对接 `rpgRuntimeStoryGateway` 的继续游戏恢复能力。
|
||||
3. 后续如果要清理旧 `useStoryGeneration.ts`、`runtimeStoryService.ts` 等旧命名入口，已经具备“新主链真实可用”的前提，不再是 façade 空壳状态。
|
||||
@@ -0,0 +1,121 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 F 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 F：后端 route 边界拆分**，严格遵守以下边界：
|
||||
|
||||
1. 只调整后端路由组织、挂载边界与兼容 façade。
|
||||
2. 不重写下游 `service` / `repository` 业务语义。
|
||||
3. 不修改任何前端交互界面设计，不额外推进工作包 G/H。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 `app.ts` 显式挂载 RPG 域路由
|
||||
|
||||
已把 `server-node/src/app.ts` 中的 RPG 相关入口改成显式按域挂载：
|
||||
|
||||
1. `rpgProfile`：资料看板、浏览历史、设置
|
||||
2. `rpgEntrySave`：快照读写、继续游戏归档列表与恢复
|
||||
3. `rpgWorldLibrary`：作品库、作品广场、works 列表
|
||||
4. `rpgRuntimeStory`：`/api/runtime/story` 状态读取与动作结算
|
||||
5. `rpgRuntimeAiAssist`：runtime story 之外的 AI 辅助接口
|
||||
|
||||
当前策略：
|
||||
|
||||
1. 使用 `scopeToPrefixes(...)` 只匹配各自域前缀，避免新路由误拦截无关 `/api` 请求。
|
||||
2. 所有线上接口路径保持不变，仍兼容现有前端与测试调用。
|
||||
3. `routeVersion` 对新域挂载统一标记为 `2026-04-21`，与本轮路由重构窗口对齐。
|
||||
|
||||
## 2.2 新 `rpg-*` 路由从骨架升级为真实实现
|
||||
|
||||
已把以下骨架路由补成真实入口：
|
||||
|
||||
1. `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
|
||||
2. `server-node/src/routes/rpg-entry/rpgEntrySaveRoutes.ts`
|
||||
3. `server-node/src/routes/rpg-entry/rpgWorldLibraryRoutes.ts`
|
||||
4. `server-node/src/routes/rpg-runtime/rpgRuntimeStoryRoutes.ts`
|
||||
5. `server-node/src/routes/rpg-runtime/rpgRuntimeAiAssistRoutes.ts`
|
||||
|
||||
本轮真实迁入的新边界包括：
|
||||
|
||||
1. `rpgProfileRoutes.ts`
|
||||
- `/api/runtime/profile/dashboard`
|
||||
- `/api/runtime/profile/wallet-ledger`
|
||||
- `/api/runtime/profile/play-stats`
|
||||
- `/api/runtime/profile/browse-history`
|
||||
- 兼容路径 `/api/profile/...`
|
||||
- `/api/runtime/settings`
|
||||
2. `rpgEntrySaveRoutes.ts`
|
||||
- `/api/runtime/save/snapshot`
|
||||
- `/api/runtime/profile/save-archives`
|
||||
- 兼容路径 `/api/profile/save-archives`
|
||||
3. `rpgWorldLibraryRoutes.ts`
|
||||
- `/api/runtime/custom-world-gallery`
|
||||
- `/api/runtime/custom-world/works`
|
||||
- `/api/runtime/custom-world-library`
|
||||
- publish / unpublish / soft delete 等库操作
|
||||
4. `rpgRuntimeStoryRoutes.ts`
|
||||
- `/api/runtime/story/actions/resolve`
|
||||
- `/api/runtime/story/state/:sessionId`
|
||||
- `/api/runtime/story/state/resolve`
|
||||
5. `rpgRuntimeAiAssistRoutes.ts`
|
||||
- runtime story 之外的 LLM proxy、cover/scene 资产、custom world profile 生成、角色/NPC chat、runtime item、quest 生成、`/api/ws/health`
|
||||
|
||||
## 2.3 旧大路由退化为兼容 façade
|
||||
|
||||
已把旧入口降级为兼容层：
|
||||
|
||||
1. `server-node/src/modules/story/storyActionRoutes.ts`
|
||||
- 不再自己承载 schema 与 handler
|
||||
- 直接桥接到 `createRpgRuntimeStoryRoutes(context)`
|
||||
2. `server-node/src/routes/runtimeRoutes.ts`
|
||||
- 不再继续承载 profile / save / world library / runtime ai assist / runtime story
|
||||
- 当前只保留旧 `customWorldAgent` 挂载与兼容 `ws/health`
|
||||
|
||||
这样处理后：
|
||||
|
||||
1. `runtimeRoutes.ts` 不再是 RPG 主链真实入口。
|
||||
2. `storyActionRoutes.ts` 不再是 runtime story 主链真实实现。
|
||||
3. 后续工作包 G/H 可以基于新 `rpg-*` 路由继续细化，而不用再穿透旧大文件。
|
||||
|
||||
## 3. 本次没有做的事
|
||||
|
||||
以下内容仍保持原状，不属于工作包 F 本轮范围：
|
||||
|
||||
1. 没有拆 `storyActionService.ts`、`runtimeSession.ts` 的内部职责。
|
||||
2. 没有继续改 `npcInteractionService.ts`、`questStoryActionService.ts` 的业务实现。
|
||||
3. 没有推进仓储、共享契约的进一步物理拆分。
|
||||
4. 没有改变任何前端页面结构、交互路径、面板形式或 UI 文案。
|
||||
|
||||
## 4. 验证结果
|
||||
|
||||
本次已执行：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `node --test --test-concurrency=1 --import tsx "src/routes/rpgRouteBoundaries.test.ts"`
|
||||
|
||||
验证结果：
|
||||
|
||||
1. 编码检查通过。
|
||||
2. 新增定向测试 `server-node/src/routes/rpgRouteBoundaries.test.ts` 4 项全部通过。
|
||||
3. 已覆盖以下工作包 F 验收重点：
|
||||
- `rpgProfile` 新路径与 legacy 路径兼容
|
||||
- `rpgEntrySave` 快照/归档路由可用
|
||||
- `rpgWorldLibrary` / `gallery` / `works` 新边界可用
|
||||
- `rpgRuntimeStory` 新边界与旧 façade 兼容可用
|
||||
|
||||
同时确认：
|
||||
|
||||
1. 全量 `npx tsc -p server-node/tsconfig.json --noEmit` 仍被仓库中既有跨模块类型问题阻塞。
|
||||
2. 这些错误覆盖 auth、inventory、custom world、scene image 等多个既有热点，与本次工作包 F 新增路由边界并非同一问题面。
|
||||
|
||||
## 5. 对执行计划的对齐结论
|
||||
|
||||
对照执行计划中的工作包 F：
|
||||
|
||||
1. `app.ts` 已能一眼看出 `rpgProfile`、`rpgEntry`、`rpgRuntimeStory`、`rpgRuntimeAiAssist` 的挂载边界。
|
||||
2. `runtimeRoutes.ts` 已退化为兼容入口，不再承接 RPG 主链的大杂糅职责。
|
||||
3. `storyActionRoutes.ts` 已退化为兼容 façade，真实 runtime story 路由落点转入 `server-node/src/routes/rpg-runtime/rpgRuntimeStoryRoutes.ts`。
|
||||
4. 本轮没有越过工作包 F 去重写下游 service 语义，满足“禁止过度开发”的约束。
|
||||
@@ -0,0 +1,96 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 G 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 G：后端 runtime session / action service 拆分**，严格遵守以下边界：
|
||||
|
||||
1. 把 `storyActionService.ts` 与 `runtimeSession.ts` 的真实实现迁入 `server-node/src/modules/rpg-runtime-story/` 新域目录。
|
||||
2. 把 runtime action 主链依赖的 session 原语、option 编译、snapshot sync、story state 读取按职责落到新文件。
|
||||
3. 旧 `server-node/src/modules/story/` 热点文件只保留兼容导出，不再承载真实实现。
|
||||
4. 不改前端入口与 UI，不改路由协议语义，不做仓储拆分。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 `runtimeSession.ts` 真实实现已迁入 `rpg-runtime-story`
|
||||
|
||||
本轮已把旧 `server-node/src/modules/story/runtimeSession.ts` 的真实实现迁入：
|
||||
|
||||
1. `server-node/src/modules/rpg-runtime-story/RpgRuntimeSessionDomain.ts`
|
||||
2. `server-node/src/modules/rpg-runtime-story/RpgRuntimeSessionLoader.ts`
|
||||
3. `server-node/src/modules/rpg-runtime-story/RpgRuntimeSessionPrimitives.ts`
|
||||
4. `server-node/src/modules/rpg-runtime-story/RpgRuntimeOptionCompiler.ts`
|
||||
5. `server-node/src/modules/rpg-runtime-story/RpgRuntimeSnapshotSync.ts`
|
||||
6. `server-node/src/modules/rpg-runtime-story/RpgRuntimeStoryPresentationCompiler.ts`
|
||||
|
||||
落地结果：
|
||||
|
||||
1. `loadRuntimeSession(...)`、`buildAvailableOptions(...)`、`buildRuntimeViewModel(...)`、`syncRawGameState(...)`、`replaceRuntimeSessionRawGameState(...)` 已有新域真实落点。
|
||||
2. `appendStoryHistory(...)`、`getEncounterNpcState(...)`、`setEncounterNpcState(...)`、`MAX_TASK5_COMPANIONS`、`TASK6_DEFERRED_FUNCTION_IDS` 等运行时原语已通过 `RpgRuntimeSessionPrimitives.ts` 对外输出。
|
||||
3. 旧 `server-node/src/modules/story/runtimeSession.ts` 已退化为兼容层，不再承载主实现。
|
||||
|
||||
## 2.2 `storyActionService.ts` 真实实现已迁入 `rpg-runtime-story`
|
||||
|
||||
本轮已把旧 `server-node/src/modules/story/storyActionService.ts` 的真实实现迁入：
|
||||
|
||||
1. `server-node/src/modules/rpg-runtime-story/RpgRuntimeStoryActionDomain.ts`
|
||||
2. `server-node/src/modules/rpg-runtime-story/RpgRuntimeStoryActionService.ts`
|
||||
3. `server-node/src/modules/rpg-runtime-story/RpgRuntimeStoryStateService.ts`
|
||||
|
||||
落地结果：
|
||||
|
||||
1. `resolveRuntimeStoryAction(...)` 已从新域动作服务入口导出。
|
||||
2. `getRuntimeStoryState(...)` 已从新域状态服务入口导出。
|
||||
3. 旧 `server-node/src/modules/story/storyActionService.ts` 已退化为兼容转发层。
|
||||
|
||||
## 2.3 runtime action 主链下游依赖已切到新域
|
||||
|
||||
本轮已把以下直接依赖 `runtimeSession.ts` 的后端模块切到 `rpg-runtime-story` 新域入口：
|
||||
|
||||
1. `server-node/src/modules/combat/combatResolutionService.ts`
|
||||
2. `server-node/src/modules/npc/npcInteractionService.ts`
|
||||
3. `server-node/src/modules/inventory/inventoryStoryActionService.ts`
|
||||
4. `server-node/src/modules/inventory/npcInventoryStoryActionService.ts`
|
||||
5. `server-node/src/modules/quest/questRuntimeSignalService.ts`
|
||||
6. `server-node/src/modules/quest/questStoryActionService.ts`
|
||||
7. `server-node/src/modules/runtime-item/treasureStoryActionService.ts`
|
||||
8. `server-node/src/modules/story/storyActionRoutes.ts`
|
||||
9. `server-node/src/modules/story/runtimeSession.test.ts`
|
||||
|
||||
当前状态：
|
||||
|
||||
1. runtime action 执行链已经直接消费 `rpg-runtime-story` 域入口，不再把旧 `modules/story/` 视为真实主实现。
|
||||
2. `storyActionRoutes.ts` 已直接从新域读取动作服务与状态服务。
|
||||
3. `runtimeSession.test.ts` 已直接验证新域编译链与 legacy currentStory 展示投影。
|
||||
|
||||
## 3. 本次没有做的事
|
||||
|
||||
以下内容仍保持原状，留给后续工作包或后续阶段：
|
||||
|
||||
1. 没有修改任何前端入口、前端运行态 UI、前端交互设计。
|
||||
2. 没有拆 `server-node/src/routes/runtimeRoutes.ts`、`server-node/src/app.ts` 的路由挂载组织，这属于工作包 F。
|
||||
3. 没有拆 `runtimeRepository.ts`、`runtimeSnapshotHydration.ts` 与 shared contract，这属于工作包 H。
|
||||
4. 没有把 `RpgRuntimeStoryActionDomain.ts` 再继续切成更细颗粒度的真实实现文件；本轮只做到工作包 G 要求的“目录化拆开 + 旧热点降级”。
|
||||
5. 没有改动任何动作语义、返回协议或 LLM 编排行为。
|
||||
|
||||
## 4. 验证与检查
|
||||
|
||||
本轮已执行：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `npx tsx --test server-node/src/modules/story/runtimeSession.test.ts server-node/src/modules/story/storyActionRoutes.test.ts`
|
||||
3. `npm --prefix server-node run build`
|
||||
|
||||
验证结果：
|
||||
|
||||
1. 编码检查通过。
|
||||
2. 与 runtime session / runtime story action 直接相关的后端定向测试 `20` 项全部通过。
|
||||
3. `server-node` 构建通过。
|
||||
4. 旧 `server-node/src/modules/story/runtimeSession.ts` 与 `server-node/src/modules/story/storyActionService.ts` 已只剩兼容导出，没有残留真实主实现。
|
||||
|
||||
## 5. 对后续工作的直接收益
|
||||
|
||||
1. 工作包 F 后续继续做 route 边界拆分时，可以直接把 runtime story 路由稳定挂到 `rpg-runtime-story` 新域入口。
|
||||
2. 工作包 H 后续拆仓储、shared contract 和测试基建时，可以围绕 `rpg-runtime-story` 新目录继续收口，而不必再穿透旧热点文件。
|
||||
3. 后续如果继续细拆 runtime story 主链，可以在新域内部继续物理拆分，而不会重新把真实实现塞回 `modules/story/`。
|
||||
@@ -0,0 +1,90 @@
|
||||
# RPG 进入游戏与运行时链路重构工作包 H 落地记录
|
||||
|
||||
更新时间：`2026-04-21`
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
本次只落实 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中的 **工作包 H：仓储、契约与测试基建**，严格遵守以下边界：
|
||||
|
||||
1. 只补仓储、shared contract、fixture 与测试基建。
|
||||
2. 不修改前端 UI，不改页面交互设计。
|
||||
3. 不重写 route 层与 runtime story 主流程逻辑。
|
||||
|
||||
## 2. 本次已落地内容
|
||||
|
||||
## 2.1 仓储按 RPG 域补齐独立入口
|
||||
|
||||
本次补齐并收口了工作包 H 目标中的按域仓储入口：
|
||||
|
||||
1. `server-node/src/repositories/rpg-runtime/RpgRuntimeSnapshotRepository.ts`
|
||||
2. `server-node/src/repositories/rpg-entry/RpgSaveArchiveRepository.ts`
|
||||
3. `server-node/src/repositories/rpg-entry/RpgWorldLibraryRepository.ts`
|
||||
4. `server-node/src/repositories/rpg-profile/RpgProfileDashboardRepository.ts`
|
||||
5. `server-node/src/repositories/rpg-profile/RpgBrowseHistoryRepository.ts`
|
||||
|
||||
本轮策略仍保持最小侵入：
|
||||
|
||||
1. 新仓储继续委托 `runtimeRepository.ts` 提供真实读写。
|
||||
2. `RpgProfileDashboardRepository` 只保留资料看板、设置、钱包、游玩统计职责。
|
||||
3. 浏览历史读写从资料仓储中抽离到 `RpgBrowseHistoryRepository`，与执行方案的目标拆分保持一致。
|
||||
|
||||
## 2.2 shared runtime contract 按领域拆分并保留兼容 façade
|
||||
|
||||
已把原 `packages/shared/src/contracts/story.ts` 中的 RPG runtime shared contract 拆分为：
|
||||
|
||||
1. `packages/shared/src/contracts/rpgRuntimeStoryAction.ts`
|
||||
2. `packages/shared/src/contracts/rpgRuntimeStoryState.ts`
|
||||
3. `packages/shared/src/contracts/rpgRuntimeChat.ts`
|
||||
4. `packages/shared/src/contracts/rpgRuntimeQuestAssist.ts`
|
||||
|
||||
兼容策略：
|
||||
|
||||
1. `story.ts` 退化为 façade，只做分文件 re-export。
|
||||
2. 现有前后端调用方仍可继续从 `contracts/story` 取用类型与常量，不要求本轮同步迁移所有 import。
|
||||
3. runtime story 主链契约与 chat / quest assist / runtime item 辅助契约已经具备独立演进落点。
|
||||
|
||||
## 2.3 测试基建补齐
|
||||
|
||||
本次补充并核对了工作包 H 范围内的测试：
|
||||
|
||||
1. `server-node/src/modules/runtime/runtimeSnapshotHydration.test.ts`
|
||||
用于覆盖 snapshot 归一化、恢复继续游戏时的默认值修复与旧存档兼容。
|
||||
2. `server-node/src/repositories/rpg-profile/RpgProfileRepositories.test.ts`
|
||||
用于确认资料看板仓储与浏览历史仓储的职责边界已经分离。
|
||||
3. `server-node/src/repositories/rpg-entry/RpgEntryRepositories.test.ts`
|
||||
用于确认 continue game 归档仓储与作品库仓储已经独立命名并保持职责边界。
|
||||
4. `server-node/src/repositories/rpg-runtime/RpgRuntimeSnapshotRepository.test.ts`
|
||||
用于确认 snapshot 读写职责已经有独立仓储入口。
|
||||
5. `packages/shared/src/contracts/rpgRuntimeContracts.test.ts`
|
||||
用于确认 `story.ts` façade 在拆分后仍保持旧入口兼容。
|
||||
|
||||
## 3. 本次没有做的事
|
||||
|
||||
以下内容仍保持原状，留给其他工作包或第三批统一收口：
|
||||
|
||||
1. 没有把前后端所有 `contracts/story` import 全量改写到新分文件，避免与并行工作包产生无谓冲突。
|
||||
2. 没有改 `server-node/src/routes/runtimeRoutes.ts`、`server-node/src/modules/story/storyActionService.ts`、`server-node/src/modules/story/runtimeSession.ts` 的真实逻辑。
|
||||
3. 没有改前端 continue game、角色选择、冒险运行态的界面与交互。
|
||||
|
||||
## 4. 验证结果
|
||||
|
||||
本轮执行并通过：
|
||||
|
||||
1. `npm run check:encoding`
|
||||
2. `npx vitest run packages/shared/src/contracts/rpgRuntimeContracts.test.ts`
|
||||
3. `node --test --test-concurrency=1 --import tsx src/modules/runtime/runtimeSnapshotHydration.test.ts src/repositories/rpg-profile/RpgProfileRepositories.test.ts src/repositories/rpg-entry/RpgEntryRepositories.test.ts src/repositories/rpg-runtime/RpgRuntimeSnapshotRepository.test.ts`
|
||||
|
||||
说明：
|
||||
|
||||
1. 工作树当前存在其他并行修改与冲突文件，因此没有把与工作包 H 无关的全量问题一并处理。
|
||||
2. 本轮验证只覆盖工作包 H 自身改动与其直接依赖，避免过度开发。
|
||||
|
||||
## 5. 与执行方案的对照结论
|
||||
|
||||
对照 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 中工作包 H 的目标，本轮已完成：
|
||||
|
||||
1. snapshot / profile / library / browse history 仓储独立命名入口补齐。
|
||||
2. `story.ts` shared contract 已拆为 runtime story action、runtime story state、runtime chat、runtime quest assist 四个独立文件。
|
||||
3. runtime story / snapshot / continue game 相关测试已补齐到可直接回归的最小闭环。
|
||||
|
||||
当前未额外扩张到主流程迁移、route 改写、UI 调整，符合“禁止过度开发”的执行要求。
|
||||
Reference in New Issue
Block a user