Rework story engine flow and reorganize project docs

docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md

@@ -0,0 +1,191 @@
+# 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_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_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 解析。
+- 非 state function 目前仍由各自原有流程模块执行，但它们的 `id`、标题和详细说明已经统一收口到 `functionCatalog/`。
+- 后续新增 function 时，建议先补独立脚本，再把运行时调用接进来，最后同步这份目录文档。

docs/reference/README.md

@@ -0,0 +1,10 @@
+# 参考目录
+
+## 当前入口
+
+- [FUNCTION_SCRIPT_CATALOG_2026-04-04.md](./FUNCTION_SCRIPT_CATALOG_2026-04-04.md)：Function 独立脚本目录与分类速查。
+
+## 使用建议
+
+- 需要快速定位 Function 脚本，而不是阅读长篇方案时，优先看这里。
+- 如果要评估 Function 分层是否合理，再配合 `docs/audits/FUNCTION_DESIGN_AUDIT_2026-04-03.md` 一起看。