文档&图片显示

app.py

@@ -23,7 +23,7 @@ import gradio as gr
 
 from state_manager import GameState
 from nlu_engine import NLUEngine
-from scene_assets import get_scene_image_path
+from scene_assets import get_scene_image_path, IMAGE_DIR
 from story_engine import StoryEngine
 from telemetry import append_turn_log, create_session_metadata
 from utils import logger
@@ -1997,6 +1997,7 @@ if __name__ == "__main__":
         server_port=7860,
         share=False,
         show_error=True,
+        allowed_paths=[str(IMAGE_DIR)],
         theme=gr.themes.Soft(
             primary_hue="emerald",
             secondary_hue="blue",

技术实现文档.md

@@ -0,0 +1,811 @@
+# StoryWeaver 技术实现文档
+
+**版本：** 1.0
+**适用范围：** 供组员理解系统运行原理、撰写项目报告使用
+
+---
+
+## 目录
+
+1. [项目概述](#1-项目概述)
+2. [技术栈](#2-技术栈)
+3. [系统架构](#3-系统架构)
+4. [模块详解](#4-模块详解)
+5. [核心数据流](#5-核心数据流)
+6. [API 集成：通义千问](#6-api-集成通义千问)
+7. [两阶段叙事生成策略](#7-两阶段叙事生成策略)
+8. [状态管理机制](#8-状态管理机制)
+9. [自然语言理解（NLU）模块](#9-自然语言理解nlu模块)
+10. [Web UI 与流式输出](#10-web-ui-与流式输出)
+11. [场景图片显示机制（及修复说明）](#11-场景图片显示机制及修复说明)
+12. [遥测与日志系统](#12-遥测与日志系统)
+13. [评估框架](#13-评估框架)
+14. [项目文件结构](#14-项目文件结构)
+
+---
+
+## 1. 项目概述
+
+StoryWeaver 是一个基于大语言模型（LLM）的**交互式文字冒险 RPG 系统**。玩家通过自然语言输入（或选择预设选项）驱动剧情发展，系统通过 AI 实时生成叙事文本、管理角色状态、解析玩家意图。
+
+**核心特点：**
+
+- 使用通义千问（Qwen）API 进行自然语言意图识别和叙事内容生成
+- 两阶段生成策略保证剧情逻辑一致性（先生成 JSON 大纲，再生成文学文本）
+- 完整的游戏状态管理（HP/MP、背包、任务、时间、天气、NPC 关系）
+- 基于 Gradio 的 Web UI，支持流式文字输出（实时打字效果）
+- JSONL 格式的完整交互日志，支持离线分析与评估
+
+---
+
+## 2. 技术栈
+
+| 技术 | 版本要求 | 用途 |
+|------|---------|------|
+| Python | 3.10+ | 主语言 |
+| Gradio | ≥4.0（实测 6.9.0） | Web UI 框架 |
+| OpenAI Python SDK | ≥1.0.0 | 调用通义千问 API（OpenAI 兼容格式） |
+| Pydantic | ≥2.0.0 | 数据模型定义与校验 |
+| python-dotenv | ≥1.0.0 | 从 `.env` 文件加载 API Key |
+
+**外部 API：**
+
+- **通义千问 API**（阿里云 DashScope）
+  - 端点：`https://dashscope.aliyuncs.com/compatible-mode/v1`
+  - 默认模型：`qwen2.5-14b-instruct`
+  - 认证：`QWEN_API_KEY` 环境变量
+
+---
+
+## 3. 系统架构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    用户（浏览器）                           │
+│              文字输入 / 点击选项按钮                        │
+└──────────────────┬───────────────────────────────────────┘
+                   │ HTTP（Gradio 前端）
+┌──────────────────▼───────────────────────────────────────┐
+│                  app.py（UI 协调层）                        │
+│   - 构建 Gradio 界面（聊天框、选项按钮、状态面板、地图）      │
+│   - 管理 Gradio State（游戏会话持久化）                      │
+│   - 流式 yield 输出（打字机效果）                           │
+└──────┬───────────────────────┬──────────────────────────┘
+       │                       │
+       ▼                       ▼
+┌─────────────┐       ┌────────────────────┐
+│  NLU 引擎   │       │   叙事引擎           │
+│ nlu_engine  │──────▶│  story_engine.py    │
+│ .py         │       │                    │
+│ 意图解析     │       │ 两阶段生成策略       │
+│ TALK/MOVE/  │       │ 1. JSON 大纲        │
+│ ATTACK/...  │       │ 2. 文学叙事文本      │
+└─────────────┘       └─────────┬──────────┘
+                                │
+                    ┌───────────▼──────────┐
+                    │  状态管理器           │
+                    │  state_manager.py    │
+                    │                     │
+                    │  GameState          │
+                    │  PlayerState        │
+                    │  WorldState         │
+                    │  QuestState         │
+                    │  NPCState           │
+                    └─────────────────────┘
+                                │
+                    ┌───────────▼──────────┐
+                    │  通义千问 API         │
+                    │  (via utils.py)      │
+                    │  qwen2.5-14b-instruct│
+                    └─────────────────────┘
+```
+
+### 模块职责一览
+
+| 文件 | 行数 | 核心职责 |
+|------|------|---------|
+| `app.py` | 2006 | Gradio UI、事件绑定、输出流协调 |
+| `state_manager.py` | 2636 | 游戏状态全量管理、一致性校验 |
+| `story_engine.py` | 4074 | AI 叙事生成（两阶段）、规则判定 |
+| `nlu_engine.py` | 431 | 自然语言意图解析（LLM + 关键词兜底） |
+| `utils.py` | 328 | Qwen API 封装、JSON 解析工具 |
+| `combat_engine.py` | 97 | 战斗结算逻辑 |
+| `scene_assets.py` | 31 | 场景图片路径解析 |
+| `demo_rules.py` | 1410 | 游戏规则常量、选项构建函数 |
+| `telemetry.py` | 81 | 交互日志（JSONL 格式） |
+
+---
+
+## 4. 模块详解
+
+### 4.1 app.py — UI 协调层
+
+`app.py` 是整个系统的入口，负责把各个引擎"粘合"在一起并呈现给用户。
+
+**关键函数：**
+
+```
+create_new_game(player_name)
+    └─ 初始化 GameState、NLUEngine、StoryEngine，返回 game_session 字典
+
+start_game(player_name, game_session)
+    └─ 生成器函数，流式 yield 开场叙事及初始状态
+
+process_user_input(user_input, chat_history, game_session)
+    └─ 主处理函数：NLU解析 → 引擎生成 → 状态更新 → 流式输出
+
+process_option_click(index, chat_history, game_session)
+    └─ 处理选项按钮点击，委托给 story_engine.process_option_selection_stream()
+
+_get_scene_image_update(gs)
+    └─ 调用 scene_assets 获取图片路径，返回 gr.update(value=..., visible=...)
+```
+
+**Gradio 状态管理：**
+
+Gradio 是无状态框架，通过 `gr.State(value={})` 在 HTTP 请求间保持游戏会话：
+
+```python
+game_session = {
+    "game_state": GameState,     # 完整游戏状态
+    "nlu": NLUEngine,            # NLU 引擎实例
+    "story": StoryEngine,        # 叙事引擎实例
+    "current_options": [...],    # 当前轮次的选项列表
+    "started": True,             # 是否已开始游戏
+    "session_id": "sw-...",      # 日志会话 ID
+    "turn_index": 3,             # 当前回合数
+}
+```
+
+**流式输出机制：**
+
+所有面向用户的函数都是 Python 生成器（`yield`），Gradio 会将每次 `yield` 的结果推送到前端，实现打字机效果：
+
+```python
+def start_game(player_name, game_session):
+    # 初始加载状态
+    yield (chat_history, world_info, status, map_html, image_update, ...)
+
+    # 流式文字更新（每收到一个 chunk 推一次）
+    for update in story_engine.generate_opening_stream():
+        if update["type"] == "story_chunk":
+            chat_history[-1]["content"] = update["text"]
+            yield (chat_history, ...)
+
+    # 最终状态（含选项）
+    yield (chat_history, ..., enabled_buttons, ...)
+```
+
+---
+
+### 4.2 state_manager.py — 游戏状态管理
+
+`state_manager.py` 是系统的"单一数据源"（Single Source of Truth），所有游戏数据均从此处读写。
+
+**数据模型层级：**
+
+```
+GameState（根对象）
+├── player: PlayerState
+│   ├── name, hp, max_hp, mp, attack, defense, level, exp
+│   ├── gold, location
+│   ├── inventory: list[str]          # 背包物品
+│   ├── equipment: dict[str, str]     # 装备槽 → 物品名
+│   ├── status_effects: list[StatusEffect]
+│   └── skills: list[str]
+│
+├── world: WorldState
+│   ├── current_scene: str            # 当前场景名
+│   ├── locations: dict[str, LocationInfo]  # 13 个地点
+│   ├── npcs: dict[str, NPCState]     # 8 个 NPC
+│   ├── quests: dict[str, QuestState] # 任务列表
+│   ├── time_of_day, weather          # 环境状态
+│   └── discovered_locations: set[str]
+│
+├── event_log: list[GameEvent]        # 事件记录（一致性检测用）
+└── location_history: list[str]       # 地点访问历史（地图显示用）
+```
+
+**核心方法：**
+
+| 方法 | 作用 |
+|------|------|
+| `apply_changes(changes)` | 应用叙事引擎返回的状态变更 JSON，返回变更日志 |
+| `pre_validate_action(intent)` | 早期拒绝非法操作（如在无商人处交易） |
+| `check_consistency(changes)` | 检测拟议变更是否与当前状态矛盾 |
+| `to_prompt()` | 将当前状态序列化为 LLM prompt 文本 |
+| `tick_time(intent)` | 推进游戏时间，触发天气/环境/状态效果 |
+| `validate()` | 完整状态合法性校验 |
+
+**不可变更新原则：**
+
+`apply_changes` 不直接修改对象字段，而是通过 Pydantic 的 `model_copy(update=...)` 生成新对象，确保状态更新的可追溯性。
+
+---
+
+### 4.3 story_engine.py — 叙事生成引擎
+
+这是系统最复杂的模块（4074 行），负责调用 LLM 生成游戏叙事。
+
+**两阶段生成策略（Chain of Thought）：**
+
+```
+玩家意图 (intent JSON)
+        │
+        ▼
+【阶段一：合并单次调用】
+MERGED_SYSTEM_PROMPT_TEMPLATE 包含：
+  - 当前世界状态（from game_state.to_prompt()）
+  - 玩家意图
+  - 输出格式约束：---STORY_TEXT--- 与 ---OPTIONS_JSON--- 分隔
+
+LLM 输出格式：
+  ---STORY_TEXT---
+  （200-400字的叙事文本）
+  ---OPTIONS_JSON---
+  [{"text":"...", "action_type":"MOVE", "target":"..."}, ...]
+        │
+        ▼
+【解析 + 状态更新】
+  story_engine 解析 JSON 选项
+  state_manager.apply_changes() 更新状态
+  telemetry.append_turn_log() 记录日志
+        │
+        ▼
+【返回前端】
+  {"story_text": "...", "options": [...], "state_changes": {...}}
+```
+
+**规则判定优先级（rule-based 短路）：**
+
+在调用 LLM 之前，`story_engine` 先检查规则系统是否能直接处理该意图，避免不必要的 API 调用：
+
+1. `_rule_trade_response()` — 商店买卖（直接结算，无需 LLM）
+2. `_rule_equip_response()` — 装备物品
+3. `_rule_shop_menu_response()` — 打开商店菜单
+4. `_rule_scene_options_response()` — 场景选项刷新
+
+只有以上规则无法处理的意图（探索、对话、战斗叙事等），才会进入 LLM 生成流程。
+
+**流式生成实现：**
+
+`generate_story_stream()` 调用 `call_qwen_stream()`，逐 token 接收 LLM 输出：
+
+```python
+for chunk in call_qwen_stream(messages, ...):
+    full_text += chunk
+    # 检测到 ---STORY_TEXT--- 后开始向前端推送文字
+    if story_started:
+        yield {"type": "story_chunk", "text": current_story_text}
+
+# 流结束后一次性解析 OPTIONS_JSON
+yield {"type": "final", "story_text": ..., "options": [...], ...}
+```
+
+---
+
+### 4.4 nlu_engine.py — 自然语言理解
+
+`NLUEngine` 将玩家输入的自然语言转换为结构化意图，供叙事引擎处理。
+
+**解析流程：**
+
+```
+用户输入（如"我想和村长聊聊森林的事"）
+        │
+        ▼
+【第一步：LLM 解析】_llm_parse()
+  构建包含当前场景上下文的 prompt
+  调用 call_qwen() 获取 JSON 意图
+        │
+        ├─ 成功 → 返回结构化意图
+        └─ 失败 → 降级到关键词匹配
+
+【第二步：关键词兜底】_keyword_fallback()
+  正则匹配攻击/对话/移动/探索等关键词
+  从场景 NPC/地点列表中抽取目标
+        │
+        ▼
+【第三步：意图后处理】_apply_intent_postprocessing()
+  - 修正高置信度错误（如误识别交易为对话）
+  - 推断攻击/交易目标
+        │
+        ▼
+输出意图 JSON：
+{
+  "intent": "TALK",         # 意图类型
+  "target": "村长老伯",      # 操作目标
+  "details": "询问森林怪事",  # 补充信息
+  "raw_input": "原始输入",
+  "parser_source": "llm"   # 或 "keyword_fallback"
+}
+```
+
+**支持的意图类型：**
+
+`ATTACK` / `TALK` / `MOVE` / `EXPLORE` / `USE_ITEM` / `TRADE` / `EQUIP` / `REST` / `QUEST` / `SKILL` / `PICKUP` / `FLEE` / `CUSTOM`
+
+---
+
+### 4.5 utils.py — API 工具层
+
+**API 客户端初始化（懒加载单例）：**
+
+```python
+_client: Optional[OpenAI] = None
+
+def get_client() -> OpenAI:
+    global _client
+    if _client is None:
+        _client = OpenAI(
+            api_key=QWEN_API_KEY,
+            base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+        )
+    return _client
+```
+
+通义千问 API 兼容 OpenAI 格式，因此直接使用 `openai` Python 包，仅替换 `base_url`。
+
+**重试机制（指数退避）：**
+
+```python
+def call_qwen(messages, model, temperature, max_tokens, max_retries=3, retry_delay=1.0):
+    for attempt in range(1, max_retries + 1):
+        try:
+            response = client.chat.completions.create(...)
+            return response.choices[0].message.content.strip()
+        except Exception as e:
+            time.sleep(retry_delay * (2 ** (attempt - 1)))
+    raise last_exception
+```
+
+**JSON 鲁棒提取（5 种策略）：**
+
+LLM 输出格式有时不稳定，`extract_json_from_text()` 依次尝试：
+
+1. 直接 `json.loads(text)`
+2. 提取 ` ```json ... ``` ` 代码块
+3. 正则匹配最外层 `{ ... }`
+4. 深度嵌套花括号匹配
+5. 数组 `[ ... ]` 匹配
+
+---
+
+## 5. 核心数据流
+
+### 玩家文字输入完整流程
+
+```
+用户在输入框中输入文字，点击发送
+                │
+                ▼
+app.py: process_user_input(user_input, chat_history, game_session)
+                │
+                ├─ 1. state_manager.pre_validate_action(intent)
+                │        → 早期拒绝非法操作，直接返回提示文本
+                │
+                ├─ 2. nlu_engine.parse_intent(user_input)
+                │        → 返回 intent dict {"intent": "TALK", "target": "..."}
+                │
+                ├─ 3. story_engine.generate_story_stream(intent)
+                │        ├─ 规则判定短路（交易/装备等直接处理）
+                │        ├─ state_manager.tick_time()（时间推进）
+                │        ├─ state_manager.check_consistency(changes)
+                │        ├─ call_qwen_stream()（流式调用 LLM）
+                │        └─ yield {"type": "story_chunk"/"final", ...}
+                │
+                ├─ 4. state_manager.apply_changes(state_changes)
+                │        → 更新 HP/物品/位置/任务等状态
+                │
+                ├─ 5. telemetry.append_turn_log(...)
+                │        → 写入 JSONL 日志文件
+                │
+                └─ 6. yield 到前端
+                         → chatbot 内容（流式）
+                         → world_info_panel（世界信息）
+                         → status_panel（角色状态）
+                         → location_map_panel（SVG 地图）
+                         → scene_image（场景图片）
+                         → option_buttons（6 个选项按钮）
+                         → game_session（更新后的状态）
+```
+
+### 选项按钮点击流程
+
+```
+用户点击选项按钮（如"前往黑暗森林"）
+                │
+                ▼
+app.py: process_option_click(button_index, chat_history, game_session)
+                │
+                ├─ 从 game_session["current_options"][index] 获取选项数据
+                │        {"text": "...", "action_type": "MOVE", "target": "黑暗森林入口"}
+                │
+                ├─ 构建 fake_intent（跳过 NLU，直接使用选项数据）
+                │
+                └─ story_engine.process_option_selection_stream(option)
+                         └─ 调用 generate_story_stream(intent)（与文字输入相同流程）
+```
+
+---
+
+## 6. API 集成：通义千问
+
+### 配置方式
+
+项目根目录创建 `.env` 文件：
+
+```
+QWEN_API_KEY=sk-your-actual-api-key-here
+STORYWEAVER_LOG_DIR=logs/interactions
+```
+
+### 模型选择
+
+默认使用 `qwen2.5-14b-instruct`（定义于 `utils.py:DEFAULT_MODEL`）。
+
+### API 调用两种模式
+
+| 函数 | 模式 | 用途 |
+|------|------|------|
+| `call_qwen()` | 同步（阻塞） | NLU 意图解析、规则文本润色 |
+| `call_qwen_stream()` | 流式（generator） | 叙事生成（打字机效果） |
+
+---
+
+## 7. 两阶段叙事生成策略
+
+### 设计动机
+
+直接让 LLM 生成"叙事文本 + 状态变化"时存在两个矛盾：
+- **文学质量要求**：状态数字（HP 减少 15）需要转化为生动描写
+- **数据准确要求**：状态变化必须是精确的、可解析的结构化数据
+
+两阶段策略将两个目标分离：
+
+### 实现方式（MERGED_SYSTEM_PROMPT_TEMPLATE）
+
+Gradio 6.x 版本中实际上使用了**合并单次调用**（`MERGED_SYSTEM_PROMPT_TEMPLATE`），在同一个 LLM 响应中要求模型先"思考"状态变化（以 JSON 形式嵌入在思维链中），再输出叙事文本和选项，降低延迟同时保留结构。
+
+**Prompt 输出格式约束：**
+
+```
+---STORY_TEXT---
+（200-400字文学叙事）
+---OPTIONS_JSON---
+[
+  {"text": "向村长询问森林异变的起因", "action_type": "TALK", "target": "村长老伯"},
+  {"text": "独自前往黑暗森林探查", "action_type": "MOVE", "target": "黑暗森林入口"},
+  {"text": "在旅店休息一晚恢复体力", "action_type": "REST", "target": null}
+]
+```
+
+`story_engine` 在接收到完整响应后，从 `---OPTIONS_JSON---` 分隔符之后解析 JSON，并从中提取状态变更数据。
+
+---
+
+## 8. 状态管理机制
+
+### 一致性校验（check_consistency）
+
+`state_manager.check_consistency()` 在叙事引擎生成大纲后执行校验，检测矛盾：
+
+- 不在当前地点的 NPC 不能被互动
+- 背包中没有的物品不能被使用或出售
+- 已死亡的 NPC 不能出现对话
+- 已完成的任务目标不能重复完成
+- HP 不能超过 max_hp
+
+### 时间系统（tick_time）
+
+每次玩家行动后，`tick_time()` 会根据行动类型推进游戏时间（单位：分钟）：
+
+```
+ACTION_TIME_COSTS（定义于 demo_rules.py）：
+  TALK     →  5 分钟
+  MOVE     → 15~60 分钟（取决于距离）
+  ATTACK   →  5 分钟
+  REST     → 480 分钟（过夜）
+  EXPLORE  → 20 分钟
+  ...
+```
+
+时间推进触发：天气变化、光照变化（白天/夜晚/黄昏）、状态效果倒计时、任务截止检查。
+
+### 装备系统
+
+装备采用槽位设计：`weapon`、`armor`、`accessory`。装备后自动通过 `get_equipment_stat_bonuses()` 叠加战斗属性。
+
+---
+
+## 9. 自然语言理解（NLU）模块
+
+### 上下文注入
+
+NLU 解析时，`_build_context()` 会将当前场景信息注入 LLM prompt：
+
+```
+当前地点：村庄广场
+在场 NPC：村长老伯
+可见物品：村庄公告板
+可前往地点：村庄旅店、村庄铁匠铺、村口小路
+```
+
+这使 LLM 能准确识别"跟他说话"中"他"指的是当前场景的 NPC。
+
+### 关键词回退
+
+当 LLM 解析失败时，`_keyword_fallback()` 通过正则匹配兜底：
+
+```python
+ATTACK_PATTERNS  = [r"攻击", r"打", r"砍", r"杀", ...]
+MOVE_PATTERNS    = [r"去", r"前往", r"走向", r"移动到", ...]
+TALK_PATTERNS    = [r"说", r"聊", r"问", r"交谈", ...]
+```
+
+---
+
+## 10. Web UI 与流式输出
+
+### 界面布局
+
+```
+┌─────────────────────────────────────────────────────────┐
+│            StoryWeaver — 交互式叙事系统                    │
+├────────────────────────────────┬────────────────────────┤
+│  角色名称输入  │ 开始冒险 │ 重启 │  世界信息面板           │
+├────────────────────────────────┤  （时间/天气/任务概要）  │
+│                                ├────────────────────────┤
+│   聊天框（故事叙事区域）          │  场景图片（当前地点）    │
+│   实时流式文字显示               ├────────────────────────┤
+│                                │  角色状态面板            │
+│                                │  （HP/MP/金币/等级）     │
+├────────────────────────────────┤                        │
+│  文字输入框  │ 发送  │ 打开背包  ├────────────────────────┤
+├────────────────────────────────┤  地图面板（SVG 拓扑图）  │
+│ [选项1] [选项2] [选项3]         │                        │
+│ [选项4] [选项5] [选项6]         │                        │
+└────────────────────────────────┴────────────────────────┘
+```
+
+### 选项按钮系统
+
+每轮生成 3 个选项按钮（最多 6 个），选项数据结构：
+
+```python
+{
+    "text": "前往黑暗森林入口",    # 按钮显示文字
+    "action_type": "MOVE",       # 行动类型
+    "target": "黑暗森林入口",     # 目标
+}
+```
+
+### SVG 地图
+
+`_render_text_map()` 根据 `discovered_locations` 动态生成 SVG 拓扑图，显示已探索地点及连接关系，当前位置高亮显示。
+
+---
+
+## 11. 场景图片显示机制（及修复说明）
+
+### 图片资源
+
+`image/` 目录包含 21 张 PNG 图片（约 4~6 MB 每张），按名称分为两类：
+
+- **地点图片**：文件名 = 游戏中地点名称（如 `村庄广场.png`、`黑暗森林入口.png`）
+- **NPC 图片**：文件名 = NPC 名称（如 `村长老伯.png`、`铁匠格林.png`）
+
+### 图片路径解析（scene_assets.py）
+
+```python
+IMAGE_DIR = Path(__file__).resolve().parent / "image"
+
+def get_scene_image_path(game_state, focus_npc=None):
+    # 优先显示当前交互 NPC 的图片
+    if focus_npc:
+        path = IMAGE_DIR / f"{focus_npc}.png"
+        if path.exists():
+            return str(path)
+
+    # 其次显示当前地点图片
+    for location_name in (game_state.world.current_scene, game_state.player.location):
+        path = IMAGE_DIR / f"{location_name}.png"
+        if path.exists():
+            return str(path)
+
+    return None
+```
+
+### 图片更新触发
+
+每次游戏状态更新（包括开场、玩家输入、点击选项）时，`app.py` 调用：
+
+```python
+def _get_scene_image_update(gs: GameState):
+    image_value = _get_scene_image_value(gs)
+    return gr.update(value=image_value, visible=bool(image_value))
+```
+
+该更新被包含在所有事件处理函数的 `yield` 元组中，传递给 `gr.Image` 组件。
+
+### 问题根因
+
+**Gradio 6.x 文件访问安全限制（`allowed_paths` 未配置）**
+
+在 Gradio 5.0 以后，框架收紧了文件服务安全策略：服务器只允许向客户端传输经过授权的文件路径。默认情况下，仅有 Gradio 的临时上传目录（`uploaded_file_dir`）和缓存目录（`get_cache_folder()`）中的文件被允许访问。
+
+**核心代码（Gradio 源码 `routes.py`）：**
+
+```python
+allowed, reason = utils.is_allowed_file(
+    abs_path,
+    blocked_paths=blocks.blocked_paths,
+    allowed_paths=blocks.allowed_paths + _StaticFiles.all_paths,
+    created_paths=[app.uploaded_file_dir, utils.get_cache_folder()],
+)
+if not allowed:
+    raise HTTPException(403, f"File not allowed: {path_or_url}.")
+```
+
+原代码的 `app.launch()` 未设置 `allowed_paths`，导致 `blocks.allowed_paths = []`，图片文件路径验证失败，浏览器收到 **HTTP 403 Forbidden** 响应，图片无法加载。
+
+### 修复方案
+
+**修改文件：`app.py`**
+
+**修改 1**：在导入行添加 `IMAGE_DIR`：
+
+```python
+# 修改前
+from scene_assets import get_scene_image_path
+
+# 修改后
+from scene_assets import get_scene_image_path, IMAGE_DIR
+```
+
+**修改 2**：在 `app.launch()` 中添加 `allowed_paths` 参数：
+
+```python
+# 修改前
+app.launch(
+    server_name="0.0.0.0",
+    server_port=7860,
+    ...
+)
+
+# 修改后
+app.launch(
+    server_name="0.0.0.0",
+    server_port=7860,
+    allowed_paths=[str(IMAGE_DIR)],  # 新增：授权图片目录
+    ...
+)
+```
+
+`allowed_paths` 接受字符串列表，Gradio 会检查请求文件是否位于列出的目录下（递归），通过验证后正常返回图片数据。
+
+---
+
+## 12. 遥测与日志系统
+
+每次玩家交互生成一条 JSONL 记录，写入 `logs/interactions/{session_id}.jsonl`。
+
+### 日志字段结构
+
+```json
+{
+  "timestamp": "2026-03-28T10:23:45.123Z",
+  "session_id": "sw-20260328-102345-ab12cd34",
+  "turn_index": 3,
+  "input_source": "text_input",       // text_input | option_click | system_opening
+  "user_input": "我想询问村长关于森林的事",
+  "nlu_result": {
+    "intent": "TALK",
+    "target": "村长老伯",
+    "parser_source": "llm"
+  },
+  "latency_ms": 842.13,
+  "nlu_latency_ms": 150.0,
+  "generation_latency_ms": 692.0,
+  "used_fallback": false,
+  "engine_mode": "merged_generation",
+  "state_changes": { "hp": -5, "gold": 0, ... },
+  "change_log": ["HP: 100 → 95", "时间: 08:00 → 08:05"],
+  "consistency_issues": [],
+  "output_text": "村长摘下烟斗，神情凝重...",
+  "post_turn_snapshot": {
+    "location": "村庄广场",
+    "player": { "hp": 95, "level": 1, ... }
+  }
+}
+```
+
+### 用途
+
+- **延迟分析**：测量 NLU 和叙事生成的各阶段耗时
+- **意图准确率**：评估 NLU 解析正确率
+- **一致性检测**：统计逻辑矛盾发生频率
+- **剧情分支分析**：分析不同选择路径的分布
+
+---
+
+## 13. 评估框架
+
+`evaluation/` 目录提供可复现的实验评估体系：
+
+### 评估维度
+
+| 测试任务 | 数据集文件 | 评估指标 |
+|---------|-----------|---------|
+| NLU 意图准确率 | `intent_accuracy.json` | Accuracy（标注输入 vs 预测意图） |
+| 状态一致性 | `consistency.json` | 一致性违规率 |
+| 生成延迟 | `latency.json` | P50/P95 延迟（毫秒） |
+| 剧情分支多样性 | `branch_divergence.json` | 相同状态不同选择→不同结果率 |
+
+### 运行评估
+
+```bash
+cd evaluation
+python run_evaluations.py --task intent     # 只跑意图识别评估
+python run_evaluations.py --task latency    # 只跑延迟评估
+python run_evaluations.py                   # 运行所有评估
+```
+
+---
+
+## 14. 项目文件结构
+
+```
+StoryWeaver/
+├── app.py                    # 入口：Gradio UI + 事件协调（2006行）
+├── state_manager.py          # 游戏状态模型与管理（2636行）
+├── story_engine.py           # AI 叙事生成引擎（4074行）
+├── nlu_engine.py             # 自然语言意图解析（431行）
+├── utils.py                  # Qwen API 封装 + JSON 工具（328行）
+├── combat_engine.py          # 战斗结算（97行）
+├── scene_assets.py           # 场景图片路径解析（31行）
+├── demo_rules.py             # 游戏规则常量与选项构建（1410行）
+├── telemetry.py              # 交互日志（81行）
+│
+├── image/                    # 场景图片（21张 PNG）
+│   ├── 村庄广场.png
+│   ├── 黑暗森林入口.png
+│   ├── 村长老伯.png
+│   └── ...（共21张）
+│
+├── evaluation/               # 评估框架
+│   ├── run_evaluations.py
+│   └── datasets/
+│       ├── intent_accuracy.json
+│       ├── consistency.json
+│       ├── latency.json
+│       └── branch_divergence.json
+│
+├── demo/
+│   ├── scenarios.json
+│   └── show_demo_checklist.py
+│
+├── logs/interactions/        # 运行时生成的 JSONL 日志
+├── requirements.txt          # Python 依赖
+├── .env.example              # 环境变量模板
+└── README.md                 # 项目概览文档
+```
+
+### 快速启动
+
+```bash
+# 1. 安装依赖
+pip install -r requirements.txt
+
+# 2. 配置 API Key
+cp .env.example .env
+# 编辑 .env，填写 QWEN_API_KEY=sk-xxxxxx
+
+# 3. 启动
+python app.py
+# 访问 http://localhost:7860
+```
+
+---
+
+*本文档由 Claude Code 生成，描述 StoryWeaver v1.0 的技术实现细节。*