@sdd330dev/jy-skill 0.3.0

package/references/player-guide.md

@@ -0,0 +1,176 @@
+# 金庸群侠传 · 玩家手册
+
+面向新玩家的完整说明。在 Cursor 里用自然语言对话即可游玩，**无需记忆任何指令**。
+
+---
+
+## 30 秒上手
+
+1. 安装 skill：`npm install @sdd330dev/jy-skill --save-dev` 后执行 `npx jy-skill install`（详见 [README.md](../README.md)）。
+2. 在对话中说：**「jy」** 或 **「开始游戏」** —— 有存档则继续，无存档则从小村开始新冒险。
+3. 用日常中文描述你想做的事，例如「去平安镇」「和村长聊聊」「买把铁剑」「攻击山贼」。
+4. 进度会在每次操作后**自动保存**，下次再说「jy」即可续玩。
+
+需要帮助时说：**「帮助」**、**「怎么玩」** 或 **「jy 帮助」**。
+
+---
+
+## 新游戏初始状态
+
+| 项目 | 内容 |
+|------|------|
+| 起始地点 | 小村 |
+| 银两 | 100 |
+| 武功 | 基本拳法 |
+| 背包 | 金创药 ×5、干粮 ×3 |
+| 生命 / 内力 / 体力 | 满值（随等级提升上限） |
+
+### 属性说明
+
+- **生命**：降为 0 则江湖路断，需重新开始。
+- **内力**：施展高级武功时消耗。
+- **体力**：移动与战斗会消耗；可吃干粮恢复。
+- **经验 / 等级**：战斗胜利获得经验，升级后生命、内力、攻防提升。
+- **周数**：每次移动推进一周；中毒、受伤状态下每周会额外掉血。
+- **中毒 / 受伤**：数值越高掉血越多，可用解毒丸或休息缓解。
+
+---
+
+## 你可以说什么
+
+| 想做什么 | 示例说法 |
+|----------|----------|
+| 移动 | 去平安镇、前往山洞、随便走走 |
+| 对话 | 和村长聊聊、找商人、拜访王重阳 |
+| 购物 | 买一把铁剑、来瓶金创药、要件皮甲 |
+| 使用物品 | 用金创药、吃干粮 |
+| 装备 | 装备铁剑、穿上布衣 |
+| 学武功 | 学习六脉神剑（需先满足剧情或 NPC 条件） |
+| 战斗 | 攻击山贼、和老虎一战 |
+| 查看信息 | 查看状态、看看背包、我会哪些武功 |
+| 恢复 | 休息 |
+| 帮助 | 帮助、怎么玩、指令说明 |
+
+说「随便走走」时，会随机前往当前地点相连的一个方向。
+
+---
+
+## 世界地图
+
+各地点只能前往**直接相连**的邻居，不能一步跨越大半个江湖。
+
+```
+       华山   桃花岛   全真教   光明顶
+         \     |     /      /
+          \    |    /      /
+   小村 — 平安镇 — (枢纽)
+     |
+   山洞
+```
+
+（除小村↔山洞、小村↔平安镇外，各门派均需经平安镇中转。）
+
+### 地点详情
+
+| 地点 | 可前往 | NPC | 商店 |
+|------|--------|-----|------|
+| **小村** | 平安镇、山洞 | 村长、商人 | 金创药、小还丹、干粮 |
+| **平安镇** | 小村、华山、桃花岛、全真教、光明顶 | 守卫、商店老板、客栈老板 | 铁剑、钢刀、布衣、皮甲、金创药、小还丹 |
+| **山洞** | 小村 | 神秘人 | 无（探险区域，可能遇敌） |
+| **华山** | 平安镇 | 王重阳 | 无 |
+| **桃花岛** | 平安镇 | 黄药师、黄蓉 | 无 |
+| **全真教** | 平安镇 | 王重阳、周伯通 | 无 |
+| **光明顶** | 平安镇 | 张无忌 | 无 |
+
+### 新人推荐路线
+
+1. **小村**：与村长对话，了解江湖概况；向商人补充药品。
+2. **平安镇**：购买武器（铁剑/钢刀）和防具（布衣/皮甲），再考虑远行。
+3. **门派地点**：拜访 NPC，触发对话、学习更高阶武功。
+4. **山洞**：实力不足时慎入，洞内可能有强敌。
+
+---
+
+## 战斗入门
+
+### 流程
+
+1. 你说要打的敌人（如山贼、老虎），或在进入**山洞**等险地时可能**自动遇敌**（移动后须应战）。
+2. **你的回合**：普通攻击，或施展已学会的武功。
+3. **敌人回合**：敌人反击，可能多人轮流出手。
+4. 重复直至一方全灭或你倒下。
+
+### 要点
+
+- **普通攻击**消耗体力，不耗内力。
+- **武功**消耗内力；内力不足时只能用普攻。初学「基本拳法」不耗内力。
+- 可遭遇的敌人包括：**山贼**、**强盗**、**武林高手**、**老虎**、**毒蛇**等；部分敌人可能多人同场。
+- 战胜敌人获得**经验**；经验足够则**升级**，各项能力上升。
+- 装备武器、防具后再战，会明显更轻松。
+
+### 简单策略
+
+- 战前确保生命、内力、体力充足；不足则休息或使用背包药品。
+- 银两充裕时在平安镇备足金创药、小还丹。
+- 感觉吃力时先升级、换装备，再挑战强敌。
+
+---
+
+## 生存技巧
+
+- **移动**每次消耗 5 点体力，并推进 1 周；规划路线，避免体力耗尽困在途中。
+- **干粮**恢复体力，**金创药**恢复生命，**小还丹**恢复内力；**解毒丸**可解除中毒。生命/内力/体力已满时不会浪费药品。
+- **休息**一次满血满内力满体力，并清除中毒、受伤（在任意地点可用）。
+- 中毒、受伤状态下每移动一周会持续掉血，宜尽快治疗或休息。
+- 死亡后当前存档清除，需从头开始；重要进度请多探索、少鲁莽涉险。
+
+---
+
+## 状态栏说明
+
+每次回复末尾会显示当前状态，例如：
+
+```
+👤 主角 | Lv.1 | 经验: 0/150
+❤️ 100/100 | 💠 50/50 | ⚡ 95/100
+💰 100 | 📍 小村 | 📅 第1周
+```
+
+若有中毒、受伤，会额外显示 🧪 中毒、💊 受伤 行。
+
+---
+
+## 常见问题
+
+**如何继续上次的游戏？**  
+直接再说「jy」或「开始游戏」，会自动读取存档。
+
+**如何重新开始？**  
+说「重新开始」「删除存档」或「新游戏」，Agent 会调用 `restartGame()` 清除存档并创建新角色。
+
+**满级后经验怎么显示？**  
+达到 Lv.100 后，状态栏显示「经验: N（已满级）」，不再显示升级所需经验。
+
+**为什么去不了某个地方？**  
+只能走到与当前地点**相连**的地图。例如在小村不能直接到华山，需先到平安镇。
+
+**为什么买不到某样东西？**  
+每个地点的商店货品不同；部分物品只在平安镇出售。银两不足也无法购买。
+
+**战斗中途可以逃跑吗？**  
+当前版本以叙述式回合战斗为主，建议战前备好药品；力有不逮时可先休息、补给再来。
+
+**需要记命令吗？**  
+不需要。用中文描述意图即可，例如「去平安镇买铁剑」比记固定指令更自然。
+
+**存档存在哪？**  
+项目目录下 `save/game-state.json`，自动创建与更新。
+
+---
+
+## 更多资料
+
+- 开发者与 Agent 说明：[SKILL.md](../SKILL.md)、[AGENTS.md](../AGENTS.md)、[agent-handbook.md](agent-handbook.md)
+- 设计与公式细节：[game-design.md](game-design.md)
+
+祝你在金庸武侠世界中，闯出一段属于自己的传说。

