# 后端创作 Agent LLM Turn 公共化 2026-04-25

## 背景

RPG、大鱼吃小鱼、拼图三条创作 Agent 后端 turn 已经统一使用 `platform-llm`，但在 `api-server` 内仍重复维护以下流程：

1. 检查 `LlmClient` 是否可用。
2. 构造 `system + user` 两段消息。
3. 调用 `stream_text` 并从增量 JSON 中抽取 `replyText` 给 SSE 前端。
4. 从模型最终文本中截取并解析 JSON。
5. 把模型调用失败、JSON 解析失败映射成中文业务错误。

这些逻辑属于 turn 级基础设施，不应散落在不同玩法文件里；但各玩法的 prompt、anchor pack 解析、stage 推进、SpacetimeDB finalize 写回仍是领域逻辑，不在本轮合并。

## 目标

1. 新增 `api-server` 内部公共模块 `creation_agent_llm_turn`。
2. 公共化流式 JSON turn 调用、非流式 JSON turn 调用、`replyText` 增量解析、最终 JSON 截取解析。
3. 大鱼、拼图、RPG Agent turn 复用公共调用骨架。
4. 保留各玩法原有结果结构、中文错误文案和持久化写回契约。

## 非目标

1. 不统一 RPG、大鱼、拼图的 prompt。
2. 不统一三类 anchor pack / draft profile schema。
3. 不改变 SpacetimeDB reducer/procedure 或 session 表结构。
4. 不改变前端 SSE contract。

## 落地边界

1. `server-rs/crates/api-server/src/creation_agent_llm_turn.rs`
   - 提供 `stream_creation_agent_json_turn(...)`。
   - 提供 `request_creation_agent_json_turn(...)`。
   - 提供 `parse_json_response_text(...)` 与 `extract_reply_text_from_partial_json(...)`。
2. `custom_world_agent_turn.rs`
   - 保留 RPG 动态状态判断、八锚点解析、结果写回。
   - 将正式单轮生成和状态识别的 LLM 请求改走公共模块。
3. `big_fish_agent_turn.rs` / `puzzle_agent_turn.rs`
   - 将 LLM 流式请求和 JSON 解析改走公共模块。
   - 继续保留玩法自己的 anchor pack 解析和 quick fill 规则。

## 验收

1. `cargo test -p api-server` 中相关 turn 单测通过。
2. `cargo check -p api-server` 不引入新的编译错误。
3. 编码检查通过。