# 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。正式奖励、资源变化与 one-shot 状态由后端 runtime action resolver 稳定计算，避免帮助收益被模型临场漂移。 - `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。它把后端 pending quest offer 写入 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` 说明：营地开场或同伴交流结束后，正式前往角色主场景的流程项。前端脚本只保留按钮与视觉元信息，目标场景、状态清理、encounter preview、`scenesTraveled` 与快照持久化由后端 runtime action resolver 负责。 - `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。前端只提交物品动作，资源变化、数量扣减、build buff 与故事历史由后端 resolver 写入。 - `equipment_equip` 脚本：`src/data/functionCatalog/panel/equipmentEquip.ts` 说明：在装备面板中把背包物品穿戴到对应槽位的 function。它会同时处理替换旧装备、背包回收和属性重算。 - `equipment_unequip` 脚本：`src/data/functionCatalog/panel/equipmentUnequip.ts` 说明：从装备槽位卸下物品的 function。后端 resolver 负责卸装结果、背包数量和 loadout 一致性。 - `forge_craft` 脚本：`src/data/functionCatalog/panel/forgeCraft.ts` 说明：在锻造面板中执行配方制作的 function。它负责扣除材料和货币、产出新物品，并把制作结果写入故事历史。 - `forge_dismantle` 脚本：`src/data/functionCatalog/panel/forgeDismantle.ts` 说明：在锻造面板中拆解物品回收材料的 function。拆解产出由后端锻造 resolver 控制，避免与物品设计脱节。 - `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 时，建议先补独立脚本，再把运行时调用接进来，最后同步这份目录文档。