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

更新时间：`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. Agent 聊天工作区进入时必须如实展示后端 session 的 `progressPercent`。新会话后端初始值为 `0` 时，前端数字与进度条填充都必须保持 `0%`；只允许对大于 0 的值使用视觉最小宽度，避免用户误判聊天流程已经推进。

## 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*` 共享契约骨架，并补齐此前遗漏的 `rpgAgentDraft.ts` 与 shared 根导出。

本轮刻意未做：

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 的目录骨架准备好后开始。

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

工作包 B 已完成以下落地：

1. 已把 `PreGameSelectionFlow.tsx` 降级为兼容入口，旧路径继续导出 `PreGameSelectionFlow`、`PreGameSelectionFlowProps`、`SelectionStage`。
2. 已把 RPG 创作平台壳层的真实实现迁入 `src/components/game-shell/rpg-creation-flow/RpgCreationShellImpl.tsx`，并把该文件收口成“hooks 组合 + stage 视图装配 + 视觉级 loading/error”的壳层。
3. `RpgCreationShell.tsx` 已直接桥接 `RpgCreationShellImpl.tsx`，新目录开始承接真实入口。
4. 已新增 `rpgCreationFlowTypes.ts`、`rpgCreationFlowShared.ts`，把壳层类型与共享 helper 从旧入口文件中收出独立落点。
5. 已接入 `useRpgCreationPlatformBootstrap.ts`、`useRpgCreationSessionController.ts`、`useRpgCreationAgentOperationPolling.ts`、`useRpgCreationDetailNavigation.ts`、`useRpgCreationResultAutosave.ts`、`useRpgCreationEnterWorld.ts`。
6. 平台侧 works / library / gallery / history / save / dashboard 拉取、session 恢复、message streaming、action 执行、operation 轮询、detail navigation、结果页自动保存、enter-world 同步已不再直接堆在壳层组件中。
7. 已完成 `PreGameSelectionFlow.agent.interaction.test.tsx` 的 14 个交互场景回归，以及壳层相关定向 eslint、编码检查。

本轮刻意未做：

1. 还没有物理删除 `PreGameSelectionFlow.tsx` 与其他旧兼容 façade，当前仍保留桥接层以避免影响并行工作包。
2. 还没有让所有调用方统一显式改走 `RpgCreationShell` 新入口，当前允许旧路径兼容收口到新实现。
3. 还没有把结果页 preview 数据源从前端兼容 adapter 切到服务端正式 preview contract，这部分仍属于后续工作包 G / H 与 Phase 3 范围。
4. 还没有清理所有 legacy 兼容导出，本轮优先完成平台壳层编排拆分与主链稳定验证。

## 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 并行。

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

工作包 C 已完成以下拆分落地：

1. 已把 `CustomWorldResultView.tsx`、`CustomWorldEntityEditorModal.tsx`、`CustomWorldRoleAssetStudioModal.tsx` 的真实实现迁入 `src/components/rpg-creation-result/`、`src/components/rpg-creation-editor/`、`src/components/rpg-creation-asset-studio/`。
2. 已把旧文件降级为兼容入口，现有调用仍可继续从旧路径导入，不影响当前主链行为。
3. 结果页已拆出 `RpgCreationResultHeader`、`RpgCreationResultActionBar`、`RpgCreationAssetDebugPanel`、`useRpgCreationResultActions`，结果页主组件开始退化为组合壳层。
4. 编辑器已补 `rpgCreationResultFormMapper.ts`，并把 `RpgCreationEntityEditorModalImpl.tsx` 收口成目标分发壳层；`world / cover / camp / playable / story / landmark` 已有稳定 section 入口。
5. 编辑器当前保留 `RpgCreationEntityEditorShared.tsx` 作为阶段性 shared 实现承载体，避免在同一轮里高风险物理拆散 180KB 级表单细节；后续可在不改壳层接口的前提下继续向各 section 文件迁移。
6. 角色资产工坊已补 `roleAssetStudioModel.ts`、`roleAssetStudioPublishClient.ts`、`useRoleVisualCandidateWorkflow.ts`、`useRoleAnimationWorkflow.ts`，并进一步拆出 `RpgCreationRoleVisualSection.tsx`、`RpgCreationRoleAnimationSection.tsx`、`RpgCreationRoleAssetStudioFooter.tsx`，当前主模态已退化为组合壳层。
7. 旧 `CustomWorldResultView.tsx`、`CustomWorldEntityEditorModal.tsx`、`CustomWorldRoleAssetStudioModal.tsx` 兼容入口已统一桥接到 RPG 创作域 façade，而不是继续直连内部 `Impl` 文件。

本轮刻意未做：

1. 还没有把 `RpgCreationEntityEditorShared.tsx` 内部的全部表单实现物理拆成独立文件，当前先以“壳层 + section 入口 + shared 实现”完成工作包 C 收口。
2. 还没有改平台壳层 `PreGameSelectionFlow.tsx` 的任何主状态编排，仍严格遵守工作包 C 的写入边界。
3. 还没有把结果页从 legacy preview 兼容数据源切到服务端正式 preview contract，这部分属于后续工作包 D / G / H 的协作范围。

## 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 并行。

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

工作包 D 第一轮已完成以下落地：

