1

docs/technical/CREATION_AGENT_ANCHOR_TEMPLATE_COMMONIZATION_2026-04-24.md

@@ -0,0 +1,66 @@
+# 创作模板 Agent 聊天共用化设计（2026-04-24）
+
+## 背景
+
+当前创作模板的 Agent 聊天链路不一致：RPG 世界共创与拼图共创已经由后端调用模型推理生成回复和锚点状态，大鱼吃小鱼仍在 SpacetimeDB 过程内用规则推断锚点并返回固定回复。这样会导致同一入口下不同模板的共创体验不一致，也会让后续新增模板重复实现聊天流程。
+
+## 目标
+
+1. 所有创作模板的 Agent 聊天都必须由后端模型推理生成回复与下一轮锚点状态。
+2. Agent 聊天能力对齐 RPG 世界共创的功能效果：后端负责模型调用、锚点更新、进度推进与落库，前端只消费 session snapshot。
+3. 不同模板在 Agent 聊天环节只允许通过“锚点问题配置”体现差异，其余提示词骨架、流式回复、JSON 解析、失败兜底流程复用。
+4. 锚点配置必须从代码逻辑中抽离为独立配置文件，新增模板时优先新增配置而不是复制聊天代码。
+
+## 首版落地范围
+
+| 模板 | 现状 | 本次处理 |
+| --- | --- | --- |
+| RPG 世界共创 | 已走模型推理，八锚点结构最完整 | 保持现有流程，作为统一体验标杆 |
+| 拼图共创 | 已走模型推理，但锚点问题硬编码在 Rust 提示词中 | 把 5 个锚点问题迁入配置文件，提示词读取配置 |
+| 大鱼吃小鱼 | 规则推断 + 固定回复 | 新增模型推理 turn，读取 4 个锚点配置，提交消息后再 finalize 落库 |
+
+## 配置设计
+
+配置文件路径固定为：`server-rs/crates/api-server/src/creation_agent_anchor_templates.json`。
+
+每个模板配置包含：
+
+- `templateId`：模板唯一标识。
+- `displayName`：用于后端提示词，不直接展示在 UI。
+- `creationGoal`：模板最终要收束出的可玩结果。
+- `anchorQuestions`：锚点问题列表，包含 `key / label / question / requiredEffect`。
+
+首版配置只存“问题与效果”，不存模型输出 schema。原因是各模板 session 的锚点结构不同，schema 仍由各自 domain 类型约束，避免为了统一而牺牲类型安全。
+
+## 共用聊天骨架
+
+后端新增 `creation_agent_anchor_templates` 模块，提供：
+
+1. 读取并缓存配置文件。
+2. 按 `templateId` 返回模板配置。
+3. 渲染统一的“锚点问题段落”。
+
+各模板 agent turn 共用以下模型推理约束：
+
+1. 系统提示词说明当前模板目标。
+2. 插入配置文件中的锚点问题段落。
+3. 插入当前锚点状态与最近聊天记录。
+4. 要求模型只输出 JSON。
+5. 流式过程中只把 `replyText` 增量给前端。
+6. 完整响应解析后，由模板自身 domain 类型反序列化并落库。
+
+## 大鱼吃小鱼落库调整
+
+SpacetimeDB module 仍保持数据真相源职责，但不再在 `submit_big_fish_message` 内生成 assistant 回复与新锚点。流程调整为：
+
+1. `submit_big_fish_message` 只写入用户消息，保留原锚点与进度。
+2. api-server 调用模型生成 `replyText / progressPercent / nextAnchorPack`。
+3. 新增 `finalize_big_fish_agent_message_turn` procedure，把模型结果写回 assistant 消息、锚点、进度与 `last_assistant_reply`。
+4. 模型失败时通过 finalize 记录失败提示，避免用户消息丢失。
+
+## 约束
+
+- 前端不新增逻辑分支，不在 UI 中展示规则说明类文本。
+- 后端 prompt、配置与 Rust 代码必须保留中文注释或中文语义说明。
+- 配置文件是后端资产，不依赖前端动态编辑。
+- 若未来模板锚点结构统一，可以再把输出 schema 迁入配置；首版不做过度抽象。