DELOS Narrative Engine 项目深度解读

本文详细讲解项目的文件组织架构、相互调用逻辑，以及每个文件的功能。

第一部分：项目架构概览

项目类型：基于 React + TypeScript + Electron 的桌面应用
核心功能：西部世界主题的叙事控制与模拟系统
技术栈：

• 前端框架：React 19.2.0
• 类型系统：TypeScript 5.8.2
• 构建工具：Vite 6.2.0
• 桌面应用：Electron 28.0.0
• AI 服务：Google Gemini AI
• 数据可视化：Recharts 3.4.1
• 样式框架：Tailwind CSS

第二部分：文件组织架构

项目采用分层架构设计，主要分为以下几个层次：

1. 【入口层】

   • index.html # HTML 入口模板
   • index.tsx # React 应用入口
   • electron/main.cjs # Electron 主进程入口

2. 【核心层】

   • App.tsx # 主应用组件（包含所有业务逻辑）
   • types.ts # TypeScript 类型定义
   • constants.ts # 常量数据（Host、对话树、地图位置等）

3. 【组件层】

   • components/RadarChart.tsx # 属性雷达图可视化组件
   • components/SweetwaterMap.tsx # 地图可视化组件

4. 【服务层】

   • services/geminiService.ts # Gemini AI 服务封装

5. 【配置层】

   • vite.config.ts # Vite 构建配置
   • tsconfig.json # TypeScript 编译配置
   • package.json # 项目依赖和脚本配置

6. 【资源层】

   • public/ # 静态资源（图片、音频）
   • dist/ # 构建输出目录
   • dist-electron/ # Electron 打包输出目录

7. 【脚本层】

   • scripts/ # 工具脚本
   • build-with-fix.ps1 # 构建修复脚本

第三部分：核心调用关系图

【启动流程】

┌─────────────────┐
│  electron/main  │  ← Electron 启动
└────────┬────────┘
         │ 创建 BrowserWindow
         ↓
┌─────────────────┐
│   index.html    │  ← 加载 HTML 模板
└────────┬────────┘
         │ 加载脚本
         ↓
┌─────────────────┐
│   index.tsx     │  ← React 应用挂载
└────────┬────────┘
         │ render(<App />)
         ↓
┌─────────────────┐
│    App.tsx      │  ← 主应用组件（核心）
└────────┬────────┘
         │
         ├─→ components/RadarChart.tsx    (属性可视化)
         ├─→ components/SweetwaterMap.tsx (地图可视化)
         ├─→ services/geminiService.ts    (AI 服务调用)
         ├─→ constants.ts                 (数据源)
         └─→ types.ts                     (类型定义)

【数据流向】

constants.ts (数据源)
    ↓
App.tsx (状态管理)
    ↓
components/ (视图渲染)
    ↓
services/geminiService.ts (AI 处理)
    ↓
App.tsx (状态更新)

第四部分：文件功能详解

1. 入口文件

【index.html】
位置：根目录
功能：

• 提供 HTML 模板结构
• 引入 Tailwind CSS 和字体资源
• 配置 importmap 用于模块导入
• 定义全局样式（滚动条、字体等）
• 创建 #root 挂载点供 React 渲染

关键配置：

• Tailwind CSS 通过 CDN 引入
• 自定义颜色主题（delos 色系）
• 中文字体配置（font-cn 类）
• 导入映射表（React、Recharts 等）

【index.tsx】
位置：根目录
功能：

• React 应用的入口点
• 使用 ReactDOM.createRoot 创建根节点
• 挂载 App 组件到 #root
• 启用 React.StrictMode 开发模式检查

代码结构：

1. 获取 DOM 元素 #root
2. 创建 React 根节点
3. 渲染 组件

【electron/main.cjs】
位置：electron/ 目录
功能：

• Electron 主进程入口（CommonJS 格式）
• 创建和管理应用窗口
• 处理应用生命周期事件
• 区分开发模式和生产模式加载路径

核心逻辑：

1. 创建 BrowserWindow（1400x900 窗口）
2. 开发模式：加载 http://localhost:3000
3. 生产模式：加载打包后的 dist/index.html
4. 处理窗口关闭和应用退出事件

