1

docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md

@@ -0,0 +1,212 @@
+# Agent 结果页深度编辑回写主链方案（阶段一）
+
+更新时间：`2026-04-20`
+
+## 1. 这次阶段一先改什么
+
+这次阶段一不做结果页只读化。
+
+结果页继续保留当前已经可用、而且用户已经满意的这些能力：
+
+1. 结果页继续允许深度编辑世界设定
+2. 结果页继续允许编辑角色、场景、营地、封面
+3. 结果页继续允许直接新增角色与地点
+4. 结果页继续保留当前已有的浏览、自动保存、进入世界体验
+
+这次真正要补的是：
+
+**把结果页里产出的完整 `CustomWorldProfile`，同步回 `Agent session`，让结果页编辑不再游离在主链之外。**
+
+---
+
+## 2. 当前真正的问题
+
+当前链路里，结果页虽然还能深度编辑，但数据职责是分裂的：
+
+```text
+Agent session
+-> 前端 buildCustomWorldProfileFromAgentDraft()
+-> 结果页本地 profile
+-> 结果页继续深度编辑
+-> 自动保存到 custom-world-library
+-> 进入世界
+```
+
+这里最大的问题不是“结果页能编辑”，而是：
+
+1. 结果页编辑后的最新世界结构，没有稳定回写到 `Agent session`
+2. 用户从结果页返回 Agent 工作区后，session 侧仍可能停留在较旧的草稿状态
+3. “结果页当前看到的世界”“Agent session 当前保存的草稿”“作品库里自动保存的 profile”可能不是同一份东西
+4. 进入世界时如果直接吃当前前端内存态，也会继续放大这个分叉
+
+所以阶段一要解决的是：
+
+**结果页仍然是深度编辑器，但它编辑的是 Agent 主链里的当前结果快照，不是脱链的本地副本。**
+
+---
+
+## 3. 阶段一目标状态
+
+阶段一把链路先收成下面这样：
+
+```text
+Agent session
+-> 前端 buildCustomWorldProfileFromAgentDraft() 生成结果页初始 profile
+-> 用户在结果页继续深度编辑 profile
+-> 前端调用新的 Agent action，把完整结果 profile 同步回 session
+-> session 保留：
+   - 当前 foundation draft
+   - 当前 legacyResultProfile 结果快照
+   - 重编译后的 draftCards / assetCoverage / suggestedActions
+-> 自动保存与进入世界都优先基于已同步的 session 结果快照执行
+```
+
+这一步仍然是过渡态，不是最终态。
+
+因为：
+
+1. 阶段一还不打通 `publish_world`
+2. 阶段一也不把结果页改造成完全原生的 draft 编辑器
+3. 阶段一允许继续保留 `draftProfile.legacyResultProfile` 作为兼容桥接字段
+
+但至少要做到：
+
+**结果页的深度编辑，必须进入 Agent session 的单一主链。**
+
+---
+
+## 4. 阶段一具体实现边界
+
+## 4.1 新增 Agent action：`sync_result_profile`
+
+阶段一新增一个面向结果页的 Agent action：
+
+```ts
+{ action: 'sync_result_profile'; profile: CustomWorldProfileRecord }
+```
+
+用途只有一个：
+
+把结果页当前完整 `CustomWorldProfile` 快照同步回 `CustomWorldAgentSessionRecord`。
+
+它不是发布动作，也不是世界编译动作。
+它只是把结果页当前编辑结果认回主链。
+
+---
+
+## 4.2 服务端写回策略
+
+服务端接到 `sync_result_profile` 后，按下面规则处理：
+
+1. 读取当前 session
+2. 取当前 `draftProfile`
+3. 保留当前 draft 层已有的结构化字段：
+   - `playableNpcs / storyNpcs / landmarks / camp`
+   - `factions / threads / chapters / sceneChapters`
+   - `worldHook / playerPremise / openingSituation / iconicElements`
+   - 以及现有资产、scene chapter 等字段
+4. 把结果页传来的完整 `CustomWorldProfile` 写入 `draftProfile.legacyResultProfile`
+5. 对于 draft 层里本来就和结果页一一对应、且结果页已经改动的字段，同步覆盖基础摘要字段：
+   - `name`
+   - `subtitle`
+   - `summary`
+   - `tone`
+   - `playerGoal`
+   - `majorFactions`
+   - `coreConflicts`
+6. 重新编译 `draftCards`
+7. 重建 `assetCoverage`
+8. 刷新 `suggestedActions`
+9. 写入 action result message 和 checkpoint
+
+这里故意不在阶段一做“把完整 runtime profile 反解成一整套全量 foundation draft 结构”的大重构。
+
+原因是：
+
+1. 结果页当前已经支持很多深度编辑字段
+2. 如果现在硬做全量反编译，最容易把场景章节、多幕、资产字段写坏
+3. 阶段一应该先保证“结果页编辑不脱链”，而不是一次性重做所有模型映射
+
+---
+
+## 4.3 前端触发策略
+
+前端只在 `customWorldResultViewSource === 'agent-draft'` 时走这条同步链。
+
+具体规则：
+
+1. 结果页 profile 每次发生变化时，继续允许本地即时更新
+2. 但在自动保存前，先把 profile 通过 `sync_result_profile` 同步到 Agent session
+3. 返回创作时，如果要重新读 Agent 草稿，也应优先以最新 session 为准
+4. 点击“进入世界”时，先拉取最新 session，再重新 `buildCustomWorldProfileFromAgentDraft()`，避免吃到旧的前端缓存 profile
+
+这样阶段一就能做到：
+
+1. 结果页编辑体验不变
+2. Agent session 成为结果页编辑后的可恢复真相源
+3. 自动保存、返回创作、进入世界三条路都围绕同一份 session-backed 结果快照
+
+---
+
+## 5. 阶段一明确不做什么
+
+这次阶段一明确不做：
+
+1. 不关闭结果页当前已有的编辑器能力
+2. 不删除结果页当前已有的 AI 新增角色/地点能力
+3. 不打通 `publish_world`
+4. 不把 `legacyResultProfile` 直接删掉
+5. 不把结果页整个改写成只操作 draft card 的新系统
+6. 不把旧 `custom-world/sessions` 链在本阶段直接物理移除
+
+---
+
+## 6. 验收标准
+
+阶段一做完后，至少要满足下面这些结果：
+
+1. Agent 草稿结果页继续保持当前深度编辑体验不变
+2. 结果页发生编辑后，Agent session 中能看到同步后的最新结果快照
+3. 从结果页返回创作后，不会明显回退到较旧的草稿态
+4. 点击“进入世界”时，会优先使用最新 session 重新编译结果，而不是只依赖前端旧内存态
+5. 自动保存到作品库的 profile 与当前 session 结果快照保持一致
+
+---
+
+## 7. 一句话结论
+
+阶段一不是收掉结果页，而是把结果页继续保留为深度编辑器，同时补上一条正式的 session 回写链，让它不再游离在 Agent 主链之外。
+
+---
+
+## 8. 2026-04-20 实际落地结果
+
+本轮已经按阶段一目标完成下面这些收口：
+
+1. 前端结果页自动保存时，若当前来源是 `agent-draft`，会先执行 `sync_result_profile`
+2. `sync_result_profile` 完成后，自动保存不再直接写旧的前端内存 profile，而是优先保存从最新 session 重新 `buildCustomWorldProfileFromAgentDraft()` 得到的结果快照
+3. 点击“进入世界”时，仍会先同步 session，再基于最新 session 重编译 profile 后进入世界
+4. 点击“返回创作”时，也会先做一次结果页到 session 的同步兜底，再返回 Agent 工作区
+5. 为避免用户刚从结果页返回工作区又被自动重开逻辑顶回结果页，前端补了一层显式返回抑制标记
+6. 服务端 `sync_result_profile` 现已按阶段一边界收窄为“保留 foundation draft 结构，只更新基础摘要字段和 `legacyResultProfile`”，没有提前做整套 runtime -> draft 反解
+
+这意味着阶段一当前已经把下面三条路径收回到同一条 session 主链：
+
+1. 自动保存到作品库
+2. 返回 Agent 工作区继续创作
+3. 从结果页直接进入世界
+
+## 9. 本轮仍然保留的阶段性边界
+
+这次落地后，仍然保留文档原先约定的过渡边界：
+
+1. 结果页深度编辑能力不做收缩
+2. `draftProfile.legacyResultProfile` 继续作为兼容桥接字段保留
+3. `publish_world` 仍未在这一轮打通
+4. 前端仍然使用 `buildCustomWorldProfileFromAgentDraft()` 作为 session -> 结果页的兼容编译层
+
+所以下一阶段如果要继续推进，重点应转向：
+
+1. 降低前端对 legacy profile 编译桥接的依赖
+2. 继续把发布链路收口到 Agent session / service 侧
+3. 逐步缩减结果页直改 legacy profile 的历史职责