Genarrative/docs/technical/RUNTIME_NPC_CHAT_LLM_MIGRATION_2026-04-25.md

Runtime NPC 聊天 LLM 迁移设计（2026-04-25）

背景

当前 server-rs/crates/api-server/src/runtime_chat.rs 已承接 POST /api/runtime/chat/npc/turn/stream，但只返回确定性兜底文本。实际游戏聊天里，NPC 回复、下一轮建议、好感变化和限轮收束都应该沿用旧 Node 服务器的 LLM 编排。

迁移源

本轮只参考旧 Node 已冻结实现，不恢复 server-node 服务，也不把前端切回 Express：

1. server-node/src/prompts/chatPromptBuilders.ts
2. server-node/src/modules/ai/chatOrchestrator.ts
3. server-node/src/services/chatService.ts
4. packages/shared/src/contracts/rpgRuntimeChat.ts

提示词常量必须原样迁移，禁止改写：

1. NPC_CHAT_TURN_REPLY_SYSTEM_PROMPT
2. NPC_CHAT_TURN_SUGGESTION_SYSTEM_PROMPT

本轮落地边界

1. Rust api-server 在同一路由内优先调用 platform-llm。
2. LLM 回复使用旧 Node 的 buildNpcChatTurnReplyPrompt(...) 等价构造逻辑，保持输入字段和中文上下文组织一致。
3. LLM 建议使用旧 Node 的 buildNpcChatTurnSuggestionPrompt(...) 等价构造逻辑，解析规则保持“最多 3 行、去掉编号/项目符号”。
4. 好感变化沿用旧 Node 的关键词打分规则：
   • 正向与负向关键词计分。
   • 首聊无明显关键词时给 +1。
   • 单轮变化限制在 [-3, 3]。
5. chatDirective.forceExitAfterTurn / closingMode=foreshadow_close 时不生成建议，返回空数组，并在 complete.chatDirective.forceExit 中显式告知前端退出。
6. LLM 未配置或失败时继续返回后端兜底 SSE，保证相遇和点击聊天链路不断。
7. 在 Node 已完成平台账号鉴权并通过内部密钥转发到 Rust API 的链路中，/api/runtime/chat/ 必须纳入 Rust 内部转发鉴权白名单；否则 NPC 主动开场会在进入 runtime_chat handler 前被 401 拒绝，前端只能收到“NPC 聊天续写失败”。

暂不落地

1. 暂不迁移 maybeBuildPendingNpcQuestOffer(...) 的完整 quest 生成链。
2. 暂不新增 SpacetimeDB reducer；本路由属于 Axum 侧 LLM 编排，SpacetimeDB reducer 仍保持确定性。
3. 暂不扩展前端 UI 文案。

工程落点

1. 新增 server-rs/crates/api-server/src/runtime_chat_prompt.rs
   • 承载旧 Node 提示词常量。
   • 承载 NPC 聊天 prompt builder 与轻量 JSON 读取 helper。
2. 修改 server-rs/crates/api-server/src/runtime_chat.rs
   • 注入 State<AppState>。
   • 优先 LlmClient.stream_text(...) 生成 reply_delta。
   • 再调用 request_text(...) 生成建议。
   • 计算 affinityDelta / affinityText / chatDirective 后输出 complete。
   • SSE stream 返回给 Axum 时要求 'static，进入 stream 的玩家输入必须先转成 owned String，不能把 handler 栈上的 &str 借入 stream。
3. 修改 server-rs/crates/api-server/src/auth.rs
   • allows_internal_forwarded_auth(...) 允许 /api/runtime/chat/，与 big-fish、puzzle 的内部转发鉴权策略保持一致。
   • 单测覆盖 /api/runtime/chat/npc/turn/stream，防止后续新增 runtime 路由时再次遗漏内部转发白名单。
4. 修改 server-rs/crates/api-server/src/main.rs
   • 注册 runtime_chat_prompt 模块。

验收

1. cargo fmt -p api-server
2. cargo check -p api-server
3. node scripts/check-encoding.mjs docs/technical/RUNTIME_NPC_CHAT_LLM_MIGRATION_2026-04-25.md server-rs/crates/api-server/src/auth.rs server-rs/crates/api-server/src/runtime_chat.rs server-rs/crates/api-server/src/runtime_chat_prompt.rs server-rs/crates/api-server/src/main.rs