# 创作模板 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 迁入配置；首版不做过度抽象。