# 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 主链，优先交付一条可验证、可继续扩展的后端边界基线。