1

2026-04-20 09:54:17 +08:00
parent 67c584b4df
commit 50759f3c1e
159 changed files with 16938 additions and 16925 deletions
--- a/docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
+++ b/docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
@@ -854,7 +854,8 @@ generatedAnimationOverrides?: Partial<Record<AnimationState, string>>;

 ## 10.3 本地 API 层

-当前项目已经有 `scripts/dev-server/localApiPlugins.ts` 这种本地 API 插件机制，应该复用。
+自 `2026-04-19` 起，旧 `scripts/dev-server/localApiPlugins.ts` 已从仓库删除。  
+当前角色视觉与动画相关 `/api/*` 能力应统一落到 `server-node/src/modules/assets/**` 与 `server-node/src/modules/ai/**`，不再复用旧 Vite 本地插件链路。

 建议新增：

--- a/docs/technical/ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md
+++ b/docs/technical/ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md
@@ -82,7 +82,8 @@

 ### 2.3 本地 API 插件里已经有 DashScope 接入样板

-`scripts/dev-server/localApiPlugins.ts` 里已经接了自定义世界场景图：
+本文撰写时，旧 `scripts/dev-server/localApiPlugins.ts` 里已经接了自定义世界场景图。  
+截至 `2026-04-19`，该文件已从仓库删除，对应样板能力应改为参考 `server-node/src/modules/assets/**` 与 `server-node/src/modules/ai/**`：

 - 默认 DashScope base URL 已经存在
 - 已经有异步任务创建、轮询、下载、落盘、写 manifest 的完整样板
@@ -480,7 +481,7 @@

 - 最少改 UI
 - 最快复用当前 `CharacterAssetPanel`
- 最容易复用 `localApiPlugins.ts` 里现有 DashScope 异步任务模式
+- 最容易复用现已迁入 `server-node` 的 DashScope 异步任务模式

 ## 9.2 第二轮

@@ -641,5 +642,6 @@
 - `src/components/preset-editor/characterAssetStudioPersistence.ts`
 - `src/routing/appRoutes.tsx`
 - `src/services/ai.ts`
- `scripts/dev-server/localApiPlugins.ts`
+- `server-node/src/modules/assets/**`
+- `server-node/src/modules/ai/**`
 - `docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md`
--- a/docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md
+++ b/docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md
@@ -73,12 +73,12 @@

 ## 5. 旧工具链隔离状态

-`scripts/dev-server/**` 中的旧 Vite 本地插件已经不再由 `vite.config.ts` 注入，也不再作为当前开发入口使用。
+自 `2026-04-19` 起，`scripts/dev-server/**` 中的旧 Vite 本地插件实现代码已经从仓库删除，也不再作为当前开发入口使用。

-旧文件保留用途：
+当前保留状态：

- 作为历史迁移参考。
- 对照旧 DashScope 调用与文件写入逻辑。
+- `scripts/dev-server/` 目录只保留迁移说明 README。
+- 旧链路的历史背景由 `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md` 等审计文档承接。

 新增编辑器或资产能力时，应优先写入：

@@ -103,4 +103,4 @@
 - 前端编辑器组件已通过统一 SDK 或资源 ID 访问编辑器 API。
 - Vite 已代理 `/api/editor` 与 `/api/assets` 到 Node 后端。
 - 写接口已经有环境门禁。
- 旧 Vite 本地插件不再是当前工具链入口。
+- 旧 Vite 本地插件代码已删除，不再保留并行实现。
--- a/docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md
+++ b/docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md
@@ -16,7 +16,7 @@

 当前不再使用：

- Vite 本地 API 插件 `scripts/dev-server/` 作为当前接口入口
+- 已删除的旧 Vite 本地 API 插件链路 `scripts/dev-server/*.ts`

 ## 2. 技术栈

@@ -162,6 +162,11 @@ JWT 现状：
 - `POST /api/runtime/items/runtime-intent`
 - `POST /api/runtime/quests/generate`

+补充说明（`2026-04-19`）：
+
+- `POST /api/custom-world/scene-image` 现在支持前端仅提交 `profile + landmark + userPrompt` 上下文，由后端统一补齐场景图 prompt 与默认 negative prompt。
+- runtime story option 的 `interaction` 元数据现在由后端随 option 一并返回，前端不再本地按 `functionId` 重建 NPC / treasure 交互语义。
+
 编辑器工具：

 - `GET /api/editor/catalog/items`
@@ -198,7 +203,11 @@ Story：

 Custom World：

