上传完整代码

.gitattributes

@@ -33,24 +33,3 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
-image/村口小路.png filter=lfs diff=lfs merge=lfs -text
-image/村长老伯.png filter=lfs diff=lfs merge=lfs -text
-image/村庄广场.png filter=lfs diff=lfs merge=lfs -text
-image/村庄旅店.png filter=lfs diff=lfs merge=lfs -text
-image/村庄铁匠铺.png filter=lfs diff=lfs merge=lfs -text
-image/村庄杂货铺.png filter=lfs diff=lfs merge=lfs -text
-image/渡口老渔夫.png filter=lfs diff=lfs merge=lfs -text
-image/废弃矿洞入口.png filter=lfs diff=lfs merge=lfs -text
-image/古塔废墟.png filter=lfs diff=lfs merge=lfs -text
-image/河边渡口.png filter=lfs diff=lfs merge=lfs -text
-image/黑暗森林入口.png filter=lfs diff=lfs merge=lfs -text
-image/精灵遗迹.png filter=lfs diff=lfs merge=lfs -text
-image/矿洞深层.png filter=lfs diff=lfs merge=lfs -text
-image/旅店老板娘莉娜.png filter=lfs diff=lfs merge=lfs -text
-image/森林深处.png filter=lfs diff=lfs merge=lfs -text
-image/山麓盗贼营.png filter=lfs diff=lfs merge=lfs -text
-image/神秘旅人.png filter=lfs diff=lfs merge=lfs -text
-image/铁匠格林.png filter=lfs diff=lfs merge=lfs -text
-image/溪边营地.png filter=lfs diff=lfs merge=lfs -text
-image/遗迹守护者.png filter=lfs diff=lfs merge=lfs -text
-image/杂货商人阿尔.png filter=lfs diff=lfs merge=lfs -text

app.py

@@ -21,9 +21,54 @@ 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.88em;
+    line-height: 1.6;
+}
+.option-btn {min-height: 50px !important;}
+.scene-sidebar {gap: 14px;}
+.scene-card {
+    border: 1px solid rgba(161, 125, 83, 0.14) !important;
+    border-radius: 18px !important;
+    background:
+        linear-gradient(180deg, rgba(255, 249, 241, 0.98) 0%,
+        rgba(246, 238, 226, 0.96) 100%) !important;
+    box-shadow: 0 14px 28px rgba(110, 81, 49, 0.08) !important;
+}
+.scene-image {
+    min-height: 280px;
+    padding: 14px !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: 14px;
+    padding: 8px;
+    background:
+        radial-gradient(circle at top, rgba(255, 255, 255, 0.95) 0%,
+        rgba(247, 239, 227, 0.92) 100%) !important;
+}
+"""
 
 # ============================================================
 # 全局游戏实例（每个会话独立）
@@ -37,8 +82,8 @@ def create_new_game(player_name: str = "旅人") -> dict:
     """创建新游戏实例，返回包含所有引擎的字典"""
     game_state = GameState(player_name=player_name)
     nlu = NLUEngine(game_state)
-    story = StoryEngine(game_state)
-    return {
+    story = StoryEngine(game_state, enable_rule_text_polish=True)
+    return {
         "game_state": game_state,
         "nlu": nlu,
         "story": story,
@@ -167,14 +212,24 @@ def _build_option_intent(selected_option: dict) -> dict:
     option_text = selected_option.get("text", "")
     return {
         "intent": selected_option.get("action_type", "EXPLORE"),
-        "target": None,
+        "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 restart_game() -> tuple:
+def restart_game() -> tuple:
     """
     重启冒险：清空所有数据，回到初始输入名称阶段。
 