1. 已新增 `src/services/rpg-creation/rpgCreationRuntimeClient.ts` 与 `src/services/rpg-creation/rpgCreationRequestHelpers.ts`，把 RPG 创作域的 runtime 请求重试策略、POST JSON 与 SSE 请求辅助能力收口到新目录。
2. `rpgCreationAgentClient.ts`、`rpgCreationWorkClient.ts`、`rpgCreationLibraryClient.ts`、`rpgCreationAssetClient.ts`、`rpgCreationGenerationClient.ts` 已从 façade 透传升级为真实请求实现，不再继续把主链请求代码堆在 `aiService.ts`、`storageService.ts` 中。
3. `generateCustomWorldProfile()` 已正式迁入 `rpgCreationGenerationClient.ts`，世界生成入口也已纳入 RPG 创作域 client 边界。
4. `aiService.ts` 中已迁出的 Agent / works / 世界生成 / 结果页实体生成接口已退化为兼容导出；`storageService.ts` 中 works / library / gallery / publish 链路也已退化为兼容导出。
5. `PreGameSelectionFlow.tsx` 已开始直接从 `src/services/rpg-creation/` 消费 Agent / works / library / gallery / publish 请求，不再从旧 service 入口拿主链接口。
6. `RpgCreationEntityEditorShared.tsx` 已把场景图生成请求切到 `rpgCreationAssetClient`，结果页与编辑器相关测试也已改为优先 mock 新的 RPG 创作域 client。
7. 已完成 `rpgCreationGenerationClient.test.ts`、`storageService.test.ts`、`CustomWorldEntityEditorModal.test.tsx`、`CustomWorldResultView.test.tsx`、`PreGameSelectionFlow.agent.interaction.test.tsx` 的定向回归，以及编码检查。

本轮刻意未做：

1. 还没有物理删除 `aiService.ts`、`storageService.ts` 中的旧命名兼容导出，本轮优先保证调用迁移可平稳过渡。
2. 还没有改平台壳层的内部流程编排与 hook 结构，这部分仍属于工作包 B。
3. 还没有把结果页从 legacy preview 兼容数据源切到服务端正式 preview contract，这部分仍属于后续工作包 G / H 的协作范围。

## 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 并行。

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

工作包 E 当前已完成 3 轮落地，真实状态如下：

1. `customWorldAgentOrchestrator.ts` 已退化为后端应用服务 façade，只保留 session/message/action 主入口、operation 创建和下游服务委托；消息轮转、action 分发与派生状态重建已从热点文件中拆出。
2. `CustomWorldAgentActionRegistry` 已正式接管 action 可用性校验、payload normalize、operation type 映射与 `supportedActions` 主链接线；前端不再需要按 action 字面量猜测按钮是否可点。
3. `customWorldAgentActionExecutors/` 已补齐并接管以下真实执行链：
   - `draft_foundation`
   - `update_draft_card`
   - `sync_result_profile`
   - `generate_characters`
   - `generate_landmarks`
   - `generate_role_assets`
   - `sync_role_assets`
   - `generate_scene_assets`
   - `sync_scene_assets`
   - `expand_long_tail`
   - `publish_world`
   - `revert_checkpoint`
4. `CustomWorldAgentMessageTurnService`、`CustomWorldAgentSnapshotBuilder`、`CustomWorldAgentResultSyncService`、`CustomWorldAgentQualityGateService`、`CustomWorldAgentSuggestedActionService` 已形成稳定协作边界：
   - message turn 负责会话轮转
   - snapshot builder 负责派生状态重建
   - result sync service 负责结果页回写
   - quality gate service 负责 `qualityFindings`
   - suggested action service 负责建议动作
5. 发布链已经统一切到 `CustomWorldAgentPublishingService`：
   - orchestrator、executor map、publish executor、server 注入口径已经一致
   - 发布 readiness 与正式写库走同一服务
   - 作者展示名优先走 `resolveAuthorDisplayName`，同时保留 `userRepository` 兼容兜底
   - 发布产物 `profileId` 固定优先沿用 legacy 结果页 ID，否则回退为 `agent-draft-${sessionId}`
6. `sync_scene_assets` 已形成完整闭环：
   - 营地/地点正式场景图会写回 draft profile
   - 对应 `sceneChapters[].acts` 的 `backgroundImageSrc / backgroundAssetId` 会同步刷新
   - `rebuildRoleAssetCoverage()` 已补 camp/landmark 正式场景资产 fallback 汇总，确保 snapshot 重建、works 读模型与 checkpoint 回放都能保住场景资产覆盖状态
7. checkpoint 已收口为“可恢复真快照”：
   - `buildCheckpointSnapshot()` 已接入关键 executor
   - `revert_checkpoint` 现在依赖真实 checkpoint snapshot 与 `restoreCheckpoint()` 主链完成回滚，不再是只开放入口的空动作
8. `CustomWorldAgentActionRegistry` 已重新收口阶段策略：
   - `sync_result_profile`、`generate_scene_assets`、`sync_scene_assets` 等精修动作仅允许 `object_refining / visual_refining`
   - `expand_long_tail`、`publish_world`、`revert_checkpoint` 单独允许 `long_tail_review / ready_to_publish`
