Upload 12 files

README.md

@@ -1,14 +1,557 @@
----
-title: Story Weaver
-emoji: 📉
-colorFrom: pink
-colorTo: green
-sdk: gradio
-sdk_version: 6.10.0
-app_file: app.py
-pinned: false
-license: mit
-short_description: 'Story_Weaver '
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: StoryWeaver
+emoji: 📖
+colorFrom: red
+colorTo: purple
+sdk: gradio
+sdk_version: 4.44.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: Interactive NLP story engine with evaluation and logging
+---
+
+# StoryWeaver
+
+StoryWeaver is an interactive text-adventure system built for our NLP course project. The repo is structured as an engineering project first and a demo second: it contains the playable app, the state-management core, evaluation scripts, and logging utilities needed for report writing and team collaboration.
+
+This README is written for teammates who need to:
+
+- understand how the system is organized
+- run the app locally
+- know where to change prompts, rules, or UI
+- collect evaluation results for the report
+- debug a bad interaction without reading the whole codebase first
+
+## What This Repository Contains
+
+At a high level, the project has five responsibilities:
+
+1. parse player input into structured intent
+2. keep the world state consistent across turns
+3. generate the next story response and options
+4. expose the system through a Gradio UI
+5. export logs and run reproducible evaluation
+
+This means the repo is not only a "game demo". It is also the evidence pipeline for the course deliverables.
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Create `.env`
+
+Create a `.env` file in the project root:
+
+```env
+QWEN_API_KEY=your_api_key_here
+```
+
+Optional:
+
+```env
+STORYWEAVER_LOG_DIR=logs/interactions
+```
+
+### 3. Run the app
+
+```bash
+python app.py
+```
+
+Default local URL:
+
+- `http://localhost:7860`
+
+### 4. Run evaluation
+
+```bash
+python evaluation/run_evaluations.py --task all --repeats 3
+```
+
+Useful variants:
+
+```bash
+python evaluation/run_evaluations.py --task intent
+python evaluation/run_evaluations.py --task consistency
+python evaluation/run_evaluations.py --task latency --repeats 5
+python evaluation/run_evaluations.py --task branch
+```
+
+## Deploy to Hugging Face Spaces (Web Upload)
+
+If you want to deploy quickly without using git commands, use this checklist:
+
+1. Create a new Space on Hugging Face:
+   - SDK: `Gradio`
+   - Python version: default is fine (3.10+)
+2. Upload project files from this repository root.
+3. Do **not** upload local-only files/directories:
+   - `venv/`, `.venv/`, `.env`, `__pycache__/`, `.gradio/`, `logs/`, `evaluation/results/`
+4. In Space settings, add secret:
+   - `QWEN_API_KEY`
+5. Wait for build to finish, then open the Space URL.
+
+This repository already uses the standard Gradio entrypoint in `app.py`, so Spaces will start the app automatically.
+
+## Recommended Reading Order
+
+If you are new to the repo, read files in this order:
+
+1. [state_manager.py](./state_manager.py)
+   Why: this is the single source of truth for player state, world state, quests, items, consistency checks, and state updates.
+2. [nlu_engine.py](./nlu_engine.py)
+   Why: this shows how raw player text becomes structured intent.
+3. [story_engine.py](./story_engine.py)
+   Why: this is the main generation pipeline and fallback logic.
+4. [app.py](./app.py)
+   Why: this connects the UI with the engines and now also writes interaction logs.
+5. [evaluation/run_evaluations.py](./evaluation/run_evaluations.py)
+   Why: this shows how we measure the system for the report.
+
+If you only have 10 minutes, start with:
+
+- `GameState.pre_validate_action`
+- `GameState.check_consistency`
+- `GameState.apply_changes`
+- `NLUEngine.parse_intent`
+- `StoryEngine.generate_story_stream`
+- `process_user_input` in [app.py](./app.py)
+
+## Repository Map
+
+```text
+StoryWeaver/
+|-- app.py
+|-- nlu_engine.py
+|-- story_engine.py
+|-- state_manager.py
+|-- telemetry.py
+|-- utils.py
+|-- requirements.txt
+|-- evaluation/
+|   |-- run_evaluations.py
+|   |-- datasets/
+|   `-- results/
+`-- logs/
+    `-- interactions/
+```
+
+Core responsibilities by file:
+
+- [app.py](./app.py)
+  Gradio app, session lifecycle, UI callbacks, per-turn logging.
+- [state_manager.py](./state_manager.py)
+  Player/world models, item registry, NPC registry, quest registry, state validation, consistency checks, change application.
+- [nlu_engine.py](./nlu_engine.py)
+  Intent parsing. Uses LLM parsing when available and keyword fallback when not.
+- [story_engine.py](./story_engine.py)
+  Opening generation, main story generation, option generation, stream handling, fallback handling, telemetry tags.
+- [telemetry.py](./telemetry.py)
+  Session metadata and JSONL interaction log export.
+- [utils.py](./utils.py)
+  API client setup, Qwen calls, JSON extraction, retry helpers.
+- [evaluation/run_evaluations.py](./evaluation/run_evaluations.py)
+  Reproducible experiment runner for the report.
+
+## System Architecture
+
+The main runtime path is:
+
+`Player Input -> NLU -> Validation -> Story Generation -> State Update -> UI Output -> Interaction Log`
+
+There are two ideas that matter most in this codebase:
+
+### 1. `GameState` is the source of truth
+
+Almost everything meaningful lives in [state_manager.py](./state_manager.py):
+
+- player stats
+- location
+- time and weather
+- inventory and equipment
+- quests
+- NPC states
+- event history
+
+When changing gameplay, try to keep state logic here instead of scattering it across prompts and UI code.
+
+### 2. The app is a coordinator, not the game logic
+
+[app.py](./app.py) should mostly:
+
+- receive user input
+- call NLU
+- call the story engine
+- update the chat UI
+- write telemetry logs
+
+If a new feature changes game rules, it probably belongs in [state_manager.py](./state_manager.py) or [story_engine.py](./story_engine.py), not in the UI layer.
+
+## Runtime Flow
+
+### Text input flow
+
+For normal text input, the path is:
+
+1. `process_user_input` receives raw text from the UI
+2. `NLUEngine.parse_intent` converts it into a structured intent dict
+3. `GameState.pre_validate_action` blocks clearly invalid actions early
+4. `StoryEngine.generate_story_stream` runs the main narrative pipeline
+5. `GameState.check_consistency` and `apply_changes` update state
+6. UI is refreshed with story text, options, and status panel
+7. `_record_interaction_log` writes a JSONL record to disk
+
+### Option click flow
+
+Button clicks do not go through full free-text parsing. Instead:
+
+1. the selected option is converted to an intent-like dict
+2. the story engine processes it the same way as text input
+3. the result is rendered and logged
+
+This is useful because option interactions and free-text interactions now share the same evaluation and observability format.
+
+## Main Modules in More Detail
+
+### `state_manager.py`
+
+This file defines:
+
+- `PlayerState`
+- `WorldState`
+- `GameEvent`
+- `GameState`
+
+Important methods:
+
+- `pre_validate_action`
+  Rejects obviously invalid actions before calling the model.
+- `check_consistency`
+  Detects contradictions in proposed state changes.
+- `apply_changes`
+  Applies state changes and returns a readable change log.
+- `validate`
+  Makes sure the resulting state is legal.
+- `to_prompt`
+  Serializes the current game state into prompt-ready text.
+
+When to edit this file:
+
+- adding new items, NPCs, quests, or locations
+- adding deterministic rules
+- improving consistency checks
+- changing state serialization for prompts
+
+### `nlu_engine.py`
+
+This file is responsible for intent recognition.
+
+Current behavior:
+
+- try LLM parsing first
+- fall back to keyword rules if parsing fails
+- return a normalized intent dict with `parser_source`
+
+Current intent labels include:
+
+- `ATTACK`
+- `TALK`
+- `MOVE`
+- `EXPLORE`
+- `USE_ITEM`
+- `TRADE`
+- `EQUIP`
+- `REST`
+- `QUEST`
+- `SKILL`
+- `PICKUP`
+- `FLEE`
+- `CUSTOM`
+
+When to edit this file:
+
+- adding a new intent type
+- improving keyword fallback
+- adding target extraction logic
+- improving low-confidence handling
+
+### `story_engine.py`
+
+This is the main generation module.
+
+It currently handles:
+
+- opening generation
+- story generation for each turn
+- streaming and non-streaming paths
+- default/fallback outputs
+- consistency-aware regeneration
+- response telemetry such as fallback reason and engine mode
+
+Important methods:
+
+- `generate_opening_stream`
+- `generate_story`
+- `generate_story_stream`
+- `process_option_selection_stream`
+- `_fallback_response`
+
+When to edit this file:
+
+- changing prompts
+- changing multi-stage generation logic
+- changing fallback behavior
+- adding generation-side telemetry
+
+### `app.py`
+
+This file is the UI entry point and interaction orchestrator.
+
+Important responsibilities:
+
+- create a new game session
+- start and restart the app session
+- process text input
+- process option clicks
+- update Gradio components
+- write structured interaction logs
+
+When to edit this file:
+
+- changing UI flow
+- adding debug panels
+- changing how logs are written
+- changing how outputs are displayed
+
+### `telemetry.py`
+
+This file handles structured log export.
+
+It is intentionally simple and file-based:
+
+- one session gets one JSONL file
+- one turn becomes one JSON object line
+
+This is useful for:
+
+- report case studies
+- measuring fallback rate
+- debugging weird turns
+- collecting examples for later evaluation
+
+## Logging and Observability
+
+Interaction logs are written under:
+
+- [logs/interactions](./logs/interactions)
+
+Each turn record includes at least:
+
+- input source
+- user input
+- NLU result
+- latency
+- fallback metadata
+- state changes
+- consistency issues
+- final output text
+- post-turn state snapshot
+
+Example shape:
+
+```json
+{
+  "timestamp": "2026-03-14T18:55:00",
+  "session_id": "sw-20260314-185500-ab12cd34",
+  "turn_index": 3,
+  "input_source": "text_input",
+  "user_input": "和村长老伯谈谈最近森林里的怪事",
+  "nlu_result": {
+    "intent": "TALK",
+    "target": "村长老伯",
+    "parser_source": "llm"
+  },
+  "latency_ms": 842.13,
+  "used_fallback": false,
+  "state_changes": {},
+  "output_text": "...",
+  "post_turn_snapshot": {
+    "location": "村庄广场"
+  }
+}
+```
+
+If you need to debug a bad interaction, the fastest path is:
+
+1. check the log file
+2. inspect `nlu_result`
+3. inspect `telemetry.used_fallback`
+4. inspect `state_changes`
+5. inspect the post-turn snapshot
+
+## Evaluation Pipeline
+
+Evaluation entry point:
+
+- [evaluation/run_evaluations.py](./evaluation/run_evaluations.py)
+
+Datasets:
+
+- [evaluation/datasets/intent_accuracy.json](./evaluation/datasets/intent_accuracy.json)
+- [evaluation/datasets/consistency.json](./evaluation/datasets/consistency.json)
+- [evaluation/datasets/latency.json](./evaluation/datasets/latency.json)
+- [evaluation/datasets/branch_divergence.json](./evaluation/datasets/branch_divergence.json)
+
+Results:
+
+- [evaluation/results](./evaluation/results)
+
+### What each task measures
+
+#### Intent
+
+- labeled input -> predicted intent
+- optional target matching
+- parser source breakdown
+- per-example latency
+
+#### Consistency
+
+- action guard correctness via `pre_validate_action`
+- contradiction detection via `check_consistency`
+
+#### Latency
+
+- NLU latency
+- generation latency
+- total latency
+- fallback rate
+
+#### Branch divergence
+
+- same start state, different choices
+- compare resulting story text
+- compare option differences
+- compare state snapshot differences
+
+## Common Development Tasks
+
+### Add a new intent
+
+You will usually need to touch:
+
+- [nlu_engine.py](./nlu_engine.py)
+- [state_manager.py](./state_manager.py)
+- [story_engine.py](./story_engine.py)
+- [evaluation/datasets/intent_accuracy.json](./evaluation/datasets/intent_accuracy.json)
+
+Suggested checklist:
+
+1. add the label to the NLU logic
+2. decide whether it needs pre-validation
+3. make sure story prompts know how to handle it
+4. add at least a few evaluation examples
+
+### Add a new location, NPC, quest, or item
+
+Most of the time you only need:
+
+- [state_manager.py](./state_manager.py)
+
+That file contains the initial world setup and registry-style data.
+
+### Add more evaluation cases
+
+Edit files under:
+
+- [evaluation/datasets](./evaluation/datasets)
+
+This is the easiest way to improve the report without changing runtime logic.
+
+### Investigate a strange game turn
+
+Check in this order:
+
+1. interaction log under `logs/interactions`
+2. `parser_source` in the NLU result
+3. `telemetry` in the final story result
+4. whether `pre_validate_action` rejected or allowed the turn
+5. whether `check_consistency` flagged anything
+
+### Change UI behavior without touching gameplay
+
+Edit:
+
+- [app.py](./app.py)
+
+Try not to put game rules in the UI layer.
+
+## Environment Notes
+
+### If `QWEN_API_KEY` is missing
+
+- warning logs will appear
+- some paths will still run through fallback logic
+- evaluation can still execute, but model-quality conclusions are not meaningful
+
+### If `openai` is not installed
+
+- the repo can still import in some cases because the client is lazily initialized
+- full Qwen generation will not work
+- evaluation scripts will mostly reflect fallback behavior
+
+### If `gradio` is not installed
+
+- the app cannot launch
+- offline evaluation scripts can still be useful
+
+## Current Known Limitations
+
+These are the main gaps we still know about:
+
+- some item and equipment effects are stored as metadata but not fully executed as deterministic rules
+- combat and trade are still more prompt-driven than rule-driven
+- branch divergence is much more meaningful with a real model than in fallback-only mode
+- evaluation quality depends on whether the real model environment is available
+
+## Suggested Team Workflow
+
+If multiple teammates are working in parallel, this split is usually clean:
+
+- gameplay/state teammate
+  Focus on [state_manager.py](./state_manager.py)
+- prompt/generation teammate
+  Focus on [story_engine.py](./story_engine.py)
+- NLU/evaluation teammate
+  Focus on [nlu_engine.py](./nlu_engine.py) and [evaluation](./evaluation)
+- UI/demo teammate
+  Focus on [app.py](./app.py)
+- report teammate
+  Focus on `evaluation/results`, `logs/interactions`, and case-study collection
+
+## What To Use in the Final Report
+
+For the course report, the most useful artifacts from this repo are:
+
+- evaluation JSON outputs under `evaluation/results`
+- interaction logs under `logs/interactions`
+- dataset files under `evaluation/datasets`
+- readable state transitions from `change_log`
+- fallback metadata from `telemetry`
+
+These can directly support:
+
+- experiment setup
+- metric definition
+- result tables
+- success cases
+- failure case analysis
+
+## License
+
+MIT

app.py

@@ -0,0 +1,2005 @@
+"""
+app.py - StoryWeaver Gradio 交互界面
+
+职责：
+1. 构建游戏的 Web 前端界面 (Gradio)
+2. 串联 NLU 引擎、叙事引擎、状态管理器
+3. 管理用户交互流程（文本输入 + 选项点击）
+4. 展示游戏状态（HP、背包、任务等）
+
+数据流转：
+  用户输入 → NLU 引擎（意图识别） → 叙事引擎（两阶段生成）
+      ↕                                    ↕
+  Gradio UI  ←  状态管理器（校验 + 更新）  ←  叙事引擎（文本 + 选项）
+"""
+
+import copy
+from collections import Counter
+import html
+import json
+import logging
+from time import perf_counter
+import gradio as gr
+
+from state_manager import GameState
+from nlu_engine import NLUEngine
+from scene_assets import get_scene_image_path
+from story_engine import StoryEngine
+from telemetry import append_turn_log, create_session_metadata
+from utils import logger
+
+APP_UI_CSS = """
+.story-chat {min-height: 500px;}
+.status-panel {
+    font-family: "Microsoft YaHei UI", "Noto Sans SC", sans-serif;
+    font-size: 0.9em;
+    line-height: 1.5;
+    background: transparent !important;
+    border: none !important;
+    border-radius: 0 !important;
+    padding: 10px 12px !important;
+    box-shadow: none !important;
+    overflow: visible !important;
+}
+.status-panel > div,
+.status-panel [class*="prose"],
+.status-panel .markdown-body,
+.status-panel [class*="wrap"] {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    padding: 0 !important;
+    overflow: visible !important;
+}
+.status-panel * {
+    word-break: break-word;
+    overflow-wrap: anywhere;
+}
+.option-btn {min-height: 50px !important;}
+.side-action-btn,
+.side-action-btn button {min-height: 50px !important;}
+.backpack-btn button {
+    min-height: 50px !important;
+    background: #ffffff !important;
+    color: #0f172a !important;
+    border: 1px solid #d1d5db !important;
+}
+.scene-sidebar {gap: 12px;}
+.scene-card {
+    border: 1px solid #e5e7eb !important;
+    border-radius: 12px !important;
+    background: #fcfcfd !important;
+    box-shadow: 0 4px 14px rgba(15, 23, 42, 0.04) !important;
+}
+.scene-image {
+    min-height: 260px;
+    padding: 10px !important;
+}
+.scene-image > div,
+.scene-image img,
+.scene-image button,
+.scene-image [class*="image"],
+.scene-image [class*="wrap"],
+.scene-image [class*="frame"],
+.scene-image [class*="preview"] {
+    border: none !important;
+    box-shadow: none !important;
+    background: transparent !important;
+}
+.scene-image img {
+    width: 100%;
+    height: 100%;
+    object-fit: contain !important;
+    border-radius: 10px;
+    padding: 4px;
+    background: #ffffff !important;
+}
+"""
+
+# ============================================================
+# 全局游戏实例（每个会话独立）
+# ============================================================
+
+# 使用 Gradio State 管理每个用户的游戏状态
+# 这里先定义工厂函数
+
+
+def create_new_game(player_name: str = "旅人") -> dict:
+    """创建新游戏实例，返回包含所有引擎的字典"""
+    game_state = GameState(player_name=player_name)
+    nlu = NLUEngine(game_state)
+    story = StoryEngine(game_state, enable_rule_text_polish=True)
+    return {
+        "game_state": game_state,
+        "nlu": nlu,
+        "story": story,
+        "current_options": [],
+        "started": False,
+        **create_session_metadata(),
+    }
+
+
+def _json_safe(value):
+    """Convert nested values into JSON-serializable data for logs."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {str(key): _json_safe(val) for key, val in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_json_safe(item) for item in value]
+    if hasattr(value, "model_dump"):
+        return _json_safe(value.model_dump())
+    return str(value)
+
+
+def _build_state_snapshot(gs: GameState) -> dict:
+    """Build a compact state snapshot for reproducible evaluation logs."""
+    active_quests = []
+    effective_stats = gs.get_effective_player_stats()
+    equipment_bonuses = gs.get_equipment_stat_bonuses()
+    environment_snapshot = gs.get_environment_snapshot(limit=3)
+    for quest in gs.world.quests.values():
+        if quest.status == "active":
+            active_quests.append(
+                {
+                    "quest_id": quest.quest_id,
+                    "title": quest.title,
+                    "status": quest.status,
+                    "objectives": _json_safe(quest.objectives),
+                }
+            )
+
+    return {
+        "turn": gs.turn,
+        "game_mode": gs.game_mode,
+        "location": gs.player.location,
+        "scene": gs.world.current_scene,
+        "day": gs.world.day_count,
+        "time_of_day": gs.world.time_of_day,
+        "weather": gs.world.weather,
+        "light_level": gs.world.light_level,
+        "environment": _json_safe(environment_snapshot),
+        "player": {
+            "name": gs.player.name,
+            "level": gs.player.level,
+            "hp": gs.player.hp,
+            "max_hp": gs.player.max_hp,
+            "mp": gs.player.mp,
+            "max_mp": gs.player.max_mp,
+            "attack": gs.player.attack,
+            "defense": gs.player.defense,
+            "speed": gs.player.speed,
+            "luck": gs.player.luck,
+            "perception": gs.player.perception,
+            "gold": gs.player.gold,
+            "morale": gs.player.morale,
+            "sanity": gs.player.sanity,
+            "hunger": gs.player.hunger,
+            "karma": gs.player.karma,
+            "effective_stats": _json_safe(effective_stats),
+            "equipment_bonuses": _json_safe(equipment_bonuses),
+            "inventory": list(gs.player.inventory),
+            "equipment": copy.deepcopy(gs.player.equipment),
+            "skills": list(gs.player.skills),
+            "status_effects": [effect.name for effect in gs.player.status_effects],
+        },
+        "active_quests": active_quests,
+        "event_log_size": len(gs.event_log),
+    }
+
+
+def _record_interaction_log(
+    game_session: dict,
+    *,
+    input_source: str,
+    user_input: str,
+    intent_result: dict | None,
+    output_text: str,
+    latency_ms: float,
+    nlu_latency_ms: float | None = None,
+    generation_latency_ms: float | None = None,
+    final_result: dict | None = None,
+    selected_option: dict | None = None,
+):
+    """Append a structured interaction log without affecting gameplay."""
+    if not game_session or "game_state" not in game_session:
+        return
+
+    final_result = final_result or {}
+    telemetry = _json_safe(final_result.get("telemetry", {})) or {}
+    record = {
+        "input_source": input_source,
+        "user_input": user_input,
+        "selected_option": _json_safe(selected_option),
+        "nlu_result": _json_safe(intent_result),
+        "latency_ms": round(latency_ms, 2),
+        "nlu_latency_ms": None if nlu_latency_ms is None else round(nlu_latency_ms, 2),
+        "generation_latency_ms": None if generation_latency_ms is None else round(generation_latency_ms, 2),
+        "used_fallback": bool(telemetry.get("used_fallback", False)),
+        "fallback_reason": telemetry.get("fallback_reason"),
+        "engine_mode": telemetry.get("engine_mode"),
+        "state_changes": _json_safe(final_result.get("state_changes", {})),
+        "change_log": _json_safe(final_result.get("change_log", [])),
+        "consistency_issues": _json_safe(final_result.get("consistency_issues", [])),
+        "output_text": output_text,
+        "story_text": final_result.get("story_text"),
+        "options": _json_safe(final_result.get("options", game_session.get("current_options", []))),
+        "post_turn_snapshot": _build_state_snapshot(game_session["game_state"]),
+    }
+
+    try:
+        append_turn_log(game_session, record)
+    except Exception as exc:
+        logger.warning(f"Failed to append interaction log: {exc}")
+
+
+def _build_option_intent(selected_option: dict) -> dict:
+    """Represent button clicks in the same schema as free-text NLU output."""
+    option_text = selected_option.get("text", "")
+    return {
+        "intent": selected_option.get("action_type", "EXPLORE"),
+        "target": selected_option.get("target"),
+        "details": option_text,
+        "raw_input": option_text,
+        "parser_source": "option_click",
+    }
+
+
+def _get_scene_image_value(gs: GameState) -> str | None:
+    focus_npc = getattr(gs, "last_interacted_npc", None)
+    return get_scene_image_path(gs, focus_npc=focus_npc)
+
+
+def _get_scene_image_update(gs: GameState):
+    image_value = _get_scene_image_value(gs)
+    return gr.update(value=image_value, visible=bool(image_value))
+
+
+def _build_map_graph_data(gs: GameState) -> dict:
+    """基于已发现地点与连接关系构建地图拓扑数据。"""
+    world_locations = getattr(getattr(gs, "world", None), "locations", {}) or {}
+    discovered = list(getattr(getattr(gs, "world", None), "discovered_locations", []) or [])
+    history = list(getattr(gs, "location_history", []) or [])
+
+    current_location = str(getattr(gs, "current_location", None) or "").strip()
+    if not current_location:
+        current_location = str(getattr(getattr(gs, "player", None), "location", None) or "未知之地")
+
+    visible_set: set[str] = set(discovered) | set(history)
+    if current_location:
+        visible_set.add(current_location)
+
+    # 使用世界注册顺序保证地图输出稳定，便于玩家快速扫描。
+    ordered_nodes: list[str] = [name for name in world_locations.keys() if name in visible_set]
+    for name in discovered + history + [current_location]:
+        if name and name in visible_set and name not in ordered_nodes:
+            ordered_nodes.append(name)
+
+    visited_set = set(history)
+    if current_location:
+        visited_set.add(current_location)
+
+    adjacency: dict[str, list[str]] = {}
+    for node in ordered_nodes:
+        loc_info = world_locations.get(node)
+        if not loc_info:
+            adjacency[node] = []
+            continue
+        neighbors = []
+        for neighbor in list(getattr(loc_info, "connected_to", []) or []):
+            if neighbor in visible_set and neighbor != node:
+                neighbors.append(neighbor)
+        adjacency[node] = neighbors
+
+    node_state: dict[str, str] = {}
+    for node in ordered_nodes:
+        if node == current_location:
+            node_state[node] = "current"
+        elif node in visited_set:
+            node_state[node] = "visited"
+        else:
+            node_state[node] = "known"
+
+    return {
+        "current_location": current_location,
+        "nodes": ordered_nodes,
+        "adjacency": adjacency,
+        "node_state": node_state,
+    }
+
+
+def _build_location_hover_text(gs: GameState, location_name: str) -> str:
+    """构造地点 hover 提示：展示 NPC 与怪物。"""
+    world = getattr(gs, "world", None)
+    locations = getattr(world, "locations", {}) or {}
+    npcs = getattr(world, "npcs", {}) or {}
+    loc = locations.get(location_name)
+    if not loc:
+        return f"{location_name}\nNPC: 无\n怪物: 无"
+
+    npc_names: set[str] = set(getattr(loc, "npcs_present", []) or [])
+    for npc in npcs.values():
+        if getattr(npc, "location", None) == location_name and getattr(npc, "is_alive", True):
+            npc_names.add(getattr(npc, "name", ""))
+    npc_names = {name for name in npc_names if name}
+
+    enemy_names = [str(name) for name in list(getattr(loc, "enemies", []) or []) if str(name)]
+    npc_text = "、".join(sorted(npc_names)) if npc_names else "无"
+    enemy_text = "、".join(enemy_names) if enemy_names else "无"
+    return f"{location_name}\nNPC: {npc_text}\n怪物: {enemy_text}"
+
+
+def _truncate_map_label(name: str, max_len: int = 8) -> str:
+    text = str(name or "")
+    return text if len(text) <= max_len else f"{text[:max_len]}..."
+
+
+def _build_fixed_branch_layout(nodes: list[str], adjacency: dict[str, list[str]]) -> dict[str, tuple[int, int]]:
+    """固定起点的分层布局：保持总体顺序稳定，同时展示分支。"""
+    if not nodes:
+        return {}
+
+    node_set = set(nodes)
+    layers: dict[str, int] = {}
+
+    def _bfs(seed: str, base_layer: int) -> None:
+        if seed not in node_set or seed in layers:
+            return
+        queue: list[str] = [seed]
+        layers[seed] = base_layer
+        cursor = 0
+        while cursor < len(queue):
+            node = queue[cursor]
+            cursor += 1
+            next_layer = layers[node] + 1
+            for nxt in adjacency.get(node, []):
+                if nxt in node_set and nxt not in layers:
+                    layers[nxt] = next_layer
+                    queue.append(nxt)
+
+    # 第一出现地点作为固定起点，避免因当前位置变化而重排。
+    _bfs(nodes[0], 0)
+    for name in nodes:
+        if name not in layers:
+            base = (max(layers.values()) + 1) if layers else 0
+            _bfs(name, base)
+
+    level_nodes: dict[int, list[str]] = {}
+    for name in nodes:
+        level = layers.get(name, 0)
+        level_nodes.setdefault(level, []).append(name)
+
+    positions: dict[str, tuple[int, int]] = {}
+    for col_idx, level in enumerate(sorted(level_nodes.keys())):
+        for row_idx, name in enumerate(level_nodes[level]):
+            positions[name] = (col_idx, row_idx)
+    return positions
+
+
+def _render_text_map(gs: GameState | None) -> str:
+    """拓扑地图：从左到右显示地点关系图。"""
+    if gs is None:
+        return "地图关系图\n（未开始）"
+
+    graph = _build_map_graph_data(gs)
+    nodes = graph["nodes"]
+    adjacency = graph["adjacency"]
+    node_state = graph["node_state"]
+    current_location = graph["current_location"]
+
+    if not nodes:
+        current = current_location or "未知之地"
+        return f"地图关系图\n当前位置：{current}"
+
+    positions = _build_fixed_branch_layout(nodes, adjacency)
+    if not positions:
+        return "地图关系图\n（暂无可显示节点）"
+
+    node_width = 110
+    node_height = 34
+    col_gap = 140
+    row_gap = 50
+    x_margin = 16
+    y_margin = 16
+
+    max_col = max(col for col, _ in positions.values())
+    max_row = max(row for _, row in positions.values())
+    canvas_width = x_margin * 2 + max_col * col_gap + node_width
+    canvas_height = y_margin * 2 + max_row * row_gap + node_height
+    canvas_height = max(canvas_height, 74)
+
+    node_boxes: dict[str, tuple[int, int, int, int]] = {}
+    centers: dict[str, tuple[int, int]] = {}
+    for name, (col, row) in positions.items():
+        x = x_margin + col * col_gap
+        y = y_margin + row * row_gap
+        node_boxes[name] = (x, y, node_width, node_height)
+        centers[name] = (x + node_width // 2, y + node_height // 2)
+
+    edge_pairs: set[tuple[str, str]] = set()
+    for source, neighbors in adjacency.items():
+        for target in neighbors:
+            if source in positions and target in positions and source != target:
+                edge_pairs.add(tuple(sorted((source, target))))
+
+    edge_svg: list[str] = []
+
+    def _segment_hits_box_horizontal(y: float, x_start: float, x_end: float, box: tuple[int, int, int, int]) -> bool:
+        bx, by, bw, bh = box
+        left = min(x_start, x_end)
+        right = max(x_start, x_end)
+        return (by + 1) <= y <= (by + bh - 1) and not (right <= bx + 1 or left >= bx + bw - 1)
+
+    def _segment_hits_box_vertical(x: float, y_start: float, y_end: float, box: tuple[int, int, int, int]) -> bool:
+        bx, by, bw, bh = box
+        top = min(y_start, y_end)
+        bottom = max(y_start, y_end)
+        return (bx + 1) <= x <= (bx + bw - 1) and not (bottom <= by + 1 or top >= by + bh - 1)
+
+    for source, target in sorted(edge_pairs):
+        sx, sy, sw, sh = node_boxes[source]
+        tx, ty, tw, th = node_boxes[target]
+        source_exit_x = sx + sw
+        source_exit_y = sy + sh / 2
+        target_entry_x = tx
+        target_entry_y = ty + th / 2
+
+        mid_x = (source_exit_x + target_entry_x) / 2
+        needs_detour = False
+        for name, box in node_boxes.items():
+            if name in {source, target}:
+                continue
+            if (
+                _segment_hits_box_horizontal(source_exit_y, source_exit_x, mid_x, box)
+                or _segment_hits_box_vertical(mid_x, source_exit_y, target_entry_y, box)
+                or _segment_hits_box_horizontal(target_entry_y, mid_x, target_entry_x, box)
+            ):
+                needs_detour = True
+                break
+
+        if not needs_detour:
+            points = (
+                f"{source_exit_x},{source_exit_y} "
+                f"{mid_x},{source_exit_y} "
+                f"{mid_x},{target_entry_y} "
+                f"{target_entry_x},{target_entry_y}"
+            )
+        else:
+            # 局部上绕：仅在必要时走上方，减少杂乱感同时避免压到节点。
+            route_y = max(4, min(source_exit_y, target_entry_y) - node_height / 2 - 10)
+            route_left_x = source_exit_x + 6
+            route_right_x = target_entry_x - 6
+            points = (
+                f"{source_exit_x},{source_exit_y} "
+                f"{route_left_x},{source_exit_y} "
+                f"{route_left_x},{route_y} "
+                f"{route_right_x},{route_y} "
+                f"{route_right_x},{target_entry_y} "
+                f"{target_entry_x},{target_entry_y}"
+            )
+
+        edge_svg.append(
+            f"<polyline points='{points}' "
+            "fill='none' stroke='#94a3b8' stroke-width='1.7' "
+            "stroke-linecap='round' stroke-linejoin='round' />"
+        )
+
+    node_svg: list[str] = []
+    for name in nodes:
+        col, row = positions[name]
+        x = x_margin + col * col_gap
+        y = y_margin + row * row_gap
+        state = node_state.get(name, "known")
+        escaped_name = html.escape(_truncate_map_label(name))
+        hover_text = html.escape(_build_location_hover_text(gs, name))
+
+        if state == "current":
+            fill = "#fff7ed"
+            stroke = "#f97316"
+            text_color = "#9a3412"
+            stroke_width = 1.8
+            display_name = escaped_name
+        elif state == "visited":
+            fill = "#f1f5f9"
+            stroke = "#64748b"
+            text_color = "#334155"
+            stroke_width = 1.4
+            display_name = escaped_name
+        else:
+            fill = "#ffffff"
+            stroke = "#cbd5e1"
+            text_color = "#334155"
+            stroke_width = 1.2
+            display_name = escaped_name
+
+        rect_class_attr = " class='map-current-node'" if state == "current" else ""
+        node_svg.append(
+            "<g cursor='help'>"
+            f"<title>{hover_text}</title>"
+            f"<rect x='{x}' y='{y}' width='{node_width}' height='{node_height}' "
+            f"rx='8' ry='8' fill='{fill}' stroke='{stroke}' stroke-width='{stroke_width}'{rect_class_attr} />"
+            f"<text x='{x + node_width / 2}' y='{y + node_height / 2 + 5}' "
+            "text-anchor='middle' font-size='11.5' font-family='Microsoft YaHei UI, Noto Sans SC, sans-serif' "
+            f"fill='{text_color}'>{display_name}</text>"
+            "</g>"
+        )
+
+    svg = (
+        f"<svg width='{canvas_width}' height='{canvas_height}' viewBox='0 0 {canvas_width} {canvas_height}' "
+        "xmlns='http://www.w3.org/2000/svg'>"
+        "<style>"
+        "@keyframes mapNodePulse{"
+        "0%{fill:#fff7ed;stroke:#f97316;stroke-width:1.8;opacity:0.9;}"
+        "50%{fill:#fdba74;stroke:#c2410c;stroke-width:1.8;opacity:1;}"
+        "100%{fill:#fff7ed;stroke:#f97316;stroke-width:1.8;opacity:0.9;}"
+        "}"
+        ".map-current-node{animation:mapNodePulse 1.2s ease-in-out infinite;}"
+        "</style>"
+        + "".join(edge_svg)
+        + "".join(node_svg)
+        + "</svg>"
+    )
+
+    return (
+        "<div style='font-size:0.9em;'>"
+        "<details>"
+        "<summary style='cursor:pointer;font-weight:700;'>展开地图关系图</summary>"
+        "<div style='font-size:0.8em;color:#475569;margin:8px 0 6px 0;'>"
+        "鼠标悬停于地点格可查看NPC与怪物。"
+        "</div>"
+        "<div style='overflow-x:auto;padding-bottom:2px;'>"
+        + svg
+        + "</div>"
+        "</details>"
+        "</div>"
+    )
+
+
+def restart_game() -> tuple:
+    """
+    重启冒险：清空所有数据，回到初始输入名称阶段。
+
+    Returns:
+        (空聊天历史, 初始状态面板, 隐藏选项按钮×3, 空游戏会话,
+         禁用文本输入框, 重置角色名称)
+    """
+    loading = _get_loading_button_updates()
+    return (
+        [],                                                          # 清空聊天历史
+        _format_world_info_panel(None),                              # 重置世界信息
+        "## 等待开始...\n\n请输入角色名称并点击「开始冒险」",         # 重置状态面板
+        "地图关系图\n（未开始）",                                      # 清空地图
+        gr.update(value=None, visible=False),                        # 清空场景图片
+        *loading,                                                    # 占位选项按钮
+        {},                                                          # 清空游戏会话
+        gr.update(value="", interactive=False),                       # 禁用并清空文本输入
+        gr.update(value="旅人"),                                      # 重置角色名称
+    )
+
+
+# ============================================================
+# 核心交互函数
+# ============================================================
+
+
+def start_game(player_name: str, game_session: dict):
+    """
+    开始新游戏：流式生成开场叙事。
+
+    使用生成器 yield 实现流式输出，让用户看到文字逐步出现。
+    """
+    if not player_name.strip():
+        player_name = "旅人"
+
+    # 创建新游戏
+    game_session = create_new_game(player_name)
+    game_session["started"] = True
+
+    # 初始 yield：显示加载状态，按钮保持可见但禁用
+    chat_history = [{"role": "assistant", "content": "⏳ 正在生成开场..."}]
+    world_info_text = _format_world_info_panel(game_session["game_state"])
+    status_text = _format_status_panel(game_session["game_state"])
+    loading = _get_loading_button_updates()
+
+    yield (
+        chat_history,
+        world_info_text,
+        status_text,
+        _render_text_map(game_session["game_state"]),
+        _get_scene_image_update(game_session["game_state"]),
+        *loading,
+        game_session,
+        gr.update(interactive=False),
+    )
+
+    # 流式生成开场（选项仅在流结束后从 final 事件中提取，流式期间不解析选项）
+    turn_started = perf_counter()
+    story_text = ""
+    final_result = None
+
+    for update in game_session["story"].generate_opening_stream():
+        if update["type"] == "story_chunk":
+            story_text = update["text"]
+            chat_history[-1]["content"] = story_text
+            yield (
+                chat_history,
+                world_info_text,
+                status_text,
+                _render_text_map(game_session["game_state"]),
+                _get_scene_image_update(game_session["game_state"]),
+                *loading,
+                game_session,
+                gr.update(interactive=False),
+            )
+        elif update["type"] == "final":
+            final_result = update
+
+    generation_latency_ms = (perf_counter() - turn_started) * 1000
+
+    # ★ 只在数据流完全结束后，从 final_result 中提取选项
+    if final_result:
+        story_text = final_result.get("story_text", story_text)
+        options = final_result.get("options", [])
+    else:
+        options = []
+
+    # ★ 安全兜底：强制确保恰好 3 个选项
+    options = _finalize_session_options(options)
+
+    # 最终 yield：显示完整文本 + 选项 + 启用按钮
+    game_session["current_options"] = options
+    full_message = story_text
+    if not final_result:
+        final_result = {
+            "story_text": story_text,
+            "options": options,
+            "state_changes": {},
+            "change_log": [],
+            "consistency_issues": [],
+            "telemetry": {
+                "engine_mode": "opening_app",
+                "used_fallback": True,
+                "fallback_reason": "missing_final_event",
+            },
+        }
+
+    chat_history[-1]["content"] = full_message
+    world_info_text = _format_world_info_panel(game_session["game_state"])
+    status_text = _format_status_panel(game_session["game_state"])
+    btn_updates = _get_button_updates(options)
+    _record_interaction_log(
+        game_session,
+        input_source="system_opening",
+        user_input="",
+        intent_result=None,
+        output_text=full_message,
+        latency_ms=generation_latency_ms,
+        generation_latency_ms=generation_latency_ms,
+        final_result=final_result,
+    )
+
+    yield (
+        chat_history,
+        world_info_text,
+        status_text,
+        _render_text_map(game_session["game_state"]),
+        _get_scene_image_update(game_session["game_state"]),
+        *btn_updates,
+        game_session,
+        gr.update(interactive=True),
+    )
+
+
+def process_user_input(user_input: str, chat_history: list, game_session: dict):
+    """
+    处理用户文本输入（流式版本）。
+
+    流程：
+    1. NLU 引擎解析意图
+    2. 叙事引擎流式生成故事
+    3. 逐步更新 UI
+    """
+    if not game_session or not game_session.get("started"):
+        chat_history = chat_history or []
+        chat_history.append({"role": "assistant", "content": "请先点击「开始冒险」按钮！"})
+        loading = _get_loading_button_updates()
+        yield (
+            chat_history,
+            _format_world_info_panel(None),
+            "",
+            "",
+            gr.update(value=None, visible=False),
+            *loading,
+            game_session,
+        )
+        return
+
+    if not user_input.strip():
+        btn_updates = _get_button_updates(game_session.get("current_options", []))
+        yield (
+            chat_history,
+            _format_world_info_panel(game_session["game_state"]),
+            _format_status_panel(game_session["game_state"]),
+            _render_text_map(game_session["game_state"]),
+            _get_scene_image_update(game_session["game_state"]),
+            *btn_updates,
+            game_session,
+        )
+        return
+
+    gs: GameState = game_session["game_state"]
+    nlu: NLUEngine = game_session["nlu"]
+    story: StoryEngine = game_session["story"]
+    turn_started = perf_counter()
+
+    # 检查游戏是否已结束
+    if gs.is_game_over():
+        chat_history.append({"role": "user", "content": user_input})
+        chat_history.append({"role": "assistant", "content": "游戏已结束。请点击「重新开始」按钮开始新的冒险。"})
+        restart_buttons = _get_button_updates(
+            [
+                {"id": 1, "text": "重新开始", "action_type": "RESTART"},
+            ]
+        )
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            _format_status_panel(gs),
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *restart_buttons,
+            game_session,
+        )
+        return
+
+    # 1. NLU 解析
+    nlu_started = perf_counter()
+    intent = nlu.parse_intent(user_input)
+    nlu_latency_ms = (perf_counter() - nlu_started) * 1000
+
+    # 1.5 预校验：立即驳回违反一致性的操作（不调用 LLM，不消耗回合）
+    is_valid, rejection_msg = gs.pre_validate_action(intent)
+    if not is_valid:
+        chat_history.append({"role": "user", "content": user_input})
+        options = game_session.get("current_options", [])
+        options = _finalize_session_options(options)
+        rejection_content = (
+            f"⚠️ **行动被驳回**：{rejection_msg}\n\n"
+            f"请重新选择行动，或输入其他指令。"
+        )
+        chat_history.append({"role": "assistant", "content": rejection_content})
+        rejection_result = {
+            "story_text": rejection_content,
+            "options": options,
+            "state_changes": {},
+            "change_log": [],
+            "consistency_issues": [],
+            "telemetry": {
+                "engine_mode": "pre_validation",
+                "used_fallback": False,
+                "fallback_reason": None,
+            },
+        }
+        _record_interaction_log(
+            game_session,
+            input_source="text_input",
+            user_input=user_input,
+            intent_result=intent,
+            output_text=rejection_content,
+            latency_ms=(perf_counter() - turn_started) * 1000,
+            nlu_latency_ms=nlu_latency_ms,
+            generation_latency_ms=0.0,
+            final_result=rejection_result,
+        )
+        btn_updates = _get_button_updates(options)
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            _format_status_panel(gs),
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
+        return
+
+    # 2. 添加用户消息 + 空的 assistant 消息（用于流式填充）
+    chat_history.append({"role": "user", "content": user_input})
+    chat_history.append({"role": "assistant", "content": "⏳ 正在生成..."})
+
+    # 按钮保持可见但禁用，防止流式期间点击
+    loading = _get_loading_button_updates(
+        max(len(game_session.get("current_options", [])), MIN_OPTION_BUTTONS)
+    )
+    yield (
+        chat_history,
+        _format_world_info_panel(gs),
+        _format_status_panel(gs),
+        _render_text_map(gs),
+        _get_scene_image_update(gs),
+        *loading,
+        game_session,
+    )
+
+    # 3. 流式生成故事
+    generation_started = perf_counter()
+    final_result = None
+    for update in story.generate_story_stream(intent):
+        if update["type"] == "story_chunk":
+            chat_history[-1]["content"] = update["text"]
+            yield (
+                chat_history,
+                _format_world_info_panel(gs),
+                _format_status_panel(gs),
+                _render_text_map(gs),
+                _get_scene_image_update(gs),
+                *loading,
+                game_session,
+            )
+        elif update["type"] == "final":
+            final_result = update
+
+    generation_latency_ms = (perf_counter() - generation_started) * 1000
+
+    # 4. 最终更新：完整文本 + 状态变化 + 选项 + 按钮
+    if final_result:
+        # ★ 安全兜底：强制确保恰好 3 个选项
+        options = _finalize_session_options(final_result.get("options", []))
+        game_session["current_options"] = options
+
+        change_log = final_result.get("change_log", [])
+        log_text = ""
+        if change_log:
+            log_text = "\n".join(f"  {c}" for c in change_log)
+            log_text = f"\n\n**状态变化：**\n{log_text}"
+
+        issues = final_result.get("consistency_issues", [])
+        issues_text = ""
+        if issues:
+            issues_text = "\n".join(f"  {i}" for i in issues)
+            issues_text = f"\n\n**一致性提示：**\n{issues_text}"
+
+        full_message = f"{final_result['story_text']}{log_text}{issues_text}"
+        chat_history[-1]["content"] = full_message
+
+        status_text = _format_status_panel(gs)
+        btn_updates = _get_button_updates(options)
+        _record_interaction_log(
+            game_session,
+            input_source="text_input",
+            user_input=user_input,
+            intent_result=intent,
+            output_text=full_message,
+            latency_ms=(perf_counter() - turn_started) * 1000,
+            nlu_latency_ms=nlu_latency_ms,
+            generation_latency_ms=generation_latency_ms,
+            final_result=final_result,
+        )
+
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            status_text,
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
+    else:
+        # ★ 兜底：final_result 为空，说明流式生成未产生 final 事件
+        logger.warning("流式生成未产生 final 事件，使用兜底文本")
+        fallback_text = "你环顾四周，思考着接下来该做什么..."
+        fallback_options = _finalize_session_options([])
+        game_session["current_options"] = fallback_options
+
+        full_message = fallback_text
+        fallback_result = {
+            "story_text": fallback_text,
+            "options": fallback_options,
+            "state_changes": {},
+            "change_log": [],
+            "consistency_issues": [],
+            "telemetry": {
+                "engine_mode": "app_fallback",
+                "used_fallback": True,
+                "fallback_reason": "missing_final_event",
+            },
+        }
+        chat_history[-1]["content"] = full_message
+
+        status_text = _format_status_panel(gs)
+        btn_updates = _get_button_updates(fallback_options)
+        _record_interaction_log(
+            game_session,
+            input_source="text_input",
+            user_input=user_input,
+            intent_result=intent,
+            output_text=full_message,
+            latency_ms=(perf_counter() - turn_started) * 1000,
+            nlu_latency_ms=nlu_latency_ms,
+            generation_latency_ms=generation_latency_ms,
+            final_result=fallback_result,
+        )
+
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            status_text,
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
+        return
+
+
+def process_option_click(option_idx: int, chat_history: list, game_session: dict):
+    """
+    处��玩家点击选项按钮（流式版本）。
+
+    Args:
+        option_idx: 选项索引 (0-5)
+    """
+    if not game_session or not game_session.get("started"):
+        chat_history = chat_history or []
+        chat_history.append({"role": "assistant", "content": "请先点击「开始冒险」按钮！"})
+        loading = _get_loading_button_updates()
+        yield (
+            chat_history,
+            _format_world_info_panel(None),
+            "",
+            "",
+            gr.update(value=None, visible=False),
+            *loading,
+            game_session,
+        )
+        return
+
+    options = game_session.get("current_options", [])
+    if option_idx >= len(options):
+        btn_updates = _get_button_updates(options)
+        yield (
+            chat_history,
+            _format_world_info_panel(game_session["game_state"]),
+            _format_status_panel(game_session["game_state"]),
+            _render_text_map(game_session["game_state"]),
+            _get_scene_image_update(game_session["game_state"]),
+            *btn_updates,
+            game_session,
+        )
+        return
+
+    selected_option = options[option_idx]
+    gs: GameState = game_session["game_state"]
+    story: StoryEngine = game_session["story"]
+    option_intent = _build_option_intent(selected_option)
+    turn_started = perf_counter()
+
+    # 检查特殊选项：退出背包（不消耗回合）
+    if selected_option.get("action_type") == "BACKPACK_EXIT":
+        chat_history.append({"role": "user", "content": f"选择: {selected_option['text']}"})
+        chat_history.append({"role": "assistant", "content": "你合上背包，把注意力重新放回当前局势。"})
+        restored_options = game_session.pop("backpack_return_options", None)
+        if not isinstance(restored_options, list):
+            restored_options = _finalize_session_options([])
+        game_session["current_options"] = restored_options
+        btn_updates = _get_button_updates(restored_options)
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            _format_status_panel(gs),
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
+        return
+
+    from_backpack_menu = str(selected_option.get("menu", "")) == "backpack"
+
+    # 检查特殊选项：重新开始
+    if selected_option.get("action_type") == "RESTART":
+        # 重新开始时使用流式开场
+        game_session = create_new_game(gs.player.name)
+        game_session["started"] = True
+
+        chat_history = [{"role": "assistant", "content": "⏳ 正在重新生成开场..."}]
+        world_info_text = _format_world_info_panel(game_session["game_state"])
+        status_text = _format_status_panel(game_session["game_state"])
+        loading = _get_loading_button_updates()
+
+        yield (
+            chat_history,
+            world_info_text,
+            status_text,
+            _render_text_map(game_session["game_state"]),
+            _get_scene_image_update(game_session["game_state"]),
+            *loading,
+            game_session,
+        )
+
+        story_text = ""
+        restart_final = None
+
+        for update in game_session["story"].generate_opening_stream():
+            if update["type"] == "story_chunk":
+                story_text = update["text"]
+                chat_history[-1]["content"] = story_text
+                yield (
+                    chat_history,
+                    world_info_text,
+                    status_text,
+                    _render_text_map(game_session["game_state"]),
+                    _get_scene_image_update(game_session["game_state"]),
+                    *loading,
+                    game_session,
+                )
+            elif update["type"] == "final":
+                restart_final = update
+
+        # ★ 只在流完全结束后提取选项
+        if restart_final:
+            story_text = restart_final.get("story_text", story_text)
+            restart_options = restart_final.get("options", [])
+        else:
+            restart_options = []
+
+        # ★ 安全兜底：强制确保恰好 3 个选项
+        restart_options = _finalize_session_options(restart_options)
+        game_session["current_options"] = restart_options
+        full_message = story_text
+        chat_history[-1]["content"] = full_message
+
+        status_text = _format_status_panel(game_session["game_state"])
+        btn_updates = _get_button_updates(restart_options)
+
+        yield (
+            chat_history,
+            _format_world_info_panel(game_session["game_state"]),
+            status_text,
+            _render_text_map(game_session["game_state"]),
+            _get_scene_image_update(game_session["game_state"]),
+            *btn_updates,
+            game_session,
+        )
+        return
+
+    # 检查特殊选项：退出
+    if selected_option.get("action_type") == "QUIT":
+        chat_history.append({"role": "user", "content": f"选择: {selected_option['text']}"})
+        chat_history.append({"role": "assistant", "content": "感谢游玩 StoryWeaver！\n你的冒险到此结束，但故事永远不会真正终结...\n\n点击「开始冒险」可以重新开始。"})
+        quit_buttons = _get_button_updates(
+            [
+                {"id": 1, "text": "重新开始", "action_type": "RESTART"},
+            ]
+        )
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            _format_status_panel(gs),
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *quit_buttons,
+            game_session,
+        )
+        return
+
+    # 正常选项处理：流式生成
+    chat_history.append({"role": "user", "content": f"选择: {selected_option['text']}"})
+    chat_history.append({"role": "assistant", "content": "⏳ 正在生成..."})
+
+    # 按钮保持可见但禁用
+    loading = _get_loading_button_updates(max(len(options), MIN_OPTION_BUTTONS))
+    yield (
+        chat_history,
+        _format_world_info_panel(gs),
+        _format_status_panel(gs),
+        _render_text_map(gs),
+        _get_scene_image_update(gs),
+        *loading,
+        game_session,
+    )
+
+    generation_started = perf_counter()
+    final_result = None
+    for update in story.process_option_selection_stream(selected_option):
+        if update["type"] == "story_chunk":
+            chat_history[-1]["content"] = update["text"]
+            yield (
+                chat_history,
+                _format_world_info_panel(gs),
+                _format_status_panel(gs),
+                _render_text_map(gs),
+                _get_scene_image_update(gs),
+                *loading,
+                game_session,
+            )
+        elif update["type"] == "final":
+            final_result = update
+
+    generation_latency_ms = (perf_counter() - generation_started) * 1000
+
+    if final_result:
+        # 背包菜单内执行使用/装备后，继续停留在背包菜单
+        if from_backpack_menu:
+            options = _build_backpack_options(gs)
+        else:
+            options = _finalize_session_options(final_result.get("options", []))
+        game_session["current_options"] = options
+
+        change_log = final_result.get("change_log", [])
+        log_text = ""
+        if change_log:
+            log_text = "\n".join(f"  {c}" for c in change_log)
+            log_text = f"\n\n**状态变化：**\n{log_text}"
+
+        full_message = f"{final_result['story_text']}{log_text}"
+        chat_history[-1]["content"] = full_message
+
+        status_text = _format_status_panel(gs)
+        btn_updates = _get_button_updates(options)
+        _record_interaction_log(
+            game_session,
+            input_source="option_click",
+            user_input=selected_option.get("text", ""),
+            intent_result=option_intent,
+            output_text=full_message,
+            latency_ms=(perf_counter() - turn_started) * 1000,
+            generation_latency_ms=generation_latency_ms,
+            final_result=final_result,
+            selected_option=selected_option,
+        )
+
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            status_text,
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
+    else:
+        # ★ 兜底：final_result 为空，说明流式生成未产生 final 事件
+        logger.warning("[选项点击] 流式生成未产生 final 事件，使用兜底文本")
+        if from_backpack_menu:
+            fallback_text = "你整理了一下背包，却一时没想好先使用哪件物品。"
+            fallback_options = _build_backpack_options(gs)
+        else:
+            fallback_text = "你环顾四周，思考着接下来该做什么..."
+            fallback_options = _finalize_session_options([])
+        game_session["current_options"] = fallback_options
+
+        full_message = fallback_text
+        fallback_result = {
+            "story_text": fallback_text,
+            "options": fallback_options,
+            "state_changes": {},
+            "change_log": [],
+            "consistency_issues": [],
+            "telemetry": {
+                "engine_mode": "app_fallback",
+                "used_fallback": True,
+                "fallback_reason": "missing_final_event",
+            },
+        }
+        chat_history[-1]["content"] = full_message
+
+        status_text = _format_status_panel(gs)
+        btn_updates = _get_button_updates(fallback_options)
+        _record_interaction_log(
+            game_session,
+            input_source="option_click",
+            user_input=selected_option.get("text", ""),
+            intent_result=option_intent,
+            output_text=full_message,
+            latency_ms=(perf_counter() - turn_started) * 1000,
+            generation_latency_ms=generation_latency_ms,
+            final_result=fallback_result,
+            selected_option=selected_option,
+        )
+
+        yield (
+            chat_history,
+            _format_world_info_panel(gs),
+            status_text,
+            _render_text_map(gs),
+            _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
+        return
+
+
+# ============================================================
+# UI 辅助函数
+# ============================================================
+
+
+MIN_OPTION_BUTTONS = 3
+MAX_OPTION_BUTTONS = 6
+
+# 兜底默认选项（当解析出的选项为空时使用）
+_FALLBACK_BUTTON_OPTIONS = [
+    {"id": 1, "text": "查看周围", "action_type": "EXPLORE"},
+    {"id": 2, "text": "等待一会", "action_type": "REST"},
+    {"id": 3, "text": "检查状态", "action_type": "EXPLORE"},
+]
+
+
+def _normalize_options(
+    options: list[dict],
+    *,
+    minimum: int = 0,
+    maximum: int = MAX_OPTION_BUTTONS,
+) -> list[dict]:
+    """
+    规范化选项列表：
+    - 至多保留 maximum 个选项
+    - 仅当 minimum > 0 时补充兜底项
+    - 始终重新编号
+    """
+    if not isinstance(options, list):
+        options = []
+
+    normalized = [opt for opt in options if isinstance(opt, dict)][:maximum]
+
+    for fb in _FALLBACK_BUTTON_OPTIONS:
+        if len(normalized) >= minimum:
+            break
+        if not any(o.get("text") == fb["text"] for o in normalized):
+            normalized.append(fb.copy())
+
+    while len(normalized) < minimum:
+        normalized.append({
+            "id": len(normalized) + 1,
+            "text": "继续探索",
+            "action_type": "EXPLORE",
+        })
+
+    for i, opt in enumerate(normalized[:maximum], 1):
+        if isinstance(opt, dict):
+            opt["id"] = i
+
+    return normalized[:maximum]
+
+
+def _finalize_session_options(options: list[dict]) -> list[dict]:
+    minimum = MIN_OPTION_BUTTONS if not options else 0
+    return _normalize_options(options, minimum=minimum)
+
+
+def _format_options(options: list[dict]) -> str:
+    """将选项列表格式化为可读的文本（纯文字，绝不显示 JSON）"""
+    if not options:
+        return ""
+    lines = ["---", "**你的选择：**"]
+    for i, opt in enumerate(options):
+        # 安全提取：兼容 dict 和异常情况
+        if isinstance(opt, dict):
+            idx = opt.get("id", i + 1)
+            text = opt.get("text", "未知选项")
+        else:
+            idx = i + 1
+            text = str(opt)
+        lines.append(f"  **[{idx}]** {text}")
+    return "\n".join(lines)
+
+
+def _is_backpack_menu_active(options: list[dict]) -> bool:
+    return any(
+        isinstance(opt, dict)
+        and str(opt.get("action_type", "")).upper() == "BACKPACK_EXIT"
+        and str(opt.get("menu", "")) == "backpack"
+        for opt in (options or [])
+    )
+
+
+def _format_item_function(item_info) -> str:
+    if item_info is None:
+        return "功能未知"
+    if item_info.use_effect:
+        return f"效果：{item_info.use_effect}"
+    if item_info.stat_bonus:
+        bonus_text = "，".join(
+            f"{stat}{'+' if int(value) >= 0 else ''}{int(value)}"
+            for stat, value in item_info.stat_bonus.items()
+        )
+        return f"装备加成：{bonus_text}"
+    if item_info.lore_text:
+        return f"线索：{item_info.lore_text}"
+    return "暂无可用效果"
+
+
+def _build_backpack_options(gs: GameState) -> list[dict]:
+    inventory = list(gs.player.inventory)
+    if not inventory:
+        return [
+            {"id": 1, "text": "退出背包", "action_type": "BACKPACK_EXIT", "menu": "backpack"},
+        ]
+
+    inventory_order = list(dict.fromkeys(inventory))
+    equip_types = {"weapon", "armor", "accessory", "helmet", "boots"}
+
+    consumable_options: list[dict] = []
+    equip_options: list[dict] = []
+    for item_name in inventory_order:
+        item_info = gs.world.item_registry.get(item_name)
+
+        if item_info and gs.is_item_consumable(item_name):
+            consumable_options.append(
+                {
+                    "text": f"使用{item_name}",
+                    "action_type": "USE_ITEM",
+                    "target": item_name,
+                    "menu": "backpack",
+                }
+            )
+            continue
+
+        if item_info and item_info.item_type in equip_types:
+            equip_options.append(
+                {
+                    "text": f"装备{item_name}",
+                    "action_type": "EQUIP",
+                    "target": item_name,
+                    "menu": "backpack",
+                }
+            )
+
+    max_action_slots = MAX_OPTION_BUTTONS - 1
+    merged_actions = (consumable_options + equip_options)[:max_action_slots]
+    merged_actions.append(
+        {"text": "退出背包", "action_type": "BACKPACK_EXIT", "menu": "backpack"}
+    )
+    return _normalize_options(merged_actions, minimum=0, maximum=MAX_OPTION_BUTTONS)
+
+
+def _format_backpack_story(gs: GameState) -> str:
+    inventory = list(gs.player.inventory)
+    if not inventory:
+        return "你打开背包，里面空空如也。"
+
+    inventory_counter = Counter(inventory)
+    inventory_order = list(dict.fromkeys(inventory))
+    lines = ["你打开背包，快速检查随身物资："]
+    for item_name in inventory_order:
+        item_info = gs.world.item_registry.get(item_name)
+        quantity = inventory_counter.get(item_name, 1)
+        quantity_text = f"x{quantity} " if quantity > 1 else ""
+        description = item_info.description if item_info else "暂无描述"
+        function_text = _format_item_function(item_info)
+        lines.append(f"- {quantity_text}**{item_name}**：{description}（{function_text}）")
+    lines.append("\n你可以直接在下方选择“使用/装备”对应物品，或退出背包。")
+    return "\n".join(lines)
+
+
+def open_backpack(chat_history: list, game_session: dict):
+    chat_history = chat_history or []
+    if not game_session or not game_session.get("started"):
+        chat_history.append({"role": "assistant", "content": "请先点击「开始冒险」按钮！"})
+        loading = _get_loading_button_updates()
+        return (
+            chat_history,
+            _format_world_info_panel(None),
+            "",
+            "",
+            gr.update(value=None, visible=False),
+            *loading,
+            game_session,
+        )
+
+    gs: GameState = game_session["game_state"]
+    current_options = game_session.get("current_options", [])
+    if not _is_backpack_menu_active(current_options):
+        game_session["backpack_return_options"] = copy.deepcopy(current_options)
+
+    backpack_story = _format_backpack_story(gs)
+    backpack_options = _build_backpack_options(gs)
+    game_session["current_options"] = backpack_options
+
+    chat_history.append({"role": "user", "content": "打开背包"})
+    chat_history.append({"role": "assistant", "content": backpack_story})
+
+    _record_interaction_log(
+        game_session,
+        input_source="backpack_button",
+        user_input="打开背包",
+        intent_result={"intent": "OPEN_BACKPACK", "target": None},
+        output_text=backpack_story,
+        latency_ms=0.0,
+        generation_latency_ms=0.0,
+        final_result={
+            "story_text": backpack_story,
+            "options": backpack_options,
+            "state_changes": {},
+            "change_log": [],
+            "consistency_issues": [],
+            "telemetry": {
+                "engine_mode": "backpack_menu",
+                "used_fallback": False,
+                "fallback_reason": None,
+            },
+        },
+    )
+
+    btn_updates = _get_button_updates(backpack_options)
+    return (
+        chat_history,
+        _format_world_info_panel(gs),
+        _format_status_panel(gs),
+        _render_text_map(gs),
+        _get_scene_image_update(gs),
+        *btn_updates,
+        game_session,
+    )
+
+
+def _get_loading_button_updates(visible_count: int = MIN_OPTION_BUTTONS) -> list:
+    """返回加载中占位按钮更新，支持最多 6 个选项槽位。"""
+    visible_count = max(0, min(int(visible_count or 0), MAX_OPTION_BUTTONS))
+    updates = []
+    for index in range(MAX_OPTION_BUTTONS):
+        updates.append(
+            gr.update(
+                value="...",
+                visible=index < visible_count,
+                interactive=False,
+            )
+        )
+    return updates
+
+
+def _get_button_updates(options: list[dict]) -> list:
+    """从选项列表生成按钮更新，始终返回 6 个槽位。"""
+    options = _normalize_options(options, minimum=0)
+
+    updates = []
+    for i in range(MAX_OPTION_BUTTONS):
+        opt = options[i] if i < len(options) else None
+        if isinstance(opt, dict):
+            text = opt.get("text", "...")
+            visible = True
+        else:
+            text = "..."
+            visible = False
+        updates.append(gr.update(value=text, visible=visible, interactive=visible))
+    return updates
+
+
+def _format_status_panel(gs: GameState) -> str:
+    """格式化状态面板文本（双列 HTML 布局，减少滚动）"""
+    p = gs.player
+    w = gs.world
+    effective_stats = gs.get_effective_player_stats()
+    equipment_bonuses = gs.get_equipment_stat_bonuses()
+    env_snapshot = gs.get_environment_snapshot(limit=3)
+    survival_snapshot = gs.get_survival_state_snapshot()
+    scene_summary = gs.get_scene_summary().replace("\n", "<br>")
+    clock_display = gs.get_clock_display()
+
+    # 属性进度条
+    hp_bar = _progress_bar(p.hp, p.max_hp, "HP")
+    mp_bar = _progress_bar(p.mp, p.max_mp, "MP")
+    stamina_bar = _progress_bar(p.stamina, p.max_stamina, "体力")
+    hunger_bar = _progress_bar(p.hunger, 100, "饱食")
+    sanity_bar = _progress_bar(p.sanity, 100, "理智")
+    morale_bar = _progress_bar(p.morale, 100, "士气")
+
+    # 装备
+    slot_names = {
+        "weapon": "武器", "armor": "护甲", "accessory": "饰品",
+        "helmet": "头盔", "boots": "靴子",
+    }
+    equip_lines = []
+    for slot, item in p.equipment.items():
+        equip_lines.append(f"{slot_names.get(slot, slot)}: {item or '无'}")
+    equip_text = "<br>".join(equip_lines)
+
+    def render_stat(stat_key: str, label: str) -> str:
+        base_value = int(getattr(p, stat_key))
+        bonus_value = int(equipment_bonuses.get(stat_key, 0))
+        effective_value = int(effective_stats.get(stat_key, base_value))
+        if bonus_value > 0:
+            return f"{label}: {effective_value} <span style='color:#4a6;'>(+{bonus_value} 装备)</span>"
+        if bonus_value < 0:
+            return f"{label}: {effective_value} <span style='color:#b44;'>({bonus_value} 装备)</span>"
+        return f"{label}: {base_value}"
+
+    def badge(text: str, bg: str, fg: str = "#1f2937") -> str:
+        return (
+            f"<span style='display:inline-block;margin:0 6px 6px 0;padding:3px 10px;"
+            f"border-radius:999px;background:{bg};color:{fg};font-size:0.8em;"
+            f"font-weight:600;'>{text}</span>"
+        )
+
+    # 状态效果
+    if p.status_effects:
+        effect_lines = "<br>".join(
+            f"{e.name}（{e.duration}回合）" for e in p.status_effects
+        )
+    else:
+        effect_lines = "无"
+
+    # 背包
+    if p.inventory:
+        inventory_text = "<br>".join(p.inventory)
+    else:
+        inventory_text = "空"
+
+    weather_colors = {
+        "晴朗": "#fef3c7",
+        "多云": "#e5e7eb",
+        "小雨": "#dbeafe",
+        "浓雾": "#e0e7ff",
+        "暴风雨": "#c7d2fe",
+        "大雪": "#f3f4f6",
+    }
+    light_colors = {
+        "明亮": "#fde68a",
+        "柔和": "#fcd34d",
+        "昏暗": "#cbd5e1",
+        "幽暗": "#94a3b8",
+        "漆黑": "#334155",
+    }
+    danger_level = int(env_snapshot.get("danger_level", 0))
+    if danger_level >= 7:
+        danger_badge = badge(f"危险 {danger_level}/10", "#fecaca", "#7f1d1d")
+    elif danger_level >= 4:
+        danger_badge = badge(f"危险 {danger_level}/10", "#fed7aa", "#9a3412")
+    else:
+        danger_badge = badge(f"危险 {danger_level}/10", "#dcfce7", "#166534")
+
+    env_badges = "".join(
+        [
+            badge(f"天气 {w.weather}", weather_colors.get(w.weather, "#e5e7eb")),
+            badge(
+                f"光照 {w.light_level}",
+                light_colors.get(w.light_level, "#e5e7eb"),
+                "#0f172a" if w.light_level not in {"幽暗", "漆黑"} else "#f8fafc",
+            ),
+            danger_badge,
+            badge(f"场景 {env_snapshot.get('location_type', 'unknown')}", "#ede9fe", "#4c1d95"),
+        ]
+    )
+
+    recent_env_events = env_snapshot.get("recent_events", [])
+    if recent_env_events:
+        latest_event = recent_env_events[-1]
+        latest_event_html = (
+            f"<div style='padding:8px 10px;border-radius:10px;background:#f8fafc;"
+            f"border:1px solid #dbeafe;margin-bottom:6px;'>"
+            f"<b>{latest_event.get('title', '环境事件')}</b>"
+            f"<br><span style='font-size:0.82em;color:#475569;'>{latest_event.get('description', '')}</span>"
+            f"</div>"
+        )
+        recent_event_lines = "<br>".join(
+            f"- {event.get('title', '环境事件')}"
+            for event in reversed(recent_env_events[-3:])
+        )
+    else:
+        latest_event_html = (
+            "<div style='padding:8px 10px;border-radius:10px;background:#f8fafc;"
+            "border:1px dashed #cbd5e1;color:#64748b;'>本回合暂无显式环境事件</div>"
+        )
+        recent_event_lines = "无"
+
+    # 活跃任务（完整展示：描述、子目标、奖励、来源）
+    active_quests = [q for q in w.quests.values() if q.status == "active"]
+    if active_quests:
+        quest_blocks = []
+        for q in active_quests:
+            done = sum(1 for v in q.objectives.values() if v)
+            total = len(q.objectives)
+            tag = "主线" if q.quest_type == "main" else "支线" if q.quest_type == "side" else "🟡 " + q.quest_type
+            # 子目标列表
+            obj_lines = "".join(
+                f"<br>&nbsp;&nbsp;{'✅' if v else '⬜'} {k}"
+                for k, v in q.objectives.items()
+            )
+            # 奖励摘要
+            reward_parts = []
+            if q.rewards.gold:
+                reward_parts.append(f"{q.rewards.gold}💰")
+            if q.rewards.experience:
+                reward_parts.append(f"{q.rewards.experience}经验")
+            if q.rewards.items:
+                reward_parts.append("、".join(q.rewards.items))
+            if q.rewards.unlock_skill:
+                reward_parts.append(f"技能:{q.rewards.unlock_skill}")
+            if q.rewards.title:
+                reward_parts.append(f"称号:{q.rewards.title}")
+            reward_str = " | ".join(reward_parts) if reward_parts else "无"
+
+            block = (
+                f"<details open><summary><b>{tag} {q.title}</b>（{done}/{total}）</summary>"
+                f"<span style='font-size:0.9em;color:#666;'>来源: {q.giver_npc or '未知'}</span><br>"
+                f"<span style='font-size:0.9em;'>{q.description}</span>"
+                f"{obj_lines}"
+                f"<br><span style='font-size:0.9em;color:#2f7a4a;'>奖励: {reward_str}</span>"
+                f"</details>"
+            )
+            quest_blocks.append(block)
+        quest_text = "".join(quest_blocks)
+    else:
+        quest_text = "无活跃任务"
+
+    # 使用 HTML 双列布局
+    status = f"""<div style="font-size:0.9em;">
+<h3 style="margin:0 0 4px 0;text-align:center;">{p.name} — {p.title}</h3>
+<p style="text-align:center;margin:2px 0 6px 0;">等级 {p.level} | 经验 {p.experience}/{p.exp_to_next_level}</p>
+
+<div style="display:grid;grid-template-columns:1fr 1fr;gap:6px 12px;">
+
+<div>
+<h4 style="margin:4px 0 2px 0;">🩸 生命与状态</h4>
+<span style="font-size:0.85em;">
+{hp_bar}<br>
+{mp_bar}<br>
+{stamina_bar}<br>
+{hunger_bar}<br>
+{sanity_bar}<br>
+{morale_bar}
+</span>
+</div>
+
+<div>
+<h4 style="margin:4px 0 2px 0;">🎒 背包</h4>
+<span style="font-size:0.85em;">
+{inventory_text}
+</span>
+</div>
+
+<div>
+<h4 style="margin:4px 0 2px 0;">⚔️ 战斗属性</h4>
+<span style="font-size:0.85em;">
+{render_stat("attack", "攻击")}<br>
+{render_stat("defense", "防御")}<br>
+{render_stat("speed", "速度")}<br>
+{render_stat("luck", "幸运")}<br>
+{render_stat("perception", "感知")}
+</span>
+</div>
+
+<div>
+<h4 style="margin:4px 0 2px 0;">🛡️ 装备</h4>
+<span style="font-size:0.85em;">
+{equip_text}
+</span>
+</div>
+
+<div>
+<h4 style="margin:4px 0 2px 0;">💰 资源</h4>
+<span style="font-size:0.85em;">
+金币: {p.gold}<br>
+善恶值: {p.karma}
+</span>
+</div>
+
+<div>
+<h4 style="margin:4px 0 2px 0;">✨ 状态效果</h4>
+<span style="font-size:0.85em;">
+{effect_lines}
+</span>
+</div>
+
+<div style="grid-column: 1 / -1;">
+<h4 style="margin:4px 0 2px 0;">📜 任务</h4>
+<span style="font-size:0.9em;line-height:1.55;">
+{quest_text}
+</span>
+</div>
+
+<div style="grid-column: 1 / -1;">
+<h4 style="margin:4px 0 2px 0;">🧭 当前场景信息</h4>
+<div style="font-size:0.85em;line-height:1.5;padding:8px 10px;border-radius:12px;background:#fff7ed;border:1px solid #fed7aa;">
+{env_badges}
+<div style="margin:6px 0 8px 0;color:#475569;">
+时间 {clock_display} | 场景 {w.current_scene} | 状态系数 {survival_snapshot.get('combined_multiplier', 1.0)}
+</div>
+{latest_event_html}
+<div style="margin-top:8px;">{scene_summary}</div>
+<div style="margin-top:6px;color:#475569;">最近环境事件: {recent_event_lines}</div>
+</div>
+</div>
+</div>
+</div>"""
+    return status
+
+
+def _format_world_info_panel(gs: GameState | None) -> str:
+    """格式化世界信息面板（放在故事框上方）。"""
+    if gs is None:
+        return "🌍 **世界信息**：未开始冒险"
+
+    w = gs.world
+    if hasattr(gs, "get_clock_display"):
+        clock_display = gs.get_clock_display()
+    else:
+        minute_of_day = int(getattr(w, "time_progress_units", 0)) * 10 % (24 * 60)
+        clock_display = f"{minute_of_day // 60:02d}:{minute_of_day % 60:02d}"
+
+    current_scene = getattr(w, "current_scene", "未知地点")
+    day_count = getattr(w, "day_count", 1)
+    time_of_day = getattr(w, "time_of_day", "未知时段")
+    weather = getattr(w, "weather", "未知")
+    light_level = getattr(w, "light_level", "未知")
+    season = getattr(w, "season", "未知")
+
+    return (
+        "🌍 **世界信息**："
+        f"位置 {current_scene} ｜ "
+        f"第{day_count}天 {time_of_day}（{clock_display}） ｜ "
+        f"天气 {weather} ｜ 光照 {light_level} ｜ "
+        f"季节 {season} ｜ 回合 {getattr(gs, 'turn', 0)}"
+    )
+
+
+def _progress_bar(current: int, maximum: int, label: str, length: int = 10) -> str:
+    """生成 HTML 进度条（数值单独一行，低于 40% 高亮红色）"""
+    ratio = current / maximum if maximum > 0 else 0
+    filled = int(ratio * length)
+    empty = length - filled
+    bar = "█" * filled + "░" * empty
+    value_color = "#b91c1c" if ratio < 0.4 else "#0f172a"
+    return (
+        f"{label}: <span style='font-family:monospace;'>{bar}</span>"
+        f"<br><span style='color:{value_color};font-weight:600;'>{current}/{maximum}</span>"
+    )
+
+
+# ============================================================
+# Gradio 界面构建
+# ============================================================
+
+
+def build_app() -> gr.Blocks:
+    """构建 Gradio 界面"""
+
+    with gr.Blocks(
+        title="StoryWeaver - 交互式叙事系统",
+    ) as app:
+        app.css = APP_UI_CSS
+
+        gr.Markdown(
+            """
+            # StoryWeaver — 交互式叙事系统
+            *基于 AI 的动态分支剧情 RPG 体验*
+            """
+        )
+
+        # 游戏会话状态（Gradio State）
+        game_session = gr.State(value={})
+
+        with gr.Row():
+            # ==================
+            # 左侧：聊天区域
+            # ==================
+            with gr.Column(scale=10):
+                # 玩家姓名输入 + 开始按钮
+                with gr.Row():
+                    player_name_input = gr.Textbox(
+                        label="角色名称",
+                        placeholder="输入你的角色名称（默认: 旅人）",
+                        value="旅人",
+                        scale=3,
+                    )
+                    start_btn = gr.Button(
+                        "开始冒险",
+                        variant="primary",
+                        scale=2,
+                    )
+                    restart_btn = gr.Button(
+                        "重启冒险",
+                        variant="stop",
+                        scale=2,
+                    )
+
+                world_info_panel = gr.Markdown(
+                    value=_format_world_info_panel(None),
+                )
+
+                # 聊天窗口
+                chatbot = gr.Chatbot(
+                    label="故事",
+                    height=480,
+                )
+
+                location_map_panel = gr.Markdown(
+                    elem_classes=["scene-card", "status-panel"],
+                    value="地图关系图\n（未开始）",
+                    label="地图",
+                )
+
+                # 选项按钮（最多 6 个，分两行显示）
+                with gr.Column():
+                    with gr.Row():
+                        option_btn_1 = gr.Button(
+                            "...",
+                            visible=True,
+                            interactive=False,
+                            elem_classes=["option-btn"],
+                        )
+                        option_btn_2 = gr.Button(
+                            "...",
+                            visible=True,
+                            interactive=False,
+                            elem_classes=["option-btn"],
+                        )
+                        option_btn_3 = gr.Button(
+                            "...",
+                            visible=True,
+                            interactive=False,
+                            elem_classes=["option-btn"],
+                        )
+                    with gr.Row():
+                        option_btn_4 = gr.Button(
+                            "...",
+                            visible=False,
+                            interactive=False,
+                            elem_classes=["option-btn"],
+                        )
+                        option_btn_5 = gr.Button(
+                            "...",
+                            visible=False,
+                            interactive=False,
+                            elem_classes=["option-btn"],
+                        )
+                        option_btn_6 = gr.Button(
+                            "...",
+                            visible=False,
+                            interactive=False,
+                            elem_classes=["option-btn"],
+                        )
+                option_buttons = [
+                    option_btn_1,
+                    option_btn_2,
+                    option_btn_3,
+                    option_btn_4,
+                    option_btn_5,
+                    option_btn_6,
+                ]
+
+                # 自由输入
+                with gr.Row():
+                    user_input = gr.Textbox(
+                        label="自由输入（也可以直接点击上方选项）",
+                        placeholder="输入你想做的事情，例如：和村长说话、攻击哥布林、搜索这个区域...",
+                        scale=5,
+                        interactive=False,
+                    )
+                    with gr.Column(scale=1):
+                        send_btn = gr.Button("发送", variant="primary", elem_classes=["side-action-btn"])
+                        open_backpack_btn = gr.Button(
+                            "打开背包",
+                            variant="secondary",
+                            elem_classes=["side-action-btn", "backpack-btn"],
+                        )
+
+            # ==================
+            # 右侧：状态面板
+            # ==================
+            with gr.Column(scale=2, min_width=320, elem_classes=["scene-sidebar"]):
+                scene_image = gr.Image(
+                    value=None,
+                    type="filepath",
+                    label="场景画面",
+                    show_label=False,
+                    container=False,
+                    interactive=False,
+                    height=260,
+                    buttons=[],
+                    visible=False,
+                    elem_classes=["scene-card", "scene-image"],
+                )
+                status_panel = gr.Markdown(
+                    elem_classes=["scene-card", "status-panel"],
+                    value="## 等待开始...\n\n请输入角色名称并点击「开始冒险」",
+                    label="角色状态",
+                )
+
+        # ============================================================
+        # 事件绑定
+        # ============================================================
+
+        # 开始游戏
+        start_btn.click(
+            fn=start_game,
+            inputs=[player_name_input, game_session],
+            outputs=[
+                chatbot, world_info_panel, status_panel, location_map_panel, scene_image,
+                *option_buttons,
+                game_session, user_input,
+            ],
+        )
+
+        # 重启冒险
+        restart_btn.click(
+            fn=restart_game,
+            inputs=[],
+            outputs=[
+                chatbot, world_info_panel, status_panel, location_map_panel, scene_image,
+                *option_buttons,
+                game_session, user_input, player_name_input,
+            ],
+        )
+
+        # 文本输入发送
+        send_btn.click(
+            fn=process_user_input,
+            inputs=[user_input, chatbot, game_session],
+            outputs=[
+                chatbot, world_info_panel, status_panel, location_map_panel, scene_image,
+                *option_buttons,
+                game_session,
+            ],
+        ).then(
+            fn=lambda: "",
+            outputs=[user_input],
+        )
+
+        # 打开背包（常驻按钮）
+        open_backpack_btn.click(
+            fn=open_backpack,
+            inputs=[chatbot, game_session],
+            outputs=[
+                chatbot, world_info_panel, status_panel, location_map_panel, scene_image,
+                *option_buttons,
+                game_session,
+            ],
+        )
+
+        # 回车发送
+        user_input.submit(
+            fn=process_user_input,
+            inputs=[user_input, chatbot, game_session],
+            outputs=[
+                chatbot, world_info_panel, status_panel, location_map_panel, scene_image,
+                *option_buttons,
+                game_session,
+            ],
+        ).then(
+            fn=lambda: "",
+            outputs=[user_input],
+        )
+
+        # 选项按钮点击（需要使用 yield from 的生成器包装函数，
+        # 使 Gradio 能正确识别为流式输出）
+        def _make_option_click_handler(index: int):
+            def _handler(ch, gs):
+                yield from process_option_click(index, ch, gs)
+
+            return _handler
+
+        for index, option_button in enumerate(option_buttons):
+            option_button.click(
+                fn=_make_option_click_handler(index),
+                inputs=[chatbot, game_session],
+                outputs=[
+                        chatbot, world_info_panel, status_panel, location_map_panel, scene_image,
+                    *option_buttons,
+                    game_session,
+                ],
+            )
+
+    return app
+
+
+# ============================================================
+# 启动入口
+# ============================================================
+
+if __name__ == "__main__":
+    logger.info("启动 StoryWeaver 交互式叙事系统...")
+    app = build_app()
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+        theme=gr.themes.Soft(
+            primary_hue="emerald",
+            secondary_hue="blue",
+        ),
+        css=APP_UI_CSS,
+    )

combat_engine.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import random
+from typing import Any
+
+
+MONSTER_DB: dict[str, dict[str, int]] = {
+    "哥布林": {"hp": 20, "attack": 5, "defense": 2, "difficulty": 1},
+    "森林狼": {"hp": 40, "attack": 15, "defense": 5, "difficulty": 2},
+    "远古巨龙": {"hp": 500, "attack": 100, "defense": 80, "difficulty": 10},
+    "default": {"hp": 30, "attack": 10, "defense": 5, "difficulty": 1},
+}
+
+
+def _difficulty_scale(game_state: Any | None) -> float:
+    if game_state is None:
+        return 1.0
+    diff_name = str(getattr(game_state, "difficulty", "normal")).lower()
+    return {"easy": 0.9, "normal": 1.0, "hard": 1.2}.get(diff_name, 1.0)
+
+
+def _current_location_danger(game_state: Any | None) -> int:
+    if game_state is None:
+        return 1
+    player = getattr(game_state, "player", None)
+    world = getattr(game_state, "world", None)
+    if player is None or world is None:
+        return 1
+    location_name = str(getattr(player, "location", ""))
+    location = getattr(world, "locations", {}).get(location_name)
+    if location is None:
+        return 1
+    try:
+        return max(1, int(getattr(location, "danger_level", 1)))
+    except Exception:
+        return 1
+
+
+def get_monster_profile(monster_name: str, game_state: Any | None = None) -> dict[str, int]:
+    normalized_name = str(monster_name or "").strip()
+    profile = MONSTER_DB.get(normalized_name)
+    if profile is not None:
+        return dict(profile)
+
+    base = dict(MONSTER_DB["default"])
+    location_danger = _current_location_danger(game_state)
+    diff_scale = _difficulty_scale(game_state)
+
+    generated_difficulty = max(1, int(round(base["difficulty"] + (location_danger - 1) * 0.6)))
+    generated_attack = max(1, int(round(base["attack"] * diff_scale + location_danger * 2)))
+    generated_defense = max(1, int(round(base["defense"] * diff_scale + location_danger)))
+    generated_hp = max(1, int(round(base["hp"] * diff_scale + location_danger * 10)))
+
+    return {
+        "hp": generated_hp,
+        "attack": generated_attack,
+        "defense": generated_defense,
+        "difficulty": generated_difficulty,
+    }
+
+
+def resolve_combat(
+    player_state: Any,
+    monster_name: str,
+    *,
+    game_state: Any | None = None,
+    rng: random.Random | None = None,
+) -> dict[str, Any]:
+    active_rng = rng or random
+    monster = get_monster_profile(monster_name, game_state=game_state)
+
+    player_level = max(1, int(getattr(player_state, "level", 1)))
+    player_attack = max(1, int(getattr(player_state, "attack_power", getattr(player_state, "attack", 1))))
+    player_defense = max(0, int(getattr(player_state, "defense_power", getattr(player_state, "defense", 0))))
+
+    player_power = player_attack + player_level * 2
+    monster_power = int(monster["defense"]) + int(monster["difficulty"]) * 3
+    outcome = "win" if player_power >= monster_power else "lose"
+
+    random_float = float(active_rng.uniform(0.0, 3.0))
+    base_hp_loss = max(1, int(round(int(monster["attack"]) - player_defense - random_float)))
+    if outcome == "lose":
+        base_hp_loss = max(base_hp_loss + int(monster["difficulty"]) * 2, int(round(base_hp_loss * 1.4)))
+
+    if outcome == "win":
+        message = f"你击败了{monster_name}，但仍受了些伤。"
+    else:
+        message = f"你不敌{monster_name}，被迫败退。"
+
+    return {
+        "outcome": outcome,
+        "player_hp_loss": int(base_hp_loss),
+        "monster_name": str(monster_name),
+        "message": message,
+        "player_power": int(player_power),
+        "monster_power": int(monster_power),
+    }

demo_rules.py

@@ -0,0 +1,1410 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Any
+
+
+ACTION_TIME_COSTS: dict[str, int] = {
+    "MOVE": 30,
+    "ATTACK": 30,
+    "COMBAT": 30,
+    "CLAIM_REWARD": 10,
+    "REST": 30,
+    "OVERNIGHT_REST": 30,
+    "TALK": 10,
+    "SHOP_MENU": 10,
+    "SCENE_OPTIONS": 10,
+    "TRADE": 10,
+    "EQUIP": 10,
+    "USE_ITEM": 10,
+    "VIEW_MAP": 10,
+    "MAP": 10,
+    "QUEST": 10,
+}
+
+MAX_OPTION_COUNT = 6
+DEFAULT_OPTION_COUNT = 3
+OVERNIGHT_REST_LOCATIONS = {"村庄旅店", "溪边营地"}
+MAIN_QUEST_ID = "main_quest_01"
+MAIN_QUEST_TROLL_ID = "main_quest_02"
+FOREST_GOBLIN_DEFEATED_FLAG = "encounter::dark_forest_gate_goblin_defeated"
+FOREST_TROLL_TRACKS_FOUND_FLAG = "clue::forest_troll_tracks_found"
+FOREST_TROLL_DEFEATED_FLAG = "encounter::forest_troll_defeated"
+FOREST_TROLL_INTRO_SEEN_FLAG = "scene::forest_troll_intro_seen"
+FOREST_TROLL_HOARD_PENDING_FLAG = "reward::forest_troll_hoard_pending"
+FOREST_TROLL_HOARD_CLAIMED_FLAG = "reward::forest_troll_hoard_claimed"
+DEEP_FOREST_BARRIER_SEEN_FLAG = "clue::deep_forest_barrier_seen"
+FOREST_CAUSE_OBJECTIVE = "调查怪物活动的原因"
+REPORT_TO_CHIEF_OBJECTIVE = "与村长老伯对话汇报发现"
+FOREST_TROLL_TRAVEL_OBJECTIVE = "前往森林深处"
+FOREST_TROLL_BOSS_OBJECTIVE = "击败森林巨魔"
+SIDE_QUEST_TRAVELER_ID = "side_quest_01"
+SIDE_QUEST_FERRY_ID = "side_quest_02"
+SIDE_QUEST_GUARDIAN_ID = "side_quest_03"
+TRAVELER_RUMOR_HEARD_FLAG = "rumor::traveler_lead_heard"
+MINE_RUMOR_HEARD_FLAG = "rumor::mine_ghost_heard"
+FERRY_ROUTE_UNLOCKED_FLAG = "rumor::ferry_route_unlocked"
+TRAVELER_ENCOUNTERED_FLAG = "scene::mysterious_traveler_encountered"
+GUARDIAN_INTRO_SEEN_FLAG = "scene::elf_guardian_introduced"
+
+LOCATION_MAP_REQUIREMENTS: dict[str, str] = {
+    "村庄广场": "村庄地图",
+    "村庄铁匠铺": "村庄地图",
+    "村庄旅店": "村庄地图",
+    "村庄杂货铺": "村庄地图",
+    "村口小路": "村庄地图",
+    # 黑暗森林入口 可以用村庄地图到达；击败哥布林后获得黑暗森林地图
+    "黑暗森林入口": "村庄地图",
+    # 溪边营地/森林深处 需要黑暗森林地图（森林入口战斗奖励）
+    "溪边营地": "黑暗森林地图",
+    "森林深处": "黑暗森林地图",
+    # 河边渡口 用村庄地图可到达；与老渔夫对话后获得山麓地图
+    "河边渡口": "村庄地图",
+    # 以下地点需要山麓地图（老渔夫给予）
+    "废弃矿洞入口": "山麓地图",
+    "山麓盗贼营": "山麓地图",
+    "精灵遗迹": "山麓地图",
+    # 古塔废墟 从村口小路可直接发现，村庄地图即可
+    "古塔废墟": "村庄地图",
+}
+
+SHOP_LOCATION_TO_MERCHANT: dict[str, str] = {
+    "村庄铁匠铺": "铁匠格林",
+    "村庄旅店": "旅店老板娘莉娜",
+    "村庄杂货铺": "杂货商人阿尔",
+}
+
+ARRIVAL_EVENT_CONFIG: dict[str, dict[str, str]] = {
+    "村庄铁匠铺": {
+        "event_key": "arrival::village_blacksmith",
+        "story_text": (
+            "一间热气腾腾的铁匠铺，炉火正旺。墙上挂满了各式武器和护甲。\n"
+            "炉火映红了铁匠粗犷的脸庞，空气中弥漫着金属和碳的气味。"
+        ),
+    },
+    "村庄旅店": {
+        "event_key": "arrival::village_inn",
+        "story_text": (
+            "一家温馨的小旅店，空气中弥漫着烤肉和麦酒的香气。壁炉里的火焰跳动着。\n"
+            "壁炉噼啪作响，几位旅客正低声交谈，空气温暖而舒适。"
+        ),
+    },
+    "村庄杂货铺": {
+        "event_key": "arrival::village_general_store",
+        "story_text": (
+            "一家琳琅满目的杂货铺，从草药到绳索应有尽有。老板是个精明的商人。\n"
+            "货架上摆满了稀奇古怪的商品，柜台后的商人正用算盘噼里啪啦地算账。"
+        ),
+    },
+    "黑暗森林入口": {
+        "event_key": "arrival::dark_forest_gate",
+        "story_text": (
+            "黑暗森林入口的树冠压低了天色，落叶间散着新鲜爪痕和被拖行过的泥印。\n"
+            "一只拎着弯刀的哥布林正伏在断木后张望，时不时发出刺耳怪叫，像是在替林中的东西守门。"
+        ),
+    },
+    "河边渡口": {
+        "event_key": "arrival::river_ferry",
+        "story_text": (
+            "破旧的渡口被河水拍得吱呀作响，湿冷水汽贴着木桩往上爬。\n"
+            "披着蓑衣的老渔夫正盯着对岸，矿洞与山麓营地的路径都从这里分开。"
+        ),
+    },
+    "山麓盗贼营": {
+        "event_key": "arrival::bandit_camp",
+        "story_text": (
+            "山麓盗贼营的篝火还留着余温，翻倒的酒桶和散落的干粮说明有人刚撤离不久。\n"
+            "营帐阴影里有个盗贼斥候正贴��木桩窥探四周，显然不打算让外来者轻易通过。"
+        ),
+    },
+    "古塔废墟": {
+        "event_key": "arrival::ancient_tower",
+        "story_text": (
+            "半坍塌的古塔在风里发出低鸣，残破石阶和裂墙间还能看到新鲜抓痕。\n"
+            "塔门内飘着一团幽蓝冷火，游荡幽灵在尘灰间若隐若现，像是在警告你别再向前。"
+        ),
+    },
+    "废弃矿洞入口": {
+        "event_key": "arrival::mine_entrance",
+        "story_text": (
+            "矿洞入口被枯枝和碎石半堵着，腐朽的矿车轨道向黑暗深处延伸，铁锈和硫磺气味扑面而来。\n"
+            "一具骷髅兵从废弃矿车后方立起，锈迹斑斑的武器指向你——矿洞里的东西不欢迎活人。"
+        ),
+    },
+    "溪边营地": {
+        "event_key": "arrival::creek_camp",
+        "story_text": (
+            "森林中一处难得的开阔地带，清澈的溪水从旁流过，树冠间的光在水面打出零碎金片。\n"
+            "篝火余烬和被压平的草丛说明有人不久前在此扎营——这里适合短暂休息和搜寻遗留物资。"
+        ),
+    },
+    "精灵遗迹": {
+        "event_key": "arrival::elf_ruins",
+        "story_text": (
+            "石柱在藤蔓间若隐若现，精灵文字的刻痕随你的步伐明灭，像是感应到了来者的意图。\n"
+            "一个穿着褪色绿袍的消瘦身影从石柱阴影里转出，用警惕的眼神审视着你——遗迹有它的守护者。"
+        ),
+    },
+    "森林深处": {
+        "event_key": "arrival::deep_forest",
+        "story_text": (
+            "古树盘根错节，荧光苔藓将深处映成幽蓝，腐朽与魔力的气息混杂难辨。\n"
+            "远处传来低沉咆哮，树影间有成双眼睛移动——有什么东西已经感知到了你的闯入。"
+        ),
+    },
+}
+
+
+@dataclass(slots=True)
+class BattleSnapshot:
+    hp: int
+    attack: int
+    defense: int
+    stamina: int
+    hit_rate: float
+    dodge_rate: float
+    live_state_multiplier: float = 1.0
+
+    @property
+    def power(self) -> float:
+        return (
+            (self.attack * 0.6 + self.defense * 0.3 + self.stamina * 0.1)
+            * self.live_state_multiplier
+        )
+
+
+BATTLE_ENCOUNTER_CONFIG: dict[tuple[str, str], dict[str, Any]] = {
+    ("黑暗森林入口", "哥布林"): {
+        "enemy_snapshot": BattleSnapshot(
+            hp=45,
+            attack=8,
+            defense=3,
+            stamina=28,
+            hit_rate=0.82,
+            dodge_rate=0.08,
+            live_state_multiplier=1.0,
+        ),
+        "defeated_flag": "encounter::dark_forest_gate_goblin_defeated",
+        "reward_items": ["黑暗森林地图"],
+        "quest_objectives": ["击败森林中的怪物"],
+    },
+    ("山麓盗贼营", "盗贼斥候"): {
+        "enemy_snapshot": BattleSnapshot(
+            hp=52,
+            attack=9,
+            defense=4,
+            stamina=30,
+            hit_rate=0.84,
+            dodge_rate=0.12,
+            live_state_multiplier=1.0,
+        ),
+        "defeated_flag": "encounter::bandit_scout_defeated",
+        "reward_items": ["山麓地图"],
+        "quest_objectives": [],
+    },
+    ("古塔废墟", "游荡幽灵"): {
+        "enemy_snapshot": BattleSnapshot(
+            hp=58,
+            attack=10,
+            defense=5,
+            stamina=32,
+            hit_rate=0.86,
+            dodge_rate=0.14,
+            live_state_multiplier=1.0,
+        ),
+        "defeated_flag": "encounter::ancient_tower_wraith_defeated",
+        "reward_items": ["古塔地图"],
+        "quest_objectives": [],
+    },
+    ("废弃矿洞入口", "骷髅兵"): {
+        "enemy_snapshot": BattleSnapshot(
+            hp=38,
+            attack=7,
+            defense=4,
+            stamina=22,
+            hit_rate=0.75,
+            dodge_rate=0.05,
+            live_state_multiplier=1.0,
+        ),
+        "defeated_flag": "encounter::mine_skeleton_defeated",
+        "reward_items": ["骷髅碎骨"],
+        "quest_objectives": ["前往废弃矿洞调查"],
+    },
+    ("黑暗森林入口", "野狼"): {
+        "enemy_snapshot": BattleSnapshot(
+            hp=58,
+            attack=11,
+            defense=5,
+            stamina=36,
+            hit_rate=0.82,
+            dodge_rate=0.14,
+            live_state_multiplier=1.0,
+        ),
+        "defeated_flag": "",
+        "reward_items": [],
+        "quest_objectives": [],
+    },
+    ("森林深处", "森林巨魔"): {
+        "enemy_snapshot": BattleSnapshot(
+            hp=120,
+            attack=15,
+            defense=10,
+            stamina=130,
+            hit_rate=0.88,
+            dodge_rate=0.1,
+            live_state_multiplier=1.0,
+        ),
+        "defeated_flag": FOREST_TROLL_DEFEATED_FLAG,
+        "reward_items": [],
+        "quest_id": MAIN_QUEST_TROLL_ID,
+        "quest_objectives": [FOREST_TROLL_BOSS_OBJECTIVE],
+    },
+}
+
+
+def action_time_cost_minutes(action_type: str) -> int:
+    return ACTION_TIME_COSTS.get(str(action_type or "").upper(), 10)
+
+
+def resolve_battle(
+    player: BattleSnapshot,
+    enemy: BattleSnapshot,
+    *,
+    player_unarmed: bool = False,
+) -> dict[str, Any]:
+    enemy_power = max(enemy.power, 1.0)
+    player_power = player.power
+
+    if player_unarmed and player.attack <= enemy.defense:
+        player_power *= 0.5
+
+    ratio = player_power / enemy_power
+    if ratio < 0.6:
+        outcome = "forced_retreat"
+    elif ratio < 1.0:
+        outcome = "pyrrhic_win"
+    elif ratio < 1.5:
+        outcome = "normal_win"
+    else:
+        outcome = "dominant_win"
+
+    return {
+        "player_power": round(player_power, 2),
+        "enemy_power": round(enemy_power, 2),
+        "ratio": round(ratio, 3),
+        "outcome": outcome,
+    }
+
+
+def resolve_trade(
+    game_state,
+    *,
+    merchant_name: str,
+    item_name: str,
+    confirm: bool,
+) -> dict[str, Any]:
+    npc = game_state.world.npcs.get(merchant_name)
+    if npc is None or not npc.can_trade:
+        return {"applied": False, "reason": "invalid_merchant"}
+    if npc.location != game_state.player.location:
+        return {"applied": False, "reason": "merchant_not_here"}
+    if item_name not in npc.shop_inventory:
+        return {"applied": False, "reason": "item_not_sold_here"}
+
+    item_info = game_state.world.item_registry.get(item_name)
+    if item_info is None:
+        return {"applied": False, "reason": "unknown_item"}
+
+    if not confirm:
+        return {
+            "applied": False,
+            "reason": "awaiting_confirmation",
+            "price": item_info.value,
+        }
+
+    if game_state.player.gold < item_info.value:
+        return {"applied": False, "reason": "insufficient_gold", "price": item_info.value}
+
+    game_state.player.gold -= item_info.value
+    game_state.player.inventory.append(item_name)
+    game_state.last_recent_gain = item_name
+    follow_up_actions = build_contextual_actions(game_state, recent_gain=item_name)
+    return {
+        "applied": True,
+        "reason": "purchased",
+        "price": item_info.value,
+        "item_name": item_name,
+        "follow_up_actions": follow_up_actions,
+    }
+
+
+def get_battle_encounter(location_name: str, enemy_name: str) -> dict[str, Any] | None:
+    return BATTLE_ENCOUNTER_CONFIG.get((str(location_name), str(enemy_name)))
+
+
+def _has_status(game_state, keyword: str) -> bool:
+    keyword = str(keyword or "")
+    return any(keyword in effect.name for effect in game_state.player.status_effects)
+
+
+def _has_map(game_state) -> bool:
+    owned_items = set(game_state.player.inventory) | {
+        str(item)
+        for item in game_state.player.equipment.values()
+        if item
+    }
+    return any("地图" in item for item in owned_items)
+
+
+def _has_named_map(game_state, map_name: str) -> bool:
+    owned_items = set(game_state.player.inventory) | {
+        str(item)
+        for item in game_state.player.equipment.values()
+        if item
+    }
+    return str(map_name) in owned_items
+
+
+def _is_accessible_destination(game_state, destination: str) -> bool:
+    target_location = game_state.world.locations.get(destination)
+    if target_location is None:
+        return False
+    if target_location.is_accessible:
+        return True
+    required_item = str(target_location.required_item or "")
+    owned_items = set(game_state.player.inventory) | {
+        str(item)
+        for item in game_state.player.equipment.values()
+        if item
+    }
+    return bool(required_item) and required_item in owned_items
+
+
+def _is_route_visible(game_state, destination: str) -> bool:
+    if destination == "河边渡口":
+        return bool(game_state.world.global_flags.get(FERRY_ROUTE_UNLOCKED_FLAG))
+    return True
+
+
+def _is_forest_troll_hunt_active(game_state) -> bool:
+    quest = game_state.world.quests.get(MAIN_QUEST_TROLL_ID)
+    if quest is None or quest.status != "active":
+        return False
+    return not bool(game_state.world.global_flags.get(FOREST_TROLL_DEFEATED_FLAG))
+
+
+def _is_main_quest_report_pending(game_state) -> bool:
+    quest = game_state.world.quests.get(MAIN_QUEST_ID)
+    if quest is None or quest.status != "active":
+        return False
+    if not game_state.world.global_flags.get(FOREST_TROLL_TRACKS_FOUND_FLAG):
+        return False
+    return not bool(quest.objectives.get(REPORT_TO_CHIEF_OBJECTIVE))
+
+
+def _find_encounter_location(enemy_name: str) -> str | None:
+    enemy_name = str(enemy_name or "")
+    if not enemy_name:
+        return None
+    for (location_name, encounter_enemy), _config in BATTLE_ENCOUNTER_CONFIG.items():
+        if str(encounter_enemy) == enemy_name:
+            return str(location_name)
+    return None
+
+
+def _move_action(
+    target: str,
+    *,
+    priority: int,
+    text: str | None = None,
+    preserve_text: bool = False,
+) -> dict[str, Any]:
+    action = _make_action(
+        action_type="MOVE",
+        target=target,
+        text=text or f"前往{target}",
+        priority=priority,
+    )
+    if preserve_text:
+        action["preserve_text"] = True
+    return action
+
+
+def _make_action(
+    *,
+    action_type: str,
+    text: str,
+    target: Any = None,
+    priority: int = 50,
+) -> dict[str, Any]:
+    return {
+        "id": 0,
+        "text": text,
+        "action_type": action_type,
+        "target": target,
+        "priority": priority,
+    }
+
+
+def _dedupe_actions(actions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    deduped: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    for action in sorted(
+        actions,
+        key=lambda item: int(item.get("priority", 0) or 0),
+        reverse=True,
+    ):
+        normalized = dict(action)
+        normalized.setdefault("priority", 0)
+        key = (
+            str(normalized.get("action_type")),
+            str(normalized.get("target")),
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        normalized["id"] = len(deduped) + 1
+        deduped.append(normalized)
+    return deduped
+
+
+def _first_incomplete_objective(game_state):
+    active_quests = [
+        quest
+        for quest in game_state.world.quests.values()
+        if quest.status == "active"
+    ]
+    active_quests.sort(key=lambda quest: (quest.quest_type != "main", quest.quest_id))
+    for quest in active_quests:
+        for objective, completed in quest.objectives.items():
+            if not completed:
+                return quest, objective
+    return None, None
+
+
+def _extract_dialogue_target(objective: str) -> str | None:
+    suffixes = ("对话", "交谈", "确认情报", "了解情况")
+    text = str(objective or "")
+    if not text.startswith("与"):
+        return None
+    candidate = text[1:]
+    for separator in ("对话", "交谈"):
+        if separator in candidate:
+            candidate = candidate.split(separator, 1)[0]
+            break
+    else:
+        for suffix in suffixes:
+            if candidate.endswith(suffix):
+                candidate = candidate[: -len(suffix)]
+                break
+    candidate = candidate.strip()
+    return candidate or None
+
+
+def _extract_location_target(objective: str) -> str | None:
+    text = str(objective or "")
+    for prefix in ("前往",):
+        if text.startswith(prefix):
+            candidate = text[len(prefix):]
+            for suffix in ("调查", "探索", "查看", "侦察"):
+                if candidate.endswith(suffix):
+                    candidate = candidate[: -len(suffix)]
+                    break
+            return candidate or None
+    return None
+
+
+def _find_next_step(game_state, destination: str) -> str | None:
+    if destination == game_state.player.location:
+        return destination
+    visited = {game_state.player.location}
+    queue: deque[tuple[str, list[str]]] = deque([(game_state.player.location, [])])
+    while queue:
+        current, path = queue.popleft()
+        current_loc = game_state.world.locations.get(current)
+        if current_loc is None:
+            continue
+        for neighbor in current_loc.connected_to:
+            if neighbor in visited:
+                continue
+            visited.add(neighbor)
+            new_path = path + [neighbor]
+            if neighbor == destination:
+                return new_path[0]
+            queue.append((neighbor, new_path))
+    return None
+
+
+def build_village_chief_follow_up_actions(game_state) -> list[dict[str, Any]]:
+    blacksmith_text = "前往村庄铁匠铺准备武器"
+    path_text = None
+    if _is_forest_troll_hunt_active(game_state):
+        blacksmith_text = "前往村庄铁匠铺准备武器和防具"
+        path_text = "沿村口小路赶赴森林深处"
+    return _dedupe_actions(
+        [
+            _make_action(
+                action_type="VIEW_MAP",
+                text="查看地图",
+                priority=120,
+            ),
+            _move_action(
+                "森林深处" if path_text else "村口小路",
+                priority=116,
+                text=path_text,
+                preserve_text=bool(path_text),
+            ),
+            _move_action(
+                "村庄杂货铺",
+                priority=112,
+                text="前往村庄杂货铺准备火把",
+                preserve_text=True,
+            ),
+            _move_action(
+                "村庄铁匠铺",
+                priority=108,
+                text=blacksmith_text,
+                preserve_text=True,
+            ),
+        ]
+    )
+
+
+def build_map_actions(game_state) -> list[dict[str, Any]]:
+    if not _has_map(game_state):
+        return []
+
+    current_location = game_state.world.locations.get(game_state.player.location)
+    if current_location is None:
+        return []
+
+    special_route_order = {
+        "村庄广场": ["村庄铁匠铺", "村庄旅店", "村口小路", "村庄杂货铺"],
+        "黑暗森林入口": ["村口小路", "溪边营地", "森林深处"],
+        "河边渡口": ["废弃矿洞入口", "山麓盗贼营", "村口小路"],
+        "山麓盗贼营": ["精灵遗迹", "河边渡口"],
+        "古塔废墟": ["村口小路"],
+    }
+    route_order = special_route_order.get(
+        current_location.name,
+        list(current_location.connected_to),
+    )
+
+    actions: list[dict[str, Any]] = []
+    for index, destination in enumerate(route_order):
+        # 不显示"前往当前场景"的无效选项
+        if destination == game_state.player.location:
+            continue
+        if destination not in current_location.connected_to:
+            continue
+        if not _is_accessible_destination(game_state, destination):
+            continue
+        required_map = LOCATION_MAP_REQUIREMENTS.get(destination)
+        if required_map and not _has_named_map(game_state, required_map):
+            continue
+        if not _is_route_visible(game_state, destination):
+            continue
+        if (
+            destination == "森林深处"
+            and game_state.world.global_flags.get(DEEP_FOREST_BARRIER_SEEN_FLAG)
+            and "森林之钥" not in game_state.player.inventory
+        ):
+            continue
+        actions.append(
+            _move_action(
+                destination,
+                priority=120 - index * 4,
+            )
+        )
+
+    return _dedupe_actions(actions)
+
+
+def build_shop_menu_actions(game_state, merchant_name: str) -> list[dict[str, Any]]:
+    npc = game_state.world.npcs.get(merchant_name)
+    if npc is None or not npc.can_trade:
+        return []
+
+    actions: list[dict[str, Any]] = []
+    player_gold = int(getattr(game_state.player, "gold", 0))
+    for index, item_name in enumerate(npc.shop_inventory):
+        item_info = game_state.world.item_registry.get(item_name)
+        price = int(item_info.value) if item_info else 0
+        affordable = player_gold >= price
+        if affordable:
+            label = f"【可购买】购买{item_name}（{price}金币）"
+            priority = 130 - index * 4
+        else:
+            label = f"【金币不足】购买{item_name}（{price}金币，当前{player_gold}）"
+            priority = 90 - index * 2
+        actions.append(
+            _make_action(
+                action_type="TRADE",
+                target={"merchant": merchant_name, "item": item_name, "confirm": False},
+                text=label,
+                priority=priority,
+            )
+        )
+
+    actions.append(
+        _make_action(
+            action_type="SCENE_OPTIONS",
+            target=npc.location,
+            text="暂不购买，先离开柜台",
+            priority=60,
+        )
+    )
+    return _dedupe_actions(actions)
+
+
+def build_scene_actions(game_state, location_name: str | None = None) -> list[dict[str, Any]]:
+    current_name = str(location_name or game_state.player.location)
+    actions: list[dict[str, Any]] = []
+
+    if current_name == "村庄广场":
+        actions.append(
+            _make_action(
+                action_type="TALK",
+                target="村长老伯",
+                text="与村长老伯对话",
+                priority=120,
+            )
+        )
+        actions.append(
+            _make_action(
+                action_type="RUMOR",
+                target={"source": "布告栏", "topic": "rumor_menu"},
+                text="查看布告栏上的异闻",
+                priority=108,
+            )
+        )
+        if _has_named_map(game_state, "村庄地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=104,
+                )
+            )
+        actions.append(_move_action("村庄铁匠铺", priority=100))
+        actions.append(_move_action("村庄旅店", priority=96))
+        actions.append(_move_action("村口小路", priority=92))
+        actions.append(_move_action("村庄杂货铺", priority=88))
+        return _dedupe_actions(actions)
+
+    if current_name == "村口小路":
+        traveler_available = (
+            game_state.world.global_flags.get(TRAVELER_RUMOR_HEARD_FLAG)
+            and game_state.world.npcs.get("神秘旅人")
+            and game_state.world.npcs["神秘旅人"].location == "村口小路"
+        )
+        if traveler_available:
+            actions.append(
+                _make_action(
+                    action_type="TALK",
+                    target="神秘旅人",
+                    text="与神秘旅人交谈",
+                    priority=120,
+                )
+            )
+        if game_state.world.global_flags.get(FERRY_ROUTE_UNLOCKED_FLAG):
+            actions.append(_move_action("河边渡口", priority=112))
+        if _has_named_map(game_state, "村庄地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=108,
+                )
+            )
+        if _is_main_quest_report_pending(game_state):
+            actions.append(
+                _move_action(
+                    "村庄广场",
+                    priority=120,
+                    text="回村向村长汇报发现",
+                    preserve_text=True,
+                )
+            )
+        else:
+            actions.append(_move_action("村庄广场", priority=112))
+        if _has_named_map(game_state, "村庄地图"):
+            actions.append(_move_action("黑暗森林入口", priority=104))
+        return _dedupe_actions(actions)
+
+    if current_name == "村庄铁匠铺":
+        actions.append(
+            _make_action(
+                action_type="TALK",
+                target="铁匠格林",
+                text="与铁匠格林对话",
+                priority=120,
+            )
+        )
+        if _has_named_map(game_state, "村庄地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=104,
+                )
+            )
+        actions.append(_move_action("村庄广场", priority=96))
+        return _dedupe_actions(actions)
+
+    if current_name == "村庄旅店":
+        actions.append(
+            _make_action(
+                action_type="TALK",
+                target="旅店老板娘莉娜",
+                text="与旅店老板娘莉娜对话",
+                priority=120,
+            )
+        )
+        actions.append(
+            _make_action(
+                action_type="RUMOR",
+                target={"source": "旅店老板娘莉娜", "topic": "rumor_menu"},
+                text="向莉娜打听最近的异状",
+                priority=116,
+            )
+        )
+        actions.append(
+            _make_action(
+                action_type="REST",
+                text="在旅店休息片刻",
+                priority=110,
+            )
+        )
+        if _has_named_map(game_state, "村庄地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=104,
+                )
+            )
+        actions.append(_move_action("村庄广场", priority=96))
+        return _dedupe_actions(actions)
+
+    if current_name == "村庄杂货铺":
+        actions.append(
+            _make_action(
+                action_type="TALK",
+                target="杂货商人阿尔",
+                text="与杂货商人阿尔对话",
+                priority=120,
+            )
+        )
+        if _has_named_map(game_state, "村庄地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=104,
+                )
+            )
+        actions.append(_move_action("村庄广场", priority=96))
+        return _dedupe_actions(actions)
+
+    if current_name == "黑暗森林入口":
+        goblin_defeated = game_state.world.global_flags.get(FOREST_GOBLIN_DEFEATED_FLAG)
+        tracks_found = game_state.world.global_flags.get(FOREST_TROLL_TRACKS_FOUND_FLAG)
+        barrier_seen = game_state.world.global_flags.get(DEEP_FOREST_BARRIER_SEEN_FLAG)
+        troll_hunt_active = _is_forest_troll_hunt_active(game_state)
+        if not goblin_defeated:
+            actions.append(
+                _make_action(
+                    action_type="ATTACK",
+                    target="哥布林",
+                    text="与哥布林战斗",
+                    priority=120,
+                )
+            )
+        else:
+            if not tracks_found:
+                actions.append(
+                    _make_action(
+                        action_type="EXPLORE",
+                        target="黑暗森林入口",
+                        text="调查哥布林留下的痕迹",
+                        priority=120,
+                    )
+                )
+            elif troll_hunt_active and "森林之钥" in game_state.player.inventory:
+                actions.append(
+                    _move_action(
+                        "森林深处",
+                        priority=120,
+                        text="前往森林深处探索",
+                        preserve_text=True,
+                    )
+                )
+            elif not barrier_seen:
+                actions.append(_move_action("森林深处", priority=120))
+            elif _is_main_quest_report_pending(game_state):
+                actions.append(
+                    _move_action(
+                        "村口小路",
+                        priority=120,
+                        text="返回村庄向村长汇报",
+                        preserve_text=True,
+                    )
+                )
+        if _has_named_map(game_state, "黑暗森林地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=112 if tracks_found else 108,
+                )
+            )
+            actions.append(_move_action("溪边营地", priority=104))
+        if tracks_found and not barrier_seen and "森林之钥" in game_state.player.inventory:
+            actions.append(
+                _move_action(
+                    "森林深处",
+                    priority=116,
+                    text="前往森林深处探索" if troll_hunt_active else None,
+                    preserve_text=troll_hunt_active,
+                )
+            )
+        if _is_main_quest_report_pending(game_state) and not barrier_seen and not troll_hunt_active:
+            actions.append(
+                _move_action(
+                    "村口小路",
+                    priority=114,
+                    text="先返回村庄汇报情况",
+                    preserve_text=True,
+                )
+            )
+        elif not barrier_seen or troll_hunt_active:
+            actions.append(_move_action("村口小路", priority=96))
+        return _dedupe_actions(actions)
+
+    if current_name == "河边渡口":
+        actions.append(
+            _make_action(
+                action_type="TALK",
+                target="渡口老渔夫",
+                text="与渡口老渔夫对话",
+                priority=120,
+            )
+        )
+        if _has_named_map(game_state, "山麓地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=116,
+                )
+            )
+        actions.append(_move_action("废弃矿洞入口", priority=112))
+        actions.append(_move_action("山麓盗贼营", priority=108))
+        actions.append(_move_action("村口小路", priority=104))
+        return _dedupe_actions(actions)
+
+    if current_name == "山麓盗贼营":
+        if not game_state.world.global_flags.get("encounter::bandit_scout_defeated"):
+            actions.append(
+                _make_action(
+                    action_type="ATTACK",
+                    target="盗贼斥候",
+                    text="与盗贼斥候战斗",
+                    priority=120,
+                )
+            )
+        if _has_named_map(game_state, "山麓地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=112,
+                )
+            )
+        actions.append(_move_action("河边渡口", priority=108))
+        return _dedupe_actions(actions)
+
+    if current_name == "古塔废墟":
+        if not game_state.world.global_flags.get("encounter::ancient_tower_wraith_defeated"):
+            actions.append(
+                _make_action(
+                    action_type="ATTACK",
+                    target="游荡幽灵",
+                    text="与游荡幽灵战斗",
+                    priority=120,
+                )
+            )
+        if _has_named_map(game_state, "古塔地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=108,
+                )
+            )
+        actions.append(_move_action("村口小路", priority=104))
+        return _dedupe_actions(actions)
+
+    if current_name == "废弃矿洞入口":
+        if not game_state.world.global_flags.get("encounter::mine_skeleton_defeated"):
+            actions.append(
+                _make_action(
+                    action_type="ATTACK",
+                    target="骷髅兵",
+                    text="与骷髅兵战斗",
+                    priority=120,
+                )
+            )
+        else:
+            actions.append(
+                _make_action(
+                    action_type="EXPLORE",
+                    target="废弃矿洞入口",
+                    text="搜查矿洞入口的遗留痕迹",
+                    priority=120,
+                )
+            )
+        if _has_named_map(game_state, "山麓地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=108,
+                )
+            )
+        actions.append(_move_action("河边渡口", priority=104))
+        return _dedupe_actions(actions)
+
+    if current_name == "溪边营地":
+        actions.append(
+            _make_action(
+                action_type="REST",
+                text="在营地休息恢复体力",
+                priority=120,
+            )
+        )
+        actions.append(
+            _make_action(
+                action_type="EXPLORE",
+                target="溪边营地",
+                text="搜寻营地遗留的物资线索",
+                priority=112,
+            )
+        )
+        if _has_named_map(game_state, "黑暗森林地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=104,
+                )
+            )
+        actions.append(_move_action("黑暗森林入口", priority=96))
+        return _dedupe_actions(actions)
+
+    if current_name == "精灵遗迹":
+        actions.append(
+            _make_action(
+                action_type="TALK",
+                target="遗迹守护者",
+                text="与遗迹守护者对话",
+                priority=120,
+            )
+        )
+        if _has_named_map(game_state, "山麓地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=108,
+                )
+            )
+        actions.append(_move_action("山麓盗贼营", priority=100))
+        return _dedupe_actions(actions)
+
+    if current_name == "森林深处":
+        if game_state.world.global_flags.get(FOREST_TROLL_HOARD_PENDING_FLAG):
+            actions.append(
+                _make_action(
+                    action_type="CLAIM_REWARD",
+                    target={"source": "forest_troll_hoard"},
+                    text="确认拾取洞穴中的战利品",
+                    priority=124,
+                )
+            )
+        elif (
+            _is_forest_troll_hunt_active(game_state)
+            and game_state.world.global_flags.get(FOREST_TROLL_INTRO_SEEN_FLAG)
+        ):
+            actions.append(
+                _make_action(
+                    action_type="ATTACK",
+                    target="森林巨魔",
+                    text="与森林巨魔战斗",
+                    priority=120,
+                )
+            )
+        else:
+            actions.append(
+                _make_action(
+                    action_type="EXPLORE",
+                    target="森林深处",
+                    text="深入调查森林异变的根源",
+                    priority=120,
+                )
+            )
+        if _has_named_map(game_state, "黑暗森林地图"):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=108,
+                )
+            )
+        actions.append(_move_action("黑暗森林入口", priority=100))
+        return _dedupe_actions(actions)
+
+    return build_adjacent_actions(game_state)
+
+
+def build_arrival_event(game_state, location_name: str) -> dict[str, Any] | None:
+    config = ARRIVAL_EVENT_CONFIG.get(str(location_name))
+    if config is None:
+        return None
+    return {
+        "event_key": config["event_key"],
+        "story_text": config["story_text"],
+        "options": build_scene_actions(game_state, location_name),
+    }
+
+
+def build_goal_directed_actions(game_state) -> list[dict[str, Any]]:
+    quest, objective = _first_incomplete_objective(game_state)
+    if not quest or not objective:
+        return []
+
+    actions: list[dict[str, Any]] = []
+    inventory = set(game_state.player.inventory)
+    current_location = game_state.world.locations.get(game_state.player.location)
+    dialogue_target = _extract_dialogue_target(objective)
+    if dialogue_target:
+        npc = game_state.world.npcs.get(dialogue_target)
+        if npc is None:
+            npc = next(
+                (
+                    candidate
+                    for candidate in game_state.world.npcs.values()
+                    if dialogue_target in candidate.name or candidate.name in objective
+                ),
+                None,
+            )
+        if npc and npc.location == game_state.player.location:
+            actions.append(
+                _make_action(
+                    action_type="TALK",
+                    target=npc.name,
+                    text=f"与{npc.name}对话",
+                    priority=120,
+                )
+            )
+        elif npc:
+            next_step = _find_next_step(game_state, npc.location)
+            if next_step:
+                actions.append(
+                    _make_action(
+                        action_type="MOVE",
+                        target=next_step,
+                        text=f"前往{next_step}",
+                        priority=112,
+                    )
+                )
+
+    location_target = _extract_location_target(objective)
+    if location_target:
+        if any("地图" in item for item in inventory):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=110,
+                )
+            )
+        if (
+            location_target == "森林深处"
+            and _is_forest_troll_hunt_active(game_state)
+            and "森林之钥" in inventory
+            and game_state.player.location != "森林深处"
+        ):
+            actions.append(
+                _make_action(
+                    action_type="MOVE",
+                    target="森林深处",
+                    text="赶赴森林深处",
+                    priority=105,
+                )
+            )
+        else:
+            next_step = _find_next_step(game_state, location_target)
+            if next_step and next_step != game_state.player.location:
+                actions.append(
+                    _make_action(
+                        action_type="MOVE",
+                        target=next_step,
+                        text=f"前往{next_step}",
+                        priority=105,
+                        )
+                    )
+
+        if location_target == "黑暗森林入口" and game_state.player.location == "村庄广场":
+            if "火把" not in inventory:
+                actions.append(
+                    _make_action(
+                        action_type="MOVE",
+                        target="村庄杂货铺",
+                        text="前往村庄杂货铺准备火把",
+                        priority=104,
+                    )
+                )
+            if (
+                not game_state.player.equipment.get("weapon")
+                and "铁剑" not in inventory
+                and "短剑" not in inventory
+            ):
+                actions.append(
+                    _make_action(
+                        action_type="MOVE",
+                        target="村庄铁匠铺",
+                        text="前往村庄铁匠铺准备武器",
+                        priority=103,
+                    )
+                )
+
+    if "击败" in str(objective):
+        enemy_name = str(objective).replace("击败", "").replace("森林中的", "").replace("矿洞中的", "").replace("的怪物", "").strip()
+        encounter_location = _find_encounter_location(enemy_name)
+        if enemy_name in {"怪物", "敌人"} and current_location:
+            local_enemies = list(current_location.enemies or [])
+            if local_enemies:
+                enemy_name = local_enemies[0]
+                encounter_location = _find_encounter_location(enemy_name)
+            else:
+                hunt_step = next(
+                    (
+                        neighbor
+                        for neighbor in current_location.connected_to
+                        if game_state.world.locations.get(neighbor)
+                        and game_state.world.locations[neighbor].enemies
+                    ),
+                    None,
+                )
+                if hunt_step:
+                    actions.append(
+                        _make_action(
+                            action_type="MOVE",
+                            target=hunt_step,
+                            text=f"前往{hunt_step}搜索怪物",
+                            priority=108,
+                        )
+                    )
+                    enemy_name = ""
+        if enemy_name and encounter_location and encounter_location != game_state.player.location:
+            next_step = _find_next_step(game_state, encounter_location)
+            if next_step and next_step != game_state.player.location:
+                actions.append(
+                    _make_action(
+                        action_type="MOVE",
+                        target=next_step,
+                        text=f"前往{next_step}",
+                        priority=108,
+                    )
+                )
+        elif enemy_name:
+            actions.append(
+                _make_action(
+                    action_type="ATTACK",
+                    target=enemy_name,
+                    text=f"与{enemy_name}战斗",
+                    priority=100,
+                )
+            )
+
+    if "调查" in str(objective) or "找到" in str(objective):
+        if (
+            str(objective) == FOREST_CAUSE_OBJECTIVE
+            and game_state.player.location == "黑暗森林入口"
+            and game_state.world.global_flags.get(FOREST_GOBLIN_DEFEATED_FLAG)
+        ):
+            actions.append(
+                _make_action(
+                    action_type="EXPLORE",
+                    target="黑暗森林入口",
+                    text="调查哥布林留下的痕迹",
+                    priority=118,
+                )
+            )
+            return _dedupe_actions(actions)
+        actions.append(
+            _make_action(
+                action_type="EXPLORE",
+                target=game_state.player.location,
+                text=f"围绕“{objective}”继续调查",
+                priority=92,
+            )
+        )
+
+    return _dedupe_actions(actions)
+
+
+def build_adjacent_actions(game_state) -> list[dict[str, Any]]:
+    current_location = game_state.world.locations.get(game_state.player.location)
+    if current_location is None:
+        return []
+
+    actions: list[dict[str, Any]] = []
+    owned_items = set(game_state.player.inventory) | {
+        str(item)
+        for item in game_state.player.equipment.values()
+        if item
+    }
+
+    for neighbor in current_location.connected_to:
+        # 不显示"前往当前场景"的无效选项
+        if neighbor == game_state.player.location:
+            continue
+        target_location = game_state.world.locations.get(neighbor)
+        if target_location is None:
+            continue
+        if not target_location.is_accessible:
+            required_item = str(target_location.required_item or "")
+            if not required_item or required_item not in owned_items:
+                continue
+        actions.append(
+            _make_action(
+                action_type="MOVE",
+                target=neighbor,
+                text=f"前往{neighbor}",
+                priority=78 if not target_location.is_discovered else 72,
+            )
+        )
+
+    for npc_name in current_location.npcs_present:
+        if npc_name not in game_state.world.npcs:
+            continue
+        actions.append(
+            _make_action(
+                action_type="TALK",
+                target=npc_name,
+                text=f"与{npc_name}对话",
+                priority=68,
+            )
+        )
+
+    return _dedupe_actions(actions)
+
+
+def merge_demo_options(
+    base_options: list[dict[str, Any]],
+    *extra_option_groups: list[dict[str, Any]],
+    limit: int = 3,
+) -> list[dict[str, Any]]:
+    merged: list[dict[str, Any]] = [option for option in base_options if isinstance(option, dict)]
+    for group in extra_option_groups:
+        merged.extend(group)
+    deduped = _dedupe_actions(merged)
+    return deduped[:limit]
+
+
+def build_contextual_actions(
+    game_state,
+    *,
+    recent_gain: str | None = None,
+) -> list[dict[str, Any]]:
+    actions: list[dict[str, Any]] = []
+    inventory = set(game_state.player.inventory)
+    light_level = str(game_state.world.light_level)
+    location = game_state.world.locations.get(game_state.player.location)
+    time_of_day = str(game_state.world.time_of_day)
+
+    if recent_gain:
+        item_info = game_state.world.item_registry.get(recent_gain)
+        if item_info and item_info.item_type in {"weapon", "armor", "accessory"}:
+            slot = "weapon" if item_info.item_type == "weapon" else "armor"
+            if game_state.player.equipment.get(slot) != recent_gain:
+                actions.append(
+                    _make_action(
+                        action_type="EQUIP",
+                        target=recent_gain,
+                        text=f"装备{recent_gain}",
+                        priority=100,
+                    )
+                )
+        if "地图" in str(recent_gain):
+            actions.append(
+                _make_action(
+                    action_type="VIEW_MAP",
+                    text="查看地图",
+                    priority=95,
+                )
+            )
+
+    in_dark_area = (
+        light_level in {"黑暗", "昏暗", "幽暗", "漆黑"}
+        or (location is not None and location.location_type == "dungeon")
+        or (
+            location is not None
+            and location.location_type in {"wilderness", "special"}
+            and time_of_day in {"夜晚", "深夜"}
+        )
+    )
+    if "火把" in inventory and in_dark_area and not _has_status(game_state, "火把"):
+        actions.append(
+            _make_action(
+                action_type="USE_ITEM",
+                target="火把",
+                text="使用火把照明",
+                priority=90,
+            )
+        )
+
+    if game_state.player.hp < max(1, game_state.player.max_hp // 2):
+        for potion_name in ("小型治疗药水", "治疗药水"):
+            if potion_name in inventory:
+                actions.append(
+                    _make_action(
+                        action_type="USE_ITEM",
+                        target=potion_name,
+                        text=f"使用{potion_name}",
+                        priority=85,
+                    )
+                )
+                break
+
+    if game_state.player.hunger < 50:
+        for food_name in ("面包", "烤肉", "麦酒", "草药包"):
+            if food_name in inventory:
+                actions.append(
+                    _make_action(
+                        action_type="USE_ITEM",
+                        target=food_name,
+                        text=f"食用{food_name}",
+                        priority=80,
+                    )
+                )
+                break
+
+    if (
+        game_state.player.location in OVERNIGHT_REST_LOCATIONS
+        and hasattr(game_state, "can_overnight_rest")
+        and game_state.can_overnight_rest()
+    ):
+        actions.append(
+            _make_action(
+                action_type="OVERNIGHT_REST",
+                text="在此处过夜",
+                priority=88,
+            )
+        )
+
+    return _dedupe_actions(actions)

nlu_engine.py

@@ -0,0 +1,431 @@
+"""
+nlu_engine.py - StoryWeaver 自然语言理解引擎
+
+职责：
+1. 解析用户自然语言输入，提取结构化意图
+2. 将玩家"乱七八糟的输入"映射到具体的动作类型
+3. 封装意图识别的 Prompt 与 API 调用
+
+设计思路：
+- 使用 Qwen API 进行意图识别，利用 LLM 的语义理解能力
+- Prompt 设计中明确列出所有可能的意图类型和示例
+- 低温度 (0.2) 确保输出的 JSON 格式稳定可靠
+- 提供降级机制：如果 API 调用失败，使用关键词匹配兜底
+
+输入/输出示例（来自需求文档）：
+  Input: "我想攻击那个哥布林"
+  Output: {"intent": "ATTACK", "target": "哥布林", "details": null}
+"""
+
+import re
+import logging
+from typing import Optional
+
+from demo_rules import build_scene_actions
+from utils import safe_json_call, DEFAULT_MODEL
+from state_manager import GameState
+
+logger = logging.getLogger("StoryWeaver")
+
+
+# ============================================================
+# 意图识别 Prompt 模板
+#
+# 设计思路：
+# - System Prompt 提供完整的意图类型列表和示例
+# - 注入当前可用的行动上下文（当前场景的NPC、物品等）
+# - 要求严格输出 JSON 格式
+# - 低温度确保稳定性
+# ============================================================
+
+NLU_SYSTEM_PROMPT_TEMPLATE = """你是一个 RPG 游戏的自然语言理解模块（NLU）。你的任务是将玩家的自然语言输入解析为结构化的 JSON 意图数据。
+
+【当前游戏上下文】
+{context}
+
+【支持的意图类型】
+以下是所有合法的意图类型及其说明和示例：
+
+| 意图 (intent) | 说明 | 示例输入 |
+|:--|:--|:--|
+| ATTACK | 攻击目标 | "攻击哥布林"、"打那个怪物"、"我要和它战斗" |
+| TALK | 与NPC对话 | "和村长说话"、"找铁匠聊聊"、"我想打听消息" |
+| MOVE | 移动到某地 | "去森林"、"回村庄"、"我要离开这里" |
+| EXPLORE | 探索/观察环境 | "看看周围"、"仔细搜索"、"调查这个地方" |
+| USE_ITEM | 使用物品 | "喝治疗药水"、"使用火把"、"吃面包" |
+| TRADE | 交易（买/卖） | "买一把剑"、"卖掉这个"、"看看有什么卖的" |
+| EQUIP | 装备物品 | "装备铁剑"、"穿上皮甲" |
+| REST | 休息恢复 | "休息一下"、"在旅店过夜"、"睡觉" |
+| QUEST | 接受/查看任务 | "接受任务"、"查看任务"、"任务完成了" |
+| SKILL | 使用技能 | "施放火球术"、"使用隐身技能" |
+| PICKUP | 拾取物品 | "捡起来"、"拿走那个东西" |
+| FLEE | 逃跑 | "快跑"、"逃离这里"、"我要撤退" |
+| CUSTOM | 其他自由行动 | "给NPC唱首歌"、"在墙上涂鸦" |
+
+【当前场景中可交互的对象】
+{interactables}
+
+【输出格式要求】
+请严格输出以下 JSON 格式（不要输出任何其他文字）：
+{{
+    "intent": "意图类型（从上表中选择）",
+    "target": "行动目标（NPC名称、物品名称、地点名称等，如果没有明确目标则为 null）",
+    "details": "补充细节（如 '用剑攻击'、'询问关于森林的事情' 等，如果没有额外细节则为 null）"
+}}
+
+【解析规则】
+1. 如果玩家输入模糊（如"我不知道该干什么"），意图设为 EXPLORE。
+2. 如果玩家输入包含多个动作，提取最主要的一个。
+3. target 应尽量匹配当前场景中实际存在的对象。
+4. 如果输入完全无法理解，设 intent 为 CUSTOM。
+"""
+
+
+class NLUEngine:
+    """
+    自然语言理解引擎
+
+    核心能力：将玩家自由文本输入映射到结构化意图。
+
+    工作流程：
+    1. 收集当前场景上下文（NPC、物品、可达地点等）
+    2. 构造 Prompt 并调用 Qwen API
+    3. 解析返回的 JSON 意图
+    4. 如果 API 失败，使用关键词匹配降级
+
+    为什么用 LLM 而不是规则匹配：
+    - 玩家输入千变万化，规则难以覆盖
+    - LLM 能理解同义词、口语化表达、上下文隐含意图
+    - 例如："我饿了" → 可能是 USE_ITEM（吃东西）或 MOVE（去旅店）
+    """
+
+    def __init__(self, game_state: GameState, model: str = DEFAULT_MODEL):
+        self.game_state = game_state
+        self.model = model
+
+    def parse_intent(self, user_input: str) -> dict:
+        """
+        解析用户输入，返回结构化意图。
+
+        Args:
+            user_input: 玩家的原始文本输入
+
+        Returns:
+            {
+                "intent": "ATTACK",
+                "target": "哥布林",
+                "details": "用剑攻击",
+                "raw_input": "我想用剑攻击那个哥布林"
+            }
+        """
+        if not user_input or not user_input.strip():
+            return {
+                "intent": "EXPLORE",
+                "target": None,
+                "details": "玩家沉默不语",
+                "raw_input": "",
+                "parser_source": "empty_input",
+            }
+
+        user_input = user_input.strip()
+        logger.info(f"NLU 解析输入: '{user_input}'")
+
+        # 尝试 LLM 解析
+        result = self._llm_parse(user_input)
+
+        # 如果 LLM 解析失败，使用关键词降级
+        if result is None:
+            logger.warning("LLM 解析失败，使用关键词降级")
+            result = self._keyword_fallback(user_input)
+
+        result = self._apply_intent_postprocessing(result, user_input)
+
+        # 附加原始输入
+        result["raw_input"] = user_input
+
+        logger.info(f"NLU 解析结果: {result}")
+        return result
+
+    def _llm_parse(self, user_input: str) -> Optional[dict]:
+        """
+        使用 Qwen API 进行意图识别。
+        低温度 (0.2) 确保 JSON 输出稳定。
+        """
+        context = self._build_context()
+        interactables = self._build_interactables()
+
+        system_prompt = NLU_SYSTEM_PROMPT_TEMPLATE.format(
+            context=context,
+            interactables=interactables,
+        )
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_input},
+        ]
+
+        result = safe_json_call(
+            messages,
+            model=self.model,
+            temperature=0.2,
+            max_tokens=300,
+            max_retries=2,
+        )
+
+        if result and isinstance(result, dict) and "intent" in result:
+            # 验证意图类型合法
+            valid_intents = {
+                "ATTACK", "TALK", "MOVE", "EXPLORE", "USE_ITEM",
+                "TRADE", "EQUIP", "REST", "QUEST", "SKILL",
+                "PICKUP", "FLEE", "CUSTOM",
+            }
+            if result["intent"] not in valid_intents:
+                result["intent"] = "CUSTOM"
+            result.setdefault("parser_source", "llm")
+            return result
+
+        return None
+
+    def _keyword_fallback(self, user_input: str) -> dict:
+        """
+        关键词匹配降级方案。
+
+        设计思路：
+        - 当 API 不可用时的兜底策略
+        - 使用正则匹配常见中文关键词
+        - 覆盖最常见的意图类型
+        - 无法匹配时默认为 EXPLORE
+        """
+        text = user_input.lower()
+
+        # 关键词 → 意图映射（按优先级排序）
+        keyword_rules = [
+            # 攻击相关
+            (r"攻击|打|杀|战斗|砍|刺|射|揍", "ATTACK"),
+            # 逃跑相关
+            (r"逃|跑|撤退|逃离|闪", "FLEE"),
+            # 对话相关
+            (r"说话|对话|交谈|聊|打听|询问|问", "TALK"),
+            # 移动相关
+            (r"去|前往|移动|走|回|离开|进入", "MOVE"),
+            # 物品使用
+            (r"使用|喝|吃|用|服用", "USE_ITEM"),
+            # 交易
+            (r"买|卖|交易|购买|出售|商店", "TRADE"),
+            # 装备
+            (r"装备|穿|戴|换装", "EQUIP"),
+            # 休息
+            (r"休息|睡|过夜|恢复|歇", "REST"),
+            # 任务
+            (r"任务|接受|完成|查看任务", "QUEST"),
+            # 技能
+            (r"施放|技能|魔法|法术|释放", "SKILL"),
+            # 拾取
+            (r"捡|拾|拿|拿走|拾取|收集", "PICKUP"),
+            # 探索
+            (r"看|观察|搜索|调查|探索|检查|四周", "EXPLORE"),
+        ]
+
+        detected_intent = "CUSTOM"
+        for pattern, intent in keyword_rules:
+            if re.search(pattern, text):
+                detected_intent = intent
+                break
+
+        # 尝试提取目标
+        target = self._extract_target_from_text(user_input)
+
+        return {
+            "intent": detected_intent,
+            "target": target,
+            "details": None,
+            "parser_source": "keyword_fallback",
+        }
+
+    def _extract_target_from_text(self, text: str) -> Optional[str]:
+        """
+        从文本中提取可能的目标对象。
+        尝试匹配当前场景中的 NPC、物品、地点名称。
+        """
+        # 检查 NPC 名称
+        for npc_name in self.game_state.world.npcs:
+            if npc_name in text:
+                return npc_name
+
+        # 检查物品名称（背包 + 当前场景）
+        for item in self.game_state.player.inventory:
+            if item in text:
+                return item
+
+        # 检查地点名称
+        current_loc = self.game_state.world.locations.get(self.game_state.player.location)
+        if current_loc:
+            for loc_name in current_loc.connected_to:
+                if loc_name in text:
+                    return loc_name
+
+        # 检查物品注册表
+        for item_name in self.game_state.world.item_registry:
+            if item_name in text:
+                return item_name
+
+        return None
+
+    def _apply_intent_postprocessing(self, result: dict, user_input: str) -> dict:
+        """Apply narrow intent corrections for high-confidence mixed phrases."""
+        normalized = dict(result)
+        intent = str(normalized.get("intent", "")).upper()
+        if intent == "MOVE" and self._looks_like_trade_request(user_input, normalized.get("target")):
+            inferred_trade_target = self._infer_trade_target(user_input, normalized.get("target"))
+            target_text = str(normalized.get("target") or "")
+            target_location = self.game_state.world.locations.get(target_text)
+            # 目标是商店地点且玩家尚未到达时，优先保持 MOVE，避免生成“未到店先扣钱”的错误交易。
+            if (
+                target_location is not None
+                and target_location.shop_available
+                and target_text != self.game_state.player.location
+            ):
+                normalized["intent_correction"] = "preserve_move_for_shop_travel"
+            elif inferred_trade_target is not None:
+                normalized["intent"] = "TRADE"
+                normalized["target"] = inferred_trade_target
+                normalized["intent_correction"] = "move_to_trade_with_structured_target"
+        if intent == "TRADE" and not isinstance(normalized.get("target"), dict):
+            target_text = str(normalized.get("target") or "")
+            target_location = self.game_state.world.locations.get(target_text)
+            if (
+                target_location is not None
+                and target_location.shop_available
+                and target_text != self.game_state.player.location
+            ):
+                normalized["intent"] = "MOVE"
+                normalized["intent_correction"] = "trade_to_move_for_shop_travel"
+                return normalized
+            inferred_trade_target = self._infer_trade_target(user_input, normalized.get("target"))
+            if inferred_trade_target is not None:
+                normalized["target"] = inferred_trade_target
+                normalized["intent_correction"] = "trade_target_inferred_from_text"
+        if intent in {"ATTACK", "COMBAT"}:
+            target = normalized.get("target")
+            if not isinstance(target, str) or not target.strip() or target in {"怪物", "敌人", "它", "那个怪物"}:
+                inferred_target = self._infer_attack_target()
+                if inferred_target:
+                    normalized["target"] = inferred_target
+                    normalized["intent_correction"] = "attack_target_inferred_from_scene"
+        return normalized
+
+    def _looks_like_trade_request(self, user_input: str, target: Optional[str]) -> bool:
+        trade_pattern = r"买|卖|交易|购买|出售|看看有什么卖的|买点"
+        if not re.search(trade_pattern, user_input):
+            return False
+
+        target_text = str(target or "")
+        if target_text:
+            npc = self.game_state.world.npcs.get(target_text)
+            if npc and npc.can_trade:
+                return True
+
+            location = self.game_state.world.locations.get(target_text)
+            if location and location.shop_available:
+                return True
+
+        shop_hint_pattern = r"商店|杂货铺|旅店|铁匠铺"
+        return bool(re.search(shop_hint_pattern, user_input))
+
+    def _infer_attack_target(self) -> Optional[str]:
+        """Infer a concrete ATTACK target from deterministic scene actions first."""
+        try:
+            scene_actions = build_scene_actions(self.game_state, self.game_state.player.location)
+        except Exception:
+            scene_actions = []
+        for action in scene_actions:
+            if str(action.get("action_type", "")).upper() != "ATTACK":
+                continue
+            target = action.get("target")
+            if isinstance(target, str) and target.strip():
+                return target
+
+        current_loc = self.game_state.world.locations.get(self.game_state.player.location)
+        if current_loc and current_loc.enemies:
+            return str(current_loc.enemies[0])
+        return None
+
+    def _infer_trade_target(self, user_input: str, target: object) -> Optional[dict]:
+        """Infer structured trade target for rule-based TRADE handling."""
+        text_blob = f"{user_input} {target if isinstance(target, str) else ''}"
+
+        merchant_name: Optional[str] = None
+        for npc in self.game_state.world.npcs.values():
+            if not npc.can_trade or npc.location != self.game_state.player.location:
+                continue
+            if npc.name in text_blob or (npc.occupation and npc.occupation in text_blob):
+                merchant_name = npc.name
+                break
+
+        if merchant_name is None:
+            for npc in self.game_state.world.npcs.values():
+                if npc.can_trade and npc.location == self.game_state.player.location:
+                    merchant_name = npc.name
+                    break
+        if merchant_name is None:
+            return None
+
+        merchant = self.game_state.world.npcs.get(merchant_name)
+        if merchant is None:
+            return None
+
+        item_name: Optional[str] = None
+        for candidate in merchant.shop_inventory:
+            if candidate in text_blob:
+                item_name = candidate
+                break
+        if item_name is None and isinstance(target, str) and target in merchant.shop_inventory:
+            item_name = target
+        if item_name is None:
+            return None
+
+        return {"merchant": merchant_name, "item": item_name, "confirm": False}
+
+    def _build_context(self) -> str:
+        """构建当前场景的简要上下文描述"""
+        gs = self.game_state
+        return (
+            f"场景: {gs.world.current_scene}\n"
+            f"时间: 第{gs.world.day_count}天 {gs.world.time_of_day}\n"
+            f"玩家位置: {gs.player.location}\n"
+            f"玩家 HP: {gs.player.hp}/{gs.player.max_hp}\n"
+            f"玩家背包: {', '.join(gs.player.inventory) if gs.player.inventory else '空'}"
+        )
+
+    def _build_interactables(self) -> str:
+        """构建当前场景中可交互对象的列表"""
+        gs = self.game_state
+        lines = []
+
+        # 当前场景的 NPC
+        current_npcs = [
+            npc for npc in gs.world.npcs.values()
+            if npc.location == gs.player.location and npc.is_alive
+        ]
+        if current_npcs:
+            npc_names = [f"{npc.name}（{npc.occupation}）" for npc in current_npcs]
+            lines.append(f"NPC: {', '.join(npc_names)}")
+
+        # 可前往的地点
+        loc = gs.world.locations.get(gs.player.location)
+        if loc and loc.connected_to:
+            lines.append(f"可前往: {', '.join(loc.connected_to)}")
+
+        # 场景中的敌人
+        if loc and loc.enemies:
+            lines.append(f"可能的敌人: {', '.join(loc.enemies)}")
+
+        # 背包物品
+        if gs.player.inventory:
+            lines.append(f"背包物品: {', '.join(gs.player.inventory)}")
+
+        # 技能
+        if gs.player.skills:
+            lines.append(f"可用技能: {', '.join(gs.player.skills)}")
+
+        return "\n".join(lines) if lines else "当前场景中没有特别的可交互对象"

requirement.md

@@ -0,0 +1,89 @@
+项目需求规格说明书：StoryWeaver 交互式叙事系统 (API版)
+1. 项目概况
+项目名称：StoryWeaver
+项目类型：基于 LLM API 的交互式叙事 Web 应用
+核心定义：构建一个能维护世界状态、保证逻辑一致性的 AI 叙事引擎。利用大模型强大的理解能力，实现动态分支剧情和角色扮演体验。
+
+2. 技术栈约束
+核心语言：Python
+LLM 服务：Qwen (通义千问) API
+调用方式：推荐使用 OpenAI 兼容格式 或官方 dashscope 库。
+前端界面：Gradio
+依赖管理：使用 python-dotenv 管理环境变量，严禁在代码中硬编码 API Key。
+3. 功能模块详解
+请利用 Qwen API 的强大能力实现以下四个核心模块：
+
+模块一：意图识别
+功能描述：解析用户自然语言输入。
+实现逻辑：构造 Prompt 指导 Qwen 输出结构化 JSON 数据。
+输入/输出示例：
+Input: "我想攻击那个哥布林"
+Output: {"intent": "ATTACK", "target": "哥布林", "details": null}
+模块二：上下文生成
+功能描述：生成连贯、有文学色彩的剧情段落。
+生成策略：采用 "两阶段生成策略" (Chain of Thought)：
+第一阶段：让 Qwen 生成 JSON 格式的剧情大纲（包含事件、地点变化、NPC反应）。
+第二阶段：基于大纲生成具体的描写文本。
+目的：便于程序解析状态变化，同时保证文本质量。
+模块三：一致性维护
+功能描述：核心难点。系统必须实时维护“世界模型”。
+状态追踪：
+在 state_manager.py 中维护字典或类对象，存储：角色位置、HP、背包物品、当前任务进度。
+核心机制：
+在调用 Qwen 生成前，将当前状态作为 System Prompt 注入。
+要求 Qwen 在输出故事的同时，输出变更的状态字段（如 {"hp_change": -10}）。
+代码层面进行校验：如果 HP <= 0，则强制触发死亡结局逻辑。
+模块四：交互与分支
+功能描述：生成后续选项。
+输出要求：要求 Qwen 在生成文本后，额外输出 3 个 JSON 格式的选项供用户点击。
+4. 项目文件结构
+请严格按照以下结构创建文件：
+
+text
+
+/StoryWeaver
+├── .env                # 存储 API Key (格式: QWEN_API_KEY=sk-xxxxxx)
+├── requirement.md      # (本文件) 需求定义文档
+├── state_manager.py    # 状态管理器：维护游戏全局状态 (Class 实现)
+├── nlu_engine.py       # NLU 引擎：封装意图识别的 Prompt 与 API 调用
+├── story_engine.py     # 叙事引擎：封装故事生成、分支生成的逻辑
+├── app.py              # Gradio 界面：交互逻辑
+└── utils.py            # 工具函数：API 配置加载、JSON 解析等
+5. 核心代码规范
+API 配置：
+请使用 os.getenv('QWEN_API_KEY') 读取密钥。
+初始化客户端时设置 base_url (如使用兼容接口)。
+Prompt 设计：
+Story Engine 的 System Prompt 必须包含当前状态的描述，例如："当前场景：森林。玩家状态：HP 50/100。已发生事件：无。"
+错误处理：
+如果 API 返回格式不是标准 JSON，必须有重试或降级处理机制。
+6. 执行步骤
+环境搭建：生成 .env 文件模板和 requirements.txt。
+架构规划：
+设计 state_manager.py 的数据结构。
+设计调用 Qwen API 的通用函数 (在 utils.py 中)。
+模块实现：
+先实现 story_engine.py，确保能跑通一个最简单的剧情生成。
+再实现 nlu_engine.py 和 state_manager.py。
+最后串联 app.py。
+测试验证：
+模拟输入 "攻击怪物"，检查控制台打印的状态更新是否正确。
+
+请确保 requirements.txt 包含 openai (如果用兼容库) 或 dashscope，以及 gradio, python-dotenv, pydantic。
+Qwen 模型推荐使用 qwen-turbo 或 qwen-plus 以平衡速度和效果。
+请在代码中详细注释 Prompt 的设计思路。
+
+| 模块 | 具体要求 | 为什么重要 |
+| :--- | :--- | :--- |
+| 1. 意图识别 (NLU) | 必须能把玩家乱七八糟的输入（如“我想打怪”）映射到具体的动作类型（如 `ATTACK`）。 | 证明AI听懂了你在说什么，而不是瞎猜。 |
+| 2. 上下文生成 (NLG) | 生成的剧情必须符合之前的设定（人物、地点、物品）。推荐使用结构化输出（先生成大纲再生成文本）。 | 保证剧情连贯，不出现“死人复活”这种低级错误。 |
+| 3. 一致性维护 (Consistency) | 这是最高频的扣分点！ 必须设计机制来检测剧情矛盾（比如时间线错误），并进行修复或拒绝。 | 证明你的系统有“记忆”和“逻辑”。 |
+| 4. 交互与分支 | 不同的选择必须导致不同的后果。系统要有“下一回合”的选项生成能力。 | 证明这是一个游戏，而不是单向的阅读。 |
+
+
+开发提示：
+请利用 Planning 能力，在写代码前先构思数据流转过程。
+state_manager.py 是项目的灵魂，请确保其健壮性。
+生成代码时，请添加必要的注释以解释关键逻辑。
+
+上述是我的建议，如果你对这个系统的开发有什么更好的想法，可以与我沟通。

requirements.txt

@@ -0,0 +1,4 @@
+openai>=1.0.0
+gradio==4.44.0
+python-dotenv>=1.0.0
+pydantic>=2.0.0

scene_assets.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+IMAGE_DIR = Path(__file__).resolve().parent / "image"
+
+
+def _candidate_path(name: str | None) -> Path | None:
+    if not name:
+        return None
+    candidate = IMAGE_DIR / f"{name}.png"
+    if candidate.exists():
+        return candidate
+    return None
+
+
+def get_scene_image_path(game_state, focus_npc: str | None = None) -> str | None:
+    npc_candidate = _candidate_path(focus_npc)
+    if npc_candidate is not None:
+        return str(npc_candidate)
+
+    for name in (
+        getattr(game_state.world, "current_scene", None),
+        getattr(game_state.player, "location", None),
+    ):
+        scene_candidate = _candidate_path(name)
+        if scene_candidate is not None:
+            return str(scene_candidate)
+
+    return None

telemetry.py

@@ -0,0 +1,81 @@
+"""
+telemetry.py - StoryWeaver 结构化交互日志工具
+
+职责：
+1. 为每个游戏会话分配稳定的 session_id
+2. 以 JSONL 形式落盘每回合交互记录
+3. 为评估脚本和案例分析提供统一的日志格式
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+PROJECT_ROOT = Path(__file__).resolve().parent
+DEFAULT_LOG_DIR = PROJECT_ROOT / "logs" / "interactions"
+
+
+def _resolve_log_dir() -> Path:
+    custom_dir = os.getenv("STORYWEAVER_LOG_DIR", "").strip()
+    if custom_dir:
+        return Path(custom_dir).expanduser()
+    return DEFAULT_LOG_DIR
+
+
+def create_session_metadata(session_id: str | None = None) -> dict[str, Any]:
+    """
+    创建新的会话元数据。
+
+    每个会话对应一个单独的 JSONL 文件，便于回放和分析。
+    """
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    new_session_id = session_id or f"sw-{timestamp}-{uuid.uuid4().hex[:8]}"
+    log_dir = _resolve_log_dir()
+    log_path = log_dir / f"{new_session_id}.jsonl"
+    return {
+        "session_id": new_session_id,
+        "turn_index": 0,
+        "interaction_log_path": str(log_path),
+    }
+
+
+def ensure_session_metadata(game_session: dict[str, Any]) -> dict[str, Any]:
+    """确保游戏会话中带有日志所需的元数据。"""
+    if "session_id" not in game_session or "interaction_log_path" not in game_session:
+        game_session.update(create_session_metadata())
+    if "turn_index" not in game_session:
+        game_session["turn_index"] = 0
+    return game_session
+
+
+def append_turn_log(game_session: dict[str, Any], record: dict[str, Any]) -> str:
+    """
+    追加一条结构化交互日志。
+
+    Returns:
+        日志文件路径，便于调试和脚本复用。
+    """
+    ensure_session_metadata(game_session)
+
+    game_session["turn_index"] += 1
+    log_path = Path(game_session["interaction_log_path"])
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = {
+        "timestamp": datetime.now().isoformat(timespec="seconds"),
+        "session_id": game_session["session_id"],
+        "turn_index": game_session["turn_index"],
+        **record,
+    }
+
+    with log_path.open("a", encoding="utf-8") as fh:
+        json.dump(payload, fh, ensure_ascii=False)
+        fh.write("\n")
+
+    return str(log_path)

utils.py

@@ -0,0 +1,328 @@
+"""
+utils.py - StoryWeaver 工具函数模块
+
+职责:
+1. 加载环境变量，初始化 OpenAI 兼容客户端 (Qwen API)
+2. 提供通用的 API 调用封装函数（带重试机制）
+3. 提供 JSON 安全解析工具（从 LLM 输出中提取结构化数据）
+"""
+
+import os
+import re
+import json
+import time
+import logging
+from typing import Any, Optional
+from dotenv import load_dotenv
+
+try:
+    from openai import OpenAI
+    _OPENAI_IMPORT_ERROR: Optional[Exception] = None
+except ImportError as exc:  # pragma: no cover - depends on local env
+    OpenAI = None  # type: ignore[assignment]
+    _OPENAI_IMPORT_ERROR = exc
+
+# ============================================================
+# 日志配置
+# ============================================================
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+logger = logging.getLogger("StoryWeaver")
+
+# ============================================================
+# 环境变量加载 & API 客户端初始化
+# ============================================================
+
+# 从项目根目录的 .env 文件加载环境变量
+load_dotenv()
+
+# 严禁硬编码 API Key —— 仅通过环境变量读取
+QWEN_API_KEY: str = os.getenv("QWEN_API_KEY", "")
+
+if not QWEN_API_KEY or QWEN_API_KEY == "sk-xxxxxx":
+    logger.warning(
+        "⚠️  QWEN_API_KEY 未设置或仍为模板值！"
+        "请在 .env 文件中填写有效的 API Key。"
+    )
+
+# 使用 OpenAI 兼容格式连接 Qwen API
+# base_url 指向通义千问的 OpenAI 兼容端点
+_client: Optional[Any] = None
+
+
+def get_client() -> Any:
+    """
+    获取全局 OpenAI 客户端（懒加载单例）。
+    使用兼容格式调用 Qwen API。
+    """
+    global _client
+    if OpenAI is None:
+        raise RuntimeError(
+            "未安装 openai 依赖，无法初始化 Qwen 客户端。"
+            "请先执行 `pip install -r requirements.txt`。"
+        ) from _OPENAI_IMPORT_ERROR
+    if _client is None:
+        _client = OpenAI(
+            api_key=QWEN_API_KEY,
+            base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+        )
+    return _client
+
+
+# ============================================================
+# 默认模型配置
+# ============================================================
+# 使用 qwen2.5-14b-instruct 以获得最快的响应速度
+DEFAULT_MODEL: str = "qwen2.5-14b-instruct"
+
+
+# ============================================================
+# 通用 API 调用封装（带重试 & 错误处理）
+# ============================================================
+
+
+def call_qwen(
+    messages: list[dict[str, str]],
+    model: str = DEFAULT_MODEL,
+    temperature: float = 0.8,
+    max_tokens: int = 2000,
+    max_retries: int = 3,
+    retry_delay: float = 1.0,
+) -> str:
+    """
+    调用 Qwen API 的通用封装函数。
+
+    设计思路:
+    - 使用 OpenAI 兼容格式，方便后续切换模型
+    - 内置指数退避重试机制，应对网络波动和限流
+    - 返回纯文本内容，JSON 解析交给调用方处理
+
+    Args:
+        messages: OpenAI 格式的消息列表 [{"role": "system", "content": "..."}, ...]
+        model: 模型名称，默认 qwen-plus
+        temperature: 生成温度，越高越有创意（0.0-2.0）
+        max_tokens: 最大生成 token 数
+        max_retries: 最大重试次数
+        retry_delay: 初始重试间隔（秒），每次翻倍
+
+    Returns:
+        模型生成的文本内容
+
+    Raises:
+        Exception: 重试耗尽后抛出最后一次异常
+    """
+    client = get_client()
+    last_exception: Optional[Exception] = None
+
+    for attempt in range(1, max_retries + 1):
+        try:
+            logger.info(f"调用 Qwen API (尝试 {attempt}/{max_retries})，模型: {model}")
+            response = client.chat.completions.create(
+                model=model,
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            content = response.choices[0].message.content.strip()
+            logger.info(f"API 调用成功，响应长度: {len(content)} 字符")
+            return content
+
+        except Exception as e:
+            last_exception = e
+            logger.warning(f"API 调用失败 (尝试 {attempt}/{max_retries}): {e}")
+            if attempt < max_retries:
+                sleep_time = retry_delay * (2 ** (attempt - 1))
+                logger.info(f"等待 {sleep_time:.1f} 秒后重试...")
+                time.sleep(sleep_time)
+
+    # 重试耗尽，抛出异常
+    raise RuntimeError(
+        f"Qwen API 调用在 {max_retries} 次尝试后仍然失败: {last_exception}"
+    )
+
+
+def call_qwen_stream(
+    messages: list[dict[str, str]],
+    model: str = DEFAULT_MODEL,
+    temperature: float = 0.8,
+    max_tokens: int = 2000,
+):
+    """
+    调用 Qwen API 的流式版本，逐块 yield 文本内容。
+
+    使用 stream=True，让用户在 AI 生成过程中就能看到文字逐步出现，
+    大幅改善感知延迟。
+
+    Args:
+        messages: OpenAI 格式的消息列表
+        model: 模型名称
+        temperature: 生成温度
+        max_tokens: 最大生成 token 数
+
+    Yields:
+        每次生成的文本片段（str）
+    """
+    client = get_client()
+    logger.info(f"调用 Qwen 流式 API，模型: {model}")
+    try:
+        response = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+        )
+        for chunk in response:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+    except Exception as e:
+        logger.error(f"流式 API 调用失败: {e}")
+        raise
+
+
+# ============================================================
+# JSON 安全解析工具
+# ============================================================
+
+
+def extract_json_from_text(text: str) -> Optional[dict | list]:
+    """
+    从 LLM 输出的文本中提取 JSON 数据。
+
+    设计思路:
+    LLM 有时会在 JSON 前后附加说明文字，或使用 ```json 代码块包裹。
+    此函数通过多种策略尝试提取有效 JSON：
+    1. 先尝试直接解析整段文本
+    2. 再尝试提取 ```json ... ``` 代码块
+    3. 最后尝试匹配第一个 { ... } 或 [ ... ] 结构
+
+    Args:
+        text: LLM 返回的原始文本
+
+    Returns:
+        解析后的 dict/list，解析失败返回 None
+    """
+    if not text:
+        return None
+
+    # 策略1: 直接解析（LLM 可能返回纯 JSON）
+    try:
+        return json.loads(text.strip())
+    except json.JSONDecodeError:
+        pass
+
+    # 策略2: 提取 ```json ... ``` 代码块
+    code_block_pattern = r"```(?:json)?\s*\n?(.*?)\n?\s*```"
+    matches = re.findall(code_block_pattern, text, re.DOTALL)
+    for match in matches:
+        try:
+            return json.loads(match.strip())
+        except json.JSONDecodeError:
+            continue
+
+    # 策略3: 匹配第一个完整的 JSON 对象 { ... }
+    brace_pattern = r"\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}"
+    brace_matches = re.findall(brace_pattern, text, re.DOTALL)
+    for match in brace_matches:
+        try:
+            return json.loads(match)
+        except json.JSONDecodeError:
+            continue
+
+    # 策略4: 匹配嵌套更深的 JSON（贪婪匹配从第一个 { 到最后一个 }）
+    deep_match = re.search(r"\{.*\}", text, re.DOTALL)
+    if deep_match:
+        try:
+            return json.loads(deep_match.group())
+        except json.JSONDecodeError:
+            pass
+
+    # 策略5: 匹配 JSON 数组 [ ... ]
+    array_match = re.search(r"\[.*\]", text, re.DOTALL)
+    if array_match:
+        try:
+            return json.loads(array_match.group())
+        except json.JSONDecodeError:
+            pass
+
+    logger.warning(f"无法从文本中提取 JSON: {text[:200]}...")
+    return None
+
+
+def safe_json_call(
+    messages: list[dict[str, str]],
+    model: str = DEFAULT_MODEL,
+    temperature: float = 0.3,
+    max_tokens: int = 2000,
+    max_retries: int = 3,
+) -> Optional[dict | list]:
+    """
+    调用 Qwen API 并安全地解析返回的 JSON。
+
+    设计思路:
+    - 将 API 调用与 JSON 解析合为一步
+    - 如果第一次解析失败，会额外重试（重新调用 API）
+    - temperature 默认较低 (0.3)，让 JSON 输出更稳定
+
+    Args:
+        messages: 消息列表
+        model: 模型名称
+        temperature: 生成温度（JSON 输出建议低温）
+        max_tokens: 最大 token 数
+        max_retries: JSON 解析失败时的额外重试次数
+
+    Returns:
+        解析后的 dict/list，全部失败返回 None
+    """
+    for attempt in range(1, max_retries + 1):
+        try:
+            raw_text = call_qwen(
+                messages=messages,
+                model=model,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            result = extract_json_from_text(raw_text)
+            if result is not None:
+                return result
+            logger.warning(
+                f"JSON 解析失败 (尝试 {attempt}/{max_retries})，原始文本: {raw_text[:300]}..."
+            )
+        except Exception as e:
+            logger.error(f"safe_json_call 异常 (尝试 {attempt}/{max_retries}): {e}")
+
+    logger.error(f"safe_json_call 在 {max_retries} 次尝试后仍无法获取有效 JSON")
+    return None
+
+
+# ============================================================
+# 辅助工具函��
+# ============================================================
+
+
+def clamp(value: int, min_val: int, max_val: int) -> int:
+    """将数值限制在 [min_val, max_val] 范围内"""
+    return max(min_val, min(max_val, value))
+
+
+def format_dict_for_prompt(data: dict, indent: int = 0) -> str:
+    """
+    将字典格式化为易读的 Prompt 文本。
+    用于将状态数据注入 System Prompt。
+    """
+    lines = []
+    prefix = "  " * indent
+    for key, value in data.items():
+        if isinstance(value, dict):
+            lines.append(f"{prefix}{key}:")
+            lines.append(format_dict_for_prompt(value, indent + 1))
+        elif isinstance(value, list):
+            if value:
+                lines.append(f"{prefix}{key}: {', '.join(str(v) for v in value)}")
+            else:
+                lines.append(f"{prefix}{key}: 无")
+        else:
+            lines.append(f"{prefix}{key}: {value}")
+    return "\n".join(lines)