# 敌人寻路逼近 + 攻击选择器 实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 新增"寻路逼近（Approach）+ 到攻击范围内按策略选招攻击、攻击时暂停逼近"的敌人交战范式，与现有冲锋（Chase）范式并存。

**Architecture:** 感知系统（`PhysicsPerceptionSystem`）继续管敌人级交战状态（脱战/警戒/追逐）；每个攻击能力**自管圆形攻击触发范围**；AI 状态机（`PerceptionStateMachine`）新增 opt-in 的 `Approach↔Attack` 两态子机做决策；纯逻辑的 `EnemyAttackSelector` 从"够得着+未冷却+LOS+着地"的候选里按 `WeightedRandom`/`Priority` 选招。

**Tech Stack:** Unity 2D、C#、PathBerserker2d 导航、自研 BrainGraph HFSM、NUnit EditMode 测试（Unity Test Runner）。

**设计文档：** `Docs_Dev/superpowers/specs/2026-07-24-enemy-nav-approach-attack-design.md`

**通用验证方式：**
- **编译门**：改动 C# 后，用 MCP `unity_get_compilation_errors` 确认 0 错误。
- **EditMode 测试**：Unity 菜单 `Window > General > Test Runner > EditMode > Run All`（或运行指定类）。
- **提交**：每个 Task 末尾 `git add <改动文件> && git commit`。提交信息用中文 + 类型前缀（`feat(enemy):`/`test(enemy):`）。

---

## 文件结构

**新建：**
- `Assets/_Game/Scripts/Enemies/Abilities/AbilityCategory.cs` — 能力调度分类枚举。
- `Assets/_Game/Scripts/Enemies/Abilities/AttackSelectionMode.cs` — 选招模式枚举。
- `Assets/_Game/Scripts/Enemies/Abilities/IAttackCandidate.cs` — 选择器候选契约。
- `Assets/_Game/Scripts/Enemies/Abilities/EnemyAttackSelector.cs` — 选招器（纯逻辑）。
- `Assets/Tests/EditMode/Enemies/EnemyAttackSelectorTests.cs` — 选招器单测。

**修改：**
- `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs` — +category/weight/rangeRadius/rangeOffset。
- `Assets/_Game/Scripts/Enemies/EnemyStatsSO.cs` — +attackSelectionMode。
- `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs` — 实现 `IAttackCandidate` + `InAttackRange()`。
- `Assets/_Game/Scripts/AI/ICombatant.cs` — +HasEligibleAttack/UseBestAttack。
- `Assets/_Game/Scripts/AI/IEnemyLocomotion.cs` — +Pursue。
- `Assets/_Game/Scripts/Enemies/EnemyLocomotion.cs` — 实现 Pursue。
- `Assets/_Game/Scripts/Enemies/AIBrain/EnemyBrainContext.cs` — 实现 HasEligibleAttack/UseBestAttack。
- `Assets/_Game/Scripts/Enemies/EnemyBase.cs` — 构建 selector + 校验。
- `Assets/_Game/Scripts/Enemies/AIBrain/PerceptionStateMachine.cs` — +ApproachAttack 拓扑。
- `Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs` — FakeCombat +HasEligibleAttack/UseBestAttack。
- `Assets/Tests/EditMode/AI/Fakes/FakeLocomotion.cs` — +Pursue。
- `Assets/Tests/EditMode/AI/PerceptionStateMachineTests.cs` — +ApproachAttack 拓扑测试。

---

## Task 1: 枚举与 SO 字段（选招/射程元数据）

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/AbilityCategory.cs`
- Create: `Assets/_Game/Scripts/Enemies/Abilities/AttackSelectionMode.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/EnemyStatsSO.cs`

- [ ] **Step 1: 建 AbilityCategory 枚举**

`AbilityCategory.cs`：
```csharp
namespace BaseGames.Enemies.Abilities
{
    /// <summary>能力调度分类：攻击选择器只从 <see cref="Attack"/> 类里选招。</summary>
    public enum AbilityCategory
    {
        None,     // 未分类（默认，不参与选招）
        Attack,   // 攻击招式（选择器候选）
        Movement, // 位移/机动
        Utility   // 辅助/增益
    }
}
```

- [ ] **Step 2: 建 AttackSelectionMode 枚举**

`AttackSelectionMode.cs`：
```csharp
namespace BaseGames.Enemies.Abilities
{
    /// <summary>多攻击选招策略。</summary>
    public enum AttackSelectionMode
    {
        WeightedRandom, // 合格集内按 weight 加权随机
        Priority        // 合格集内取 priority 最高（并列取首个）
    }
}
```

- [ ] **Step 3: EnemyAbilitySO 加字段**

在 `EnemyAbilitySO.cs` 的 `priority` 字段之后（`exclusionGroup`/`priority` 所在 Header 块末尾）追加：
```csharp
        [Header("选招（攻击选择器用）")]
        [Tooltip("能力调度分类；攻击选择器只从 Attack 类里选招")]
        public AbilityCategory category = AbilityCategory.None;
        [Tooltip("WeightedRandom 模式下的相对权重（越大越易被选）")]
        [Min(0f)] public float weight = 1f;

        [Header("攻击触发范围（招式自管，圆形）")]
        [Tooltip("触发半径(m)；category==Attack 时必须 > 0，否则永远够不着（Awake 报错）")]
        [Min(0f)] public float rangeRadius = 0f;
        [Tooltip("范围圆心相对敌人的偏移(m)，X 随朝向翻转")]
        public Vector2 rangeOffset = Vector2.zero;
