init with react+axum+spacetimedb

docs/reference/BUSINESS_PROMPT_INVENTORY_2026-04-19.md

@@ -0,0 +1,181 @@
+# 业务提示词清单（2026-04-19）
+
+## 1. 目标
+
+这份清单用于回答两个问题：
+
+- 目前业务里到底有哪些提示词还在被使用。
+- 哪些提示词已经收口到独立目录，哪些仍散落在前后端与工具链里。
+
+本次统计范围：
+
+- `server-node/src/**`
+- `src/**`
+- `packages/shared/src/**`
+
+本次“提示词”统计口径包含：
+
+- system prompt
+- user prompt builder
+- repair prompt
+- negative prompt
+- 图像 / 动画生成 prompt
+- 编辑器里会直接喂给模型的默认 prompt 种子
+
+本次不计入：
+
+- 单纯转发 prompt 的接口入参校验
+- 普通剧情文案、UI 文案、剧情预设文本
+- 纯测试断言文件
+
+## 2. 当前结论
+
+截至 2026-04-19 本轮收口完成后，业务 prompt 主源已经集中到 3 个目录：
+
+1. `server-node/src/prompts/`
+2. `src/prompts/`
+3. `packages/shared/src/prompts/`
+
+当前业务模块、路由、服务层里的旧 prompt 文件大多已经退化成两类：
+
+- prompt 调用方
+- 薄 re-export 兼容层
+
+目前没有再发现“正式业务 prompt 正文仍长期内联在主流程文件里”的大块散点；剩余位于非 prompt 目录的相关文件，主要是兼容层、测试文件或普通调用方。
+
+## 3. 当前 Prompt 目录清单
+
+### 3.1 后端
+
+| 文件 | 业务域 | 关键导出 |
+| --- | --- | --- |
+| `server-node/src/prompts/storyPromptBuilders.ts` | 主剧情推进 | `SYSTEM_PROMPT`、`buildUserPrompt` |
+| `server-node/src/prompts/storyOrchestratorPrompts.ts` | 剧情语言修复 | `STORY_LANGUAGE_REPAIR_SYSTEM_PROMPT`、`buildStoryLanguageRepairPrompt` |
+| `server-node/src/prompts/chatPromptBuilders.ts` | 角色私聊 / NPC 对话 / 招募 | `CHARACTER_PANEL_CHAT_*`、`NPC_CHAT_*`、多个 `build*Prompt` |
+| `server-node/src/prompts/questPrompts.ts` | 任务意图 | `QUEST_INTENT_SYSTEM_PROMPT`、`buildQuestIntentPrompt` |
+| `server-node/src/prompts/runtimeItemPrompts.ts` | 运行时物品意图 | `RUNTIME_ITEM_INTENT_SYSTEM_PROMPT`、`buildRuntimeItemIntentPromptText` |
+| `server-node/src/prompts/customWorldOrchestratorPrompts.ts` | 自定义世界主编排 | `CUSTOM_WORLD_GENERATION_JSON_ONLY_SYSTEM_PROMPT`、`CUSTOM_WORLD_JSON_REPAIR_SYSTEM_PROMPT`、`buildCustomWorldProfilePrompt`、`buildCustomWorldProfileRepairPrompt` |
+| `server-node/src/prompts/customWorldAgentPrompts.ts` | 世界草稿增补 | `FOUNDATION_JSON_ONLY_SYSTEM_PROMPT`、`FOUNDATION_JSON_REPAIR_SYSTEM_PROMPT`、多个扩展 prompt |
+| `server-node/src/prompts/customWorldEntityPrompts.ts` | 世界编辑器实体生成 | `CUSTOM_WORLD_ENTITY_GENERATOR_SYSTEM_PROMPT`、`buildPlayablePrompt`、`buildStoryPrompt`、`buildLandmarkPrompt` |
+| `server-node/src/prompts/customWorldSceneNpcPrompts.ts` | 世界编辑器场景 NPC | `CUSTOM_WORLD_SCENE_NPC_SYSTEM_PROMPT`、`buildCustomWorldSceneNpcPrompt` |
+| `server-node/src/prompts/eightAnchorPrompts.ts` | 八锚点共创 | `BASE_SYSTEM_PROMPT`、`GLOBAL_HARD_RULES`、`MODE_RULES`、`USER_SIGNAL_RULES`、`buildPromptDynamicStateInferencePrompt`、`buildEightAnchorSingleTurnPrompt` |
+| `server-node/src/prompts/characterAssetPrompts.ts` | 角色形象 / 动作资产生成 | `buildNpcVisualPrompt`、`buildNpcAnimationPrompt`、`buildArkCharacterAnimationPrompt`、`buildImageSequencePrompt`、`buildNpcVisualNegativePrompt` |
+
+### 3.2 前端
+
+| 文件 | 业务域 | 关键导出 |
+| --- | --- | --- |
+| `src/prompts/storyPromptBuilders.ts` | 剧情推进 | `SYSTEM_PROMPT`、`buildUserPrompt` |
+| `src/prompts/characterChatPrompts.ts` | 角色面板私聊 | `CHARACTER_PANEL_CHAT_*`、多个 `build*Prompt` |
+| `src/prompts/questPrompts.ts` | 前端任务意图兜底 | `QUEST_INTENT_SYSTEM_PROMPT`、`buildQuestIntentPrompt` |
+| `src/prompts/runtimeItemPrompts.ts` | 前端物品意图兜底 | `RUNTIME_ITEM_INTENT_SYSTEM_PROMPT`、`buildRuntimeItemIntentPrompt` |
+| `src/prompts/customWorldPrompts.ts` | 自定义世界分阶段生成 + 场景背景图 | 多个 `buildCustomWorld*Prompt`、`DEFAULT_CUSTOM_WORLD_SCENE_IMAGE_NEGATIVE_PROMPT` |
+| `src/prompts/customWorldOrchestratorPrompts.ts` | 世界 JSON 修复 / JSON only | `CUSTOM_WORLD_JSON_REPAIR_SYSTEM_PROMPT`、`CUSTOM_WORLD_GENERATION_JSON_ONLY_SYSTEM_PROMPT` |
+| `src/prompts/storyOrchestratorPrompts.ts` | 剧情中文修复 | `STORY_LANGUAGE_REPAIR_SYSTEM_PROMPT` |
+| `src/prompts/customWorldRolePromptDefaults.ts` | 角色资产工作台默认词唯一主源 | `buildDefaultRolePromptBundle` |
+| `src/prompts/customWorldEntityActionPrompts.ts` | 编辑器技能动作词 | `buildSkillActionPrompt` |
+
+### 3.3 共享层
+
+| 文件 | 业务域 | 关键导出 |
+| --- | --- | --- |
+| `packages/shared/src/prompts/qwenSprite.ts` | 共享像素角色主 prompt 模板 | `QWEN_SPRITE_ACTION_TEMPLATES`、`buildMasterPrompt`、`buildVideoActionPrompt`、`getActionTemplateById` |
+
+## 4. 兼容层与调用层
+
+为了避免一次性打断旧引用，当前保留了若干兼容层：
+
+- `src/services/prompt.ts`
+- `src/services/characterChatPrompt.ts`
+- `src/services/questPrompt.ts`
+- `src/services/runtimeItemAiPrompt.ts`
+- `server-node/src/services/eightAnchorPromptBuilder.ts`
+- `src/components/asset-studio/customWorldRolePromptDefaults.ts`
+- `packages/shared/src/assets/qwenSprite.ts`
+
+这些文件当前职责是：
+
+- 维持旧路径可用
+- re-export 到新的 prompt 目录
+
+它们不再是 prompt 正文主源。
+
+## 5. AI 角色形象生成当前来源
+
+这部分是你点名要求补齐的重点，现在已经收口为：
+
+| 文件 | 角色 | 当前定位 |
+| --- | --- | --- |
+| `server-node/src/prompts/characterAssetPrompts.ts` | 正式角色资产生成 prompt | 后端角色主图、动作试片、角色场景词主源 |
+| `packages/shared/src/prompts/qwenSprite.ts` | 共享角色主 prompt 模板 | 共享给后端资产链使用的基础模板 |
+| `src/prompts/customWorldRolePromptDefaults.ts` | 工作台默认词种子 | 角色视觉词、动画词、场景词默认值 |
+| `src/prompts/customWorldEntityActionPrompts.ts` | 编辑器动作词 | 技能动作描述 prompt builder |
+
+当前调用关系：
+
+- `server-node/src/modules/assets/characterAssetRoutes.ts` 调用 `server-node/src/prompts/characterAssetPrompts.ts`
+- `src/components/CustomWorldRoleAssetStudioModal.tsx` 通过兼容层消费 `src/prompts/customWorldRolePromptDefaults.ts`
+- `src/components/CustomWorldEntityEditorModal.tsx` 直接调用 `src/prompts/customWorldEntityActionPrompts.ts`
+
+## 6. AI 场景背景生成当前来源
+
+场景背景图 prompt 现在已经从业务流程文件里抽出，统一主源是：
+
+| 文件 | 角色 | 当前定位 |
+| --- | --- | --- |
+| `src/prompts/customWorldPrompts.ts` | 场景背景图 prompt 主源 | `buildCustomWorldSceneImagePrompt`、`DEFAULT_CUSTOM_WORLD_SCENE_IMAGE_NEGATIVE_PROMPT` |
+| `src/services/ai.ts` | 前端编排调用方 | 组装请求并调用同一份 prompt builder |
+| `server-node/src/services/sceneImageService.ts` | 后端执行器调用方 | 在服务端用同一份 prompt builder 生成 prompt，再请求上游模型 |
+
+这条链的关键变化是：
+
+- 不再让 `src/services/customWorld.ts` 承担场景图 prompt 正文主源
+- 前后端场景图生成改为共用 `src/prompts/customWorldPrompts.ts`
+
+## 7. 本轮完成的原散点收口
+
+本轮已经完成的原散点包括：
+
+- `server-node/src/modules/assets/characterAssetRoutes.ts` 中的角色资产 prompt
+- `server-node/src/services/eightAnchorPromptBuilder.ts` 中的八锚点 prompt
+- `src/services/customWorld.ts` 中的自定义世界分阶段 prompt 与场景背景图 prompt
+- `src/services/ai.ts` 中的世界修复 / 语言修复 / JSON only system prompt
+- `src/services/prompt.ts`、`characterChatPrompt.ts`、`questPrompt.ts`、`runtimeItemAiPrompt.ts` 这批前端 prompt 脚本
+- `src/components/asset-studio/customWorldRolePromptDefaults.ts`、`src/components/CustomWorldEntityEditorModal.tsx` 里的工具 / 编辑器 prompt 散点
+
+## 8. 当前仍在非 Prompt 目录中的相关文件
+
+仍在非 prompt 目录中的相关文件，当前主要是：
+
+- 调用方
+- 兼容层
+- 测试
+
+因此现在的工程状态已经从“散点查找”变成“目录集中 + 兼容过渡”。
+
+## 9. 验证结果
+
+本轮收口后已验证：
+
+- `npm run check:encoding`
+- `npm --prefix server-node run build`
+- `npm run build`
+- `npm run server-node:test`
+
+结果：
+
+- 编码检查通过
+- 前端构建通过
+- 后端构建通过
+- `server-node` 测试 143 项全部通过
+
+## 10. 本次盘点后的判断
+
+截至 2026-04-19，本仓库的业务 prompt 已经基本完成目录化管理。
+
+当前更准确的结论是：
+
+- 后端正式业务 prompt 主源集中在 `server-node/src/prompts/`
+- 前端与编辑器 prompt 主源集中在 `src/prompts/`
+- 共享资产 prompt 主源集中在 `packages/shared/src/prompts/`
+- 旧服务路径、旧工具路径仍保留为兼容层，但不再承担 prompt 正文维护职责