- Node 后端直接复用前端现有多阶段生成编排
+- Node 后端当前已自持 `server-node/src/modules/custom-world/**` 运行时模块
+- 已承接 `creator intent` 归一化、`anchorPack / lockState` 推导、framework normalize、runtime profile compile
+- `customWorldOrchestrator` 与 `customWorldAgentFoundationDraftService` 已不再运行时 import 前端 `src/services/customWorld*.ts` 与 `src/types.js`
+- `server-node/src/prompts/customWorldPrompts.ts` 已承接 foundation draft 与 scene image 使用的 custom world prompt source
+- 上述 prompt 迁移只改变源码归属位置，没有改动提示词正文
 - 当前保留 `session + answers + SSE progress/result/error` 协议
 - 前端已支持接收真实阶段进度对象

@@ -238,4 +247,4 @@ Vite 当前只负责代理，不再提供本地 API 插件。

 全部转发到 Node 后端。

-旧 `scripts/dev-server/**` 文件仅保留为迁移参考，不再由 `vite.config.ts` 注入。
+`scripts/dev-server/` 目录现仅保留 README 作为迁移说明，旧本地 API 实现代码已于 `2026-04-19` 删除。
--- a/docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md
+++ b/docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md
@@ -2,12 +2,17 @@

 ## 1. 这次调整解决什么问题

-此前后端提示词分散在多个业务模块里：
+此前提示词分散在多个后端、前端和工具文件里：

 - `server-node/src/modules/ai/**`
 - `server-node/src/modules/quest/**`
 - `server-node/src/modules/runtime-item/**`
 - `server-node/src/services/customWorld*.ts`
+- `server-node/src/services/eightAnchorPromptBuilder.ts`
+- `server-node/src/modules/assets/characterAssetRoutes.ts`
+- `src/services/**`
+- `src/tools/qwenSpriteSheetToolModel.ts`
+- `src/components/**`

 问题主要有三类：

@@ -15,23 +20,40 @@
 2. 同一类 prompt 缺少集中入口，排查系统 prompt / user prompt / repair prompt 成本高。
 3. 老桥接层、测试和新业务链路同时依赖时，迁移成本高，容易出现导出断裂。

-这次收口目标不是“重写全部 AI 链路”，而是先把当前后端主链 prompt 收到单独目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。
+这次收口目标不是“重写全部 AI 链路”，而是把当前正式业务 prompt 主源收到独立目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。

 ## 2. 新目录

-本轮新增目录：
+本轮落地后的目录：

 ```text
+packages/shared/src/prompts/
+└─ qwenSprite.ts
+
 server-node/src/prompts/
+├─ characterAssetPrompts.ts
 ├─ chatPromptBuilders.ts
 ├─ customWorldAgentPrompts.ts
 ├─ customWorldEntityPrompts.ts
 ├─ customWorldOrchestratorPrompts.ts
 ├─ customWorldSceneNpcPrompts.ts
+├─ eightAnchorPrompts.ts
 ├─ questPrompts.ts
 ├─ runtimeItemPrompts.ts
 ├─ storyOrchestratorPrompts.ts
 └─ storyPromptBuilders.ts
+
+src/prompts/
+├─ characterChatPrompts.ts
+├─ customWorldEntityActionPrompts.ts
+├─ customWorldOrchestratorPrompts.ts
+├─ customWorldPrompts.ts
+├─ customWorldRolePromptDefaults.ts
+├─ questPrompts.ts
+├─ qwenSpriteSheetToolPrompts.ts
+├─ runtimeItemPrompts.ts
+├─ storyOrchestratorPrompts.ts
+└─ storyPromptBuilders.ts
 ```

 当前职责划分：
@@ -54,6 +76,20 @@ server-node/src/prompts/
  - 世界编辑器角色 / 场景实体生成 prompt
 - `customWorldSceneNpcPrompts.ts`
  - 世界编辑器场景 NPC 生成 prompt
+- `characterAssetPrompts.ts`
+  - 角色主图 / 动作试片 / 角色关联场景 prompt
+- `eightAnchorPrompts.ts`
+  - 八锚点状态推断、模式规则与正式单轮共创 prompt
+- `src/prompts/customWorldPrompts.ts`
+  - 自定义世界分阶段生成 prompt 与场景背景图 prompt
+- `src/prompts/qwenSpriteSheetToolPrompts.ts`
+  - 精灵图工具主词 / 分镜词 / 修帧词 / 负面词
+- `src/prompts/customWorldRolePromptDefaults.ts`
+  - 角色资产工作台默认 prompt 种子
+- `src/prompts/customWorldEntityActionPrompts.ts`
+  - 编辑器技能动作 prompt
+- `packages/shared/src/prompts/qwenSprite.ts`
+  - 共享资产层的基础角色 prompt 模板

 ## 3. 落地规则

@@ -82,12 +118,18 @@ server-node/src/prompts/

 ### 3.3 兼容层保留旧导出

