# 当前创作流程链路前后端脚本重构执行方案

更新时间：`2026-04-21`

## 0. 文档目标

本文件只服务一件事：

**把当前“创作入口 -> Agent 会话 -> 世界底稿 -> 结果页编辑 -> 自动保存 -> 作品库 -> 进入世界”这条链路上的前后端脚本，整理成一份可以直接指导后续编码拆分的执行方案。**

本轮不直接改业务逻辑，只明确：

1. 当前链路上的真实脚本地图
2. 当前可读性差、可扩展性差的结构性问题
3. 目标分层与真相源边界
4. 文件级拆分建议
5. 分阶段落地计划与验收标准

---

## 1. 范围与依据

### 1.1 本文覆盖的创作链路

```text
平台创作入口
-> Agent session 创建 / 恢复
-> Agent 对话与 action 执行
-> foundation draft 生成
-> 角色图 / 地点图 / 分幕图 / 动作资产生成与同步
-> 结果页编辑
-> 自动保存到作品库
-> works 聚合展示 / 恢复创作
-> 进入游戏世界
```

### 1.2 本文主要依据

1. `docs/audits/AGENT_TO_DRAFT_TO_WORLD_PIPELINE_AUDIT_2026-04-20.md`
2. `docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md`
3. `docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE2_2026-04-20.md`
4. `docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md`
5. `docs/audits/engineering/FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md`
6. `docs/technical/CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md`
7. `docs/technical/AGENT_DRAFT_RESULT_AUTOSAVE_DB_CHECK_2026-04-21.md`

---

## 2. 当前链路脚本地图

## 2.1 前端主链脚本

| 文件 | 当前职责 | 当前问题 |
| --- | --- | --- |
| `src/components/game-shell/PreGameSelectionFlow.tsx` | 平台 tab、详情页、创作入口、Agent session 创建与恢复、operation 轮询、结果页自动保存、session 同步、进入世界前同步、works/library/gallery/history/save 拉取 | 单文件承载过多流程编排，页面壳层、状态机、网络请求、自动保存和世界进入逻辑混在一起，是当前前端最大热点 |
| `src/components/custom-world-home/CustomWorldCreationHub.tsx` | 创作中心 works 展示、继续创作、草稿与已发布作品入口 | 读模型已经存在，但与平台壳层仍有状态耦合，入口职责还没有完全收口 |
| `src/components/CustomWorldResultView.tsx` | 结果页预览、结果页内生成角色/地点、结果页内触发编辑、资产调试面板 | 结果页同时是预览层、编辑层、生成层，仍保留 legacy profile 直改能力 |
| `src/components/CustomWorldEntityEditorModal.tsx` | 世界、封面、营地、角色、地点等多种对象编辑，以及部分资产与运行时预览能力 | 单文件过大，编辑表单、资产工作流、运行时预览混合，后续很难局部扩展 |
| `src/components/CustomWorldRoleAssetStudioModal.tsx` | 角色主图候选、动作生成、动作发布、缓存读写 | 视觉生成、动作生成、缓存、发布四类职责耦合在一个模态层里 |
| `src/services/customWorldAgentDraftResult.ts` | `Agent session draftProfile -> legacy CustomWorldProfile` 的桥接编译与资产合并 | 前端承担了结构化编译责任，是“前端只做表现”边界下最应继续收缩的兼容层 |
| `src/services/aiService.ts` | Agent session、消息流、operation、旧 custom world 相关请求、若干结果页生成动作 | custom world 相关 API 与 story/chat/legacy AI 接口混放，不利于链路收口 |
| `src/services/storageService.ts` | works、library、gallery、browse history、save archive、profile dashboard | custom world 作品链 API 与通用 runtime 存储 API 混放，边界不清晰 |

## 2.2 后端主链脚本

| 文件 | 当前职责 | 当前问题 |
| --- | --- | --- |
| `packages/shared/src/contracts/customWorldAgent.ts` | session、message、draft、asset、works、action、operation 契约 | 契约体量过大，action 定义与后端真实执行能力存在漂移 |
| `server-node/src/routes/customWorldAgent.ts` | Agent session 与 action 路由入口 | 应继续保持薄路由，但当前下游编排层过重，路由可读性受限 |
| `server-node/src/routes/runtimeRoutes.ts` | works、library、gallery、runtime 相关通用路由 | custom world 作品链路仍混在 runtime 大路由里，不利于独立演进 |
| `server-node/src/services/customWorldAgentOrchestrator.ts` | session 生命周期、消息处理、action 分发、result sync、派生状态拼装、suggested actions、质量状态拼装 | 当前后端最大热点之一，承担了过多业务分支和字段同步细节 |
| `server-node/src/services/customWorldAgentSessionStore.ts` | session 创建、读写、兼容旧结构补齐、snapshot 输出 | store、兼容转换、session factory 三类职责还没有拆开 |
| `server-node/src/services/customWorldAgentFoundationDraftService.ts` | eight-anchor / intent -> foundation draft；内部依赖 runtime profile 编译再转回 draft | 存在“先编 legacy runtime profile，再转回 foundation draft”的双重编译 |
| `server-node/src/modules/custom-world/runtimeProfile.ts` | custom world runtime profile 规范化、构建、编译、属性 schema、场景章节处理 | 文件过大，normalize/build/schema/scene/role 等职责全部堆在一起 |
| `server-node/src/repositories/runtimeRepository.ts` | save/settings/custom world profiles/custom world sessions/browse history 等仓储 | 仓储按技术分组，不按领域分组；custom world 相关方法和通用 runtime 方法耦合 |
| `server-node/src/services/customWorldWorkSummaryService.ts` | 聚合 Agent 草稿与已发布 profile，生成 works 读模型 | 汇总逻辑、展示语义、metadata 回退混在一起，适合作为独立 read model 层继续收口 |

