Rework story engine flow and reorganize project docs

2026-04-06 23:19:00 +08:00
parent d678929064
commit ddcb5d5c8c
241 changed files with 19805 additions and 2478 deletions
--- a/src/hooks/story/choiceActions.test.ts
+++ b/src/hooks/story/choiceActions.test.ts
@@ -62,7 +62,6 @@ function createBaseState(): GameState {
    currentEncounter: null,
    npcInteractionActive: false,
    currentScenePreset: null,
-    sceneMonsters: [],
    sceneHostileNpcs: [],
    playerX: 0,
    playerOffsetY: 0,
@@ -140,7 +139,6 @@ describe('createStoryChoiceActions', () => {
    const afterSequence = {
      ...state,
      inBattle: false,
-      sceneMonsters: [],
      sceneHostileNpcs: [],
      currentNpcBattleOutcome: 'fight_victory' as const,
    };
@@ -179,7 +177,7 @@ describe('createStoryChoiceActions', () => {
      generateStoryForState,
      getAvailableOptionsForState: vi.fn(() => null),
      getStoryGenerationHostileNpcs: vi.fn(() => []),
-      getResolvedSceneHostileNpcs: vi.fn((inputState: GameState) => inputState.sceneMonsters),
+      getResolvedSceneHostileNpcs: vi.fn((inputState: GameState) => inputState.sceneHostileNpcs),
      buildNpcStory: vi.fn(() => createFallbackStory()),
      updateQuestLog: vi.fn((inputState: GameState) => inputState),
      incrementRuntimeStats: vi.fn((inputState: GameState) => inputState),
@@ -233,7 +231,7 @@ describe('createStoryChoiceActions', () => {
      ...createBaseState(),
      currentBattleNpcId: null,
      currentNpcBattleMode: null,
-      sceneMonsters: [
+      sceneHostileNpcs: [
        {
          id: 'wolf-1',
          name: '山狼',
@@ -289,7 +287,7 @@ describe('createStoryChoiceActions', () => {
      generateStoryForState: vi.fn(),
      getAvailableOptionsForState: vi.fn(() => null),
      getStoryGenerationHostileNpcs: vi.fn(() => []),
-      getResolvedSceneHostileNpcs: vi.fn((inputState: GameState) => inputState.sceneMonsters),
+      getResolvedSceneHostileNpcs: vi.fn((inputState: GameState) => inputState.sceneHostileNpcs),
      buildNpcStory: vi.fn(() => createFallbackStory()),
      updateQuestLog: vi.fn((inputState: GameState) => inputState),
      incrementRuntimeStats: vi.fn((inputState: GameState) => inputState),
--- a/src/hooks/story/choiceActions.ts
+++ b/src/hooks/story/choiceActions.ts
@@ -18,6 +18,7 @@ import {
 import { applyStoryReasoningRecovery } from '../../data/storyRecovery';
 import { generateNextStep } from '../../services/ai';
 import type { StoryGenerationContext } from '../../services/aiTypes';
+import { appendStoryEngineCarrierMemory } from '../../services/storyEngine/echoMemory';
 import { createHistoryMoment } from '../../services/storyHistory';
 import {
  AnimationState,
@@ -95,7 +96,7 @@ function buildCombatResolutionContextText(params: {
  afterSequence: GameState;
  optionKind: ResolvedChoiceState['optionKind'];
  projectedBattleReward: BattleRewardSummary | null;
-  getResolvedSceneHostileNpcs: (state: GameState) => GameState['sceneMonsters'];
+  getResolvedSceneHostileNpcs: (state: GameState) => GameState['sceneHostileNpcs'];
 }) {
  const {
    baseState,
@@ -138,7 +139,7 @@ function buildCombatResolutionContextText(params: {
 function buildHostileNpcBattleReward(
  state: GameState,
  afterSequence: GameState,
-  getResolvedSceneHostileNpcs: (state: GameState) => GameState['sceneMonsters'],
+  getResolvedSceneHostileNpcs: (state: GameState) => GameState['sceneHostileNpcs'],
 ): BattleRewardSummary | null {
  if (!state.worldType || state.currentBattleNpcId || !state.inBattle || afterSequence.inBattle) {
    return null;
@@ -230,8 +231,8 @@ export function createStoryChoiceActions({
  buildFallbackStoryForState: BuildFallbackStoryForState;
  generateStoryForState: GenerateStoryForState;
  getAvailableOptionsForState: (state: GameState, character: Character) => StoryOption[] | null;
-  getStoryGenerationHostileNpcs: (state: GameState) => GameState['sceneMonsters'];
-  getResolvedSceneHostileNpcs: (state: GameState) => GameState['sceneMonsters'];
+  getStoryGenerationHostileNpcs: (state: GameState) => GameState['sceneHostileNpcs'];
+  getResolvedSceneHostileNpcs: (state: GameState) => GameState['sceneHostileNpcs'];
  buildNpcStory: BuildNpcStory;
  updateQuestLog: UpdateQuestLog;
  incrementRuntimeStats: IncrementRuntimeStats;
@@ -273,7 +274,6 @@ export function createStoryChoiceActions({
      ambientIdleMode: undefined,
      currentEncounter: null,
      npcInteractionActive: false,
-      sceneMonsters: [],
      sceneHostileNpcs: [],
      playerX: 0,
      playerFacing: 'right' as const,
@@ -298,7 +298,6 @@ export function createStoryChoiceActions({
      currentScenePreset: targetScene,
      currentEncounter: null,
      npcInteractionActive: false,
-      sceneMonsters: [],
      sceneHostileNpcs: [],
      playerX: 0,
      playerFacing: 'right' as const,
@@ -427,10 +426,10 @@ export function createStoryChoiceActions({
        ? null
        : buildHostileNpcBattleReward(baseChoiceState, projectedState, getResolvedSceneHostileNpcs);
      const projectedStateWithBattleReward = projectedBattleReward
-        ? {
+        ? appendStoryEngineCarrierMemory({
            ...projectedState,
            playerInventory: addInventoryItems(projectedState.playerInventory, projectedBattleReward.items),
-          }
+          } as GameState, projectedBattleReward.items)
        : projectedState;
      fallbackState = projectedStateWithBattleReward;
      const projectedAvailableOptions = getAvailableOptionsForState(
@@ -485,10 +484,10 @@ export function createStoryChoiceActions({

      let afterSequence = shouldUseLocalNpcVictory ? resolvedChoice.afterSequence : actionResult.value;
      if (projectedBattleReward) {
-        afterSequence = {
+        afterSequence = appendStoryEngineCarrierMemory({
          ...afterSequence,
          playerInventory: addInventoryItems(afterSequence.playerInventory, projectedBattleReward.items),
-        };
+        } as GameState, projectedBattleReward.items);
      }
      fallbackState = afterSequence;

--- a/src/hooks/story/npcEncounterActions.ts
+++ b/src/hooks/story/npcEncounterActions.ts
@@ -5,6 +5,7 @@ import { hasEncounterEntity } from '../../data/encounterTransition';
 import { NPC_PREVIEW_TALK_FUNCTION } from '../../data/functionCatalog';
 import {
  addInventoryItems,
+  applyStoryChoiceToStanceProfile,
  buildNpcChatResultText,
  buildNpcHelpCommitActionText,
  buildNpcHelpResultText,
@@ -12,6 +13,7 @@ import {
  buildNpcLeaveResultText,
  buildNpcSparResultText,
  createNpcBattleMonster,
+  describeNpcAffinityInWords,
  generateNpcHelpReward,
  getChatAffinityOutcome,
  getNpcLootItems,
@@ -40,6 +42,10 @@ import { applyStoryReasoningRecovery } from '../../data/storyRecovery';
 import { generateNextStep, streamNpcChatDialogue } from '../../services/ai';
 import type { StoryGenerationContext } from '../../services/aiTypes';
 import { generateQuestForNpcEncounter } from '../../services/questDirector';
+import {
+  appendStoryEngineCarrierMemory,
+  syncNpcNarrativeState,
+} from '../../services/storyEngine/echoMemory';
 import { createHistoryMoment } from '../../services/storyHistory';
 import type {
  Character,
@@ -92,13 +98,13 @@ type BuildStoryContextExtras = {
 function buildCampCompanionChatResultText(
  encounter: Encounter,
  affinityGain: number,
-  _nextAffinity: number,
+  nextAffinity: number,
 ) {
  const teamworkText =
    affinityGain > 0
-      ? 'You also feel a little more confident about how you will work together next.'
-      : 'You at least realign your rhythm for what comes next.';
-  return `${encounter.npcName}閸滃奔缍樻禍銈嗗床娴滃棔绔存潪顔藉厒濞夋洩绱?{describeNpcAffinityInWords(encounter, nextAffinity)}${teamworkText}`;
+      ? '你也更能感觉到，下一步和对方并肩时会顺手一些。'
+      : '至少你们把接下来的节奏重新校准了一遍。';
+  return `${encounter.npcName}和你交换了一番想法，${describeNpcAffinityInWords(encounter, nextAffinity)}${teamworkText}`;
 }

 function isNpcEncounter(
@@ -169,7 +175,7 @@ export function createStoryNpcEncounterActions({
  generateStoryForState: GenerateStoryForState;
  getStoryGenerationHostileNpcs: (
    state: GameState,
-  ) => GameState['sceneMonsters'];
+  ) => GameState['sceneHostileNpcs'];
  getTypewriterDelay: (char: string) => number;
  getAvailableOptionsForState: (
    state: GameState,
@@ -232,10 +238,7 @@ export function createStoryNpcEncounterActions({
    const battleNpcId = state.currentBattleNpcId;
    const npcState = state.npcStates[battleNpcId];
    if (!npcState) return null;
-    const activeBattleHostiles =
-      state.sceneMonsters.length > 0
-        ? state.sceneMonsters
-        : (state.sceneHostileNpcs ?? []);
+    const activeBattleHostiles = state.sceneHostileNpcs;

    if (battleMode === 'spar' && battleOutcome === 'spar_complete') {
      const nextAffinity = npcState.affinity + NPC_SPAR_AFFINITY_GAIN;
@@ -251,7 +254,6 @@ export function createStoryNpcEncounterActions({
        currentNpcBattleOutcome: null,
        currentEncounter: restoredEncounter,
        npcInteractionActive: true,
-        sceneMonsters: [],
        sceneHostileNpcs: [],
        npcStates: {
          ...state.npcStates,
@@ -259,6 +261,11 @@ export function createStoryNpcEncounterActions({
            ...markNpcFirstMeaningfulContactResolved(npcState),
            affinity: nextAffinity,
            relationState: buildRelationState(nextAffinity),
+            stanceProfile: applyStoryChoiceToStanceProfile(
+              npcState.stanceProfile,
+              'npc_chat',
+              { affinityGain: NPC_SPAR_AFFINITY_GAIN },
+            ),
          },
        },
        quests: progressedQuests,
@@ -303,7 +310,8 @@ export function createStoryNpcEncounterActions({
      nextNpcInventory = removeInventoryItem(nextNpcInventory, item.id, 1);
    }

-    const nextState: GameState = incrementRuntimeStats(
+    const nextState: GameState = appendStoryEngineCarrierMemory(
+      incrementRuntimeStats(
      {
        ...state,
        currentBattleNpcId: null,
@@ -311,7 +319,6 @@ export function createStoryNpcEncounterActions({
        currentNpcBattleOutcome: null,
        currentEncounter: null,
        npcInteractionActive: false,
-        sceneMonsters: [],
        sceneHostileNpcs: [],
        playerInventory: addInventoryItems(state.playerInventory, lootItems),
        quests: progressedQuests,
@@ -339,6 +346,8 @@ export function createStoryNpcEncounterActions({
      {
        hostileNpcsDefeated: defeatedHostileNpcIds.length,
      },
+    ),
+      lootItems,
    );

    const lootText =
@@ -638,10 +647,14 @@ export function createStoryNpcEncounterActions({
              (currentNpcState) => ({
                ...markNpcFirstMeaningfulContactResolved(currentNpcState),
                helpUsed: true,
+                stanceProfile: applyStoryChoiceToStanceProfile(
+                  currentNpcState.stanceProfile,
+                  'npc_help',
+                ),
              }),
            );

-            nextState = {
+            nextState = appendStoryEngineCarrierMemory({
              ...nextState,
              playerHp: Math.min(
                nextState.playerMaxHp,
@@ -665,7 +678,7 @@ export function createStoryNpcEncounterActions({
                      ),
                    )
                  : nextState.playerInventory,
-            };
+            } as GameState, reward.items);

            await commitNpcChatState(
              nextState,
@@ -705,10 +718,14 @@ export function createStoryNpcEncounterActions({
              (currentNpcState) => ({
                ...markNpcFirstMeaningfulContactResolved(currentNpcState),
                helpUsed: true,
+                stanceProfile: applyStoryChoiceToStanceProfile(
+                  currentNpcState.stanceProfile,
+                  'npc_help',
+                ),
              }),
            );

-            nextState = {
+            nextState = appendStoryEngineCarrierMemory({
              ...nextState,
              playerHp: Math.min(
                nextState.playerMaxHp,
@@ -732,7 +749,7 @@ export function createStoryNpcEncounterActions({
                      ),
                    )
                  : nextState.playerInventory,
-            };
+            } as GameState, reward.items);

            await commitNpcChatState(
              nextState,
@@ -779,6 +796,11 @@ export function createStoryNpcEncounterActions({
              affinity: nextAffinity,
              relationState: buildRelationState(nextAffinity),
              chattedCount: currentNpcState.chattedCount + 1,
+              stanceProfile: applyStoryChoiceToStanceProfile(
+                currentNpcState.stanceProfile,
+                'npc_chat',
+                { affinityGain },
+              ),
            };
          },
        );
@@ -838,8 +860,13 @@ export function createStoryNpcEncounterActions({
              updateNpcState(
                updateQuestLog(gameState, (quests) => acceptQuest(quests, quest)),
                encounter,
-                (currentNpcState) =>
-                  markNpcFirstMeaningfulContactResolved(currentNpcState),
+                (currentNpcState) => ({
+                  ...markNpcFirstMeaningfulContactResolved(currentNpcState),
+                  stanceProfile: applyStoryChoiceToStanceProfile(
+                    currentNpcState.stanceProfile,
+                    'npc_quest_accept',
+                  ),
+                }),
              ),
              {questsAccepted: 1},
            );
@@ -870,8 +897,13 @@ export function createStoryNpcEncounterActions({
                  acceptQuest(quests, fallbackQuest),
                ),
                encounter,
-                (currentNpcState) =>
-                  markNpcFirstMeaningfulContactResolved(currentNpcState),
+                (currentNpcState) => ({
+                  ...markNpcFirstMeaningfulContactResolved(currentNpcState),
+                  stanceProfile: applyStoryChoiceToStanceProfile(
+                    currentNpcState.stanceProfile,
+                    'npc_quest_accept',
+                  ),
+                }),
              ),
              {questsAccepted: 1},
            );
@@ -896,19 +928,26 @@ export function createStoryNpcEncounterActions({
        const quest = questId ? findQuestById(gameState.quests, questId) : null;
        if (!quest || quest.status !== 'completed') return true;

-        const nextState = {
+        const nextState = appendStoryEngineCarrierMemory({
          ...updateQuestLog(gameState, (quests) =>
            markQuestTurnedIn(quests, quest.id),
          ),
          npcStates: {
            ...gameState.npcStates,
            [getNpcEncounterKey(encounter)]: {
-              ...npcState,
-              ...markNpcFirstMeaningfulContactResolved(npcState),
-              affinity: npcState.affinity + quest.reward.affinityBonus,
-              relationState: buildRelationState(
-                npcState.affinity + quest.reward.affinityBonus,
-              ),
+              ...syncNpcNarrativeState({
+                encounter,
+                npcState: {
+                  ...npcState,
+                  ...markNpcFirstMeaningfulContactResolved(npcState),
+                  affinity: npcState.affinity + quest.reward.affinityBonus,
+                  relationState: buildRelationState(
+                    npcState.affinity + quest.reward.affinityBonus,
+                  ),
+                },
+                customWorldProfile: gameState.customWorldProfile,
+                storyEngineMemory: gameState.storyEngineMemory,
+              }),
            },
          },
          playerCurrency: gameState.playerCurrency + quest.reward.currency,
@@ -916,7 +955,7 @@ export function createStoryNpcEncounterActions({
            gameState.playerInventory,
            quest.reward.items,
          ),
-        };
+        } as GameState, quest.reward.items);

        void commitGeneratedState(
          nextState,
@@ -933,7 +972,6 @@ export function createStoryNpcEncounterActions({
          ambientIdleMode: undefined,
          currentEncounter: null,
          npcInteractionActive: false,
-          sceneMonsters: [],
          sceneHostileNpcs: [],
          playerX: 0,
          playerFacing: 'right' as const,
@@ -981,7 +1019,6 @@ export function createStoryNpcEncounterActions({
          },
          currentEncounter: null,
          npcInteractionActive: false,
-          sceneMonsters: [battleMonster],
          sceneHostileNpcs: [battleMonster],
          playerX: 0,
          playerFacing: 'right' as const,
@@ -1026,7 +1063,6 @@ export function createStoryNpcEncounterActions({
          },
          currentEncounter: null,
          npcInteractionActive: false,
-          sceneMonsters: [battleMonster],
          sceneHostileNpcs: [battleMonster],
          playerX: 0,
          playerHp: sparPlayerMaxHp,
--- a/src/hooks/story/npcInteraction.ts
+++ b/src/hooks/story/npcInteraction.ts
@@ -22,6 +22,7 @@ import {
 } from '../../data/functionCatalog';
 import {
  addInventoryItems,
+  applyStoryChoiceToStanceProfile,
  buildNpcGiftCommitActionText,
  buildNpcGiftResultText,
  buildNpcRecruitResultText,
@@ -35,6 +36,10 @@ import {
 } from '../../data/npcInteractions';
 import { streamNpcChatDialogue, streamNpcRecruitDialogue } from '../../services/ai';
 import type { StoryGenerationContext } from '../../services/aiTypes';
+import {
+  appendStoryEngineCarrierMemory,
+  syncNpcNarrativeState,
+} from '../../services/storyEngine/echoMemory';
 import { createHistoryMoment } from '../../services/storyHistory';
 import type {
  Character,
@@ -84,7 +89,7 @@ type StoryNpcInteractionRuntime = {
    streaming?: boolean,
  ) => StoryMoment;
  generateStoryForState: GenerateStoryForState;
-  getStoryGenerationHostileNpcs: (state: GameState) => GameState['sceneMonsters'];
+  getStoryGenerationHostileNpcs: (state: GameState) => GameState['sceneHostileNpcs'];
  getTypewriterDelay: (char: string) => number;
 };

@@ -381,8 +386,20 @@ export function useStoryNpcInteractionFlow({
    const nextNpcStates = {
      ...gameState.npcStates,
      [recruitKey]: {
-        ...markNpcFirstMeaningfulContactResolved(npcState),
-        recruited: true,
+        ...syncNpcNarrativeState({
+          encounter,
+          npcState: {
+            ...markNpcFirstMeaningfulContactResolved(npcState),
+            recruited: true,
+            stanceProfile: applyStoryChoiceToStanceProfile(
+              npcState.stanceProfile,
+              'npc_recruit',
+              { recruited: true },
+            ),
+          },
+          customWorldProfile: gameState.customWorldProfile,
+          storyEngineMemory: gameState.storyEngineMemory,
+        }),
      },
    };

@@ -408,11 +425,10 @@ export function useStoryNpcInteractionFlow({
    const nextState: GameState = {
      ...rosterState,
      npcStates: nextNpcStates,
-      currentEncounter: null,
-      npcInteractionActive: false,
-      sceneMonsters: [],
-      sceneHostileNpcs: [],
-      playerX: 0,
+    currentEncounter: null,
+    npcInteractionActive: false,
+    sceneHostileNpcs: [],
+    playerX: 0,
      playerFacing: 'right' as const,
      animationState: gameState.animationState,
      scrollWorld: false,
@@ -662,14 +678,14 @@ export function useStoryNpcInteractionFlow({
        }),
      );

-      nextState = {
+      nextState = appendStoryEngineCarrierMemory({
        ...nextState,
        playerCurrency: nextState.playerCurrency - totalPrice,
        playerInventory: addInventoryItems(
          nextState.playerInventory,
          [cloneInventoryItemForOwner(npcItem, 'player', quantity)],
        ),
-      };
+      } as GameState, [cloneInventoryItemForOwner(npcItem, 'player', quantity)]);

      setTradeModal(null);
      void commitNpcReactionAndGenerate({
@@ -766,6 +782,11 @@ export function useStoryNpcInteractionFlow({
          affinity: nextAffinity,
          relationState: buildRelationState(nextAffinity),
          giftsGiven: currentNpcState.giftsGiven + 1,
+          stanceProfile: applyStoryChoiceToStanceProfile(
+            currentNpcState.stanceProfile,
+            'npc_gift',
+            { affinityGain },
+          ),
          inventory: addInventoryItems(
            currentNpcState.inventory,
            [cloneInventoryItemForOwner(giftItem, 'npc')],
--- a/src/hooks/story/openingAdventure.ts
+++ b/src/hooks/story/openingAdventure.ts
@@ -157,7 +157,7 @@ export async function playOpeningAdventureSequence({
  ) => StoryGenerationContext;
  getStoryGenerationHostileNpcs: (
    state: GameState,
-  ) => GameState['sceneMonsters'];
+  ) => GameState['sceneHostileNpcs'];
  hasRenderableDialogueTurns: (text: string, npcName: string) => boolean;
  inferOpeningCampFollowupOptions: (
    state: GameState,
--- a/src/hooks/story/progressionActions.ts
+++ b/src/hooks/story/progressionActions.ts
@@ -8,6 +8,77 @@ import {
  interpolateEncounterTransitionState,
 } from '../../data/encounterTransition';
 import { applyStoryReasoningRecovery } from '../../data/storyRecovery';
+import {
+  buildFallbackActorNarrativeProfile,
+  normalizeActorNarrativeProfile,
+} from '../../services/storyEngine/actorNarrativeProfile';
+import { resolveCurrentActState } from '../../services/storyEngine/actPlanner';
+import { buildAuthorialConstraintPack } from '../../services/storyEngine/authorialConstraintPack';
+import { evaluateBranchBudget } from '../../services/storyEngine/branchBudgetPlanner';
+import {
+  advanceCampaignState,
+  resolveCampaignState,
+} from '../../services/storyEngine/campaignDirector';
+import { compileCampaignFromWorldProfile } from '../../services/storyEngine/campaignPackCompiler';
+import {
+  buildCampEvent,
+  evaluateCampEventOpportunity,
+} from '../../services/storyEngine/campEventDirector';
+import {
+  advanceChapterState,
+  resolveCurrentChapterState,
+} from '../../services/storyEngine/chapterDirector';
+import {
+  advanceCompanionArc,
+  buildCompanionArcStates,
+} from '../../services/storyEngine/companionArcDirector';
+import {
+  applyCompanionReactionToStance,
+  buildCompanionReactionBatch,
+} from '../../services/storyEngine/companionReactionDirector';
+import { resolveAllCompanionResolutions } from '../../services/storyEngine/companionResolutionDirector';
+import {
+  appendConsequenceRecord,
+} from '../../services/storyEngine/consequenceLedger';
+import { buildContentDiffReport } from '../../services/storyEngine/contentDiffReport';
+import { resolveEndingState } from '../../services/storyEngine/endingResolver';
+import { buildEpilogueSummary } from '../../services/storyEngine/epilogueComposer';
+import { buildFactionTensionState } from '../../services/storyEngine/factionTensionState';
+import { resolveCurrentJourneyBeat } from '../../services/storyEngine/journeyBeatPlanner';
+import { buildNarrativeCodex } from '../../services/storyEngine/narrativeCodex';
+import { runNarrativeConsistencyChecks } from '../../services/storyEngine/narrativeConsistencyChecks';
+import { buildNarrativeQaReport } from '../../services/storyEngine/narrativeQaReport';
+import {
+  recordReplaySeed,
+  replayNarrativeRun,
+} from '../../services/storyEngine/narrativeRegressionReplay';
+import { captureNarrativeTelemetry } from '../../services/storyEngine/narrativeTelemetry';
+import { updatePlayerStyleProfileFromAction } from '../../services/storyEngine/playerStyleProfiler';
+import { runPlaythroughMatrix } from '../../services/storyEngine/playthroughMatrixLab';
+import { buildContinueGameDigest } from '../../services/storyEngine/recapDigest';
+import { buildReleaseGateReport } from '../../services/storyEngine/releaseGateReport';
+import { buildSaveMigrationManifest } from '../../services/storyEngine/saveMigrationManifest';
+import { resolveScenarioPack } from '../../services/storyEngine/scenarioPackRegistry';
+import {
+  buildSetpieceDirective,
+  evaluateSetpieceOpportunity,
+} from '../../services/storyEngine/setpieceDirector';
+import { appendChronicleEntries } from '../../services/storyEngine/storyChronicle';
+import { buildThemePackFromWorldProfile } from '../../services/storyEngine/themePack';
+import { buildThreadContractsFromProfile } from '../../services/storyEngine/threadContract';
+import {
+  collectStorySignals,
+  resolveSignalsToThreadUpdates,
+} from '../../services/storyEngine/threadSignalRouter';
+import {
+  buildEncounterVisibilitySlice,
+  createEmptyStoryEngineMemoryState,
+} from '../../services/storyEngine/visibilityEngine';
+import {
+  applyWorldMutationsToGameState,
+  resolveWorldMutations,
+} from '../../services/storyEngine/worldMutationRouter';
+import { buildFallbackWorldStoryGraph } from '../../services/storyEngine/worldStoryGraph';
 import { createHistoryMoment } from '../../services/storyHistory';
 import type {
  Character,
@@ -20,6 +91,390 @@ import type { CommitGeneratedState } from '../generatedState';
 const ENCOUNTER_ENTRY_DURATION_MS = 1800;
 const ENCOUNTER_ENTRY_TICK_MS = 180;

+function dedupeStrings(values: Array<string | null | undefined>, limit = 10) {
+  return [...new Set(values.map((value) => value?.trim() ?? '').filter(Boolean))]
+    .slice(0, limit);
+}
+
+function hydrateStoryEngineMemory(state: GameState): GameState {
+  const storyEngineMemory =
+    state.storyEngineMemory ?? createEmptyStoryEngineMemoryState();
+  if (!state.customWorldProfile || state.currentEncounter?.kind !== 'npc') {
+    return {
+      ...state,
+      storyEngineMemory,
+    };
+  }
+
+  const role =
+    state.customWorldProfile.storyNpcs.find((npc) =>
+      npc.id === state.currentEncounter?.id || npc.name === state.currentEncounter?.npcName,
+    )
+    ?? state.customWorldProfile.playableNpcs.find((npc) =>
+      npc.id === state.currentEncounter?.id || npc.name === state.currentEncounter?.npcName,
+    );
+  if (!role) {
+    return {
+      ...state,
+      storyEngineMemory,
+    };
+  }
+
+  const themePack =
+    state.customWorldProfile.themePack
+    ?? buildThemePackFromWorldProfile(state.customWorldProfile);
+  const storyGraph =
+    state.customWorldProfile.storyGraph
+    ?? buildFallbackWorldStoryGraph(state.customWorldProfile, themePack);
+  const narrativeProfile = normalizeActorNarrativeProfile(
+    role.narrativeProfile,
+    buildFallbackActorNarrativeProfile(role, storyGraph, themePack),
+  );
+  const npcState =
+    state.npcStates[state.currentEncounter.id ?? state.currentEncounter.npcName];
+  const activeThreadIds =
+    storyEngineMemory.activeThreadIds.length > 0
+      ? storyEngineMemory.activeThreadIds
+      : narrativeProfile.relatedThreadIds.slice(0, 4);
+  const visibilitySlice = buildEncounterVisibilitySlice({
+    narrativeProfile,
+    backstoryReveal: state.currentEncounter.backstoryReveal ?? null,
+    disclosureStage:
+      npcState?.affinity != null
+        ? npcState.affinity < 15
+          ? 'guarded'
+          : npcState.affinity < 45
+            ? 'partial'
+            : npcState.affinity < 75
+              ? 'honest'
+              : 'deep'
+        : 'guarded',
+    isFirstMeaningfulContact: npcState?.firstMeaningfulContactResolved !== true,
+    seenBackstoryChapterIds: npcState?.seenBackstoryChapterIds ?? [],
+    storyEngineMemory,
+    activeThreadIds,
+  });
+
+  return {
+    ...state,
+    storyEngineMemory: {
+      ...storyEngineMemory,
+      discoveredFactIds: dedupeStrings([
+        ...storyEngineMemory.discoveredFactIds,
+        ...visibilitySlice.sayableFactIds,
+      ], 16),
+      activeThreadIds: dedupeStrings([
+        ...storyEngineMemory.activeThreadIds,
+        ...activeThreadIds,
+      ], 6),
+    },
+  };
+}
+
+function findNewInventoryItems(previousState: GameState, nextState: GameState) {
+  const previousIds = new Set(previousState.playerInventory.map((item) => item.id));
+  return nextState.playerInventory.filter((item) => !previousIds.has(item.id));
+}
+
+function applyStoryEngineEchoes(params: {
+  previousState: GameState;
+  nextState: GameState;
+  actionText: string;
+  lastFunctionId?: string | null;
+}) {
+  const hydratedState = hydrateStoryEngineMemory(params.nextState);
+  const contracts = hydratedState.customWorldProfile
+    ? hydratedState.customWorldProfile.threadContracts
+        ?? buildThreadContractsFromProfile(hydratedState.customWorldProfile)
+    : [];
+  const newItems = findNewInventoryItems(params.previousState, hydratedState);
+  const signals = collectStorySignals({
+    prevState: params.previousState,
+    nextState: hydratedState,
+    actionText: params.actionText,
+    lastFunctionId: params.lastFunctionId,
+    rewardItems: newItems,
+  });
+  const stateWithSignals = resolveSignalsToThreadUpdates({
+    state: hydratedState,
+    signals,
+    contracts,
+  });
+  const reactions = buildCompanionReactionBatch({
+    state: stateWithSignals,
+    signals,
+    actionText: params.actionText,
+  });
+  const stateWithReactions = applyCompanionReactionToStance({
+    state: stateWithSignals,
+    reactions,
+  });
+  const storyEngineMemory = stateWithReactions.storyEngineMemory ?? createEmptyStoryEngineMemoryState();
+  const chapterState = advanceChapterState({
+    previousChapter:
+      stateWithReactions.chapterState
+      ?? storyEngineMemory.currentChapter
+      ?? null,
+    nextChapter: resolveCurrentChapterState({
+      state: stateWithReactions,
+    }),
+  });
+  const journeyBeat = resolveCurrentJourneyBeat({
+    state: {
+      ...stateWithReactions,
+      chapterState,
+      storyEngineMemory: {
+        ...storyEngineMemory,
+        currentChapter: chapterState,
+      },
+    },
+    chapterState,
+  });
+  const companionArcStates = advanceCompanionArc({
+    previous: storyEngineMemory.companionArcStates,
+    next: buildCompanionArcStates({
+      state: stateWithReactions,
+      reactions,
+    }),
+  });
+  const campEvent = evaluateCampEventOpportunity({
+    state: stateWithReactions,
+    chapterState,
+    journeyBeat,
+    companionArcStates,
+  })
+    ? buildCampEvent({
+        state: stateWithReactions,
+        chapterState,
+        journeyBeat,
+        companionArcStates,
+      })
+    : null;
+  const worldMutations = resolveWorldMutations({
+    state: stateWithReactions,
+    signals,
+    chapterState,
+  });
+  const stateWithMutations = applyWorldMutationsToGameState({
+    state: stateWithReactions,
+    mutations: worldMutations,
+  });
+  const setpieceDirective = evaluateSetpieceOpportunity({
+    state: stateWithMutations,
+    chapterState,
+    journeyBeat,
+  })
+    ? buildSetpieceDirective({
+        state: stateWithMutations,
+        chapterState,
+        journeyBeat,
+      })
+    : null;
+  const chronicle = appendChronicleEntries({
+    state: stateWithMutations,
+    chapterState,
+    worldMutations,
+    reactions,
+    signals,
+    campEvent,
+    setpieceDirective,
+  });
+  const factionTensionStates = buildFactionTensionState(
+    stateWithMutations.customWorldProfile,
+    storyEngineMemory,
+  );
+  const actState = resolveCurrentActState({
+    state: stateWithMutations,
+    chapterState,
+  });
+  const campaignState = advanceCampaignState({
+    previous: storyEngineMemory.campaignState ?? stateWithMutations.campaignState ?? null,
+    next: resolveCampaignState({
+      state: stateWithMutations,
+      actState,
+    }),
+  });
+  const consequenceLedger = appendConsequenceRecord({
+    existing: storyEngineMemory.consequenceLedger,
+    signals,
+    reactions,
+    worldMutations,
+    campEvent,
+  });
+  const authorialConstraintPack = buildAuthorialConstraintPack({
+    profile: stateWithMutations.customWorldProfile,
+  });
+  const compiledPacks = stateWithMutations.customWorldProfile
+    ? compileCampaignFromWorldProfile({
+        profile: stateWithMutations.customWorldProfile,
+      })
+    : null;
+  const activeScenarioPack =
+    resolveScenarioPack(stateWithMutations.activeScenarioPackId)
+    ?? compiledPacks?.scenarioPack
+    ?? null;
+  const activeCampaignPack = compiledPacks?.campaignPack ?? null;
+  const playerStyleProfile = updatePlayerStyleProfileFromAction({
+    current: storyEngineMemory.playerStyleProfile,
+    actionText: params.actionText,
+  });
+  const companionResolutions = resolveAllCompanionResolutions({
+    state: stateWithMutations,
+    arcStates: companionArcStates,
+    ledger: consequenceLedger,
+    reactions,
+  });
+  const endingState =
+    actState?.status === 'finale' || actState?.status === 'resolved'
+      ? resolveEndingState({
+          state: stateWithMutations,
+          companionResolutions,
+          factionTensionStates,
+        })
+      : storyEngineMemory.endingState ?? null;
+  const epilogueSummary =
+    endingState
+      ? buildEpilogueSummary({
+          endingState,
+          companionResolutions,
+        })
+      : null;
+  const currentJourneyBeatId = journeyBeat?.id ?? storyEngineMemory.currentJourneyBeatId ?? null;
+  const branchBudgetStatus = evaluateBranchBudget({
+    consequenceLedger,
+    authorialConstraintPack,
+    endingFamilyCount: endingState ? 1 : 0,
+  });
+  const baseMemoryForQa = {
+    ...storyEngineMemory,
+    currentChapter: chapterState,
+    currentJourneyBeatId,
+    currentJourneyBeat: journeyBeat,
+    companionArcStates,
+    worldMutations,
+    chronicle,
+    factionTensionStates,
+    currentCampEvent: campEvent,
+    currentSetpieceDirective: setpieceDirective,
+    campaignState,
+    actState,
+    consequenceLedger,
+    companionResolutions,
+    endingState,
+    authorialConstraintPack,
+    branchBudgetStatus,
+    playerStyleProfile,
+  };
+  const consistencyIssues = runNarrativeConsistencyChecks({
+    memory: baseMemoryForQa,
+    threadContracts: contracts,
+    branchBudgetStatus,
+  });
+  const narrativeQaReport = buildNarrativeQaReport({
+    issues: consistencyIssues,
+  });
+  const simulationRunResults =
+    activeScenarioPack && activeCampaignPack
+      ? runPlaythroughMatrix({
+          scenarioPackId: activeScenarioPack.id,
+          campaignPack: activeCampaignPack,
+          memory: {
+            ...baseMemoryForQa,
+            narrativeQaReport,
+          },
+          seeds: ['baseline', 'companion', 'explore'],
+        })
+      : [];
+  const replaySummary =
+    simulationRunResults[0]
+      ? replayNarrativeRun({
+          recordedSeed: recordReplaySeed({
+            seed: simulationRunResults[0].seed,
+            label: `${activeCampaignPack?.title ?? 'campaign'} 基线回放`,
+          }),
+          result: simulationRunResults[0],
+        }).summary
+      : null;
+  const releaseGateReport = buildReleaseGateReport({
+    qaReport: narrativeQaReport,
+    simulationResults: simulationRunResults,
+    unresolvedThreadCount: stateWithMutations.storyEngineMemory?.activeThreadIds.length ?? 0,
+  });
+  const saveMigrationManifest = buildSaveMigrationManifest({
+    version: 'story-engine-v5',
+  });
+  const telemetrySnapshot = captureNarrativeTelemetry({
+    memory: {
+      ...baseMemoryForQa,
+      narrativeQaReport,
+    },
+    qaReport: narrativeQaReport,
+  });
+  const contentDiffReport = buildContentDiffReport({
+    previousProfile: params.previousState.customWorldProfile,
+    nextProfile: stateWithMutations.customWorldProfile,
+    previousCampaignPack: null,
+    nextCampaignPack: activeCampaignPack,
+  });
+  const narrativeCodex = buildNarrativeCodex({
+    ...stateWithMutations,
+    chapterState,
+    campaignState,
+    storyEngineMemory: {
+      ...baseMemoryForQa,
+      narrativeQaReport,
+      releaseGateReport,
+      simulationRunResults,
+    },
+  });
+  const continueDigest = buildContinueGameDigest({
+    state: {
+      ...stateWithMutations,
+      chapterState,
+      campaignState,
+      storyEngineMemory: {
+        ...baseMemoryForQa,
+        currentJourneyBeatId,
+        narrativeQaReport,
+        releaseGateReport,
+        simulationRunResults,
+        narrativeCodex,
+        saveMigrationManifest,
+      },
+    },
+  }) + [
+    epilogueSummary,
+    replaySummary,
+    telemetrySnapshot.summary,
+    contentDiffReport.summary,
+    `发布门禁：${releaseGateReport.status} / ${releaseGateReport.summary}`,
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  return {
+    ...stateWithMutations,
+    chapterState,
+    campaignState,
+    activeScenarioPackId: activeScenarioPack?.id ?? stateWithMutations.activeScenarioPackId ?? null,
+    activeCampaignPackId: activeCampaignPack?.id ?? stateWithMutations.activeCampaignPackId ?? null,
+    storyEngineMemory: {
+      ...baseMemoryForQa,
+      currentJourneyBeatId,
+      continueGameDigest: continueDigest,
+      narrativeQaReport,
+      narrativeCodex,
+      releaseGateReport,
+      simulationRunResults,
+      saveMigrationManifest,
+      recentCompanionReactions: [
+        ...(storyEngineMemory.recentCompanionReactions ?? []),
+        ...reactions,
+      ].slice(-6),
+    },
+  };
+}
+
 export type GenerateStoryForState = (params: {
  state: GameState;
  character: Character;
@@ -79,26 +534,36 @@ export function createStoryProgressionActions({
    actionText,
    resultText,
    lastFunctionId,
-  ) => {
-    const nextHistory = appendStoryHistory(gameState, actionText, resultText);
-    const stateWithHistory: GameState = {
+    ) => {
+      const nextHistory = appendStoryHistory(gameState, actionText, resultText);
+    const stateWithHistory = applyStoryEngineEchoes({
+      previousState: gameState,
+      nextState: {
      ...nextState,
      storyHistory: nextHistory,
-    };
+    } as GameState,
+      actionText,
+      lastFunctionId,
+    });

    setGameState(stateWithHistory);
    setAiError(null);
    setIsLoading(true);

-    try {
-      const nextStory = await generateStoryForState({
-        state: stateWithHistory,
+      try {
+        const nextStory = await generateStoryForState({
+          state: stateWithHistory,
        character,
        history: nextHistory,
-        choice: actionText,
+          choice: actionText,
+          lastFunctionId,
+        });
+      const recoveredState = applyStoryEngineEchoes({
+        previousState: gameState,
+        nextState: applyStoryReasoningRecovery(stateWithHistory),
+        actionText,
        lastFunctionId,
      });
-      const recoveredState = applyStoryReasoningRecovery(stateWithHistory);
      setGameState(recoveredState);
      setCurrentStory(nextStory);
    } catch (error) {
@@ -134,22 +599,32 @@ export function createStoryProgressionActions({
    }

    const nextHistory = appendStoryHistory(gameState, actionText, resultText);
-    const stateWithHistory: GameState = {
+    const stateWithHistory = applyStoryEngineEchoes({
+      previousState: gameState,
+      nextState: {
      ...resolvedState,
      storyHistory: nextHistory,
-    };
+    } as GameState,
+      actionText,
+      lastFunctionId,
+    });

    setGameState(stateWithHistory);

-    try {
-      const nextStory = await generateStoryForState({
+      try {
+        const nextStory = await generateStoryForState({
        state: stateWithHistory,
        character,
        history: nextHistory,
-        choice: actionText,
+          choice: actionText,
+          lastFunctionId,
+        });
+      const recoveredState = applyStoryEngineEchoes({
+        previousState: gameState,
+        nextState: applyStoryReasoningRecovery(stateWithHistory),
+        actionText,
        lastFunctionId,
      });
-      const recoveredState = applyStoryReasoningRecovery(stateWithHistory);
      setGameState(recoveredState);
      setCurrentStory(nextStory);
    } catch (error) {
--- a/src/hooks/story/sessionActions.test.ts
+++ b/src/hooks/story/sessionActions.test.ts
@@ -104,7 +104,7 @@ function createBaseState(): GameState {
    currentEncounter: encounter,
    npcInteractionActive: false,
    currentScenePreset: null,
-    sceneMonsters: [],
+    sceneHostileNpcs: [],
    playerX: 0,
    playerOffsetY: 0,
    playerFacing: 'right',
--- a/src/hooks/story/sessionActions.ts
+++ b/src/hooks/story/sessionActions.ts
@@ -9,6 +9,7 @@ import {
  markQuestCompletionNotified,
  markQuestTurnedIn,
 } from '../../data/questFlow';
+import { appendStoryEngineCarrierMemory } from '../../services/storyEngine/echoMemory';
 import type {
  GameState,
  StoryMoment,
@@ -43,7 +44,7 @@ export function applyQuestRewardClaim(

  const issuerNpcState = state.npcStates[quest.issuerNpcId];

-  return {
+  return appendStoryEngineCarrierMemory({
    ...state,
    quests: markQuestTurnedIn(state.quests, questId),
    playerCurrency: state.playerCurrency + quest.reward.currency,
@@ -57,7 +58,7 @@ export function applyQuestRewardClaim(
          },
        }
      : state.npcStates,
-  };
+  }, quest.reward.items);
 }

 export function createStorySessionActions({
--- a/src/hooks/story/storyGenerationState.test.ts
+++ b/src/hooks/story/storyGenerationState.test.ts
@@ -141,7 +141,7 @@ function createBaseState(): GameState {
    currentEncounter: createEncounter(),
    npcInteractionActive: false,
    currentScenePreset: scenes[0] ?? null,
-    sceneMonsters: [],
+    sceneHostileNpcs: [],
    playerX: 0,
    playerOffsetY: 0,
    playerFacing: 'right',
--- a/src/hooks/story/storyGenerationState.ts
+++ b/src/hooks/story/storyGenerationState.ts
@@ -142,7 +142,7 @@ export function buildMapTravelResolution(
    currentScenePreset: targetScene,
    currentEncounter: null,
    npcInteractionActive: false,
-    sceneMonsters: [],
+    sceneHostileNpcs: [],
    playerX: 0,
    playerFacing: 'right' as const,
    animationState: AnimationState.IDLE,