# 任务生成链路与简化建议

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