## 2.3 当前链路上的次级执行模块

以下脚本不是主入口，但属于链路中的重要执行点，后续重构不能绕开：

1. `server-node/src/services/customWorldAgentEntityGenerationService.ts`
2. `server-node/src/services/customWorldAgentAutoAssetService.ts`
3. `server-node/src/services/customWorldAgentAssetBridgeService.ts`
4. `server-node/src/services/customWorldAgentDraftCompiler.ts`
5. `server-node/src/services/customWorldAgentRoleAssetStateService.ts`

这些模块后续要继续明确边界：

1. 生成型 service 只负责生成结果
2. bridge / sync 型 service 只负责把已确认结果写回 session
3. snapshot / read model 型 service 只负责组织前端展示数据

---

## 3. 当前结构性问题

## 3.1 前端壳层承担了过多编排责任

`PreGameSelectionFlow.tsx` 当前既是平台页面壳层，又是创作流程控制器，还同时负责：

1. Agent session 创建与恢复
2. operation 轮询
3. works、gallery、history、save、dashboard 拉取
4. 结果页自动保存
5. 结果页改动同步回 session
6. 进入世界前同步

这会导致：

1. 页面组件一改就容易碰到主链数据流
2. 自动保存与页面切换耦合过紧
3. 后续任何新增 action 都会继续堆进壳层文件

## 3.2 前端仍在承担结果 profile 编译责任

`buildCustomWorldProfileFromAgentDraft()` 仍是当前 session draft -> result profile 的关键桥接点。

这意味着：

1. Agent session 不是最终唯一真相源
2. 前端在裁决字段取舍、默认值、资产合并
3. 自动保存和进入世界依赖的是前端重编译结果，而不是服务端正式输出

这与“前端只做表现，逻辑和数据收回 Express 后端”的项目约束不一致。

## 3.3 结果页仍是 legacy 编辑器兼容工作台

`CustomWorldResultView.tsx`、`CustomWorldEntityEditorModal.tsx`、`CustomWorldRoleAssetStudioModal.tsx` 当前仍然存在：

1. 直接改 legacy `CustomWorldProfile`
2. 直接调用 legacy 生成接口补角色、地点
3. 资产工坊直接处理缓存、候选、发布

结果页就不只是“预览 / 发布前收口层”，而是独立并行编辑器。

## 3.4 后端编排层和编译层都过重

`customWorldAgentOrchestrator.ts` 与 `runtimeProfile.ts` 是当前两个最明显的大文件热点：

1. 一个同时承担 message orchestration、action dispatch、result sync、snapshot 拼装
2. 一个同时承担 runtime normalize、schema build、scene chapter compile、role build

结果是：

1. 新增 action 成本高
2. 新增字段时容易遗漏多个分支
3. 单测很难精准覆盖局部职责

## 3.5 works、library、publish、enter world 仍没有完全收成单一路径

当前仍然是：

1. Agent session 草稿链
2. 已保存 profile 链
3. 结果页 legacy profile 直改链
4. works 聚合读模型链

多条 pipeline 并存会继续放大桥接层复杂度。

---

## 4. 目标分层架构

## 4.1 目标原则

后续重构必须统一遵守 5 条原则：

1. **Agent session 是创作态唯一真相源。**
2. **服务端编译结果预览是结果页唯一数据来源。**
3. **published profile 是进入世界与作品库持久化的正式真相。**
4. **前端只保留展示状态、交互状态、表单草稿态，不再承担结构化编译。**
5. **action 能力由后端注册表统一声明，前端不再假设 contract 中定义的 action 一定真实可用。**

## 4.2 目标链路

```text
前端平台壳层
-> custom world 专属 client
-> Agent route / works route / library route
-> session application service
-> action registry
-> foundation / entity / asset / publish domain services
-> session store / custom world repository
-> 服务端 result preview compiler
-> 前端结果页展示与编辑
-> 服务端 autosave / publish / enter-world gate
```

## 4.3 三类真相源

后续必须严格区分三类数据：

| 数据 | 真相位置 | 用途 |
| --- | --- | --- |
| 创作态 session | Agent session store | 对话、草稿、锁定、suggested actions、asset 覆盖率、阶段状态 |
| 结果页预览态 result preview | 服务端 preview compiler 输出 | 结果页展示、结果页局部编辑回填、自动保存前比对 |
| 已发布世界 profile | custom world profile repository | 作品库、发布态、进入世界、对外展示 |

前端不再把 `draftProfile -> runtime profile` 编译结果视为正式真相，只能把它视为临时兼容输出，且这条兼容层要持续收缩。

---

## 4.4 RPG 创作流程脚本命名规范

