1

2026-04-21 19:18:26 +08:00
parent 4372ab5be1
commit 48957311bc
78 changed files with 643 additions and 3801 deletions
--- a/docs/audits/engineering/ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md
+++ b/docs/audits/engineering/ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md
@@ -0,0 +1,117 @@
+# 工程死分支清理执行记录 E（2026-04-21）
+
+更新时间：`2026-04-21`
+
+## 0. 本批次目标
+
+本批次承接批次 D，继续清掉已经退出 RPG 游戏创作主流程、RPG 运行时玩法主流程、平台基本功能主流程的历史壳层。
+
+本批次不处理仍需后端 contract 先收口的对象，例如：
+
+1. `src/services/questDirector.ts`
+2. `src/services/runtimeItemAiDirector.ts`
+3. `src/hooks/rpg-runtime-story/runtimeStoryCoordinator.ts`
+4. `src/services/apiClient.ts`
+
+这些对象仍属于“前端越界逻辑继续后端化”的后续批次，不按无引用文件直接删除。
+
+---
+
+## 1. 删除判定口径
+
+本批只删除满足下面条件之一的对象：
+
+1. 无运行时入口、无脚本入口、无当前路由挂载。
+2. 已有现行正式实现，旧文件只剩 re-export / facade / 兼容命名。
+3. 只被测试验证旧壳自身，且该测试不再服务当前主流程门禁。
+4. 文档已明确该对象处于“后续只允许收缩、不再接新逻辑”的兼容残留状态。
+
+---
+
+## 2. 本批次已处理对象
+
+| 文件 | 判定 | 删除原因 | 替代路径 / 当前真相源 |
+| --- | --- | --- | --- |
+| `server-node/src/routes/rpgCreationAgentRoutes.ts` | 旧命名 re-export | 当前后端正式路由直接使用 `customWorldAgent.ts` | `server-node/src/routes/customWorldAgent.ts` |
+| `server-node/src/routes/rpgWorldGalleryRoutes.ts` | 空路由骨架 | 世界广场实际列表和详情已经进入世界库路由 | `server-node/src/routes/rpg-entry/rpgWorldLibraryRoutes.ts` |
+| `server-node/src/services/RpgAgentOrchestrator.ts` | 旧命名 re-export | 当前正式上下文直接使用 `CustomWorldAgentOrchestrator` | `server-node/src/services/customWorldAgentOrchestrator.ts` |
+| `server-node/src/services/RpgAgentSessionStore.ts` | 旧命名 re-export | 当前正式上下文直接使用 `CustomWorldAgentSessionStore` | `server-node/src/services/customWorldAgentSessionStore.ts` |
+| `server-node/src/services/customWorldWorkSummaryService.ts` | 旧兼容入口 | 测试和路由已改为直接使用 RPG 命名服务 | `server-node/src/services/RpgWorldWorkSummaryService.ts` |
+| `server-node/src/services/customWorldAgentPublishGateService.ts` | 旧发布门禁实现 | 当前 action executor 与作品库发布链已统一走 PublishingService | `server-node/src/services/customWorldAgentPublishingService.ts` |
+| `server-node/src/services/customWorldAgentPublishService.ts` | 旧发布实现 | 当前发布链不再编译旧 legacy result profile | `server-node/src/services/customWorldAgentPublishingService.ts` |
+| `server-node/src/modules/custom-world/runtime-profile/runtimeProfileCompiler.ts` | 旧 facade | runtime profile 已拆到目录模块并由 `index.ts` / `runtimeProfile.ts` 承接 | `server-node/src/modules/custom-world/runtime-profile/index.ts` |
+| `server-node/src/bridges/legacyBuildRuntimeBridge.ts` | 无引用旧桥 | 后端 runtime build / equipment 已直接在正式模块内使用 | `server-node/src/modules/runtime/**` |
+| `server-node/src/bridges/legacyRuntimeItemResolutionBridge.ts` | 旧桥 | runtime item 解析服务一并删除，正式运行时使用 `runtimeItemModule.ts` | `server-node/src/modules/runtime-item/runtimeItemModule.ts` |
+| `server-node/src/modules/runtime-item/runtimeItemResolutionService.ts` | 无正式入口 wrapper | 只被 barrel 和自身测试引用，未挂入 Express 运行时主链 | `server-node/src/modules/runtime-item/runtimeItemModule.ts` |
+| `server-node/src/modules/**/index.ts` | 无引用 barrel | 这些 barrel 没有被当前后端入口消费，反而制造“公共模块入口仍存在”的错觉 | 直接 import 具体正式模块 |
+| `server-node/src/routes/rpg-*/index.ts` | 无引用 barrel | 当前 Express app 直接 import 具体 route 文件 | `server-node/src/app.ts` 中的具体路由 |
+| `server-node/src/repositories/rpg-*/index.ts` | 无引用 barrel | 当前上下文直接 import 具体 repository | `server-node/src/server.ts` 中的具体仓储 |
+| `src/components/DeveloperTeamModal.tsx` | 无入口 UI | 平台主流程没有打开该弹窗的入口 | 无替代 UI，删除历史壳 |
+| `src/components/LazySkillEffectPreview.tsx` | 无入口 lazy 壳 | 正式技能预览直接使用 `SkillEffectPreview` | `src/components/SkillEffectPreview.tsx` |
+| `src/components/npcVisualEditorModel.ts` | 旧 NPC 形象写回模型 | 当前 RPG 创作编辑器使用 `CustomWorldNpcVisualEditor` 与结果页新入口 | `src/components/CustomWorldNpcVisualEditor.tsx`、`src/components/rpg-creation-editor/**` |
+| `src/components/npcVisualEditorPersistence.ts` | 旧 NPC 形象写回持久层 | 只被旧持久化测试引用，正式编辑入口已迁移 | `src/components/rpg-creation-editor/**` |
+| `src/components/rpg-creation-*/index.ts` | 无引用 barrel | 当前入口直接 import 具体 facade 文件，barrel 没有主流程消费 | 直接 import `RpgCreation*` 具体文件 |
+| `src/components/rpg-creation-editor/CustomWorldSceneChapterEditorSection.tsx` | 旧 facade | 当前编辑器 section 直接在 `RpgCreationEntityEditorShared.tsx` 中分发 | `src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx` |
+| `src/data/editorValidation.ts` | 旧预设编辑器校验 | 当前主流程和内容门禁不再调用 | `scripts/validate-overrides.ts`、后端 editor API |
+| `src/editor/shared/EditorNotice.tsx` | 无入口共享 UI | 只被同批删除的 FormFields 使用 | 无替代 UI，删除历史编辑器壳 |
+| `src/editor/shared/FormFields.tsx` | 无入口共享 UI | 旧编辑器共享表单未接主流程 | 当前 RPG 编辑器组件内聚在 `rpg-creation-editor/**` |
+| `src/editor/shared/SectionCard.tsx` | 无入口共享 UI | 旧编辑器卡片未接主流程 | 当前 RPG 编辑器组件内聚在 `rpg-creation-editor/**` |
+| `src/hooks/rpg-runtime-story/npcEncounterActions.ts` | 旧 wrapper | 正式实现已在 `useRpgRuntimeNpcInteraction.ts`，测试已改到正式文件 | `src/hooks/rpg-runtime-story/useRpgRuntimeNpcInteraction.ts` |
+| `src/hooks/rpg-runtime-story/openingAdventure.ts` | 旧前端开局特殊流程 | 开局营地对白已由后端 `RpgRuntimeStoryActionDomain` 和当前 story context 承接 | `server-node/src/modules/rpg-runtime-story/RpgRuntimeStoryActionDomain.ts` |
+| `src/hooks/rpg-runtime-story/storyCampCompanion.ts` | 旧前端营地同伴 helper | 只剩旧开局流程和自身测试引用，正式开局上下文已迁到当前 runtime story 链 | 后端 runtime story action domain 与 `storyContextBuilder.ts` |
+| `src/hooks/rpg-runtime-story/storyRenderingHelpers.ts` | 无入口旧渲染 helper | 当前正式 story presentation 不再 import | `src/hooks/rpg-runtime-story/storyPresentation.ts` |
+| `src/prompts/questPrompts.ts` | 前端 prompt 残留 | Quest prompt 真相已迁到后端 | `server-node/src/prompts/questPrompts.ts` |
+| `src/prompts/runtimeItemPrompts.ts` | 前端 prompt 残留 | Runtime item prompt 真相已迁到后端 | `server-node/src/prompts/runtimeItemPrompts.ts` |
+| `src/services/questPrompt.ts` | 前端 prompt re-export | 只指向同批删除的前端 prompt | `server-node/src/prompts/questPrompts.ts` |
+| `src/services/runtimeItemAiPrompt.ts` | 前端 prompt re-export | 只指向同批删除的前端 prompt | `server-node/src/prompts/runtimeItemPrompts.ts` |
+| `src/services/storyEngine/contentDependencyGraph.ts` | 实验性孤岛 | 只被自身测试引用，没有主流程消费 | 后续如需要重新设计到后端 story graph 服务 |
+
+---
+
+## 3. 同步调整
+
+1. `customWorldAgentPhase2/3/4` 测试改为直接实例化 `RpgWorldWorkSummaryService`。
+2. `customWorldWorkSummaryService.integration.test.ts` 改为直接覆盖 `RpgWorldWorkSummaryService`。
+3. `npcEncounterActions.test.ts` 改为直接覆盖 `useRpgRuntimeNpcInteraction.ts`，不再通过旧 wrapper。
+4. `story_opening_camp_dialogue` 的 function catalog 执行路径改为后端 runtime action domain，不再指向已删除旧前端文件。
+5. NPC function catalog 中 `npc_chat / npc_help / npc_leave / npc_fight / npc_spar / npc_preview_talk` 的 executor 路牌改到现行 `useRpgRuntimeNpcInteraction.ts`。
+
+---
+
+## 4. 本批次暂缓对象
+
+以下对象仍然保留，原因是它们不是“无引用死代码”，而是需要下一轮按 contract 或主链职责迁移：
+
+1. `src/services/questDirector.ts`
+2. `src/services/runtimeItemAiDirector.ts`
+3. `src/services/ai.ts`
+4. `src/data/sceneObservation.ts`
+5. `server-node/ecosystem.config.cjs`
+6. `server-node/src/scripts/syncCustomWorldSavedProfileAssets.ts`
+
+其中 `ecosystem.config.cjs` 被部署脚本直接使用；`sceneObservation.ts` 被内容 smoke 脚本验证；`syncCustomWorldSavedProfileAssets.ts` 是一次性运维脚本，后续要单独按运维脚本治理口径确认是否归档。
+
+---
+
+## 5. 验证口径
+
+本批删除后建议验证：
+
+1. `npm run check:encoding`
+2. `npx tsx --test server-node/src/services/customWorldWorkSummaryService.integration.test.ts`
+3. `npx vitest run src/hooks/rpg-runtime-story/npcEncounterActions.test.ts`
+4. `npm run server-node:build`
+5. `npm run build`
+
+如果 `npm run build` 仍被既有 chunk warning 拦截，需要单独记录为既有门禁问题，不归因到本批删除。
+
+---
+
+## 6. 当前结论
+
+本批次进一步删除了“旧命名入口、旧 facade、旧 prompt 前端镜像、无入口编辑器壳层”这批容易误导后续开发的文件。
+
+后续清理不应继续按“静态无引用”直接推进，而应进入两类工作：
+
+1. 运行时 / 任务 / 物品 / AI 的后端 contract 收口。
+2. RPG 创作编辑器与运行时热点文件的职责拆分。
--- a/docs/audits/engineering/ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md
+++ b/docs/audits/engineering/ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md
@@ -0,0 +1,91 @@
+# 工程死分支清理执行记录 F（2026-04-21）
+
+更新时间：`2026-04-21`
+
+## 0. 本批次目标
+
+本批次承接批次 E 的验证结果，继续处理删除后暴露出的最后一组高置信残留：
+
+1. 已经没有任何代码入口引用的前端任务生成 director。
+2. 只被内容 smoke 牵住、但不再是正式运行时入口的旧观察文案 helper。
+3. 带有固定用户、固定 session、固定 profile 的一次性历史同步脚本。
+4. 清理后暴露出的 function catalog 契约覆盖缺口。
+
+本批次仍然不按文件名直接删除 `legacy` 命名对象。经核对，`server-node/src/bridges/legacyInventoryRuntimeBridge.ts`、`legacyNpcTask6Bridge.ts`、`legacyQuestProgressBridge.ts`、`legacyQuestRuntimeBridge.ts`、`legacyRuntimeItemBridge.ts`、`legacyTreasureRuntimeBridge.ts` 仍被后端战斗、背包、任务、宝藏主链直接引用，不能按历史命名硬删。
+
+---
+
+## 1. 删除判定口径
+
+本批删除对象必须同时满足：
+
+1. 修正 `.js -> .ts` 后端源码解析、前端懒加载入口解析后，仍不可从正式入口到达。
+2. 全仓库代码引用扫描没有正式入口引用。
+3. 如只被 smoke 或测试牵住，先把 smoke / 测试改到当前正式主链，再删除旧对象。
+4. 删除后通过对应门禁验证，没有新增悬空 import。
+
+---
+
+## 2. 本批次已处理对象
+
+| 文件 | 判定 | 删除 / 调整原因 | 替代路径 / 当前真相源 |
+| --- | --- | --- | --- |
+| `src/services/questDirector.ts` | 无代码入口残留 | 正式 quest 生成已由后端 `/api/runtime/quests/generate` 与 `questService.ts` 承接，前端当前没有任何 import | `server-node/src/services/questService.ts`、`server-node/src/modules/quest/runtimeQuestModule.ts` |
+| `src/data/sceneObservation.ts` | 旧观察文案 helper | 只被 `scripts/smoke-content.ts` 引用，正式观察动作已走 `idle_observe_signs` function 与运行时 story continuation | `src/data/functionCatalog/state/idleObserveSigns.ts`、`src/hooks/rpg-runtime-story/storyChoiceContinuation.ts` |
+| `server-node/src/scripts/syncCustomWorldSavedProfileAssets.ts` | 一次性硬编码运维脚本 | 脚本内固定用户、session、profile，只服务历史补丁，没有 CLI 参数和当前运维入口 | 无替代；如未来需要，按参数化运维脚本重新设计 |
+
+---
+
+## 3. 同步调整
+
+1. `scripts/smoke-content.ts` 不再 import 旧 `sceneObservation.ts`，改为通过 `resolveFunctionOption('idle_observe_signs', ...)` 验证当前正式 function 目录。
+2. `packages/shared/src/contracts/rpgRuntimeContracts.test.ts` 不再验证已移除的旧 `story` façade，改为直接验证当前拆分契约。
+3. `src/data/functionCatalog/` 补齐仍在后端运行时契约中的 function 文档：
+   - `battle_attack_basic`
+   - `battle_use_skill`
+   - `npc_chat_quest_offer_view`
+   - `npc_chat_quest_offer_replace`
+   - `npc_chat_quest_offer_abandon`
+4. `battle_attack_basic` 与 `battle_use_skill` 只作为后端契约文档登记，不进入 `STATE_FUNCTION_DEFINITIONS`，避免前端本地候选池生成缺少 `runtimePayload.skillId` 的假技能 option。
+
+---
+
+## 4. 本批次暂缓对象
+
+以下对象经本批复核后继续保留：
+
+1. `server-node/src/services/customWorldAgentRepositoryTestHelpers.ts`
+2. `server-node/src/services/customWorldAgentTestHelpers.ts`
+3. `server-node/src/testFixtures/runtimeCharacter.ts`
+4. `server-node/src/testHttp.ts`
+
+这些文件不属于正式运行时入口，但当前被后端测试、smoke 与路由边界门禁使用。它们不是 RPG 创作 / 运行时玩法主流程代码，但仍是平台基本质量门禁的一部分，不能在“删除冗余业务代码”批次里直接硬删。
+
+另保留：
+
+1. `src/services/runtimeItemAiDirector.ts`
+2. `src/services/ai.ts`
+3. `src/services/apiClient.ts`
+
+这些文件仍被当前主链或前端 SDK 入口引用，后续如继续压缩，必须先完成对应 contract / SDK 拆分，不按无引用规则删除。
+
+---
+
+## 5. 验证结果
+
+本批已通过：
+
+1. `npx vitest run src/data/functionCatalog/functionCatalog.test.ts packages/shared/src/contracts/rpgRuntimeContracts.test.ts`
+2. `npx tsx scripts/smoke-content.ts`
+3. `npm run check:encoding`
+
+并额外确认：
+
+1. 全仓库代码中不再引用 `sceneObservation`、`questDirector`、`syncCustomWorldSavedProfileAssets`。
+2. `buildStateFunctionDefinitions()` 中不会出现 `battle_attack_basic` / `battle_use_skill`，这两个 function 只由后端运行时 option 池下发。
+
+---
+
+## 6. 当前结论
+
+本批次后，静态入口扫描中剩余的高置信“不可达源码”已经收敛为测试辅助、测试夹具和 smoke helper。继续删除前需要先重构测试基础设施或迁移剩余前端 SDK，而不应再按文件名或历史命名直接硬删。
--- a/docs/audits/engineering/README.md
+++ b/docs/audits/engineering/README.md
@@ -4,27 +4,31 @@

 ## 当前推荐入口