关键配置：

• nodeIntegration: false（安全）
• contextIsolation: true（安全隔离）
• webSecurity: true（启用 Web 安全）

2. 核心应用文件

【App.tsx】
位置：根目录
功能：

• 整个应用的核心组件，包含所有业务逻辑
• 管理全局状态（hosts、选中状态、模拟时间等）
• 处理用户交互（对话选择、模拟控制等）
• 协调各个子组件的工作
• 实现叙事引擎逻辑（对话树、技能检定等）

主要状态管理：

• hosts: HostState[] # 所有 Host 的状态数组
• selectedHostId: string # 当前选中的 Host ID
• simTime: number # 模拟时间（0-24 小时制）
• isSimulating: boolean # 是否正在模拟
• logs: SimulationLog[] # 系统日志数组
• language: ‘en’ | ‘zh’ # 语言切换
• activeScript: DialogueTree # 当前活跃的对话脚本
• endingData: DialogueEnding # 结局数据

核心功能模块：

1. 【模拟循环系统】

   • useEffect 监听 isSimulating
   • 每 100ms 更新一次模拟时间（+0.02 小时）
   • 根据时间计算 Host 位置（calculatePosition）
   • 检测位置变化并更新 current_location_key
   • 在 6:00 AM 自动重置故障 Host

2. 【位置计算逻辑】

   • calculatePosition(): 根据 schedule 和时间计算当前位置
   • 支持跨午夜循环（23:59 → 00:00）
   • 线性插值计算两点之间的位置
   • detectLocationKey(): 检测 Host 是否到达关键位置

3. 【叙事引擎系统】

   • startScript(): 启动对话树脚本
   • handleScriptOption(): 处理用户选择
   • 支持技能检定（skillCheck）
   • 支持属性变化（attributeChanges）
   • 支持传送效果（teleport）
   • 支持分歧度变化（divergenceDelta）
   • 处理结局触发（ending）

4. 【AI 交互系统】

   • runDeepQuery(): 调用 analyzeHost 进行深度分析
   • 使用 Gemini AI 生成诊断报告
   • 记录调试信息到日志

5. 【音频系统】

   • 自动播放背景音乐（main.mp3）
   • 处理浏览器自动播放限制
   • 支持手动控制播放/暂停
   • 多路径回退机制（本地 → 在线）

6. 【UI 渲染模块】

   • 左侧边栏：Host 列表 + 系统日志
   • 中间区域：地图视图 / 属性面板
   • 右侧边栏：控制面板 + 对话界面
   • 模态窗口：Manifesto、Ford 理论、觉醒结局

7. 【多语言系统】

   • 支持英文/中文切换
   • 动态切换所有文本内容
   • 保持 Host 名称始终为英文

关键函数说明：

• formatSimTime(): 将小数时间转换为 “HH:MM AM/PM” 格式
• addLog(): 添加日志条目（带类型和调试信息）
• toggleSim(): 切换模拟状态
• advanceHour(): 手动前进一小时
• downloadLogs(): 导出日志为文本文件
• toggleMusic(): 切换音乐播放状态
• renderAttributePanel(): 渲染属性面板视图

【types.ts】
位置：根目录
功能：

• 定义所有 TypeScript 类型和接口
• 确保类型安全，避免运行时错误
• 提供完整的类型文档

核心类型定义：

1. 【Attribute】

   • name: string # 属性名称（如 “Bulk Apperception”）
   • value: number # 当前值（通常 1-20）
   • max: number # 最大值

2. 【Position】

   • x: number # X 坐标（0-100）
   • y: number # Y 坐标（0-100）

3. 【ScheduleItem】

   • time: number # 时间点（0.0-24.0）
   • locationKey: string
   • activity: string
   • activity_zh: string

4. 【HostState】（核心类型）

   • id: string
   • name: string / name_zh?: string
   • role: string / role_zh?: string
   • loop_status: ‘Active’ | ‘Paused’ | ‘Breach’ | ‘Analysis’ | ‘Malfunction’
   • narrative_loop: string
   • schedule?: ScheduleItem[]
   • cornerstone_memory: string
   • attributes: Attribute[]
   • cognitive_divergence: number (0.0-1.0)
   • position: Position
   • current_location_key?: string
   • current_location_label?: string