```
> `EnemyAbilitySO` 已 `using UnityEngine;` 且与 `AbilityCategory` 同命名空间，无需额外 using。旧的 `preferredMinRange/preferredMaxRange` 保留不动（降级为编辑器提示）。

- [ ] **Step 4: EnemyStatsSO 加字段**

在 `EnemyStatsSO.cs` 的 `AttackCooldown` 字段附近（战斗参数区）追加：
```csharp
        [Header("攻击选招策略")]
        [Tooltip("到攻击范围内如何从多个候选招里选一个")]
        public BaseGames.Enemies.Abilities.AttackSelectionMode attackSelectionMode
            = BaseGames.Enemies.Abilities.AttackSelectionMode.WeightedRandom;
```

- [ ] **Step 5: 编译门**

用 MCP `unity_get_compilation_errors`，预期：0 错误。

- [ ] **Step 6: 提交**

```bash
git add Assets/_Game/Scripts/Enemies/Abilities/AbilityCategory.cs \
        Assets/_Game/Scripts/Enemies/Abilities/AttackSelectionMode.cs \
        Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs \
        Assets/_Game/Scripts/Enemies/EnemyStatsSO.cs
git commit -m "feat(enemy): 攻击选招元数据(category/weight/圆形射程)与选招模式入 SO"
```

---

## Task 2: 攻击候选契约与 InAttackRange

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/IAttackCandidate.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs`

- [ ] **Step 1: 建 IAttackCandidate 接口**

`IAttackCandidate.cs`：
```csharp
namespace BaseGames.Enemies.Abilities
{
    /// <summary>
    /// 攻击选择器的候选契约。攻击类 <see cref="EnemyAbilityBase"/> 实现之；
    /// 抽象出来使 <see cref="EnemyAttackSelector"/> 可脱离 MonoBehaviour 单测。
    /// </summary>
    public interface IAttackCandidate
    {
        bool  CanUse { get; }              // 未冷却 + 未运行 + 存活
        bool  RequiresLineOfSight { get; } // 是否需要视线（由敌人级 LOS 提供）
        bool  RequiresGrounded { get; }    // 是否需要着地
        float Weight { get; }              // WeightedRandom 权重
        int   Priority { get; }            // Priority 优先级
        bool  InAttackRange();             // 招式自管圆形射程内是否有玩家
        bool  Execute();                   // 触发本招
    }
}
```

- [ ] **Step 2: EnemyAbilityBase 实现 IAttackCandidate**

在 `EnemyAbilityBase.cs`，把类声明改为实现接口：
```csharp
    public abstract class EnemyAbilityBase : MonoBehaviour, IAttackCandidate
```
并在类内（`CanUse` 属性附近）追加以下成员（`CanUse` 已存在，接口自动匹配）：
```csharp
        // ── IAttackCandidate（供 EnemyAttackSelector 选招）──────────────────
        public bool  RequiresLineOfSight => _config != null && _config.requiresLineOfSight;
        public bool  RequiresGrounded    => _config != null && _config.requiresGrounded;
        public float Weight              => _config != null ? _config.weight : 0f;
        public int   Priority            => _config != null ? _config.priority : 0;

        /// <summary>本招圆形攻击范围内是否有玩家（招式自管其射程；LOS 复用敌人级 IsPlayerVisible）。</summary>
        public virtual bool InAttackRange()
        {
            if (_config == null || _config.rangeRadius <= 0f
                || _enemy == null || _enemy.PlayerTransform == null) return false;
            float   sign   = _transform.localScale.x < 0f ? -1f : 1f;
            Vector2 origin = (Vector2)_transform.position
                           + new Vector2(_config.rangeOffset.x * sign, _config.rangeOffset.y);
            float r = _config.rangeRadius;
            return ((Vector2)_enemy.PlayerTransform.position - origin).sqrMagnitude <= r * r;
        }
```
> `Execute()` 与 `CanUse` 已在基类存在，直接满足接口。`_config`/`_enemy`/`_transform` 均为已有受保护字段。

- [ ] **Step 3: 编译门**

MCP `unity_get_compilation_errors`，预期 0 错误。

- [ ] **Step 4: 提交**

```bash
git add Assets/_Game/Scripts/Enemies/Abilities/IAttackCandidate.cs \
        Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs
git commit -m "feat(enemy): EnemyAbilityBase 实现 IAttackCandidate 契约(自管圆形射程)"
```

---

## Task 3: EnemyAttackSelector（选招器）+ 单元测试（TDD）

**Files:**
- Test: `Assets/Tests/EditMode/Enemies/EnemyAttackSelectorTests.cs`
- Create: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAttackSelector.cs`

- [ ] **Step 1: 写失败测试**

`EnemyAttackSelectorTests.cs`：
```csharp
using System.Collections.Generic;
using NUnit.Framework;
using BaseGames.Enemies.Abilities;

