1

server-rs/crates/api-server/src/custom_world_foundation_draft.rs

@@ -10,6 +10,7 @@ use platform_llm::{LlmClient, LlmMessage, LlmTextRequest};
 use serde_json::{Map as JsonMap, Value as JsonValue, json};
 use shared_contracts::runtime::ExecuteCustomWorldAgentActionRequest;
 use spacetime_client::CustomWorldAgentSessionRecord;
+use tracing::warn;
 
 use crate::llm_model_routing::CREATION_TEMPLATE_LLM_MODEL;
 
@@ -35,6 +36,7 @@ pub struct CustomWorldFoundationDraftProgress {
 pub async fn generate_custom_world_foundation_draft(
     llm_client: &LlmClient,
     session: &CustomWorldAgentSessionRecord,
+    enable_web_search: bool,
     mut on_progress: impl FnMut(CustomWorldFoundationDraftProgress) + Send,
 ) -> Result<CustomWorldFoundationDraftResult, String> {
     let setting_text = build_foundation_generation_seed_text(session);
@@ -51,6 +53,7 @@ pub async fn generate_custom_world_foundation_draft(
         |response_text| build_custom_world_framework_json_repair_prompt(response_text),
         "agent-foundation-framework-json-repair",
         "世界框架阶段没有返回有效内容。",
+        enable_web_search,
     )
     .await?;
     normalize_framework_shape(&mut framework, setting_text.as_str());
@@ -61,6 +64,7 @@ pub async fn generate_custom_world_foundation_draft(
         "playable",
         FOUNDATION_DRAFT_PLAYABLE_COUNT,
         (16, 30),
+        enable_web_search,
         &mut on_progress,
     )
     .await?;
@@ -72,6 +76,7 @@ pub async fn generate_custom_world_foundation_draft(
         "story",
         FOUNDATION_DRAFT_STORY_COUNT,
         (30, 44),
+        enable_web_search,
         &mut on_progress,
     )
     .await?;
@@ -82,6 +87,7 @@ pub async fn generate_custom_world_foundation_draft(
         &framework,
         FOUNDATION_DRAFT_LANDMARK_COUNT,
         (44, 66),
+        enable_web_search,
         &mut on_progress,
     )
     .await?;
@@ -94,6 +100,7 @@ pub async fn generate_custom_world_foundation_draft(
         &playable_outlines,
         "narrative",
         (66, 76),
+        enable_web_search,
         &mut on_progress,
     )
     .await?;
@@ -104,6 +111,7 @@ pub async fn generate_custom_world_foundation_draft(
         &playable_narrative,
         "dossier",
         (76, 84),
+        enable_web_search,
         &mut on_progress,
     )
     .await?;
@@ -114,6 +122,7 @@ pub async fn generate_custom_world_foundation_draft(
         &story_outlines,
         "narrative",
         (84, 92),
+        enable_web_search,
         &mut on_progress,
     )
     .await?;
@@ -124,6 +133,7 @@ pub async fn generate_custom_world_foundation_draft(
         &story_narrative,
         "dossier",
         (92, 96),
+        enable_web_search,
         &mut on_progress,
     )
     .await?;
@@ -171,22 +181,19 @@ async fn request_foundation_json_stage<F>(
     repair_prompt_builder: F,
     repair_debug_label: &str,
     empty_response_message: &str,
+    enable_web_search: bool,
 ) -> Result<JsonValue, String>
 where
     F: Fn(&str) -> String,
 {
-    let response = llm_client
-        .request_text(
-            LlmTextRequest::new(vec![
-                LlmMessage::system(FOUNDATION_JSON_ONLY_SYSTEM_PROMPT),
-                LlmMessage::user(user_prompt),
-            ])
-            .with_model(CREATION_TEMPLATE_LLM_MODEL)
-            .with_responses_api()
-            .with_web_search(true),
-        )
-        .await
-        .map_err(|error| format!("{debug_label} LLM 请求失败：{error}"))?;
+    let response = request_foundation_text_with_optional_search_fallback(
+        llm_client,
+        FOUNDATION_JSON_ONLY_SYSTEM_PROMPT,
+        user_prompt.as_str(),
+        debug_label,
+        enable_web_search,
+    )
+    .await?;
     let text = response.content.trim();
     if text.is_empty() {
         return Err(empty_response_message.to_string());
@@ -211,12 +218,69 @@ where
     }
 }
 
+async fn request_foundation_text_with_optional_search_fallback(
+    llm_client: &LlmClient,
+    system_prompt: &str,
+    user_prompt: &str,
+    debug_label: &str,
+    enable_web_search: bool,
+) -> Result<platform_llm::LlmTextResponse, String> {
+    match request_foundation_text(llm_client, system_prompt, user_prompt, enable_web_search).await {
+        Ok(response) => Ok(response),
+        Err(error) if enable_web_search && should_retry_foundation_without_web_search(&error) => {
+            warn!(
+                error = %error,
+                debug_label,
+                "foundation draft 联网搜索增强不可用或超时，自动降级为无联网搜索重试"
+            );
+            request_foundation_text(llm_client, system_prompt, user_prompt, false)
+                .await
+                .map_err(|retry_error| format!("{debug_label} LLM 请求失败：{retry_error}"))
+        }
+        Err(error) => Err(format!("{debug_label} LLM 请求失败：{error}")),
+    }
+}
+
+async fn request_foundation_text(
+    llm_client: &LlmClient,
+    system_prompt: &str,
+    user_prompt: &str,
+    enable_web_search: bool,
+) -> Result<platform_llm::LlmTextResponse, platform_llm::LlmError> {
+    llm_client
+        .request_text(
+            LlmTextRequest::new(vec![
+                LlmMessage::system(system_prompt),
+                LlmMessage::user(user_prompt),
+            ])
+            .with_model(CREATION_TEMPLATE_LLM_MODEL)
+            .with_responses_api()
+            .with_web_search(enable_web_search),
+        )
+        .await
+}
+
+fn should_retry_foundation_without_web_search(error: &platform_llm::LlmError) -> bool {
+    match error {
+        platform_llm::LlmError::Timeout { .. } | platform_llm::LlmError::Connectivity { .. } => {
+            true
+        }
+        platform_llm::LlmError::Upstream { message, .. } => {
+            message.contains("ToolNotOpen")
+                || message.contains("has not activated web search")
+                || message.contains("未开通")
+        }
+        _ => false,
+    }
+}
+
 async fn generate_foundation_role_outline_entries(
     llm_client: &LlmClient,
     framework: &JsonValue,
     role_type: &str,
     total_count: usize,
     progress_range: (u32, u32),
+    enable_web_search: bool,
     on_progress: &mut (impl FnMut(CustomWorldFoundationDraftProgress) + Send),
 ) -> Result<Vec<JsonValue>, String> {
     let mut merged_entries = Vec::new();
@@ -275,6 +339,7 @@ async fn generate_foundation_role_outline_entries(
             )
             .as_str(),
             "角色框架名单阶段没有返回有效内容。",
+            enable_web_search,
         )
         .await?;
         let key = role_key(role_type);
@@ -305,6 +370,7 @@ async fn generate_foundation_landmark_seed_entries(
     framework: &JsonValue,
     total_count: usize,
     progress_range: (u32, u32),
+    enable_web_search: bool,
     on_progress: &mut (impl FnMut(CustomWorldFoundationDraftProgress) + Send),
 ) -> Result<Vec<JsonValue>, String> {
     let mut merged_entries = Vec::new();
@@ -352,6 +418,7 @@ async fn generate_foundation_landmark_seed_entries(
             )
             .as_str(),
             "地点框架名单阶段没有返回有效内容。",
+            enable_web_search,
         )
         .await?;
         merged_entries.extend(array_field(&raw, "landmarks").into_iter().take(batch_count));
@@ -486,6 +553,7 @@ async fn expand_foundation_role_entries(
     base_entries: &[JsonValue],
     stage: &str,
     progress_range: (u32, u32),
+    enable_web_search: bool,
     on_progress: &mut (impl FnMut(CustomWorldFoundationDraftProgress) + Send),
 ) -> Result<Vec<JsonValue>, String> {
     let mut merged_entries = Vec::new();
@@ -540,6 +608,7 @@ async fn expand_foundation_role_entries(
             )
             .as_str(),
             "角色档案补全阶段没有返回有效内容。",
+            enable_web_search,
         )
         .await?;
         merged_entries.extend(array_field(&raw, role_key(role_type)));
@@ -2047,7 +2116,7 @@ mod tests {
         net::TcpListener,
         sync::{Arc, Mutex},
         thread,
-        time::Duration as StdDuration,
+        time::{Duration as StdDuration, SystemTime, UNIX_EPOCH},
     };
 
     use platform_llm::{DEFAULT_REQUEST_TIMEOUT_MS, LlmConfig, LlmProvider};
@@ -2383,6 +2452,80 @@ mod tests {
         );
     }
 
+    #[test]
+    fn foundation_search_fallback_handles_tool_unavailable_and_timeout() {
+        let tool_error = platform_llm::LlmError::Upstream {
+            status_code: 404,
+            message: "Your account has not activated web search. code=ToolNotOpen".to_string(),
+        };
+        let timeout_error = platform_llm::LlmError::Timeout { attempts: 2 };
+
+        assert!(should_retry_foundation_without_web_search(&tool_error));
+        assert!(should_retry_foundation_without_web_search(&timeout_error));
+        assert!(!should_retry_foundation_without_web_search(
+            &platform_llm::LlmError::EmptyResponse
+        ));
+    }
+
+    #[tokio::test]
+    async fn foundation_json_stage_retries_without_web_search_when_tool_unavailable() {
+        let log_dir = std::env::temp_dir().join(format!(
+            "api-server-foundation-raw-log-test-{}-{}",
+            std::process::id(),
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .expect("system time should be after epoch")
+                .as_nanos()
+        ));
+        unsafe {
+            std::env::set_var("LLM_RAW_LOG_DIR", &log_dir);
+        }
+        let request_capture = Arc::new(Mutex::new(Vec::new()));
+        let server_url = spawn_mock_server_with_statuses(
+            request_capture.clone(),
+            vec![
+                MockHttpResponse {
+                    status_code: 404,
+                    body: r#"{"error":{"code":"ToolNotOpen","message":"Your account has not activated web search."}}"#.to_string(),
+                },
+                MockHttpResponse {
+                    status_code: 200,
+                    body: llm_response(r#"{"name":"无搜索底稿"}"#),
+                },
+            ],
+        );
+        let llm_client = build_test_llm_client(server_url);
+
+        let parsed = request_foundation_json_stage(
+            &llm_client,
+            "请生成 JSON".to_string(),
+            "agent-foundation-test",
+            |_| "修复 JSON".to_string(),
+            "agent-foundation-test-json-repair",
+            "空响应",
+            true,
+        )
+        .await
+        .expect("web search fallback should succeed");
+
+        assert_eq!(parsed.get("name"), Some(&json!("无搜索底稿")));
+        let requests = request_capture
+            .lock()
+            .expect("request capture should lock")
+            .clone();
+        assert_eq!(requests.len(), 2);
+        assert!(requests[0].contains("\"tools\""));
+        assert!(requests[0].contains("\"web_search\""));
+        assert!(!requests[1].contains("\"tools\""));
+
+        unsafe {
+            std::env::remove_var("LLM_RAW_LOG_DIR");
+        }
+        if log_dir.exists() {
+            std::fs::remove_dir_all(log_dir).expect("temporary LLM raw log dir should be removed");
+        }
+    }
+
     #[tokio::test]
     async fn role_outline_missing_asset_fields_are_filled_locally_before_details() {
         let request_capture = Arc::new(Mutex::new(Vec::<String>::new()));
@@ -2471,7 +2614,7 @@ mod tests {
         let llm_client = build_test_llm_client(server_url);
         let session = build_test_session();
 
-        let result = generate_custom_world_foundation_draft(&llm_client, &session, |_| {})
+        let result = generate_custom_world_foundation_draft(&llm_client, &session, false, |_| {})
             .await
             .expect("draft generation should succeed");
         let draft_profile = serde_json::from_str::<JsonValue>(&result.draft_profile_json)
@@ -2739,13 +2882,9 @@ mod tests {
     fn llm_response(content: &str) -> String {
         json!({
             "id": "resp_01",
-            "choices": [
-                {
-                    "message": {
-                        "content": content,
-                    }
-                }
-            ]
+            "model": CREATION_TEMPLATE_LLM_MODEL,
+            "output_text": content,
+            "status": "completed"
         })
         .to_string()
     }
@@ -2814,6 +2953,27 @@ mod tests {
     fn spawn_mock_server(
         request_capture: Arc<Mutex<Vec<String>>>,
         response_bodies: Vec<String>,
+    ) -> String {
+        spawn_mock_server_with_statuses(
+            request_capture,
+            response_bodies
+                .into_iter()
+                .map(|body| MockHttpResponse {
+                    status_code: 200,
+                    body,
+                })
+                .collect(),
+        )
+    }
+
+    struct MockHttpResponse {
+        status_code: u16,
+        body: String,
+    }
+
+    fn spawn_mock_server_with_statuses(
+        request_capture: Arc<Mutex<Vec<String>>>,
+        responses: Vec<MockHttpResponse>,
     ) -> String {
         let listener = TcpListener::bind("127.0.0.1:0").expect("listener should bind");
         let address = listener
@@ -2821,10 +2981,13 @@ mod tests {
             .expect("listener should expose address");
 
         thread::spawn(move || {
-            let mut response_queue = VecDeque::from(response_bodies);
+            let mut response_queue = VecDeque::from(responses);
             for _ in 0..32 {
-                let response_body = response_queue.pop_front().unwrap_or_else(|| {
-                    llm_response(r#"{"storyNpcs":[{"name":"议长甲","backstory":"长期维持群岛议会体面并遮掩沉船旧案。","personality":"冷硬周密","motivation":"压住旧案","combatStyle":"以权令封锁线索","backstoryReveal":{"publicSummary":"议会遮掩者。","chapters":[{"affinityRequired":15,"title":"议会","summary":"议会出面。"},{"affinityRequired":30,"title":"封锁","summary":"封锁港口。"},{"affinityRequired":60,"title":"旧案","summary":"旧案松动。"},{"affinityRequired":90,"title":"对质","summary":"灯塔对质。"}]},"skills":[{"name":"封港令","summary":"调动巡海封锁","style":"压制"}],"initialItems":[{"name":"议会印信","category":"道具","quantity":1,"rarity":"rare","description":"可调动巡海队。","tags":["权力"]}]}]}"#)
+                let response = response_queue.pop_front().unwrap_or_else(|| {
+                    MockHttpResponse {
+                        status_code: 200,
+                        body: llm_response(r#"{"storyNpcs":[{"name":"议长甲","backstory":"长期维持群岛议会体面并遮掩沉船旧案。","personality":"冷硬周密","motivation":"压住旧案","combatStyle":"以权令封锁线索","backstoryReveal":{"publicSummary":"议会遮掩者。","chapters":[{"affinityRequired":15,"title":"议会","summary":"议会出面。"},{"affinityRequired":30,"title":"封锁","summary":"封锁港口。"},{"affinityRequired":60,"title":"旧案","summary":"旧案松动。"},{"affinityRequired":90,"title":"对质","summary":"灯塔对质。"}]},"skills":[{"name":"封港令","summary":"调动巡海封锁","style":"压制"}],"initialItems":[{"name":"议会印信","category":"道具","quantity":1,"rarity":"rare","description":"可调动巡海队。","tags":["权力"]}]}]}"#),
+                    }
                 });
                 let (mut stream, _) = listener.accept().expect("request should connect");
                 let request_text = read_request(&mut stream);
@@ -2832,7 +2995,7 @@ mod tests {
                     .lock()
                     .expect("request capture should lock")
                     .push(request_text);
-                write_response(&mut stream, response_body);
+                write_response(&mut stream, response);
             }
         });
 
@@ -2880,11 +3043,18 @@ mod tests {
         String::from_utf8(buffer).expect("request should be utf-8")
     }
 
-    fn write_response(stream: &mut std::net::TcpStream, body: String) {
+    fn write_response(stream: &mut std::net::TcpStream, response: MockHttpResponse) {
+        let status_text = if response.status_code == 200 {
+            "OK"
+        } else {
+            "ERROR"
+        };
         let raw_response = format!(
-            "HTTP/1.1 200 OK\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
-            body.len(),
-            body
+            "HTTP/1.1 {} {}\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+            response.status_code,
+            status_text,
+            response.body.len(),
+            response.body
         );
         stream
             .write_all(raw_response.as_bytes())