-1. [FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md](./FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md)
+1. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md)
+   这一版是第六批落地记录，聚焦删除无入口 `questDirector`、旧观察文案 helper、一次性硬编码同步脚本，并补齐后端运行时 function catalog 契约覆盖。
+2. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md)
+   这一版是第五批落地记录，聚焦旧命名 re-export、空路由骨架、旧发布服务、前端 prompt 镜像与无入口编辑器壳层的物理删除。
+3. [FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md](./FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md)
   这一版是本轮前端越界逻辑专项审计，专门汇总当前仍应继续迁到 Express 后端的运行时、鉴权、生成编排与本地真相残留。
-2. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md)
+4. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md)
   这一版是第四批落地记录，聚焦未接入业务的数据生成产物、测试专用 stub 与对应配置残留出清。
-3. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md)
+5. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md)
   这一版是第三批落地记录，聚焦鉴权真相收口，先移除前端保存自动登录用户名/密码的本地真相，并明确运行时快照前置写入为什么当前还不能硬砍。
-4. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md)
+6. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md)
   这一版是第二批落地记录，聚焦旧主流程壳层、旧 bootstrap 和旧 inventory / forge / equipment flow Hook 的正式出清。
-5. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md)
+7. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md)
   这一版是第一批落地记录，聚焦高置信度小型孤岛、prompt 壳子、stub 和无入口 modal 的首轮清理。