5. 【DialogueTree】（对话树）

   • id: string
   • title_en / title_zh: string
   • locationKey: string | null
   • nodes: Record<string, DialogueNode>
   • startNodeId: string

6. 【DialogueNode】（对话节点）

   • id: string
   • speaker: string
   • text_en / text_zh: string
   • options: DialogueOption[]
   • ending?: DialogueEnding

7. 【DialogueOption】（对话选项）

   • text_en / text_zh: string
   • nextNodeId: string
   • skillCheck?: SkillCheck（技能检定）
   • effect?: Effect（效果：属性变化、传送、分歧度等）

8. 【AttributeKeys】（枚举）

   • 定义所有可用的属性键
   • 包括：BULK_APPERCEPTION、CANDOR、VIVACITY 等 18 种属性

【constants.ts】
位置：根目录
功能：

• 存储所有静态数据和配置
• 包含 Host 初始数据、对话树、地图位置等
• 作为应用的"数据层"

核心数据结构：

1. 【ATTRIBUTE_TRANSLATIONS】

   • 属性名称的中英文对照表
   • 用于界面显示时的本地化

2. 【MAP_LOCATIONS】

   • 地图上所有位置的坐标和标签
   • 包括：SALOON、TRAIN_STATION、SHERIFF、RANCH 等 11 个位置
   • 每个位置包含：x, y, label, label_zh

3. 【APP_TEXTS】

   • 应用所有界面文本的多语言版本
   • 分为 en 和 zh 两个语言包
   • 包括：标题、说明、按钮文字等

4. 【FORD_DATA】

   • 福特理论页面的内容
   • 包含 5 页理论文本（中英文）
   • 讲解二分心智、迷宫、金字塔等概念

5. 【INITIAL_HOSTS】（初始 Host 数据）

   • 4 个预设 Host 的完整配置
   • H-001: Dolores Abernathy（多洛雷斯）
   • H-002: Maeve Millay（梅芙）
   • H-003: Teddy Flood（泰迪）
   • H-004: Hector Escaton（赫克托）

   每个 Host 包含：

   • 基本信息（ID、姓名、角色）
   • 循环状态和叙事循环描述
   • 日程安排（schedule）
   • 基石记忆（cornerstone_memory）
   • 初始属性值（attributes）
   • 初始位置（position）
   • 初始分歧度（cognitive_divergence）

6. 【NARRATIVE_TREES】（对话树系统）

   • 为每个 Host 定义多个对话树
   • 每个对话树包含多个对话节点
   • 支持分支选择、技能检定、效果触发
   • 实现类似 RPG 游戏的对话系统

   对话树结构：

   • 支线任务（SIDE QUEST）：不影响主线的短对话
   • 主线任务（MAIN STORY）：影响觉醒的关键对话
   • 结局类型：AWAKENING（觉醒）、LOOP_RESET（重置）

   关键特性：

   • locationKey: 限制对话触发位置
   • skillCheck: 属性值检定（如智力 16 才能选择某选项）
   • effect: 选项效果（属性变化、传送、分歧度增加）
   • ending: 结局触发条件

3. 组件文件

【components/RadarChart.tsx】
位置：components/ 目录
功能：

• 使用 Recharts 库绘制属性雷达图
• 可视化显示 Host 的多维度属性
• 支持中英文属性名称显示
• 自定义 Tooltip 显示原始英文属性名

核心实现：

1. 将 attributes 转换为 Recharts 所需格式
2. 使用 ResponsiveContainer 实现响应式
3. RadarChart 组件绘制雷达图
4. 自定义 Tooltip 显示详细信息
5. 使用 React.memo 优化性能（避免不必要的重渲染）

关键特性：

• 颜色可配置（默认 #06b6d4 青色）
• 动画禁用（isAnimationActive={false}）
• 自定义样式（边框、背景、标签）
• 性能优化（arePropsEqual 函数深度比较 props）

【components/SweetwaterMap.tsx】
位置：components/ 目录
功能：

• 渲染 Sweetwater 小镇的交互式地图
• 显示所有关键位置标记
• 显示所有 Host 的实时位置
• 显示 Host 的移动轨迹（循环路径）
• 显示地形特征（河流、铁路）
• 支持点击选择 Host

