Genarrative/docs/technical/RUNTIME_STORY_BACKEND_BOUNDARY_MIGRATION_2026-04-19.md

Runtime Story 后端边界迁移记录（2026-04-19）

更新时间：2026-04-20

1. 本轮目标

本轮只处理 docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md 中已经明确、且可以无需求漂移落地的两类问题：

1. RuntimeStoryOptionView 的 interaction 语义不能再由前端根据 functionId + currentEncounter 本地重建。
2. src/hooks/story/npcEncounterActions.ts 中 help / leave / fight / spar / quest_turn_in 等运行时动作不能继续在浏览器里保留旧本地结算分支。

本轮没有做以下事情：

1. 没有修改任何功能需求。
2. 没有修改任何业务提示词。
3. 没有扩展新的动作能力面。
4. 没有处理 custom-world 领域规则从 server-node -> src/services/** 反向 import 的剩余问题。

2. 已落地收口

2.1 runtime option interaction 改为后端唯一构建

已完成：

1. server-node/src/modules/story/runtimeSession.ts
   • buildOptionView(...) 直接输出 interaction
   • buildAvailableOptions(...) 直接返回带 interaction 的 runtime option
   • 删除前一版补丁式附加逻辑，避免后续再出现“双份映射”
2. server-node/src/modules/story/storyActionService.ts
   • story option view model 直接透传 option.interaction
3. src/services/runtimeStoryService.ts
   • 前端不再根据 currentEncounter 重建一份 interaction
   • 只消费服务端返回的 option.interaction

这意味着：

1. npc_chat / npc_help / npc_fight / npc_leave / npc_trade / npc_gift / npc_quest_*
2. treasure_secure / treasure_inspect / treasure_leave

这些交互语义以后都以后端 runtime session 为准。

2.2 npcEncounterActions 收缩为前端壳层

已完成：

1. src/hooks/story/npcEncounterActions.ts

   • help
   • leave
   • fight
   • spar
   • quest_accept
   • quest_turn_in

   以上动作已统一改为走 resolveServerRuntimeChoice(...)

2. 删除本轮迁移后已无消费方的本地 helper / import / 常量残留，避免误以为本地仍承担这部分结算职责。

当前前端在这条链路上只保留：

1. 选项点击分发
2. trade / gift / recruit 的 UI modal 打开
3. NPC 对话壳层与流式展示
4. 服务端返回结果的状态落地与 story 刷新

2.3 待接委托正式接取改为后端收口

已完成：

1. server-node/src/modules/quest/questStoryActionService.ts
   • npc_quest_accept 会优先读取服务端快照里 currentStory.npcChatState.pendingQuestOffer.quest
   • 如果当前聊天态里已经存在待接委托，就按这份已展示给玩家的委托正式接取，不再在后端临时重建另一份任务
2. server-node/src/modules/story/storyActionService.ts
   • npc_quest_accept 在存在待接委托聊天态时，会继续输出 displayMode: 'dialogue' 的 current story
   • 会清空 pendingQuestOffer
   • 会恢复既有的三条自由追问建议，避免接任务后 UI 退回普通 story 文本态
3. src/hooks/story/npcEncounterActions.ts
   • acceptPendingNpcQuestOffer() 不再本地直接修改 quests / runtimeStats / storyHistory
   • 现在只负责触发 resolveServerRuntimeChoice(...)，由后端统一落地正式接取结果

这意味着：

1. “NPC 聊天里弹出的待接委托”不再是一份只存在于前端内存里的临时结果
2. 前端不会再一边展示待接委托、一边本地把正式 quest log 写出来
3. 正式接取后的 quest 真相源、聊天态投影与快照持久化统一以后端为准

2.4 NPC 聊天待接委托生成与浏览器 LLM fallback 继续后移

已完成：

1. server-node/src/modules/ai/chatOrchestrator.ts
   • streamNpcChatTurnFromOrchestrator(...) 现在会基于前端提交的 questOfferContext
   • 由后端判断是否应该生成 pendingQuestOffer
   • quest draft 与引导文案 introText 由服务端一并回填到 complete 事件
2. src/services/aiService.ts
   • streamNpcChatTurn(...) 已支持把 questOfferContext 送入后端
3. src/hooks/story/npcEncounterActions.ts
   • NPC 单轮聊天结束后不再本地调用 generateQuestForNpcEncounter(...)
   • 前端改为只消费服务端回填的 pendingQuestOffer + introText
4. src/services/questDirector.ts
   • 浏览器端 quest draft 失败时，不再退回本地 LLM 调用
   • 当前改为直接走 deterministic fallback quest compile
5. src/services/runtimeItemAiDirector.ts
   • 浏览器端 runtime item intent 失败时，不再退回本地 LLM 调用
   • 当前改为直接返回 deterministic fallback intents

这意味着：

1. NPC 聊天里“是否触发待接委托”的判定不再由前端依据 turnCount / affinity / quests 本地重跑
2. 浏览器不再保留 quest draft 与 runtime item intent 的正式 LLM fallback orchestration
3. 前端在这两条链路上继续退化为服务端结果消费层

3. 本轮涉及文件

代码：

1. server-node/src/modules/story/runtimeSession.ts
2. server-node/src/modules/story/storyActionService.ts
3. server-node/src/modules/story/storyActionRoutes.test.ts
4. src/services/runtimeStoryService.ts
5. src/services/runtimeStoryService.test.ts
6. src/hooks/story/npcEncounterActions.ts
7. src/hooks/story/npcEncounterActions.test.ts
8. server-node/src/modules/quest/questStoryActionService.ts
9. server-node/src/modules/ai/chatOrchestrator.ts
10. server-node/src/modules/ai/orchestrator.test.ts
11. src/services/aiService.ts
12. src/services/questDirector.ts
13. src/services/runtimeItemAiDirector.ts

说明：

1. 本轮没有改 prompt 文本。
2. 本轮没有新增或删减 runtime functionId。
3. 本轮只是把既有交互语义和动作结算职责收回到后端。

4. 验证结果

已执行并通过：

1. npm run check:encoding
2. npx vitest run src/services/runtimeStoryService.test.ts src/hooks/story/npcEncounterActions.test.ts
3. npx tsx --test server-node/src/modules/story/runtimeSession.test.ts

新增的防回退验证包括：

1. 前端 runtimeStoryService 会保留并消费服务端返回的 interaction
2. npcEncounterActions 的 help / leave / fight / spar 明确走服务端 resolver
3. npc_quest_turn_in 会把 questId 原样透传到后端
4. 后端 runtimeSession 明确直接构建并透传 NPC option interaction
5. 待接委托正式接取会复用快照中的 pending quest，而不是在接取瞬间重新造一份 quest
6. 待接委托接取后仍保持 NPC 聊天展示态，并清空 pendingQuestOffer
7. NPC chat turn 的 pending quest offer 现在由后端直接产出，前端不再本地二次决定
8. 浏览器端 quest / runtime item 已不再保留直接调用本地 LLM 的 fallback orchestration

补充说明：

1. server-node/src/modules/story/storyActionRoutes.test.ts 已补充路由级 interaction 断言。
2. 2026-04-20 的补充收口改为以 storyActionRoutes.test.ts 直接覆盖待接委托正式接取链路，验证快照输入与快照输出是否都以后端为准。
3. 本轮没有改 prompt 文本，也没有新增函数能力面，只是继续把现有 runtime story 结算权后移。

5. 暂未处理的后续边界项

这轮故意没有继续扩大的点：

1. server-node/src/modules/ai/customWorldOrchestrator.ts 仍直接依赖 src/services/customWorld*.ts
2. server-node/src/services/customWorldAgentFoundationDraftService.ts 仍直接依赖 src/services/customWorld*.ts 与 src/types.ts
3. pending quest offer 的 replace / abandon 仍由前端 UI 壳层协调
4. 浏览历史、本地快照真相源、custom-world 领域规则共享化仍需后续阶段继续推进

原因：

1. 这些点会牵涉 shared contract 抽取与较大范围重组
2. 若与本轮 runtime story 收口混做，容易把“边界迁移”误做成“需求改造”

因此本轮把范围锁在 runtime story 主链，优先交付一条可验证、可继续扩展的后端边界基线。