这套创作流程只服务 **RPG 类型游戏**，后续命名不能继续沿用过于泛化的 `customWorld`、`runtime`、`flow` 混搭口径，而应把“RPG 创作域”显式写进命名里。

### 命名目标

1. 让人一眼看出这是 **RPG 世界创作链**，不是通用世界编辑器。
2. 让文件名能直接表达层级：页面壳层、工作流、应用服务、编译器、仓储、读模型。
3. 避免继续出现“同一文件名里既有业务域又有历史兼容语义”的情况。

### 推荐命名根

后续新建或重命名文件时，优先使用下面 3 类命名根：

1. `rpgCreation`：用于前端创作流程壳层、workflow、client、view model
2. `rpgWorld`：用于后端世界草稿、世界预览、世界发布、世界仓储
3. `rpgAgent`：用于 Agent session、message turn、action executor、snapshot

### 命名规则

1. 前端组件文件使用 `RpgCreation` 前缀。
2. 前端 hooks / workflow 文件使用 `useRpgCreation` 前缀。
3. 前端 client / adapter / mapper 文件使用 `rpgCreation` 前缀。
4. 后端应用服务文件使用 `RpgAgent` 或 `RpgWorld` 前缀。
5. 后端仓储文件使用 `RpgWorld...Repository` 或 `RpgAgent...Repository`。
6. 共享契约文件使用 `rpgCreation...` 或 `rpgAgent...` 小驼峰命名。
7. 禁止再新增过于泛化的 `customWorld*Service.ts`、`customWorld*Flow.tsx` 作为新主命名。

### 文件命名示例

#### 前端示例

1. `src/components/game-shell/rpg-creation-flow/RpgCreationShell.tsx`
2. `src/components/game-shell/rpg-creation-flow/useRpgCreationPlatformBootstrap.ts`
3. `src/components/game-shell/rpg-creation-flow/useRpgCreationSessionController.ts`
4. `src/components/rpg-creation-result/RpgCreationResultView.tsx`
5. `src/components/rpg-creation-editor/RpgCreationRoleEditorSection.tsx`
6. `src/services/rpg-creation/rpgCreationAgentClient.ts`
7. `src/services/rpg-creation/rpgCreationPreviewAdapter.ts`

#### 后端示例

1. `server-node/src/routes/rpgCreationAgentRoutes.ts`
2. `server-node/src/routes/rpgWorldLibraryRoutes.ts`
3. `server-node/src/services/RpgAgentOrchestrator.ts`
4. `server-node/src/services/RpgAgentActionRegistry.ts`
5. `server-node/src/services/RpgWorldPreviewCompiler.ts`
6. `server-node/src/repositories/RpgWorldProfileRepository.ts`
7. `server-node/src/repositories/RpgAgentSessionRepository.ts`

#### 共享契约示例

1. `packages/shared/src/contracts/rpgAgentSession.ts`
2. `packages/shared/src/contracts/rpgAgentActions.ts`
3. `packages/shared/src/contracts/rpgCreationPreview.ts`
4. `packages/shared/src/contracts/rpgCreationWorkSummary.ts`

### 兼容期命名策略

因为当前主链已有大量 `customWorld*` 文件，重构期间采用“两段式迁移”：

1. 第一阶段先新增按规范命名的新目录和 façade。
2. 第二阶段再把旧 `customWorld*` 文件逐步迁到 `rpgCreation* / rpgWorld* / rpgAgent*` 命名。

### 命名禁忌

后续重构中禁止继续出现以下命名问题：

1. 一个文件名同时表达多个层级，例如 `FlowServiceController`。
2. 用 `runtime` 指代创作态脚本。
3. 用 `customWorld` 指代实际上只服务 RPG 创作链的新模块。
4. 用 `Helper`、`Utils`、`Manager` 作为主业务模块名。

---

## 5. 前端重构拆分方案

## 5.1 `PreGameSelectionFlow.tsx` 拆分方案

### 现状问题

当前文件同时承担“平台壳层 + 数据加载器 + 创作流程控制器 + 自动保存协调器 + 世界进入协调器”五类职责。

### 目标拆分

保留 `PreGameSelectionFlow.tsx` 作为页面壳层，只负责：

1. stage 切换
2. 组件装配
3. 视觉级 loading / error 展示

从该文件中拆出以下模块：

1. `src/components/game-shell/custom-world-flow/useCustomWorldPlatformBootstrap.ts`
2. `src/components/game-shell/custom-world-flow/useCustomWorldWorkEntries.ts`
3. `src/components/game-shell/custom-world-flow/useCustomWorldAgentSessionController.ts`
4. `src/components/game-shell/custom-world-flow/useCustomWorldAgentOperationPolling.ts`
5. `src/components/game-shell/custom-world-flow/useCustomWorldResultAutosave.ts`
6. `src/components/game-shell/custom-world-flow/useCustomWorldEnterWorld.ts`
7. `src/components/game-shell/custom-world-flow/useCustomWorldDetailNavigation.ts`

### 编码要求

1. 壳层文件内不再直接拼接 route path。
2. 壳层文件内不再直接包含自动保存防抖实现。
3. 壳层文件内不再直接包含 session -> result profile 编译细节。
4. 壳层文件内不再直接处理 works/library/history/save 的多路请求编排。

## 5.2 custom world 专属 client 拆分方案