namespace BaseGames.Tests.EditMode.Enemies
{
    public class EnemyAttackSelectorTests
    {
        sealed class FakeCandidate : IAttackCandidate
        {
            public bool  CanUseV = true, InRange = true, ReqLOS = false, ReqGround = false, Executed;
            public float WeightV = 1f;
            public int   PriorityV = 0;
            public bool  CanUse => CanUseV;
            public bool  RequiresLineOfSight => ReqLOS;
            public bool  RequiresGrounded => ReqGround;
            public float Weight => WeightV;
            public int   Priority => PriorityV;
            public bool  InAttackRange() => InRange;
            public bool  Execute() { Executed = true; return true; }
        }

        static EnemyAttackSelector Sel(params IAttackCandidate[] cs)
            => new EnemyAttackSelector(new List<IAttackCandidate>(cs));

        [Test]
        public void Empty_NoEligible()
        {
            var s = Sel();
            Assert.IsFalse(s.HasEligible(true, true));
            Assert.IsNull(s.Select(true, true, AttackSelectionMode.Priority));
        }

        [Test]
        public void ExcludesOnCooldown()
        {
            var c = new FakeCandidate { CanUseV = false };
            Assert.IsFalse(Sel(c).HasEligible(true, true));
        }

        [Test]
        public void ExcludesOutOfRange()
        {
            var c = new FakeCandidate { InRange = false };
            Assert.IsFalse(Sel(c).HasEligible(true, true));
        }

        [Test]
        public void ExcludesWhenNeedsLOS_ButNoLOS()
        {
            var c = new FakeCandidate { ReqLOS = true };
            Assert.IsFalse(Sel(c).HasEligible(false, true)); // hasLOS=false
            Assert.IsTrue (Sel(c).HasEligible(true,  true));
        }

        [Test]
        public void ExcludesWhenNeedsGrounded_ButAirborne()
        {
            var c = new FakeCandidate { ReqGround = true };
            Assert.IsFalse(Sel(c).HasEligible(true, false)); // grounded=false
            Assert.IsTrue (Sel(c).HasEligible(true, true));
        }

        [Test]
        public void Priority_PicksHighest()
        {
            var lo = new FakeCandidate { PriorityV = 1 };
            var hi = new FakeCandidate { PriorityV = 5 };
            var pick = Sel(lo, hi).Select(true, true, AttackSelectionMode.Priority);
            Assert.AreSame(hi, pick);
        }

        [Test]
        public void Priority_TieTakesFirstInList()
        {
            var a = new FakeCandidate { PriorityV = 3 };
            var b = new FakeCandidate { PriorityV = 3 };
            var pick = Sel(a, b).Select(true, true, AttackSelectionMode.Priority);
            Assert.AreSame(a, pick);
        }

        [Test]
        public void Priority_SkipsIneligible()
        {
            var blocked = new FakeCandidate { PriorityV = 9, InRange = false }; // 高优但够不着
            var ok      = new FakeCandidate { PriorityV = 1 };
            var pick = Sel(blocked, ok).Select(true, true, AttackSelectionMode.Priority);
            Assert.AreSame(ok, pick);
        }

        [Test]
        public void Weighted_SingleEligible_AlwaysThatOne()
        {
            var only = new FakeCandidate { WeightV = 2f };
            for (int i = 0; i < 20; i++)
                Assert.AreSame(only, Sel(only).Select(true, true, AttackSelectionMode.WeightedRandom));
        }

