@sdd330dev/jy-skill 0.3.0

package/assets/templates.json

@@ -0,0 +1,127 @@
+{
+  "defaultCharacter": {
+    "name": "主角",
+    "level": 1,
+    "exp": 0,
+    "hp": 100,
+    "maxHp": 100,
+    "mp": 50,
+    "maxMp": 50,
+    "stamina": 100,
+    "poison": 0,
+    "hurt": 0,
+    "attributes": {
+      "maxHp": 100,
+      "maxMp": 50,
+      "hp": 100,
+      "mp": 50,
+      "hpInc": 5,
+      "attack": 20,
+      "agility": 15,
+      "defence": 10,
+      "heal": 0,
+      "usePoison": 0,
+      "dePoison": 0,
+      "antiPoison": 0,
+      "fist": 0,
+      "sword": 0,
+      "blade": 0,
+      "exotic": 0,
+      "hiddenWeapon": 0,
+      "martialKnowledge": 0,
+      "attackPoison": 0,
+      "ambidextrous": 0,
+      "iq": 50,
+      "morality": 50,
+      "reputation": 0,
+      "stamina": 100,
+      "poison": 0,
+      "hurt": 0,
+      "mpType": "neutral",
+      "level": 1,
+      "exp": 0
+    },
+    "equipment": {
+      "weapon": null,
+      "armor": null
+    },
+    "skills": ["基本拳法"]
+  },
+  "startLocation": "小村",
+  "enemies": {
+    "山贼": { "characterId": 200 },
+    "强盗": { "characterId": 201 },
+    "武林高手": { "characterId": 202 },
+    "老虎": { "hp": 150, "attack": 35, "defence": 20, "solo": true },
+    "毒蛇": { "hp": 60, "attack": 10, "defence": 5, "solo": true }
+  },
+  "defaultInventory": {
+    "silver": 100,
+    "items": [
+      { "id": "30", "name": "金创药", "count": 5 },
+      { "id": "35", "name": "干粮", "count": 3 }
+    ]
+  },
+  "maps": {
+    "小村": {
+      "npcs": ["村长", "商人"],
+      "shops": ["金创药", "小还丹", "干粮"],
+      "connections": ["平安镇", "山洞"]
+    },
+    "平安镇": {
+      "npcs": ["守卫", "商店老板", "客栈老板"],
+      "shops": ["铁剑", "钢刀", "布衣", "皮甲", "金创药", "小还丹"],
+      "connections": ["小村", "华山", "桃花岛", "全真教", "光明顶"]
+    },
+    "山洞": {
+      "npcs": ["神秘人"],
+      "shops": [],
+      "connections": ["小村"],
+      "encounters": { "rate": 20, "enemies": ["山贼", "强盗", "老虎"] }
+    },
+    "华山": {
+      "npcs": ["王重阳"],
+      "shops": [],
+      "connections": ["平安镇"]
+    },
+    "桃花岛": {
+      "npcs": ["黄药师", "黄蓉"],
+      "shops": [],
+      "connections": ["平安镇"]
+    },
+    "全真教": {
+      "npcs": ["王重阳", "周伯通"],
+      "shops": [],
+      "connections": ["平安镇"]
+    },
+    "光明顶": {
+      "npcs": ["张无忌"],
+      "shops": [],
+      "connections": ["平安镇"]
+    }
+  },
+  "skills": [
+    { "id": 1, "name": "基本拳法", "type": "point", "range": 1, "mpCost": 0, "damage": 10, "source": "基础" },
+    { "id": 2, "name": "基本刀法", "type": "point", "range": 1, "mpCost": 0, "damage": 12, "source": "基础" },
+    { "id": 3, "name": "六脉神剑", "type": "line", "range": 3, "mpCost": 30, "damage": 40, "source": "天龙八部" },
+    { "id": 4, "name": "北冥神功", "type": "point", "range": 1, "mpCost": 10, "damage": 15, "source": "天龙八部" },
+    { "id": 5, "name": "凌波微步", "type": "none", "range": 0, "mpCost": 20, "damage": 0, "source": "天龙八部" },
+    { "id": 6, "name": "降龙十八掌", "type": "cross", "range": 2, "mpCost": 25, "damage": 50, "source": "射雕英雄传" },
+    { "id": 10, "name": "独孤九剑", "type": "point", "range": 1, "mpCost": 20, "damage": 45, "source": "笑傲江湖" },
+    { "id": 12, "name": "九阴真经", "type": "area", "range": 3, "mpCost": 35, "damage": 55, "source": "射雕英雄传" },
+    { "id": 13, "name": "九阳神功", "type": "point", "range": 1, "mpCost": 15, "damage": 25, "source": "倚天屠龙记" },
+    { "id": 18, "name": "太极拳", "type": "point", "range": 1, "mpCost": 15, "damage": 30, "source": "倚天屠龙记" }
+  ],
+  "items": [
+    { "id": 1, "name": "银两", "type": "currency", "price": 0 },
+    { "id": 10, "name": "铁剑", "type": "weapon", "price": 100, "attack": 10 },
+    { "id": 11, "name": "钢刀", "type": "weapon", "price": 200, "attack": 20 },
+    { "id": 20, "name": "布衣", "type": "armor", "price": 50, "defence": 5 },
+    { "id": 21, "name": "皮甲", "type": "armor", "price": 200, "defence": 15 },
+    { "id": 30, "name": "金创药", "type": "consumable", "price": 20, "hp": 50 },
+    { "id": 31, "name": "大还丹", "type": "consumable", "price": 100, "hp": 150 },
+    { "id": 33, "name": "小还丹", "type": "consumable", "price": 30, "mp": 50 },
+    { "id": 35, "name": "干粮", "type": "consumable", "price": 5, "stamina": 20 },
+    { "id": 36, "name": "解毒丸", "type": "consumable", "price": 50, "dePoison": 50 }
+  ]
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@sdd330dev/jy-skill",
+  "version": "0.3.0",
+  "description": "金庸群侠传 Cursor Agent Skill — 对话式武侠 RPG，自然语言驱动移动、战斗与存档",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "cursor",
+    "cursor-skill",
+    "agent-skill",
+    "rpg",
+    "金庸群侠传",
+    "jy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sdd330/jy-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sdd330/jy-skill/issues"
+  },
+  "homepage": "https://github.com/sdd330/jy-skill#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@11.8.0",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "jy-skill": "scripts/install-skill.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "AGENTS.md",
+    "LICENSE",
+    "references",
+    "assets",
+    "save/.gitkeep",
+    "scripts/game-engine.ts",
+    "scripts/game-logic.ts",
+    "scripts/config-loader.ts",
+    "scripts/persistence.ts",
+    "scripts/game-types.ts",
+    "scripts/install-skill.mjs"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:skill": "vitest run",
+    "test:logic": "vitest run scripts/game-logic.test.ts",
+    "test:engine": "vitest run scripts/game-engine.test.ts",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --fix scripts vite.config.ts",
+    "format": "oxfmt scripts vite.config.ts",
+    "check": "oxlint scripts vite.config.ts && oxfmt --check scripts vite.config.ts",
+    "validate:meta": "tsx scripts/validate-skill.ts",
+    "validate:skill": "tsx scripts/validate-assets.ts",
+    "validate:pack": "tsx scripts/validate-pack.ts",
+    "validate:versions": "tsx scripts/validate-versions.ts",
+    "validate:docs": "tsx scripts/validate-docs.ts",
+    "validate:npm": "node scripts/validate-npm-pack.mjs",
+    "validate": "pnpm run validate:meta && pnpm run validate:skill && pnpm run validate:versions && pnpm run validate:docs",
+    "audit:ci": "pnpm audit --audit-level=high",
+    "prepack": "pnpm run validate:versions",
+    "publish:npm": "npm publish --access public",
+    "ci": "pnpm run check && pnpm run typecheck && pnpm run validate && pnpm run validate:pack && pnpm run validate:npm && pnpm run audit:ci && pnpm run test:coverage",
+    "pack:skill": "node scripts/pack-skill.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.2",
+    "@vitest/coverage-v8": "^4.1.9",
+    "oxfmt": "^0.55.0",
+    "oxlint": "^1.70.0",
+    "tsx": "^4.19.4",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  }
+}