### 现状问题

`aiService.ts` 和 `storageService.ts` 中 custom world 相关接口已经比较多，继续堆在通用 service 里会加重跨域耦合。

### 目标拆分

新增 custom world 专属 client 目录：

1. `src/services/custom-world/customWorldAgentClient.ts`
2. `src/services/custom-world/customWorldWorkClient.ts`
3. `src/services/custom-world/customWorldLibraryClient.ts`
4. `src/services/custom-world/customWorldAssetClient.ts`

### 保留边界

1. `aiService.ts` 只保留 story/chat/通用 AI 能力。
2. `storageService.ts` 只保留 save/settings/profile dashboard 等通用 runtime 存储。
3. custom world 相关请求全部从通用 service 中迁出后，旧导出保留一个阶段的兼容别名，再统一删除。

## 5.3 `CustomWorldResultView.tsx` 拆分方案

### 现状问题

该文件同时承担结果概览、实体目录、结果页动作、局部生成动作和调试面板。

### 目标拆分

保留 `CustomWorldResultView.tsx` 作为结果页组合壳层，并拆出：

1. `src/components/custom-world-result/CustomWorldResultHeader.tsx`
2. `src/components/custom-world-result/CustomWorldResultActionBar.tsx`
3. `src/components/custom-world-result/CustomWorldResultEntitySection.tsx`
4. `src/components/custom-world-result/CustomWorldAssetCoveragePanel.tsx`
5. `src/components/custom-world-result/CustomWorldAssetDebugPanel.tsx`
6. `src/components/custom-world-result/useCustomWorldResultActions.ts`

### 边界要求

1. 结果页只调用 custom world 专属 client。
2. 结果页不再直接依赖 legacy 生成函数作为长期主链能力。
3. 调试面板与正式结果页逻辑隔离，避免调试代码继续污染主流程组件。

## 5.4 `CustomWorldEntityEditorModal.tsx` 拆分方案

### 现状问题

该文件把 world / cover / camp / role / landmark / chapter 编辑全部放在一个文件里，且还混入运行时预览与资产工作流。

### 目标拆分

保留 modal 壳层，拆出：

1. `src/components/custom-world-editor/CustomWorldWorldEditorSection.tsx`
2. `src/components/custom-world-editor/CustomWorldCoverEditorSection.tsx`
3. `src/components/custom-world-editor/CustomWorldCampEditorSection.tsx`
4. `src/components/custom-world-editor/CustomWorldRoleEditorSection.tsx`
5. `src/components/custom-world-editor/CustomWorldLandmarkEditorSection.tsx`
6. `src/components/custom-world-editor/CustomWorldSceneChapterEditorSection.tsx`
7. `src/components/custom-world-editor/customWorldResultFormMapper.ts`

### 边界要求

1. 编辑 section 只负责表单表现。
2. 提交 patch、差异比较、字段清洗都收口到独立 mapper / mutation 层。
3. 运行时预览和战斗预览不继续堆在结果编辑主链文件里。

## 5.5 `CustomWorldRoleAssetStudioModal.tsx` 拆分方案

### 现状问题

角色图候选、动作模板、动作生成、缓存恢复、结果发布都在一个文件里，后续加“场景资产工坊”时会继续复制相同问题。

### 目标拆分

建议拆为：

1. `src/components/custom-world-asset-studio/useRoleVisualCandidateWorkflow.ts`
2. `src/components/custom-world-asset-studio/useRoleAnimationWorkflow.ts`
3. `src/components/custom-world-asset-studio/roleAssetStudioModel.ts`
4. `src/components/custom-world-asset-studio/roleAssetStudioPublishClient.ts`
5. `src/components/custom-world-asset-studio/CustomWorldRoleAssetStudioModal.tsx`

### 边界要求

1. 缓存模型独立于 UI。
2. 发布动作只负责把“已确认资产结果”提交给后端。
3. 动作生成参数模板不要散落在 UI 文件里。

## 5.6 `customWorldAgentDraftResult.ts` 收缩方案

### 当前定位

这是当前最重要的前端兼容桥接层。

### 过渡策略

阶段一不直接删除，但要改名并收缩定位：

1. 建议迁为 `src/services/custom-world/customWorldResultPreviewAdapter.ts`
2. 只保留“服务端 result preview -> 前端 view model”的轻量适配
3. 禁止继续在其中新增业务裁决和字段拼装逻辑

### 长期目标

服务端提供正式 `result preview` 输出后，前端不再执行 `draftProfile -> CustomWorldProfile` 编译，本文件可以在后续阶段物理删除。

---

## 6. 后端重构拆分方案

## 6.1 route 层收口

### 当前问题

`customWorldAgent.ts` 与 `runtimeRoutes.ts` 的下游能力边界还不够清晰，custom world 作品链仍混在 runtime 大路由里。

### 目标拆分

1. `server-node/src/routes/customWorldAgent.ts` 只保留 Agent session / action / operation 路由。
2. 从 `server-node/src/routes/runtimeRoutes.ts` 中拆出：
   - `server-node/src/routes/customWorldWorks.ts`
   - `server-node/src/routes/customWorldLibrary.ts`
   - `server-node/src/routes/customWorldGallery.ts`

### 编码要求