        [Test]
        public void Weighted_NeverPicksIneligible()
        {
            var bad = new FakeCandidate { WeightV = 100f, InRange = false };
            var ok  = new FakeCandidate { WeightV = 1f };
            for (int i = 0; i < 50; i++)
                Assert.AreSame(ok, Sel(bad, ok).Select(true, true, AttackSelectionMode.WeightedRandom));
        }
    }
}
```

- [ ] **Step 2: 运行确认失败**

Test Runner 运行 `EnemyAttackSelectorTests`，预期：**编译失败**（`EnemyAttackSelector` 未定义）。

- [ ] **Step 3: 实现 EnemyAttackSelector**

`EnemyAttackSelector.cs`：
```csharp
using System.Collections.Generic;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>
    /// 多攻击选招器：从候选（category==Attack）里按"射程 + 冷却 + LOS + 着地"过滤，
    /// 再按 <see cref="AttackSelectionMode"/> 选一个。纯逻辑、无 MonoBehaviour 依赖，可单测。
    /// </summary>
    public sealed class EnemyAttackSelector
    {
        private readonly List<IAttackCandidate> _candidates;

        public EnemyAttackSelector(IEnumerable<IAttackCandidate> candidates)
            => _candidates = new List<IAttackCandidate>(candidates);

        public int Count => _candidates.Count;

        private static bool Eligible(IAttackCandidate c, bool hasLOS, bool grounded)
            => c != null && c.CanUse && c.InAttackRange()
               && (!c.RequiresLineOfSight || hasLOS)
               && (!c.RequiresGrounded    || grounded);

        public bool HasEligible(bool hasLOS, bool grounded)
        {
            for (int i = 0; i < _candidates.Count; i++)
                if (Eligible(_candidates[i], hasLOS, grounded)) return true;
            return false;
        }

        public IAttackCandidate Select(bool hasLOS, bool grounded, AttackSelectionMode mode)
            => mode == AttackSelectionMode.Priority
                ? SelectByPriority(hasLOS, grounded)
                : SelectByWeight(hasLOS, grounded);

        private IAttackCandidate SelectByPriority(bool hasLOS, bool grounded)
        {
            IAttackCandidate best = null;
            for (int i = 0; i < _candidates.Count; i++)
            {
                var c = _candidates[i];
                if (!Eligible(c, hasLOS, grounded)) continue;
                if (best == null || c.Priority > best.Priority) best = c; // 并列取首个
            }
            return best;
        }

        private IAttackCandidate SelectByWeight(bool hasLOS, bool grounded)
        {
            float total = 0f;
            for (int i = 0; i < _candidates.Count; i++)
            {
                var c = _candidates[i];
                if (Eligible(c, hasLOS, grounded)) total += Mathf.Max(0f, c.Weight);
            }
            if (total <= 0f) return SelectByPriority(hasLOS, grounded); // 权重全 0 → 退化为确定性取首个合格
            float roll = Random.value * total;
            for (int i = 0; i < _candidates.Count; i++)
            {
                var c = _candidates[i];
                if (!Eligible(c, hasLOS, grounded)) continue;
                roll -= Mathf.Max(0f, c.Weight);
                if (roll <= 0f) return c;
            }
            return null; // 理论不达（浮点边界兜底）
        }
    }
}
```

- [ ] **Step 4: 运行确认通过**

Test Runner 运行 `EnemyAttackSelectorTests`，预期：全部 PASS。若 `Assets/Tests/EditMode/Enemies/` 需要 `.asmdef`——不需要，EditMode 测试同属 `BaseGames.Tests.EditMode` 程序集（已引用 `BaseGames.Enemies`）。

- [ ] **Step 5: 提交**

```bash
git add Assets/_Game/Scripts/Enemies/Abilities/EnemyAttackSelector.cs \
        Assets/Tests/EditMode/Enemies/EnemyAttackSelectorTests.cs
git commit -m "feat(enemy): EnemyAttackSelector 选招器(射程+冷却+LOS+着地过滤,两模式选招)+单测"
```

---

## Task 4: ICombatant 扩展 + EnemyBrainContext 实现 + FakeCombat

**Files:**
- Modify: `Assets/_Game/Scripts/AI/ICombatant.cs`
- Modify: `Assets/_Game/Scripts/Enemies/AIBrain/EnemyBrainContext.cs`
- Modify: `Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs`

- [ ] **Step 1: ICombatant 加两方法**

在 `ICombatant.cs` 接口内追加：
```csharp
        /// <summary>攻击选择器中是否有"够得着且未冷却"的招（供 Approach→Attack 转换）。</summary>
        bool HasEligibleAttack();

        /// <summary>按敌人配置的选招模式选一个攻击并触发；返回是否成功触发。</summary>
        bool UseBestAttack();
```

- [ ] **Step 2: EnemyBrainContext 实现**

在 `EnemyBrainContext.cs` 的 `// ---- ICombatant ----` 区块末尾（`InterruptAbilities` 之后）追加：
```csharp
        public bool HasEligibleAttack()
        {
            var sel = _enemy.AttackSelector;
            if (sel == null) return false;
            return sel.HasEligible(_enemy.IsPlayerVisible(), _enemy.Movement != null && _enemy.Movement.IsGrounded);
        }

        public bool UseBestAttack()
        {
            var sel = _enemy.AttackSelector;
            if (sel == null) return false;
            var mode = _enemy.StatsSO != null
                ? _enemy.StatsSO.attackSelectionMode
                : Abilities.AttackSelectionMode.WeightedRandom;
            bool grounded = _enemy.Movement != null && _enemy.Movement.IsGrounded;
            var pick = sel.Select(_enemy.IsPlayerVisible(), grounded, mode);
            return pick != null && pick.Execute();
        }
```
> `_enemy.AttackSelector` 在 Task 6 添加。此处引用即可（同一提交在 Task 6 前无法编译——所以 Task 4 的编译门与 Task 6 合并验证；见 Step 5）。为避免"引用未定义成员"，**先做 Task 6 的 Step 1（加 AttackSelector 属性桩）再回本任务**——或按下方 Step 顺序：本任务与 Task 6 连续实现、统一编译门。

- [ ] **Step 3: FakeCombat 实现新方法**

在 `FakeAiContext.cs` 的 `FakeCombat` 类内追加（供状态机测试控制）：
```csharp
        public bool Eligible;                    // 测试控制：是否有合格攻击
        public bool HasEligibleAttack() => Eligible;
        public bool UseBestAttack()
        {
            if (!Eligible) return false;
            Used.Add("best"); Running = "best"; return true;
        }
```

- [ ] **Step 4: 检查其它 ICombatant 实现者**

用 Grep 搜 `: ICombatant` / `ICombatant,` 确认只有 `EnemyBrainContext` 与 `FakeCombat` 两处实现；若有其它实现者，一并补齐两方法（否则编译失败）。

- [ ] **Step 5: 编译门（与 Task 6 合并）**

因 `_enemy.AttackSelector` 依赖 Task 6，**先完成 Task 6 再统一跑编译门**。届时 MCP `unity_get_compilation_errors` 预期 0 错误。