-6. [CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md](./CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md)
+8. [CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md](./CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md)
   这一版是面向当前仓库状态的优化点盘点，适合直接拿来排优先级和拆执行批次。
-7. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)
+9. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)
   这一版是对 `2026-04-19` 基线的当前仓库复核，明确哪些问题已经处理、哪些表述需要纠正、热点又迁移到了哪里。
-8. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md)
+10. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md)
   这一版保留原始问题快照和执行回填，适合回看“为什么会有这轮清理与边界收口”。
-9. [ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md)
+11. [ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md)
   这一版最适合作为当前工程基线，重点从“是否真正绿色”“门禁有没有覆盖真实风险”来判断仓库状态。
-10. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md)
+12. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md)
   适合回看运行时主链路、Story/Combat 边界、分层过渡期问题。
-11. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md)
+13. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md)
   适合看第一轮系统性工程扫描，了解最早的问题基线。

 ## 融合结论
@@ -34,6 +38,8 @@
 - 第二批已经开始清理旧主流程壳层与旧 flow Hook，当前主工程的“现行入口”和“历史入口”边界正在变得更清楚。
 - 第三批已经先完成鉴权真相收口的一段，前端不再保存自动登录用户名/密码；运行时快照链仍需先补后端 contract，再继续往前删。
 - 第四批已经继续收掉未接入业务的数据生成产物、测试专用 stub 与对应脚本/配置残留，主工程里的“假数据主源”进一步减少。