-本轮对已有纯 prompt builder 文件采取了兼容迁移：
+本轮对已有纯 prompt builder 文件采取了兼容迁移，旧路径保留为薄 re-export：

 - `server-node/src/modules/ai/chatPromptBuilders.ts`
 - `server-node/src/modules/ai/storyPromptBuilders.ts`
-
-旧路径现在作为薄 re-export 保留，避免测试、桥接层和旧引用一次性全部断掉。
+- `server-node/src/services/eightAnchorPromptBuilder.ts`
+- `src/services/prompt.ts`
+- `src/services/characterChatPrompt.ts`
+- `src/services/questPrompt.ts`
+- `src/services/runtimeItemAiPrompt.ts`
+- `src/tools/qwenSpriteSheetToolModel.ts`
+- `src/components/asset-studio/customWorldRolePromptDefaults.ts`
+- `packages/shared/src/assets/qwenSprite.ts`

 对于 `runtimeQuestModule.ts`、`runtimeItemModule.ts` 这类被桥接层直接引用的模块，本轮保留原导出名，通过 re-export 指向新 prompt 文件，保证兼容性。

@@ -95,11 +137,12 @@ server-node/src/prompts/

 新增提示词时按下面顺序处理：

-1. 先判断是否属于已有领域。
-2. 如果属于已有领域，优先补到对应 `server-node/src/prompts/*.ts`。
-3. 如果是新领域，再新增一个独立 prompt 脚本文件。
-4. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
-5. 至少补一条该 prompt 的调用链测试或现有测试断言。
+1. 先判断属于后端、前端/编辑器还是共享工具层。
+2. 后端正式业务优先补到 `server-node/src/prompts/*.ts`。
+3. 前端/编辑器 prompt 优先补到 `src/prompts/*.ts`。
+4. 可复用的共享资产 prompt 优先补到 `packages/shared/src/prompts/*.ts`。
+5. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
+6. 至少补一条该 prompt 的调用链测试或现有测试断言。

 建议命名：

@@ -108,7 +151,7 @@ server-node/src/prompts/
 - user prompt：`buildXXXPrompt`
 - 纯文本装配：`buildXXXPromptText`

-## 5. 本轮范围与剩余事项
+## 5. 本轮范围与当前状态

 本轮已经收口：

@@ -119,16 +162,17 @@ server-node/src/prompts/
 - Custom World 主编排
 - Custom World Agent 草稿增补
 - Custom World 编辑器角色 / 场景 / 场景 NPC 生成
+- Character Asset
+- Eight Anchor
+- Scene Image
+- 前端剧情 / 私聊 / 任务 / 物品 prompt 兼容层
+- 编辑器与工具链 prompt 种子

-本轮尚未完全收口的内联 prompt 聚集区：
+当前状态：

- `server-node/src/modules/assets/characterAssetRoutes.ts`
- `server-node/src/services/eightAnchorPromptBuilder.ts`
-
-这两块后续继续沿用同一规则：
-
- 先抽出 prompt 文本与 builder
- 再让业务文件只保留参数整理与调用
+- 正式业务 prompt 主源已经集中到 prompt 目录。
+- 旧 `services/`、`tools/`、`components/` 下保留的相关文件主要是兼容层或调用方。
+- 当前没有再发现需要优先继续抽离的大块业务 prompt 正文。

 ## 6. 验证方式

@@ -138,6 +182,9 @@ server-node/src/prompts/
 - `npm run server-node:test`
 - `npm --prefix server-node run build`

-说明：
+本轮实测结果：

- 当前仓库里 `server-node/src/db.test.ts` 仍有一条与新增迁移版本号相关的既有失败，不属于本次 prompt 目录改造引入的问题。
+- `npm run check:encoding` 通过
+- `npm --prefix server-node run build` 通过
+- `npm run build` 通过
+- `npm run server-node:test` 143 项全部通过
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -4,6 +4,7 @@

 ## 文档列表

+- [REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md](./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md)：落实工程清理审计第一阶段后的仓库噪音清理范围、忽略规则闭合点与后续约束。
 - [PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md](./PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md)：后端提示词收口到 `server-node/src/prompts/` 的目录方案、兼容策略与后续新增规则。
 - [NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md](./NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md)：当前 Node 运行时后端的技术栈、入口、鉴权、存储与接口知识图谱。
 - [EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md](./EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md)：Express 后端当前 contract 冻结版本、热点文件编辑规则与集成窗口清单。
