Genarrative/docs/reference/TASK_GENERATION_TRACE_2026-04-08.md

任务生成链路与简化建议

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