# 统一创作品类 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. 前端结构

新增目录：

```text
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 / 编码检查通过。