- [ ] **Step 6: 提交（与 Task 6 合并提交，或本任务单独提交待 Task 6 后编译通过再提交）**

```bash
git add Assets/_Game/Scripts/AI/ICombatant.cs \
        Assets/_Game/Scripts/Enemies/AIBrain/EnemyBrainContext.cs \
        Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs
git commit -m "feat(enemy): ICombatant 增加 HasEligibleAttack/UseBestAttack + Context/Fake 实现"
```

---

## Task 5: IEnemyLocomotion.Pursue + EnemyLocomotion 实现 + FakeLocomotion

**Files:**
- Modify: `Assets/_Game/Scripts/AI/IEnemyLocomotion.cs`
- Modify: `Assets/_Game/Scripts/Enemies/EnemyLocomotion.cs`
- Modify: `Assets/Tests/EditMode/AI/Fakes/FakeLocomotion.cs`

- [ ] **Step 1: 接口加 Pursue**

在 `IEnemyLocomotion.cs` 接口内 `Approach` 之后追加：
```csharp
        void Pursue(Vector2 target);         // 寻路逼近(RunSpeed)：每帧朝 target 重寻路(底层防抖)
```

- [ ] **Step 2: EnemyLocomotion 实现 Pursue**

在 `EnemyLocomotion.cs` 的 `MoveTo` 方法之后追加：
```csharp
        /// <summary>
        /// 寻路逼近：设 Approach 模式 + RunSpeed，每帧朝 target 发一次寻路请求（底层 Nav 自带防抖/受阻/NavLink）。
        /// 与一次性 <see cref="MoveTo"/> 的区别：设跑速、语义为"持续追向移动目标"。供 AI 追击态每帧调用。
        /// </summary>
        public void Pursue(Vector2 target)
        {
            _mode = LocomotionMode.Approach;
            _approachTarget = null;
            if (_enemy?.Stats != null) _enemy.Nav?.SetSpeed(_enemy.Stats.RunSpeed);
            _enemy?.MoveTo(target);
        }
```

- [ ] **Step 3: FakeLocomotion 实现 Pursue**

在 `FakeLocomotion.cs` 类内追加：
```csharp
        public void Pursue(Vector2 p) { CurrentMode = LocomotionMode.Approach; Calls.Add("Pursue"); }
```

- [ ] **Step 4: 编译门**

MCP `unity_get_compilation_errors`，预期 0 错误。

- [ ] **Step 5: 提交**

```bash
git add Assets/_Game/Scripts/AI/IEnemyLocomotion.cs \
        Assets/_Game/Scripts/Enemies/EnemyLocomotion.cs \
        Assets/Tests/EditMode/AI/Fakes/FakeLocomotion.cs
git commit -m "feat(enemy): IEnemyLocomotion 增加 Pursue 寻路逼近原语(RunSpeed)"
```

---

## Task 6: EnemyBase 构建选择器 + 根因校验

**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/EnemyBase.cs`

- [ ] **Step 1: 加 AttackSelector 属性与字段**

在 `EnemyBase.cs` 的 `Abilities` 属性附近追加：
```csharp
        public Abilities.EnemyAttackSelector AttackSelector => _attackSelector;
        private Abilities.EnemyAttackSelector _attackSelector;
```

- [ ] **Step 2: 在 Abilities 收集后构建选择器**

在 `EnemyBase.Awake`（或调用 `_abilities.CollectFrom(gameObject)` 之处）**紧随其后**追加：
```csharp
            BuildAttackSelector();
```
并在类内新增方法：
```csharp
        /// <summary>
        /// 从已注册能力里收集 category==Attack 的候选，构建攻击选择器。
        /// 根因校验：攻击招 rangeRadius<=0（永远够不着）显式报错，不静默兜底（CLAUDE.md §6）。
        /// </summary>
        private void BuildAttackSelector()
        {
            var candidates = new System.Collections.Generic.List<Abilities.IAttackCandidate>();
            var all = _abilities?.All;
            if (all != null)
            {
                for (int i = 0; i < all.Count; i++)
                {
                    var ab = all[i];
                    if (ab == null || ab.Config == null) continue;
                    if (ab.Config.category != Abilities.AbilityCategory.Attack) continue;
                    if (ab.Config.rangeRadius <= 0f)
                        Debug.LogError($"[EnemyBase] 攻击招 '{ab.Config.abilityId}' 的 rangeRadius<=0，" +
                                       "永远够不着玩家。请在其 EnemyAbilitySO 上配置攻击触发半径。", ab);
                    candidates.Add(ab); // EnemyAbilityBase 实现 IAttackCandidate
                }
            }
            _attackSelector = new Abilities.EnemyAttackSelector(candidates);
        }