9. 已完成以下验证：
   - `npm --prefix server-node run build`
   - `npm --prefix server-node run test -- customWorldAgentPhase3.test.ts customWorldAgentActionRegistry.test.ts customWorldAgentPhase5.test.ts`
   当前 `server-node` 定向回归共 `208` 项通过，已覆盖工作包 E 第三轮的发布链、场景资产、长尾扩展与 checkpoint 回滚主链。

本轮刻意未做：

1. 还没有进入 Phase 4 的“进入世界统一走发布态 gate”收口，当前只完成 `publish_world` 本身的后端闭环。
2. 还没有改 `customWorldAgentSessionStore.ts` 与 repository 边界，这部分仍属于工作包 F。
3. 还没有让前端结果页正式消费服务端 `resultPreview` 主链字段，这部分仍需要与工作包 G / H 协作。
4. 旧 `customWorldAgentPublishGateService.ts`、`customWorldAgentPublishService.ts` 仍作为历史兼容文件保留，尚未进入物理删除阶段。

## 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 汇合。

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

工作包 F 已完成以下拆分落地：

1. 已新增 `server-node/src/services/rpg-agent-session-store/`，把 session record、compatibility、factory、repository adapter 从 `customWorldAgentSessionStore.ts` 中物理拆出。
2. `customWorldAgentSessionStore.ts` 已退化为兼容 façade，保留原类名、原方法签名，并正式改为依赖 `RpgAgentSessionRepositoryPort`。
3. 已新增 `server-node/src/repositories/RpgAgentSessionRepository.ts`、`server-node/src/repositories/RpgWorldProfileRepository.ts`、`server-node/src/repositories/rpgWorldRepositoryShared.ts`。
4. `runtimeRepository.ts` 中的 custom world session/profile/gallery 读写已改成委托新仓储，runtime 大仓储开始向“通用 runtime façade”收口。
5. 已新增 `server-node/src/services/RpgWorldWorkCoverResolver.ts`、`server-node/src/services/RpgWorldWorkSummaryAssembler.ts`、`server-node/src/services/RpgWorldWorkSummaryService.ts`，把 works 读模型的封面解析、条目组装与服务入口从 `customWorldWorkSummaryService.ts` 中拆出。
6. `context.ts`、`server.ts`、`runtimeRoutes.ts`、`syncCustomWorldSavedProfileAssets.ts` 已切到直接注入和使用 `RpgAgentSessionRepository`、`RpgWorldProfileRepository`、`RpgWorldWorkSummaryService`。
7. `customWorldAgentPhase2~5` 与 `customWorldWorkSummaryService.integration.test.ts` 已切到新的 session/profile 内存仓储端口，定向回归 21 项全部通过。

本轮刻意未做：

1. `RuntimeRepositoryPort` 仍保留兼容 façade 与 custom world 相关旧方法，现阶段先稳住 story/runtime 其他调用方。
2. `RuntimeRepository` 中的 runtime 快照同步编排还没有继续下沉，当前先完成 custom world 持久化与 works 读模型边界拆分。
3. `customWorldAgentSessionStore.ts`、`customWorldWorkSummaryService.ts` 等旧命名 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。

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

工作包 G 已完成以下落地：

1. 已新增 `server-node/src/modules/custom-world/runtime-profile/` 目录入口，并把原 `runtimeProfile.ts` 退化为兼容 façade。
2. 已把 runtime profile 进一步物理拆分到：
   - `normalizeShared.ts`
   - `normalizeRole.ts`
   - `normalizeLandmark.ts`
   - `normalizeSceneChapter.ts`
   - `normalizeCamp.ts`
   - `buildCompiledProfile.ts`
   - `buildAttributeSchema.ts`
   - `creatorIntentBridge.ts`
3. `runtimeProfileCompiler.ts` 已退化为兼容 façade，不再承载主实现。
4. `RpgWorldPreviewCompiler.ts` 已从简单别名升级为服务端 preview compiler 入口，新增 preview envelope 输出能力。
5. `packages/shared/src/contracts/rpgCreationPreview.ts` 已补 `RpgCreationPreviewSource`，并在 Phase 5 后把 session 结果页正式 source 收口为 `session_preview`。
6. `customWorldAgentFoundationDraftService.ts` 的 LLM foundation draft 主生成链已改成“直接组装 draft 主字段 + 单独保留 `legacyResultProfile` 兼容快照”，不再通过 preview compiler 反解草稿主字段。
7. 已新增 `server-node/src/services/RpgWorldPreviewCompiler.test.ts`、`server-node/src/services/customWorldAgentFoundationDraftService.test.ts`，并完成编码检查与工作包 G 定向回归验证。

本轮刻意未做：

1. 还没有把 preview contract 从当前 runtime-profile 兼容载体升级成独立 view model。
2. 还没有让 orchestrator、route、前端结果页正式消费 preview envelope。
3. `legacyResultProfile` 仍作为结果页兼容快照保留，相关消费链还没有完全脱离 legacy profile 富字段。
4. 兼容 façade `runtimeProfile.ts` / `runtimeProfileCompiler.ts` 仍保留，等待后续阶段统一清理。

## 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 持续补齐。

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

工作包 H 已完成以下落地：

