Genarrative/docs/technical/RPG_FOUNDATION_DRAFT_LLM_SEARCH_FALLBACK_2026-05-01.md

RPG foundation draft LLM 联网搜索降级修正（2026-05-01）

背景

本次现场错误为：

agent-foundation-story-outline-batch-1 LLM 请求失败：LLM 请求超时，累计尝试 2 次

同一轮 logs/llm-raw 还记录了前置 ToolNotOpen：

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 重启后端。