Simplify custom world result editing controls

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 负责“把当前最重要的一步展示给玩家”