1. 已把 `rpgAgentAnchors.ts`、`rpgAgentDraft.ts`、`rpgAgentActions.ts`、`rpgAgentSession.ts`、`rpgCreationPreview.ts`、`rpgCreationWorkSummary.ts` 从类型别名骨架推进为真实共享契约定义。
2. 已把旧 `packages/shared/src/contracts/customWorldAgent.ts` 降级为兼容聚合出口，并补齐：
   - `customWorldAgentAnchors.ts`
   - `customWorldAgentDraft.ts`
   - `customWorldAgentActions.ts`
   - `customWorldAgentSession.ts`
   - `customWorldResultPreview.ts`
   - `customWorldWorkSummary.ts`
   让旧命名导入可以按分域文件渐进迁移，而不是继续依赖单一大文件。
3. 已新增 `packages/shared/src/contracts/rpgCreationFixtures.ts`，补齐八锚点、foundation draft、session、preview、published profile、library、works 等共享样本，并把 fixture 接入 `packages/shared/src/index.ts` 统一导出。
4. 已把 shared contract tests 接入 `vitest.config.ts`，并补齐 `packages/shared/src/contracts/rpgContracts.test.ts`，覆盖 session snapshot、preview envelope、published profile、works summary，以及旧命名兼容分文件的类型消费。
5. 已新增 `server-node/src/services/RpgWorldPreviewCompiler.fixture.test.ts`、`server-node/src/services/RpgWorldWorkSummaryAssembler.fixture.test.ts`、`server-node/src/services/customWorldWorkSummaryService.integration.test.ts`，把 preview compiler、works assembler、works service 对共享 fixture 的消费纳入 unit / integration / regression 回归。
6. 已补 `server-node/src/services/RpgWorldWorkSummaryService.ts` 兼容实现，确保 works 兼容入口与当前 `rpgWorldProfiles + customWorldAgentSessions` 读模型服务口径一致。
7. `customWorldAgentOrchestrator.ts` 已新增统一 session snapshot 装配入口，当前普通拉取与 SSE message stream 返回的 session 字段口径开始收口。
8. 服务端 `RpgWorldPreviewCompiler` 输出已正式接入 session snapshot 的 `resultPreview` 字段，并复用当前 `qualityFindings` 生成 preview `qualityFindings / blockers` 兼容输出。
9. `rpg-agent-session-store/rpgAgentSessionCompatibility.test.ts` 已覆盖“compatibility 脱离 store 直接单测”的主链能力，Phase 2 的 session 兼容层开始具备独立回归保障。
10. `src/app.test.ts` 已补“custom world agent stream message returns enriched session payload over sse”回归，session snapshot / resultPreview / supportedActions 的 HTTP 与 SSE 响应口径开始统一验证。

本轮刻意未做：

1. 还没有批量迁移仓库里所有旧 `customWorldAgent.ts` 导入到 `rpgAgent* / rpgCreation*`。
2. 还没有批量把前端结果页与自动保存链统一切到服务端 `resultPreview`。
3. 还没有把服务端 preview contract 从 legacy profile 兼容载体升级成独立 view model。

## 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. 结果页字段回退问题不再依赖前端兼容修补

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

Phase 3 本轮已完成以下主链接线：

1. 前端 `rpgCreationPreviewAdapter.ts` 已正式改成“优先读取 `session.resultPreview`，本地 `draftProfile -> legacy result profile` 只做 fallback”的薄适配层。
2. `useRpgCreationSessionController.ts`、`useRpgCreationResultAutosave.ts`、`useRpgEntryLibraryDetail.ts` 所在的 Agent 结果页打开链、自动保存链、继续创作恢复链，已统一通过 `buildPreviewFromSession()` 消费服务端 preview。
3. `RpgEntryFlowShellImpl.tsx` 当前传给结果页自动保存与创作入口恢复的 `buildDraftResultProfile` 已切到服务端 preview 主链，不再把前端本地编译结果当成正式真相源。
4. 前端 fallback 编译实现已迁入 `src/services/rpg-creation/rpgCreationPreviewDraftFallback.ts`，旧 `src/services/customWorldAgentDraftResult.ts` 已退化为兼容 re-export，不再继续承载主实现。
5. 已新增 `src/services/rpg-creation/rpgCreationPreviewAdapter.test.ts`，补齐“服务端 `resultPreview` 优先于本地 draft fallback”的回归断言。
6. `PreGameSelectionFlow.agent.interaction.test.tsx` 已补充“没有 `legacyResultProfile` 也能凭服务端 preview 打开 Agent 结果页”的交互回归，验证结果页主链已切到后端 preview。

本轮刻意未做：

1. `src/services/customWorldAgentDraftResult.ts` 仍保留，但当前已退化为兼容 re-export；真实 fallback 编译实现已迁到 `src/services/rpg-creation/rpgCreationPreviewDraftFallback.ts`，尚未物理删除该兼容入口。
2. `legacyResultProfile` 仍保留在 session draft 中参与兼容输出，本轮没有越界清理后端兼容字段。
3. 结果页 UI 还没有显式消费 `qualityFindings / blockers / preview source` 做额外展示，当前先完成主数据源迁移，不扩大 UI 变更面。

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

### 目标

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

### 工作项

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

### 验收标准

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

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