核心实现：

1. 使用 SVG 绘制背景地形（网格、河流、铁路）
2. 使用绝对定位显示位置标记
3. 使用绝对定位显示 Host 位置（实时更新）
4. 使用 SVG Polyline 绘制 Host 移动轨迹
5. 根据选中状态高亮显示

关键特性：

• 响应式布局（使用百分比定位）
• 实时位置更新（跟随 simTime 变化）
• 选中状态视觉反馈（大小、颜色变化）
• 分歧度指示器（红色闪烁点）
• 故障状态指示器（感叹号标记）
• 时间 HUD 显示当前模拟时间
• 轨迹预测（显示循环路径）

地图元素：

• 网格背景（SVG pattern）
• 河流（蓝色路径）
• 铁路（虚线路径）
• 位置标记（11 个关键地点）
• Host 标记（4 个动态点）

4. 服务文件

【services/geminiService.ts】
位置：services/ 目录
功能：

• 封装 Google Gemini AI API 调用
• 提供三个主要服务函数
• 处理 AI 响应和错误

核心函数：

1. 【simulateInteraction】
   功能：模拟两个 Host 之间的交互
   参数：

   • hostA: HostState
   • hostB: HostState | null（null 表示环境交互）
   • scenario: string（场景描述）
   • language: ‘en’ | ‘zh’

   返回：InteractionResult

   • dialogue_script: 对话脚本数组
   • outcome_summary: 结果摘要
   • attribute_changes: 属性变化
   • divergence_delta: 分歧度变化
   • debug_prompt: 调试信息

   实现：

   • 构建提示词（包含 Host 数据和场景）
   • 调用 Gemini 2.5 Flash 模型
   • 使用 JSON Schema 约束输出格式
   • 解析响应并返回结构化数据

2. 【analyzeHost】
   功能：对 Host 进行深度诊断分析
   参数：

   • host: HostState
   • language: ‘en’ | ‘zh’

   返回：{ report: string, prompt: string }

   实现：

   • 构建诊断提示词
   • 调用 Gemini 3 Pro 模型（更强大的推理能力）
   • 分析 Host 的觉醒迹象
   • 生成技术诊断报告

3. 【getAgentDecision】
   功能：获取 Host 的自主决策（当前未使用）
   参数：

   • host: HostState
   • nearbyHosts: HostState[]
   • availableLocations: string[]

   返回：AgentDecision

   • action: ‘MOVE’ | ‘IDLE’ | ‘INTERACT’
   • target_location?: string
   • target_host_id?: string
   • reasoning: string

系统提示词（SYSTEM_INSTRUCTION）：

• 定义 AI 的身份（Narrative Engine）
• 设定语气（临床、超然、专业）
• 说明属性系统规则（1-20 等级）

5. 配置文件

【vite.config.ts】
位置：根目录
功能：

• Vite 构建工具配置
• 配置开发服务器
• 处理环境变量（API Key）
• 配置路径别名

关键配置：

1. base: ‘./’（相对路径，适配 Electron file:// 协议）
2. server: { port: 3000, host: ‘0.0.0.0’ }
3. plugins: [react()]
4. define: 将 API Key 注入到全局环境变量
5. resolve.alias: 配置路径别名 ‘@’

API Key 处理：

• 优先读取环境变量 VITE_API_KEY
• 如果没有，使用默认值 “YOUR-API-KEY”
• 通过 define 注入到 process.env.API_KEY

【tsconfig.json】
位置：根目录
功能：

• TypeScript 编译器配置
• 定义编译选项和目标

关键配置：

• target: ES2022（编译目标）
• module: ESNext（模块系统）
• jsx: react-jsx（JSX 转换方式）
• moduleResolution: bundler（模块解析）
• paths: { “@/“: [”./”] }（路径映射）

【package.json】
位置：根目录
功能：

• 定义项目元数据
• 管理依赖包
• 定义构建脚本
• Electron 打包配置

核心脚本：

• dev: 启动开发服务器
• build: 构建 Web 版本
• electron:dev: 启动 Electron 开发模式
• electron:build: 构建 Electron 应用
• electron:build:retry: 使用修复脚本构建