1. 路由层只做鉴权、请求校验、应用服务调用、响应映射。
2. 不在路由层拼装 session 派生状态。
3. 不在路由层做 draft / profile 字段兼容转换。

## 6.2 `customWorldAgentOrchestrator.ts` 拆分方案

### 当前问题

该文件当前同时承担：

1. message turn 处理
2. action 分发
3. session 读写
4. result profile sync
5. suggested actions 生成
6. 派生状态与 operation 文案拼装

### 目标拆分

保留 `customWorldAgentOrchestrator.ts` 作为应用服务 façade，只负责主链事务编排，并拆出：

1. `server-node/src/services/customWorldAgentMessageTurnService.ts`
2. `server-node/src/services/customWorldAgentActionRegistry.ts`
3. `server-node/src/services/customWorldAgentActionExecutors/`
4. `server-node/src/services/customWorldAgentResultSyncService.ts`
5. `server-node/src/services/customWorldAgentSuggestedActionService.ts`
6. `server-node/src/services/customWorldAgentSnapshotBuilder.ts`
7. `server-node/src/services/customWorldAgentQualityGateService.ts`

### 关键要求

1. `action -> executor` 必须通过注册表映射，不再在 orchestrator 里堆分支。
2. `publish_world`、`generate_scene_assets`、`expand_long_tail` 等 contract 中存在的 action，要么接入真实 executor，要么明确标记为未开放并返回禁用原因。
3. `sync_result_profile` 的字段回写细节只允许出现在独立 sync service 中。

## 6.3 `customWorldAgentSessionStore.ts` 拆分方案

### 当前问题

store 当前混合了：

1. session factory
2. session persistence
3. 旧结构兼容补齐
4. snapshot 输出

### 目标拆分

1. `server-node/src/services/customWorldAgentSessionFactory.ts`
2. `server-node/src/services/customWorldAgentSessionCompatibility.ts`
3. `server-node/src/services/customWorldAgentSessionStore.ts`
4. `server-node/src/repositories/customWorldAgentSessionRepository.ts`

### 关键要求

1. session store 只保留高层读写接口。
2. 兼容 legacy session 的逻辑单独隔离，避免污染新字段演进。
3. persistence adapter 不再依赖 runtime 仓储大文件直接暴露全部能力。

## 6.4 `customWorldAgentFoundationDraftService.ts` 拆分方案

### 当前问题

当前 foundation draft 生成还带着“runtime profile 双重编译”的历史包袱。

### 目标拆分

1. `server-node/src/services/customWorldAgentFoundationInputBuilder.ts`
2. `server-node/src/services/customWorldAgentFoundationLlmService.ts`
3. `server-node/src/services/customWorldAgentFoundationNormalizer.ts`
4. `server-node/src/services/customWorldAgentFoundationDraftService.ts`
5. `server-node/src/services/customWorldAgentResultPreviewCompiler.ts`

### 关键要求

1. foundation draft 生成与 runtime preview 编译彻底拆开。
2. 不再通过“先编 legacy runtime profile，再转回 foundation draft”维持主链。
3. `legacyResultProfile` 只作为阶段性兼容字段存在，禁止继续扩大依赖面。

## 6.5 `runtimeProfile.ts` 拆分方案

### 当前问题

这是当前 custom world runtime 编译中心，但文件过大，后续继续在原文件上叠加只会放大维护成本。

### 目标拆分

新增目录：

1. `server-node/src/modules/custom-world/runtime-profile/index.ts`
2. `server-node/src/modules/custom-world/runtime-profile/normalizeShared.ts`
3. `server-node/src/modules/custom-world/runtime-profile/normalizeRole.ts`
4. `server-node/src/modules/custom-world/runtime-profile/normalizeLandmark.ts`
5. `server-node/src/modules/custom-world/runtime-profile/normalizeSceneChapter.ts`
6. `server-node/src/modules/custom-world/runtime-profile/normalizeCamp.ts`
7. `server-node/src/modules/custom-world/runtime-profile/buildCompiledProfile.ts`
8. `server-node/src/modules/custom-world/runtime-profile/buildAttributeSchema.ts`
9. `server-node/src/modules/custom-world/runtime-profile/creatorIntentBridge.ts`

### 过渡策略

1. 原 `runtimeProfile.ts` 先保留为 façade 导出层。
2. 新调用逐步改走目录化模块。
3. 旧导出在阶段性兼容完成后再统一清理。

## 6.6 仓储层与 works 聚合层拆分方案

### 当前问题

`runtimeRepository.ts` 与 `customWorldWorkSummaryService.ts` 目前都承担了过多跨域职责。

### 目标拆分

建议把 `runtimeRepository.ts` 拆成：

1. `server-node/src/repositories/runtimeSaveRepository.ts`
2. `server-node/src/repositories/runtimeSettingsRepository.ts`
3. `server-node/src/repositories/customWorldProfileRepository.ts`
4. `server-node/src/repositories/customWorldAgentSessionRepository.ts`
5. `server-node/src/repositories/profileBrowseHistoryRepository.ts`

建议把 `customWorldWorkSummaryService.ts` 拆成：

1. `server-node/src/services/customWorldWorkSummaryAssembler.ts`
2. `server-node/src/services/customWorldWorkCoverResolver.ts`
3. `server-node/src/services/customWorldWorkSummaryService.ts`