Phase 4 本轮已完成以下主链接线：

1. 服务端 `customWorldAgentPublishingService.ts` 已补结构化 `evaluatePublishReadiness()`，把 publish blocker 从“只在发布时报错”提升为可供 session preview、结果页和 works 读模型统一消费的后端真相。
2. `customWorldAgentOrchestrator.ts` 当前输出的 `session.resultPreview` 已补：
   - `publishReady`
   - `canEnterWorld`
   - 基于发布门槛而不是仅 `qualityFindings` 生成的 `blockers`
   让结果页可以直接消费正式 gate 语义。
3. `RpgWorldWorkSummaryAssembler.ts` 已把 works 读模型进一步收口：
   - 已进入 `published` 阶段的 Agent session 不再继续以草稿项出现在 works 创作中心
   - draft works 新增 `blockerCount / publishReady`
   - published works 明确输出 `canEnterWorld=true`
4. 前端 Agent 结果页已开始消费服务端 Phase4 状态：
   - 结果页在 Agent 草稿未发布时把主 CTA 改成“发布并进入世界”
   - 结果页会消费服务端 gate 语义，但不再把 preview source 做成底部常驻提示
   - publish blockers 改为点击“发布并进入世界”时，通过独立面板提示
   - warning 数量仍可作为非阻断摘要展示
5. `useRpgCreationEnterWorld.ts` 与 `RpgEntryFlowShellImpl.tsx` 已把 Agent 结果页进入世界主链改成：
   - 先 `sync_result_profile`
   - 再执行后端 `publish_world`
   - 发布成功后才进入世界
   不再允许 Agent 草稿结果页绕开 publish gate 直接起游戏。
6. `RpgEntryWorldDetailView.tsx` 已把作品详情页草稿态的主按钮改成“请先发布作品”，避免 detail 页继续暗示未发布作品可以直接开始游戏。
7. 已补回归测试覆盖：
   - 服务端 `customWorldAgentPhase4.test.ts`
   - 服务端 `customWorldAgentPhase5.test.ts`
   - 服务端 `RpgWorldWorkSummaryAssembler.fixture.test.ts`
   - 前端 `CustomWorldResultView.test.tsx`
   - 前端 `PreGameSelectionFlow.agent.interaction.test.tsx`
8. 作品库 detail 页的“发布到广场”入口已统一复用 Agent Phase4 publish gate：
   - `/api/runtime/custom-world-library/:profileId/publish` 在命中 `agent-draft-${sessionId}` 且 session 真实存在时，不再直接绕过 gate 调 `publishOwnProfile()`
   - 现在会先复用 `CustomWorldAgentPublishingService` 的 blocker 判断
   - publish 成功后同步把对应 session 推进到 `published`
   - detail 页、works、gallery 三处发布态语义已对齐到同一条后端主链
9. 已补 HTTP 级回归测试覆盖 detail publish 主链：
   - 服务端 `app.test.ts` 已新增“agent-backed detail publish 在 blocker 存在时返回明确错误”
   - 服务端 `app.test.ts` 已新增“agent-backed detail publish 成功后同步发布 profile 与 session”

本轮刻意未做：

1. 旧兼容作品草稿的 detail publish 还没有强行套入 Agent publish gate，当前只在 `agent-draft-${sessionId}` 且 session 真实存在时切换到统一发布链，避免在未补齐兼容映射前误伤历史作品。
2. 运行态真正的“进入世界解析”仍然是前端把 profile 交给 runtime session bootstrap，本轮先完成 Agent 创作主链的 publish gate 收口与 UI 阻断，不扩大到 runtime 启动协议改造。

## Phase 5：兼容层清理

### 目标

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

### 工作项

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

### 验收标准

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

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

Phase 5 本轮已完成以下主链清理：

1. 服务端已新增 `server-node/src/services/rpgCreationPreviewProfileBuilder.ts`，把“foundation draft + legacyResultProfile 富字段 + 最新草稿资产”的合并规则正式收回后端，preview 与 publish 开始复用同一套兼容编译口径。
2. `customWorldAgentOrchestrator.ts` 当前产出的 `session.resultPreview` 已不再依赖前端本地 fallback：
   - 预览 profile 改为基于服务端 `rpgCreationPreviewProfileBuilder` 构建
   - preview source 已从兼容期的 `legacy_custom_world_profile` 收口为正式主链值 `session_preview`
3. 前端 `rpgCreationPreviewAdapter.ts` 已改成只消费服务端 `session.resultPreview`，结果页、继续创作、自动保存、发布后进入世界所复用的 `buildPreviewFromSession()` 不再承担本地 `draftProfile -> result profile` 编译职责。
4. 结果页与编辑器目录内部的旧 façade 依赖已继续收口，当前 RPG 创作目录内部不再通过已删除旧文件反向跳转结果页/编辑器/资产工坊主链。
5. 前后端测试口径已同步切到 Phase 5：
   - 前端 `rpgCreationPreviewAdapter.test.ts`、`PreGameSelectionFlow.agent.interaction.test.tsx` 已统一改为消费 `session_preview`
   - 服务端 `RpgWorldPreviewCompiler.test.ts` 已新增“preview builder 保留 legacy 富字段并合并最新草稿资产”的回归
   - 服务端 `customWorldAgentPhase3.test.ts`、`customWorldAgentPhase4.test.ts`、`app.test.ts` 已把 preview source 断言更新为 `session_preview`