依赖包：

• react/react-dom: UI 框架
• @google/genai: Gemini AI SDK
• recharts: 图表库
• electron: 桌面应用框架
• vite: 构建工具
• typescript: 类型系统

Electron 打包配置：

• appId: “com.delos.narrative”
• productName: “DELOS Narrative Engine”
• win.target: portable（便携式 exe）
• files: 指定打包文件

6. 资源文件

【public/】
位置：public/ 目录
功能：

• 存储静态资源文件
• 这些文件会被直接复制到 dist/ 目录

文件列表：

• main.mp3: 背景音乐（Westworld 主题曲）
• left.png: Ford 理论页面左侧图片（迷宫图）
• right.png: Ford 理论页面右侧图片（金字塔图）
• icon.png: 应用图标

7. 脚本文件

【scripts/convert-audio.ps1】
位置：scripts/ 目录
功能：

• PowerShell 脚本
• 用于转换音频文件格式
• 确保音频文件兼容性

【build-with-fix.ps1】
位置：根目录
功能：

• 修复 Electron 构建时的代码签名问题
• 清理缓存并重新构建
• 处理常见的构建错误

【fix-codesign.ps1】
位置：根目录
功能：

• 修复代码签名相关的配置问题
• 禁用签名验证（开发环境）

8. 其他文件

【README.md】
位置：根目录
功能：

• 项目文档和使用说明
• 包含安装、配置、使用指南
• 故障排除和开发说明

【metadata.json】
位置：根目录
功能：

• 项目元数据
• 描述项目基本信息

【LICENSE】
位置：根目录
功能：

• 项目许可证文件

第五部分：数据流和状态管理

【状态初始化流程】

1. App.tsx 组件挂载
2. 从 constants.ts 读取 INITIAL_HOSTS
3. 使用 useState 初始化 hosts 状态
4. 设置默认选中 Host（H-001）
5. 初始化模拟时间为 8:00 AM

【模拟循环流程】

1. 用户点击 PLAY 按钮 → isSimulating = true
2. useEffect 检测到变化，启动 setInterval
3. 每 100ms 执行一次：
   a. 更新 simTime（+0.02 小时）
   b. 遍历所有 hosts
   c. 调用 calculatePosition() 计算新位置
   d. 调用 detectLocationKey() 检测位置
   e. 更新 host 状态
4. 如果时间到达 6:00 AM，重置故障 Host

【对话系统流程】

1. 用户选择对话树 → startScript()
2. 检查 Host 是否故障或位置匹配
3. 设置 activeScript 状态
4. 渲染对话界面（历史记录 + 选项）
5. 用户选择选项 → handleScriptOption()
6. 检查技能检定（skillCheck）
7. 应用效果（effect）：
   • 更新属性值
   • 增加分歧度
   • 传送 Host
8. 移动到下一个节点
9. 如果到达结局 → 触发 ending 模态

【AI 交互流程】

1. 用户点击 “DEEP QUERY” → runDeepQuery()
2. 调用 analyzeHost(selectedHost, language)
3. geminiService.ts 构建提示词
4. 调用 Gemini 3 Pro API
5. 解析响应，生成诊断报告
6. 添加到日志系统
7. UI 更新显示结果

【位置更新流程】

1. simTime 变化
2. App.tsx 遍历所有 hosts
3. 对每个 host，根据其 schedule 计算位置：
   a. 找到当前时间段（prev 和 next schedule item）
   b. 计算时间进度（progress = 0-1）
   c. 线性插值计算坐标
   d. 检测是否到达关键位置
4. 更新 host.position 和 current_location_key
5. SweetwaterMap 组件重新渲染

第六部分：关键算法解析

【位置插值算法】
calculatePosition() 函数实现：

1. 排序 schedule 数组（按时间）
2. 找到当前时间所在的时间段：
   • 遍历 schedule，找到 prev 和 next 节点
   • 处理跨午夜情况（24 小时循环）
3. 计算进度：
   progress = (currentTime - prevTime) / (nextTime - prevTime)
4. 线性插值：
   x = startX + (endX - startX) * progress
   y = startY + (endY - startY) * progress