docs/reference/CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md

@@ -0,0 +1,398 @@
+# 自定义世界依赖的模板设定清单
+
+更新时间：`2026-04-08`
+
+## 0. 这份清单回答什么
+
+这份文档只回答一个问题：
+
+**当前仓库里，自定义世界仍然依赖哪些“模板世界设定”。**
+
+这里的“模板世界设定”不是指玩家还能进入的 `武侠 / 仙侠` 预设世界流程，而是指：
+
+1. 自定义世界在生成时仍借用哪些模板锚点。
+2. 自定义世界在运行时仍复用哪些模板 schema、词库、怪物池、角色模板、图片参考池。
+3. 哪些引用是“必须保留”，否则会直接伤到自定义世界。
+4. 哪些引用只是编辑器 / 审计 / 测试残留，不属于自定义世界主链硬依赖。
+
+一句话结论先说：
+
+**当前主流程虽然已经不再让玩家进入武侠 / 仙侠预设世界，但自定义世界底层仍明确依赖“模板世界锚点层”。**
+
+---
+
+## 1. 依赖总览
+
+自定义世界当前仍依赖的模板设定，主要分成 7 类：
+
+1. 模板世界锚点类型
+2. 主题判定与规则回退
+3. 属性 schema 与术语体系
+4. 角色模板与技能骨架
+5. 场景图参考池与营地图像逻辑
+6. 怪物 / 敌对实体模板池
+7. 叙事 ThemePack 与生成 prompt 兼容字段
+
+除此之外，还有一类是：
+
+8. 编辑器 / 审计 / 测试中的残留模板引用
+
+这类不一定属于自定义世界正式运行时硬依赖，但当前仓库里仍然存在。
+
+---
+
+## 2. 核心硬依赖
+
+## 2.1 模板世界锚点类型
+
+这是最底层、也是目前最不能直接删的部分。
+
+相关文件：
+
+- `src/types/core.ts`
+- `src/types/customWorld.ts`
+- `src/services/customWorld.ts`
+- `src/data/customWorldLibrary.ts`
+
+当前依赖点：
+
+1. `WorldType.WUXIA / WorldType.XIANXIA / WorldType.CUSTOM`
+   - 自定义世界虽然运行时是 `CUSTOM`，但其模板锚点仍通过 `WUXIA / XIANXIA` 表达。
+
+2. `WorldTemplateType = Exclude<WorldType, WorldType.CUSTOM>`
+   - 这就是“自定义世界挂靠哪个模板锚”的类型定义。
+
+3. `CustomWorldProfile.templateWorldType`
+   - 当前自定义世界 profile 里明确保存这个字段。
+   - 它是兼容字段，但目前仍被多个系统直接消费。
+
+4. `buildCustomWorldFrameworkPrompt(...)`
+   - 生成框架 prompt 仍要求模型输出：
+     - `"templateWorldType": "WUXIA|XIANXIA"`
+
+5. `customWorldLibrary.normalizeProfile(...)`
+   - 本地读取自定义世界时，也会把 `templateWorldType` 归一化到：
+     - `WUXIA`
+     - `XIANXIA`
+
+结论：
+
+**如果直接删掉 `WUXIA / XIANXIA / WorldTemplateType / templateWorldType` 这层，自定义世界的生成、存档归一化和多处运行时回退都会直接断。**
+
+---
+
+## 2.2 主题判定与规则回退
+
+相关文件：
+
+- `src/services/customWorldTheme.ts`
+- `src/data/customWorldRuntime.ts`
+- `src/services/storyEngine/themePack.ts`
+
+当前依赖点：
+
+1. `detectCustomWorldThemeMode(profile)`
+   - 先把自定义世界识别成：
+     - `martial`
+     - `arcane`
+     - `machina`
+     - `tide`
+     - `rift`
+     - `mythic`
+
+2. `resolveCustomWorldAnchorWorldType(profile)`
+   - 再把主题模式压回模板锚点：
+     - `arcane -> XIANXIA`
+     - 其它默认回到 `WUXIA`
+
+3. `resolveRuleWorldType(worldType, customWorldProfile)`
+   - 这是当前运行时非常关键的桥接函数。
+   - 当 `worldType === CUSTOM` 时，它会把规则世界解析成模板锚点。
+   - 如果没有 profile，还会默认回退到 `WUXIA`。
+
+4. `buildThemePackFromWorldProfile(profile)`
+   - 自定义世界最终的 `ThemePack` 并不是纯空中生成。
+   - 它是从预设的主题包底板开始，再用自定义世界自己的词汇补进去。
+
+结论：
+
+**自定义世界现在不是完全脱离模板世界独立运行，而是“先判定自己的主题模式，再回落到模板锚点做规则支撑”。**
+
+---
+
+## 2.3 属性 schema 与术语体系
+
+相关文件：
+
+- `src/data/worldAttributeSchemas.ts`
+- `src/services/attributeSchemaGenerator.ts`
+- `src/services/customWorldPresentation.ts`
+- `src/data/economy.ts`
+
+当前依赖点：
+
+1. `PRESET_WORLD_ATTRIBUTE_SCHEMAS`
+   - 当前仓库里有两套预设属性 schema：
+     - 武侠：`江湖六脉`
+     - 仙侠：`灵界六轴`
+
+2. `getPresetWorldAttributeSchema(...)`
+   - 多个地方仍然用它作为生成自定义世界 schema 的参考底板。
+
+3. `generateWorldAttributeSchema(...)`
+   - 自定义世界自己的 attribute schema 虽然是生成的，
+   - 但内部会参考预设世界 schema 的槽位结构和 fallback 逻辑。
+
+4. `getAttributeLabelsForWorld(...) / getResourceLabelsForWorld(...)`
+   - 如果当前没有显式自定义 world presentation，会按 `WUXIA / XIANXIA` 走回退术语。
+
+5. `getCurrencyName(...) / getInitialPlayerCurrency(...)`
+   - 经济层仍按模板世界决定初始货币命名和初始数量。
+
+结论：
+
+**自定义世界现在虽然有自己的 presentation 和 attribute schema，但模板世界仍然是它们的 fallback 和参考骨架。**
+
+---
+
+## 2.4 角色模板与技能骨架
+
+相关文件：
+
+- `src/data/characterPresets.ts`
+
+当前依赖点：
+
+1. `PRESET_CHARACTERS`
+   - 自定义世界的可玩角色 / 场景角色运行时形态，是从现有预设角色模板变体化出来的。
+
+2. `pickCustomWorldRoleTemplateCharacter(...)`
+   - 会从 `PRESET_CHARACTERS` 里挑一个模板角色作为骨架。
+
+3. `buildCustomWorldRoleCharacter(...)`
+   - 会把自定义世界角色内容覆盖到模板角色上：
+     - 名字
+     - 背景
+     - 描述
+     - 技能文案
+     - 外观
+     - 等等
+
+4. `buildCustomWorldSkillVariant(...)`
+   - 自定义世界角色技能的数值和命名，也是从模板技能定义变体生成出来的。
+
+5. `adventureOpenings`
+   - 当前实现里，自定义世界角色 opening 同时写入：
+     - `WUXIA`
+     - `XIANXIA`
+     - `CUSTOM`
+   - 说明角色开局结构仍沿用模板世界的旧接口习惯。
+
+6. `getCharacterHomeSceneId / getCharacterNpcSceneIds`
+   - 对 `CUSTOM` 路径已经优先走自定义世界自己的 landmark 映射；
+   - 但非 CUSTOM 路径仍大量依赖模板世界的基础场景绑定表。
+
+结论：
+
+**自定义世界角色并不是从零独立建模，而是“自定义内容 + 预设角色模板骨架”的组合。**
+
+---
+
+## 2.5 场景图参考池与营地图像逻辑
+
+相关文件：
+
+- `src/data/customWorldVisuals.ts`
+- `src/services/customWorldCamp.ts`
+
+当前依赖点：
+
+1. `WUXIA_SCENE_IMAGE_REFERENCES`
+2. `XIANXIA_SCENE_IMAGE_REFERENCES`
+3. `WORLD_SCENE_IMAGE_REFERENCES`
+
+当前自定义世界场景图不是纯随机抽图，而是：
+
+1. 先确定模板锚点世界
+2. 再从对应模板世界的场景参考词池里匹配：
+   - 场景名称
+   - 关键词
+   - 图片参考
+
+具体依赖：
+
+1. `collectWorldSceneImagePool(worldType)`
+   - 按模板世界从背景包里抽参考池。
+
+2. `buildSceneReferencePool(worldType)`
+   - 用武侠 / 仙侠各自的场景参考名和关键词构造图像匹配池。
+
+3. `getDefaultCustomWorldSceneImage(...)`
+   - 自定义世界 landmark / camp / 场景默认图，会基于模板世界参考池挑选。
+
+4. `resolveCustomWorldCampSceneImage(profile)`
+   - 开局归处场景图也依赖 `templateWorldType` 和主题判定。
+
+结论：
+
+**当前自定义世界的场景视觉虽然是独立输出，但“默认图像匹配逻辑”仍然是挂在武侠 / 仙侠两套参考池上的。**
+
+---
+
+## 2.6 怪物 / 敌对实体模板池
+
+相关文件：
+
+- `src/data/customWorldNpcMonsters.ts`
+- `src/data/hostileNpcPresets.ts`
+- `src/data/hostileNpcs.ts`
+- `src/data/scenePresets.ts`
+
+当前依赖点：
+
+1. `resolveCustomWorldNpcMonsterPreset(...)`
+   - 自定义世界中带敌意的 NPC / 怪物，会从模板怪物池里找最接近的 preset。
+
+2. `getMonsterPresetPool(worldType?)`
+   - 如果传了 worldType，就取对应模板世界的怪物池。
+   - 如果没传，就把武侠和仙侠怪物池拼起来一起选。
+
+3. `resolveRuleWorldType(...)`
+   - `hostileNpcPresets.ts` 和 `hostileNpcs.ts` 在处理 `CUSTOM` 时，会先解析到模板锚点，再决定取哪个怪物 preset / schema。
+
+4. `getMonsterPresetsByWorld(...) / getHostileNpcPresetById(...)`
+   - 自定义世界的运行时怪物表现，目前仍然依赖这套模板怪物 preset 查询接口。
+
+结论：
+
+**自定义世界当前没有完全独立的怪物体系，仍然是基于武侠 / 仙侠预设怪物池做匹配和包装。**
+
+---
+
+## 2.7 叙事 ThemePack 与 prompt 兼容字段
+
+相关文件：
+
+- `src/services/customWorld.ts`
+- `src/services/storyEngine/themePack.ts`
+- `src/services/ai.ts`
+
+当前依赖点：
+
+1. 自定义世界框架 prompt 仍强制要求 `templateWorldType`
+2. `normalizeCustomWorldGenerationFramework(...)`
+   - 会把模型输出的模板世界字段规范化
+3. `buildThemePackFromWorldProfile(...)`
+   - 会以预设主题包为底，再混入自定义世界词汇
+4. `ai.ts` 里某些 fallback 逻辑仍根据 `templateWorldType` 决定主题包回退
+
+结论：
+
+**自定义世界的 AI 生成链条目前明确假设“世界框架里存在模板锚点字段”。**
+
+---
+
+## 3. 运行时硬依赖 vs 非运行时残留
+
+## 3.1 自定义世界正式运行时硬依赖
+
+这些目前不能轻易删：
+
+1. `WorldType.WUXIA / WorldType.XIANXIA / WorldTemplateType`
+2. `CustomWorldProfile.templateWorldType`
+3. `detectCustomWorldThemeMode / resolveCustomWorldAnchorWorldType / resolveRuleWorldType`
+4. `PRESET_WORLD_ATTRIBUTE_SCHEMAS / getPresetWorldAttributeSchema`
+5. `PRESET_CHARACTERS` 作为自定义角色模板骨架
+6. 武侠 / 仙侠场景图参考池
+7. 武侠 / 仙侠怪物 preset 池
+8. `buildThemePackFromWorldProfile` 的模板底板
+9. `customWorld.ts` 里生成框架 prompt 的 `templateWorldType` 字段约束
+
+## 3.2 不是主流程硬依赖，但仓库里仍存在的残留引用
+
+这些更多是编辑器 / 工具 / 审计 / 测试引用：
+
+1. 预设编辑器
+   - `preset-editor/*`
+
+2. 一些开发工具页
+   - 例如 `ItemCatalogEditor.tsx`
+   - `StateFunctionEditor.tsx`
+
+3. 审计 / 报告工具
+   - `storyAuditReport.ts`
+
+4. 各类基于武侠 / 仙侠的测试
+
+5. 一些 UI 图标与世界按钮贴图
+   - 例如 `uiAssets.ts` 里的图标键位仍保留
+
+这些不一定影响当前玩家主流程，但如果目标是“代码库级彻底清理”，它们也需要后续处理。
+
+---
+
+## 4. 当前最不能动的边界
+
+如果前提是：
+
+**不要动素材和自定义世界的任何设定。**
+
+那么当前最不能直接删除的是：
+
+1. `templateWorldType`
+2. `WorldTemplateType`
+3. `resolveRuleWorldType(...)`
+4. `detectCustomWorldThemeMode(...)`
+5. `resolveCustomWorldAnchorWorldType(...)`
+6. `PRESET_WORLD_ATTRIBUTE_SCHEMAS`
+7. `PRESET_CHARACTERS`
+8. `customWorldVisuals.ts` 里的模板场景参考池
+9. `customWorldNpcMonsters.ts` 对模板怪物池的映射
+10. `themePack.ts` 的模板底板
+
+原因很简单：
+
+**这些不是“预设世界可玩入口”，而是自定义世界当前仍在使用的模板支撑层。**
+
+---
+
+## 5. 可以安全理解为“已从玩家主流程移除”的部分
+
+目前已经可以视作从正式玩家流程移除的，是：
+
+1. 世界选择页里的武侠 / 仙侠入口
+2. 主流程的世界选择 API
+3. 继续游戏入口中的武侠 / 仙侠旧存档
+
+但这不等于：
+
+- 代码库内部已经完全不再依赖模板世界
+
+这两件事要分开看。
+
+---
+
+## 6. 最后结论
+
+当前仓库里，自定义世界对模板设定的依赖，本质上是：
+
+**“不再复用预设世界的玩家入口，但仍然复用预设世界的模板支撑层。”**
+
+最准确的理解是：
+
+1. 玩家已经不能直接进入武侠 / 仙侠预设世界
+2. 但自定义世界仍借用武侠 / 仙侠作为：
+   - 模板锚点
+   - 规则回退
+   - 属性 schema 参考
+   - 角色模板骨架
+   - 场景图参考池
+   - 怪物模板池
+   - ThemePack 底板
+
+所以如果后续要继续“深度清理”，正确顺序不是直接删光 `WUXIA / XIANXIA`，而应该是：
+
+1. 先识别哪些是主流程入口，哪些是模板支撑层
+2. 再决定是否要把自定义世界从“模板依赖型”重构成“完全自足型”
+
+在那一步没做完之前，模板支撑层仍然是自定义世界当前可用性的真实依赖。

docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md

@@ -0,0 +1,212 @@
+# Function 独立脚本目录（2026-04-04）
+
+## 目标
+
+这次整理把运行时所有核心 `functionId` 统一收敛到 `src/data/functionCatalog/` 目录下：
+
+- `state/`：基础状态 function，每个 function 一个独立脚本，`src/data/stateFunctions.ts` 只负责聚合、覆盖和运行时过滤。
+- `npc/`：NPC 交互 function 的独立说明脚本。
+- `treasure/`：宝藏交互 function 的独立说明脚本。
+- `flow/`：流程控制型 function 的独立说明脚本。
+- `panel/`：背包 / 装备 / 锻造等面板动作 function 的独立说明脚本。
+
+每个脚本都包含：
+
+- 脚本顶部的中文注释，说明定位、触发时机和执行意图。
+- 导出的 function 元数据，统一记录 `id`、标题、详细描述、执行方式和结果。
+- 对基础 state function 额外导出正式运行时 definition，供 `stateFunctions.ts` 聚合。
+- 对流程控制 / NPC 分流类 function，额外导出运行时 helper，例如：
+  - `buildContinueAdventureOption`
+  - `buildCampTravelHomeOption`
+  - `buildNpcPreviewTalkOption`
+  - `buildNpcTradeModalState`
+  - `buildNpcGiftModalState`
+  - `buildNpcRecruitModalState`
+    这些 helper 已经在实际运行时被调用，不再只是文档描述。
+
+## 目录入口
+
+- 统一索引：`src/data/functionCatalog/index.ts`
+- 基础状态聚合：`src/data/stateFunctions.ts`
+- 文档类型定义：`src/data/functionCatalog/types.ts`
+
+## 基础状态 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` 状态且有存活敌人时进入候选池。它会提高伤害与终结/爆发技能权重，同时抬高承伤，适合收头、压血和赌一波换血抢节奏。
+
+- `battle_guard_break`
+  脚本：`src/data/functionCatalog/state/battleGuardBreak.ts`
+  说明：围绕破架和打断敌方节奏的重击 function。它强调“砸开敌人架势”，在保持较高伤害的同时略降反击压力，适合对付正在招架或露出结构性破绽的敌人。
+
+- `battle_probe_pressure`
+  脚本：`src/data/functionCatalog/state/battleProbePressure.ts`
+  说明：稳扎稳打的试探压制动作。它把回合塑造成持续施压与信息试探，偏向 `steady` 技能，适合低蓝、观望或不想冒进的战斗阶段。
+
+- `battle_feint_step`
+  脚本：`src/data/functionCatalog/state/battleFeintStep.ts`
+  说明：通过虚晃、变线和抢身位制造切入窗口的机动 function。它提高机动技能权重并降低承伤，适合塑造灵巧、安全的近身切入节奏。
+
+- `battle_recover_breath`
+  脚本：`src/data/functionCatalog/state/battleRecoverBreath.ts`
+  说明：战斗中的保命和回气动作。它负责回血、回蓝和推进冷却轮转，优先在低血低蓝时提权，用来把高压局面拉回可控节奏。
+
+- `battle_finisher_window`
+  脚本：`src/data/functionCatalog/state/battleFinisherWindow.ts`
+  说明：针对敌方破绽和残局血线的终结 function。它大幅提高终结和爆发倾向，适合在敌人残血、明显失衡或已经露出空档时直接收口。
+
+- `battle_escape_breakout`
+  脚本：`src/data/functionCatalog/state/battleEscapeBreakout.ts`
+  说明：从当前战斗中脱身的逃跑 function。它不追求输出，而是驱动逃跑时长、拉开距离和追兵滞后参数，适合保命、撤离和切掉当前战斗。
+
+- `idle_explore_forward`
+  脚本：`src/data/functionCatalog/state/idleExploreForward.ts`
+  说明：空闲状态下最核心的推进 function。它表示继续深入当前场景，允许下一步真正生成角色、怪物、宝藏或危险，是默认的主探索入口。
+
+- `idle_travel_next_scene`
+  脚本：`src/data/functionCatalog/state/idleTravelNextScene.ts`
+  说明：从当前地点切换到相邻场景的地图流转 function。它通过 `sceneShift: 1` 把探索重心从“继续挖当前场景”改成“前往下一处地点重新开始遭遇”。
+
+- `idle_rest_focus`
+  脚本：`src/data/functionCatalog/state/idleRestFocus.ts`
+  说明：非战斗状态下的原地调息 function。它不推进遭遇，只负责给玩家一个稳定的回血回蓝缓冲回合，适合战后休整或资源回收。
+
+- `idle_observe_signs`
+  脚本：`src/data/functionCatalog/state/idleObserveSigns.ts`
+  说明：围绕侦察和判断的空闲 function。它要求本轮先输出可延续的观察结果，而不是立刻推进遭遇，适合摸清附近异动和前方风险。
+
+- `idle_follow_clue`
+  脚本：`src/data/functionCatalog/state/idleFollowClue.ts`
+  说明：循着脚印、声音或痕迹继续逼近目标的保留 function。它目前仍保留在源码定义层，但运行时会在聚合阶段被过滤，属于停用中但仍需记录的 function。
+
+- `idle_call_out`
+  脚本：`src/data/functionCatalog/state/idleCallOut.ts`
+  说明：主动出声试探的空闲 function。它把探索从被动观察切成主动打破寂静，适合把暗处角色、怪物或潜伏动静直接逼到台前。
+
+## NPC 交互 Function
+
+- `npc_preview_talk`
+  脚本：`src/data/functionCatalog/npc/npcPreviewTalk.ts`
+  说明：把前探预览切到正式 NPC 互动层的入口 function。第一次点击主要完成遭遇切换，不是立刻结算完整聊天。
+
+- `npc_trade`
+  脚本：`src/data/functionCatalog/npc/npcTrade.ts`
+  说明：与 NPC 交易的入口 function。点击后通常先打开交易 modal，确认买卖后才真正把结果写回主故事。
+
+- `npc_fight`
+  脚本：`src/data/functionCatalog/npc/npcFight.ts`
+  说明：与眼前 NPC 正面开战的 function。它会把交互态切到 NPC 战斗模式，并在战后结算掉落、关系和任务推进。
+
+- `npc_spar`
+  脚本：`src/data/functionCatalog/npc/npcSpar.ts`
+  说明：与眼前 NPC 进行点到为止切磋的 function。它复用战斗骨架，但目标是关系推进，不是击杀或掠夺。
+
+- `npc_help`
+  脚本：`src/data/functionCatalog/npc/npcHelp.ts`
+  说明：向 NPC 寻求补给、回复或支援的 function。奖励由本地规则稳定计算，避免帮助收益被模型临场漂移。
+
+- `npc_chat`
+  脚本：`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。第一次点击通常只打开礼物面板，确认礼物后才结算好感变化并继续剧情。
+
+- `npc_recruit`
+  脚本：`src/data/functionCatalog/npc/npcRecruit.ts`
+  说明：邀请 NPC 入队的招募 function。若队伍已满会先进入替换确认流程；若满足条件且队伍未满，可直接进入招募对话和入队结算。
+
+- `npc_quest_accept`
+  脚本：`src/data/functionCatalog/npc/npcQuestAccept.ts`
+  说明：正式接下 NPC 委托的 function。它把本地生成的任务写入 quest log，并让剧情承接“玩家已经答应处理这件事”。
+
+- `npc_quest_turn_in`
+  脚本：`src/data/functionCatalog/npc/npcQuestTurnIn.ts`
+  说明：向 NPC 交付已完成委托的 function。它负责领奖、任务状态收尾与交付剧情反馈。
+
+- `npc_leave`
+  脚本：`src/data/functionCatalog/npc/npcLeave.ts`
+  说明：结束当前 NPC 互动并回到探索态的 function。它是正常离场出口，避免玩家必须通过战斗或继续聊天才能离开当前 encounter。
+
+## 宝藏交互 Function
+
+- `treasure_secure`
+  脚本：`src/data/functionCatalog/treasure/treasureSecure.ts`
+  说明：直接收取宝藏的 function。它优先把主要战利品拿到手，适合玩家不想再花回合排查机关时使用。
+
+- `treasure_inspect`
+  脚本：`src/data/functionCatalog/treasure/treasureInspect.ts`
+  说明：先检查机关和线索再收取宝藏的 function。它通常会带来更完整的收益、恢复或额外线索，但叙事上更谨慎、更耗一步。
+
+- `treasure_leave`
+  脚本：`src/data/functionCatalog/treasure/treasureLeave.ts`
+  说明：暂时不碰宝藏、只记住位置和异常的 function。适合资源不足、风险过高或暂时不想打断当前节奏时使用。
+
+## 流程控制 Function
+
+- `story_continue_adventure`
+  脚本：`src/data/functionCatalog/flow/storyContinueAdventure.ts`
+  说明：用于承接延迟展示的 `deferredOptions`。它通常出现在 `npc_chat` 之后，点击时更多是本地恢复后续选项，而不是再次请求新剧情。
+
+- `camp_travel_home_scene`
+  脚本：`src/data/functionCatalog/flow/campTravelHomeScene.ts`
+  说明：营地开场或同伴交流结束后，正式前往角色主场景的流程项。它负责定制化场景迁移和状态清理，不属于普通 state function。
+
+- `story_opening_camp_dialogue`
+  脚本：`src/data/functionCatalog/flow/storyOpeningCampDialogue.ts`
+  说明：驱动营地开场 4 到 6 行对白的特殊流程项。它会让 prompt 进入开场对白模式，而不是走普通探索推进模板。
+
+## 面板动作 Function
+
+- `inventory_use`
+  脚本：`src/data/functionCatalog/panel/inventoryUse.ts`
+  说明：在背包面板里使用药品、灵力物或 build buff 物品的 function。它先由本地规则结算资源变化，再把结果记入故事历史。
+
+- `equipment_equip`
+  脚本：`src/data/functionCatalog/panel/equipmentEquip.ts`
+  说明：在装备面板中把背包物品穿戴到对应槽位的 function。它会同时处理替换旧装备、背包回收和属性重算。
+
+- `equipment_unequip`
+  脚本：`src/data/functionCatalog/panel/equipmentUnequip.ts`
+  说明：从装备槽位卸下物品的 function。它确保卸装结果由本地规则严格处理，不会破坏背包数量和 loadout 一致性。
+
+- `forge_craft`
+  脚本：`src/data/functionCatalog/panel/forgeCraft.ts`
+  说明：在锻造面板中执行配方制作的 function。它负责扣除材料和货币、产出新物品，并把制作结果写入故事历史。
+
+- `forge_dismantle`
+  脚本：`src/data/functionCatalog/panel/forgeDismantle.ts`
+  说明：在锻造面板中拆解物品回收材料的 function。拆解产出由本地锻造规则控制，避免与物品设计脱节。
+
+- `forge_reforge`
+  脚本：`src/data/functionCatalog/panel/forgeReforge.ts`
+  说明：在锻造面板中重铸现有物品的 function。它负责货币消耗、生成新结果与历史记录，适合承接装备再随机化或再塑形。
+
+## 当前实现约定
+
+- `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 时，建议先补独立脚本，再把运行时调用接进来，最后同步这份目录文档。