本轮刻意未做：

1. 后端 `legacyResultProfile` 兼容字段仍保留在 foundation draft / result sync / publishing service 中，当前只是把“如何消费它”统一后移到服务端 preview / publish compiler，而不是继续让前端主链本地重编译。
2. 旧命名 façade 如 `customWorldAgentSessionStore.ts`、`customWorldWorkSummaryService.ts`、`runtimeProfile.ts` 仍保留，因它们还在后端兼容与模块边界层承担真实职责，不属于本轮必须删除项。
3. shared contracts 中旧 `customWorld*` 分域兼容导出仍保留，当前只收口真实定义与 preview source 语义，不越界做全仓库导入迁移。

---

## 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 发布态**

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

---

## 13. 2026-04-21 执行核查与老流程清理记录

本节用于记录本次按执行方案做的真实完成度核查、测试结果与老流程删除情况，避免“文档宣称已完成”和“代码真实状态”继续漂移。

### 13.1 本轮核查口径

本轮围绕以下 3 件事执行：

1. 对照工作包 A / B / D / E / F / G / H 进度文档，核对真实代码入口与引用关系。
2. 运行创作链相关与全量测试，确认当前主链真实可用范围。
3. 只删除已经确认不再承载业务逻辑的旧流程桥接入口，不提前删除仍承担兼容编译责任的模块。

### 13.2 核查结论

当前可以确认：

1. 工作包 B、D、E、F、G、H 的首轮主体拆分已经真实落地，且对应的新目录、hooks、client、service、repository、compiler 文件已存在。
2. 工作包 C 的结果页、编辑器、资产工坊拆分也已基本落地到 `rpg-creation-result/`、`rpg-creation-editor/`、`rpg-creation-asset-studio/` 新目录。
3. Phase 3、Phase 4、Phase 5 的主链接线与兼容层清理现已完成；当前剩余的是后端兼容字段与旧命名 façade 的保留问题，不能再把它们等同于“前端主链仍依赖老流程”。

### 13.3 本轮已物理删除的老流程入口

本轮已确认以下旧入口仅剩桥接职责，且完成引用迁移后可以安全物理删除：

1. `src/components/game-shell/PreGameSelectionFlow.tsx`
2. `src/components/CustomWorldResultView.tsx`
3. `src/components/CustomWorldEntityEditorModal.tsx`

同步完成的调用迁移包括：

1. `GameShellMainContent.tsx` 已改为直接 lazy import `rpg-creation-flow` 新入口。
2. `useGameShellViewModel.ts` 已改为直接从 `rpg-creation-flow` 取 `SelectionStage`。
3. 结果页、编辑器与对应测试已切到 `rpg-creation-result/`、`rpg-creation-editor/` 新入口。
4. `RpgCreationShellImpl.tsx` 已改为直接 lazy import `RpgCreationResultView` 新入口，不再回退到已删除旧结果页文件。

### 13.4 本轮明确不能删除的兼容层

以下模块本轮核查后确认仍在主链中承担真实兼容职责，暂时不能物理删除：

1. `src/services/rpg-creation/rpgCreationPreviewAdapter.ts`
2. `server-node/src/services/customWorldAgentSessionStore.ts`
3. `server-node/src/services/customWorldWorkSummaryService.ts`
4. `server-node/src/services/customWorldAgentOrchestrator.ts`
5. `server-node/src/modules/custom-world/runtimeProfile.ts`

原因分别是：

1. `rpgCreationPreviewAdapter.ts` 仍是前端消费服务端 preview 的统一 façade，只是已经不再承担本地 fallback 编译。
2. 后端仍通过 `legacyResultProfile` 参与阶段性结果回写与兼容输出。
3. 多个旧命名 façade 仍被 server、context、tests 或 UI 入口直接引用。

### 13.5 本轮测试结果

已执行并确认结果如下：

1. `npm run check:encoding`
   结果：通过。
2. `npm --prefix server-node run test`
   结果：通过，`192` 项测试全部通过。
3. `npm --prefix server-node run build`
   结果：通过。
4. `npm --prefix server-node run test -- --test-name-pattern="action registry|phase5 publish_world|phase5 generate_scene_assets|phase5 publish_world blocks incomplete|phase5 revert_checkpoint|phase5 expand_long_tail"`
   结果：通过，`208` 项测试全部通过，已覆盖工作包 E 第三轮发布链、场景资产、长尾扩展与 checkpoint 回滚主链。
5. `npm run test -- src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx src/components/CustomWorldResultView.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx`
   结果：通过，`34` 项测试全部通过。
6. `npm run test`
   结果：失败，但失败点与本轮删除旧入口无直接关系；创作链相关定向回归已通过。
7. `npm run build`
   结果：Vite 构建成功，但 build gate 因 chunk warning 失败，属于既有构建门禁问题。
8. `npm run typecheck`
   结果：失败，存在 shared contracts、story contracts、runtime data、旧测试断言等既有类型问题，当前不适合作为本轮创作链清理通过口径。