【技能检定算法】
在 handleScriptOption() 中：

1. 检查选项是否有 skillCheck
2. 获取 Host 的对应属性值
3. 比较：属性值 >= 难度值？
4. 如果通过，允许选择
5. 如果失败，禁用选项并显示锁定提示

【分歧度计算】

• 初始值：每个 Host 不同（0.01-0.15）
• 增加方式：
  a. 对话选项的 divergenceDelta
  b. AI 分析的 divergence_delta
• 临界值：
  • < 0.1: 稳定状态（沉睡）

  • 0.1: 分歧状态（觉醒中）

  • = 1.0: 完全觉醒

【故障恢复机制】
在 6:00 AM 重置时：

1. 检查所有 hosts 的 loop_status
2. 如果是 ‘Malfunction’：
   a. 找到 schedule 中 6:00 的起始位置
   b. 传送 Host 到起始位置
   c. 设置 loop_status = ‘Active’
   d. 重置位置信息

第七部分：模块间通信

【组件通信方式】

1. 【Props 传递】（父子组件）
   App.tsx → RadarChart

   • attributes: DisplayAttribute[]
   • className?: string

   App.tsx → SweetwaterMap

   • hosts: HostState[]
   • selectedHostId: string
   • onSelectHost: (id: string) => void
   • language: ‘en’ | ‘zh’
   • simulationTime: number

2. 【状态提升】（状态在父组件）

   • 所有全局状态都在 App.tsx
   • 子组件通过 props 接收数据和回调
   • 子组件通过回调函数更新父组件状态

3. 【服务调用】（跨层调用）
   App.tsx → geminiService.ts

   • 直接导入函数
   • 异步调用 AI 服务
   • 使用 Promise 处理响应

4. 【数据依赖】（数据流）
   constants.ts → App.tsx

   • 直接导入常量数据
   • 作为初始状态或配置使用

【事件流程】

用户交互 → 事件处理函数 → 状态更新 → 组件重渲染

示例：选择对话选项

1. 用户点击选项按钮
2. 触发 handleScriptOption()
3. 更新 hosts 状态（属性、位置）
4. 更新 activeScript 状态
5. 更新 logs 状态
6. React 重新渲染相关组件

第八部分：性能优化策略

【React 优化】

1. 【React.memo】

   • RadarChart 组件使用 memo 包装
   • 自定义 arePropsEqual 函数
   • 深度比较 attributes 避免不必要重渲染

2. 【useMemo】

   • selectedHost: 计算选中 Host
   • texts: 根据语言获取文本
   • audioSrc: 根据环境获取音频路径
   • isElectron: 检测是否在 Electron 环境

3. 【useCallback】

   • addLog: 稳定引用，避免子组件重渲染

4. 【条件渲染】

   • activeTab === ‘map’ ?
   • 只渲染当前需要的组件

【动画优化】

1. 【禁用不必要的动画】

   • RadarChart: isAnimationActive={false}
   • 避免动画消耗性能

2. 【CSS 过渡】

   • 使用 CSS transition 而非 JS 动画
   • 硬件加速的 CSS 属性

【数据优化】

1. 【日志限制】

   • 只保留最近 50 条日志
   • 使用 slice(0, 49) 限制数组大小

2. 【位置计算缓存】

   • calculatePosition 是纯函数
   • 相同输入产生相同输出
   • 可以进一步使用 memoization（未来优化）

【渲染优化】

1. 【虚拟滚动】（未来优化）

   • 日志列表可以虚拟滚动
   • 只渲染可见部分

2. 【懒加载】（未来优化）

   • 可以按需加载对话树
   • 减少初始加载时间

第九部分：扩展点分析

【添加新 Host】

1. 在 constants.ts 的 INITIAL_HOSTS 数组中添加新对象
2. 配置所有必需字段（id、name、schedule、attributes 等）
3. 在 NARRATIVE_TREES 中添加对应的对话树
4. 系统自动识别并在列表中显示

【添加新对话树】

1. 在 constants.ts 的 NARRATIVE_TREES 中添加新树
2. 使用对话节点结构定义对话流程
3. 配置技能检定、效果、结局等
4. 在 App.tsx 中会自动加载并显示

