chore:首次提交

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`，减少硬编码内容