init with react+axum+spacetimedb

docs/technical/UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md

@@ -0,0 +1,136 @@
+# 统一创作品类 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 / 编码检查通过。