chore:首次提交

docs/ARCHITECTURE.md

@@ -0,0 +1,145 @@
+# OES-WEB 架构文档
+
+## 系统架构图
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   UI Layer (HTML/CSS)                │
+│  HUD │ Inventory │ Dialogue │ Skills │ Map │ Mods   │
+└──────────────────────┬──────────────────────────────┘
+                       │ EventBus
+┌──────────────────────┴──────────────────────────────┐
+│                Game Logic Layer (TypeScript)          │
+│  Systems: Combat │ Magic │ Quest │ Alchemy │ ...     │
+│  Components: Health │ Skills │ Inventory │ ...       │
+│  Entities: Player │ NPC │ Enemy │ Corpse │ Item      │
+└──────────────────────┬──────────────────────────────┘
+                       │
+┌──────────────────────┴──────────────────────────────┐
+│               Core Engine Layer (Phaser 3)           │
+│  Rendering │ Physics │ Input │ Audio │ Scene Mgmt   │
+└──────────────────────┬──────────────────────────────┘
+                       │
+┌──────────────────────┴──────────────────────────────┐
+│                Data Layer (JSON + IndexedDB)         │
+│  Base Data │ DataRegistry │ Save Data │ Mod Data      │
+└─────────────────────────────────────────────────────┘
+```
+
+## 核心模块
+
+### GameManager (单例)
+- 初始化 Phaser 游戏实例
+- 注册和管理系统
+- 管理主循环 tick 顺序
+
+### EventBus (单例)
+- 发布/订阅事件系统
+- 系统间解耦通信
+- 所有交互通过事件，不直接调用
+
+### EntityManager (单例)
+- 实体生命周期管理
+- 组件存储和查询
+- 实体工厂方法
+
+## 系统执行顺序
+
+每帧按以下顺序执行:
+
+```
+1.  InputSystem          ← 读取玩家输入
+2.  AIControlSystem      ← NPC/敌人 AI 决策
+3.  PhysicsSystem        ← 移动、碰撞检测
+4.  CombatSystem         ← 伤害计算、命中检测
+5.  MagicSystem          ← 法术施放、效果
+6.  StealthSystem        ← 检测等级、潜行倍率
+7.  StatusEffectSystem   ← Buff/Debuff/毒药
+8.  InventorySystem      ← 重量、物品管理
+9.  CorpseSystem         ← 尸体状态、搜刮
+10. ItemInteractionSystem ← 物品拾取、容器
+11. QuestSystem          ← 任务状态更新
+12. DialogueSystem       ← NPC 对话
+13. AnimationSystem      ← 精灵动画
+14. SpawnSystem          ← 随机遭遇、刷新
+15. ModHookSystem        ← Mod 事件钩子
+16. SaveSystem           ← 自动存档
+```
+
+## 数据流
+
+```
+Player Input
+    ↓
+EventBus.emit('player:attack', { target, damage })
+    ↓
+CombatSystem 处理事件
+    ↓
+EventBus.emit('entity:damaged', { entity, amount })
+    ↓
+HealthSystem 更新生命值
+    ↓
+EventBus.emit('entity:died', { entity })
+    ↓
+CorpseSystem 生成尸体
+LootSystem 生成掉落
+QuestSystem 检查任务目标
+```
+
+## 组件设计
+
+所有组件必须有 `type` 字段:
+
+```typescript
+interface Component {
+  type: string;
+  [key: string]: any;
+}
+
+// 示例
+{ type: 'health', current: 100, max: 100 }
+{ type: 'position', x: 100, y: 200 }
+{ type: 'combat', attackPower: 10, defense: 5 }
+```
+
+## Mod 系统架构
+
+```
+Base Game Data (src/data/*.json)
+    ↓
+ModValidator (manifest + data schema guard)
+    ↓
+ModResolver (dependency order + priority merge + conflict report)
+    ↓
+Resolved Mod Data
+    ↓
+DataRegistry rebuilds runtime snapshot
+    ↓
+Game Systems read DataRegistry
+```
+
+### Mod v1 边界
+
+- 当前只支持 JSON 数据 Mod: `manifest + data`
+- 支持数据域: `items / enemies / npcs / quests / recipes / spells / skills / perks / zones`
+- 禁止执行玩家导入脚本；旧脚本入口只保留为禁用兼容桩
+- 加载顺序: 依赖先于依赖方，同层按 `priority` 从小到大合并，后合并者覆盖前者
+- 冲突: 多个启用 Mod 修改同一 `domain.id` 时记录冲突，最终以后合并者为准
+- 运行时数据入口: 新系统应通过 `DataRegistry` 读取物品、敌人、掉落、任务等内容，不再在系统内硬编码内容表
+
+## 存档结构
+
+```json
+{
+  "version": 1,
+  "timestamp": 1234567890,
+  "playTime": 3600,
+  "character": { "name", "race", "level", "skills", "perks" },
+  "inventory": { "items", "gold", "equipped" },
+  "worldState": { "discoveredLocations", "clearedDungeons" },
+  "quests": { "active", "completed", "failed" },
+  "factions": { "factionId": "reputation" },
+  "npcs": { "npcId": "state" },
+  "mapStates": { "mapId": "entities" }
+}
+```

docs/GDD.md

@@ -0,0 +1,158 @@
+# OES-WEB 游戏设计文档 (GDD)
+
+> 上古卷轴风格 Web RPG - 用 AI 工具开发，系统完整性优先，Mod 生态为核心
+
+---
+
+## 1. 核心定位
+
+- **类型**: 2D 俯视角开放世界 RPG
+- **平台**: Web 浏览器 (Chrome/Firefox/Edge)
+- **风格**: 上古卷轴 (Elder Scrolls) 系统复刻
+- **美术**: 极简像素/色块 (后期可美化)
+- **特色**: 完整 RPG 系统 + Mod 生态
+
+## 2. 核心循环
+
+```
+探索世界 → 遭遇敌人/发现地点 → 战斗/对话/制作 → 获得奖励 → 角色成长 → 探索更远
+```
+
+## 3. 系统清单
+
+### 3.1 角色系统
+- [x] 10 个可玩种族 (Nord/Dunmer/Altmer/Argonian/Khajiit/Breton/Imperial/Redguard/Orc/Bosmer)
+- [ ] 3 大属性: 生命/魔力/耐力
+- [ ] 18 项技能 (战斗6/魔法6/潜行6)
+- [ ] ~251 个天赋 (Perk), 18 棵天赋树
+- [ ] 升级系统: 每 10 级技能 = 1 角色等级
+- [ ] 传奇技能系统
+
+### 3.2 战斗系统
+- [ ] 实时动作战斗 (俯视角)
+- [ ] 单手武器: 剑/锤/斧/匕首
+- [ ] 双手武器: 大剑/战锤/战斧
+- [ ] 盾牌格挡和猛击
+- [ ] 双持武器
+- [ ] 强力攻击 (消耗耐力)
+- [ ] 弓箭远程战斗
+- [ ] 潜行攻击倍率 (匕首最高 15x)
+- [ ] 检测系统: 隐藏/警觉/发现/搜索
+
+### 3.3 魔法系统
+- [ ] 5 大魔法学派: 毁灭/恢复/幻术/召唤/变化
+- [ ] 龙吼系统: 20 个龙吼, 每个 3 个字
+- [ ] 魔力消耗和施法
+
+### 3.4 炼金系统
+- [ ] 40+ 种材料, 每种 4 个可发现效果
+- [ ] 2-3 种材料组合制作药水/毒药
+- [ ] 毒药涂抹在武器上
+
+### 3.5 附魔系统
+- [ ] 分解物品学习附魔
+- [ ] 灵魂石 (6 级: 微小→大→黑色)
+- [ ] 武器/护甲附魔
+
+### 3.6 锻造系统
+- [ ] 锻造台制作武器护甲
+- [ ] 砂轮/工作台强化
+- [ ] 材料等级: 铁→钢→矮人→兽人→乌木→魔族→龙
+
+### 3.7 任务系统
+- [ ] 主线任务 (~20 个)
+- [ ] 4 个公会任务线 (战士/盗贼/黑暗兄弟会/法师学院)
+- [ ] 15 个魔神任务
+- [ ] 辐射任务 (程序生成)
+
+### 3.8 NPC 系统
+- [ ] 分支对话树, 技能检定
+- [ ] 60+ 商人, 50+ 随从
+- [ ] 结婚系统
+- [ ] 阵营声望
+
+### 3.9 世界探索
+- [ ] 8 个主要城市
+- [ ] 200+ 地牢
+- [ ] 随机遭遇
+- [ ] 快速旅行
+
+### 3.10 背包/装备
+- [ ] 重量系统 (基础负重 300)
+- [ ] 8+ 装备槽位
+- [ ] 等级化掉落
+
+### 3.11 经济系统
+- [ ] 金币货币 (塞普汀)
+- [ ] 商人金池和补货
+
+### 3.12 站立之石
+- [ ] 13 个站立之石, 每次激活一个
+
+### 3.13 狼人/吸血鬼
+- [ ] 狼人变形 + 天赋树
+- [ ] 吸血鬼阶段 + 喂食机制
+
+### 3.14 尸体系统
+- [ ] 状态机: 活着→尸体→已搜刮→灰烬/销毁
+- [ ] 搜刮容器, "搜索 [名字]" 提示
+- [ ] 复生法术梯度 (25级→100级)
+- [ ] 狼人/吸血鬼喂食
+
+### 3.15 物品交互系统
+- [ ] 地面物品拾取, 悬停提示
+- [ ] 容器系统 (宝箱/桶/瓮)
+- [ ] 开锁小游戏 (5 级难度)
+- [ ] 重量/负重
+- [ ] 收藏/快捷栏 (F 收藏, 1-9 快捷)
+- [ ] 偷窃/赏金系统
+- [ ] 书籍阅读
+- [ ] 烹饪系统
+
+### 3.16 Mod 系统 (核心)
+- [x] JSON 数据覆盖, 深度合并
+- [x] 加载优先级系统
+- [ ] 插件清单 (manifest.json)
+- [ ] 事件钩子 API
+- [ ] Mod 管理器 UI
+- [x] 依赖检查和冲突检测
+- [x] 基础 Schema 验证
+- [ ] Mod 导入/导出
+
+## 4. 操控方式
+
+| 按键 | 功能 |
+|------|------|
+| WASD / 方向键 | 移动 |
+| E | 交互/攻击 |
+| F | 收藏物品 |
+| 1-9 | 快捷栏 |
+| Tab/Esc | 暂停菜单 |
+| I | 背包 |
+| M | 地图 |
+| J | 任务日志 |
+
+## 5. 技术约束
+
+- 60fps 目标 (中端硬件)
+- 最大 100 个活跃实体
+- 存档压缩后 < 500KB
+- 初始加载 < 5MB
+- 现代浏览器 (Chrome/Firefox/Edge/Safari)
+
+## 6. 开发阶段
+
+| 阶段 | 内容 | 状态 |
+|------|------|------|
+| Phase 0 | 项目脚手架 | ✅ 完成 |
+| Phase 1 | 核心角色系统 | 🔄 进行中 |
+| Phase 2 | 基础战斗 | ⏳ 待开始 |
+| Phase 3 | 探索与世界 | ⏳ |
+| Phase 4 | NPC 与对话 | ⏳ |
+| Phase 5 | 扩展战斗与魔法 | ⏳ |
+| Phase 6 | 制作系统 | ⏳ |
+| Phase 7 | 任务系统 | ⏳ |
+| Phase 8 | 高级系统 | ⏳ |
+| Phase 8.5 | Mod 系统 | ⏳ |
+| Phase 9 | 内容与打磨 | ⏳ |
+| Phase 10 | 最终集成 | ⏳ |

docs/adr/001-entity-component-pattern.md

@@ -0,0 +1,33 @@
+# ADR-001: 使用 Entity-Component 模式
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+需要一个管理游戏对象的架构，要求:
+- 支持 50+ 个并发实体
+- 轻松添加新实体类型，无需修改核心系统
+- 高效查询特定组件组合的实体
+- 解耦物理、渲染和 AI 逻辑
+
+## Decision
+使用 Entity-Component (EC) 模式，不用完整 ECS 框架。
+
+- 实体是唯一 ID (字符串)
+- 组件是纯数据对象，必须有 `type` 字段
+- 系统遍历组件数组操作匹配的实体
+- EventBus 处理系统间通信
+
+选择此方案而非:
+- 继承层次 (太僵化，钻石问题)
+- 完整 ECS 库 (增加依赖，复杂度超出需求)
+- 扁平对象数组 (大数据量缓存不友好)
+
+## Consequences
+- 添加新实体类型只需定义组件 (无需修改类)
+- 系统可以独立开发和测试
+- 需要自己编写组件存储和查询逻辑
+- 实体数量在 200+ 时可能需要优化

docs/adr/002-2d-topdown-rendering.md

@@ -0,0 +1,33 @@
+# ADR-002: 使用 2D 俯视角渲染
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+需要选择渲染方式，要求:
+- 浏览器原生支持
+- AI 工具可以生成素材
+- 开发速度快
+- 能展示所有 RPG 系统
+
+## Decision
+使用 2D 俯视角 (类经典塞尔达/早期最终幻想)。
+
+- Phaser 3 + Arcade Physics
+- 32x32 像素 tile 地图
+- 极简色块/简单像素美术
+- HTML/CSS 覆盖层处理 UI
+
+选择此方案而非:
+- 3D WebGL (开发周期太长，AI 难以生成 3D 模型)
+- 2D 横版 (不适合开放世界探索)
+- 纯 HTML UI (失去游戏世界沉浸感)
+
+## Consequences
+- 开发速度快，可以专注系统完整性
+- AI 可以生成 2D 像素美术
+- 性能良好，中端硬件可达 60fps
+- 视觉表现简单，后期可美化

docs/adr/003-json-mod-system.md

@@ -0,0 +1,34 @@
+# ADR-003: 使用 JSON 数据的 Mod 系统
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+需要实现 Mod 生态系统，要求:
+- 玩家可以制作和分享 Mod
+- Mod 可以添加新内容和修改现有内容
+- 加载顺序可控制
+- 冲突可以检测和解决
+
+## Decision
+使用 JSON 数据文件作为 Mod 格式。
+
+- Mod 格式: JSON 数据 + manifest.json 清单
+- 加载方式: 深度合并，后加载覆盖先加载
+- 优先级: 数字越小越先加载
+- 事件钩子: GameEvents.on() 让 Mod 响应游戏事件
+- 验证: JSON Schema 确保数据结构合规
+
+选择此方案而非:
+- 二进制格式 (不可读，难以调试)
+- 脚本语言 (安全风险，性能问题)
+- 文件系统覆盖 (浏览器限制)
+
+## Consequences
+- Mod 格式简单易懂，玩家容易上手
+- JSON 可以被任何文本编辑器修改
+- 深度合并可能产生意外覆盖，需要冲突检测
+- 运行时加载性能良好

docs/adr/004-json-only-mod-runtime.md

@@ -0,0 +1,27 @@
+# ADR-004: Mod v1 采用 JSON-only 数据运行时
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+OES-WEB 的目标是让 Mod 成为核心能力，但浏览器内执行玩家导入的脚本会带来注入、数据窃取、无限循环和调试成本风险。当前阶段更需要先把基础内容扩展、覆盖、加载顺序、冲突报告和游戏系统接入跑稳。
+
+## Decision
+Mod v1 只支持 JSON 数据 Mod，不执行任意 JavaScript。
+
+- Mod 包结构: `{ manifest, data }`
+- `manifest` 声明 id/name/version/priority/dependencies
+- `data` 支持 items/enemies/npcs/quests/recipes/spells/skills/perks/zones
+- `ModValidator` 校验清单、数据域、内容 id 和危险 key
+- `ModResolver` 按依赖和优先级合并启用 Mod，并报告冲突
+- `DataRegistry` 使用 Base Data + Resolved Mod Data 重建运行时数据快照
+- 旧脚本入口保留为禁用桩，任何执行请求都会失败并发出 `script:error`
+
+## Consequences
+- 武器、敌人、掉落、任务和地图可以先通过 JSON 稳定扩展
+- 安全边界清晰，避免 `new Function`/eval 类执行入口进入主包
+- 脚本 Mod 暂时不能实现复杂行为，后续如需要应单独设计 Worker 沙箱和权限 API
+- 系统必须逐步改为只读 `DataRegistry`，减少硬编码内容