GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
04bff9617dbb24513bacd271b3c651be21ba2925
Genarrative/docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md

39 KiB
Raw Blame History

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

更新时间：2026-04-21

0. 文档目标

本文件只服务一件事：

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

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

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

1. 范围与依据

1.1 本文覆盖的创作链路

平台创作入口
-> 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 目标链路

前端平台壳层
-> 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 之后，统一为：

结果页编辑
-> 服务端写回 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 并行推进关系

推荐并行顺序如下：

第一批并行：
工作包 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 发布态

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

Reference in New Issue View Git Blame Copy Permalink