Genarrative/docs/technical/UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md

统一创作品类 Agent 对话框架技术方案

日期：2026-04-22

1. 目标

把平台内所有“先 Agent 聊天收束锚点，再生成结果页”的创作流程统一到一套前端框架：

1. UI 交互共用一套：标题区、返回、进度条、进度操作按钮、生成结果页按钮、操作横幅、聊天气泡、推荐回复、输入框。
2. 对话进度管理共用一套：进度归一化、忙碌态判断、SSE reply_delta / session / error 解析、操作状态展示。
3. 品类差异只允许落在配置和后端领域逻辑：锚点列表、提示词/占位文案、生成结果页 action、快捷补全/总结话术、结果页与运行态。

2. 本轮范围

覆盖当前已接入平台入口的三条创作链：

1. RPG / Custom World Agent 创作。
2. 大鱼吃小鱼 Agent 创作。
3. 拼图 Agent 创作。

本轮不迁移结果页、运行态、发布、资产生成 UI；这些仍按各品类自己的页面承载。

3. 前端结构

新增目录：

src/components/creation-agent/
├─ CreationAgentWorkspace.tsx
└─ index.ts

src/services/creation-agent/
├─ creationAgentProgress.ts
├─ creationAgentSse.ts
└─ index.ts

3.1 CreationAgentWorkspace

统一组件只接收通用 view model：

1. session: CreationAgentSessionView | null
2. theme: 品类主题色与背景 class
3. primaryAction: 生成结果页按钮配置
4. progressActions: 总结、补全等可选快捷动作
5. activeOperation: 可选操作状态
6. streamingReplyText / isStreamingReply / isBusy / error
7. onBack / onSubmitText / onPrimaryAction / onQuickAction

聊天页展示规则：

1. Agent 聊天页不展示锚点内容卡片，锚点只作为进度与后端生成依据。
2. 标题区文案支持按品类留空；当 title 与 assistantSummary 都为空时，顶部模块只保留返回、进度和操作按钮，不显示额外标题与副文案。
3. 生成草稿 / 生成结果页主按钮只在 progressPercent 归一化后达到 100% 时显示。
4. 进度条下方承载“总结当前设定”“补全剩余设定”等进度操作按钮。
5. “补全剩余设定”必须配置 minTurn: 2，对话不足两轮时不显示。

组件内部只做表现，不读取任何 RPG、Big Fish、Puzzle 专属字段。

3.2 会话 view model

各品类工作区负责把自己的 session 映射成：

1. title
2. assistantSummary
3. progressPercent
4. currentTurn
5. anchors: { key, label, value, status }[]
6. messages: { id, role, kind, text, createdAt }[]
7. recommendedReplies

因此新增品类时只需要新增 mapper，不再复制聊天工作区。

3.3 进度管理

creationAgentProgress.ts 统一提供：

1. normalizeCreationAgentProgress(progressPercent)
2. isCreationAgentOperationBusy(operation)
3. resolveCreationAgentProgressHint(progressPercent, copy?)
4. resolveCreationAnchorStatusLabel(status)
5. createCreationAgentClientMessageId(prefix)

3.4 SSE 解析

creationAgentSse.ts 统一解析现有 SSE 事件：

1. reply_delta: 调用 onUpdate(text)
2. session: 缓存最终 session
3. error: 抛出后端错误
4. 流结束后若没有 session，抛出品类传入的 incomplete message

各品类 client 只负责打开自己的 URL 和提供类型参数。

4. 品类差异边界

4.1 RPG / Custom World

保留差异：

1. 8 个 RPG 高杠杆锚点映射。
2. 总结当前设定话术。
3. 补全剩余设定话术。
4. 生成结果页 action：draft_foundation。

draft_foundation 的生成进度必须展示并真实执行后端后台任务阶段：世界骨架、角色/场景结构、底稿编译、角色主形象生成、幕背景图生成、草稿卡编译、结果页写回。角色主形象与幕背景图不能只作为 UI 进度占位；后台任务必须调用素材生成链路，将角色 imageSrc / generatedVisualAssetId 与场景幕 backgroundImageSrc / backgroundAssetId 写回 draftProfile 后，才能继续进入草稿卡编译与结果页写回。

4.2 大鱼吃小鱼

保留差异：

1. 4 个玩法锚点映射。
2. 输入框占位提示。
3. 生成结果页 action：big_fish_compile_draft。

4.3 拼图

保留差异：

1. 拼图视觉/题材锚点映射。
2. 输入框占位提示。
3. 生成结果页 action：compile_puzzle_draft。

5. 禁止事项

1. 禁止在统一组件中判断具体品类名称后写分支业务。
2. 禁止把 Big Fish / Puzzle 的状态写入 RPG 命名脚本。
3. 禁止把后端锚点收束、提示词生成或进度裁决搬到前端。
4. 禁止为了统一 UI 改写结果页、运行态或发布流程。

6. 验收

1. 三个创作流程的 Agent 聊天区都通过 CreationAgentWorkspace 渲染。
2. Big Fish 与 Puzzle 不再各自复制聊天 UI、输入框和进度条。
3. RPG / Custom World 保留原有“总结当前设定 / 补全剩余设定 / 生成游戏设定草稿”交互。
4. 定向 TypeScript / ESLint / 编码检查通过。