@@ -183,16 +238,15 @@ def restart_game() -> tuple:
          禁用文本输入框, 重置角色名称)
     """
     loading = _get_loading_button_updates()
-    return (
-        [],                                                          # 清空聊天历史
-        "## 等待开始...\n\n请输入角色名称并点击「开始冒险」",         # 重置状态面板
-        loading[0],                                                   # 占位选项按钮1
-        loading[1],                                                   # 占位选项按钮2
-        loading[2],                                                   # 占位选项按钮3
-        {},                                                          # 清空游戏会话
-        gr.update(value="", interactive=False),                       # 禁用并清空文本输入
-        gr.update(value="旅人"),                                      # 重置角色名称
-    )
+    return (
+        [],                                                          # 清空聊天历史
+        "## 等待开始...\n\n请输入角色名称并点击「开始冒险」",         # 重置状态面板
+        gr.update(value=None, visible=False),                        # 清空场景图片
+        *loading,                                                    # 占位选项按钮
+        {},                                                          # 清空游戏会话
+        gr.update(value="", interactive=False),                       # 禁用并清空文本输入
+        gr.update(value="旅人"),                                      # 重置角色名称
+    )
 
 
 # ============================================================
@@ -218,12 +272,12 @@ def start_game(player_name: str, game_session: dict):
     status_text = _format_status_panel(game_session["game_state"])
     loading = _get_loading_button_updates()
 
-    yield (
-        chat_history, status_text,
-        loading[0], loading[1], loading[2],
-        game_session,
-        gr.update(interactive=False),
-    )
+    yield (
+        chat_history, status_text, _get_scene_image_update(game_session["game_state"]),
+        *loading,
+        game_session,
+        gr.update(interactive=False),
+    )
 
     # 流式生成开场（选项仅在流结束后从 final 事件中提取，流式期间不解析选项）
     turn_started = perf_counter()
@@ -234,12 +288,12 @@ def start_game(player_name: str, game_session: dict):
         if update["type"] == "story_chunk":
             story_text = update["text"]
             chat_history[-1]["content"] = story_text
-            yield (
-                chat_history, status_text,
-                loading[0], loading[1], loading[2],
-                game_session,
-                gr.update(interactive=False),
-            )
+            yield (
+                chat_history, status_text, _get_scene_image_update(game_session["game_state"]),
+                *loading,
+                game_session,
+                gr.update(interactive=False),
+            )
         elif update["type"] == "final":
             final_result = update
 
@@ -253,7 +307,7 @@ def start_game(player_name: str, game_session: dict):
         options = []
 
     # ★ 安全兜底：强制确保恰好 3 个选项
-    options = _ensure_min_options(options, 3)
+    options = _finalize_session_options(options)
 
     # 最终 yield：显示完整文本 + 选项 + 启用按钮
     game_session["current_options"] = options
@@ -287,12 +341,12 @@ def start_game(player_name: str, game_session: dict):
         final_result=final_result,
     )
 
-    yield (
-        chat_history, status_text,
-        btn_updates[0], btn_updates[1], btn_updates[2],
-        game_session,
-        gr.update(interactive=True),
-    )
+    yield (
+        chat_history, status_text, _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):
@@ -304,24 +358,25 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
     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, "",
-            loading[0], loading[1], loading[2],
-            game_session,
-        )
-        return
-
-    if not user_input.strip():
-        yield (
-            chat_history, _format_status_panel(game_session["game_state"]),
-            gr.update(), gr.update(), gr.update(),
-            game_session,
-        )
-        return
+    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, "", 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_status_panel(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"]
@@ -329,18 +384,22 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
     turn_started = perf_counter()
 
     # 检查游戏是否已结束
-    if gs.is_game_over():
-        chat_history.append({"role": "user", "content": user_input})
-        chat_history.append({"role": "assistant", "content": "游戏已结束。请点击「重新开始」按钮开始新的冒险。"})
-        yield (
-            chat_history,
-            _format_status_panel(gs),
-            gr.update(value="重新开始", visible=True, interactive=True),
-            gr.update(value="...", visible=True, interactive=False),
-            gr.update(value="...", visible=True, interactive=False),
-            game_session,
-        )
-        return
+    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_status_panel(gs),
+            _get_scene_image_update(gs),
+            *restart_buttons,
+            game_session,
+        )
+        return
 
     # 1. NLU 解析
     nlu_started = perf_counter()
@@ -350,10 +409,10 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
     # 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 = _ensure_min_options(options, 3)
-        options_text = _format_options(options)
+        chat_history.append({"role": "user", "content": user_input})
+        options = game_session.get("current_options", [])
+        options = _finalize_session_options(options)
+        options_text = _format_options(options)
         rejection_content = (
             f"⚠️ **行动被驳回**：{rejection_msg}\n\n"
             f"请重新选择行动，或输入其他指令。\n\n{options_text}"
@@ -383,26 +442,30 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
             final_result=rejection_result,
         )
         btn_updates = _get_button_updates(options)
-        yield (
-            chat_history,
-            _format_status_panel(gs),
-            btn_updates[0], btn_updates[1], btn_updates[2],
-            game_session,
-        )
-        return
+        yield (
+            chat_history,
+            _format_status_panel(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()
-    yield (
-        chat_history,
-        _format_status_panel(gs),
-        loading[0], loading[1], loading[2],
-        game_session,
-    )
+    loading = _get_loading_button_updates(
+        max(len(game_session.get("current_options", [])), MIN_OPTION_BUTTONS)
+    )
+    yield (
+        chat_history,
+        _format_status_panel(gs),
+        _get_scene_image_update(gs),
+        *loading,
+        game_session,
+    )
 
     # 3. 流式生成故事
     generation_started = perf_counter()
@@ -412,10 +475,11 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
             chat_history[-1]["content"] = update["text"]
             yield (
                 chat_history,
-                _format_status_panel(gs),
-                loading[0], loading[1], loading[2],
-                game_session,
-            )
+                _format_status_panel(gs),
+                _get_scene_image_update(gs),
+                *loading,
+                game_session,
+            )
         elif update["type"] == "final":
             final_result = update
 
@@ -424,8 +488,8 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
     # 4. 最终更新：完整文本 + 状态变化 + 选项 + 按钮
     if final_result:
         # ★ 安全兜底：强制确保恰好 3 个选项
-        options = _ensure_min_options(final_result.get("options", []), 3)
-        game_session["current_options"] = options
+        options = _finalize_session_options(final_result.get("options", []))
+        game_session["current_options"] = options
 
         change_log = final_result.get("change_log", [])
         log_text = ""
@@ -459,15 +523,16 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
 
         yield (
             chat_history,
-            status_text,
-            btn_updates[0], btn_updates[1], btn_updates[2],
-            game_session,
-        )
+            status_text,
+            _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
     else:
         # ★ 兜底：final_result 为空，说明流式生成未产生 final 事件
         logger.warning("流式生成未产生 final 事件，使用兜底文本")
         fallback_text = "你环顾四周，思考着接下来该做什么..."
-        fallback_options = _ensure_min_options([], 3)
+        fallback_options = _finalize_session_options([])
         game_session["current_options"] = fallback_options
 
         options_text = _format_options(fallback_options)
@@ -500,42 +565,45 @@ def process_user_input(user_input: str, chat_history: list, game_session: dict):
             final_result=fallback_result,
         )
 
-        yield (
-            chat_history,
-            status_text,
-            btn_updates[0], btn_updates[1], btn_updates[2],
-            game_session,
-        )
-        return
-
+        yield (
+            chat_history,
+            status_text,
+            _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, 1, 2)
+def process_option_click(option_idx: int, chat_history: list, game_session: dict):
     """