package/scripts/config-loader.ts

@@ -0,0 +1,408 @@
+/**
+ * 配置加载器 — 从 assets/*.json 单源加载游戏数据
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+const ASSETS_DIR = join(ROOT_DIR, 'assets');
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+export interface MapInfo {
+  npcs: string[];
+  shops: string[];
+  connections: string[];
+  npcDialogs: Record<string, string>;
+  encounterRate?: number;
+  encounterEnemies?: string[];
+}
+
+export interface ItemConfig {
+  id: number;
+  name: string;
+  desc: string;
+  type: number;
+  equipmentType: number;
+  price: number;
+  addAttack: number;
+  addDefence: number;
+  useAddHp: number;
+  useAddMp: number;
+  useAddStamina: number;
+  useDePoison: number;
+}
+
+export interface SkillConfig {
+  id: number;
+  name: string;
+  desc: string;
+  mpCost: number;
+  damageType: number;
+  levels: number[][];
+}
+
+export interface CharacterConfig {
+  id: number;
+  name: string;
+  maxHp: number;
+  attack: number;
+  defence: number;
+  skills: number[][];
+  source: string;
+}
+
+export interface DialogConfig {
+  id: string;
+  speaker: string;
+  text: string;
+}
+
+export interface EnemyTemplate {
+  hp: number;
+  attack: number;
+  defence: number;
+  solo?: boolean;
+}
+
+export interface GameTemplates {
+  defaultCharacter: {
+    name: string;
+    skills: string[];
+  };
+  defaultInventory: {
+    silver: number;
+    items: Array<{ id: string; name: string; count: number }>;
+  };
+  startLocation: string;
+  enemies: Record<string, EnemyTemplate | { characterId: number }>;
+  maps?: Record<
+    string,
+    {
+      npcs: string[];
+      shops: string[];
+      connections: string[];
+      encounters?: number | { rate: number; enemies: string[] };
+    }
+  >;
+}
+
+function parseEncounters(
+  encounters?: number | { rate: number; enemies: string[] },
+): Pick<MapInfo, 'encounterRate' | 'encounterEnemies'> {
+  if (encounters == null) return {};
+  if (typeof encounters === 'number') {
+    return { encounterRate: encounters, encounterEnemies: ['山贼', '强盗'] };
+  }
+  return { encounterRate: encounters.rate, encounterEnemies: [...encounters.enemies] };
+}
+
+// ============================================================================
+// 加载
+// ============================================================================
+
+function loadJson<T>(relativePath: string): T {
+  const path = join(ASSETS_DIR, relativePath);
+  return JSON.parse(readFileSync(path, 'utf-8')) as T;
+}
+
+const mapsByName = new Map<string, MapInfo>();
+const itemsByName = new Map<string, ItemConfig>();
+const itemsById = new Map<number, ItemConfig>();
+const skillsByName = new Map<string, SkillConfig>();
+const charactersById = new Map<number, CharacterConfig>();
+const charactersByName = new Map<string, CharacterConfig>();
+const dialogsById = new Map<string, DialogConfig>();
+let templates: GameTemplates;
+let initialized = false;
+
+function resolveEnemyTemplate(
+  entry: EnemyTemplate | { characterId: number },
+): EnemyTemplate | undefined {
+  if ('characterId' in entry) {
+    const char = charactersById.get(entry.characterId);
+    if (!char) return undefined;
+    return { hp: char.maxHp, attack: char.attack, defence: char.defence };
+  }
+  return entry;
+}
+
+function buildMapsFromConfig(): void {
+  const gameConfig = loadJson<{
+    maps: Array<{
+      id: number;
+      name: string;
+      npcs: Array<{
+        roleId: number;
+        dialogId: string;
+        isShop: boolean;
+        shopItems: number[];
+      }>;
+      connections: Array<{ targetMapId: number }>;
+    }>;
+    dialogs: Record<string, DialogConfig>;
+  }>('game-config.json');
+
+  const mapIdToName = new Map<number, string>();
+  for (const map of gameConfig.maps) {
+    mapIdToName.set(map.id, map.name);
+  }
+
+  for (const [id, dialog] of Object.entries(gameConfig.dialogs)) {
+    dialogsById.set(id, dialog);
+  }
+
+  const templateMaps = templates.maps ?? {};
+
+  for (const map of gameConfig.maps) {
+    const templateMap = templateMaps[map.name as keyof typeof templateMaps];
+    const npcDialogs: Record<string, string> = {};
+    const npcNames: string[] = [];
+    const shopNames = new Set<string>();
+
+    for (const npc of map.npcs) {
+      const char = charactersById.get(npc.roleId);
+      if (!char) continue;
+      npcNames.push(char.name);
+      npcDialogs[char.name] = npc.dialogId;
+      if (npc.isShop) {
+        for (const itemId of npc.shopItems) {
+          const item = itemsById.get(itemId);
+          if (item) shopNames.add(item.name);
+        }
+      }
+    }
+
+    const connections =
+      templateMap && 'connections' in templateMap
+        ? [...templateMap.connections]
+        : map.connections
+            .map((c) => mapIdToName.get(c.targetMapId))
+            .filter((name): name is string => Boolean(name));
+
+    const shops =
+      templateMap && templateMap.shops.length > 0 ? [...templateMap.shops] : [...shopNames];
+
+    const encounterConfig = parseEncounters(templateMap?.encounters);
+
+    mapsByName.set(map.name, {
+      npcs: templateMap?.npcs?.length ? [...templateMap.npcs] : npcNames,
+      shops,
+      connections,
+      npcDialogs,
+      ...encounterConfig,
+    });
+  }
+
+  // templates 中有但 game-config 未列出的地图（兜底）
+  for (const [name, map] of Object.entries(templateMaps)) {
+    if (!mapsByName.has(name)) {
+      const encounterConfig = parseEncounters(map.encounters);
+      mapsByName.set(name, {
+        npcs: [...map.npcs],
+        shops: [...map.shops],
+        connections: [...map.connections],
+        npcDialogs: {},
+        ...encounterConfig,
+      });
+    }
+  }
+}
+
+function loadCharacters(): void {
+  const index = loadJson<{ characters: Array<{ id: number; name: string }> }>(
+    'characters/index.json',
+  );
+
+  for (const info of index.characters) {
+    try {
+      const data = loadJson<CharacterConfig>(`characters/${info.id}.json`);
+      charactersById.set(data.id, data);
+      charactersByName.set(data.name, data);
+    } catch {
+      // 跳过缺失文件，validate-assets 会报告
+    }
+  }
+}
+
+function loadItems(): void {
+  const data = loadJson<{ items: ItemConfig[] }>('items.json');
+  for (const item of data.items) {
+    itemsByName.set(item.name, item);
+    itemsById.set(item.id, item);
+  }
+}
+
+function loadSkills(): void {
+  const data = loadJson<{ skills: SkillConfig[] }>('skills.json');
+  for (const skill of data.skills) {
+    skillsByName.set(skill.name, skill);
+  }
+}
+
+/** 初始化配置（幂等） */
+export function initConfigs(): void {
+  if (initialized) return;
+
+  templates = loadJson<GameTemplates>('templates.json');
+  if (!templates.startLocation) {
+    templates.startLocation = '小村';
+  }
+  if (!templates.enemies) {
+    templates.enemies = {
+      山贼: { characterId: 200 },
+      强盗: { characterId: 201 },
+      武林高手: { characterId: 202 },
+      老虎: { hp: 150, attack: 35, defence: 20, solo: true },
+      毒蛇: { hp: 60, attack: 10, defence: 5, solo: true },
+    };
+  }
+
+  loadCharacters();
+  loadItems();
+  loadSkills();
+  buildMapsFromConfig();
+
+  initialized = true;
+}
+
+/** 重置缓存（仅测试用） */
+export function resetConfigsForTest(): void {
+  initialized = false;
+  mapsByName.clear();
+  itemsByName.clear();
+  itemsById.clear();
+  skillsByName.clear();
+  charactersById.clear();
+  charactersByName.clear();
+  dialogsById.clear();
+}
+
+// ============================================================================
+// 查询 API
+// ============================================================================
+
+export function getTemplates(): GameTemplates {
+  initConfigs();
+  return templates;
+}
+
+export function getMap(name: string): MapInfo | undefined {
+  initConfigs();
+  return mapsByName.get(name);
+}
+
+export function getAllMapNames(): string[] {
+  initConfigs();
+  return [...mapsByName.keys()];
+}
+
+export function getItem(name: string): ItemConfig | undefined {
+  initConfigs();
+  return itemsByName.get(name);
+}
+
+export function getSkill(name: string): SkillConfig | undefined {
+  initConfigs();
+  return skillsByName.get(name);
+}
+
+export function getSkillAttackAtLevel(skillName: string, levelIndex = 0): number {
+  const skill = getSkill(skillName);
+  if (!skill || !skill.levels.length) return 0;
+  const idx = Math.min(levelIndex, skill.levels.length - 1);
+  return skill.levels[idx][0] ?? 0;
+}
+
+export function getCharacterByName(name: string): CharacterConfig | undefined {
+  initConfigs();
+  return charactersByName.get(name);
+}
+
+export function getDialog(dialogId: string): DialogConfig | undefined {
+  initConfigs();
+  return dialogsById.get(dialogId);
+}
+
+export function getEnemyTemplate(enemyName: string): EnemyTemplate | undefined {
+  initConfigs();
+  const entry = templates.enemies[enemyName];
+  if (!entry) return undefined;
+  return resolveEnemyTemplate(entry);
+}
+
+export function isWeapon(item: ItemConfig): boolean {
+  return item.type === 1 && item.equipmentType >= 0 && item.addAttack > 0;
+}
+
+export function isArmor(item: ItemConfig): boolean {
+  return item.type === 1 && item.equipmentType >= 0 && item.addDefence > 0;
+}
+
+export function isConsumable(item: ItemConfig): boolean {
+  return item.useAddHp > 0 || item.useAddMp > 0 || item.useAddStamina > 0 || item.useDePoison > 0;
+}
+
+/** 校验 assets 完整性（CLI / CI 用） */
+export function validateAssets(): string[] {
+  resetConfigsForTest();
+  initConfigs();
+
+  const errors: string[] = [];
+  const index = loadJson<{ characters: Array<{ id: number; name: string }> }>(
+    'characters/index.json',
+  );
+
+  for (const info of index.characters) {
+    const path = join(ASSETS_DIR, 'characters', `${info.id}.json`);
+    try {
+      readFileSync(path, 'utf-8');
+    } catch {
+      errors.push(`Missing character file: characters/${info.id}.json (${info.name})`);
+    }
+  }
+
+  const charFiles = readdirSync(join(ASSETS_DIR, 'characters')).filter((f) =>
+    /^\d+\.json$/.test(f),
+  );
+  const indexIds = new Set(index.characters.map((c) => c.id));
+  for (const file of charFiles) {
+    const id = Number.parseInt(file.replace('.json', ''), 10);
+    if (!indexIds.has(id)) {
+      errors.push(`Character file ${file} not listed in characters/index.json`);
+    }
+  }
+
+  for (const mapName of getAllMapNames()) {
+    const map = getMap(mapName)!;
+    for (const shopItem of map.shops) {
+      if (!getItem(shopItem)) {
+        errors.push(`Map "${mapName}" shop references unknown item: ${shopItem}`);
+      }
+    }
+    for (const conn of map.connections) {
+      if (!getMap(conn)) {
+        errors.push(`Map "${mapName}" connection target unknown: ${conn}`);
+      }
+    }
+  }
+
+  for (const enemyName of Object.keys(templates.enemies)) {
+    if (!getEnemyTemplate(enemyName)) {
+      errors.push(`Enemy template unresolved: ${enemyName}`);
+    }
+  }
+
+  for (const skillName of templates.defaultCharacter.skills ?? ['基本拳法']) {
+    if (!getSkill(skillName)) {
+      errors.push(`Default skill not found in skills.json: ${skillName}`);
+    }
+  }
+
+  resetConfigsForTest();
+  return errors;
+}