GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
4ac4a0ca9c4b88533359a3134cab7f144a07b4bb
Genarrative/docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md
kdletters cbc27bad4a
Some checks failed
CI / verify (push) Has been cancelled
Details
init with react+axum+spacetimedb
2026-04-26 18:06:23 +08:00

76 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. 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 之后，统一为：

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

推荐并行顺序如下：

第一批并行：
工作包 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 回归。
  16. node --test --import tsx src/services/customWorldAgentPhase3.test.ts src/services/customWorldAgentPhase4.test.ts 结果：通过，11 项测试全部通过。
  17. npm --prefix server-node run build 结果：通过。
  18. npm run check:encoding 结果：通过，1877 个文件编码检查通过。
  19. npm run test -- src/services/rpg-creation/rpgCreationPreviewAdapter.test.ts src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx 结果：通过，20 项测试全部通过；已验证前端结果页主链不再依赖本地 preview fallback。
  20. 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 状态语义还没有完全统一到后端正式发布态。
  5. Phase 4：主链完成。Agent 结果页、works 聚合、detail publish 与进入世界阻断已统一到后端正式发布态；当前剩余仅是 runtime 启动协议与旧兼容草稿映射，不再属于本阶段必须项。
  6. 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 个文件编码检查通过。
Reference in New Issue View Git Blame Copy Permalink