Genarrative/docs/technical/BACKEND_CREATION_AGENT_LLM_TURN_COMMONIZATION_2026-04-25.md

后端创作 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. 编码检查通过。