docs/reference/README.md

@@ -0,0 +1,14 @@
+# 参考目录
+
+## 当前入口
+
+- [BUSINESS_PROMPT_INVENTORY_2026-04-19.md](./BUSINESS_PROMPT_INVENTORY_2026-04-19.md)：业务中现存提示词的总清单，覆盖后端主链、前端遗留、自定义世界、角色形象生成、场景背景生成与工具链 prompt。
+- [FUNCTION_SCRIPT_CATALOG_2026-04-04.md](./FUNCTION_SCRIPT_CATALOG_2026-04-04.md)：Function 独立脚本目录与分类速查。
+- [TASK_GENERATION_TRACE_2026-04-08.md](./TASK_GENERATION_TRACE_2026-04-08.md)：任务描述、达成条件与奖励生成链路梳理。
+- [CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md](./CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md)：自定义世界当前仍依赖哪些模板世界设定的清单。
+
+## 使用建议
+
+- 需要快速定位 Function 脚本，而不是阅读长篇方案时，优先看这里。
+- 需要判断“武侠 / 仙侠模板层”哪些还能删、哪些不能删时，优先看自定义世界模板依赖清单。
+- 如果要评估 Function 分层是否合理，再配合 `docs/audits/FUNCTION_DESIGN_AUDIT_2026-04-03.md` 一起看。

