Upload 6 files

app.py

@@ -0,0 +1,633 @@
+"""
+app.py - StoryWeaver Gradio 交互界面
+
+职责：
+1. 构建游戏的 Web 前端界面 (Gradio)
+2. 串联 NLU 引擎、叙事引擎、状态管理器
+3. 管理用户交互流程（文本输入 + 选项点击）
+4. 展示游戏状态（HP、背包、任务等）
+
+数据流转：
+  用户输入 → NLU 引擎（意图识别） → 叙事引擎（两阶段生成）
+      ↕                                    ↕
+  Gradio UI  ←  状态管理器（校验 + 更新）  ←  叙事引擎（文本 + 选项）
+"""
+
+import json
+import logging
+import gradio as gr
+
+from state_manager import GameState
+from nlu_engine import NLUEngine
+from story_engine import StoryEngine
+from utils import logger
+
+# ============================================================
+# 全局游戏实例（每个会话独立）
+# ============================================================
+
+# 使用 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)
+    return {
+        "game_state": game_state,
+        "nlu": nlu,
+        "story": story,
+        "current_options": [],
+        "started": False,
+    }
+
+
+def restart_game() -> tuple:
+    """
+    重启冒险：清空所有数据，回到初始输入名称阶段。
+
+    Returns:
+        (空聊天历史, 初始状态面板, 隐藏选项按钮×3, 空游戏会话,
+         禁用文本输入框, 重置角色名称)
+    """
+    return (
+        [],                                                          # 清空聊天历史
+        "## 等待开始...\n\n请输入角色名称并点击「开始冒险」",         # 重置状态面板
+        gr.update(visible=False, interactive=False),                  # 隐藏选项按钮1
+        gr.update(visible=False, interactive=False),                  # 隐藏选项按钮2
+        gr.update(visible=False, interactive=False),                  # 隐藏选项按钮3
+        {},                                                          # 清空游戏会话
+        gr.update(value="", interactive=False),                       # 禁用并清空文本输入
+        gr.update(value="旅人"),                                      # 重置角色名称
+    )
+
+
+# ============================================================
+# 核心交互函数
+# ============================================================
+
+
+def start_game(player_name: str, game_session: dict) -> tuple:
+    """
+    开始新游戏：生成开场叙事。
+
+    Returns:
+        (聊天历史, 状态面板文本, 选项按钮文本, 游戏会话)
+    """
+    if not player_name.strip():
+        player_name = "旅人"
+
+    # 创建新游戏
+    game_session = create_new_game(player_name)
+    game_session["started"] = True
+
+    # 生成开场
+    result = game_session["story"].generate_opening()
+
+    # 保存当前选项
+    game_session["current_options"] = result.get("options", [])
+
+    # 构建聊天历史
+    story_text = result["story_text"]
+    options_text = _format_options(result.get("options", []))
+    full_message = f"{story_text}\n\n{options_text}"
+
+    chat_history = [{"role": "assistant", "content": full_message}]
+
+    # 状态面板
+    status_text = _format_status_panel(game_session["game_state"])
+
+    # 选项按钮更新（静态按钮 + 动态更新模式）
+    btn_updates = _get_button_updates(result.get("options", []))
+
+    return (
+        chat_history,
+        status_text,
+        btn_updates[0], btn_updates[1], btn_updates[2],
+        game_session,
+        gr.update(interactive=True),  # 文本输入框
+    )
+
+
+def process_user_input(user_input: str, chat_history: list, game_session: dict) -> tuple:
+    """
+    处理用户文本输入。
+
+    流程：
+    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": "请先点击「开始冒险」按钮！"})
+        return (
+            chat_history, "",
+            gr.update(visible=False), gr.update(visible=False), gr.update(visible=False),
+            game_session,
+        )
+
+    if not user_input.strip():
+        return (
+            chat_history, _format_status_panel(game_session["game_state"]),
+            gr.update(), gr.update(), gr.update(),
+            game_session,
+        )
+
+    gs: GameState = game_session["game_state"]
+    nlu: NLUEngine = game_session["nlu"]
+    story: StoryEngine = game_session["story"]
+
+    # 检查游戏是否已结束
+    if gs.is_game_over():
+        chat_history.append({"role": "user", "content": user_input})
+        chat_history.append({"role": "assistant", "content": "游戏已结束。请点击「重新开始」按钮开始新的冒险。"})
+        return (
+            chat_history,
+            _format_status_panel(gs),
+            gr.update(value="重新开始", visible=True, interactive=True),
+            gr.update(visible=False), gr.update(visible=False),
+            game_session,
+        )
+
+    # 1. NLU 解析
+    intent = nlu.parse_intent(user_input)
+
+    # 2. 生成故事
+    result = story.generate_story(intent)
+
+    # 3. 更新选项
+    game_session["current_options"] = result.get("options", [])
+
+    # 4. 构建聊天消息
+    chat_history.append({"role": "user", "content": user_input})
+
+    # 变更日志
+    change_log = 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 = 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}"
+
+    # 选项文本
+    options_text = _format_options(result.get("options", []))
+
+    full_message = f"{result['story_text']}{log_text}{issues_text}\n\n{options_text}"
+    chat_history.append({"role": "assistant", "content": full_message})
+
+    # 5. 更新状态面板
+    status_text = _format_status_panel(gs)
+    btn_updates = _get_button_updates(result.get("options", []))
+
+    return (
+        chat_history,
+        status_text,
+        btn_updates[0], btn_updates[1], btn_updates[2],
+        game_session,
+    )
+
+
+def process_option_click(option_idx: int, chat_history: list, game_session: dict) -> tuple:
+    """
+    处理玩家点击选项按钮。
+
+    Args:
+        option_idx: 选项索引 (0, 1, 2)
+    """
+    if not game_session or not game_session.get("started"):
+        chat_history = chat_history or []
+        chat_history.append({"role": "assistant", "content": "请先点击「开始冒险」按钮！"})
+        return (
+            chat_history, "",
+            gr.update(visible=False), gr.update(visible=False), gr.update(visible=False),
+            game_session,
+        )
+
+    options = game_session.get("current_options", [])
+    if option_idx >= len(options):
+        return (
+            chat_history,
+            _format_status_panel(game_session["game_state"]),
+            gr.update(), gr.update(), gr.update(),
+            game_session,
+        )
+
+    selected_option = options[option_idx]
+    gs: GameState = game_session["game_state"]
+    story: StoryEngine = game_session["story"]
+
+    # 检查特殊选项：重新开始
+    if selected_option.get("action_type") == "RESTART":
+        full_result = start_game(gs.player.name, game_session)
+        # start_game 返回 7 个值（含 user_input 更新），此处只需前 6 个
+        return full_result[:6]
+
+    # 检查特殊选项：退出
+    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点击「开始冒险」可以重新开始。"})
+        return (
+            chat_history,
+            _format_status_panel(gs),
+            gr.update(value="重新开始", visible=True, interactive=True),
+            gr.update(visible=False), gr.update(visible=False),
+            game_session,
+        )
+
+    # 正常选项处理
+    chat_history.append({"role": "user", "content": f"选择: {selected_option['text']}"})
+
+    result = story.process_option_selection(selected_option)
+    game_session["current_options"] = result.get("options", [])
+
+    # 构建响应消息
+    change_log = 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}"
+
+    options_text = _format_options(result.get("options", []))
+    full_message = f"{result['story_text']}{log_text}\n\n{options_text}"
+    chat_history.append({"role": "assistant", "content": full_message})
+
+    status_text = _format_status_panel(gs)
+    btn_updates = _get_button_updates(result.get("options", []))
+
+    return (
+        chat_history,
+        status_text,
+        btn_updates[0], btn_updates[1], btn_updates[2],
+        game_session,
+    )
+
+
+# ============================================================
+# UI 辅助函数
+# ============================================================
+
+
+def _format_options(options: list[dict]) -> str:
+    """将选项列表格式化为可读的文本"""
+    if not options:
+        return ""
+    lines = ["---", "**你的选择：**"]
+    for opt in options:
+        idx = opt.get("id", "?")
+        text = opt.get("text", "未知选项")
+        lines.append(f"  **[{idx}]** {text}")
+    return "\n".join(lines)
+
+
+def _get_button_updates(options: list[dict]) -> list:
+    """从选项列表生成按钮的 gr.update() 对象（静态按钮 + 动态更新模式）"""
+    updates = []
+    for i in range(3):
+        if i < len(options):
+            text = options[i].get("text", "...")
+            updates.append(gr.update(value=text, visible=True, interactive=True))
+        else:
+            updates.append(gr.update(value="", visible=False, interactive=False))
+    return updates
+
+
+def _format_status_panel(gs: GameState) -> str:
+    """格式化状态面板文本（双列 HTML 布局，减少滚动）"""
+    p = gs.player
+    w = gs.world
+
+    # 属性进度条
+    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, "士气")
+
+    # 装备
+    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)
+
+    # 状态效果
+    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 = "空"
+
+    # 活跃任务
+    active_quests = [q for q in w.quests.values() if q.status == "active"]
+    if active_quests:
+        quest_lines = []
+        for q in active_quests:
+            done = sum(1 for v in q.objectives.values() if v)
+            total = len(q.objectives)
+            quest_lines.append(f"{q.title}（{done}/{total}）")
+        quest_text = "<br>".join(quest_lines)
+    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>
+{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;">
+攻击: {p.attack}<br>
+防御: {p.defense}<br>
+速度: {p.speed}<br>
+幸运: {p.luck}<br>
+感知: {p.perception}
+</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;">
+{equip_text}
+</span>
+</div>
+
+<div>
+<h4 style="margin:4px 0 2px 0;">✨ 状态效果</h4>
+<span style="font-size:0.85em;">
+{effect_lines}
+</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;">
+{quest_text}
+</span>
+</div>
+
+<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.weather}<br>
+季节: {w.season}<br>
+回合: {gs.turn}
+</span>
+</div>
+
+</div>
+</div>"""
+    return status
+
+
+def _progress_bar(current: int, maximum: int, label: str, length: int = 10) -> str:
+    """生成文本进度条"""
+    ratio = current / maximum if maximum > 0 else 0
+    filled = int(ratio * length)
+    empty = length - filled
+    bar = "█" * filled + "░" * empty
+    return f"{label}: {bar} {current}/{maximum}"
+
+
+# ============================================================
+# Gradio 界面构建
+# ============================================================
+
+
+def build_app() -> gr.Blocks:
+    """构建 Gradio 界面"""
+
+    with gr.Blocks(
+        title="StoryWeaver - 交互式叙事系统",
+    ) as app:
+
+        gr.Markdown(
+            """
+            # StoryWeaver — 交互式叙事系统
+            *基于 AI 的动态分支剧情 RPG 体验*
+            """
+        )
+
+        # 游戏会话状��（Gradio State）
+        game_session = gr.State(value={})
+
+        with gr.Row():
+            # ==================
+            # 左侧：聊天区域
+            # ==================
+            with gr.Column(scale=3):
+                # 玩家姓名输入 + 开始按钮
+                with gr.Row():
+                    player_name_input = gr.Textbox(
+                        label="角色名称",
+                        placeholder="输入你的角色名称（默认: 旅人）",
+                        value="旅人",
+                        scale=3,
+                    )
+                    start_btn = gr.Button(
+                        "开始冒险",
+                        variant="primary",
+                        scale=1,
+                    )
+                    restart_btn = gr.Button(
+                        "重启冒险",
+                        variant="stop",
+                        scale=1,
+                    )
+
+                # 聊天窗口
+                chatbot = gr.Chatbot(
+                    label="故事",
+                    height=480,
+                )
+
+                # 选项按钮
+                with gr.Row():
+                    option_btn_1 = gr.Button(
+                        "选项 1", visible=False
+                    )
+                    option_btn_2 = gr.Button(
+                        "选项 2", visible=False
+                    )
+                    option_btn_3 = gr.Button(
+                        "选项 3", visible=False
+                    )
+
+                # 自由输入
+                with gr.Row():
+                    user_input = gr.Textbox(
+                        label="自由输入（也可以直接点击上方选项）",
+                        placeholder="输入你想做的事情，例如：和村长说话、攻击哥布林、搜索这个区域...",
+                        scale=4,
+                        interactive=False,
+                    )
+                    send_btn = gr.Button("发送", variant="primary", scale=1)
+
+            # ==================
+            # 右侧：状态面板
+            # ==================
+            with gr.Column(scale=1):
+                status_panel = gr.Markdown(
+                    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,
+            ],
+        )
+
+        # 重启冒险
+        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,
+            ],
+        )
+
+        # 文本输入发送
+        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(
+            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(
+            fn=lambda: "",
+            outputs=[user_input],
+        )
+
+        # 选项按钮点击
+        option_btn_1.click(
+            fn=lambda ch, gs: process_option_click(0, ch, gs),
+            inputs=[chatbot, game_session],
+            outputs=[
+                chatbot, status_panel,
+                option_btn_1, option_btn_2, option_btn_3,
+                game_session,
+            ],
+        )
+
+        option_btn_2.click(
+            fn=lambda ch, gs: process_option_click(1, ch, gs),
+            inputs=[chatbot, game_session],
+            outputs=[
+                chatbot, status_panel,
+                option_btn_1, option_btn_2, option_btn_3,
+                game_session,
+            ],
+        )
+
+        option_btn_3.click(
+            fn=lambda ch, gs: process_option_click(2, ch, gs),
+            inputs=[chatbot, game_session],
+            outputs=[
+                chatbot, status_panel,
+                option_btn_1, option_btn_2, option_btn_3,
+                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="""
+        .story-chat {min-height: 500px;}
+        .status-panel {font-family: monospace; font-size: 0.85em;}
+        .option-btn {min-height: 50px !important;}
+        """,
+    )

nlu_engine.py

@@ -0,0 +1,310 @@
+"""
+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 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": "",
+            }
+
+        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["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"
+            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,
+        }
+
+    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 _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 "当前场景中没有特别的可交互对象"

requirements.txt

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

state_manager.py

@@ -0,0 +1,1481 @@
+"""
+state_manager.py - StoryWeaver 状态管理器
+
+职责：
+1. 定义游戏世界的完整数据模型（Pydantic BaseModel）
+2. 维护全局状态的唯一真相来源 (Single Source of Truth)
+3. 提供状态变更、校验、一致性检查、序列化等核心方法
+4. 记录事件日志用于一致性维护
+
+设计思路：
+- 所有数据结构使用 Pydantic BaseModel，天然支持 JSON 序列化/反序列化
+- GameState 是顶层容器，包含 PlayerState、WorldState、EventLog
+- event_log 是一致性维护的灵魂：每次操作都记录快照，用于矛盾检测
+- to_prompt() 方法将结构化数据转为自然语言，注入 LLM 的 System Prompt
+"""
+
+from __future__ import annotations
+
+import copy
+import logging
+from typing import Any, Optional
+from pydantic import BaseModel, Field
+
+from utils import clamp
+
+logger = logging.getLogger("StoryWeaver")
+
+
+# ============================================================
+# 辅助数据模型
+# ============================================================
+
+
+class StatusEffect(BaseModel):
+    """
+    状态效果模型（Buff / Debuff）
+
+    设计思路：
+    - 每个状态效果有持续时间和属性修正，每回合自动结算
+    - source 记录来源，便于在 Prompt 中说明"你身上中了哥布林的毒"
+    - stackable 控制是否可叠加，防止无限叠加 bug
+    """
+    name: str                                     # 效果名（中毒、祝福、隐身…）
+    effect_type: str = "debuff"                   # buff / debuff / neutral
+    stat_modifiers: dict[str, int] = Field(default_factory=dict)
+                                                  # 属性修正 {"attack": -3, "defense": +2}
+    duration: int = 3                             # 剩余持续回合数（-1 = 永久）
+    description: str = ""                         # 效果描述
+    source: str = ""                              # 来源（"哥布林的毒刃"）
+    stackable: bool = False                       # 是否可叠加
+
+
+class ItemInfo(BaseModel):
+    """
+    物品详情模型
+
+    设计思路：
+    - item_type 区分装备/消耗品/任务道具等，不同类型有不同交互逻辑
+    - rarity 影响掉落概率和商店价格
+    - quest_related 标记任务道具，防止玩家丢弃关键物品
+    - lore_text 提供物品背景，丰富生成文本的细节
+    """
+    name: str                                     # 物品名称
+    item_type: str = "misc"                       # weapon / armor / consumable / quest_item / material / key / misc
+    description: str = ""                         # 物品描述
+    rarity: str = "common"                        # common / uncommon / rare / epic / legendary
+    stat_bonus: dict[str, int] = Field(default_factory=dict)
+                                                  # 装备时属性加成 {"attack": +5}
+    usable: bool = False                          # 是否可主动使用
+    use_effect: str = ""                          # 使用效果描述（如"恢复 30 HP"）
+    value: int = 0                                # 商店价值（金币）
+    quest_related: bool = False                   # 是否为任务道具
+    lore_text: str = ""                           # 物品背景故事
+
+
+class NPCState(BaseModel):
+    """
+    NPC 状态模型
+
+    设计思路：
+    - npc_type 决定交互方式（商人可交易、任务NPC可接任务、敌人可战斗）
+    - memory 是一致性维护的关键：NPC"记住"与玩家的互动历史
+    - schedule 模拟 NPC 日常行为，不同时间段出现在不同地点
+    - relationship_level 影响对话态度和任务可用性
+    """
+    name: str                                     # NPC 名称
+    npc_type: str = "civilian"                    # civilian / merchant / quest_giver / enemy / companion / boss
+    location: str = ""                            # 所在地点
+    attitude: str = "neutral"                     # friendly / neutral / cautious / hostile
+    is_alive: bool = True                         # 是否存活
+    description: str = ""                         # 外观描述
+    race: str = "人类"                             # 种族
+    occupation: str = ""                          # 职业（铁匠、旅店老板、守卫…）
+    faction: str = ""                             # 所属阵营
+
+    # --- 交互相关 ---
+    relationship_level: int = 0                   # 与玩家好感度（-100 ~ 100）
+    dialogue_tags: list[str] = Field(default_factory=list)
+                                                  # 已触发的对话标签（防止重复触发）
+    can_trade: bool = False                       # 是否可交易
+    shop_inventory: list[str] = Field(default_factory=list)
+                                                  # 商店物品（如果是商人）
+    can_give_quest: bool = False                  # 是否可发布任务
+    available_quests: list[str] = Field(default_factory=list)
+                                                  # 可发布的任务 ID
+
+    # --- 战斗相关（敌人/Boss） ---
+    hp: int = 0
+    max_hp: int = 0
+    attack: int = 0
+    defense: int = 0
+    loot_table: list[str] = Field(default_factory=list)
+                                                  # 击败后掉落物品
+    weakness: str = ""                            # 弱点（火、光…）
+    special_ability: str = ""                     # 特殊能力
+
+    # --- 记忆与行为 ---
+    memory: list[str] = Field(default_factory=list)
+                                                  # NPC 记住的关键事件
+    schedule: dict[str, str] = Field(default_factory=dict)
+                                                  # 时间行为表 {"清晨": "在市场摆摊"}
+    backstory: str = ""                           # 背景故事
+
+
+class QuestRewards(BaseModel):
+    """
+    任务奖励模型
+
+    设计思路：
+    - 奖励类型丰富，覆盖经济、声望、技能、称号等多维度
+    - 每种奖励都可选，通过组合实现多样化的奖励体验
+    """
+    gold: int = 0                                 # 金币奖励
+    experience: int = 0                           # 经验值奖励
+    items: list[str] = Field(default_factory=list)
+                                                  # 奖励物品
+    reputation_changes: dict[str, int] = Field(default_factory=dict)
+                                                  # 声望变化 {"精灵族": +10}
+    karma_change: int = 0                         # 善恶值变化
+    unlock_location: str = ""                     # 解锁新地点
+    unlock_skill: str = ""                        # 解锁新技能
+    title: str = ""                               # 解锁称号
+
+
+class QuestState(BaseModel):
+    """
+    任务状态模型
+
+    设计思路：
+    - quest_type 区分主线/支线/隐藏任务，影响 UI 展示和优先级
+    - objectives 是任务子目标字典，每个子目标独立追踪
+    - branching_choices 支持任务内分支（如"放走囚犯"导向不同结局）
+    - time_limit / turns_remaining 支持限时任务机制
+    - prerequisites 保证任务链的逻辑顺序
+    """
+    quest_id: str                                 # 任务唯一 ID
+    title: str                                    # 任务名称
+    description: str                              # 任务描述
+    quest_type: str = "main"                      # main / side / hidden / daily
+    status: str = "active"                        # active / completed / failed / expired
+    giver_npc: str = ""                           # 任务发布者 NPC
+
+    # --- 目标 ---
+    objectives: dict[str, bool] = Field(default_factory=dict)
+                                                  # 子目标 {"找到钥匙": False, "打开宝箱": False}
+
+    # --- 奖励 ---
+    rewards: QuestRewards = Field(default_factory=QuestRewards)
+
+    # --- 约束 ---
+    time_limit: int = -1                          # 限时回合数（-1 = 无限）
+    turns_remaining: int = -1                     # 剩余回合数
+    prerequisites: list[str] = Field(default_factory=list)
+                                                  # 前置任务 ID
+    level_requirement: int = 1                    # 等级要求
+    karma_requirement: Optional[int] = None       # 善恶值要求
+
+    # --- 分支 ---
+    branching_choices: dict[str, str] = Field(default_factory=dict)
+                                                  # 关键选择 {"放走囚犯": "mercy_path"}
+    chosen_path: str = ""                         # 已选择的路线
+    consequences: list[str] = Field(default_factory=list)
+                                                  # 完成后的剧情后果描述
+
+
+class LocationInfo(BaseModel):
+    """
+    地点详情模型
+
+    设计思路：
+    - connected_to 构成游戏地图的拓扑结构，控制玩家可移动范围
+    - danger_level 影响遭遇概率和 NPC 行为
+    - is_accessible + required_item 实现"锁门/钥匙"机制
+    - ambient_description 用于丰富 LLM 生成的场景描写
+    - special_events 支持地点触发式事件
+    """
+    name: str                                     # 地点名称
+    location_type: str = "town"                   # town / dungeon / wilderness / shop / special
+    description: str = ""                         # 地点描述
+    connected_to: list[str] = Field(default_factory=list)
+                                                  # 可前往的相邻地点
+    npcs_present: list[str] = Field(default_factory=list)
+                                                  # 当前在该地点的 NPC
+    available_items: list[str] = Field(default_factory=list)
+                                                  # 可拾取/发现的物品
+    enemies: list[str] = Field(default_factory=list)
+                                                  # 可能遭遇的敌人
+    danger_level: int = 0                         # 危险等级 (0=安全, 10=极度危险)
+    weather: str = "晴朗"                          # 当前天气
+    is_discovered: bool = False                   # 是否已被玩家发现
+    is_accessible: bool = True                    # 是否可进入
+    required_item: str = ""                       # 进入所需道具
+    ambient_description: str = ""                 # 环境氛围描述
+    special_events: list[str] = Field(default_factory=list)
+                                                  # 该地点可触发的特殊事件
+    rest_available: bool = False                  # 是否可以休息恢复
+    shop_available: bool = False                  # 是否有商店
+
+
+# ============================================================
+# 玩家状态
+# ============================================================
+
+
+class PlayerState(BaseModel):
+    """
+    玩家角色状态（RPG 核心属性）
+
+    设计思路：
+    - 基础属性 + 战斗属性 + 装备栏 + 社交属性 构成完整的角色模型
+    - reputation / karma / relationships 影响 NPC 态度和剧情分支
+    - morale / sanity / hunger 增加生存维度，丰富游戏体验
+    - known_lore 记录玩家获得的情报，影响可用对话选项
+    - death_count 支持"轮回"类剧情彩蛋
+    """
+    # --- 基础属性 ---
+    name: str = "旅人"                             # 玩家名称
+    title: str = "无名冒险者"                       # 称号（随剧情解锁）
+    level: int = 1                                # 等级
+    experience: int = 0                           # 当前经验值
+    exp_to_next_level: int = 100                  # 升级所需经验
+
+    # --- 战斗属性 ---
+    hp: int = 100                                 # 当前生命值
+    max_hp: int = 100                             # 最大生命值
+    mp: int = 50                                  # 魔力值
+    max_mp: int = 50                              # 最大魔力值
+    attack: int = 10                              # 攻击力
+    defense: int = 5                              # 防御力
+    speed: int = 8                                # 速度（影响行动顺序）
+    luck: int = 5                                 # 幸运（影响暴击、掉落）
+    perception: int = 5                           # 感知（影响探索发现、陷阱识别）
+
+    # --- 装备栏 ---
+    equipment: dict[str, Optional[str]] = Field(default_factory=lambda: {
+        "weapon": None,       # 武器
+        "armor": None,        # 护甲
+        "accessory": None,    # 饰品
+        "helmet": None,       # 头盔
+        "boots": None,        # 靴子
+    })
+
+    # --- 状态 ---
+    location: str = "村庄"                         # 当前所在地点
+    inventory: list[str] = Field(default_factory=list)
+                                                  # 背包物品列表
+    skills: list[str] = Field(default_factory=list)
+                                                  # 已习得技能列表
+    status_effects: list[StatusEffect] = Field(default_factory=list)
+                                                  # 状态效果列表
+    gold: int = 50                                # 金币
+    reputation: dict[str, int] = Field(default_factory=dict)
+                                                  # 阵营声望 {"精灵族": 10}
+    morale: int = 100                             # 士气（0=崩溃, 100=高昂）
+    sanity: int = 100                             # 理智值（探索黑暗区域消耗）
+    hunger: int = 100                             # 饱食度（0=饥饿惩罚）
+    karma: int = 0                                # 善恶值（正=善, 负=恶）
+    known_lore: list[str] = Field(default_factory=list)
+                                                  # 已知传说/情报片段
+    relationships: dict[str, int] = Field(default_factory=dict)
+                                                  # 与特定 NPC 的好感度
+    death_count: int = 0                          # 累计死亡次数
+
+
+# ============================================================
+# 世界状态
+# ============================================================
+
+
+class WorldState(BaseModel):
+    """
+    世界状态容器
+
+    设计思路：
+    - 包含所有非玩家的世界数据：地图、NPC、任务、物品注册表
+    - time_of_day + day_count + weather + season 构成动态环境系统
+    - global_flags 是灵活的剧情标记系统，支持分支判断
+    - rumors / active_threats 丰富 NPC 对话内容
+    - faction_relations 支持阵营间动态关系
+    """
+    current_scene: str = "村庄广场"                 # 当前场景名称
+    time_of_day: str = "清晨"                      # 清晨 / 上午 / 正午 / 下�� / 黄昏 / 夜晚 / 深夜
+    day_count: int = 1                            # 当前天数
+    weather: str = "晴朗"                          # 晴朗 / 多云 / 小雨 / 暴风雨 / 大雪 / 浓雾
+    season: str = "春"                             # 春 / 夏 / 秋 / 冬
+
+    # --- 地图 ---
+    locations: dict[str, LocationInfo] = Field(default_factory=dict)
+    discovered_locations: list[str] = Field(default_factory=list)
+
+    # --- NPC ---
+    npcs: dict[str, NPCState] = Field(default_factory=dict)
+
+    # --- 任务 ---
+    quests: dict[str, QuestState] = Field(default_factory=dict)
+
+    # --- 物品注册表 ---
+    item_registry: dict[str, ItemInfo] = Field(default_factory=dict)
+
+    # --- 全局标记 ---
+    global_flags: dict[str, bool] = Field(default_factory=dict)
+    world_events: list[str] = Field(default_factory=list)
+                                                  # 已发生的全局事件
+    active_threats: list[str] = Field(default_factory=list)
+                                                  # 当前全局威胁
+    rumors: list[str] = Field(default_factory=list)
+                                                  # 流传的传闻
+    faction_relations: dict[str, dict[str, str]] = Field(default_factory=dict)
+                                                  # 阵营间关系
+
+
+# ============================================================
+# 事件日志
+# ============================================================
+
+
+class GameEvent(BaseModel):
+    """
+    事件日志模型（一致性维护的关键）
+
+    设计思路：
+    - 每次状态变更都记录为一个事件，包含完整的上下文信息
+    - state_changes 记录该事件引发的状态变更快照
+    - consequence_tags 用于后续一致性检查（如 "killed_goblin_king"）
+    - is_reversible 标记不可逆事件，LLM 生成时需特别注意
+    - involved_npcs + location 便于按维度检索历史事件
+    """
+    turn: int                                     # 发生在第几回合
+    day: int = 1                                  # 发生在第几天
+    time_of_day: str = ""                         # 发生时的时段
+    event_type: str = ""                          # COMBAT / DIALOGUE / MOVE / ITEM / QUEST / TRADE / REST / DISCOVERY / DEATH / LEVEL_UP
+    description: str = ""                         # 事件简述
+    location: str = ""                            # 事件发生地点
+    involved_npcs: list[str] = Field(default_factory=list)
+                                                  # 涉及的 NPC
+    state_changes: dict = Field(default_factory=dict)
+                                                  # 状态变更快照
+    player_action: str = ""                       # 触发该事件的玩家操作
+    consequence_tags: list[str] = Field(default_factory=list)
+                                                  # 后果标签
+    is_reversible: bool = True                    # 是否可逆
+
+
+# ============================================================
+# 游戏主控类
+# ============================================================
+
+
+class GameState:
+    """
+    游戏全局状态管理器 —— 项目的灵魂
+
+    职责：
+    1. 持有并管理 PlayerState、WorldState、EventLog
+    2. 提供状态变更、校验、一致性检查的统一入口
+    3. 将结构化状态序列化为自然语言 Prompt
+    4. 每回合自动结算状态效果、时间推进、任务超时等
+
+    核心设计原则：
+    - 所有状态修改必须通过 apply_changes() 进入
+    - 每次修改都伴随 validate() 校验和 log_event() 记录
+    - check_consistency() 在生成前检测可能的矛盾
+    """
+
+    def __init__(self, player_name: str = "旅人"):
+        """初始化游戏状态，创建默认的起始世界"""
+        self.player = PlayerState(name=player_name)
+        self.world = WorldState()
+        self.event_log: list[GameEvent] = []
+        self.turn: int = 0
+        self.game_mode: str = "exploration"       # exploration / combat / dialogue / cutscene / game_over
+        self.difficulty: str = "normal"            # easy / normal / hard
+        self.story_arc: str = "序章"               # 当前故事章节
+        self.ending_flags: dict[str, bool] = {}   # 结局条件追踪
+        self.combat_log: list[str] = []           # 最近战斗记录
+        self.achievement_list: list[str] = []     # 已解锁成就
+
+        # 初始化起始世界
+        self._init_starting_world()
+
+    def _init_starting_world(self):
+        """
+        创建游戏的起始世界设定。
+        包含初始地点、NPC、任务和物品，为故事提供起点。
+        """
+        # --- 初始地点 ---
+        self.world.locations = {
+            "村庄广场": LocationInfo(
+                name="村庄广场",
+                location_type="town",
+                description="一个宁静的小村庄中心广场，阳光温暖地照耀着鹅卵石路面。周围有几家商铺和一口古老的水井。",
+                connected_to=["村庄铁匠铺", "村庄旅店", "村口小路", "村庄杂货铺"],
+                npcs_present=["村长老伯"],
+                danger_level=0,
+                is_discovered=True,
+                rest_available=False,
+                ambient_description="阳光斑驳地洒在广场上，远处传来铁匠铺叮叮当当的锤声。",
+            ),
+            "村庄铁匠铺": LocationInfo(
+                name="村庄铁匠铺",
+                location_type="shop",
+                description="一间热气腾腾的铁匠铺，炉火正旺。墙上挂满了各式武器和护甲。",
+                connected_to=["村庄广场"],
+                npcs_present=["铁匠格林"],
+                danger_level=0,
+                is_discovered=True,
+                shop_available=True,
+                ambient_description="炉火映红了铁匠粗犷的脸庞，空气中弥漫着金属和碳的气味。",
+            ),
+            "村庄旅店": LocationInfo(
+                name="村庄旅店",
+                location_type="shop",
+                description="一家温馨的小旅店，空气中弥漫着烤肉和麦酒的香气。壁炉里的火焰跳动着。",
+                connected_to=["村庄广场"],
+                npcs_present=["旅店老板娘莉娜"],
+                danger_level=0,
+                is_discovered=True,
+                rest_available=True,
+                shop_available=True,
+                ambient_description="壁炉噼啪作响，几位旅客正低声交谈，空气温暖而舒适。",
+            ),
+            "村庄杂货铺": LocationInfo(
+                name="村庄杂货铺",
+                location_type="shop",
+                description="一家琳琅满目的杂货铺，从草药到绳索应有尽有。老板是个精明的商人。",
+                connected_to=["村庄广场"],
+                npcs_present=["杂货商人阿尔"],
+                danger_level=0,
+                is_discovered=True,
+                shop_available=True,
+                ambient_description="货架上摆满了稀奇古怪的商品，柜台后的商人正用算盘噼里啪啦地算账。",
+            ),
+            "村口小路": LocationInfo(
+                name="村口小路",
+                location_type="wilderness",
+                description="通往村外的一条泥泞小路，两旁长满了野草。远处隐约可见黑暗森林的轮廓。",
+                connected_to=["村庄广场", "黑暗森林入口"],
+                danger_level=2,
+                is_discovered=True,
+                ambient_description="微风拂过野草，远处的森林在薄雾中若隐若现，传来不知名鸟兽的叫声。",
+            ),
+            "黑暗森林入口": LocationInfo(
+                name="黑暗森林入口",
+                location_type="wilderness",
+                description="森林的入口处，参天大树遮蔽了阳光，地面覆盖着厚厚的落叶。一股不祥的气息扑面而来。",
+                connected_to=["村口小路", "森林深处", "溪边营地"],
+                enemies=["哥布林", "野狼"],
+                danger_level=4,
+                is_discovered=False,
+                ambient_description="树冠密集得几乎遮蔽了所有阳光，偶尔传来树枝折断的声音，不知道是风还是别的什么。",
+            ),
+            "森林深处": LocationInfo(
+                name="森林深处",
+                location_type="dungeon",
+                description="森林的最深处，古树盘根错节。空气中弥漫着腐朽和魔力的气息，据说这里住着森林的主人。",
+                connected_to=["黑暗森林入口"],
+                enemies=["哥布林巫师", "巨型蜘蛛", "森林巨魔"],
+                danger_level=7,
+                is_discovered=False,
+                is_accessible=False,
+                required_item="森林之钥",
+                ambient_description="黑暗几乎吞噬了一切，只有奇异的荧光苔藓发出微弱的光。远处传来低沉的咆哮。",
+            ),
+            "溪边营地": LocationInfo(
+                name="溪边营地",
+                location_type="wilderness",
+                description="森林中一处难得的开阔地带，一条清澈的小溪从旁流过。适合扎营休息。",
+                connected_to=["黑暗森林入口"],
+                danger_level=2,
+                is_discovered=False,
+                rest_available=True,
+                ambient_description="溪水潺潺流淌，偶有鸟鸣声在林间回荡，这里是森林中的一片安宁绿洲。",
+            ),
+        }
+
+        self.world.discovered_locations = ["村庄广场", "村庄铁匠铺", "村庄旅店", "村庄杂货铺", "村口小路"]
+
+        # --- 初始 NPC ---
+        self.world.npcs = {
+            "村长老伯": NPCState(
+                name="村长老伯",
+                npc_type="quest_giver",
+                location="村庄广场",
+                attitude="friendly",
+                description="一位白发苍苍但精神矍铄的老人，是这个村庄的领导者。他的眼中带着忧虑。",
+                race="人类",
+                occupation="村长",
+                relationship_level=20,
+                can_give_quest=True,
+                available_quests=["main_quest_01"],
+                memory=[],
+                schedule={"清晨": "村庄广场", "正午": "村庄广场", "夜晚": "村庄旅店"},
+                backstory="在这个村庄生活了七十年的老者，见证过上一次暗潮来袭，深知森林中潜伏的危险。",
+            ),
+            "铁匠格林": NPCState(
+                name="铁匠格林",
+                npc_type="merchant",
+                location="村庄铁匠铺",
+                attitude="neutral",
+                description="一个肌肉发达的中年矮人，手臂上布满烧伤痕迹。沉默寡言但手艺精湛。",
+                race="矮人",
+                occupation="铁匠",
+                can_trade=True,
+                shop_inventory=["铁剑", "皮甲", "木盾"],
+                relationship_level=0,
+                schedule={"清晨": "村庄铁匠铺", "正午": "村庄铁匠铺", "夜晚": "村庄旅店"},
+                backstory="曾经是王都的御用铁匠，因一场变故隐居此地。对远方的怪物有独到的了解。",
+            ),
+            "旅店老板娘莉娜": NPCState(
+                name="旅店老板娘莉娜",
+                npc_type="merchant",
+                location="村庄旅店",
+                attitude="friendly",
+                description="一位热情开朗的红发女子，笑容温暖。她的旅店是村里情报的集散地。",
+                race="人类",
+                occupation="旅店老板",
+                can_trade=True,
+                shop_inventory=["面包", "烤肉", "麦酒", "草药包"],
+                relationship_level=10,
+                schedule={"清晨": "村庄旅店", "正午": "村庄旅店", "夜晚": "村庄旅店"},
+                backstory="年轻时曾是一名冒险者，后来受伤退役经营旅店。对旅行者总是格外关照。",
+            ),
+            "杂货商人阿尔": NPCState(
+                name="杂货商人阿尔",
+                npc_type="merchant",
+                location="村庄杂货铺",
+                attitude="neutral",
+                description="一个精明的瘦长男子，鹰钩鼻上架着一副圆框眼镜。善于讨价还价。",
+                race="人类",
+                occupation="商人",
+                can_trade=True,
+                shop_inventory=["火把", "绳索", "解毒药水", "小型治疗药水", "地图碎片"],
+                relationship_level=-5,
+                schedule={"清晨": "村庄杂货铺", "正午": "村庄广场", "夜晚": "村庄杂货铺"},
+                backstory="来自远方的行商，在村中定居多年。对各地的传闻消息灵通，但消息总是要收费的。",
+            ),
+            "神秘旅人": NPCState(
+                name="神秘旅人",
+                npc_type="quest_giver",
+                location="村庄旅店",
+                attitude="cautious",
+                description="一个身披灰色斗篷的旅人，面容隐藏在兜帽之下，只露出锐利的双眼。",
+                race="未知",
+                occupation="旅人",
+                relationship_level=-10,
+                can_give_quest=True,
+                available_quests=["side_quest_01"],
+                memory=[],
+                schedule={"清晨": "村庄旅店", "夜晚": "村口小路"},
+                backstory="似乎在寻找什么。偶尔从斗篷下露出的手指上有奇异的魔法纹路。",
+            ),
+        }
+
+        # --- 初始任务 ---
+        self.world.quests = {
+            "main_quest_01": QuestState(
+                quest_id="main_quest_01",
+                title="森林中的阴影",
+                description="村长老伯告诉你，最近森林中频繁出现怪物袭击事件。他请求你前往调查。",
+                quest_type="main",
+                status="active",
+                giver_npc="村长老伯",
+                objectives={
+                    "与村长对话了解情况": False,
+                    "前往黑暗森林入口调查": False,
+                    "击败森林中的怪物": False,
+                    "调查怪物活动的原因": False,
+                },
+                rewards=QuestRewards(
+                    gold=100,
+                    experience=50,
+                    items=["森林之钥"],
+                    reputation_changes={"村庄": 20},
+                    karma_change=5,
+                ),
+            ),
+            "side_quest_01": QuestState(
+                quest_id="side_quest_01",
+                title="失落的传承",
+                description="神秘旅人似乎在寻找一件古老的遗物。也许帮助他能得到意想不到的回报。",
+                quest_type="side",
+                status="active",
+                giver_npc="神秘旅人",
+                objectives={
+                    "与神秘旅人交谈": False,
+                    "找到古老遗物的线索": False,
+                },
+                rewards=QuestRewards(
+                    experience=30,
+                    items=["神秘卷轴"],
+                    unlock_skill="暗影感知",
+                ),
+                prerequisites=[],
+            ),
+        }
+
+        # --- 初始物品注册表 ---
+        self.world.item_registry = {
+            "铁剑": ItemInfo(name="铁剑", item_type="weapon", description="一把标准的铁制长剑，刀锋锐利。", rarity="common", stat_bonus={"attack": 5}, value=30),
+            "皮甲": ItemInfo(name="皮甲", item_type="armor", description="硬化皮革制成的轻甲，兼顾防护与灵活性。", rarity="common", stat_bonus={"defense": 3}, value=25),
+            "木盾": ItemInfo(name="木盾", item_type="armor", description="坚硬橡木制成的盾牌，可以抵挡基础攻击。", rarity="common", stat_bonus={"defense": 2}, value=15),
+            "面包": ItemInfo(name="面包", item_type="consumable", description="新鲜烤制的面包，香气扑鼻。", usable=True, use_effect="恢复 10 饱食度", value=5),
+            "烤肉": ItemInfo(name="烤肉", item_type="consumable", description="多汁的烤肉，令人食指大动。", usable=True, use_effect="恢复 25 饱食度", value=10),
+            "麦酒": ItemInfo(name="麦酒", item_type="consumable", description="村庄特产的麦酒，味道醇厚。", usable=True, use_effect="恢复 10 士气，降低 5 理智", value=8),
+            "草药包": ItemInfo(name="草药包", item_type="consumable", description="采集的新鲜草药，可以制作简单药剂。", usable=True, use_effect="恢复 20 HP", value=15),
+            "火把": ItemInfo(name="火把", item_type="misc", description="浸过油脂的火把，可在黑暗中照明。", usable=True, use_effect="照亮周围区域", value=3),
+            "绳索": ItemInfo(name="绳索", item_type="misc", description="结实的麻绳，在探险中很实用。", value=5),
+            "解毒药水": ItemInfo(name="解毒药水", item_type="consumable", description="散发着清苦气味的药水，可以解除中毒状态。", usable=True, use_effect="解除中毒状态", value=20),
+            "小型治疗药水": ItemInfo(name="小型治疗药水", item_type="consumable", description="泛着淡红色光芒的药水。", usable=True, use_effect="恢复 30 HP", value=25),
+            "地图碎片": ItemInfo(name="地图碎片", item_type="quest_item", description="一片残破的地图，标记着森林深处的某个位置。", quest_related=True, value=0, lore_text="这张地图似乎非常古老，纸张已经泛黄，但上面的墨迹依然清晰。"),
+            "森林之钥": ItemInfo(name="森林之钥", item_type="key", description="一把散发着微弱绿光的古老钥匙，似乎能打开森林深处的某个入口。", rarity="rare", quest_related=True, value=0, lore_text="钥匙上刻着精灵文字，翻译过来是：'唯有勇者可通行'。"),
+            "神秘卷轴": ItemInfo(name="神秘卷轴", item_type="quest_item", description="记载着古老知识的卷轴，散发着微弱的魔力波动。", rarity="rare", quest_related=True, value=0),
+        }
+
+        # --- 初始传闻 ---
+        self.world.rumors = [
+            "最近森林里的哥布林越来越嚣张了，好几个猎人都不敢进去了。",
+            "听说铁匠格林以前在王都待过，不知道为什么来了这个小村子。",
+            "旅店里来了个奇怪的旅人，整天把自己裹得严严实实的。",
+        ]
+
+        # --- 玩家初始装备 ---
+        self.player.inventory = ["面包", "面包", "小型治疗药水"]
+
+    # ============================================================
+    # 核心方法
+    # ============================================================
+
+    def apply_changes(self, changes: dict) -> list[str]:
+        """
+        接收 Qwen 返回的状态变更 JSON，校验并应用到当前状态。
+
+        设计思路：
+        - LLM 返回的变更是增量式的（如 hp_change: -10），而非绝对值
+        - 逐字段解析和应用，确保每个变更都经过校验
+        - 返回变更日志列表，方便 UI 展示
+
+        Args:
+            changes: Qwen 输出中解析出的状态变更字典
+
+        Returns:
+            变更描述列表 ["HP: 100 → 90", "位置: 村庄 → 森林"]
+        """
+        change_log: list[str] = []
+
+        # --- 过滤 None 值：LLM 可能将 null 字段返回为 None，全部跳过 ---
+        _filtered = {}
+        for k, v in changes.items():
+            if v is None:
+                continue
+            # 字符串 "None" / "null" 也视为空
+            if isinstance(v, str) and v.strip().lower() in ("none", "null", ""):
+                continue
+            # 数值 0 的 change 字段无意义，也跳过
+            if isinstance(v, (int, float)) and v == 0 and k.endswith("_change"):
+                continue
+            # 空列表 / 空字典跳过
+            if isinstance(v, (list, dict)) and len(v) == 0:
+                continue
+            _filtered[k] = v
+        changes = _filtered
+
+        # --- 玩家属性变更 ---
+        if "hp_change" in changes:
+            old_hp = self.player.hp
+            self.player.hp = clamp(
+                self.player.hp + int(changes["hp_change"]),
+                0,
+                self.player.max_hp,
+            )
+            change_log.append(f"HP: {old_hp} → {self.player.hp}")
+
+        if "mp_change" in changes:
+            old_mp = self.player.mp
+            self.player.mp = clamp(
+                self.player.mp + int(changes["mp_change"]),
+                0,
+                self.player.max_mp,
+            )
+            change_log.append(f"MP: {old_mp} → {self.player.mp}")
+
+        if "gold_change" in changes:
+            old_gold = self.player.gold
+            self.player.gold = max(0, self.player.gold + int(changes["gold_change"]))
+            change_log.append(f"金币: {old_gold} → {self.player.gold}")
+
+        if "exp_change" in changes:
+            old_exp = self.player.experience
+            self.player.experience += int(changes["exp_change"])
+            change_log.append(f"经验: {old_exp} → {self.player.experience}")
+            # 检查是否升级
+            while self.player.experience >= self.player.exp_to_next_level:
+                self._level_up()
+                change_log.append(f"升级！当前等级: {self.player.level}")
+
+        if "morale_change" in changes:
+            old_morale = self.player.morale
+            self.player.morale = clamp(
+                self.player.morale + int(changes["morale_change"]),
+                0, 100,
+            )
+            change_log.append(f"士气: {old_morale} → {self.player.morale}")
+
+        if "sanity_change" in changes:
+            old_sanity = self.player.sanity
+            self.player.sanity = clamp(
+                self.player.sanity + int(changes["sanity_change"]),
+                0, 100,
+            )
+            change_log.append(f"理智: {old_sanity} → {self.player.sanity}")
+
+        if "hunger_change" in changes:
+            old_hunger = self.player.hunger
+            self.player.hunger = clamp(
+                self.player.hunger + int(changes["hunger_change"]),
+                0, 100,
+            )
+            change_log.append(f"饱食度: {old_hunger} → {self.player.hunger}")
+
+        if "karma_change" in changes:
+            old_karma = self.player.karma
+            self.player.karma += int(changes["karma_change"])
+            change_log.append(f"善恶值: {old_karma} → {self.player.karma}")
+
+        # --- 位置变更 ---
+        if "new_location" in changes:
+            old_loc = self.player.location
+            new_loc = str(changes["new_location"])
+            self.player.location = new_loc
+            self.world.current_scene = new_loc
+            change_log.append(f"位置: {old_loc} → {new_loc}")
+            # 发现新地点
+            if new_loc not in self.world.discovered_locations:
+                self.world.discovered_locations.append(new_loc)
+                change_log.append(f"发现新地点: {new_loc}")
+                if new_loc in self.world.locations:
+                    self.world.locations[new_loc].is_discovered = True
+
+        # --- 物品变更 ---
+        if "items_gained" in changes:
+            for item in changes["items_gained"]:
+                self.player.inventory.append(str(item))
+                change_log.append(f"获得物品: {item}")
+
+        if "items_lost" in changes:
+            for item in changes["items_lost"]:
+                item_str = str(item)
+                if item_str in self.player.inventory:
+                    self.player.inventory.remove(item_str)
+                    change_log.append(f"失去物品: {item}")
+
+        # --- 技能变更 ---
+        if "skills_gained" in changes:
+            for skill in changes["skills_gained"]:
+                skill_str = str(skill)
+                if skill_str not in self.player.skills:
+                    self.player.skills.append(skill_str)
+                    change_log.append(f"习得技能: {skill}")
+
+        # --- 状态效果 ---
+        if "status_effects_added" in changes:
+            for effect_data in changes["status_effects_added"]:
+                if isinstance(effect_data, dict):
+                    effect = StatusEffect(**effect_data)
+                    self.player.status_effects.append(effect)
+                    # 构建详细的状态效果日志
+                    parts = [f"获得状态: {effect.name}"]
+                    if effect.description:
+                        parts.append(f"（{effect.description}）")
+                    if effect.stat_modifiers:
+                        mod_strs = []
+                        _STAT_CN = {
+                            "hp": "生命", "mp": "魔力",
+                            "attack": "攻击力", "defense": "防御力",
+                            "speed": "速度", "luck": "幸运",
+                            "perception": "感知", "sanity": "理智",
+                            "hunger": "饱食度", "morale": "士气",
+                            "gold": "金币", "karma": "善恶值",
+                            "experience": "经验",
+                        }
+                        for stat, val in effect.stat_modifiers.items():
+                            cn = _STAT_CN.get(stat, stat)
+                            sign = "+" if val > 0 else ""
+                            mod_strs.append(f"{cn}{sign}{val}/回合")
+                        parts.append(f"[{', '.join(mod_strs)}]")
+                    if effect.duration > 0:
+                        parts.append(f"持续{effect.duration}回合")
+                    elif effect.duration == -1:
+                        parts.append("永久")
+                    change_log.append(" ".join(parts))
+                elif isinstance(effect_data, str):
+                    effect = StatusEffect(name=effect_data)
+                    self.player.status_effects.append(effect)
+                    change_log.append(f"获得状态: {effect_data}")
+
+        if "status_effects_removed" in changes:
+            for name in changes["status_effects_removed"]:
+                self.player.status_effects = [
+                    e for e in self.player.status_effects if e.name != str(name)
+                ]
+                change_log.append(f"移除状态: {name}")
+
+        # --- NPC 相关变更 ---
+        if "npc_changes" in changes:
+            for npc_name, npc_data in changes["npc_changes"].items():
+                if npc_name in self.world.npcs:
+                    npc = self.world.npcs[npc_name]
+                    if "attitude" in npc_data:
+                        npc.attitude = str(npc_data["attitude"])
+                        change_log.append(f"NPC {npc_name} 态度变为: {npc.attitude}")
+                    if "is_alive" in npc_data:
+                        npc.is_alive = bool(npc_data["is_alive"])
+                        if not npc.is_alive:
+                            change_log.append(f"NPC {npc_name} 已死亡")
+                    if "relationship_change" in npc_data:
+                        old_rel = npc.relationship_level
+                        npc.relationship_level = clamp(
+                            npc.relationship_level + int(npc_data["relationship_change"]),
+                            -100, 100,
+                        )
+                        change_log.append(
+                            f"NPC {npc_name} 好感度: {old_rel} → {npc.relationship_level}"
+                        )
+                    if "hp_change" in npc_data:
+                        npc.hp = max(0, npc.hp + int(npc_data["hp_change"]))
+                        if npc.hp <= 0:
+                            npc.is_alive = False
+                            change_log.append(f"NPC {npc_name} 被击败")
+                    if "memory_add" in npc_data:
+                        npc.memory.append(str(npc_data["memory_add"]))
+
+        # --- 任务变更 ---
+        if "quest_updates" in changes:
+            for quest_id, quest_data in changes["quest_updates"].items():
+                if quest_id in self.world.quests:
+                    quest = self.world.quests[quest_id]
+                    if "objectives_completed" in quest_data:
+                        for obj in quest_data["objectives_completed"]:
+                            if str(obj) in quest.objectives:
+                                quest.objectives[str(obj)] = True
+                                change_log.append(f"完成目标: {obj}")
+                    if "status" in quest_data:
+                        quest.status = str(quest_data["status"])
+                        _QUEST_STATUS_CN = {
+                            "active": "进行中", "in_progress": "进行中",
+                            "IN_PROGRESS": "进行中", "ACTIVE": "进行中",
+                            "completed": "已完成", "COMPLETED": "已完成",
+                            "failed": "已失败", "FAILED": "已失败",
+                            "expired": "已过期", "EXPIRED": "已过期",
+                        }
+                        status_cn = _QUEST_STATUS_CN.get(quest.status, quest.status)
+                        change_log.append(f"任务【{quest.title}】进展至\"{status_cn}\"")
+
+        # --- 世界状态变更 ---
+        if "weather_change" in changes:
+            self.world.weather = str(changes["weather_change"])
+            change_log.append(f"天气变为: {self.world.weather}")
+
+        if "time_change" in changes:
+            valid_times = ["清晨", "上午", "正午", "下午", "黄昏", "夜晚", "深夜"]
+            new_time = str(changes["time_change"])
+            if new_time in valid_times:
+                old_time = self.world.time_of_day
+                self.world.time_of_day = new_time
+                change_log.append(f"时间流逝: {old_time} → {self.world.time_of_day}")
+            else:
+                logger.warning(f"无效的 time_change 值 '{new_time}'，已忽略。合法值: {valid_times}")
+
+        if "global_flags_set" in changes:
+            for flag, value in changes["global_flags_set"].items():
+                self.world.global_flags[flag] = bool(value)
+                # 全局标记仅内部使用，不展示给用户
+                logger.info(f"全局标记设置: {flag} = {value}")
+
+        if "world_event" in changes:
+            self.world.world_events.append(str(changes["world_event"]))
+            change_log.append(f"世界事件: {changes['world_event']}")
+
+        # --- 装备变更 ---
+        if "equip" in changes:
+            for slot, item_name in changes["equip"].items():
+                if slot in self.player.equipment:
+                    old_item = self.player.equipment[slot]
+                    self.player.equipment[slot] = item_name
+                    change_log.append(f"装备 [{slot}]: {old_item} → {item_name}")
+
+        # --- 玩家称号变更 ---
+        if "title_change" in changes:
+            old_title = self.player.title
+            self.player.title = str(changes["title_change"])
+            change_log.append(f"称号: {old_title} → {self.player.title}")
+
+        if change_log:
+            logger.info(f"状态变更: {change_log}")
+
+        return change_log
+
+    def validate(self) -> tuple[bool, list[str]]:
+        """
+        校验当前状态的合法性。
+
+        设计思路：
+        - 检查所有数值是否在合法范围内
+        - HP <= 0 时标记游戏结束
+        - 理智过低时施加特殊效果
+        - 返回 (是否合法, 问题列表)
+
+        Returns:
+            (is_valid, issues): 合法性标志和问题描述列表
+        """
+        issues: list[str] = []
+
+        # HP 校验 —— 核心逻辑：HP <= 0 触发死亡
+        if self.player.hp <= 0:
+            self.player.hp = 0
+            self.game_mode = "game_over"
+            self.player.death_count += 1
+            issues.append("玩家生命值归零，触发死亡结局！")
+
+        # MP 范围校验
+        self.player.mp = clamp(self.player.mp, 0, self.player.max_mp)
+
+        # 饱食度惩罚
+        if self.player.hunger <= 0:
+            self.player.hunger = 0
+            issues.append("玩家极度饥饿，攻击力和防御力下降！")
+
+        # 理智值校验
+        if self.player.sanity <= 0:
+            self.player.sanity = 0
+            self.game_mode = "game_over"
+            issues.append("玩家理智归零，陷入疯狂！触发疯狂结局！")
+
+        # 士气校验
+        if self.player.morale <= 10:
+            issues.append("玩家士气极低，行动效率降低。")
+
+        # 金币不能为负
+        if self.player.gold < 0:
+            self.player.gold = 0
+            issues.append("金币不足。")
+
+        is_valid = self.game_mode != "game_over"
+        return is_valid, issues
+
+    def to_prompt(self) -> str:
+        """
+        将当前完整状态序列化为自然语言描述，注入 System Prompt。
+
+        设计思路（需求文档核心要求）：
+        - System Prompt 必须包含当前状态描述
+        - 描述要全面但简洁，避免 token 浪费
+        - 包括：场景、玩家状态、已发生的重要事件、NPC 信息
+        - 加入一致性约束指令，提醒 LLM 不要产生矛盾
+        """
+        # 1. 场景与环境
+        scene_desc = (
+            f"【当前场景】{self.world.current_scene}\n"
+            f"【时间】第{self.world.day_count}天 {self.world.time_of_day}\n"
+            f"【天气】{self.world.weather}\n"
+            f"【季节】{self.world.season}"
+        )
+
+        # 2. 玩家状态
+        effects_str = "、".join(e.name for e in self.player.status_effects) if self.player.status_effects else "无"
+        equipped = {k: (v or "无") for k, v in self.player.equipment.items()}
+        equip_str = "、".join(f"{k}={v}" for k, v in equipped.items())
+        # 背包物品标注消耗品/可重复使用
+        if self.player.inventory:
+            inv_items = []
+            for item_name in self.player.inventory:
+                if self.is_item_consumable(item_name):
+                    inv_items.append(f"{item_name}[消耗品]")
+                else:
+                    inv_items.append(f"{item_name}[可重复使用]")
+            inventory_str = "、".join(inv_items)
+        else:
+            inventory_str = "空"
+        skills_str = "、".join(self.player.skills) if self.player.skills else "无"
+
+        player_desc = (
+            f"【玩家】{self.player.name}（{self.player.title}）\n"
+            f"  等级: {self.player.level} | 经验: {self.player.experience}/{self.player.exp_to_next_level}\n"
+            f"  HP: {self.player.hp}/{self.player.max_hp} | MP: {self.player.mp}/{self.player.max_mp}\n"
+            f"  攻击: {self.player.attack} | 防御: {self.player.defense} | 速度: {self.player.speed} | 幸运: {self.player.luck} | 感知: {self.player.perception}\n"
+            f"  金币: {self.player.gold} | 善恶值: {self.player.karma}\n"
+            f"  士气: {self.player.morale} | 理智: {self.player.sanity} | 饱食度: {self.player.hunger}\n"
+            f"  装备: {equip_str}\n"
+            f"  背包: {inventory_str}\n"
+            f"  技能: {skills_str}\n"
+            f"  状态效果: {effects_str}\n"
+            f"  所在位置: {self.player.location}"
+        )
+
+        # 3. 当前场景中的 NPC
+        current_npcs = [
+            npc for npc in self.world.npcs.values()
+            if npc.location == self.player.location and npc.is_alive
+        ]
+        if current_npcs:
+            npc_lines = []
+            for npc in current_npcs:
+                mem = "；".join(npc.memory[-3:]) if npc.memory else "无记忆"
+                npc_lines.append(
+                    f"  - {npc.name}（{npc.occupation}, {npc.race}, 态度: {npc.attitude}, "
+                    f"好感度: {npc.relationship_level}, 记忆: {mem}）"
+                )
+            npc_desc = "【场景中的NPC】\n" + "\n".join(npc_lines)
+        else:
+            npc_desc = "【场景中的NPC】无"
+
+        # 4. 当前活跃任务
+        active_quests = [q for q in self.world.quests.values() if q.status == "active"]
+        if active_quests:
+            quest_lines = []
+            for q in active_quests:
+                objectives = "；".join(
+                    f"{'✅' if done else '❌'}{obj}" for obj, done in q.objectives.items()
+                )
+                time_info = f"（剩余 {q.turns_remaining} 回合）" if q.turns_remaining > 0 else ""
+                quest_lines.append(f"  - [{q.quest_type.upper()}] {q.title}: {objectives}{time_info}")
+            quest_desc = "【活跃任务】\n" + "\n".join(quest_lines)
+        else:
+            quest_desc = "【活跃任务】无"
+
+        # 5. 已发现地点的连接关系
+        loc_info = self.world.locations.get(self.player.location)
+        if loc_info:
+            accessible = [
+                name for name in loc_info.connected_to
+                if name in self.world.locations
+                and self.world.locations[name].is_accessible
+            ]
+            blocked = [
+                f"{name}（需要: {self.world.locations[name].required_item}）"
+                for name in loc_info.connected_to
+                if name in self.world.locations
+                and not self.world.locations[name].is_accessible
+            ]
+            move_desc = f"【可前往的地点】{'、'.join(accessible) if accessible else '无'}"
+            if blocked:
+                move_desc += f"\n【被阻挡的地点】{'、'.join(blocked)}"
+        else:
+            move_desc = "【可前往的地点】未知"
+
+        # 6. 近期事件（最近 5 条）
+        if self.event_log:
+            recent = self.event_log[-5:]
+            event_lines = [f"  - [回合{e.turn}] {e.description}" for e in recent]
+            event_desc = "【近期事件】\n" + "\n".join(event_lines)
+        else:
+            event_desc = "【近期事件】无"
+
+        # 7. 传闻
+        rumors_desc = ""
+        if self.world.rumors:
+            rumors_desc = "\n【流传的传闻】\n" + "\n".join(f"  - {r}" for r in self.world.rumors[-3:])
+
+        # 8. 一致性约束指令
+        consistency_rules = (
+            "\n【一致性约束 —— 你必须严格遵守】\n"
+            "1. 已死亡的NPC不可再出现或对话（除非有特殊复活剧情）。\n"
+            "2. 玩家背包中没有的物品不可使用或赠送。\n"
+            "3. 玩家不可到达未连接的地点，被阻挡的地点需要对应物品才能进入。\n"
+            "4. 时间线不可回退，已发生的事件不可矛盾。\n"
+            "5. NPC的态度和记忆应与历史事件一致。\n"
+            "6. 战斗伤害应考虑攻击力和防御力的差值，��果要合理。\n"
+            "7. 所有状态变更必须在 state_changes 字段中明确输出。\n"
+            "8. 每次生成的文本描写必须使用全新的比喻和意象，严禁重复之前回合用过的修辞和句式。\n"
+            "9. 【物品消耗规则】只有消耗品（药水、食物等一次性物品）在使用后才会消失，应放入 items_lost。"
+            "非消耗品（哨子、武器、工具、乐器、钥匙等可重复使用的物品）使用后仍然保留在背包中，"
+            "绝对不要将它们放入 items_lost。例如：吹响哨子后哨子仍在背包中；使用火把照明后火把仍在。\n"
+            "10. 【选项物品约束】生成的选项中如果涉及使用某个物品，该物品必须当前在玩家背包中。"
+            "不要生成使用玩家不拥有的物品的选项。"
+        )
+
+        # 组合完整 Prompt
+        full_prompt = "\n\n".join([
+            scene_desc,
+            player_desc,
+            npc_desc,
+            quest_desc,
+            move_desc,
+            event_desc,
+            rumors_desc,
+            consistency_rules,
+        ])
+
+        return full_prompt
+
+    def log_event(
+        self,
+        event_type: str,
+        description: str,
+        player_action: str = "",
+        involved_npcs: list[str] | None = None,
+        state_changes: dict | None = None,
+        consequence_tags: list[str] | None = None,
+        is_reversible: bool = True,
+    ):
+        """
+        记录一条事件到 event_log。
+
+        每次状态变更都应该调用此方法，确保完整的历史记录。
+        事件日志是一致性维护的基石。
+        """
+        event = GameEvent(
+            turn=self.turn,
+            day=self.world.day_count,
+            time_of_day=self.world.time_of_day,
+            event_type=event_type,
+            description=description,
+            location=self.player.location,
+            involved_npcs=involved_npcs or [],
+            state_changes=state_changes or {},
+            player_action=player_action,
+            consequence_tags=consequence_tags or [],
+            is_reversible=is_reversible,
+        )
+        self.event_log.append(event)
+        logger.info(f"事件记录: [{event_type}] {description}")
+
+    def check_consistency(self, proposed_changes: dict) -> list[str]:
+        """
+        对比事件日志和当前状态，检测拟议变更中的矛盾。
+
+        设计思路：
+        - 在 apply_changes 之前调用，预防性检测
+        - 返回所有发现的矛盾描述列表
+        - 空列表 = 无矛盾，可以安全应用
+
+        检测维度：
+        1. 已死亡 NPC 是否被重新引用
+        2. 不存在的物品是否被消耗
+        3. 不可达的地点是否被移动到
+        4. 任务目标是否已经跳跃完成
+        """
+        contradictions: list[str] = []
+
+        # 检测1: 已死亡NPC是否被引用
+        if "npc_changes" in proposed_changes:
+            for npc_name in proposed_changes["npc_changes"]:
+                if npc_name in self.world.npcs and not self.world.npcs[npc_name].is_alive:
+                    contradictions.append(
+                        f"矛盾: 试图与已死亡的NPC '{npc_name}' 交互"
+                    )
+
+        # 检测2: 不存在的物品是否被消耗
+        if "items_lost" in proposed_changes:
+            for item in proposed_changes["items_lost"]:
+                if str(item) not in self.player.inventory:
+                    contradictions.append(
+                        f"矛盾: 试图消耗不在背包中的物品 '{item}'"
+                    )
+                elif not self.is_item_consumable(str(item)):
+                    # 非消耗品不应因使用而消失（交易/丢弃除外，由引擎层判断）
+                    contradictions.append(
+                        f"矛盾: 物品 '{item}' 不是消耗品，使用后不应消失。请将其从 items_lost 中移除。"
+                    )
+
+        # 检测3: 位置移动是否合法
+        if "new_location" in proposed_changes:
+            target = str(proposed_changes["new_location"])
+            current_loc = self.world.locations.get(self.player.location)
+            if current_loc and target not in current_loc.connected_to:
+                contradictions.append(
+                    f"矛盾: 试图移动到不相邻的地点 '{target}'（当前位置: {self.player.location}）"
+                )
+            target_loc = self.world.locations.get(target)
+            if target_loc and not target_loc.is_accessible:
+                if target_loc.required_item and target_loc.required_item not in self.player.inventory:
+                    contradictions.append(
+                        f"矛盾: 地点 '{target}' 被锁定，需要 '{target_loc.required_item}'"
+                    )
+
+        # 检测4: 金币��否足够（如果是消费操作）
+        if "gold_change" in proposed_changes:
+            change = int(proposed_changes["gold_change"])
+            if change < 0 and self.player.gold + change < 0:
+                contradictions.append(
+                    f"矛盾: 金币不足（当前: {self.player.gold}，需要: {abs(change)}）"
+                )
+
+        if contradictions:
+            logger.warning(f"一致性检查发现矛盾: {contradictions}")
+
+        return contradictions
+
+    def is_game_over(self) -> bool:
+        """
+        判断游戏是否结束。
+
+        结束条件：
+        1. HP <= 0（死亡）
+        2. 理智 <= 0（疯狂）
+        3. 触发终局标记
+        """
+        if self.player.hp <= 0:
+            return True
+        if self.player.sanity <= 0:
+            return True
+        if self.game_mode == "game_over":
+            return True
+        # 检查终局标记
+        if self.ending_flags.get("game_complete", False):
+            return True
+        return False
+
+    def tick_time(self) -> list[str]:
+        """
+        推进游戏时间（每回合调用）。
+
+        设计思路：
+        - 回合数递增
+        - 时间段按固定顺序轮转
+        - 每过一个完整日夜循环，天数+1
+        - 自动减少饱食度，模拟饥饿机制
+        - 结算状态效果持续时间
+        - 检查限时任务
+
+        Returns:
+            tick_log: 本回合时间流逝引起的状态变化描述列表
+        """
+        tick_log: list[str] = []
+        self.turn += 1
+
+        # 时间推进
+        time_sequence = ["清晨", "上午", "正午", "下午", "黄昏", "夜晚", "深夜"]
+        current_idx = time_sequence.index(self.world.time_of_day) if self.world.time_of_day in time_sequence else 0
+        next_idx = (current_idx + 1) % len(time_sequence)
+        old_time = self.world.time_of_day
+        self.world.time_of_day = time_sequence[next_idx]
+        tick_log.append(f"时间流逝: {old_time} → {self.world.time_of_day}")
+
+        # 新的一天
+        if next_idx == 0:
+            self.world.day_count += 1
+            tick_log.append(f"新的一天！第 {self.world.day_count} 天")
+            logger.info(f"新的一天开始了！第 {self.world.day_count} 天")
+
+        # 饱食度衰减（每回合 -3）
+        old_hunger = self.player.hunger
+        self.player.hunger = max(0, self.player.hunger - 3)
+        if old_hunger != self.player.hunger:
+            tick_log.append(f"饱食度自然衰减: {old_hunger} → {self.player.hunger}")
+        if self.player.hunger <= 0:
+            tick_log.append("极度饥饿！属性受到惩罚")
+            logger.info("玩家非常饥饿，属性受到惩罚")
+
+        # 结算状态效果
+        effect_log = self._apply_status_effects()
+        tick_log.extend(effect_log)
+
+        # 检查限时任务
+        self._check_quest_deadlines()
+
+        # 更新 NPC 位置（根据时间表）
+        self._update_npc_schedules()
+
+        return tick_log
+
+    def _apply_status_effects(self) -> list[str]:
+        """每回合结算状态效果：应用修正、递减持续时间、移除过期效果
+
+        Returns:
+            effect_log: 状态效果结算引起的变化描述列表
+        """
+        effect_log: list[str] = []
+        expired = []
+        for effect in self.player.status_effects:
+            # 应用属性修正（每回合）
+            if "hp" in effect.stat_modifiers:
+                old_hp = self.player.hp
+                self.player.hp = clamp(
+                    self.player.hp + effect.stat_modifiers["hp"],
+                    0, self.player.max_hp,
+                )
+                if old_hp != self.player.hp:
+                    effect_log.append(f"{effect.name}: HP {old_hp} → {self.player.hp}")
+            if "mp" in effect.stat_modifiers:
+                old_mp = self.player.mp
+                self.player.mp = clamp(
+                    self.player.mp + effect.stat_modifiers["mp"],
+                    0, self.player.max_mp,
+                )
+                if old_mp != self.player.mp:
+                    effect_log.append(f"{effect.name}: MP {old_mp} → {self.player.mp}")
+            if "sanity" in effect.stat_modifiers:
+                old_sanity = self.player.sanity
+                self.player.sanity = clamp(
+                    self.player.sanity + effect.stat_modifiers["sanity"],
+                    0, 100,
+                )
+                if old_sanity != self.player.sanity:
+                    effect_log.append(f"{effect.name}: 理智 {old_sanity} → {self.player.sanity}")
+            # 感知、攻击、防御、速度、幸运、士气、饱食度等直接加减属性
+            for stat_key, stat_cn in [("perception", "感知"), ("attack", "攻击力"),
+                                      ("defense", "防御力"), ("speed", "速度"),
+                                      ("luck", "幸运"), ("morale", "士气"),
+                                      ("hunger", "饱食度")]:
+                if stat_key in effect.stat_modifiers:
+                    old_val = getattr(self.player, stat_key)
+                    max_val = 100 if stat_key in ("morale", "hunger") else None
+                    new_val = old_val + effect.stat_modifiers[stat_key]
+                    if max_val is not None:
+                        new_val = clamp(new_val, 0, max_val)
+                    setattr(self.player, stat_key, new_val)
+                    if old_val != new_val:
+                        effect_log.append(f"{effect.name}: {stat_cn} {old_val} → {new_val}")
+
+            # 递减持续时间
+            if effect.duration > 0:
+                effect.duration -= 1
+                if effect.duration <= 0:
+                    expired.append(effect)
+            # duration == -1 表示永久效果，不递减
+
+        # 移除过期效果
+        for effect in expired:
+            self.player.status_effects.remove(effect)
+            effect_log.append(f"状态效果 '{effect.name}' 已过期并移除")
+            logger.info(f"状态效果 '{effect.name}' 已过期")
+
+        return effect_log
+
+    def _check_quest_deadlines(self):
+        """检查限时任务是否过期"""
+        for quest in self.world.quests.values():
+            if quest.status == "active" and quest.turns_remaining > 0:
+                quest.turns_remaining -= 1
+                if quest.turns_remaining <= 0:
+                    quest.status = "failed"
+                    logger.info(f"任务 '{quest.title}' 已超时失败！")
+
+    def _update_npc_schedules(self):
+        """根据当前时间段更新 NPC 位置"""
+        for npc in self.world.npcs.values():
+            if not npc.is_alive:
+                continue
+            if self.world.time_of_day in npc.schedule:
+                old_loc = npc.location
+                new_loc = npc.schedule[self.world.time_of_day]
+                if old_loc != new_loc:
+                    npc.location = new_loc
+                    # 更新地点的 NPC 列表
+                    if old_loc in self.world.locations:
+                        loc = self.world.locations[old_loc]
+                        if npc.name in loc.npcs_present:
+                            loc.npcs_present.remove(npc.name)
+                    if new_loc in self.world.locations:
+                        loc = self.world.locations[new_loc]
+                        if npc.name not in loc.npcs_present:
+                            loc.npcs_present.append(npc.name)
+
+    def _level_up(self):
+        """
+        角色升级逻辑。
+
+        每次升级：
+        - 等级+1
+        - 扣除当前升级所需经验
+        - 下次升级所需经验提升 50%
+        - 属性随机增长
+        - HP/MP 完全恢复
+        """
+        self.player.experience -= self.player.exp_to_next_level
+        self.player.level += 1
+        self.player.exp_to_next_level = int(self.player.exp_to_next_level * 1.5)
+
+        # 属性提升
+        self.player.max_hp += 10
+        self.player.max_mp += 5
+        self.player.attack += 2
+        self.player.defense += 1
+        self.player.speed += 1
+        self.player.perception += 1
+
+        # 升级后满血满蓝
+        self.player.hp = self.player.max_hp
+        self.player.mp = self.player.max_mp
+
+        logger.info(
+            f"升级！等级: {self.player.level}, "
+            f"HP: {self.player.max_hp}, MP: {self.player.max_mp}, "
+            f"ATK: {self.player.attack}, DEF: {self.player.defense}"
+        )
+
+    def get_death_narrative_context(self) -> str:
+        """生成死亡结局的上下文信息（供 story_engine 使用）"""
+        cause = "生命值归零" if self.player.hp <= 0 else "理智崩溃"
+        last_event = self.event_log[-1].description if self.event_log else "未知"
+        return (
+            f"玩家 {self.player.name} 因{cause}而倒下。\n"
+            f"最后发生的事件: {last_event}\n"
+            f"死亡次数: {self.player.death_count}\n"
+            f"存活天数: {self.world.day_count}\n"
+            f"最终善恶值: {self.player.karma}"
+        )
+
+    def is_item_consumable(self, item_name: str) -> bool:
+        """
+        判断物品是否为消耗品（使用后会消失）。
+
+        规则：
+        - item_registry 中 item_type == "consumable" 的物品是消耗品
+        - item_type == "material" 的物品也视为消耗品（合成材料，用完即消失）
+        - 其他类型（weapon, armor, key, quest_item, misc 等）为可重复使用物品
+        - 未注册物品默认为非消耗品（更安全，避免误删）
+        """
+        if item_name in self.world.item_registry:
+            item_info = self.world.item_registry[item_name]
+            return item_info.item_type in ("consumable", "material")
+        # 对未注册物品，用关键词启发式判断
+        consumable_keywords = ["药水", "药剂", "食物", "面包", "烤肉", "麦酒",
+                               "草药", "卷轴", "炸弹", "手雷", "箭矢", "弹药",
+                               "丹药", "果实", "干粮", "肉干", "饮料", "汤",
+                               "符咒", "一次性"]
+        for keyword in consumable_keywords:
+            if keyword in item_name:
+                return True
+        return False  # 默认为非消耗品
+
+    def get_available_actions(self) -> list[str]:
+        """根据当前场景和状态返回可用的行动类型"""
+        actions = ["观察", "对话", "移动"]
+
+        # 当前场景信息
+        loc = self.world.locations.get(self.player.location)
+        if loc:
+            if loc.rest_available:
+                actions.append("休息")
+            if loc.shop_available:
+                actions.append("交易")
+            if loc.enemies:
+                actions.append("战斗")
+            if loc.available_items:
+                actions.append("搜索")
+
+        # 背包中有可用物品
+        if self.player.inventory:
+            actions.append("使用物品")
+
+        # 有技能可用
+        if self.player.skills:
+            actions.append("使用技能")
+
+        return actions
+
+    def get_scene_summary(self) -> str:
+        """获取当前场景的简短摘要（用于 UI 展示）"""
+        loc = self.world.locations.get(self.player.location)
+        desc = loc.description if loc else "未知区域"
+        ambient = loc.ambient_description if loc else ""
+
+        npcs = [
+            npc.name for npc in self.world.npcs.values()
+            if npc.location == self.player.location and npc.is_alive
+        ]
+        npc_str = f"可见NPC: {'、'.join(npcs)}" if npcs else ""
+
+        return f"{desc}\n{ambient}\n{npc_str}".strip()

story_engine.py

@@ -0,0 +1,852 @@
+"""
+story_engine.py - StoryWeaver 叙事引擎
+
+职责：
+1. 封装故事生成的核心逻辑（两阶段生成策略）
+2. 生成连贯、有文学色彩的剧情段落
+3. 生成 3 个后续选项供玩家选择
+4. 输出结构化的状态变更数据
+
+两阶段生成策略 (Chain of Thought)：
+- 第一阶段：让 Qwen 生成 JSON 格式的剧情大纲（事件、地点变化、NPC反应、状态变更）
+- 第二阶段：基于大纲生成具体的描写文本 + 3 个选项
+
+目的：
+- 第一阶段便于程序解析状态变化，保证数据准确
+- 第二阶段保证文本质量和文学色彩
+"""
+
+import logging
+import re
+from typing import Optional
+
+from utils import call_qwen, safe_json_call, extract_json_from_text, DEFAULT_MODEL
+from state_manager import GameState
+
+logger = logging.getLogger("StoryWeaver")
+
+
+# ============================================================
+# 变更日志合并工具
+# ============================================================
+
+# 用于从 "饱食度自然衰减: 100 → 97" 或 "饱食度: 97 → 95" 中提取属性名和数值
+_CHANGE_LOG_PATTERN = re.compile(
+    r"^(.+?)(?:自然衰减)?:\s*(\S+)\s*→\s*(\S+)$"
+)
+
+
+def _merge_change_logs(tick_log: list[str], action_log: list[str]) -> list[str]:
+    """
+    合并时间流逝日志与行动变更日志，避免同一属性出现两行。
+
+    例如：
+      tick_log:   ["饱食度自然衰减: 100 → 97"]
+      action_log: ["饱食度: 97 → 95"]
+    合并为：      ["饱食度: 100 → 95"]
+
+    原理：按属性名匹配，如果 tick_log 中某属性的终值 == action_log 中同属性的起始值，
+    则合并为一条：属性名: tick起始值 → action终值。
+    """
+    # 从 tick_log 中提取 {属性名: (起始值, 终值, 原始索引)}
+    tick_attrs: dict[str, tuple[str, str, int]] = {}
+    for i, line in enumerate(tick_log):
+        m = _CHANGE_LOG_PATTERN.match(line.strip())
+        if m:
+            attr_name = m.group(1).strip()
+            tick_attrs[attr_name] = (m.group(2), m.group(3), i)
+
+    # 标记哪些 tick_log 条目被合并掉了
+    tick_merged: set[int] = set()
+    merged_results: list[str] = []
+
+    for line in action_log:
+        m = _CHANGE_LOG_PATTERN.match(line.strip())
+        if m:
+            attr_name = m.group(1).strip()
+            action_start = m.group(2)
+            action_end = m.group(3)
+            if attr_name in tick_attrs:
+                tick_start, tick_end, tick_idx = tick_attrs[attr_name]
+                if tick_end == action_start:
+                    # 可以合并：使用 tick 的起始值 + action 的终值
+                    if tick_start != action_end:
+                        merged_results.append(f"{attr_name}: {tick_start} → {action_end}")
+                    # 如果起始值==终值（变了又变回来），直接省略此条
+                    tick_merged.add(tick_idx)
+                    continue
+        merged_results.append(line)
+
+    # 输出：未被合并的 tick_log 条目 + 合并后的 action_log 条目
+    remaining_tick = [
+        line for i, line in enumerate(tick_log) if i not in tick_merged
+    ]
+    return remaining_tick + merged_results
+
+
+# ============================================================
+# Prompt 模板设计
+# ============================================================
+
+# ------------------------------------------------------------
+# 第一阶段 Prompt：生成剧情大纲（结构化 JSON）
+#
+# 设计思路：
+# - System Prompt 注入当前完整状态（来自 state_manager.to_prompt()）
+# - 要求 LLM 严格输出 JSON，包含：事件描述、状态变更、NPC 反应
+# - 低温度 (0.3) 确保 JSON 结构稳定
+# - 明确指定每个字段的含义和格式
+# ------------------------------------------------------------
+OUTLINE_SYSTEM_PROMPT_TEMPLATE = """你是一个专业的 RPG 叙事引擎的规划模块。你的任务是根据玩家的行动和当前世界状态，生成剧情大纲。
+
+{world_state}
+
+【你的任务】
+根据玩家的行动意图，生成一个 JSON 格式的剧情大纲。你必须：
+1. 考虑当前所有状态（HP、位置、NPC态度、背包物品等）
+2. 确保剧情发展合理，不违反一致性约束
+3. 生成合理的状态变更数据
+4. 考虑剧情的趣味性和戏剧张力
+
+请严格按以下 JSON 格式输出（不要输出任何其他文字）：
+{{
+    "event_summary": "简短描述发生了什么事（一句话）",
+    "event_type": "事件类型（COMBAT/DIALOGUE/MOVE/ITEM/QUEST/TRADE/REST/DISCOVERY）",
+    "involved_npcs": ["涉及的NPC名称列表"],
+    "state_changes": {{
+        "hp_change": 0,
+        "mp_change": 0,
+        "gold_change": 0,
+        "exp_change": 0,
+        "morale_change": 0,
+        "sanity_change": 0,
+        "hunger_change": 0,
+        "karma_change": 0,
+        "new_location": null,
+        "items_gained": [],
+        "items_lost": [],
+        "skills_gained": [],
+        "status_effects_added": [],
+        "status_effects_removed": [],
+        "npc_changes": {{}},
+        "quest_updates": {{}},
+        "weather_change": null,
+        "time_change": null,
+        "global_flags_set": {{}},
+        "world_event": null,
+        "equip": {{}},
+        "title_change": null
+    }},
+    "npc_reactions": {{
+        "NPC名称": "NPC的反应描述"
+    }},
+    "scene_atmosphere": "场景氛围描述（天气、光线、声音等）",
+    "consequence_tags": ["后果标签列表，如 angered_dragon"],
+    "is_reversible": true,
+    "danger_hint": "如果有潜在危险，在这里提示"
+}}
+
+注意：
+- state_changes 中只填写确实发生变化的字段，未变化的字段可以省略或设为 null/0/空
+- npc_changes 格式: {{"NPC名称": {{"attitude": "新态度", "relationship_change": 数值, "memory_add": "新记忆", "hp_change": 数值}}}}
+- quest_updates 格式: {{"任务ID": {{"objectives_completed": ["完成的目标"], "status": "新状态"}}}}
+- 确保所有数值变更合理（例如战斗伤害应考虑攻防差值）
+- 【关键】所有数值变更必须精确，禁止使用“恢复一些”“大幅降低”等模糊描述，必须给出精确数字（如 hunger_change: 14）。
+- 【关键】time_change 字段只允许以下值之一："清晨""上午""正午""下午""黄昏""夜晚""深夜"，不要填写其他格式（如"30分钟""两小时后"等都是非法值）。如果本回合没有发生时间跳跃（例如休息、等待、长途旅行等），请设为 null（系统会自动推进一个时段）。只有当剧情需要跳跃多个时段时才设置此字段。
+- 【关键】游戏内的货币单位是"金币"，对应 gold_change 字段。不要使用"银币""铜币""银两"等其他货币名称，所有交易都以"金币"结算。
+- 【关键】status_effects_added 中每个效果必须是一个对象，且必须包含以下字段：
+    - "name": 中文效果名称（如"中毒""祝福""饱腹"），必须是中文，不要使用英文字段名
+    - "description": 获得原因的简短说明（如"食用面包后精力充沛""被毒蛇咬伤"）
+    - "effect_type": "buff" 或 "debuff" 或 "neutral"
+    - "stat_modifiers": 具体属性影响的字典（如 {{"hp": 5}} 表示每回合恢复5HP）
+    - "duration": 持续回合数（正整数，-1表示永久）
+  示例: {{"name": "饱腹", "description": "吃了面包后恢复了体力", "effect_type": "buff", "stat_modifiers": {{"hp": 2}}, "duration": 3}}
+- 【关键】state_changes 是程序更新游戏状态的唯一数据源，你输出的 JSON 将被直接用于更新游戏状态。请先在心中做算术验证，确保变更后的数值不超出合法范围（HP ∈ [0, max_hp]，饱食度/士气/理智 ∈ [0, 100]）。
+- 【关键】请在生成状态变更 JSON 时，确保数值的精确性和一致性。不要在 JSON 中使用模糊或近似的数值。
+- 【关键】如果某个字段没有发生变化，请完全省略该字段或将其设为 null / 0 / 空。绝对不要将实际值写成字符串 "None"。特别注意：new_location 仅在玩家移动到新地点时填写（必须是具体的地点名称），weather_change 仅在天气真正改变时填写（必须是具体天气名称），title_change 仅在称号真正变更时填写（必须是具体称号名称），world_event 仅在发生世界级大事件时填写。如果没有变化，这些字段统一设为 null 或省略。
+- 【关键】quest_updates 中的 status 字段只允许以下值："active"（进行中）、"completed"（已完成）、"failed"（已失败）。不要使用英文大写或其他变体如 "IN_PROGRESS" "ACTIVE" 等。
+- 【关键】status_effects_added 不是每回合都必须添加的。只有在剧情确实发生了影响角色身心状态的重要事件时才添加状态效果（例如中毒、受到祝福、吃了特殊食物等）。普通的对话、行走、观察等日常行为不应产生状态效果。大约每 3-5 个回合才可能自然产生一次状态效果。同时，状态效果应正向（buff）和负向（debuff）均衡分布，不要总是给予负面效果。
+- 【极其重要 —— 物品消耗规则】items_lost 字段仅用于记录真正消失的物品。判断标准如下：
+  - 消耗品（药水、食物、卷轴、弹药等一次性物品）：使用后会消失，应放入 items_lost。
+  - 非消耗品（哨子、武器、护甲、工具、乐器、钥匙、火把、绳索等可重复使用的物品）：使用后仍然保留在背包中，绝对不要放入 items_lost。
+  - 举例：吹响哨子 → 哨子仍在背包中（不放入 items_lost）；吃了面包 → 面包消失（放入 items_lost）；使用火把照明 → 火把仍在（不放入 items_lost）。
+  - 在背包列表中，标注了[消耗品]的物品才是消耗品，标注[可重复使用]的物���绝对不能因使用而消失。
+  - 如果不确定某个物品是否为消耗品，就不要将它放入 items_lost。
+"""
+
+# ------------------------------------------------------------
+# 第二阶段 Prompt：基于大纲生成文本 + 选项
+#
+# 设计思路：
+# - 将第一阶段的大纲作为硬性约束注入
+# - 要求生成有文学色彩的描写段落
+# - 额外生成 3 个选项，每个选项有标签和描述
+# - 选项应覆盖不同策略（如激进/保守/探索）
+# - 中等温度 (0.8) 增加文学创意
+# ------------------------------------------------------------
+NARRATIVE_SYSTEM_PROMPT_TEMPLATE = """你是一个经验丰富的奇幻小说家，正在为一个互动 RPG 游戏编写剧情文本。
+
+{world_state}
+
+【剧情大纲（必须严格遵守，不可偏离）】
+{outline}
+
+【实际状态变更记录（数值必须以此为准，不可偏离）】
+{actual_changes}
+当你在叙事中提及任何属性数值变化（如 HP、饱食度、金币等）时，必须与上方「实际状态变更记录」完全一致，不要自行推算或编造数值。
+
+【你的任务】
+1. 基于以上大纲，写一段剧情描写（200-400字，使用中文）。
+   - 使用第二人称（“你”）叙述
+   - 【最重要】文本开头必须直接回应玩家的行动或选择，让玩家明确感受到自己的操作产生了效果。例如玩家选择“和铁匠交谈”，开头就应写玩家走向铁匠并开始对话，而不是先写一大段环境描写。
+   - 文风要求：简洁、自然、有画面感。像写小说而不是写诗歌。少用比喻和修辞，多用具体的动作和对话。不要堆砌华丽辞藻，不要每句都加形容词。
+   - 描写要具体：与其说“空气中弥漫着岁月的沉淀”，不如说“柜台上摆着一壶凉透的茶”。用具体的事物代替抽象的感受。
+   - 禁止使用以下老套表达：“阳光洒下”“微风拂过”“空气中弥漫着”“XX与 XX 交织在一起”“如同XX般”。如果你压根想不到新鲜的表达，就用最普通的叙述即可。
+   - 【反重复】严禁在不同回合反复使用相同或极度相似的动作描写和身体反应描写（如“喉结上下一滚”“握紧了拳头”“深吸一口气”等）。每段描写中的动作细节必须是全新的，绝不能与之前出现过的动作描写雷同。如果你不确定是否用过某个表达，就换一种完全不同的描写方式。
+   - 如果大纲中涉及 NPC，要呈现 NPC 的性格特点
+   - NPC 姓名规则：当某个 NPC 在本次冒险中第一次出场时，必须先通过外貌、职业等特征描写他（如“铁匠铺里一个肩宽体壮的矮人”），然后通过自然的方式引出名字（如自我介绍、别人称呼、招牌上写着等）。绝对不要在没有铺垫的情况下直接使用名字。
+   - 如果是战斗场景，描写要紧张刺激
+   - 游戏内的货币统一称为"金币"，不要使用"银币""铜币""银两"等其他名称
+
+2. 在文本之后，生成恰好 3 个后续选项供玩家选择。选项应：
+   - 覆盖不同策略方向（如：激进/谨慎/探索/社交 等）
+   - 每个选项都可能导向不同的剧情分支
+   - 简洁明了，让玩家一眼就能理解
+   - 【关键约束】选项中提及的所有人物、物品和地点，必须已经在本回合的剧情文本中出现过，或在之前的冒险历史中铺垫过。绝对禁止在选项中凭空引入未经铺垫的新 NPC、新地点或新物品。
+   - 【关键约束】如果本回合玩家获得了新物品（武器、食物、药水、装备等），至少一个选项应涉及使用、装备或查看该物品。例如：获得武器→选项之一为"装备XX"；获得食物→选项之一为"食用XX恢复体力"。   - 【关键约束】选项中如果涉及使用某个物品，该物品必须当前在玩家背包中。不要生成使用玩家不拥有的物品的选项。请仔细检查上方的背包列表，确保选项中提及的物品确实在背包中。
+请严格按以下格式输出（先是剧情文本，然后是分隔符，最后是JSON选项）：
+
+---STORY_TEXT---
+（在这里写剧情描写文本）
+---OPTIONS_JSON---
+[
+    {{"id": 1, "text": "选项描述", "action_type": "动作类型（如ATTACK/TALK/MOVE/EXPLORE/USE_ITEM等）"}},
+    {{"id": 2, "text": "选项描述", "action_type": "动作类型"}},
+    {{"id": 3, "text": "选项描述", "action_type": "动作类型"}}
+]
+"""
+
+# ------------------------------------------------------------
+# 死亡结局 Prompt
+# ------------------------------------------------------------
+DEATH_NARRATIVE_PROMPT = """你是一个才华横溢的奇幻小说家。玩家的角色已经死亡，请为他写一段庄严、有诗意的死亡结局描写。
+
+{death_context}
+
+{world_state}
+
+请写一段 150-250 字的死亡结局描写（使用第二人称"你"叙述），包含：
+1. 角色倒下的场��描写
+2. 回顾此次冒险的点滴
+3. 一句意味深长的结语
+
+然后生成 2 个选项：
+---STORY_TEXT---
+（死亡结局文本）
+---OPTIONS_JSON---
+[
+    {{"id": 1, "text": "重新开始冒险", "action_type": "RESTART"}},
+    {{"id": 2, "text": "接受命运，结束游戏", "action_type": "QUIT"}}
+]
+"""
+
+# ------------------------------------------------------------
+# 开场叙事 Prompt
+# ------------------------------------------------------------
+OPENING_NARRATIVE_PROMPT = """你是一个经验丰富的奇幻小说家，正在为一个互动 RPG 游戏编写开场白。
+
+{world_state}
+
+【你的任务】
+写一段游戏开场叙事（200-400字，中文，第二人称“你”叙述）：
+1. 介绍主角（{player_name}）抵达这个村庄的背景
+2. 用具体的场景和细节描写村庄（而不是笼统的氛围形容词）
+3. 暗示冒险即将开始（可以提到村民们的忧虑、远处森林的阴影等）
+4. 以一种引人入胜的方式结束，激发玩家的探索欲望
+
+文风要求：简洁自然，像写小说而不是写诗歌。少用比喻、少用形容词，多用具体的动作和场景细节。禁止使用“阳光洒下”“微风拂过”“空气中弥漫着”等老套表达。
+
+然后生成 3 个初始选项：
+---STORY_TEXT---
+（开场叙事文本）
+---OPTIONS_JSON---
+[
+    {{"id": 1, "text": "前往村庄广场，与村长交谈", "action_type": "TALK"}},
+    {{"id": 2, "text": "先去旅店休息一下，顺便打听消息", "action_type": "MOVE"}},
+    {{"id": 3, "text": "在村子里四处走走，观察环境", "action_type": "EXPLORE"}}
+]
+"""
+
+
+class StoryEngine:
+    """
+    叙事引擎 —— 负责故事内容的生成
+
+    核心工作流程：
+    1. 接收玩家意图（来自 nlu_engine 解析）
+    2. 第一阶段：调用 Qwen 生成剧情大纲 (JSON)
+    3. 一致性检查（通过 state_manager）
+    4. 第二阶段：调用 Qwen 基于大纲生成文学文本 + 选项
+    5. 返回完整结果（文本 + 选项 + 状态变更）
+    """
+
+    def __init__(self, game_state: GameState, model: str = DEFAULT_MODEL):
+        self.game_state = game_state
+        self.model = model
+
+    def generate_opening(self) -> dict:
+        """
+        生成游戏开场叙事。
+
+        Returns:
+            {
+                "story_text": "开场叙事文本",
+                "options": [{"id": 1, "text": "...", "action_type": "..."}],
+                "state_changes": {}
+            }
+        """
+        logger.info("生成游戏开场叙事...")
+
+        prompt = OPENING_NARRATIVE_PROMPT.format(
+            world_state=self.game_state.to_prompt(),
+            player_name=self.game_state.player.name,
+        )
+
+        messages = [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": "请开始讲述故事的开场。"},
+        ]
+
+        raw_text = call_qwen(messages, model=self.model, temperature=0.9, max_tokens=2000)
+        story_text, options = self._parse_story_response(raw_text)
+
+        # 开场没有状态变更
+        return {
+            "story_text": story_text,
+            "options": options,
+            "state_changes": {},
+            "change_log": [],
+        }
+
+    def generate_story(self, player_intent: dict) -> dict:
+        """
+        核心方法：根据玩家意图生成完整的故事响应。
+
+        两阶段生成流程：
+        1. 生成剧情大纲（结构化 JSON）
+        2. 一致性检查
+        3. 基于大纲生成文学文本 + 选项
+        4. 应用状态变更
+
+        Args:
+            player_intent: NLU 引擎解析出的意图
+                {
+                    "intent": "ATTACK",
+                    "target": "哥布林",
+                    "details": "用剑攻击",
+                    "raw_input": "我想攻击那个哥布林"
+                }
+
+        Returns:
+            {
+                "story_text": "剧情文本",
+                "options": [选项列表],
+                "state_changes": {状态变更},
+                "change_log": ["变更日志"],
+                "outline": {大纲},
+                "consistency_issues": ["一致性问题"],
+            }
+        """
+        logger.info(f"生成故事响应，玩家意图: {player_intent}")
+
+        # ============================================
+        # 推进时间（行动前，时间自然流逝）
+        # 设计思路：将 tick_time 放在大纲生成之前，确保：
+        #   1. LLM 看到的是 tick 后的真实状态
+        #   2. apply_changes 的 change_log 与状态栏显示一致
+        #   3. 不会出现“文本说100、状态栏显示97”的同步Bug
+        # ============================================
+        tick_log = self.game_state.tick_time()
+
+        # ============================================
+        # 第一阶段：生成剧情大纲
+        # ============================================
+        outline = self._generate_outline(player_intent)
+
+        if outline is None:
+            # 大纲生成失败 —— 降级处理
+            logger.error("大纲生成失败，使用降级叙事")
+            return self._fallback_response(player_intent, tick_log)
+
+        # ============================================
+        # 处理时间冲突：如果大纲指定了 time_change（时间跳跃），
+        # 则移除 tick_time 自动推进的"时间流逝"日志，
+        # 避免出现"时间流逝: 上午→正午"和"时段变为: 下午"两条冲突记录。
+        # ============================================
+        state_changes = outline.get("state_changes", {})
+        if state_changes.get("time_change"):
+            tick_log = [line for line in tick_log if not line.startswith("时间流逝:")]
+
+        # ============================================
+        # 一致性检查
+        # ============================================
+        consistency_issues = self.game_state.check_consistency(state_changes)
+
+        if consistency_issues:
+            logger.warning(f"发现一致性问题: {consistency_issues}")
+            # 尝试修复：重新生成大纲，附带一致性约束
+            outline = self._regenerate_outline_with_fixes(player_intent, consistency_issues)
+            if outline is None:
+                return self._fallback_response(player_intent, tick_log)
+            state_changes = outline.get("state_changes", {})
+            # 再次检查
+            consistency_issues = self.game_state.check_consistency(state_changes)
+
+        # ============================================
+        # 清理状态变更：阻止非消耗品被错误移除
+        # ============================================
+        event_type = outline.get("event_type", "")
+        state_changes, sanitize_warnings = self._sanitize_state_changes(state_changes, event_type)
+        if sanitize_warnings:
+            logger.info(f"状态变更清理: {sanitize_warnings}")
+
+        # ============================================
+        # 应用状态变更
+        # ============================================
+        change_log = self.game_state.apply_changes(state_changes)
+
+        # 校验状态合法性
+        is_valid, validation_issues = self.game_state.validate()
+
+        # 记录事件
+        self.game_state.log_event(
+            event_type=outline.get("event_type", "UNKNOWN"),
+            description=outline.get("event_summary", ""),
+            player_action=player_intent.get("raw_input", ""),
+            involved_npcs=outline.get("involved_npcs", []),
+            state_changes=state_changes,
+            consequence_tags=outline.get("consequence_tags", []),
+            is_reversible=outline.get("is_reversible", True),
+        )
+
+        # ============================================
+        # 检查是否游戏结束
+        # ============================================
+        if self.game_state.is_game_over():
+            return self._generate_death_narrative()
+
+        # ============================================
+        # 第二阶段：生成文学文本 + 选项
+        # （将实际 change_log 注入叙事 Prompt，确保文本数值与状态一致）
+        # ============================================
+        story_text, options = self._generate_narrative(outline, change_log)
+
+        # 验证生成的选项：确保不引用玩家没有的物品
+        options = self._validate_options(options)
+
+        # 合并 tick_log 和 change_log 中的重复属性条目
+        merged_log = _merge_change_logs(tick_log, change_log + validation_issues)
+
+        return {
+            "story_text": story_text,
+            "options": options,
+            "state_changes": state_changes,
+            "change_log": merged_log,
+            "outline": outline,
+            "consistency_issues": consistency_issues,
+        }
+
+    def _generate_outline(self, player_intent: dict) -> Optional[dict]:
+        """
+        第一阶段：生成剧情大纲。
+
+        使用低温度 (0.3) 确保 JSON 结构稳定，
+        将完整世界状态注入 System Prompt。
+        """
+        system_prompt = OUTLINE_SYSTEM_PROMPT_TEMPLATE.format(
+            world_state=self.game_state.to_prompt(),
+        )
+
+        # 构造用户消息：包含意图的完整描述
+        user_message = (
+            f"玩家行动: {player_intent.get('raw_input', '未知行动')}\n"
+            f"解析意图: {player_intent.get('intent', 'UNKNOWN')}\n"
+            f"目标: {player_intent.get('target', '无')}\n"
+            f"细节: {player_intent.get('details', '无')}"
+        )
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ]
+
+        result = safe_json_call(messages, model=self.model, temperature=0.3, max_tokens=1500)
+
+        if result and isinstance(result, dict):
+            logger.info(f"大纲生成成功: {result.get('event_summary', 'N/A')}")
+            return result
+
+        logger.error("大纲生成失败，未能获取有效 JSON")
+        return None
+
+    def _regenerate_outline_with_fixes(
+        self, player_intent: dict, issues: list[str]
+    ) -> Optional[dict]:
+        """
+        当一致性检查发现问题时，重新生成大纲。
+        将发现的矛盾作为额外约束注入 Prompt。
+        """
+        logger.info("重新生成大纲（附带一致性修正）...")
+
+        system_prompt = OUTLINE_SYSTEM_PROMPT_TEMPLATE.format(
+            world_state=self.game_state.to_prompt(),
+        )
+
+        issues_text = "\n".join(f"- {issue}" for issue in issues)
+        user_message = (
+            f"玩家行动: {player_intent.get('raw_input', '未知行动')}\n"
+            f"解析意图: {player_intent.get('intent', 'UNKNOWN')}\n"
+            f"目标: {player_intent.get('target', '无')}\n"
+            f"细节: {player_intent.get('details', '无')}\n\n"
+            f"【⚠️ 注意：上一次生成存在以下矛盾，请修正】\n{issues_text}\n"
+            f"请重新生成符合逻辑的剧情大纲。"
+        )
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ]
+
+        result = safe_json_call(messages, model=self.model, temperature=0.2, max_tokens=1500)
+
+        if result and isinstance(result, dict):
+            logger.info(f"修正后大纲生成成功: {result.get('event_summary', 'N/A')}")
+            return result
+
+        return None
+
+    def _generate_narrative(self, outline: dict, change_log: list[str] | None = None) -> tuple[str, list[dict]]:
+        """
+        第二阶段：基于大纲生成文学文本 + 3 个选项。
+
+        使用中等温度 (0.8) 增加文学创意。
+
+        Args:
+            outline: 第一阶段生成的剧情大纲
+            change_log: apply_changes 返回的实际状态变更日志，用于约束叙事中的数值描写
+        """
+        import json
+
+        actual_changes_text = "\n".join(change_log) if change_log else "无状态变化"
+        system_prompt = NARRATIVE_SYSTEM_PROMPT_TEMPLATE.format(
+            world_state=self.game_state.to_prompt(),
+            outline=json.dumps(outline, ensure_ascii=False, indent=2),
+            actual_changes=actual_changes_text,
+        )
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": "请基于以上大纲，生成剧情描写和选项。"},
+        ]
+
+        raw_text = call_qwen(
+            messages, model=self.model, temperature=0.8, max_tokens=2000
+        )
+
+        story_text, options = self._parse_story_response(raw_text)
+        return story_text, options
+
+    def _generate_death_narrative(self) -> dict:
+        """生成死亡结局叙事"""
+        logger.info("生成死亡结局...")
+
+        death_context = self.game_state.get_death_narrative_context()
+        prompt = DEATH_NARRATIVE_PROMPT.format(
+            death_context=death_context,
+            world_state=self.game_state.to_prompt(),
+        )
+
+        messages = [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": "请为这位冒险者写一段死亡结局。"},
+        ]
+
+        raw_text = call_qwen(messages, model=self.model, temperature=0.9, max_tokens=1500)
+        story_text, options = self._parse_story_response(raw_text)
+
+        return {
+            "story_text": story_text,
+            "options": options,
+            "state_changes": {},
+            "change_log": ["游戏结束"],
+            "outline": None,
+            "consistency_issues": [],
+        }
+
+    def _parse_story_response(self, raw_text: str) -> tuple[str, list[dict]]:
+        """
+        解析 LLM 返回的故事响应，分离文本和选项。
+
+        预期格式：
+        ---STORY_TEXT---
+        (故事文本)
+        ---OPTIONS_JSON---
+        [JSON 选项数组]
+
+        降级策略：如果格式不符，尝试直接提取 JSON 数组。
+        """
+        story_text = ""
+        options = []
+
+        if "---STORY_TEXT---" in raw_text and "---OPTIONS_JSON---" in raw_text:
+            # 标准格式解析：严格取两个标记之间的内容，避免LLM在标记前重复输出导致文本重复
+            story_start = raw_text.index("---STORY_TEXT---") + len("---STORY_TEXT---")
+            options_start = raw_text.index("---OPTIONS_JSON---")
+            story_part = raw_text[story_start:options_start].strip()
+            options_part = raw_text[options_start + len("---OPTIONS_JSON---"):].strip()
+
+            story_text = story_part
+            parsed_options = extract_json_from_text(options_part)
+            if isinstance(parsed_options, list):
+                options = parsed_options
+        else:
+            # 降级：尝试找到 JSON 数组作为选项
+            logger.warning("响应格式不标准，尝试降级解析")
+            # 查找最后出现的 JSON 数组
+            import re
+            array_matches = list(re.finditer(r"\[[\s\S]*?\]", raw_text))
+            if array_matches:
+                last_match = array_matches[-1]
+                options_text = last_match.group()
+                parsed = extract_json_from_text(options_text)
+                if isinstance(parsed, list):
+                    options = parsed
+                    story_text = raw_text[:last_match.start()].strip()
+                else:
+                    story_text = raw_text
+            else:
+                story_text = raw_text
+
+        # 确保至少有默认选项
+        if not options:
+            options = self._generate_default_options()
+
+        return story_text, options
+
+    def _generate_default_options(self) -> list[dict]:
+        """生成默认选项（当 LLM 未能提供有效选项时的降级方案）"""
+        available = self.game_state.get_available_actions()
+        default_options = []
+
+        action_map = {
+            "观察": {"text": "仔细观察周围的环境", "action_type": "EXPLORE"},
+            "对话": {"text": "与附近的人交谈", "action_type": "TALK"},
+            "移动": {"text": "前往其他地方", "action_type": "MOVE"},
+            "休息": {"text": "在此处休息一会儿", "action_type": "REST"},
+            "战斗": {"text": "准备战斗", "action_type": "ATTACK"},
+            "搜索": {"text": "搜索这个区域", "action_type": "EXPLORE"},
+        }
+
+        for i, action in enumerate(available[:3], 1):
+            if action in action_map:
+                opt = action_map[action].copy()
+                opt["id"] = i
+                default_options.append(opt)
+
+        # 确保恰好 3 个选项
+        while len(default_options) < 3:
+            default_options.append({
+                "id": len(default_options) + 1,
+                "text": "继续探索",
+                "action_type": "EXPLORE",
+            })
+
+        return default_options[:3]
+
+    def _fallback_response(self, player_intent: dict, tick_log: list[str] | None = None) -> dict:
+        """
+        降级响应：当大纲生成完全失败时，提供基本响应。
+
+        设计思路：
+        - 直接用单次调用生成简短叙事 + 选项
+        - 不涉及状态变更（安全保守策略）
+        - 确保游戏不会卡死
+
+        Args:
+            player_intent: 玩家意图
+            tick_log: tick_time 返回的时间流逝日志（可能为 None）
+        """
+        logger.warning("使用降级响应模式")
+
+        fallback_prompt = (
+            f"你是一个 RPG 游戏的叙事引擎。\n"
+            f"当前场景: {self.game_state.world.current_scene}\n"
+            f"玩家说: {player_intent.get('raw_input', '...')}\n\n"
+            f"请写一段简短的过渡叙事（100字以内），并给出 3 个后续选项。\n"
+            f"格式:\n"
+            f"---STORY_TEXT---\n(叙事文本)\n---OPTIONS_JSON---\n"
+            f'[{{"id":1,"text":"选项1","action_type":"EXPLORE"}},'
+            f'{{"id":2,"text":"选项2","action_type":"TALK"}},'
+            f'{{"id":3,"text":"选项3","action_type":"MOVE"}}]'
+        )
+
+        messages = [
+            {"role": "system", "content": fallback_prompt},
+            {"role": "user", "content": "请继续。"},
+        ]
+
+        try:
+            raw_text = call_qwen(messages, model=self.model, temperature=0.7, max_tokens=800)
+            story_text, options = self._parse_story_response(raw_text)
+        except Exception:
+            story_text = "你沉思片刻，思考着下一步该怎么做..."
+            options = self._generate_default_options()
+
+        fallback_change_log = (tick_log or []) + ["（系统提示：本回合使用了降级响应）"]
+        return {
+            "story_text": story_text,
+            "options": options,
+            "state_changes": {},
+            "change_log": fallback_change_log,
+            "outline": None,
+            "consistency_issues": [],
+        }
+
+    def _sanitize_state_changes(self, changes: dict, event_type: str = "") -> tuple[dict, list[str]]:
+        """
+        清理状态变更：阻止非消耗品因使用而被移除。
+
+        规则：
+        - 交易(TRADE)、赠送、丢弃等行为可以移除任何物品
+        - 其他行为（使用、探索、对话等）只能移除消耗品
+
+        Args:
+            changes: 状态变更字典
+            event_type: 事件类型（来自大纲）
+
+        Returns:
+            (清理���的changes, 警告列表)
+        """
+        warnings = []
+        if "items_lost" not in changes:
+            return changes, warnings
+
+        # 交易/赠送行为可以移除任何物品
+        trade_events = {"TRADE", "GIVE", "DROP"}
+        if event_type.upper() in trade_events:
+            return changes, warnings
+
+        # 其他行为：只允许移除消耗品
+        changes = dict(changes)  # 浅拷贝，避免修改原始数据
+        sanitized_items_lost = []
+        for item_name in changes["items_lost"]:
+            item_str = str(item_name)
+            if self.game_state.is_item_consumable(item_str):
+                sanitized_items_lost.append(item_name)
+            else:
+                warnings.append(
+                    f"物品 '{item_str}' 不是消耗品，使用后仍保留在背包中"
+                )
+                logger.warning(f"阻止移除非消耗品: {item_str}")
+
+        if sanitized_items_lost:
+            changes["items_lost"] = sanitized_items_lost
+        else:
+            changes.pop("items_lost", None)
+
+        return changes, warnings
+
+    def _validate_options(self, options: list[dict]) -> list[dict]:
+        """
+        验证生成的选项：移除引用了玩家不拥有的物品的选项。
+
+        检查逻辑：
+        - 收集所有已知物品名（来自 item_registry 和事件日志）
+        - 如果选项文本提及了某个已知物品，但该物品不在当前背包中，
+          则该选项无效，替换为默认选项
+        """
+        inventory = set(self.game_state.player.inventory)
+
+        # 构建所有已知物品名称集合
+        known_items: set[str] = set(self.game_state.world.item_registry.keys())
+        for event in self.game_state.event_log:
+            sc = event.state_changes
+            if isinstance(sc, dict):
+                for item in sc.get("items_gained", []):
+                    known_items.add(str(item))
+                for item in sc.get("items_lost", []):
+                    known_items.add(str(item))
+
+        # 玩家不拥有的已知物品
+        unavailable_items = known_items - inventory
+
+        validated = []
+        for opt in options:
+            text = opt.get("text", "")
+            action_type = opt.get("action_type", "")
+            is_valid = True
+
+            # 检查选项是否引用了玩家不拥有的物品
+            for item_name in unavailable_items:
+                # 只检查名称足够长的物品（避免单字误匹配）
+                if len(item_name) >= 2 and item_name in text:
+                    # 额外确认：如果选项是使用类动作，更可能是无效的
+                    # 对于移动/对话类选项，提及物品可能只是描述性的
+                    if action_type in ("USE_ITEM", "EQUIP", "SKILL"):
+                        logger.warning(
+                            f"移除无效选项（引用了不在背包中的物品 '{item_name}'）: {text}"
+                        )
+                        is_valid = False
+                        break
+                    # 对于其他动作类型，用更严格的判断：是否是“使用XX”“吹XX”“吃XX”等模式
+                    use_patterns = [
+                        f"使用{item_name}", f"吹响{item_name}", f"吹{item_name}",
+                        f"吃{item_name}", f"喝{item_name}", f"装备{item_name}",
+                        f"拿出{item_name}", f"打开{item_name}",
+                    ]
+                    if any(pattern in text for pattern in use_patterns):
+                        logger.warning(
+                            f"移除无效选项（涉及使用不在背包中的物品 '{item_name}'）: {text}"
+                        )
+                        is_valid = False
+                        break
+
+            if is_valid:
+                validated.append(opt)
+
+        # 确保仍然有 3 个选项
+        if len(validated) < 3:
+            defaults = self._generate_default_options()
+            for d in defaults:
+                if len(validated) >= 3:
+                    break
+                # 避免重复选项
+                if not any(v.get("text") == d["text"] for v in validated):
+                    d["id"] = len(validated) + 1
+                    validated.append(d)
+
+        # 重新编号
+        for i, opt in enumerate(validated[:3], 1):
+            opt["id"] = i
+
+        return validated[:3]
+
+    def process_option_selection(self, option: dict) -> dict:
+        """
+        处理玩家点击选项的操作。
+
+        将选项转化为意图格式，然后调用 generate_story。
+
+        Args:
+            option: 玩家选择的选项 {"id": 1, "text": "...", "action_type": "..."}
+
+        Returns:
+            generate_story 的返回结果
+        """
+        intent = {
+            "intent": option.get("action_type", "EXPLORE"),
+            "target": None,
+            "details": option.get("text", ""),
+            "raw_input": option.get("text", ""),
+        }
+        return self.generate_story(intent)

utils.py

@@ -0,0 +1,278 @@
+"""
+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
+from openai import OpenAI
+
+# ============================================================
+# 日志配置
+# ============================================================
+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[OpenAI] = None
+
+
+def get_client() -> OpenAI:
+    """
+    获取全局 OpenAI 客户端（懒加载单例）。
+    使用兼容格式调用 Qwen API。
+    """
+    global _client
+    if _client is None:
+        _client = OpenAI(
+            api_key=QWEN_API_KEY,
+            base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+        )
+    return _client
+
+
+# ============================================================
+# 默认模型配置
+# ============================================================
+# 推荐使用 qwen-plus 平衡速度和效果
+DEFAULT_MODEL: str = "qwen-plus"
+
+
+# ============================================================
+# 通用 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}"
+    )
+
+
+# ============================================================
+# 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)