+- 第五批已经继续收掉旧命名 re-export、空路由骨架、旧发布 service、前端 prompt 镜像与无入口编辑器壳层，主工程里的“假入口”和“假 prompt 主源”进一步减少。
+- 第六批已经继续收掉无入口 `questDirector`、旧观察文案 helper、一次性硬编码同步脚本，并修复 function catalog 对后端运行时契约的覆盖缺口。
 - 当前仓库已经完成“旧 dev 插件链路删除、根目录噪音清理、`server-node -> src/**` 反向依赖切断”这批第一阶段任务。
 - 当前如果想直接判断“今天先优化什么”，优先看 `CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md`。
 - 当前的新重点已经进一步收敛到三类：未接线孤岛模块、前端残留的运行时/鉴权真相、热点向 prompt/runtime profile/平台入口壳层迁移。
--- a/docs/experience/AGENT_UI_CHANGELOG.md
+++ b/docs/experience/AGENT_UI_CHANGELOG.md
@@ -163,4 +163,13 @@

 ---

+## 13. 2026-04-21 创作中心失效草稿恢复兜底
+
+- `src/components/rpg-entry/useRpgEntryLibraryDetail.ts` 现在会识别 `custom-world agent session` 的 `404 NOT_FOUND` 读取失败，不再把这类错误直接冒泡成未捕获 Promise。
+- 当用户在创作中心点击“继续创作”命中失效草稿时，前端会主动清空 `customWorldSessionId` 恢复参数，并刷新一次 works 列表，避免刷新页面后反复尝试恢复同一个坏会话。
+- 当前交互已收口成平台内可见提示：用户会停留在创作中心，并看到“这份共创草稿已失效，已为你返回创作中心，请重新开始创作。”，而不是卡在空白工作区或只在控制台看到英文异常。
+- 这次兜底只处理失效会话恢复，不改变正常草稿继续创作、结果页恢复和已发布作品进入世界的主链。
+
+---
+
 _文档目的：交接给下一个 Agent 时，优先读本文件 + `UI_CODING_STANDARD.md`，再改 `uiAssets.ts` / `App.tsx` / `index.css`。_
