Genarrative/docs/technical/AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md

Agent 结果页深度编辑回写主链方案（阶段一）

更新时间：2026-04-20

1. 这次阶段一先改什么

这次阶段一不做结果页只读化。

结果页继续保留当前已经可用、而且用户已经满意的这些能力：

1. 结果页继续允许深度编辑世界设定
2. 结果页继续允许编辑角色、场景、营地、封面
3. 结果页继续允许直接新增角色与地点
4. 结果页继续保留当前已有的浏览、自动保存、进入世界体验

这次真正要补的是：

把结果页里产出的完整 CustomWorldProfile，同步回 Agent session，让结果页编辑不再游离在主链之外。

---

2. 当前真正的问题

当前链路里，结果页虽然还能深度编辑，但数据职责是分裂的：

Agent session
-> 前端 buildCustomWorldProfileFromAgentDraft()
-> 结果页本地 profile
-> 结果页继续深度编辑
-> 自动保存到 custom-world-library
-> 进入世界

这里最大的问题不是“结果页能编辑”，而是：

1. 结果页编辑后的最新世界结构，没有稳定回写到 Agent session
2. 用户从结果页返回 Agent 工作区后，session 侧仍可能停留在较旧的草稿状态
3. “结果页当前看到的世界”“Agent session 当前保存的草稿”“作品库里自动保存的 profile”可能不是同一份东西
4. 进入世界时如果直接吃当前前端内存态，也会继续放大这个分叉

所以阶段一要解决的是：

结果页仍然是深度编辑器，但它编辑的是 Agent 主链里的当前结果快照，不是脱链的本地副本。

---

3. 阶段一目标状态

阶段一把链路先收成下面这样：

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：

{ 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 的历史职责