### 关键要求

1. works service 只做读模型聚合，不直接承担 session 兼容修补。
2. repository 按领域而不是按技术杂糅方式拆开。
3. works 聚合输出必须稳定支持“继续创作”和“进入世界”两个入口判定。

## 6.7 结果预览与发布链统一方案

### 当前问题

当前“结果页可进入世界”和“正式发布”还不是一条统一主链。

### 目标方案

后续增加服务端 result preview / publish gate 之后，统一为：

```text
结果页编辑
-> 服务端写回 session patch
-> 服务端编译 result preview
-> 自动保存或发布
-> 发布校验
-> 生成 published profile
-> 进入世界
```

### 关键要求

1. 进入世界前不再绕开 publish gate。
2. `qualityFindings` 与 blocker 要成为真实 gate，而不是仅展示字段。
3. 自动保存保存的是“服务端确认后的 preview / profile”，而不是前端私有重编译产物。

---

## 7. 共享契约重构方案

## 7.1 `customWorldAgent.ts` 拆分建议

建议拆为以下契约文件，再由 index 统一 re-export：

1. `packages/shared/src/contracts/customWorldAgentAnchors.ts`
2. `packages/shared/src/contracts/customWorldAgentDraft.ts`
3. `packages/shared/src/contracts/customWorldAgentActions.ts`
4. `packages/shared/src/contracts/customWorldAgentSession.ts`
5. `packages/shared/src/contracts/customWorldWorkSummary.ts`

## 7.2 契约演进要求

后续 contract 调整需要新增两类约束：

1. `supportedActions` 或等价能力矩阵，由后端真实注册表生成，前端只消费它，不再根据类型字面量自行假设按钮可用。
2. `resultPreview` 或独立 preview contract，明确区分“session 草稿”和“结果页预览”。

## 7.3 兼容字段处理

以下字段或能力要被明确标为“兼容过渡态”：

1. `legacyResultProfile`
2. 前端 `buildCustomWorldProfileFromAgentDraft()`
3. 结果页直接调用 legacy 生成函数补实体

所有新功能禁止再建立对这些兼容字段的新增依赖。

---

## 8. 测试与文档同步方案

## 8.1 测试分层

后续重构至少补齐 4 层测试：

1. **unit tests**：针对 result sync、action registry、foundation normalizer、runtime preview compiler
2. **contract tests**：针对 session snapshot、works summary、preview contract
3. **integration tests**：覆盖“创建 session -> 发消息 -> draft foundation -> 编辑结果 -> 自动保存 -> 继续创作”
4. **regression tests**：覆盖角色图、地点图、分幕图、动作资产字段不会在 session 重编译中回退

## 8.2 fixture 要求

建议补充固定 fixture：

1. 最小 eight-anchor session fixture
2. foundation draft fixture
3. result preview fixture
4. published profile fixture

这样 runtime compiler、autosave、works 聚合三条链可以共享相同样本。

## 8.3 文档同步要求

每完成一个阶段，至少同步更新：

1. 本执行方案
2. `docs/technical/README.md`
3. 与本阶段对应的阶段性技术文档
4. 若边界发生变化，还要同步相关 PRD / 审计文档口径

---

## 9. 可并行重构工作包

本次执行计划需要拆成多个可同时推进的工作部分，避免所有人都集中修改同一个热点文件。

并行原则如下：

1. 每个工作包只负责一组清晰模块。
2. 每个工作包必须有明确写入边界。
3. 同一阶段允许并行，但禁止多人同时大改同一核心文件。
4. 先做 façade 和新目录，再做调用迁移，最后做旧层清理。

## 9.1 工作包 A：命名规范与目录骨架

### 目标

先建立 RPG 创作域的新命名与目录骨架，给后续并行迁移提供统一落点。