--- a/docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md
+++ b/docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md
@@ -32,6 +32,14 @@

 ## 基础状态 Function

+- `battle_attack_basic`
+  脚本：`src/data/functionCatalog/state/battleAttackBasic.ts`
+  说明：后端单行为战斗模型中的普通攻击 function。它由后端战斗 option 池下发，前端只透传 functionId，不进入前端本地 `STATE_FUNCTION_DEFINITIONS` 候选池。
+
+- `battle_use_skill`
+  脚本：`src/data/functionCatalog/state/battleUseSkill.ts`
+  说明：后端单行为战斗模型中的技能释放 function。每个技能 option 必须携带 `runtimePayload.skillId`，因此只登记文档和契约，不作为前端本地泛用 state function 生成。
+
 - `battle_all_in_crush`
  脚本：`src/data/functionCatalog/state/battleAllInCrush.ts`
  说明：战斗中的正面强压动作，只在 `battle` 状态且有存活敌人时进入候选池。它会提高伤害与终结/爆发技能权重，同时抬高承伤，适合收头、压血和赌一波换血抢节奏。
@@ -110,6 +118,18 @@
  脚本：`src/data/functionCatalog/npc/npcChat.ts`
  说明：围绕当前话题与 NPC 继续交谈的 function。它会先生成对话正文，再把真正的新选项延迟到 `story_continue_adventure` 之后展示。