-    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, "",
-            loading[0], loading[1], loading[2],
-            game_session,
-        )
-        return
-
-    options = game_session.get("current_options", [])
-    if option_idx >= len(options):
-        yield (
-            chat_history,
-            _format_status_panel(game_session["game_state"]),
-            gr.update(), gr.update(), gr.update(),
-            game_session,
-        )
-        return
+    处理玩家点击选项按钮（流式版本）。
+
+    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, "", 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_status_panel(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"]
@@ -549,15 +617,15 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
         game_session = create_new_game(gs.player.name)
         game_session["started"] = True
 
-        chat_history = [{"role": "assistant", "content": "⏳ 正在重新生成开场..."}]
-        status_text = _format_status_panel(game_session["game_state"])
-        loading = _get_loading_button_updates()
-
-        yield (
-            chat_history, status_text,
-            loading[0], loading[1], loading[2],
-            game_session,
-        )
+        chat_history = [{"role": "assistant", "content": "⏳ 正在重新生成开场..."}]
+        status_text = _format_status_panel(game_session["game_state"])
+        loading = _get_loading_button_updates()
+
+        yield (
+            chat_history, status_text, _get_scene_image_update(game_session["game_state"]),
+            *loading,
+            game_session,
+        )
 
         story_text = ""
         restart_final = None
@@ -566,11 +634,11 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
             if update["type"] == "story_chunk":
                 story_text = update["text"]
                 chat_history[-1]["content"] = story_text
-                yield (
-                    chat_history, status_text,
-                    loading[0], loading[1], loading[2],
-                    game_session,
-                )
+                yield (
+                    chat_history, status_text, _get_scene_image_update(game_session["game_state"]),
+                    *loading,
+                    game_session,
+                )
             elif update["type"] == "final":
                 restart_final = update
 
@@ -582,8 +650,8 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
             restart_options = []
 
         # ★ 安全兜底：强制确保恰好 3 个选项
-        restart_options = _ensure_min_options(restart_options, 3)
-        game_session["current_options"] = restart_options
+        restart_options = _finalize_session_options(restart_options)
+        game_session["current_options"] = restart_options
         options_text = _format_options(restart_options)
         full_message = f"{story_text}\n\n{options_text}"
         chat_history[-1]["content"] = full_message
@@ -591,39 +659,44 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
         status_text = _format_status_panel(game_session["game_state"])
         btn_updates = _get_button_updates(restart_options)
 
-        yield (
-            chat_history, status_text,
-            btn_updates[0], btn_updates[1], btn_updates[2],
-            game_session,
-        )
-        return
+        yield (
+            chat_history, status_text, _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点击「开始冒险」可以重新开始。"})
-        yield (
-            chat_history,
-            _format_status_panel(gs),
-            gr.update(value="重新开始", visible=True, interactive=True),
-            gr.update(value="...", visible=True, interactive=False),
-            gr.update(value="...", visible=True, interactive=False),
-            game_session,
-        )
-        return
+        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_status_panel(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()
-    yield (
-        chat_history,
-        _format_status_panel(gs),
-        loading[0], loading[1], loading[2],
-        game_session,
-    )
+    loading = _get_loading_button_updates(max(len(options), MIN_OPTION_BUTTONS))
+    yield (
+        chat_history,
+        _format_status_panel(gs),
+        _get_scene_image_update(gs),
+        *loading,
+        game_session,
+    )
 
     generation_started = perf_counter()
     final_result = None
@@ -632,10 +705,11 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
             chat_history[-1]["content"] = update["text"]
             yield (
                 chat_history,
-                _format_status_panel(gs),
-                loading[0], loading[1], loading[2],
-                game_session,
-            )
+                _format_status_panel(gs),
+                _get_scene_image_update(gs),
+                *loading,
+                game_session,
+            )
         elif update["type"] == "final":
             final_result = update
 
@@ -643,8 +717,8 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
 
     if final_result:
         # ★ 安全兜底：强制确保恰好 3 个选项
-        options = _ensure_min_options(final_result.get("options", []), 3)
-        game_session["current_options"] = options
+        options = _finalize_session_options(final_result.get("options", []))
+        game_session["current_options"] = options
 
         change_log = final_result.get("change_log", [])
         log_text = ""
@@ -671,15 +745,15 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
         )
 
         yield (
-            chat_history, status_text,
-            btn_updates[0], btn_updates[1], btn_updates[2],
-            game_session,
-        )
-    else:
+            chat_history, status_text, _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
+    else:
         # ★ 兜底：final_result 为空，说明流式生成未产生 final 事件
         logger.warning("[选项点击] 流式生成未产生 final 事件，使用兜底文本")
         fallback_text = "你环顾四周，思考着接下来该做什么..."
-        fallback_options = _ensure_min_options([], 3)
+        fallback_options = _finalize_session_options([])
         game_session["current_options"] = fallback_options
 
         options_text = _format_options(fallback_options)
@@ -712,59 +786,70 @@ def process_option_click(option_idx: int, chat_history: list, game_session: dict
             selected_option=selected_option,
         )
 
-        yield (
-            chat_history, status_text,
-            btn_updates[0], btn_updates[1], btn_updates[2],
-            game_session,
-        )
+        yield (
+            chat_history, status_text, _get_scene_image_update(gs),
+            *btn_updates,
+            game_session,
+        )
         return
 
 
-# ============================================================
-# UI 辅助函数
-# ============================================================
-
-
-# 兜底默认选项（当解析出的选项不足 3 个时使用）
-_FALLBACK_BUTTON_OPTIONS = [
-    {"id": 1, "text": "查看周围", "action_type": "EXPLORE"},
-    {"id": 2, "text": "等待一会", "action_type": "REST"},
-    {"id": 3, "text": "检查状态", "action_type": "EXPLORE"},
-]
-
-
-def _ensure_min_options(options: list[dict], min_count: int = 3) -> list[dict]:
-    """
-    强制确保选项列表至少有 min_count 个选项。
-    不足时用通用兜底选项补全，作为 UI 层的最终安全网。
-    """
-    if not isinstance(options, list):
-        options = []
-
-    if len(options) >= min_count:
-        return options[:min_count]
-
-    # 用兜底选项补全
-    for fb in _FALLBACK_BUTTON_OPTIONS:
-        if len(options) >= min_count:
-            break
-        if not any(o.get("text") == fb["text"] for o in options):
-            options.append(fb.copy())
-
-    # 极端兜底：仍不足则用"继续探索"填充
-    while len(options) < min_count:
-        options.append({
-            "id": len(options) + 1,
-            "text": "继续探索",
-            "action_type": "EXPLORE",
-        })
-
-    # 重新编号
-    for i, opt in enumerate(options[:min_count], 1):
-        if isinstance(opt, dict):
-            opt["id"] = i
-
-    return options[:min_count]
+# ============================================================
+# 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:
@@ -784,33 +869,36 @@ def _format_options(options: list[dict]) -> str:
     return "\n".join(lines)
 
 
-def _get_loading_button_updates() -> list:
-    """返回 3 个加载中占位按钮更新（始终可见，但禁用交互）"""
-    return [
-        gr.update(value="...", visible=True, interactive=False),
-        gr.update(value="...", visible=True, interactive=False),
-        gr.update(value="...", visible=True, interactive=False),
-    ]
-
-
-def _get_button_updates(options: list[dict]) -> list:
-    """从选项列表生成按钮的 gr.update() 对象，始终返回恰好 3 个更新"""
-    # 确保 options 是列表
-    if not isinstance(options, list):
-        options = []
-
-    # ★ 安全兜底：强制补全到 3 个选项，确保按钮永远是 3 个
-    options = _ensure_min_options(options, 3)
-
-    updates = []
-    for i in range(3):
-        opt = options[i]
-        if isinstance(opt, dict):
-            text = opt.get("text", "...")
-        else:
-            text = str(opt) if opt else "..."
-        updates.append(gr.update(value=text, visible=True, interactive=True))
-    return updates
+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:
@@ -820,14 +908,17 @@ def _format_status_panel(gs: GameState) -> str:
     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")
-    hunger_bar = _progress_bar(p.hunger, 100, "饱食")
-    sanity_bar = _progress_bar(p.sanity, 100, "理智")
-    morale_bar = _progress_bar(p.morale, 100, "士气")
+    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 = {
@@ -977,13 +1068,14 @@ def _format_status_panel(gs: GameState) -> str:
 <div>
 <h4 style="margin:4px 0 2px 0;">🩸 生命与状态</h4>
 <span style="font-size:0.85em;">
-{hp_bar}<br>
-{mp_bar}<br>
-{hunger_bar}<br>
-{sanity_bar}<br>
-{morale_bar}
-</span>
-</div>
+{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>
@@ -1026,18 +1118,15 @@ def _format_status_panel(gs: GameState) -> str:
 </div>
 
 <div style="grid-column: 1 / -1;">
-<h4 style="margin:4px 0 2px 0;">🌦️ 环境态势</h4>
-<div style="font-size:0.85em;">
+<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}
-{latest_event_html}
-<span style="color:#475569;">最近环境事件: {recent_event_lines}</span>
-</div>
+<div style="margin:6px 0 8px 0;color:#475569;">
+时间 {clock_display} | 场景 {w.current_scene} | 状态系数 {survival_snapshot.get('combined_multiplier', 1.0)}
 </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:10px;background:#fff7ed;border:1px solid #fed7aa;">
-{scene_summary}
+{latest_event_html}
+<div style="margin-top:8px;">{scene_summary}</div>
+<div style="margin-top:6px;color:#475569;">最近环境事件: {recent_event_lines}</div>
 </div>
 </div>
 
@@ -1051,8 +1140,8 @@ def _format_status_panel(gs: GameState) -> str:
 <div>
 <h4 style="margin:4px 0 2px 0;">🌍 世界信息</h4>
 <span style="font-size:0.85em;">
-位置: {w.current_scene}<br>
-时间: 第{w.day_count}天 {w.time_of_day}<br>
+位置: {w.current_scene}<br>
+时间: 第{w.day_count}天 {w.time_of_day} ({clock_display})<br>
 天气: {w.weather}<br>
 光照: {w.light_level}<br>
 季节: {w.season}<br>
@@ -1079,12 +1168,13 @@ def _progress_bar(current: int, maximum: int, label: str, length: int = 10) -> s
 # ============================================================
 
 
-def build_app() -> gr.Blocks:
-    """构建 Gradio 界面"""
-
-    with gr.Blocks(
-        title="StoryWeaver - 交互式叙事系统",
-    ) as app:
+def build_app() -> gr.Blocks:
+    """构建 Gradio 界面"""
+
+    with gr.Blocks(
+        title="StoryWeaver - 交互式叙事系统",
+    ) as app:
+        app.css = APP_UI_CSS
 
         gr.Markdown(
             """
@@ -1126,17 +1216,54 @@ def build_app() -> gr.Blocks:
                     height=480,
                 )
 
-                # 选项按钮（始终可见，加载时显示占位符）
-                with gr.Row():
-                    option_btn_1 = gr.Button(
-                        "...", visible=True, interactive=False
-                    )
-                    option_btn_2 = gr.Button(
-                        "...", visible=True, interactive=False
-                    )
-                    option_btn_3 = gr.Button(
-                        "...", visible=True, interactive=False
-                    )
+                # 选项按钮（最多 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():
@@ -1148,109 +1275,100 @@ def build_app() -> gr.Blocks:
                     )
                     send_btn = gr.Button("发送", variant="primary", scale=1)
 
-            # ==================
-            # 右侧：状态面板
-            # ==================
-            with gr.Column(scale=2, min_width=250):
-                status_panel = gr.Markdown(
-                    value="## 等待开始...\n\n请输入角色名称并点击「开始冒险」",
-                    label="角色状态",
-                )
+            # ==================
+            # 右侧：状态面板
+            # ==================
+            with gr.Column(scale=2, min_width=250, 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, status_panel,
-                option_btn_1, option_btn_2, option_btn_3,
-                game_session, user_input,
-            ],
-        )
+        start_btn.click(
+            fn=start_game,
+            inputs=[player_name_input, game_session],
+            outputs=[
+                chatbot, status_panel, scene_image,
+                *option_buttons,
+                game_session, user_input,
+            ],
+        )
 
         # 重启冒险
-        restart_btn.click(
-            fn=restart_game,
-            inputs=[],
-            outputs=[
-                chatbot, status_panel,
-                option_btn_1, option_btn_2, option_btn_3,
-                game_session, user_input, player_name_input,
-            ],
-        )
+        restart_btn.click(
+            fn=restart_game,
+            inputs=[],
+            outputs=[
+                chatbot, status_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, status_panel,
-                option_btn_1, option_btn_2, option_btn_3,
-                game_session,
-            ],
-        ).then(
+        send_btn.click(
+            fn=process_user_input,
+            inputs=[user_input, chatbot, game_session],
+            outputs=[
+                chatbot, status_panel, scene_image,
+                *option_buttons,
+                game_session,
+            ],
+        ).then(
             fn=lambda: "",
             outputs=[user_input],
         )
 
         # 回车发送
-        user_input.submit(
-            fn=process_user_input,
-            inputs=[user_input, chatbot, game_session],
-            outputs=[
-                chatbot, status_panel,
-                option_btn_1, option_btn_2, option_btn_3,
-                game_session,
-            ],
-        ).then(
+        user_input.submit(
+            fn=process_user_input,
+            inputs=[user_input, chatbot, game_session],
+            outputs=[
+                chatbot, status_panel, scene_image,
+                *option_buttons,
+                game_session,
+            ],
+        ).then(
             fn=lambda: "",
             outputs=[user_input],
         )
 
         # 选项按钮点击（需要使用 yield from 的生成器包装函数，
         # 使 Gradio 能正确识别为流式输出）
-        def _option_click_0(ch, gs):
-            yield from process_option_click(0, ch, gs)
-
-        def _option_click_1(ch, gs):
-            yield from process_option_click(1, ch, gs)
-
-        def _option_click_2(ch, gs):
-            yield from process_option_click(2, ch, gs)
-
-        option_btn_1.click(
-            fn=_option_click_0,
-            inputs=[chatbot, game_session],
-            outputs=[
-                chatbot, status_panel,
-                option_btn_1, option_btn_2, option_btn_3,
-                game_session,
-            ],
-        )
-
-        option_btn_2.click(
-            fn=_option_click_1,
-            inputs=[chatbot, game_session],
-            outputs=[
-                chatbot, status_panel,
-                option_btn_1, option_btn_2, option_btn_3,
-                game_session,
-            ],
-        )
-
-        option_btn_3.click(
-            fn=_option_click_2,
-            inputs=[chatbot, game_session],
-            outputs=[
-                chatbot, status_panel,
-                option_btn_1, option_btn_2, option_btn_3,
-                game_session,
-            ],
-        )
+        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, status_panel, scene_image,
+                    *option_buttons,
+                    game_session,
+                ],
+            )
 
     return app
 
@@ -1271,9 +1389,5 @@ if __name__ == "__main__":
             primary_hue="emerald",
             secondary_hue="blue",
         ),
-        css="""
-        .story-chat {min-height: 500px;}
-        .status-panel {font-family: monospace; font-size: 0.85em;}
-        .option-btn {min-height: 50px !important;}
-        """,
-    )
+        css=APP_UI_CSS,
+    )

demo_rules.py

@@ -0,0 +1,1402 @@
+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]] = []
+    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
+        actions.append(
+            _make_action(
+                action_type="TRADE",
+                target={"merchant": merchant_name, "item": item_name, "confirm": False},
+                text=f"购买{item_name}（{price}金币）",
+                priority=120 - index * 4,
+            )
+        )
+
+    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)

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