1

docs/prd/AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE6_IMPLEMENTATION_PLAN_2026-04-14.md

@@ -0,0 +1,700 @@
+# AI 原生 Agent-First 自定义世界创作工具第六阶段技术落地方案
+
+更新时间：`2026-04-14`
+
+## 0. 文档目的
+
+这份文档用于把以下几份文档进一步收束成第六阶段实现方案：
+
+- [AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PRD_2026-04-12.md](./AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PRD_2026-04-12.md)
+- [AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE4_IMPLEMENTATION_PLAN_2026-04-14.md](./AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE4_IMPLEMENTATION_PLAN_2026-04-14.md)
+- [AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE5_IMPLEMENTATION_PLAN_2026-04-14.md](./AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE5_IMPLEMENTATION_PLAN_2026-04-14.md)
+
+如果说第五阶段的目标是：
+
+**把草稿世界里的角色第一次接上正式的主图与核心动作资产工坊**
+
+那么第六阶段的目标就是：
+
+**把草稿世界里的营地和关键场景第一次接上正式的背景图工坊。**
+
+一句话定义：
+
+**第六阶段把“场景只是文字卡”升级成“场景开始有可预览、可应用的背景图资产”。**
+
+---
+
+## 1. 阶段衔接关系
+
+## 1.1 第五阶段已经完成什么
+
+第六阶段默认建立在第五阶段已经完成的能力之上：
+
+1. 角色卡已经可以接入资产工坊
+2. 角色主图与动作可以写回 `draftProfile`
+3. `assetCoverage.roleAssets` 已开始发挥作用
+4. 工作区已具备“卡片详情 -> 资产工坊 -> session 同步”的基本模式
+
+## 1.2 第六阶段不再重做什么
+
+以下内容第六阶段不重做：
+
+1. 不重做 foundation draft 生成
+2. 不重做草稿设定编辑
+3. 不重做 AI 新增角色 / 场景
+4. 不重做角色主图与动作资产工坊接入
+
+第六阶段只继续补：
+
+1. 营地背景图资产工坊
+2. 场景背景图资产工坊
+3. 场景图状态写回 session 与 draftProfile
+4. 场景卡资产状态展示
+
+---
+
+## 2. 第六阶段在八阶段中的位置
+
+八阶段拆分如下：
+
+1. 阶段 1：创作页面入口、Agent 会话主链与工作区骨架
+2. 阶段 2：最小锚点收集与澄清流程
+3. 阶段 3：世界底稿生成与草稿卡编译
+4. 阶段 4：草稿设定编辑与 AI 新增角色/场景生成
+5. 阶段 5：角色主图与动作资产工坊接入
+6. 阶段 6：场景背景图工坊接入
+7. 阶段 7：长尾内容扩展与自动补齐
+8. 阶段 8：发布、世界库接入与继续创作恢复
+
+本文件只覆盖：
+
+**阶段 6：场景背景图工坊接入**
+
+---
+
+## 3. 第六阶段目标
+
+第六阶段只做 7 件必须一起成立的事：
+
+1. 用户可以从 `landmark` 卡和 `camp` 卡打开场景图工坊
+2. 用户可以为场景生成背景图候选
+3. 用户可以预览生成结果
+4. 用户可以选择结果并保存为正式场景图
+5. 保存成功后，场景对象会写回 `imageSrc / generatedSceneAssetId / generatedScenePrompt / generatedSceneModel`
+6. `assetCoverage.sceneAssets` 状态会更新
+7. 工作区和创作页面能感知场景资产状态变化
+
+一句话目标：
+
+**让第六阶段结束时，至少部分关键场景已经不只是“设定存在”，而是“有可用背景图”。**
+
+---
+
+## 4. 第六阶段完成定义
+
+第六阶段完成后，必须同时满足以下结果：
+
+1. 用户从某张 `landmark` 或 `camp` 卡进入详情后，可以点击“场景背景图”打开场景图工坊。
+2. 用户可以输入 prompt 并生成场景背景图结果。
+3. 用户可以预览生成结果，并在保存前决定是否继续重试。
+4. 用户保存成功后，对应场景对象会得到：
+   - `imageSrc`
+   - `generatedSceneAssetId`
+   - `generatedScenePrompt`
+   - `generatedSceneModel`
+5. `assetCoverage.sceneAssets` 中对应场景状态会更新。
+6. 工作区中的地点卡 / 营地卡会显示背景图状态变化。
+7. 第六阶段仍然不要求所有场景都立刻完成背景图，也不要求进入发布。
+
+---
+
+## 5. 范围控制
+
+## 5.1 第六阶段纳入范围
+
+纳入范围的模块：
+
+- `packages/shared/src/contracts/customWorldAgent.ts`
+- `src/components/custom-world-agent/CustomWorldAgentWorkspace.tsx`
+- `src/components/custom-world-agent/CustomWorldAgentDraftDetailPanel.tsx`
+- `src/components/custom-world-agent/CustomWorldAgentQuickActions.tsx`
+- `src/services/ai.ts`
+- `src/services/aiService.ts`
+- `server-node/src/services/customWorldAgentSessionStore.ts`
+- `server-node/src/services/customWorldAgentOrchestrator.ts`
+- `server-node/src/services/customWorldAgentDraftCompiler.ts`
+- `server-node/src/services/customWorldWorkSummaryService.ts`
+- `server-node/src/services/sceneImageService.ts`
+- `server-node/src/routes/runtimeRoutes.ts`
+
+新增前端模块：
+
+- `src/components/custom-world-agent/CustomWorldSceneAssetStudioModal.tsx`
+
+新增服务端模块：
+
+- `server-node/src/services/customWorldAgentSceneAssetStateService.ts`
+
+## 5.2 第六阶段明确不做
+
+以下内容不放进第六阶段：
+
+1. 不做角色资产工坊改造
+2. 不做长尾场景批量自动出图
+3. 不做场景图批量预生成
+4. 不做发布时强制所有场景图齐全
+5. 不做场景图精修工作流
+6. 不做地图连接与场景图自动同步生成
+
+原因：
+
+**第六阶段只解决“选中的营地或场景如何进入背景图工坊并成功把结果写回草稿世界”。**
+
+---
+
+## 6. 第六阶段最小闭环
+
+建议把第六阶段的最小闭环定义为：
+
+```text
+第五阶段已有 landmark/camp 卡
+-> 用户打开某张地点卡详情
+-> 点击“场景背景图”
+-> 打开场景图工坊
+-> 输入 prompt 并开始生成
+-> 预览结果
+-> 保存
+-> sync_scene_assets
+-> landmark/camp card / assetCoverage / 创作页面摘要同步更新
+```
+
+这个闭环里，先只强接两条高价值链路：
+
+1. `landmark/camp card -> scene asset studio`
+2. `scene asset studio save -> session sync`
+
+---
+
+## 7. 第六阶段产品行为定义
+
+## 7.1 哪些对象可以进入场景图工坊
+
+第六阶段允许以下对象进入场景图工坊：
+
+1. `camp`
+2. `landmark`
+
+不处理：
+
+1. 其他卡片类型
+
+## 7.2 入口位置
+
+### 地点卡详情入口
+
+在 `CustomWorldAgentDraftDetailPanel` 中，当当前卡类型为：
+
+```ts
+kind === 'landmark' || kind === 'camp'
+```
+
+显示按钮：
+
+- `场景背景图`
+
+### 快捷动作入口
+
+当当前 focus card 为 `landmark` 或 `camp` 时，`CustomWorldAgentQuickActions` 可显示：
+
+- `生成场景背景图`
+
+说明：
+
+快捷动作与详情按钮最终都打开同一个 modal。
+
+## 7.3 第六阶段支持的场景图流程
+
+### 阶段 A：场景图生成
+
+允许：
+
+1. 输入场景内容描述
+2. 上传一张可选参考图
+3. 基于当前场景语义生成背景图
+
+### 阶段 B：场景图预览
+
+用户必须可以：
+
+1. 看到新生成图片
+2. 对比当前图片
+3. 决定是否保存
+
+### 阶段 C：场景图保存
+
+保存后把结果写回：
+
+1. `imageSrc`
+2. `generatedSceneAssetId`
+3. `generatedScenePrompt`
+4. `generatedSceneModel`
+
+## 7.4 第六阶段不强制的事情
+
+第六阶段明确不强制：
+
+1. 每个场景都必须立刻生成背景图
+2. 每个背景图都必须一次满意
+3. 没有背景图的场景不能继续文本创作
+
+说明：
+
+这一步是“场景开始接资产”，不是“所有场景必须立刻完工”。**
+
+## 7.5 积分消耗提示规则
+
+和第五阶段保持一致：
+
+**不做预算限制，但高成本生成前必须明确提示积分消耗。**
+
+因此第六阶段必须遵守：
+
+### 生成前
+
+必须提示：
+
+1. 本次会消耗多少积分
+2. 这是候选生成，不是最终发布
+
+### 保存前
+
+保存本身不应再次重复收积分，除非现有场景图服务明确要求。
+
+---
+
+## 8. 场景资产状态定义
+
+## 8.1 `assetCoverage.sceneAssets`
+
+第六阶段必须开始真正使用它。
+
+建议状态：
+
+```ts
+type CustomWorldSceneAssetStatus = 'missing' | 'ready';
+```
+
+### 含义
+
+#### `missing`
+
+场景还没有正式背景图
+
+#### `ready`
+
+场景已经有：
+
+1. `imageSrc`
+2. `generatedSceneAssetId`
+
+## 8.2 场景对象写回字段
+
+保存成功后，必须写回：
+
+```ts
+imageSrc
+generatedSceneAssetId
+generatedScenePrompt
+generatedSceneModel
+```
+
+### 明确要求
+
+第六阶段不允许只更新 `assetCoverage`，不更新场景对象本身。
+
+---
+
+## 9. 数据结构落地方案
+
+## 9.1 启用 `CustomWorldAgentActionRequest`
+
+第六阶段正式启用：
+
+```ts
+| {
+    action: 'sync_scene_assets';
+    sceneId: string;
+    sceneKind: 'camp' | 'landmark';
+    imageSrc: string;
+    generatedSceneAssetId: string;
+    generatedScenePrompt?: string | null;
+    generatedSceneModel?: string | null;
+  }
+```
+
+### 第六阶段说明
+
+不新增新的 `generate_scene_assets` 前置准备 action。
+
+原因：
+
+当前场景图生成链已经由 `generateCustomWorldSceneImage(...)` 直接承接，
+因此第六阶段只需要在保存成功后做 session 同步。
+
+## 9.2 扩展 `CustomWorldSceneAssetSummary`
+
+第六阶段开始必须真正填：
+
+1. `imageSrc`
+2. `generatedSceneAssetId`
+3. `status`
+4. `nextPointCost`
+
+## 9.3 新增场景资产同步结果结构
+
+建议新增：
+
+```ts
+type SyncSceneAssetsResult = {
+  sceneId: string;
+  sceneKind: 'camp' | 'landmark';
+  updatedScene: Record<string, unknown>;
+  updatedAssetSummary: CustomWorldSceneAssetSummary;
+};
+```
+
+---
+
+## 10. 服务端实现方案
+
+## 10.1 新增 `customWorldAgentSceneAssetStateService.ts`
+
+### 文件
+
+`server-node/src/services/customWorldAgentSceneAssetStateService.ts`
+
+### 职责
+
+根据营地或场景对象真实字段，更新：
+
+1. `assetCoverage.sceneAssets`
+2. `draftCards` 中地点卡 / 营地卡的副摘要
+3. 创作页面作品卡统计
+
+### 导出函数建议
+
+```ts
+rebuildSceneAssetCoverage(draftProfile)
+mergeSceneAssetIntoDraftProfile(draftProfile, payload)
+```
+
+## 10.2 修改 `customWorldAgentOrchestrator.ts`
+
+第六阶段必须启用：
+
+1. `sync_scene_assets`
+
+### `sync_scene_assets` 流程
+
+```text
+收到 sync_scene_assets
+-> 校验 sceneId
+-> 校验 sceneKind
+-> 写回 draftProfile.camp 或 draftProfile.landmarks
+-> 重建 assetCoverage.sceneAssets
+-> 重新编译地点卡 / 营地卡摘要
+-> 写入 assistant action_result
+-> 写入 checkpoint
+-> operation completed
+```
+
+### camp 写回规则
+
+当：
+
+```ts
+sceneKind === 'camp'
+```
+
+写回：
+
+```ts
+draftProfile.camp
+```
+
+### landmark 写回规则
+
+当：
+
+```ts
+sceneKind === 'landmark'
+```
+
+写回：
+
+```ts
+draftProfile.landmarks.find(...)
+```
+
+## 10.3 修改 `customWorldAgentDraftCompiler.ts`
+
+第六阶段它必须让：
+
+1. `landmark` 卡摘要带出场景图状态
+2. `camp` 卡摘要带出场景图状态
+
+### 推荐展示方式
+
+在 `subtitle` 或 `summary` 中追加：
+
+1. `背景图已就绪`
+2. `待生成背景图`
+
+但不要把卡片变成技术表。
+
+## 10.4 修改 `customWorldWorkSummaryService.ts`
+
+第六阶段创作页面草稿卡应支持展示：
+
+1. 已有多少场景具备背景图
+
+第一版如果不想上具体数字，也至少要能体现：
+
+- `场景资产进行中`
+
+---
+
+## 11. 前端实现方案
+
+## 11.1 新增 `CustomWorldSceneAssetStudioModal.tsx`
+
+### 来源
+
+从当前 `CustomWorldEntityEditorModal.tsx` 中的 `SceneImageGenerationModal` 思路抽出，
+但改成可被 Agent 工作区调用的版本。
+
+### props
+
+```ts
+{
+  profile: Pick<CustomWorldProfile, 'id' | 'name' | 'summary' | 'tone' | 'playerGoal' | 'settingText'>;
+  scene: {
+    id: string;
+    kind: 'camp' | 'landmark';
+    name: string;
+    description: string;
+    dangerLevel?: string;
+    imageSrc?: string;
+  };
+  onPublishSuccess: (payload) => void;
+  onClose: () => void;
+}
+```
+
+### 功能
+
+1. 输入场景 prompt
+2. 上传可选参考图
+3. 调用 `generateCustomWorldSceneImage(...)`
+4. 展示预览
+5. 保存并回调 `onPublishSuccess`
+
+## 11.2 修改 `CustomWorldAgentDraftDetailPanel.tsx`
+
+当卡片类型为 `landmark` 或 `camp` 时，新增：
+
+1. `场景背景图` 按钮
+2. 资产状态 badge
+
+### 状态显示建议
+
+1. `待生成背景图`
+2. `背景图已就绪`
+
+## 11.3 修改 `CustomWorldAgentQuickActions.tsx`
+
+当当前 focus card 为 `landmark` 或 `camp` 时，可显示：
+
+- `生成场景背景图`
+
+点击后：
+
+1. 直接打开 `CustomWorldSceneAssetStudioModal`
+
+## 11.4 修改 `CustomWorldAgentWorkspace.tsx`
+
+新增状态：
+
+```ts
+activeSceneAssetTarget?: {
+  sceneId: string;
+  sceneKind: 'camp' | 'landmark';
+} | null;
+showSceneAssetStudio: boolean;
+```
+
+### 打开逻辑
+
+1. 来自 detail panel
+2. 来自 quick actions
+
+### 关闭逻辑
+
+关闭不代表写回成功。
+
+必须等：
+
+1. 场景图生成完成并保存
+2. `sync_scene_assets` 成功
+
+之后才刷新场景资产状态。
+
+## 11.5 修改 `CustomWorldCreationHub.tsx`
+
+第六阶段它必须支持草稿作品卡的“场景资产进度感”。
+
+第一版至少做到：
+
+1. 草稿卡可展示：
+   - 场景资产进行中
+   - 或若数量可得，则展示场景背景图完成数
+
+---
+
+## 12. 交互时序
+
+## 12.1 打开场景图工坊
+
+```text
+用户点击地点卡
+-> 打开 detail panel
+-> 点击“场景背景图”
+-> 前端打开 CustomWorldSceneAssetStudioModal
+```
+
+## 12.2 保存场景图
+
+```text
+用户在工坊中生成场景图
+-> 预览结果
+-> 点击保存
+-> 工坊得到 imageSrc + generatedSceneAssetId + prompt + model
+-> 前端调用 sync_scene_assets
+-> 服务端写回 draftProfile.camp 或 landmark
+-> 服务端重建 assetCoverage.sceneAssets
+-> 服务端重编译地点卡摘要
+-> 前端刷新 snapshot
+-> 工坊关闭
+```
+
+---
+
+## 13. 与第五阶段的兼容要求
+
+## 13.1 兼容有图场景
+
+如果某场景已经有：
+
+1. `imageSrc`
+2. `generatedSceneAssetId`
+
+仍允许继续打开工坊重新生成，再保存覆盖。
+
+## 13.2 兼容无图场景
+
+如果某场景完全无：
+
+1. `imageSrc`
+2. `generatedSceneAssetId`
+
+也允许打开工坊从零生成。
+
+## 13.3 兼容新增场景
+
+第四阶段新增的 `landmark` 一旦存在于 `draftProfile.landmarks` 中，立即允许进入场景图工坊。
+
+---
+
+## 14. 落地文件清单
+
+## 14.1 frontend
+
+必须新增：
+
+1. `src/components/custom-world-agent/CustomWorldSceneAssetStudioModal.tsx`
+
+必须修改：
+
+1. `src/components/custom-world-agent/CustomWorldAgentWorkspace.tsx`
+2. `src/components/custom-world-agent/CustomWorldAgentDraftDetailPanel.tsx`
+3. `src/components/custom-world-agent/CustomWorldAgentQuickActions.tsx`
+4. `src/components/custom-world-home/CustomWorldCreationHub.tsx`
+5. `src/services/ai.ts`
+6. `src/services/aiService.ts`
+
+## 14.2 backend
+
+必须新增：
+
+1. `server-node/src/services/customWorldAgentSceneAssetStateService.ts`
+
+必须修改：
+
+1. `server-node/src/services/customWorldAgentOrchestrator.ts`
+2. `server-node/src/services/customWorldAgentDraftCompiler.ts`
+3. `server-node/src/services/customWorldAgentSessionStore.ts`
+4. `server-node/src/services/customWorldWorkSummaryService.ts`
+5. `server-node/src/services/sceneImageService.ts`
+6. `server-node/src/routes/runtimeRoutes.ts`
+
+---
+
+## 15. 测试要求
+
+## 15.1 服务端测试
+
+至少要补：
+
+1. `sync_scene_assets` 能正确写回 `camp`
+2. `sync_scene_assets` 能正确写回 `landmark`
+3. 写回后 `assetCoverage.sceneAssets` 状态更新
+4. 写回后地点卡 / 营地卡摘要更新
+5. 写回后 checkpoint 存在
+
+## 15.2 前端测试
+
+至少要补：
+
+1. landmark/camp 卡详情可显示背景图入口
+2. quick actions 可打开场景图工坊
+3. 工坊保存成功后会触发 `sync_scene_assets`
+4. snapshot 刷新后场景卡显示新状态
+
+## 15.3 手工回归
+
+至少走这 4 条：
+
+1. 为一个无图场景生成背景图
+2. 为营地生成背景图
+3. 返回 workspace 确认场景卡状态变化
+4. 返回创作页面确认草稿卡摘要变化
+
+---
+
+## 16. 第六阶段验收标准
+
+做到以下几点，才算第六阶段真正完成：
+
+1. 场景卡和营地卡已经可以接入并打开背景图工坊。
+2. 保存成功后，场景对象会写回 `imageSrc / generatedSceneAssetId / generatedScenePrompt / generatedSceneModel`。
+3. 场景资产状态会同步反映到 session snapshot 和场景卡摘要。
+4. 场景图接入不会阻塞继续文本创作。
+5. 第六阶段仍然不越界去做长尾自动补齐和发布逻辑。
+
+---
+
+## 17. 一句话结论
+
+第六阶段最重要的不是“让所有场景都立刻有图”，而是：
+
+**先把草稿世界里的营地和关键场景，真正接到一条可预览、可保存、可写回的背景图工坊链路上。**