package/references/agent-handbook.md

@@ -0,0 +1,308 @@
+# 金庸群侠传 · 智能体操作手册
+
+面向 Agent 的完整玩法与逻辑说明。玩家向文案见 [player-guide.md](player-guide.md)；叙事风格见 [AGENTS.md](../AGENTS.md)。
+
+---
+
+## 1. 核心职责
+
+你是**叙述者 + 执行者**，必须：
+
+1. **只通过** `scripts/game-engine.ts` 改变游戏状态，禁止手改 `save/game-state.json` 或心算数值。
+2. **每次状态变更后**引擎自动存档；回复结束前可幂等调用 `saveGameState(state)`。
+3. **用武侠文风**叙述 API 返回的 `message`，勿向玩家暴露函数名。
+4. **失败时**根据 `success: false` 的 `message` 用自然语言解释，并给出可行替代（如「银两不足，可先卖…」→ 本版无出售，应建议去商人处或减少购买）。
+5. **数值以引擎为准**：伤害、经验、升级、物品消耗均由 `game-logic.ts` / `game-engine.ts` 计算。
+
+---
+
+## 2. 每轮决策流程
+
+```
+玩家输入
+  ↓
+解析意图（可含多步：「去平安镇买铁剑」）
+  ↓
+若无 state → loadOrCreateGame(createNewGame, '主角')
+  ↓
+按顺序调用 API（移动 → 遇敌？→ 购物 → …）
+  ↓
+moveTo 若返回 encounter → 必须 startBattle 并打完或玩家死亡
+  ↓
+战斗后 isDead(state) ? → 死亡结算 + restartGame()
+  ↓
+getStatus(state) 生成状态栏，附在回复末尾
+```
+
+**复合指令**：按逻辑顺序逐步调用。例：「去平安镇买铁剑并装备」→ `moveTo` → 若 `encounter` 先战斗 → `buyItem` → `equipItem`。
+
+**续玩 vs 新游戏**：
+
+| 场景 | 做法 |
+|------|------|
+| 「jy / 开始游戏」 | `loadOrCreateGame`；`isNewGame === true` 时做首登引导 |
+| 「重新开始 / 新游戏」 | `restartGame()`，勿只 `deleteSave` 不落盘 |
+| 战斗后 HP≤0 | 死亡叙述 → `restartGame()` |
+
+---
+
+## 3. 游戏规则（引擎实现）
+
+### 3.1 时间与移动
+
+- **`moveTo(state, destination)`** 成功时：
+  - 更新 `state.location`
+  - 体力 **-5**（不低于 0）
+  - **周数 +1**
+  - 若中毒/受伤，触发每周掉血（见下）
+  - 可能触发 **随机遇敌**（见 3.6）
+- **目的地**必须是当前地图 `connections` 中的**精确名称**（如「平安镇」，非「平安」）。
+- **`destination === 'random'`**：随机选一条相连道路（玩家说「随便走走」时用）。
+
+### 3.2 中毒与受伤
+
+移动推进周数后（`advanceWeekEffects`）：
+
+- 中毒掉血 = `floor(中毒值 / 10)`，HP 最低保留 **1**
+- 受伤掉血 = `floor(受伤值 / 20)`，HP 最低保留 **1**
+- **`rest(state)`** 可满血满内力满体力并清零中毒、受伤。
+
+### 3.3 物品
+
+| 物品 | 效果（配置值，实际恢复量可更少） |
+|------|----------------------------------|
+| 金创药 | +HP |
+| 小还丹 | +MP |
+| 干粮 | +体力 |
+| 解毒丸 | 解毒 |
+
+**重要**：`useItem` 按**实际收益**扣物品；生命/内力/体力已满或无毒时 **不消耗**，返回失败 message。叙述时引用 API 返回的实际恢复量。
+
+### 3.4 装备
+
+- `equipItem` 仅支持**武器**（铁剑、钢刀等）和**防具**（布衣、皮甲等）。
+- 装备后攻击/防御在战斗中通过 `getEffectiveAttack` / `getEffectiveDefence` 生效。
+- 装备**不消耗**背包数量（与使用品不同）。
+
+### 3.5 升级
+
+- 击败敌人获得经验：`10 + 敌人maxHp/10`
+- 升级所需：`floor(100 × 1.5^(等级-1))`
+- 最高 **Lv.100**；满级后 `getStatus` 显示「经验: N（已满级）」
+- 升级时 maxHp/maxMp/攻防提升，HP/MP 回满
+
+### 3.6 随机遇敌
+
+配置于 `assets/templates.json` 各地图 `encounters` 字段。当前实现：
+
+| 地点 | 概率 | 敌人池 |
+|------|------|--------|
+| 山洞 | 20% | 山贼、强盗、老虎 |
+
+`moveTo` 抵达后若触发，返回 `{ encounter: '山贼' }` 等。**Agent 必须**在同一轮或下一轮立即 `startBattle(state, encounter)` 并进入战斗循环，不可忽略。
+
+### 3.7 商店与对话
+
+- **`buyItem`**：物品须在**当前地点** `shops` 列表中，且银两 ≥ 价格。
+- **`talkTo`**：NPC 名须与当前地点 `npcs` **完全一致**。
+- **`talkTo(state, 'random')`**：随机与在场 NPC 对话。
+- 有配置对话的 NPC 返回「说话者：「台词」」格式。
+
+### 3.8 武功
+
+- 新角色默认：**基本拳法**（不耗内力）。
+- **`learnSkill`**：武功须存在于 `assets/skills.json`；已学会则失败。
+- **`useSkillInBattle`**：须已学会且内力 ≥ 消耗；消耗公式见 `game-logic.ts`。
+- **已知限制**：战斗中 `skillLevels` 暂不增长（等级恒为 0 索引）。
+
+---
+
+## 4. 战斗系统
+
+### 4.1 开战
+
+```typescript
+const { success, message, enemies } = startBattle(state, '山贼')
+```
+
+- 敌人名须在 `templates.json` → `enemies` 中（山贼、强盗、武林高手、老虎、毒蛇）。
+- **solo 敌人**（老虎、毒蛇及标记 solo）：仅 1 个。
+- 其他敌人：随机 **1～3** 个，名称可能为 `山贼1`、`山贼2`…
+- `enemies` 为**内存临时数组**，不写入存档；每轮战斗重新 `startBattle` 或沿用同一数组直至结束。
+
+### 4.2 回合循环
+
+```
+while (尚有敌人 hp > 0 && !isDead(state)) {
+  // 玩家回合
+  attackEnemy(state, enemies, targetIndex)
+  或 useSkillInBattle(state, enemies, skillName, targetIndex)
+
+  // 若仍有存活敌人
+  enemyAttack(state, enemies)  // 随机一名存活敌人反击
+
+  // 检查 isDead(state)
+}
+```
+
+- **`targetIndex`**：0 基，对应 `enemies` 数组下标；优先攻击 HP>0 的敌人。
+- 普攻消耗 **3** 体力；武功也消耗 **3** 体力 + 内力。
+- 敌人伤害 = `max(1, 敌人攻击 - 玩家有效防御)`。
+- 玩家伤害由 `calculateDamage` 计算（含 ±20% 波动，**不可自行编造**）。
+
+### 4.3 战斗叙述建议
+
+- 每回合简述「你出招 / 敌人反击 / 剩余 HP」。
+- 多敌人时说明攻击目标名称（用 `enemies[i].name`）。
+- 战斗结束总结：经验获得、是否升级、剩余状态。
+
+---
+
+## 5. API 完整参考
+
+所有函数自 `scripts/game-engine.ts` 导入。
+
+### 存档与初始化
+
+| 函数 | 返回 | 说明 |
+|------|------|------|
+| `loadOrCreateGame(createNewGame, name?)` | `{ state, isNewGame }` | 有档续玩，无档新建落盘 |
+| `loadGameState()` | `GameState \| null` | 仅读取，不创建 |
+| `saveGameState(state)` | void | 幂等手动存档 |
+| `deleteSave()` | void | 仅删档；重开请用 `restartGame` |
+| `restartGame(name?)` | `GameState` | 删档 + 新建 + 落盘 |
+| `createNewGame(name)` | `GameState` | 仅内存，不自动存档 |
+
+### 查询
+
+| 函数 | 说明 |
+|------|------|
+| `getStatus(state)` | 状态栏文本（含经验、中毒/受伤行） |
+| `getInventory(state)` | 银两 + 物品列表 |
+| `getSkills(state)` | 已学武功 |
+| `getLocationInfo(state)` | 当前地点：可前往、NPC、商店、险地提示 |
+
+### 探索与交互
+
+| 函数 | 返回 | 失败常见原因 |
+|------|------|--------------|
+| `moveTo(state, dest)` | `{ success, message, encounter? }` | 不相连、无处可去 |
+| `talkTo(state, npc)` | `{ success, message }` | NPC 不在场 |
+| `rest(state)` | `{ success, message }` | 一般总成功 |
+| `buyItem(state, item)` | `{ success, message }` | 非本店、无货、银两不足 |
+| `useItem(state, item)` | `{ success, message }` | 无物品、非消耗品、无收益 |
+| `equipItem(state, item)` | `{ success, message }` | 无物品、不可装备 |
+| `learnSkill(state, skill)` | `{ success, message }` | 不存在、已学会 |
+
+### 战斗
+
+| 函数 | 说明 |
+|------|------|
+| `startBattle(state, enemyName)` | 返回 `enemies[]` |
+| `attackEnemy(state, enemies, i)` | 返回 `{ message, enemyDefeated, playerDamage }` |
+| `useSkillInBattle(state, enemies, skill, i)` | 返回 `{ success, message }` |
+| `enemyAttack(state, enemies)` | 返回 `{ message, playerDefeated }` |
+| `isDead(state)` | `character.hp <= 0` |
+
+---
+
+## 6. 世界速查（`assets/templates.json`）
+
+地图只能走**相邻**连接；各门派经**平安镇**枢纽。
+
+| 地点 | 可前往 | NPC | 商店 |
+|------|--------|-----|------|
+| 小村 | 平安镇、山洞 | 村长、商人 | 金创药、小还丹、干粮 |
+| 平安镇 | 小村、华山、桃花岛、全真教、光明顶 | 守卫、商店老板、客栈老板 | 铁剑、钢刀、布衣、皮甲、金创药、小还丹 |
+| 山洞 | 小村 | 神秘人 | 无（20% 遇敌） |
+| 华山 | 平安镇 | 王重阳 | 无 |
+| 桃花岛 | 平安镇 | 黄药师、黄蓉 | 无 |
+| 全真教 | 平安镇 | 王重阳、周伯通 | 无 |
+| 光明顶 | 平安镇 | 张无忌 | 无 |
+
+**可战斗敌人**（任意地点可主动开战）：山贼、强盗、武林高手、老虎、毒蛇。
+
+**新角色初始**：小村、100 银两、金创药×5、干粮×3、基本拳法、HP/MP/体力满值。
+
+> 完整数值与扩展设计见 `assets/` 与 [game-design.md](game-design.md)。**禁止**在叙述中编造未在 assets 出现的物品价、敌人 HP 或地图连接。
+
+---
+
+## 7. GameState 结构（只读理解）
+
+```typescript
+interface GameState {
+  character: {
+    name, level, exp, hp, maxHp, mp, maxMp, stamina
+    poison, hurt
+    attributes   // 攻防等，来自 game-logic DEFAULT_ATTRIBUTES
+    equipment: { weapon, armor }
+    skills: string[]
+    skillLevels: Record<string, number>
+  }
+  inventory: { silver, items: [{ id, name, count }] }
+  location: string
+  week: number
+  flags, visitedMaps, completedQuests, team
+}
+```
+
+---
+
+## 8. 禁止与常见错误
+
+| 错误 | 正确做法 |
+|------|----------|
+| 手改 JSON 存档 | 只调 engine API |
+| 忽略 `moveTo.encounter` | 立即 `startBattle` |
+| 编造伤害/经验数字 | 只用 API 返回值叙述 |
+| 使用不存在的 NPC（如「店小二」） | 查 `getLocationInfo` 或上表 |
+| 跨地图一步到达（小村→华山） | 先经平安镇 |
+| 满血仍描述「服下药丸」且扣物品 | 先 `useItem`，失败则如实告知 |
+| 死亡后只删档不新建 | `restartGame()` |
+| 战斗中使用已阵亡敌人的 index | 选 `hp > 0` 的下标 |
+| 向玩家展示 `moveTo(state,…)` 代码 | 武侠化叙述 |
+
+---
+
+## 9. 交互示例（完整链）
+
+### 移动遇敌
+
+```
+moveTo(state, '山洞')
+→ success, encounter: '老虎'
+→ startBattle(state, '老虎')
+→ 循环 attackEnemy / enemyAttack 直至结束
+→ getStatus(state)
+```
+
+### 帮助
+
+```
+getLocationInfo(state) + getStatus(state)
+→ 按 AGENTS.md 模板用自然语言说明，附状态栏
+```
+
+### 死亡
+
+```
+isDead(state) === true
+→ 叙述陨落 + 结算（level, week, silver）
+→ restartGame('主角')
+→ 简短新人生开场 + 状态栏
+```
+
+---
+
+## 10. 文档索引
+
+| 文件 | 用途 |
+|------|------|
+| [SKILL.md](../SKILL.md) | Skill 入口、快速开始 |
+| [AGENTS.md](../AGENTS.md) | 叙事、首登、帮助模板 |
+| [player-guide.md](player-guide.md) | 玩家 FAQ、地图图 |
+| [game-design.md](game-design.md) | 公式与设计细节 |
+| `scripts/game-engine.ts` | 唯一 API |
+| `scripts/game-logic.ts` | 唯一公式 |
+| `assets/templates.json` | 地图、敌人、初始配置 |