docs/reference/TASK_GENERATION_TRACE_2026-04-08.md

@@ -0,0 +1,248 @@
+# 任务生成链路与简化建议
+
+更新时间：`2026-04-08`
+
+## 0. 简化版结论
+
+推荐把任务系统收敛成一条主链：
+
+1. `npcInteractions.ts`
+   - 只负责判断“现在是否适合接任务”，不再提前本地造整份任务预览。
+2. `npcEncounterActions.ts`
+   - 玩家真正点击“接下委托”时，才调用 AI 任务导演。
+3. `questDirector.ts + questPrompt.ts`
+   - 用 AI 原生剧情引擎根据当前局势生成任务意图。
+4. `questFlow.ts`
+   - 只负责把 AI 意图编译成可追踪任务、生成本地奖励、推进步骤。
+5. `goalDirector.ts`
+   - 把任务编译成“当前目标 / 下一步”。
+6. `AdventurePanelOverlays.tsx`
+   - 只负责展示，不再自己承载任务生成逻辑。
+
+一句话：
+
+**任务内容主要由 AI 原生剧情引擎生成，本地代码只保留状态推进、奖励结算和失败兜底。**
+
+## 1. 现在建议保留的主流程
+
+## 1.1 接任务
+
+推荐主流程：
+
+`npcInteractions.ts`
+-> 展示“可接任务”入口
+-> `npcEncounterActions.ts`
+-> `generateQuestForNpcEncounter(...)`
+-> `questDirector.ts`
+-> `questPrompt.ts`
+-> `questFlow.ts`
+-> 写入 `QuestLogEntry`
+
+当前已经做的简化：
+
+- NPC 面板不再为了预览，先本地生成一整份 fallback 任务。
+- 现在只做任务机会判断，并提示“接取后将由 AI 剧情引擎根据当前局势生成具体目标、步骤与奖励”。
+
+这样可以直接消掉一层不必要的双轨：
+
+- 旧流程：
+  - 预览先本地生成
+  - 正式接取再 AI 生成
+- 新流程：
+  - 预览只判断有没有任务机会
+  - 正式接取时再真正生成任务
+
+## 1.2 任务描述
+
+简化后应理解成：
+
+- 任务描述的主来源是 AI 生成的 `QuestIntent.description`
+- 本地只负责把它写入 `QuestLogEntry.description`
+- UI 只负责展示 `quest.description`
+
+主脚本：
+
+- `src/services/questPrompt.ts`
+- `src/services/questDirector.ts`
+- `src/data/questFlow.ts`
+
+## 1.3 达成条件
+
+简化后应理解成：
+
+- AI 负责给出“这件事大概要怎么做”的意图
+- 本地把意图编译成 `steps / objective`
+- UI 根据当前 `activeStep` 生成最短的“下一步”
+
+也就是：
+
+**AI 决定任务方向，本地决定可追踪步骤，UI 只显示当前这一步。**
+
+主脚本：
+
+- `src/data/questFlow.ts`
+- `src/components/adventure-panel/AdventurePanelOverlays.tsx`
+
+## 1.4 奖励
+
+奖励不建议交给 AI 直接写死。
+
+更稳的边界是：
+
+- AI 只给 `rewardTheme`
+- 本地生成具体金币、物品、好感奖励
+- 交付时由本地状态系统结算
+
+主脚本：
+
+- `src/data/questFlow.ts`
+- `src/data/runtimeItemDirector.ts`
+- `src/hooks/story/sessionActions.ts`
+- `src/hooks/story/npcEncounterActions.ts`
+
+## 2. 你这次最关心的三个问题
+
+## 2.1 任务描述怎么生成
+
+主生成链：
+
+- `src/services/questPrompt.ts`
+  - 约束 AI 输出 `title / description / summary / rewardTheme`
+- `src/services/questDirector.ts`
+  - 请求 AI，得到 `QuestIntent`
+- `src/data/questFlow.ts`
+  - `compileQuestIntentToQuest(...)` 把 `description` 写入 `QuestLogEntry`
+
+前台展示：
+
+- `src/components/adventure-panel/AdventurePanelOverlays.tsx`
+  - 优先显示 `quest.description`
+
+## 2.2 达成条件怎么生成
+
+主生成链：
+
+- `src/data/questFlow.ts`
+  - `buildPrimaryQuestStep(...)`
+  - `buildTalkBackStep(...)`
+  - 把 AI 任务意图编译成 `steps`
+
+前台展示：
+
+- `src/components/adventure-panel/AdventurePanelOverlays.tsx`
+  - `buildQuestConditionText(...)`
+  - 根据当前 `activeStep / objective` 重算成一句玩家看得懂的话
+
+## 2.3 任务奖励怎么生成
+
+主生成链：
+
+- `src/data/questFlow.ts`
+  - `buildQuestReward(...)`
+- `src/data/runtimeItemContext.ts`
+  - 给奖励物品生成器准备上下文
+- `src/data/runtimeItemDirector.ts`
+  - 根据 seed 和频道生成奖励物品
+- `src/data/runtimeItemNarrative.ts`
+  - 把奖励物品摊平回 `reward.items`
+
+结算链：
+
+- `src/hooks/story/sessionActions.ts`
+- `src/hooks/story/npcEncounterActions.ts`
+
+## 3. 哪些预设逻辑应该收缩
+
+## 3.1 应该保留
+
+- `buildFallbackQuestIntent(...)`
+  - 保留
+  - 但只作为 AI 失败兜底
+- `buildQuestReward(...)`
+  - 保留
+  - 因为奖励和数值应该继续走本地规则
+- `buildPrimaryQuestStep(...) / buildTalkBackStep(...)`
+  - 保留
+  - 因为任务必须能被本地追踪和结算
+
+## 3.2 应该降级
+
+- `buildQuestForEncounter(...)`
+  - 不再作为 NPC 面板预览主路径
+  - 只保留给 fallback 和测试使用
+- `buildFallbackQuestIntent(...)` 里的多套模板
+  - 可以继续精简
+  - 最终只保留最小 2 到 3 种兜底 archetype 即可
+
+## 3.3 应该谨慎接线
+
+- `buildChapterQuestForScene(...)`
+  - 当前更像“备用章节任务生成器”
+  - 但我还没有在运行时主链里找到直接调用点
+- `SCENE_CHAPTER_OVERRIDES`
+  - 不应该继续扩大
+  - 只保留少量关键样板场景
+
+如果要坚持“AI 原生任务引擎”为主，这部分不应继续膨胀成大规模预设系统。
+
+## 4. 脚本解释速查
+
+| 脚本 | 作用 | 简化方案中的定位 |
+| --- | --- | --- |
+| `src/data/npcInteractions.ts` | 生成 NPC 面板选项、礼物/交易/帮助等交互入口 | 只负责任务机会判断和入口展示，不再预生成整任务 |
+| `src/hooks/story/npcEncounterActions.ts` | 处理点击“接任务 / 交任务 / 切磋 / 离开”等真实执行逻辑 | 任务接取与交付的运行时主入口 |
+| `src/services/questDirector.ts` | 调用 AI，拿到任务意图 `QuestIntent` | AI 原生任务生成主入口 |
+| `src/services/questPrompt.ts` | 组织任务 prompt，约束 AI 输出格式 | AI 任务生成的提示词层 |
+| `src/data/questFlow.ts` | 把任务意图编译成 quest、推进 steps、生成 reward、做 fallback | 任务数据层主脚本，保留但收缩预设分支 |
+| `src/services/storyEngine/goalDirector.ts` | 把 quest / chapter / journeyBeat 编译成当前目标和下一步 | 负责“目标感”，不是负责生成任务本身 |
+| `src/components/adventure-panel/AdventurePanelOverlays.tsx` | 展示任务描述、达成条件、奖励和日志 | 纯展示层 |
+| `src/data/runtimeItemContext.ts` | 给奖励物品生成器准备上下文 | 奖励生成辅助层 |
+| `src/data/runtimeItemDirector.ts` | 生成奖励物品 | 奖励物品生成主脚本 |
+| `src/data/runtimeItemNarrative.ts` | 整理奖励物品和叙事 hint | 奖励辅助层 |
+| `src/hooks/story/sessionActions.ts` | 统一处理领奖、章节同步等动作 | 非 NPC 面板路径下的奖励结算入口 |
+
+## 5. 当前代码现状
+
+截至这次整理，任务主链可以这样理解：
+
+### 已经对齐到“AI 优先”的部分
+
+- 真正点击“接下委托”时，优先调用 `generateQuestForNpcEncounter(...)`
+- AI 返回任务意图后，再由 `questFlow.ts` 编译成本地任务
+
+### 仍然是本地规则负责的部分
+
+- `steps / objective` 推进
+- 奖励数值和奖励物品
+- 领奖与状态结算
+
+### 仍然偏预设、但建议继续收缩的部分
+
+- `buildFallbackQuestIntent(...)`
+- `buildChapterQuestForScene(...)`
+- `SCENE_CHAPTER_OVERRIDES`
+
+## 6. 推荐后的最简架构
+
+如果后面继续收缩，我建议把目标定成下面这版：
+
+1. NPC 面板只判断“能不能接任务”
+2. 点击接任务后，统一走 `questDirector.ts`
+3. AI 只产出：
+   - `title`
+   - `description`
+   - `summary`
+   - `recommendedObjectiveKinds`
+   - `rewardTheme`
+4. `questFlow.ts` 只负责：
+   - 编译 steps
+   - 生成 reward
+   - 推进 status
+5. `goalDirector.ts` 只负责把 quest 变成“当前目标 / 下一步”
+6. 章节任务生成器只做少量 fallback，不再做大规模场景预设扩张
+
+这样之后，代码层的职责会更清楚：
+
+- AI 负责“这件事讲什么”
+- 本地规则负责“这件事怎么追踪、怎么结算”
+- UI 负责“把当前最重要的一步展示给玩家”