+- `npc_chat_quest_offer_view`
+  脚本：`src/data/functionCatalog/npc/npcChatQuestOffer.ts`
+  说明：聊天内待领取委托的查看入口，只查看 pending quest offer，不立即写入正式任务日志。
+
+- `npc_chat_quest_offer_replace`
+  脚本：`src/data/functionCatalog/npc/npcChatQuestOffer.ts`
+  说明：聊天内待领取委托的更换入口，重新走任务生成链替换当前 pending quest offer。
+
+- `npc_chat_quest_offer_abandon`
+  脚本：`src/data/functionCatalog/npc/npcChatQuestOffer.ts`
+  说明：聊天内待领取委托的放弃入口，只清空 pending quest offer，不影响已接任务。
+
 - `npc_gift`
  脚本：`src/data/functionCatalog/npc/npcGift.ts`
  说明：向 NPC 送礼的入口 function。第一次点击通常只打开礼物面板，确认礼物后才结算好感变化并继续剧情。
@@ -186,6 +206,7 @@

 ## 当前实现约定

- `src/data/stateFunctions.ts` 现在只负责基础 state function 的聚合、override 合并、运行时过滤和 option 解析。
+- `src/data/stateFunctions.ts` 现在只负责前端本地基础 state function 的聚合、override 合并、运行时过滤和 option 解析。
+- `battle_attack_basic` / `battle_use_skill` 虽然属于后端运行时契约中的战斗 function，但不进入 `STATE_FUNCTION_DEFINITIONS`。它们由后端 runtime story / combat option 池生成，避免前端本地生成缺少 `runtimePayload` 的假选项。
 - 非 state function 目前仍由各自原有流程模块执行，但它们的 `id`、标题和详细说明已经统一收口到 `functionCatalog/`。
 - 后续新增 function 时，建议先补独立脚本，再把运行时调用接进来，最后同步这份目录文档。