### 负责范围

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/`
5. 后端 `server-node/src/routes/` 下 RPG 创作相关新路由文件
6. 后端 `server-node/src/services/` 下 RPG 创作相关 façade 文件
7. 共享契约新文件骨架

### 写入边界

1. 可以新建目录和 façade 文件。
2. 可以改文档和导出索引。
3. 不负责大规模迁移老逻辑。

### 前置依赖

无，可最先开始。

### 当前进展（`2026-04-21`）

工作包 A 第一轮已完成以下骨架落地：

1. 已新增前端 `rpg-creation-flow`、`rpg-creation-result`、`rpg-creation-editor`、`rpg-creation` service 目录。
2. 已新增 `RpgCreationShell`、`RpgCreationResultView`、`RpgCreationEntityEditorModal` 等 façade 入口，当前仍桥接旧实现。
3. 已新增 `rpgCreationAgentClient`、`rpgCreationWorkClient`、`rpgCreationLibraryClient`、`rpgCreationAssetClient`、`rpgCreationPreviewAdapter`。
4. 已新增后端 `rpgCreationAgentRoutes`、`rpgWorldWorksRoutes`、`rpgWorldLibraryRoutes`、`rpgWorldGalleryRoutes` 命名骨架。
5. 已新增 `RpgAgentOrchestrator`、`RpgAgentSessionStore`、`RpgWorldPreviewCompiler`、`RpgWorldWorkSummaryService` façade。
6. 已新增 `rpgAgent*` 与 `rpgCreation*` 共享契约骨架。

本轮刻意未做：

1. 没有迁移 `runtimeRoutes.ts` 的真实 works/library/gallery 实现。
2. 没有拆分 `PreGameSelectionFlow.tsx`、`CustomWorldResultView.tsx`、`CustomWorldEntityEditorModal.tsx` 内部逻辑。
3. 没有改动现有主链行为，只建立后续并行迁移的统一落点。

## 9.2 工作包 B：前端平台壳层与流程编排拆分

### 目标

把 `PreGameSelectionFlow.tsx` 从大编排文件拆成壳层 + hooks。

### 负责范围

1. `PreGameSelectionFlow.tsx`
2. 平台 bootstrap、session controller、operation polling、detail navigation 相关 hooks
3. 平台侧 works / dashboard / save / history 拉取协调

### 写入边界

1. 主要修改前端壳层与流程 hooks。
2. 不直接改后端 route / service 语义。
3. 不承担结果页编辑器拆分。

### 前置依赖

最好在工作包 A 的目录骨架准备好后开始。

## 9.3 工作包 C：前端结果页与编辑器拆分

### 目标

把结果页、实体编辑器、角色资产工坊拆成组合壳层与独立 section / workflow。

### 负责范围

1. `CustomWorldResultView.tsx`
2. `CustomWorldEntityEditorModal.tsx`
3. `CustomWorldRoleAssetStudioModal.tsx`
4. 结果页 action hooks、表单 mapper、资产 workflow

### 写入边界

1. 主要改结果页与编辑器相关前端组件。
2. 允许补前端 view model 与 mapper。
3. 不直接改平台壳层主状态编排。

### 前置依赖

依赖工作包 A 的命名规范与目录落点，和工作包 B 并行。

## 9.4 工作包 D：前端 custom world client 收口

### 目标

把 custom world 专属接口从 `aiService.ts`、`storageService.ts` 中迁出。

### 负责范围

1. `aiService.ts`
2. `storageService.ts`
3. 新增 `rpgCreation*Client` 文件
4. 调整前端调用导入路径

### 写入边界

1. 只负责 API client 与请求封装。
2. 不负责结果页 UI 拆分。
3. 不负责后端业务实现重构。

### 前置依赖

依赖工作包 A 的命名和目录约束；可与 B、C 并行。

## 9.5 工作包 E：后端 Agent 编排拆分

### 目标

拆解 `customWorldAgentOrchestrator.ts`，引入 registry、snapshot builder、result sync service。

### 负责范围

1. `customWorldAgentOrchestrator.ts`
2. action registry
3. action executors
4. result sync service
5. snapshot builder
6. quality gate service

### 写入边界

1. 主改后端应用服务层。
2. 不负责 runtime profile 编译模块的目录化拆分。
3. 不负责前端壳层迁移。

### 前置依赖

建议在工作包 A 后开始；可与 B、C、D 并行。

## 9.6 工作包 F：后端 session/store/repository 拆分

### 目标

拆出 session factory、compatibility、repository adapter，并把 custom world 仓储从 runtime 大仓储中分离。

### 负责范围

1. `customWorldAgentSessionStore.ts`
2. `runtimeRepository.ts`
3. `customWorldWorkSummaryService.ts`
4. 新 session repository / profile repository / work summary assembler

### 写入边界

1. 主改后端持久化与读模型层。
2. 不负责 action executor 细节。
3. 不负责前端调用改造。

### 前置依赖

与工作包 E 有接口协作关系，但可以并行推进，最终通过 façade 汇合。

## 9.7 工作包 G：后端 preview compiler 与 runtime profile 目录化

### 目标

把 `runtimeProfile.ts` 拆成目录化模块，并引入服务端 result preview compiler。

### 负责范围

1. `runtimeProfile.ts`
2. `runtime-profile/` 新目录
3. result preview compiler
4. foundation draft 与 preview 编译的边界收口

### 写入边界

1. 只负责编译层、normalize 层和 preview 输出。
2. 不直接重构路由层。
3. 不直接迁前端组件。

### 前置依赖

与工作包 E、F 并行，但在主链接入前需要先和 E 对齐 preview contract。

## 9.8 工作包 H：共享契约与测试基建

### 目标

拆分共享契约，补齐 fixture、contract tests、integration tests。

### 负责范围

1. `packages/shared/src/contracts/`
2. preview / action / session / works summary 契约
3. fixture
4. unit / contract / integration / regression tests

### 写入边界

1. 契约变更必须同步测试。
2. 不直接承担业务 UI 拆分。
3. 不直接承担数据库仓储重构。

### 前置依赖

可从工作包 A 开始先建骨架，随后跟随 B 到 G 持续补齐。

## 9.9 并行推进关系

推荐并行顺序如下：

```text
第一批并行：
工作包 A + 工作包 H

第二批并行：
工作包 B + 工作包 C + 工作包 D + 工作包 E + 工作包 F + 工作包 G

