docs: 添加 Pokémon 战斗系统审查报告

记录 20 个已发现的 bug 及修复状态，涵盖严重/中等/轻度三个级别。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: claude-code-best

packages/pokemon/docs/battle-audit-report.md

@@ -0,0 +1,338 @@
+# Pokémon Battle 实现审查报告
+
+> 审查日期：2026-04-23
+> 审查范围：`packages/pokemon/` 全部源码（battle、core、dex、ui）
+> 对比基准：原版 Pokémon 核心系列游戏（Gen 9：Scarlet/Violet）
+> 更新日期：2026-04-24 — 修复了 #1, #2, #3, #4, #6, #7, #8, #13
+
+---
+
+## 一、严重问题（核心机制错误）
+
+### 1. XP 计算公式与原版不符
+
+**文件**: `src/battle/settlement.ts:30-31`
+
+```ts
+const baseXp = (oppSpecies?.baseStats?.hp ?? 50) * opponentLevel / 7
+```
+
+原版 Gen 9 的 XP 计算公式为：
+
+```
+XP = (baseXP × opponentLevel × isTraded × isParticipating) / 7 × partySizeModifier
+```
+
+当前实现存在以下错误：
+
+- **baseXP 不等于 baseStats.hp**。每只宝可梦有独立的 `base_experience` 值（例如妙蛙种子是 64，皮卡丘是 112），而不是 HP 种族值。目前用 `baseStats.hp` 做代理完全是错的。
+- **缺少 traded Pokémon 1.5x 加成**。
+- **缺少参与战斗的宝可梦分摊机制**（原版中只有实际参与战斗的宝可梦获得 XP）。
+- **缺少 Lucky Egg 1.5x 加成**。
+- **缺少 Affection 加成**（Gen 6+）。
+
+### 2. EV 收益完全自造，不使用真实数据
+
+**文件**: `src/battle/settlement.ts:176-191`
+
+```ts
+function getEvYield(speciesId: string): Record<string, number> {
+  // @pkmn/sim Dex.species doesn't have evs field
+  // Use baseStats as proxy: highest base stat gets 1-2 EVs
+  ...
+}
+```
+
+原版中每只宝可梦有固定的 EV yield（如妙蛙种子击倒后给 HP+1，皮卡丘给 Speed+2）。这些数据在 `@pkmn/data` 中是有的（`species.evs`），但代码误以为 `@pkmn/sim` 没有这个字段，就自造了一个「最高种族值 → 2 EV，第二高 → 1 EV」的算法，与原版完全不同。
+
+### 3. 物品使用在战斗中无效
+
+**文件**: `src/battle/engine.ts:436-438`
+
+```ts
+case 'item':
+  p1Choice = 'move 1'  // fallback to move 1
+  break
+```
+
+当玩家使用物品（如药水）时，代码直接忽略了，改为使用第一个招式。原版中物品使用是战斗的核心部分——回复药、状态治愈药、精灵球等都有完整的效果。
+
+### 4. 逃跑功能未实现
+
+**文件**: `src/ui/BattleFlow.tsx:314`
+
+```ts
+case 3: // 逃跑 — show message
+  return
+```
+
+战斗菜单中「逃跑」按钮存在但点击后什么也不做。原版中有逃跑概率计算公式（基于速度对比），对野外战斗是核心机制。
+
+### 5. 对手（p2）不支持多精灵队伍
+
+**文件**: `src/battle/engine.ts:61-67`
+
+```ts
+function wildPokemonToSetString(speciesId: SpeciesId, level: number): string {
+  ...
+  return [species.name, `Level: ${level}`, `Ability: ${ability}`, ...moves.map(m => `- ${m}`)].join('\n')
+}
+```
+
+对手始终只有一只宝可梦（野生宝可梦模式）。没有 Trainer Battle 的概念——对手不能有多只精灵、不能换人、不能使用物品。虽然 AI 在精灵倒下后会自动换人（`executeSwitch` 中有处理），但 `createBattle` 本身只接受单个对手 species。
+
+---
+
+## 二、中等问题（机制简化/缺失）
+
+### 6. AI 过于简单
+
+**文件**: `src/battle/ai.ts:6-13`
+
+```ts
+export function chooseAIMove(pokemon: BattlePokemon): number {
+  const usable = pokemon.moves
+    .map((m, i) => ({ move: m, index: i }))
+    .filter(({ move }) => move.pp > 0 && !move.disabled)
+  if (usable.length === 0) return 0
+  return usable[Math.floor(Math.random() * usable.length)]!.index
+}
+```
+
+AI 只是随机选择一个可用招式。原版 NPC AI 至少会考虑：
+
+- **属性克制**：优先使用效果绝佳的招式
+- **状态技 vs 攻击技**的权衡
+- **HP 低时**可能使用回复招式
+- **玩家属性**：避免使用被抵抗的招式
+- 不会换人、不会使用物品
+
+### 7. 野生宝可梦的招式是按属性硬编码的
+
+**文件**: `src/battle/engine.ts:69-94`
+
+```ts
+function getSpeciesMoves(speciesId: string, _level: number): string[] {
+  ...
+  const basicMoves: Record<string, string[]> = {
+    normal: ['Tackle', 'Scratch'],
+    fire: ['Ember', 'FireSpin'],
+    ...
+  }
+  return basicMoves[type] ?? ['Tackle', 'Scratch']
+}
+```
+
+野生对手的招式不是从 learnset 中获取的，而是按第一属性硬编码了固定招式。`_level` 参数被完全忽略了——原版中不同等级的野生宝可梦应该有不同的招式组合。
+
+### 8. 进化系统不完整
+
+**文件**: `src/dex/evolution.ts` + `src/battle/settlement.ts:92-106`
+
+- 只处理了 `evoType` 为 `level_up`、`item`、`trade`、`friendship` 四种类型
+- **只取第一个进化目标** (`dex.evos[0]`)，忽略了分支进化（如伊布的多种进化）
+- **没有进化石使用的交互**（使用雷之石等道具触发进化）
+- **没有通讯交换进化**
+- **没有条件进化**（如知道特定招式、特定时间、特定地点等 Gen 9 新增条件）
+
+### 9. 能力值计算缺少特性/道具修正
+
+**文件**: `src/core/creature.ts:51-73`
+
+`calculateStats` 只计算基础能力值，没有考虑：
+
+- **特性对能力值的修正**（如 Hustle 增加攻击降低命中）
+- **道具对能力值的修正**（如 Choice Band 增加攻击 50%）
+
+注：性格修正虽然传入了 `nature`，但由 `@pkmn/data` 的 `gen.stats.calc` 内部处理，这部分是正确的。
+
+### 10. 捕获系统完全缺失
+
+没有任何捕获野生宝可梦的机制：
+
+- 没有 Pokeball 道具的实际效果
+- 没有捕获率计算（Shake check 公式）
+- 战斗结束后不能获得对手宝可梦
+- 虽然数据中有 `captureRate` 字段和 `pokeball` 字段，但从未使用
+
+### 11. 状态异常处理不完整
+
+**文件**: `src/battle/engine.ts:130-140`
+
+只映射了 6 种基本状态（中毒、剧毒、灼伤、麻痹、冰冻、睡眠），但缺少：
+
+- **混乱 (Confusion)**：不在 status 中，是 volatile status
+- **着迷 (Infatuation)**：同上
+- **畏缩 (Flinch)**：同上
+- 所有 volatile status（暂时性状态）都未追踪
+
+### 12. 天气/场地效果未完整追踪
+
+**文件**: `src/battle/engine.ts:153-173`
+
+- `projectState` 中天气只在初始化时从 `prevConditions` 传入，不会自动更新
+- `mapWeather` 不区分 Primal Weather（原始回归天气）和普通天气
+- **场地效果（Electric Terrain、Grassy Terrain 等）** 被映射为 `fieldCondition` 事件，但没有影响战斗状态的逻辑
+
+注：底层 `@pkmn/sim` 会正确处理这些效果，只是上层状态投影不完整，导致 UI 无法正确显示。
+
+---
+
+## 三、轻度问题（数值/细节偏差）
+
+### 13. Growth Rate 数据覆盖不全
+
+**文件**: `src/dex/species.ts:38-99`
+
+只有 9 个物种（御三家 + 皮卡丘）有正确的 `growthRate` 数据，其余全部使用默认值 `medium-slow`。实际上超过 1000 个物种各有不同的成长速率。这导致 XP 计算对大部分物种不正确。
+
+### 14. 闪光概率未使用 PID 计算
+
+**文件**: `src/core/creature.ts:25`
+
+```ts
+const isShiny = Math.random() < species.shinyChance  // 1/4096
+```
+
+原版 Gen 9 的闪光判定基于 Personality Value（32 位 PID）的异或运算，不是简单的随机概率。Shiny Charm 等道具的加成也无法体现。
+
+### 15. IV 生成算法不是真正的 LCRNG
+
+**文件**: `src/core/creature.ts:108-122`
+
+```ts
+function generateIVs(seed: number): Record<StatName, number> {
+  let s = seed
+  const nextRand = () => {
+    s = (s * 1103515245 + 12345) & 0x7fffffff
+    return s
+  }
+```
+
+原版 Gen 3+ 使用的是完全不同的随机数生成器。更重要的是，Gen 3-5 的 IV 是通过 PID 的高位/低位直接提取的，不是独立随机。
+
+### 16. 性别判定阈值计算偏差
+
+**文件**: `src/core/gender.ts:12-13`
+
+```ts
+const threshold = (speciesData.genderRate / 8) * 256
+return (seed % 256) < threshold ? 'female' : 'male'
+```
+
+原版中性别由 PID 的低 8 位与 `genderRate` 直接比较决定，不需要乘 256 再取阈值。当前实现引入了不必要的精度损失。
+
+### 17. 蛋系统与原版差异巨大
+
+**文件**: `src/core/egg.ts`
+
+- **获得条件**：原版通过培育屋/寄养屋繁殖，当前通过「连续编码 3 天 + 每 50 回合」获得
+- **孵化步数**：基于 captureRate 反推，而不是物种真实的 `hatch_counter` 数据
+- **没有遗传招式**：原版中蛋可以遗传父母双方的招式
+- **没有个体值遗传**：原版中蛋会随机继承父母的某些 IV
+- **没有球种遗传**：原版中蛋继承母亲的球种
+
+### 18. 多语言名称覆盖极少
+
+**文件**: `src/dex/names.ts`
+
+只有 10 个物种有中/英/日三语名称，其余 1000+ 个物种只回退到英文名。这对于中文/日文用户来说体验不完整。
+
+### 19. 缺少 Held Item 获取途径
+
+战斗中 `heldItem` 被正确传入 Showdown 格式，所以底层模拟会处理道具效果。但是：
+
+- 没有获得/装备道具的途径
+- 没有商店系统
+- 所有野生对手没有道具
+- 玩家的宝可梦默认 `heldItem: null`
+
+### 20. Ability 系统不完整
+
+- `getDefaultAbility` 只取第一个非隐藏特性
+- 没有隐藏特性（Hidden Ability）的选择
+- 没有特性胶囊/特性补丁的使用
+- 底层 Showdown 会正确处理特性效果（如 Intimidate、Levitate），但 UI 层不显示特性触发
+
+---
+
+## 四、问题汇总
+
+| 严重程度 | 数量 | 编号 |
+|---------|------|------|
+| 严重（核心机制错误） | 5 | #1 ~ #5 |
+| 中等（机制简化/缺失） | 7 | #6 ~ #12 |
+| 轻度（数值/细节偏差） | 8 | #13 ~ #20 |
+
+---
+
+## 五、优先修复建议
+
+按影响面从大到小排列：
+
+1. **修复 XP 和 EV 计算（#1, #2）**：从 `@pkmn/data` 获取真实的 `base_experience` 和 `evs` 数据，替换当前的代理算法。这两个问题直接影响所有战斗的成长反馈。
+2. **实现物品使用（#3）**：至少支持 Potion（回复 HP）和状态治愈药。这是战斗中最基本的交互。
+3. **实现逃跑（#4）**：需要添加逃跑概率公式和对应的 Showdown 协议处理。
+4. **修复野生对手招式（#7）**：从 learnset 中按等级获取招式，替换硬编码映射。
+5. **补全 Growth Rate 数据（#13）**：从 PokeAPI 或 `@pkmn/data` 批量导入，而非只覆盖 9 个物种。
+
+---
+
+## 六、做得好的部分
+
+- **底层战斗引擎（`@pkmn/sim`）集成正确**：属性克制、伤害公式、能力值计算、特性效果等核心数学由 Pokémon Showdown 引擎处理，结果与原版一致。
+- **EV 上限正确**：单项 252 / 总计 510，与原版一致。
+- **XP 经验曲线公式正确**：6 种 Growth Rate 的计算公式（erratic、fluctuating 等）与原版完全一致。
+- **Nature 系统完整**：25 个性格及其加成/减益效果通过 `@pkmn/data` 正确获取。
+- **Learnset 查询正确**：从 `Dex.data.Learnsets` 获取招式学习表，支持跨代回退。
+- **状态异常映射基本正确**：6 种主要状态的 Showdown 协议映射准确。
+- **战斗测试覆盖全面**：包括属性克制、强制换人、多精灵队伍等场景的集成测试。
+
+---
+
+## 七、修复记录（2026-04-24）
+
+### 已修复
+
+| 编号 | 问题 | 修复方式 |
+|------|------|---------|
+| #1 | XP 使用 baseStats.hp | 从 PokeAPI 获取真实 `base_experience`，存入 `pokedex-data.ts`，公式改为 `baseXP × level / 7` |
+| #2 | EV yield 伪造 | 从 PokeAPI 获取真实 EV yield 数据（1024 个物种），存入 `pokedex-data.ts` |
+| #3 | 物品使用无效 | 实现 Potion/HyperPotion/FullRestore 等回复药效果，直接操作 Battle 对象 HP，消耗背包物品 |
+| #4 | 逃跑未实现 | 实现 Gen 9 逃跑概率公式 `f = (playerSpeed × 128 / opponentSpeed + 30 × attempts) % 256`，成功时 forfeit 结束战斗 |
+| #6 | AI 纯随机 | AI 现在优先选克制招式（70%），避免被抵抗招式和蓄力招式，状态技最低优先级 |
+| #7 | 野生招式硬编码 | 从 `Dex.data.Learnsets` 按等级获取升级招式（最后 4 个），替换按属性硬编码映射 |
+| #8 | 进化只取第一目标 | 检查所有 `evos` 目标，支持分支进化，增加友谊度进化检测 |
+| #13 | Growth Rate 只覆盖 9 个 | 从 PokeAPI 批量导入所有 1024 个物种的 growth rate 数据 |
+| #5 | 多精灵对战不支持 | `createBattle` 支持传入 `OpponentEntry[]`，AI 换人时考虑属性克制 |
+| #10 | 缺少捕获系统 | 新增 `capture.ts`，实现 Gen 9 捕获率公式，支持精灵球/状态修正 |
+| #11 | 缺少 volatile status | 新增 `VolatileStatus` 类型，`BattlePokemon` 添加 `volatileStatus` 字段 |
+| #12 | 天气/地形未投影 | 确认 `projectState` 从 `battle.field.weather/terrain` 读取 |
+| #14 | Shiny 检测用随机 | 改为 Gen 3+ PID XOR 方法，阈值 < 16（Gen 8+ 1/4096 概率） |
+| #15 | IV 生成用 LCRNG | 改为 Gen 3+ PID 位提取法（word1/word2 各取 3 个 5-bit IV） |
+| #16 | 性别阈值精度丢失 | 从 `(rate/8)*256` 改为 `rate*32` 直接比较，消除浮点精度问题 |
+| #17 | 蛋孵化步数用 captureRate | 改为使用真实 `hatchCounter` 数据（步数 = cycles × 257），支持进化阶段回退 |
+| #18 | 多语言名称仅 10 个 | 创建 fetch 脚本获取全量中/日名称，`names.ts` 支持动态加载生成数据 |
+| #19 | 野生对手无道具 | 添加 `rollWildHeldItem`：5% 物种专属道具、5% 树果、3% 属性增强道具 |
+| #20 | Ability 只有第一个 | 新增 `randomAbility`/`getAbilities`，隐藏特性 5% 概率，第二特性 20% 概率 |
+
+### 新增文件
+- `src/dex/pokedex-data.ts` — 1024 个物种的 baseExperience、EV yield、growthRate、captureRate、baseHappiness 数据
+- `scripts/fetch-pokedex-data.ts` — PokeAPI 数据抓取脚本（可重新运行以更新数据，含 hatchCounter）
+- `src/battle/capture.ts` — Gen 9 捕获率计算，精灵球/状态/时间修正
+- `scripts/fetch-species-names.ts` — 多语言名称抓取脚本（中/日/英）
+
+### 修改文件
+- `src/battle/settlement.ts` — XP/EV 计算、进化检测
+- `src/battle/engine.ts` — 物品效果、逃跑逻辑、野生招式、AI 调用、多对手支持、野生道具
+- `src/battle/ai.ts` — 属性克制 AI（使用 `Dex.getEffectiveness`）
+- `src/battle/types.ts` — 新增 `run` 动作、`escaped`/`escapeAttempts`/`captureResult` 状态、VolatileStatus
+- `src/battle/index.ts` — 导出 OpponentEntry、attemptCapture、CaptureResult
+- `src/ui/BattleFlow.tsx` — 逃跑按钮、物品消耗
+- `src/dex/species.ts` — 使用 pokedex-data 替代硬编码 supplement
+- `src/dex/learnsets.ts` — 新增 randomAbility、getAbilities 函数
+- `src/dex/names.ts` — 支持加载 auto-generated 多语言名称数据
+- `src/dex/pokedex-data.ts` — 新增 getHatchCounter 函数
+- `src/core/creature.ts` — PID 生成、IV 位提取、Shiny XOR 检测、randomAbility
+- `src/core/gender.ts` — 修复阈值为 `genderRate * 32`
+- `src/core/egg.ts` — 使用 getHatchCounter 替代 captureRate 计算孵化步数