```
> 是否报"配了 ApproachAttack 却无候选"由使用该风格的敌人在其 AI/配置侧校验（本期以 rangeRadius 校验为主，够暴露最常见漏配）。`_abilities` 为已有字段（`Abilities` 属性的后备）。

- [ ] **Step 3: 编译门（含 Task 4 改动）**

MCP `unity_get_compilation_errors`，预期 0 错误（此时 Task 4 的 `_enemy.AttackSelector` 引用已可解析）。

- [ ] **Step 4: 运行既有 EditMode 测试确认无回归**

Test Runner 运行 `EnemyAttackSelectorTests` + `PerceptionStateMachineTests`（既有），预期全 PASS。

- [ ] **Step 5: 提交（可与 Task 4 合并）**

```bash
git add Assets/_Game/Scripts/Enemies/EnemyBase.cs
git commit -m "feat(enemy): EnemyBase 构建攻击选择器(收集 Attack 类+rangeRadius 根因校验)"
```

---

## Task 7: PerceptionStateMachine 的 ApproachAttack 拓扑 + 测试（TDD）

**Files:**
- Test: `Assets/Tests/EditMode/AI/PerceptionStateMachineTests.cs`
- Modify: `Assets/_Game/Scripts/Enemies/AIBrain/PerceptionStateMachine.cs`

- [ ] **Step 1: 写失败测试**

在 `PerceptionStateMachineTests.cs` 类内追加 ApproachAttack 构图工厂与测试：
```csharp
        // ── ApproachAttack 交战风格 ───────────────────────────────────────
        static AiGraph GraphApproach(string entry = "Idle")
        {
            var b = new BrainBuilder();
            PerceptionStateMachine.Add(b, new PerceptionStateMachine.Config
            {
                Idle = "Idle", Patrol = "Patrol", Alert = "Alert", Death = "Death",
                Entry = entry, Rest = "Patrol",
                IdleMode = LocomotionMode.Idle, PatrolMode = LocomotionMode.Patrol, AlertMode = LocomotionMode.Face,
                Engagement = PerceptionStateMachine.EngagementStyle.ApproachAttack,
                ApproachState = "Approach", AttackState = "Attack",
            });
            return b.Build();
        }

        [Test]
        public void Approach_EnteredFromChaseZone_UsesPursue()
        {
            var ctx = new Ctx();
            var rt = new AiRuntime(GraphApproach(), ctx);
            ctx.S.Chase = true;
            rt.Tick(0.1f);
            Assert.AreEqual("Approach", rt.CurrentStateName);
            CollectionAssert.Contains(ctx.L.Calls, "Pursue"); // 寻路逼近意图
        }

        [Test]
        public void Approach_ToAttack_WhenEligibleAttack()
        {
            var ctx = new Ctx();
            var rt = new AiRuntime(GraphApproach(), ctx);
            ctx.S.Chase = true; rt.Tick(0.1f);        // → Approach
            ctx.C.Eligible = true;                     // 有招够得着
            rt.Tick(0.1f);
            Assert.AreEqual("Attack", rt.CurrentStateName);
            CollectionAssert.Contains(ctx.C.Used, "best"); // 选招触发
        }

        [Test]
        public void Attack_StopsLocomotion_OnEnter()
        {
            var ctx = new Ctx();
            var rt = new AiRuntime(GraphApproach(), ctx);
            ctx.S.Chase = true; rt.Tick(0.1f);
            ctx.C.Eligible = true; rt.Tick(0.1f);      // → Attack
            CollectionAssert.Contains(ctx.L.Calls, "Stop"); // 攻击时暂停逼近
        }

        [Test]
        public void Attack_ToApproach_WhenAttackDone()
        {
            var ctx = new Ctx();
            var rt = new AiRuntime(GraphApproach(), ctx);
            ctx.S.Chase = true; rt.Tick(0.1f);
            ctx.C.Eligible = true; rt.Tick(0.1f);      // → Attack, Running="best"
            Assert.AreEqual("Attack", rt.CurrentStateName);
            ctx.C.Running = null;                       // 攻击打完
            rt.Tick(0.1f);
            Assert.AreEqual("Approach", rt.CurrentStateName); // 回逼近重判
        }

        [Test]
        public void Approach_ToRest_WhenLeftAllZones()
        {
            var ctx = new Ctx();
            var rt = new AiRuntime(GraphApproach(), ctx);
            ctx.S.Chase = true; rt.Tick(0.1f);          // → Approach
            ctx.S.Chase = false; ctx.S.Vision = false;  // 脱离全部感知
            rt.Tick(0.1f);
            Assert.AreEqual("Patrol", rt.CurrentStateName);
        }

        [Test]
        public void ApproachAttack_Death_IsGlobal()
        {
            var ctx = new Ctx();
            var rt = new AiRuntime(GraphApproach(), ctx);
            ctx.S.Chase = true; rt.Tick(0.1f);
            rt.Send(AiSignal.Died); rt.Tick(0.1f);
            Assert.AreEqual("Death", rt.CurrentStateName);
        }
```

- [ ] **Step 2: 运行确认失败**

Test Runner 运行 `PerceptionStateMachineTests`，预期：**编译失败**（`EngagementStyle`/`ApproachState`/`AttackState` 未定义）。

- [ ] **Step 3: PerceptionStateMachine 加 EngagementStyle + Config 字段**

在 `PerceptionStateMachine` 类内、`Config` 之上加枚举：
```csharp
        /// <summary>交战风格：单一冲锋能力，或"寻路逼近 + 选招攻击"两态子机。</summary>
        public enum EngagementStyle { ChaseAbility, ApproachAttack }