--- a/docs/technical/REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md
+++ b/docs/technical/REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md
@@ -0,0 +1,53 @@
+# 仓库噪音清理基线（2026-04-19）
+
+更新时间：`2026-04-19`
+
+## 1. 背景
+
+本次清理落实以下审计结论：
+
+- `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md`
+
+目标只覆盖审计文档推荐执行顺序中的第一阶段，也就是先把仓库噪音产物和本地检查残留从主工程面清掉，不在这一轮同时推进前后端边界迁移或无入口模块归档。
+
+## 2. 本次已执行的清理
+
+本轮已从仓库中移除以下高置信度噪音产物：
+
+- 根目录的 `.codex-*` 日志、`.preview.*` 输出、`tmp_*` 扫描文本与 HTML、`npc-editor-*` 截图和调试文件、`temp-write-check.txt`
+- 根目录 `temp-build-goal-check/` 大体量检查产物目录
+- `scripts/__pycache__/` Python 缓存目录与 `.pyc` 文件
+- `.codex-logs/` 中遗留的旧日志与 restore backup 文件
+
+这些文件都不属于正式运行时代码、PRD、设计稿或生产资源，继续保留只会污染根目录视野、拖慢扫描和 review，并增加误判成本。
+
+## 3. 规则闭合
+
+为避免相同问题反复回流，本次同步补齐了两层规则：
+
+1. `.gitignore`
+   - 新增 `/.codex-logs/`
+   - 新增 `*.py[cod]`
+   - 保持 `.preview.*`、`tmp_*`、`tmp/`、`npc-editor-*`、`temp-write-check.txt`、`temp-build-goal-check/`、`**/__pycache__/` 为忽略项
+2. `.eslintrc.cjs`
+   - 保持 `temp-build-goal-check/**`
+   - 保持 `.preview.*`、`tmp_*`、`tmp/**`、`npc-editor-*`、`temp-write-check.txt`
+   - 保持 `**/__pycache__/**`
+
+这样 Git 与 ESLint 对临时产物的忽略口径保持一致，不会再出现某个目录虽然被 Git 忽略，但仍被 lint 扫进去的情况。
+
+## 4. 后续约束
+
+- 以后所有临时扫描结果、调试截图、HTML 导出、一次性日志，不要直接落在仓库根目录。
+- 如需保留本地临时产物，统一放到本地忽略目录，例如 `tmp/` 或 `.codex-logs/`。
+- `temp-build-goal-check/` 仍视为本地检查产物，不作为主工程目录的一部分长期保留。
+- Python 脚本执行后产生的 `__pycache__` 不应进入仓库。
+
+## 5. 本轮未处理范围
+
+以下内容仍按审计原计划留待后续阶段处理：
+
+- `scripts/dev-server/localApiPlugins.ts` 及旧 Vite 本地 API 链路的归档
+- 无运行时入口或仅测试引用的孤岛模块处置
+- 前后端双份真相收口与 `server-node -> src/**` 反向依赖治理
+- 巨型热点文件拆分
--- a/docs/technical/RUNTIME_STORY_BACKEND_BOUNDARY_MIGRATION_2026-04-19.md
+++ b/docs/technical/RUNTIME_STORY_BACKEND_BOUNDARY_MIGRATION_2026-04-19.md
@@ -0,0 +1,174 @@
+# 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 主链，优先交付一条可验证、可继续扩展的后端边界基线。
--- a/docs/technical/SERVER_DEPLOYMENT_AND_CORS_TECHNICAL_SOLUTION_2026-04-05.md
+++ b/docs/technical/SERVER_DEPLOYMENT_AND_CORS_TECHNICAL_SOLUTION_2026-04-05.md
@@ -42,7 +42,8 @@

 ### 2.2 当前 API 层还只是开发期能力

-这些接口现在主要由 [scripts/dev-server/localApiPlugins.ts](/E:/Repos/Genarrative/scripts/dev-server/localApiPlugins.ts) 挂在 Vite dev/preview 服务器里。
+本文撰写时，这些接口主要由旧 `scripts/dev-server/localApiPlugins.ts` 挂在 Vite dev/preview 服务器里。  
+截至 `2026-04-19`，这条旧链路已经从仓库删除，当前统一由 `server-node` 承接。

 这在本地开发阶段很方便，但生产环境存在几个明显问题：

@@ -500,7 +501,14 @@ flowchart LR

 ## 11.1 第一优先级：把 Vite 里的 API 能力抽出来

-当前 [scripts/dev-server/localApiPlugins.ts](/E:/Repos/Genarrative/scripts/dev-server/localApiPlugins.ts) 里的能力，建议分三类迁移：
+该迁移建议已完成，原 `scripts/dev-server/localApiPlugins.ts` 已于 `2026-04-19` 删除。  
+对应能力现统一收口到以下正式模块：
+
+- `server-node/src/modules/editor/**`
+- `server-node/src/modules/assets/**`
+- `server-node/src/modules/ai/**`
+
+原旧链路中的能力，可按以下三类理解其迁移归属：

 ### A. 运行时代理接口