1

docs/technical/API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md

@@ -95,3 +95,28 @@ Rust 首版返回：
 4. `Upstream(status=429)` -> `429 TOO_MANY_REQUESTS`
 5. 其他 `Upstream` -> `502 BAD_GATEWAY`
 6. `stream=true` 首版直接返回 `501 NOT_IMPLEMENTED`
+
+## 8. 角色扮演模型联网搜索补充（2026-04-25）
+
+### 8.1 目标
+
+角色扮演运行时调用文本模型生成剧情正文、NPC 对话、战斗演出文本时，需要默认允许模型使用上游联网搜索能力，提升现实题材、时代背景、地名器物、文化细节的准确度。
+
+### 8.2 落地范围
+
+1. `platform-llm` 的 `LlmTextRequest` 增加 `enable_web_search` 布尔开关，默认 `false`，避免影响普通平台代理和非剧情调用。
+2. `api-server` 配置增加 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED` / `RPG_LLM_WEB_SEARCH_ENABLED`，默认 `true`。
+3. 仅 `runtime_story` 兼容链路中的角色扮演剧情文本请求按配置开启联网搜索。
+4. `/api/llm/chat/completions` 通用代理不默认开启联网搜索，避免外部调用方在无感情况下产生额外成本或不可预期内容来源。
+
+### 8.3 上游请求口径
+
+1. 当前默认文本模型走火山方舟 OpenAI 兼容 Chat Completions 路由。
+2. 联网搜索开启时，请求体追加 `web_search_options: {}`；关闭时不序列化该字段。
+3. 若后续迁移到 Responses API 或更换 provider，由 `platform-llm` 统一收口字段映射，业务层仍只使用 `enable_web_search` 语义开关。
+
+### 8.4 验收
+
+1. `platform-llm` 单测能捕获开启搜索时上游 JSON 包含 `web_search_options`。
+2. `api-server` 配置单测能验证角色扮演搜索开关默认开启、环境变量可关闭。
+3. 角色扮演剧情、NPC 对话、推理战斗文本请求都通过同一辅助函数设置搜索开关，避免漏接。