第三批收口：
把 B~H 的 façade 接回主链
-> 联调自动保存 / works / publish / enter world
-> 清理旧兼容层
```

## 9.10 并行协作约束

为避免多人互相覆盖，本轮建议遵守：

1. 工作包 B 独占 `PreGameSelectionFlow.tsx`。
2. 工作包 C 独占 `CustomWorldResultView.tsx`、`CustomWorldEntityEditorModal.tsx`、`CustomWorldRoleAssetStudioModal.tsx`。
3. 工作包 D 独占 `aiService.ts`、`storageService.ts`。
4. 工作包 E 独占 `customWorldAgentOrchestrator.ts`。
5. 工作包 F 独占 `customWorldAgentSessionStore.ts`、`runtimeRepository.ts`、`customWorldWorkSummaryService.ts`。
6. 工作包 G 独占 `runtimeProfile.ts` 及其新目录。
7. 工作包 H 独占 shared contracts 主文件和测试 fixture 总目录。

---

## 10. 分阶段落地计划

## Phase 0：冻结口径与清点兼容层

### 目标

把当前链路拆分前的边界先冻结，避免后续一边拆一边新增同类耦合。

### 工作项

1. 完成本文档并作为后续施工总口径
2. 标记兼容层：`customWorldAgentDraftResult.ts`、`legacyResultProfile`、结果页 legacy 生成动作
3. 列出当前 action contract 与真实 executor 的对照表

### 验收标准

1. 团队对“session / preview / published profile”三类真相源达成一致
2. 新需求不再默认往 `PreGameSelectionFlow.tsx` 和 `customWorldAgentOrchestrator.ts` 继续堆逻辑

## Phase 1：目录骨架、命名规范与前端拆分并行启动

### 目标

先建立 RPG 创作域的新目录和命名规范，并把前端热点文件拆成可维护结构，但不改当前主流程行为。

### 工作项

1. 完成工作包 A
2. 完成工作包 B
3. 完成工作包 C
4. 完成工作包 D

### 验收标准

1. `PreGameSelectionFlow.tsx` 只剩 stage 与组件装配逻辑
2. 通用 service 中不再继续新增 custom world workflow 接口
3. 自动保存、session 恢复、进入世界逻辑都有独立 hook / coordinator
4. 新增文件遵循 RPG 创作域命名规范

## Phase 2：后端应用服务、仓储、编译层并行拆分

### 目标

把后端主链从“大 orchestrator + 大 store + 大 compiler”拆成 registry + services + repositories + compiler modules。

### 工作项

1. 完成工作包 E
2. 完成工作包 F
3. 完成工作包 G
4. 工作包 H 同步补 contract 与测试

### 验收标准

1. `customWorldAgentOrchestrator.ts` 不再包含具体字段回写实现
2. action 的启用 / 禁用状态可由后端统一描述
3. session 兼容逻辑可以脱离 store 单独测试
4. `runtimeProfile.ts` 已退化为 façade 或兼容导出层

## Phase 3：结果预览编译后移到后端

### 目标

消除前端“本地编译结果 profile”的主链地位。

### 工作项

1. 新增服务端 result preview compiler
2. 结果页改为消费服务端 preview
3. `customWorldAgentDraftResult.ts` 改为薄适配层

### 验收标准

1. 前端不再把 `buildCustomWorldProfileFromAgentDraft()` 作为正式编译步骤
2. 自动保存与 session 同步都基于服务端确认后的 preview
3. 结果页字段回退问题不再依赖前端兼容修补

## Phase 4：发布链、自动保存链、进入世界链统一

### 目标

把“可玩”与“已发布”的门槛统一到后端。

### 工作项

1. 打通 publish gate
2. 把 `qualityFindings` / blocker 接成真实阻断条件
3. enter world 统一走服务端发布态或明确允许的预览态

### 验收标准

1. 前端不能绕开 publish / gate 直接进世界
2. works、library、enter world 三处状态语义一致
3. 发布失败可以给出明确 blocker 与恢复入口

## Phase 5：兼容层清理

### 目标

在主链稳定后，物理清理历史桥接层和重复 pipeline。

### 工作项

1. 删除前端 draft result 编译桥
2. 删除结果页 legacy 直改链的残余入口
3. 清理 contract 中已废弃 action / 字段

### 验收标准

1. 创作主链只剩 session -> preview -> published profile 三层
2. 不再存在“前端本地编译 profile 才能自动保存”的依赖
3. 文档、契约、测试口径一致

---

## 11. 本次执行约束

后续按本文落地时，需要持续遵守以下约束：

1. 不做大爆炸式重写，按阶段保留 façade 与兼容层。
2. 不新开平行系统，优先在现有创作中心、结果页、Agent 工作区上做结构拆分。
3. 前端新增文件优先按“壳层 / hook / client / section”拆，不把逻辑再塞回组件文件。
4. 后端新增文件优先按“route / application service / domain service / repository / compiler”拆，不再继续扩大大文件。
5. 每个阶段完成后同步文档与测试，不允许代码结构已经迁移但文档还停留在旧链路口径。

---

## 12. 结论

当前创作流程的核心问题，不是单点 bug，而是：

**前端壳层、前端兼容编译层、后端编排层、后端 runtime 编译层同时过重，导致整条创作链处在“多条 pipeline 并存、桥接层过多、职责分层混乱”的过渡态。**

后续重构的正确方向不是继续在热点文件上补判断，而是按本文把主链收成：

**session 真相源 -> 服务端 preview 编译 -> published profile 发布态**

只有这样，当前链路的可读性、可扩展性和后续功能落地稳定性，才会一起提升。