1

docs/technical/LLM_MODEL_ROUTING_RPG_AND_CREATION_2026-04-30.md

@@ -0,0 +1,79 @@
+# RPG 剧情与模板创作模型路由调整（2026-04-30）
+
+## 1. 背景
+
+当前 `server-rs` 的文本模型主链统一通过 `platform-llm` 走 Ark OpenAI 兼容 `/chat/completions`。本轮模型切换有两个不同边界：
+
+1. RPG 运行时剧情推理继续使用 Ark `/chat/completions`，但模型固定为 `doubao-seed-character-251128`。
+2. 模板创作流程的大模型推理统一使用 Ark `/responses`，模型固定为 `deepseek-v3-2-251201`，并按 Responses API 的 `tools: [{ type: "web_search", max_keyword: 3 }]` 方式启用联网搜索。
+
+因此本次不能只替换 `GENARRATIVE_LLM_MODEL` 默认值。默认值仍可能被通用代理或其他兼容调用使用；RPG 剧情与模板创作需要在业务请求上显式覆盖模型和协议，避免两条主链互相污染。
+
+## 2. 落地范围
+
+### 2.1 RPG 剧情推理
+
+以下运行时 RPG 推理请求必须显式使用：
+
+- model: `doubao-seed-character-251128`
+- protocol: `/chat/completions`
+
+覆盖入口：
+
+1. `runtime_story/compat/ai.rs`
+   - 首段剧情与继续剧情。
+   - NPC 对话剧情文本。
+   - 预留的动作结果叙事生成。
+2. `runtime_chat.rs`
+   - NPC 单轮聊天回复。
+   - NPC 单轮后续建议。
+3. `runtime_chat_plain.rs`
+   - 角色私聊回复、建议、摘要。
+   - NPC 对话、招募对话等纯文本流。
+
+### 2.2 模板创作流程
+
+以下创作链路必须显式使用：
+
+- model: `deepseek-v3-2-251201`
+- protocol: `/responses`
+- web_search: 开启时映射为 `tools: [{ "type": "web_search", "max_keyword": 3 }]`
+
+覆盖入口：
+
+1. `creation_agent_llm_turn.rs`
+   - RPG/自定义世界 Agent 单轮 JSON turn。
+   - 大鱼吃小鱼 Agent 单轮 JSON turn。
+   - 拼图 Agent 单轮 JSON turn。
+   - 动态状态判断等非流式 JSON turn。
+2. `custom_world_foundation_draft.rs`
+   - 世界框架、角色、场景、角色详情等分阶段底稿生成。
+   - JSON 修复阶段。
+3. `custom_world_agent_entities.rs`
+   - 结果页新增角色/地点生成。
+4. `custom_world_ai.rs`
+   - 结果页兜底补齐实体生成。
+5. `big_fish_draft_compiler.rs`
+   - 大鱼吃小鱼草稿结构化编译与 JSON 修复。
+
+图片、视频、OSS、SpacetimeDB reducer 不属于本次模型切换范围。
+
+## 3. 平台层改造
+
+`platform-llm` 保留原 `/chat/completions` 能力，并新增 Responses 协议：
+
+1. `LlmTextProtocol::ChatCompletions`
+2. `LlmTextProtocol::Responses`
+3. `LlmTextRequest::with_responses_api()`
+4. `LlmConfig::responses_url()`
+
+Responses 非流式解析优先读取 `output_text`，再兼容 `output[].content[].text`。Responses 流式解析只把 `response.output_text.delta` 的 `delta` 推给上层，避免把 reasoning summary、工具事件或完成事件误拼进玩家可见文本。
+
+## 4. 验收标准
+
+1. RPG 运行时 LLM 请求在代码层显式带 `doubao-seed-character-251128`。
+2. 创作模板 LLM 请求在代码层显式带 `deepseek-v3-2-251201` 与 Responses 协议。
+3. `platform-llm` 单测覆盖 Responses 非流式、Responses SSE、Responses web_search tools 请求体。
+4. `cargo test -p platform-llm --manifest-path server-rs/Cargo.toml` 通过。
+5. `cargo test -p api-server creation_agent_llm_turn --manifest-path server-rs/Cargo.toml` 通过。
+6. 修改后按项目约束使用 `npm run api-server:maincloud` 重新启动后端，并执行相应自动测试。