9. `npm --prefix server-node test -- src/services/customWorldAgentPhase3.test.ts src/services/customWorldAgentPhase4.test.ts src/services/customWorldAgentActionRegistry.test.ts src/services/RpgWorldPreviewCompiler.test.ts`
   结果：本轮新增的 `resultPreview` / `supportedActions` 主链断言已通过，但定向命令仍被一个既有 `customWorldAgentFoundationDraftService.test.ts` 断言失败带停，失败点与本轮 session snapshot 装配改动无直接耦合。
10. `npm --prefix server-node run build`
   结果：通过。
11. `npm run test -- src/services/rpg-creation/rpgCreationPreviewAdapter.test.ts src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx`
   结果：通过，`17` 项测试全部通过。
12. `node --test --import tsx src/services/customWorldAgentActionRegistry.test.ts`
   结果：通过，`5` 项测试全部通过。
13. `node --test --import tsx src/services/customWorldAgentPhase5.test.ts`
   结果：通过，`7` 项测试全部通过，已覆盖 `publish_world`、`generate_scene_assets`、`sync_scene_assets`、`expand_long_tail`、`revert_checkpoint` 的 Phase 5 主链回归。
14. `node --test --import tsx src/services/rpg-agent-session-store/rpgAgentSessionCompatibility.test.ts`
   结果：通过，`2` 项测试全部通过。
15. `node --test --import tsx src/app.test.ts`
   结果：通过，`55` 项测试全部通过，包含 SSE enriched session 回归。
15. `node --test --import tsx src/services/customWorldAgentPhase3.test.ts src/services/customWorldAgentPhase4.test.ts`
   结果：通过，`11` 项测试全部通过。
16. `npm --prefix server-node run build`
   结果：通过。
17. `npm run check:encoding`
   结果：通过，`1877` 个文件编码检查通过。
18. `npm run test -- src/services/rpg-creation/rpgCreationPreviewAdapter.test.ts src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx`
   结果：通过，`20` 项测试全部通过；已验证前端结果页主链不再依赖本地 preview fallback。
19. `node --test --test-concurrency=1 --import tsx src/services/customWorldAgentActionRegistry.test.ts src/services/customWorldAgentPhase3.test.ts src/services/customWorldAgentPhase5.test.ts`
   结果：通过，`16` 项测试全部通过；已验证 action registry 契约清理、Phase3 preview source 口径与 Phase5 发布链回归均正常。

### 13.6 当前全量阻塞项

截至 `2026-04-21` 本轮核查结束时，仓库仍存在以下全量阻塞：

1. `server-node/src/app.test.ts` 存在未解决合并冲突。
2. `src/hooks/story/npcEncounterActions.test.ts` 存在未解决合并冲突。
3. 前端全量 Vitest 仍有 3 个失败用例：
   - `src/components/game-shell/useGameShellRuntimeViewModel.test.ts`
   - `src/data/functionCatalog/functionCatalog.test.ts`
   - `src/hooks/story/npcEncounterActions.test.ts`
4. 前端全量 TypeScript 检查仍有多处既有错误。
5. 前端 build gate 仍被大 chunk warning 阻断。

### 13.7 完成度判断

按执行方案分阶段判断，当前更准确的状态是：

1. Phase 1：主体完成，并已开始物理清理前端旧入口。
2. Phase 2：后端拆分主体完成，`snapshot / supportedActions / resultPreview / SSE enriched session / session compatibility` 主链都已有定向回归覆盖；但旧命名 façade 兼容层仍保留，且发布链统一语义尚未进入 Phase 4 收口态。
3. Phase 3：主链接线已完成，前端结果页、自动保存与创作恢复入口已切到服务端 `resultPreview`；但本地 preview fallback 与 `legacyResultProfile` 兼容层仍保留，尚未进入 Phase 5 清理态。
4. Phase 4：部分完成，`publish_world` 已有真实 executor 与 gate 接线，但 publish gate / enter world / works 状态语义还没有完全统一到后端正式发布态。
4. Phase 4：主链完成。Agent 结果页、works 聚合、detail publish 与进入世界阻断已统一到后端正式发布态；当前剩余仅是 runtime 启动协议与旧兼容草稿映射，不再属于本阶段必须项。
5. Phase 5：主链完成。前端本地 preview 编译桥、结果页旧入口影子引用、执行型废弃 action 契约已清理完成；当前剩余仅是后端 `legacyResultProfile` 兼容字段与旧命名 façade 保留，不再阻塞本阶段验收。

### 13.8 后续删除顺序建议

后续继续删除老流程代码时，应严格按下面顺序推进：

1. 先完成 `qualityFindings / blockers / preview source` 的结果页与 gate 消费，把 Phase 4 所需阻断语义真正接到 UI 与进入世界链。
2. 再按后端兼容迁移节奏收缩 `legacyResultProfile` 写回范围，而不是恢复前端本地 preview 编译桥。
3. 再删除 `customWorldAgentSessionStore.ts`、`customWorldWorkSummaryService.ts`、`runtimeProfile.ts` 等旧命名 façade。
4. 最后清理 `customWorld*` 旧契约聚合入口与剩余测试旧导入。

### 13.9 Phase 4 本轮追加落地（`2026-04-21`）

本轮围绕 Phase 4 继续补齐了“发布链、自动保存链、进入世界链统一”的剩余断点：

