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 对话、推理战斗文本请求都通过同一辅助函数设置搜索开关，避免漏接。

docs/technical/CUSTOM_WORLD_DRAFT_SCENE_TASK_AND_ACT_EVENT_FIELDS_2026-04-25.md

@@ -0,0 +1,57 @@
+# 自定义世界草稿场景幕事件与任务字段落地设计（2026-04-25）
+
+## 背景
+
+自定义世界 Agent 生成第一版草稿时，已经会为 `sceneChapterBlueprints[*].acts[*]` 生成逐幕背景图描述，并为场景写入基础描述、出场角色等信息。后续运行时需要更稳定的章节任务上下文，因此草稿阶段必须同时生成：
+
+1. 每一幕的对面角色。
+2. 每一幕的事件描述。
+3. 每个场景的场景任务描述。
+
+## 字段契约
+
+### SceneActBlueprint
+
+新增字段：
+
+- `oppositeNpcId: string`
+  - 当前幕“对面的角色”，优先使用该场景 `sceneNpcNames` / `encounterNpcIds` 的第一个角色。
+  - 若当前场景暂未绑定角色，使用空字符串，不在草稿合成阶段伪造角色 ID。
+- `eventDescription: string`
+  - 描述当前幕正在发生的事件。
+  - 必须强绑定 `oppositeNpcId` / `primaryNpcId` 所指角色，写清该角色的行动、阻碍、试探、求助或冲突。
+  - 默认生成兜底规则：`第N幕中，玩家在当前场景遭遇/处理与某角色直接相关的事件，并推动当前场景问题升级或转向。`
+
+兼容字段：
+
+- `primaryNpcId` 继续保留，默认等于 `oppositeNpcId`，避免旧运行时代码读取不到主角色。
+- `encounterNpcIds` 继续保留，至少承载当前场景可出场角色名称/ID。
+
+### SceneChapterBlueprint
+
+新增字段：
+
+- `sceneTaskDescription: string`
+  - 当前场景的核心任务描述。
+  - 文本会作为游戏中首次进入某个场景生成章节任务的关键上下文。
+  - 必须结合场景描述、场景入口钩子、出场角色与 3 幕事件，说明玩家首次进入该场景时要完成什么。
+
+## 生成链路
+
+1. `api-server` 的 `custom_world_foundation_draft.rs` 是第一版草稿的真实生成入口。
+2. LLM 提示词需要要求：
+   - `camp.sceneTaskDescription` 默认生成开局场景核心任务。
+   - `landmarks[*].sceneTaskDescription` 默认生成关键场景核心任务。
+   - `actEventDescriptions` 恰好 3 条，对应每一幕事件。
+3. 后端合成 `sceneChapterBlueprints` 时把这些源字段落到：
+   - `sceneChapterBlueprints[*].sceneTaskDescription`
+   - `sceneChapterBlueprints[*].acts[*].oppositeNpcId`
+   - `sceneChapterBlueprints[*].acts[*].eventDescription`
+4. 若 LLM 遗漏字段，归一化阶段用场景描述、入口钩子、角色名单生成中文默认值，保证草稿阶段字段非空。
+5. 前端类型与归一化逻辑必须允许读取这些字段，旧草稿缺字段时仍自动补默认值。
+
+## 非目标
+
+- 不新增 UI 说明文案。
+- 不迁移或兼容 `server-node`。
+- 不改变现有幕背景图生成队列与资产写回链路。