```
在 `Config` 内追加字段：
```csharp
            // 交战风格（默认冲锋能力，保持现状）；ApproachAttack 时启用 Approach↔Attack 两态子机。
            public EngagementStyle Engagement = EngagementStyle.ChaseAbility;
            public string ApproachState = "Approach";
            public string AttackState   = "Attack";
```

- [ ] **Step 4: 改 Add 方法：交战入口与子机分支**

将 `Add` 中"进追击条件"与"追击状态构建"两段改为如下（其余不变）。

先把 `canChase` 计算改为仅在 `ChaseAbility` 风格下应用冷却门：
```csharp
            string chaseId = c.ChaseAbilityId;
            System.Func<IAiContext, bool> canChase;
            string chaseLabel;
            if (c.Engagement == EngagementStyle.ChaseAbility && c.PatrolBetweenChases)
            {
                canChase   = x => x.Sensor.InChaseZone() && x.Combat.CanUseAbility(chaseId);
                chaseLabel = "InChaseZone+offCD";
            }
            else
            {
                canChase   = x => x.Sensor.InChaseZone();
                chaseLabel = "InChaseZone";
            }

            // 交战入口态：冲锋风格=Chase；逼近风格=Approach
            string combatEntry = c.Engagement == EngagementStyle.ApproachAttack ? c.ApproachState : c.Chase;
```
把 Idle/Patrol/Alert 三处的 `.To(c.Chase)` 改为 `.To(combatEntry)`：
```csharp
            AddLocomotionState(b, c.Idle, c.IdleMode)
                .To(combatEntry).When(canChase, chaseLabel)
                .To(c.Alert).When(x => HasAlert(x) && x.Sensor.InVisionZone(), "InVision+HasAlert");
            AddLocomotionState(b, c.Patrol, c.PatrolMode)
                .To(combatEntry).When(canChase, chaseLabel)
                .To(c.Alert).When(x => HasAlert(x) && x.Sensor.InVisionZone(), "InVision+HasAlert");

            AddLocomotionState(b, c.Alert, c.AlertMode)
                .To(combatEntry).When(canChase, chaseLabel)
                .To(c.Rest).When(x => !x.Sensor.InVisionZone(), "leftVision");
```
把原"追击退出"整段（`var chase = AddAbilityState(...)` 那段）替换为按风格分支：
```csharp
            if (c.Engagement == EngagementStyle.ApproachAttack)
            {
                // Approach：寻路逼近；有招够得着→Attack；脱离全部感知→R
                b.State(c.ApproachState)
                    .OnEnter(x => x.Locomotion.Pursue(x.Sensor.LastKnown))
                    .Tick(x => x.Locomotion.Pursue(x.Sensor.LastKnown))
                    .OnExit(x => x.Locomotion.Stop())
                    .To(c.AttackState).When(x => x.Combat.HasEligibleAttack(), "attackInRange")
                    .To(c.Rest).When(x => !x.Sensor.InChaseZone() && !x.Sensor.InVisionZone(), "leftAllZones");

                // Attack：停逼近 + 选招攻击；打完回 Approach；脱离感知→R
                b.State(c.AttackState)
                    .OnEnter(x => { x.Locomotion.Stop(); x.Combat.UseBestAttack(); })
                    .OnExit(x => x.Combat.InterruptAbilities())
                    .To(c.ApproachState).When(x => !x.Combat.IsAbilityRunning(), "attackDone")
                    .To(c.Rest).When(x => !x.Sensor.InChaseZone() && !x.Sensor.InVisionZone(), "leftAllZones");
            }
            else
            {
                var chase = AddAbilityState(b, c.Chase, chaseId);
                if (c.PatrolBetweenChases)
                    chase.To(c.Rest).When(x => !x.Combat.IsAbilityRunning(chaseId), "dashDone→CD");
                else
                    chase.To(c.Rest).When(x => !x.Sensor.InChaseZone() && !x.Sensor.InVisionZone(), "leftAllZones");
            }
```
> 保留 `AddAbilityState(b, c.Death, c.DeathAbilityId);` 与全局 Died 转换不变。`combatEntry` 用于三处升级转换；`ApproachAttack` 风格下 `c.Chase` 不建态。

- [ ] **Step 5: 运行确认通过**

Test Runner 运行 `PerceptionStateMachineTests`（含既有 ChaseAbility 用例 + 新 ApproachAttack 用例），预期：全部 PASS。既有冲锋用例应不受影响（默认 `Engagement=ChaseAbility`）。

- [ ] **Step 6: 编译门**

MCP `unity_get_compilation_errors`，预期 0 错误。

- [ ] **Step 7: 提交**

```bash
git add Assets/_Game/Scripts/Enemies/AIBrain/PerceptionStateMachine.cs \
        Assets/Tests/EditMode/AI/PerceptionStateMachineTests.cs
git commit -m "feat(enemy): PerceptionStateMachine 增加 ApproachAttack 风格(寻路逼近↔选招攻击)+测试"
```

---

## Task 8: 编辑器 —— 攻击射程 Gizmo 与自检校验

**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs`（`#if UNITY_EDITOR` Gizmo）
- Modify: 自检工具（`SOValidationRunner` 所在文件，用 Grep 定位）