--- a/docs/technical/AGENT_DRAFT_RESULT_ASSET_MERGE_FIX_2026-04-21.md
+++ b/docs/technical/AGENT_DRAFT_RESULT_ASSET_MERGE_FIX_2026-04-21.md
@@ -94,3 +94,26 @@
 1. `legacyResultProfile` 继续长期作为结果页主列表来源风险很高
 2. 只做“按 id 回贴图片字段”在对象集合会漂移的链路里不够稳
 3. 后续如果继续推进后端单一真相源，应优先把结果页对象集合完全改为服务端最新 compile/preview 结果，而不是继续让前端桥接层承担最终裁决
+
+---
+
+## 8. 2026-04-21 补充：新建共创会话 500 根因
+
+后续联调里又发现一条与资产合并无关、但会直接阻断创作入口的后端问题：
+
+1. 点击“创建新 RPG 游戏”时，`POST /api/runtime/custom-world/agent/sessions` 返回 `500`
+2. 表面上前端只看到“服务器内部错误”，实际根因在路由层
+
+本次补查确认：
+
+1. `server-node/src/routes/customWorldAgent.ts` 这组路由内部直接使用 `request.userId!`
+2. 但路由文件本身在 `2026-04-21` 修复前没有挂 `requireJwtAuth(...)`
+3. 结果是 HTTP 请求虽然带了登录 token，但 `request.userId` 并不会被注入
+4. 后端继续拿 `undefined` 作为 `userId` 创建 / 读取 agent session，最终在仓储写库阶段触发 `500`
+
+修复方式：
+
+1. 在 `createCustomWorldAgentRoutes(...)` 顶部统一补上 `router.use(requireJwtAuth(context.config, context.userRepository))`
+2. 让 session 创建、读取、发消息、执行 action、读取 operation / card 详情全部走同一层鉴权注入
+
+这次补丁的意义不是新增功能，而是把 `custom-world agent` 路由和其他 `rpg-entry / rpg-profile / rpg-runtime` 受保护接口重新对齐，避免再出现“路由里依赖 `request.userId`，但入口没挂鉴权”的低层断线问题。