Genarrative/docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md

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。奖励由本地规则稳定计算，避免帮助收益被模型临场漂移。

• 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。它把本地生成的任务写入 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 解析。
• battle_attack_basic / battle_use_skill 虽然属于后端运行时契约中的战斗 function，但不进入 STATE_FUNCTION_DEFINITIONS。它们由后端 runtime story / combat option 池生成，避免前端本地生成缺少 runtimePayload 的假选项。
• 非 state function 目前仍由各自原有流程模块执行，但它们的 id、标题和详细说明已经统一收口到 functionCatalog/。
• 后续新增 function 时，建议先补独立脚本，再把运行时调用接进来，最后同步这份目录文档。