- [ ] **Step 1: 攻击范围 Gizmo（选中敌人可见）**

在 `EnemyAbilityBase.cs` 末尾追加（类内，`#if UNITY_EDITOR`）：
```csharp
#if UNITY_EDITOR
        private void OnDrawGizmosSelected()
        {
            if (_config == null || _config.category != AbilityCategory.Attack || _config.rangeRadius <= 0f) return;
            float   sign   = transform.localScale.x < 0f ? -1f : 1f;
            Vector3 origin = transform.position
                           + new Vector3(_config.rangeOffset.x * sign, _config.rangeOffset.y, 0f);
            UnityEditor.Handles.color = new Color(1f, 0.4f, 0.2f, 0.9f);
            UnityEditor.Handles.DrawWireDisc(origin, Vector3.forward, _config.rangeRadius);
            UnityEditor.Handles.Label(origin, $"{_config.abilityId} range");
        }
#endif
```
> `_config` 在编辑期未 Awake 也可用（SerializeField）；`_enemy`/`_transform` 不依赖，用 `transform` 直接取。

- [ ] **Step 2: 编译门**

MCP `unity_get_compilation_errors`，预期 0 错误。

- [ ] **Step 3: SOValidationRunner 加校验项（若存在该扩展点）**

用 Grep 定位 `SOValidationRunner`。若其对 `EnemyAbilitySO` 有逐资产校验钩子，追加：`category==Attack` 且 `rangeRadius<=0` → 记为校验失败（附资产路径与 `abilityId`）。若该工具无按类型钩子，则跳过本步（运行时 `BuildAttackSelector` 的 `LogError` 已兜住根因暴露），并在提交信息注明"运行时已校验，SO 静态校验待工具支持"。

- [ ] **Step 4: 提交**

```bash
git add Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs
# 若改了自检工具，一并 add 其文件
git commit -m "feat(enemy): 攻击能力射程 Gizmo + category==Attack 的 rangeRadius 自检"
```

---

## Task 9: 手动 / PlayMode 验收

**Files:** 无（场景内验证）

- [ ] **Step 1: 准备测试敌人**

在 `TestRoomA`（或用 ChaoFeng）：给一个敌人挂 ≥2 个攻击能力（各配 `category=Attack`、不同 `rangeRadius`/`rangeOffset`、`weight`/`priority`），其 `EnemyStatsSO.attackSelectionMode` 先设 `WeightedRandom`。其 AI 定义（`AiScript`）改用 `Engagement=ApproachAttack`（参照 `E001CaoZhiAi` 的 `PerceptionStateMachine.Add` 配置，去掉 `ChaseAbilityId`、加 `Engagement`）。确保敌人身上有寻路组件（`EnemyNavAgent`）与场景已烘焙 PB2d 导航面（含隔沟处的 Jump/Fall NavLink）。

- [ ] **Step 2: 验证寻路逼近**

进 Play，让玩家站在与敌人**隔着平台缺口**的位置且在 `aggro` 范围内。预期：敌人**沿寻路路径**（走到跳点→跳/落 NavLink→过去）逼近玩家，而非直线卡在缺口边。

- [ ] **Step 3: 验证到范围选招攻击 + 暂停逼近**

玩家进入某招 `rangeRadius`。预期：敌人**停下逼近**、播该招攻击；打完回逼近；若仍在范围且招就绪→再次选招（`WeightedRandom` 下多次交战招式有变化）。切 `attackSelectionMode=Priority` 复验：稳定优先高 `priority` 招。

- [ ] **Step 4: 验证脱战回退**

玩家跑出全部感知区。预期：敌人退出交战、回巡逻（Rest=Patrol）。

- [ ] **Step 5: 验证根因校验**

临时把某攻击招 `rangeRadius` 设 0，进 Play。预期：Console 出现 `[EnemyBase] 攻击招 '...' 的 rangeRadius<=0` 报错（不静默）。验证后改回。

- [ ] **Step 6: 记录结果**

把验收结论（通过/问题）记入 `Docs_Dev/Verification/`（沿用现有验证文档风格）。若全通过，本功能完成。

---

## 自检记录（写计划时）

- **Spec 覆盖**：§2 职责边界→Task 1/2/6/7；§4.1 SO 字段→Task 1；§4.2 InAttackRange→Task 2；§4.3 选择器→Task 3；§4.4 StatsSO→Task 1；§4.5 ICombatant→Task 4；§4.6 Pursue→Task 5；§4.7 状态机→Task 7；§5 边界/校验→Task 6/9；§6 测试→Task 3/7/9；§7 脚手架/Gizmo/自检→Task 8。全部有对应任务。
- **类型一致性**：`EnemyAttackSelector(IEnumerable<IAttackCandidate>)`、`HasEligible(bool,bool)`、`Select(bool,bool,AttackSelectionMode)`、`ICombatant.HasEligibleAttack()/UseBestAttack()`、`IEnemyLocomotion.Pursue(Vector2)`、`EnemyBase.AttackSelector`、`Config.Engagement/ApproachState/AttackState` —— 各任务引用一致。
- **顺序依赖**：Task 4（引用 `EnemyBase.AttackSelector`）需与 Task 6 连续实现、统一编译门（已在 Task 4 Step 2/5 注明）。