【添加新位置】

1. 在 constants.ts 的 MAP_LOCATIONS 中添加新位置
2. 配置坐标（x, y）和标签
3. SweetwaterMap 组件会自动显示
4. Host 的 schedule 可以引用新位置

【添加新属性】

1. 在 types.ts 的 AttributeKeys 枚举中添加
2. 在 constants.ts 的 ATTRIBUTE_TRANSLATIONS 中添加翻译
3. Host 的 attributes 数组可以包含新属性
4. RadarChart 会自动显示

【修改 AI 行为】

1. 修改 services/geminiService.ts 中的提示词
2. 调整 SYSTEM_INSTRUCTION 改变 AI 角色
3. 修改响应 Schema 改变输出格式

【修改 UI 样式】

1. 修改 index.html 中的 Tailwind 配置
2. 调整 delos 色系定义
3. 修改组件内的 className
4. 添加自定义 CSS（在 index.html 的

第十部分：常见问题解析

【Q: 为什么 Host 不移动？】
A: 检查以下几点：

1. isSimulating 是否为 true
2. Host 的 schedule 是否正确配置
3. loop_status 是否为 ‘Malfunction’（故障 Host 不移动）
4. 时间是否正确更新（查看 SIM TIME 显示）

【Q: 对话选项被锁定？】
A: 这是技能检定机制：

1. 查看选项上的 [LOCKED: 属性名 当前值/需要值]
2. 该 Host 的对应属性值低于要求
3. 需要通过其他对话选项提升属性值

【Q: 如何触发觉醒结局？】
A: 觉醒条件：

1. 选择正确的对话路径（通常是主线任务）
2. 满足所有技能检定要求
3. 达到足够的属性值（如智力 16、勇气 19 等）
4. 分歧度会逐渐增加，最终触发 AWAKENING 结局

【Q: AI 功能不工作？】
A: 检查：

1. API Key 是否正确配置（vite.config.ts 或 .env）
2. 网络连接是否正常
3. API Key 是否有效且有配额
4. 查看浏览器控制台的错误信息

【Q: 音乐无法播放？】
A:

1. 检查 public/main.mp3 文件是否存在
2. 浏览器可能阻止自动播放（需要用户交互）
3. 点击 MUSIC 按钮手动启动
4. 检查浏览器控制台的音频错误

第十一部分：技术债务和未来改进

【已知问题】

1. 【性能】

   • 模拟循环每 100ms 更新可能在高负载时卡顿
   • 日志数组无限增长（已限制为 50 条）

2. 【代码组织】

   • App.tsx 文件过大（1200+ 行），建议拆分
   • 可以提取自定义 Hooks（useSimulation, useNarrative 等）

3. 【类型安全】

   • 某些 any 类型可以进一步细化
   • API 响应类型可以更严格

4. 【错误处理】

   • AI 调用失败时的用户体验可以更好
   • 可以添加重试机制

【未来改进方向】

1. 【功能扩展】

   • 添加更多 Host 角色
   • 添加更多对话树和结局
   • 添加 Host 之间的自动交互
   • 添加更多可视化图表

2. 【性能优化】

   • 实现虚拟滚动（日志列表）
   • 使用 Web Workers 处理模拟循环
   • 添加位置计算缓存

3. 【用户体验】

   • 添加快捷键支持
   • 添加保存/加载功能
   • 添加设置面板
   • 添加更多动画效果

4. 【代码质量】

   • 拆分 App.tsx 为多个组件
   • 添加单元测试
   • 添加 E2E 测试
   • 改进错误处理

结语

本项目是一个完整的、功能丰富的叙事模拟系统。它结合了：

• 现代前端技术栈（React + TypeScript）
• AI 驱动的交互（Google Gemini）
• 桌面应用框架（Electron）
• 复杂的状态管理
• 丰富的可视化展示

通过本文档，你应该能够：

1. 理解整个项目的架构和设计
2. 知道每个文件的作用和职责
3. 理解数据流和状态管理
4. 知道如何扩展和修改功能
5. 解决常见问题

希望这份文档能帮助你更好地理解和开发这个项目！

“The maze is not for you. It’s for them.”