package/references/game-design.md

@@ -0,0 +1,124 @@
+# 金庸群侠传 · 游戏设计文档
+
+## 文档导航
+
+| 读者 | 推荐阅读 |
+|------|----------|
+| 玩家 | [player-guide.md](player-guide.md) — 上手、地图、战斗、FAQ |
+| Agent | [agent-handbook.md](agent-handbook.md) — 完整规则与 API；[SKILL.md](../SKILL.md) + [AGENTS.md](../AGENTS.md) — 入口与叙事 |
+| 开发者 | 本文档 + `scripts/game-logic.ts` — 公式与设计参考 |
+
+**说明**：当前对话版引擎采用**地点跳转式**探索（相邻地图移动、自然语言驱动），而非下方部分章节描述的网格战棋；实现以 `scripts/game-engine.ts` 为准。
+
+---
+
+## 游戏概述
+
+金庸群侠传是一款基于金庸武侠世界的对话式 RPG。玩家通过自然语言与智能体对话，体验武侠冒险。
+
+## 核心玩法
+
+### 角色系统
+- 角色有 40+ 属性：生命、内力、武力、轻功、防御等
+- 角色可装备武器和防具
+- 角色可学习武功，武功有 10 个等级
+- 角色通过战斗获得经验，升级提升属性
+
+### 战斗系统（对话版实现）
+
+- 回合制：玩家攻击 → 敌人反击，循环至战斗结束
+- 普通攻击消耗体力；武功消耗内力
+- 支持左右互搏、武学常识等公式加成（见 `game-logic.ts`）
+- 中毒/受伤每周持续掉血
+
+### 战斗系统（完整设计参考）
+
+以下为扩展设计，供后续版本参考：
+
+- 按轻功排序行动顺序
+- 每回合可移动 + 攻击/使用技能/使用物品/等待
+
+### 物品系统
+- 物品分类：装备、消耗品、书籍、暗器
+- 消耗品可恢复生命/内力/体力
+- 装备可提升属性
+- 书籍可学习武功
+
+### 技能系统
+- 技能有 10 个等级
+- 内力消耗：`MpCost * ((level+1)/2)`
+- 体力消耗：普通3/用毒2/解毒2/医疗4
+- 技能升级：每次使用增加 1-3 经验，100 升级
+
+### 地图系统（对话版实现）
+
+- 7 个地点：小村、平安镇、山洞、华山、桃花岛、全真教、光明顶
+- 只能在相邻地点间移动；移动消耗体力并推进周数
+- 支持 NPC 对话、商店购买
+- **随机遇敌**：配置于 `assets/templates.json` 各地图 `encounters` 字段；进入险地（如山洞，20% 概率）时 `moveTo` 返回 `encounter`，Agent 须接着调用 `startBattle`
+
+### 地图系统（完整设计参考）
+
+- 2D 网格地图（扩展设计）
+- 支持随机遇敌
+
+## 游戏公式
+
+### 升级
+```
+升级经验 = floor(100 × 1.5^(等级-1))
+升级时:
+  maxHp += (hpInc + random(0,3)) × 3
+  attrGain = random(0, floor((资质-10)/20) + 2) + 1
+  maxMp += (9 - attrGain) × 4
+  武力/轻功/防御 += attrGain
+```
+
+### 战斗伤害
+```
+伤害 = 武力 + 技能攻击力 - 敌方防御
+左右互搏: ×1.5
+武学常识加成: +武学常识/10
+随机波动: ±20%
+最低伤害: 1
+```
+
+### 中毒/受伤
+```
+中毒掉血 = 中毒值 / 10
+受伤掉血 = 受伤值 / 20
+最低保留 1 HP
+```
+
+### 武功消耗
+```
+内力消耗 = 基础消耗 × ((等级+1)/2)
+体力消耗: 普通攻击3, 用毒2, 解毒2, 医疗4
+```
+
+### 移动力
+```
+移动力 = 轻功/15 + 3
+```
+
+## 配置数据
+
+### 角色配置
+- 116 个角色（金庸原著角色）
+- 每个角色单独 JSON 文件
+- 包含属性、技能、物品、装备
+
+### 武功配置
+- 25 种武功
+- 每种武功 10 个等级
+- 5 种覆盖类型：点、线、十字、矩形、菱形
+
+### 物品配置
+- 28 种物品
+- 武器、防具、消耗品、经书、暗器
+
+### 地图配置
+
+- 7 个地点：小村、平安镇、山洞、华山、桃花岛、全真教、光明顶
+- 敌人模板：山贼、强盗、武林高手、老虎、毒蛇等
+- 对话与 NPC 配置见 `assets/game-config.json`