1. 服务端 `CustomWorldAgentPublishingService` 已新增统一的 publish gate 摘要出口，`resultPreview` 与 works 聚合现在复用同一套 `blockers / publishReady / canEnterWorld` 判断，不再各自重复拼门禁语义。
2. `RpgWorldWorkSummaryAssembler` 已改为跳过 `stage === published` 的 session 草稿项，避免作品中心在正式发布后同时出现“已发布 profile + 已发布 session 草稿”双份状态。
3. works 草稿项的 `publishReady / blockerCount` 已从“只看 qualityFindings”切到真实 publish gate 结果，作品中心、结果页与发布执行器开始共享同一套阻断口径。
4. 前端 Agent 结果页继续沿用服务端 `resultPreview`，并在“发布并进入世界”成功后优先消费发布后的 preview/profile，而不是直接把 preview 原始对象强转成运行时 profile。
5. 已补 `RpgWorldWorkSummaryAssembler.fixture.test.ts`、`customWorldWorkSummaryService.integration.test.ts` 与 `PreGameSelectionFlow.agent.interaction.test.tsx` 回归，覆盖 works 去重、publish gate 口径一致，以及“先发布再进入世界”主链。
6. 共享 fixture 已补齐 `generatedSceneAssetId / publishReady / blockerCount / canEnterWorld` 等 Phase 4 口径字段，默认基线样本现在能够真实通过服务端 publish gate，避免 works / preview / 测试断言继续使用“前端自定义假 ready”状态。
7. 前端“发布并进入世界”交互回归已改为状态驱动 mock：结果页打开前保持 `ready_to_publish`，仅在 `publish_world` 完成后切换为 `published`，从而覆盖 Phase 4 真实的“草稿结果页 -> 发布 -> 进入世界”顺序，而不是直接伪造已发布初始态。

本轮仍未完成：

1. Agent 工作区内还没有独立的“发布世界”快捷入口，当前主入口仍在结果页。
2. 旧兼容作品草稿的 detail publish 仍保留旧作品库接口，不属于本次 Agent Phase 4 主链统一范围。

### 13.10 老脚本依赖删除追加记录（`2026-04-21`）

本轮按“不要再与老脚本有依赖”的口径继续执行物理清理，完成以下事项：

1. 前端 RPG 创作主链已切到 `Rpg*` client 命名：
   - `src/components/rpg-entry/useRpgCreationSessionController.ts` 直接调用 `createRpgCreationSession / getRpgCreationSession / streamRpgCreationMessage / executeRpgCreationAction`
   - `src/components/rpg-entry/useRpgCreationResultAutosave.ts` 直接调用 `executeRpgCreationAction / getRpgCreationOperation / upsertRpgWorldProfile`
2. `src/services/rpg-creation/` 已删除旧命名导出：
   - 不再导出 `createCustomWorldAgentSession / executeCustomWorldAgentAction / getCustomWorldAgentSession`
   - 不再导出 `listCustomWorldWorks / upsertCustomWorldProfile / listCustomWorldLibrary`
   - 不再导出结果页实体生成的 `generateCustomWorldPlayableNpc / generateCustomWorldSceneImage` 等兼容别名
3. 旧 service 聚合入口已断开：
   - `src/services/aiService.ts` 不再 re-export RPG 创作链能力
   - `src/services/storageService.ts` 已删除，运行时存档、设置、作品入口能力已迁入 `rpg-entry / rpg-runtime` 域 client
4. 旧组件入口继续物理删除：
   - `src/components/CustomWorldRoleAssetStudioModal.tsx`
   - `src/components/CustomWorldResultView.tsx`
   - `src/components/CustomWorldEntityEditorModal.tsx`
   - `src/components/game-shell/PreGameSelectionFlow.tsx`
5. 新组件入口已删除旧命名导出：
   - `RpgCreationResultView.tsx` 只导出 `RpgCreationResultView`
   - `RpgCreationEntityEditorModal.tsx` 只导出 `RpgCreationEntityEditorModal / RpgCreationEditorTarget`
   - `RpgCreationRoleAssetStudioModal.tsx` 只导出 `RpgCreationRoleAssetStudioModal`
6. 已使用源码级扫描确认 `src / packages / server-node` 中不再存在以下旧主链符号引用：
   - `createCustomWorldAgentSession`
   - `executeCustomWorldAgentAction`
   - `getCustomWorldAgentSession`
   - `streamCustomWorldAgentMessage`
   - `listCustomWorldWorks`
   - `upsertCustomWorldProfile`
   - `CustomWorldRoleAssetStudioModal`
   - `CustomWorldResultView`
   - `CustomWorldEntityEditorModal`
7. 本轮未删除 `CustomWorldProfile` 等历史数据结构类型名，也未删除 `server-node` 侧仍承担真实兼容职责的旧命名 façade；这些属于后端兼容字段与契约命名迁移，不再是前端老脚本依赖。
8. 本轮验证结果：
   - `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` 项测试全部通过。
   - `npm run test -- src/services/rpg-creation/rpgCreationGenerationClient.test.ts`
     结果：通过，`2` 项测试全部通过。
   - `npm run check:encoding`
     结果：通过，`1929` 个文件编码检查通过。