1

docs/technical/RPG_FOUNDATION_DRAFT_LLM_SEARCH_FALLBACK_2026-05-01.md

@@ -0,0 +1,45 @@
+# RPG foundation draft LLM 联网搜索降级修正（2026-05-01）
+
+## 背景
+
+本次现场错误为：
+
+```text
+agent-foundation-story-outline-batch-1 LLM 请求失败：LLM 请求超时，累计尝试 2 次
+```
+
+同一轮 `logs/llm-raw` 还记录了前置 `ToolNotOpen`：
+
+```text
+Your account has not activated web search.
+```
+
+当前 `custom_world_foundation_draft.rs` 的分阶段底稿生成全部硬编码 `.with_web_search(true)`。但这些批次只根据 Agent 已收集的八锚点、世界骨架、角色名单和场景名单生成结构化 JSON，本身不需要实时联网检索；联网搜索只能作为模板创作的增强能力，不能成为 foundation draft 的必经前置。
+
+## 根因
+
+1. `generate_custom_world_foundation_draft(...)` 没有接收 `AppConfig.creation_agent_llm_web_search_enabled`。
+2. `request_foundation_json_stage(...)` 对所有 Responses 请求固定开启 `web_search`。
+3. 非流式 foundation draft 调用没有复用创作 Agent SSE turn 中的 `ToolNotOpen` 降级策略。
+4. 当账号未开通 web search 或搜索工具链响应慢时，底稿批次会在内部 JSON 生成阶段失败，最终 operation 进入 failed。
+
+## 落地策略
+
+1. `api-server` 调用 foundation draft 生成器时显式传入 `state.config.creation_agent_llm_web_search_enabled`。
+2. foundation draft 每个业务 JSON 阶段先按配置决定是否带 `tools: [{ type: "web_search", max_keyword: 3 }]`。
+3. 若开启搜索后出现以下错误，自动使用同一 system/user prompt 无搜索重试一次：
+   - `ToolNotOpen`
+   - `has not activated web search`
+   - `未开通`
+   - 上游连接失败
+   - 请求超时
+4. JSON 修复阶段继续不启用搜索，因为修复只处理已有响应文本。
+5. SpacetimeDB reducer / procedure 不新增任何外部 I/O；仍只接收 api-server 已生成的确定性 `draftProfile` 并落库。
+
+## 验收标准
+
+1. `agent-foundation-*-batch-*` 首次搜索增强失败时，日志出现一次降级 warning，operation 不应直接失败。
+2. 降级重试请求体不再包含 `tools` / `web_search`。
+3. `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED=false` 时，foundation draft 全流程直接不带搜索工具。
+4. `cargo test -p api-server custom_world_foundation_draft --manifest-path server-rs/Cargo.toml` 通过。
+5. 修改后按项目约束使用 `npm run api-server:maincloud` 重启后端。