docs(enemy): 移除寻路库实现计划(10任务/6阶段,TDD+编译门+回归门+PlayMode验收)

2026-07-28 10:53:21 +08:00
parent d74a2b6646
commit d9ec0a4f6e
1 changed files with 849 additions and 0 deletions
@@ -0,0 +1,849 @@
+# 移除寻路库 / 敌人导航框架重构 实现计划
+
+> **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:** 用约 200 行的"直接移动 + 地形夹紧"导航替换 405 行第三方寻路适配层，删除第三方寻路包（21,069 行）及对其源码的 4 处修改，同时收敛 3 处重复的卡死检测并修复 Pace 翻向缺陷。
+
+**Architecture:** 可达性由 `EnemyMovement` 的墙/悬崖夹紧天然表达——"走过去、被夹停就是边界"，不重建任何图/段结构。导航接口从 20+ 成员瘦身为 7 成员的 `IEnemyNavigator`，地面/飞行两个实现；巡逻策略与 AI 决策层契约不变。
+
+**Tech Stack:** Unity 2022.3、C#、NUnit EditMode（经 MCP `unity_testing_run_tests` 运行）。
+
+**设计文档：** `Docs_Dev/superpowers/specs/2026-07-28-enemy-navigation-without-pathfinding-design.md`
+
+**通用验证（每个 Task 都要做）：**
+- **编译门**：MCP `unity_execute_menu_item("Assets/Refresh")` → 等约 10 秒 → `unity_get_compilation_errors`，预期 0 错误。
+- **测试门**：MCP `unity_testing_run_tests({mode:"EditMode"})` → `unity_testing_get_job(jobId)`。**当前基线 191 条**，新增测试后基线上升（各 Task 注明）。
+- **提交**：中文 + 类型前缀。每个 Task 独立提交。
+
+**关键既有事实（已核实，可直接依赖）：**
+- 硬依赖 `using PathBerserker2d` 的仅 **4 个文件**：`Navigation/EnemyNavAgent.cs`、`Editor/Enemies/Navigation/NavSurfaceBakeShortcut.cs`、`Editor/Scene/SceneObjectPlacerTool.cs`、`Editor/Scene/SceneScaffoldTools.cs`。其余文件仅在注释提及。
+- `NavLinkType` / `INavLinkHandler` 是**项目自有抽象**，不含第三方类型。
+- **Boss 代码完全不引用导航**（无 `.Nav`/`IPathAgent`/`MoveTo`/`Locomotion`），其预制体上的导航组件是冗余件。
+- 敌人预制体除 `ENM_ChaoFeng` 外均已删除；场景敌人实例只有 `TestRoomA` 的 `ENM_CaoZhi`。
+- ⚠ **同名陷阱**：`UI/MainMenu/DataDrivenMainMenuController.cs` 的 `Nav` 是 **UI 导航栈**，**不得改动**。
+
+---
+
+## 文件结构
+
+**新建：**
+- `Assets/_Game/Scripts/Enemies/StallDetector.cs` — 推进停滞检测（纯逻辑 struct）
+- `Assets/_Game/Scripts/Enemies/IEnemyNavigator.cs` — 新导航接口 + `NullEnemyNavigator`
+- `Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs` — 地面直接移动导航
+- `Assets/Tests/EditMode/Enemies/StallDetectorTests.cs`
+- `Assets/Tests/EditMode/Enemies/GroundNavigatorLogicTests.cs`
+
+**修改：** `EnemyLocomotion.cs`、`RushAbility.cs`、`EnemyBase.cs`、`EnemyLocomotionEditor.cs`、`FlyingDirectNavigator.cs`(→`FlyingNavigator.cs`)、2 个 asmdef、3 个编辑器脚本
+
+**删除：** `IPathAgent.cs`、`Navigation/EnemyNavAgent.cs`、`Editor/Enemies/Navigation/NavSurfaceBakeShortcut.cs`、`Assets/PathBerserker2d/`
+
+---
+
+# 阶段 P0：修 Pace 翻向缺陷 + 收敛卡死检测
+
+> 此阶段与寻路库无关，独立成立。完成后寻路库仍在。
+
+## Task 1: `StallDetector` 纯逻辑 struct（TDD）
+
+**Files:**
+- Test: `Assets/Tests/EditMode/Enemies/StallDetectorTests.cs`
+- Create: `Assets/_Game/Scripts/Enemies/StallDetector.cs`
+
+- [ ] **Step 1: 先写失败测试**
+
+创建 `Assets/Tests/EditMode/Enemies/StallDetectorTests.cs`：
+```csharp
+using NUnit.Framework;
+using BaseGames.Enemies;
+
+namespace BaseGames.Tests.EditMode.Enemies
+{
+    /// <summary>
+    /// StallDetector：窗口内净位移不足即判停滞。
+    /// 该逻辑原本在 3 处各写一遍（巡逻 Pace / 导航层 / 冲锋），此处集中钉住行为。
+    /// </summary>
+    public class StallDetectorTests
+    {
+        const float Window = 0.5f, MinProgress = 0.05f;
+
+        [Test]
+        public void BeforeWindowElapses_NeverStalled()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            d.Reset(0f);
+            Assert.IsFalse(d.Tick(0f, 0.1f));   // 完全没动，但窗口未到
+            Assert.IsFalse(d.Tick(0f, 0.1f));
+        }
+
+        [Test]
+        public void NoProgressOverWindow_Stalled()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            d.Reset(0f);
+            Assert.IsFalse(d.Tick(0f, 0.4f));
+            Assert.IsTrue (d.Tick(0f, 0.2f));   // 累计 0.6s ≥ 窗口，净位移 0
+        }
+
+        [Test]
+        public void EnoughProgressOverWindow_NotStalled()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            d.Reset(0f);
+            Assert.IsFalse(d.Tick(1f, 0.6f));   // 位移 1m 远超阈值
+        }
+
+        [Test]
+        public void ProgressJustBelowThreshold_Stalled()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            d.Reset(0f);
+            Assert.IsTrue(d.Tick(0.04f, 0.6f)); // 0.04 < 0.05
+        }
+
+        [Test]
+        public void ProgressCountsBothDirections()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            d.Reset(0f);
+            Assert.IsFalse(d.Tick(-1f, 0.6f));  // 向左移动同样算推进
+        }
+
+        [Test]
+        public void AfterStalled_WindowRestartsFromCurrentPosition()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            d.Reset(0f);
+            Assert.IsTrue (d.Tick(0f, 0.6f));   // 第一次判停滞
+            Assert.IsFalse(d.Tick(0f, 0.1f));  // 窗口已重开，未到期
+            Assert.IsTrue (d.Tick(0f, 0.6f));  // 再次到期且仍无推进
+        }
+
+        [Test]
+        public void Reset_ClearsAccumulatedTime()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            d.Reset(0f);
+            d.Tick(0f, 0.4f);
+            d.Reset(0f);                        // 重开窗口
+            Assert.IsFalse(d.Tick(0f, 0.2f));  // 只累计了 0.2s
+        }
+
+        [Test]
+        public void WithoutReset_FirstTickInitializes()
+        {
+            var d = new StallDetector(Window, MinProgress);
+            Assert.IsFalse(d.Tick(5f, 1f));     // 未 Reset 时首帧只做初始化，不误判
+        }
+    }
+}
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+MCP：`Assets/Refresh` → 等 10 秒 → `unity_get_compilation_errors`。
+预期：**编译失败**，报 `StallDetector` 不存在。
+
+- [ ] **Step 3: 实现**
+
+创建 `Assets/_Game/Scripts/Enemies/StallDetector.cs`：
+```csharp
+using UnityEngine;
+
+namespace BaseGames.Enemies
+{
+    /// <summary>
+    /// 推进停滞检测：滑动窗口内的**净水平位移**不足阈值即判为停滞。
+    /// 用于"命令了移动却推不动"的兜底（撞上未纳入检测层的碰撞体、贴墙微抖等）。
+    ///
+    /// <para>用净位移而非逐帧差值，避免"贴墙推进-被弹回"的微抖每帧重置计数。</para>
+    /// <para><b>调用方须以字段持有本结构</b>（struct 的方法会就地修改字段）；
+    /// 开始移动 / 更换目标后调用 <see cref="Reset"/> 重开窗口。</para>
+    /// </summary>
+    public struct StallDetector
+    {
+        private readonly float _windowSeconds;
+        private readonly float _minProgress;
+        private float _timer;
+        private float _startX;
+        private bool  _initialized;
+
+        /// <param name="windowSeconds">判定窗口时长（秒）。</param>
+        /// <param name="minProgress">窗口内所需的最小净位移（米）。</param>
+        public StallDetector(float windowSeconds, float minProgress)
+        {
+            _windowSeconds = windowSeconds;
+            _minProgress   = minProgress;
+            _timer         = 0f;
+            _startX        = 0f;
+            _initialized   = false;
+        }
+
+        /// <summary>以当前位置重开窗口。</summary>
+        public void Reset(float currentX)
+        {
+            _startX      = currentX;
+            _timer       = 0f;
+            _initialized = true;
+        }
+
+        /// <summary>
+        /// 推进一帧。返回 true 表示本窗口内推进不足（停滞）；返回 true 后窗口自动以当前位置重开。
+        /// </summary>
+        public bool Tick(float currentX, float deltaTime)
+        {
+            if (!_initialized) { Reset(currentX); return false; }
+
+            _timer += deltaTime;
+            if (_timer < _windowSeconds) return false;
+
+            bool stalled = Mathf.Abs(currentX - _startX) < _minProgress;
+            _startX = currentX;
+            _timer  = 0f;
+            return stalled;
+        }
+    }
+}
+```
+
+- [ ] **Step 4: 编译门 + 测试**
+
+预期 0 错误；EditMode **199 条**全绿（191 + 新增 8）。
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add Assets/_Game/Scripts/Enemies/StallDetector.cs Assets/Tests/EditMode/Enemies/StallDetectorTests.cs
+git commit -m "feat(enemy): 新增 StallDetector 推进停滞检测(+8 单测),为收敛三处重复实现做准备"
+```
+
+---
+
+## Task 2: 三处改用 `StallDetector` + 修复 Pace 翻向缺陷
+
+**Files:**
+- Modify: `Assets/_Game/Scripts/Enemies/Navigation/EnemyLocomotion.cs`
+- Modify: `Assets/_Game/Scripts/Enemies/Abilities/RushAbility.cs`
+- Modify: `Assets/_Game/Scripts/Enemies/Navigation/EnemyNavAgent.cs`
+
+- [ ] **Step 1: `EnemyLocomotion` — Pace 改用 StallDetector 并修翻向**
+
+字段区把 `_paceWindowStartX` / `_paceWindowFrames` 两个字段替换为：
+```csharp
+        // Pace 推进停滞检测（原为 12 帧计数，@60fps ≈ 0.2s，改用统一原语并保持观感）
+        private StallDetector _paceStall = new StallDetector(0.2f, 0.05f);
+```
+
+把 `TickPatrol()` 的 `case PatrolStrategy.Pace:` 整段替换为：
+```csharp
+                case PatrolStrategy.Pace: // 撞墙/悬崖翻向的来回踱步（速度驱动，不依赖 nav）
+                    var mv = _enemy.Movement;
+                    // 用与移动层夹紧同一判定(WouldBlockAhead，即时按请求方向+碰撞体前缘)，
+                    // 保证"夹停在地形边缘"与"掉头"一致，不会夹停却不翻向。
+                    bool blocked = mv != null && mv.WouldBlockAhead(_paceDir);
+                    // 兜底卡死检测：命令前进但窗口内净位移过小(撞上未挂检测层的墙/卡角，含贴墙微抖)也视为受阻。
+                    if (_paceStall.Tick(_enemy.transform.position.x, Time.deltaTime)) blocked = true;
+
+                    // 翻向：首次受阻翻一次(边沿触发，天然消抖)；或"持续受阻但反方向畅通"也翻——
+                    // 后者修复"顶着堵侧却因边沿触发失效而永远转不回来"的死锁。
+                    // 两侧都堵(窄台)时只有边沿那一次翻向，之后保持，不来回抖。
+                    bool oppositeFree = mv != null && !mv.WouldBlockAhead(-_paceDir);
+                    if (blocked && (!_paceBlockedPrev || oppositeFree))
+                    {
+                        _paceDir = -_paceDir;
+                        _paceStall.Reset(_enemy.transform.position.x); // 翻向后重开窗口
+                    }
+                    _paceBlockedPrev = blocked;
+                    _enemy.MoveInDirection(_paceDir);
+                    break;
+```
+
+- [ ] **Step 2: `RushAbility` — 内联停滞检测改用 StallDetector**
+
+删除常量 `StuckWindowSeconds` / `StuckMinProgress`，改为字段：
+```csharp
+        // 推进停滞检测（撞上未纳入墙层的碰撞体时兜底结束冲锋）
+        private StallDetector _stall = new StallDetector(0.15f, 0.05f);
+```
+`RushRoutine` 中删除 `winX` / `winT` 两个局部变量及其窗口判定块，改为：
+```csharp
+            var   body    = _enemy.Body;
+            float elapsed = 0f;
+            _stall.Reset(_enemy.transform.position.x);
+
+            while (true)
+            {
+                if (body != null && body.HasPassed(lockX, dir)) break;
+                if (mv != null && mv.WouldHitWallAhead(dir)) break;
+                if (_cfg.maxDashDuration > 0f && elapsed >= _cfg.maxDashDuration) break;
+
+                _enemy.MoveInDirectionWithSpeed(dir, speed, allowLedgeCross: true);
+                yield return null;
+
+                float dt = Time.deltaTime;
+                elapsed += dt;
+                // 兜底：撞上未纳入墙层的碰撞体(玩家/边界墙)导致原地不动 → 结束本次冲锋
+                if (_stall.Tick(_enemy.transform.position.x, dt)) break;
+            }
+```
+
+- [ ] **Step 3: `EnemyNavAgent` — 段内推进停滞改用 StallDetector**
+
+删除字段 `_stuckWinTimer` / `_stuckWinStartDist` / `_stuckWinInit`，改为：
+```csharp
+        private StallDetector _segStall;
+```
+在 `Awake` 末尾初始化：
+```csharp
+            _segStall = new StallDetector(_stuckWindowSeconds, _stuckMinProgress);
+```
+把 `TickStuckDetection(bool onSegment)` 整体替换为：
+```csharp
+        // 卡死检测：段上移动时，窗口内净水平位移不足 → 判受阻（覆盖"障碍未进图"的物理空推）。
+        private void TickStuckDetection(bool onSegment)
+        {
+            if (!onSegment) { _segStall.Reset(transform.position.x); return; }
+            if (_segStall.Tick(transform.position.x, Time.fixedDeltaTime))
+                _obstructionSignal = true;
+        }
+```
+并把 `ResetStuckWindow()` 的实现改为 `_segStall.Reset(transform.position.x);`。
+
+> 注：原实现比较的是"到子目标的距离缩小量"，新实现比较"净水平位移"。两者都用于识别"推不动"，
+> 后者与另外两处统一且不依赖子目标；行为差异仅在"绕行时距离不减但确实在移动"的场景——
+> 那种情况下**新实现更准确**（不会误判为卡死）。
+
+- [ ] **Step 4: 编译门 + 测试**
+
+预期 0 错误；EditMode **199 条**全绿。
+
+- [ ] **Step 5: PlayMode 验证 Pace 修复**
+
+进 Play，禁用 `ENM_CaoZhi` 的 `EnemyAiBrain`，用反射把 `_patrolStrategy` 设为 `Pace`，
+把敌人放到平台左缘外侧悬空处（`center x = -22.30, y = 2.01`），`Locomotion.SetMode(Patrol)`。
+预期：敌人**能掉头走回平台**（修复前会永久顶着崖外不动）。验证后 `unity_play_mode({action:"stop"})`。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add Assets/_Game/Scripts/Enemies/Navigation/EnemyLocomotion.cs \
+        Assets/_Game/Scripts/Enemies/Abilities/RushAbility.cs \
+        Assets/_Game/Scripts/Enemies/Navigation/EnemyNavAgent.cs
+git commit -m "refactor(enemy): 三处卡死检测收敛为 StallDetector;修复 Pace 持续受阻时无法掉头的死锁"
+```
+
+---
+
+# 阶段 P1：新增 `IEnemyNavigator` 与 `GroundNavigator`（不动现有接线）
+
+## Task 3: 新接口 `IEnemyNavigator` + `NullEnemyNavigator`
+
+**Files:**
+- Create: `Assets/_Game/Scripts/Enemies/IEnemyNavigator.cs`
+
+- [ ] **Step 1: 创建接口文件**
+
+```csharp
+using UnityEngine;
+
+namespace BaseGames.Enemies
+{
+    /// <summary>
+    /// 敌人导航抽象：把"去某个世界点"的请求翻译为具体移动方式（地面沿地形走 / 飞行直取），
+    /// 并报告到达与受阻。
+    ///
+    /// <para><b>不含任何路径图概念</b>——可达性由移动层的墙/悬崖夹紧天然决定：
+    /// 走得过去就是可达，被夹停的地方就是边界。</para>
+    ///
+    /// 实现：<c>GroundNavigator</c>（地面）、<c>FlyingNavigator</c>（飞行）、
+    /// <see cref="NullEnemyNavigator"/>（无导航/测试）。
+    /// </summary>
+    public interface IEnemyNavigator
+    {
+        /// <summary>
+        /// 请求朝世界坐标移动。目标被记录后由实现逐帧驱动，**重复传入同一目标是幂等的**
+        /// （每帧调用或只在目标变化时调用皆可）。传入新目标会清除 <see cref="HasArrived"/> / <see cref="IsBlocked"/>。
+        /// </summary>
+        void MoveTowards(Vector2 target);
+
+        /// <summary>停止移动并清除当前目标。</summary>
+        void Stop();
+
+        /// <summary>设置移动速度（巡逻走速 / 追击跑速）。传 0 表示使用移动层配置的默认步速。</summary>
+        void SetSpeed(float speed);
+
+        /// <summary>当前是否正朝目标推进（有目标、未到达、未受阻）。</summary>
+        bool IsMoving { get; }
+
+        /// <summary>是否已到达目标（进入停止距离内）。</summary>
+        bool HasArrived { get; }
+
+        /// <summary>是否被地形挡住而无法继续靠近目标（墙 / 悬崖夹停 / 推进停滞）。</summary>
+        bool IsBlocked { get; }
+
+        /// <summary>取一个可供游走的目标点。取不到时返回 false。</summary>
+        bool TryPickWanderPoint(out Vector2 point);
+    }
+
+    /// <summary>无导航单位 / 测试用空实现：不移动，不报告到达或受阻。</summary>
+    public sealed class NullEnemyNavigator : IEnemyNavigator
+    {
+        public void MoveTowards(Vector2 _) { }
+        public void Stop()                 { }
+        public void SetSpeed(float _)      { }
+        public bool IsMoving   => false;
+        public bool HasArrived => false;
+        public bool IsBlocked  => false;
+        public bool TryPickWanderPoint(out Vector2 point) { point = Vector2.zero; return false; }
+    }
+}
+```
+
+- [ ] **Step 2: 编译门 + 测试**
+
+预期 0 错误；EditMode 199 条全绿（新接口尚无人使用）。
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add Assets/_Game/Scripts/Enemies/IEnemyNavigator.cs
+git commit -m "feat(enemy): 新增 IEnemyNavigator 瘦身导航接口(7 成员)与 NullEnemyNavigator"
+```
+
+---
+
+## Task 4: `GroundNavigator` + 纯逻辑单测（TDD）
+
+**Files:**
+- Test: `Assets/Tests/EditMode/Enemies/GroundNavigatorLogicTests.cs`
+- Create: `Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs`
+
+- [ ] **Step 1: 先写失败测试**
+
+```csharp
+using NUnit.Framework;
+using BaseGames.Enemies.Navigation;
+
+namespace BaseGames.Tests.EditMode.Enemies
+{
+    /// <summary>GroundNavigator 的方向/到达判定纯函数（无场景依赖）。</summary>
+    public class GroundNavigatorLogicTests
+    {
+        [Test]
+        public void Arrived_WhenWithinStopDistance()
+            => Assert.IsTrue(GroundNavigator.Arrived(1.0f, 1.1f, 0.2f));
+
+        [Test]
+        public void Arrived_ExactlyAtStopDistance_True()
+            => Assert.IsTrue(GroundNavigator.Arrived(1.0f, 1.2f, 0.2f));
+
+        [Test]
+        public void NotArrived_WhenOutsideStopDistance()
+            => Assert.IsFalse(GroundNavigator.Arrived(1.0f, 1.5f, 0.2f));
+
+        [Test]
+        public void Arrived_IgnoresDirection()
+        {
+            Assert.IsTrue(GroundNavigator.Arrived(1.0f, 0.9f, 0.2f));   // 目标在左侧
+            Assert.IsFalse(GroundNavigator.Arrived(1.0f, 0.5f, 0.2f));
+        }
+
+        [Test]
+        public void WanderX_PositiveSign_LandsWithinForwardRange()
+        {
+            float x = GroundNavigator.WanderX(10f, 1.5f, 5f, +1f, 0f);
+            Assert.AreEqual(11.5f, x, 1e-4f);                            // t=0 → 最近端
+            x = GroundNavigator.WanderX(10f, 1.5f, 5f, +1f, 1f);
+            Assert.AreEqual(15f, x, 1e-4f);                              // t=1 → 最远端
+        }
+
+        [Test]
+        public void WanderX_NegativeSign_LandsWithinBackwardRange()
+        {
+            float x = GroundNavigator.WanderX(10f, 1.5f, 5f, -1f, 0f);
+            Assert.AreEqual(8.5f, x, 1e-4f);
+            x = GroundNavigator.WanderX(10f, 1.5f, 5f, -1f, 1f);
+            Assert.AreEqual(5f, x, 1e-4f);
+        }
+
+        [Test]
+        public void WanderX_MidT_Interpolates()
+            => Assert.AreEqual(13.25f, GroundNavigator.WanderX(10f, 1.5f, 5f, +1f, 0.5f), 1e-4f);
+    }
+}
+```
+
+- [ ] **Step 2: 运行确认失败**（`GroundNavigator` 不存在）
+
+- [ ] **Step 3: 实现**
+
+创建 `Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs`：
+```csharp
+using UnityEngine;
+
+namespace BaseGames.Enemies.Navigation
+{
+    /// <summary>
+    /// 地面单位导航：朝目标 X 直接行走，由 <see cref="EnemyMovement"/> 的墙/悬崖夹紧决定可达性。
+    ///
+    /// <para><b>不做任何地形扫描</b>：走得过去就是可达，被夹停的地方就是边界。
+    /// 因此不存在"脱离导航图"这类状态——敌人无论被击退/冲锋到哪里，都能正常继续行走。</para>
+    ///
+    /// <para>只驱动水平方向；垂直交给刚体重力。移动经 <see cref="EnemyMoveInput"/> 下发，
+    /// 速度为 0 时退化为移动层配置的步速。</para>
+    /// </summary>
+    [RequireComponent(typeof(EnemyMovement))]
+    public sealed class GroundNavigator : MonoBehaviour, IEnemyNavigator
+    {
+        [Header("到达判定")]
+        [Tooltip("身体中心 X 与目标 X 的距离小于此值即视为到达(m)")]
+        [SerializeField] [Min(0.01f)] private float _stoppingDistance = 0.2f;
+
+        [Header("游走取点（Wander 用）")]
+        [Tooltip("单次游走的最近距离(m)")]
+        [SerializeField] [Min(0f)] private float _wanderMinRange = 1.5f;
+        [Tooltip("单次游走的最远距离(m)。走不到会被地形夹停，自然结束本次游走。")]
+        [SerializeField] [Min(0f)] private float _wanderMaxRange = 5f;
+
+        [Header("推进停滞检测")]
+        [Tooltip("窗口时长(s)：此时长内净位移不足即判受阻")]
+        [SerializeField] [Min(0.05f)] private float _stallWindowSeconds = 0.4f;
+        [Tooltip("窗口内所需最小净位移(m)")]
+        [SerializeField] [Min(0f)] private float _stallMinProgress = 0.05f;
+
+        private EnemyBase     _enemy;
+        private EnemyMovement _movement;
+        private StallDetector _stall;
+
+        private Vector2 _target;
+        private bool    _hasTarget;
+        private float   _speed;       // 0 = 用移动层配置步速
+        private bool    _arrived;
+        private bool    _blocked;
+
+        public bool IsMoving   => _hasTarget && !_arrived && !_blocked;
+        public bool HasArrived => _arrived;
+        public bool IsBlocked  => _blocked;
+
+        private void Awake()
+        {
+            _enemy    = GetComponent<EnemyBase>();
+            _movement = GetComponent<EnemyMovement>();
+            _stall    = new StallDetector(_stallWindowSeconds, _stallMinProgress);
+            if (_enemy == null)
+                Debug.LogError($"[GroundNavigator] {name} 找不到 EnemyBase，无法读取身体几何。", this);
+        }
+
+        // ── IEnemyNavigator ────────────────────────────────────────────
+        public void MoveTowards(Vector2 target)
+        {
+            // 幂等：同一目标重复调用不重置状态，避免每帧调用时永远清掉到达/受阻标志
+            if (_hasTarget && (target - _target).sqrMagnitude < 1e-6f) return;
+            _target    = target;
+            _hasTarget = true;
+            _arrived   = false;
+            _blocked   = false;
+            _stall.Reset(BodyX);
+        }
+
+        public void Stop()
+        {
+            _hasTarget = false;
+            _arrived   = false;
+            _blocked   = false;
+            _enemy?.StopMovement();
+        }
+
+        public void SetSpeed(float speed) => _speed = Mathf.Max(0f, speed);
+
+        public bool TryPickWanderPoint(out Vector2 point)
+        {
+            float sign = Random.value < 0.5f ? -1f : 1f;
+            float x = WanderX(BodyX, _wanderMinRange, _wanderMaxRange, sign, Random.value);
+            point = new Vector2(x, transform.position.y);
+            return true;   // 地面单位总能尝试；走不到会被夹停并置 IsBlocked
+        }
+
+        // ── 驱动 ───────────────────────────────────────────────────────
+        private float BodyX => _enemy != null ? _enemy.Body.Center.x : transform.position.x;
+
+        private void FixedUpdate()
+        {
+            if (!_hasTarget || _arrived || _blocked || _movement == null) return;
+
+            float bodyX = BodyX;
+            if (Arrived(bodyX, _target.x, _stoppingDistance))
+            {
+                _arrived = true;
+                _enemy?.StopMovement();
+                return;
+            }
+
+            float dir = Mathf.Sign(_target.x - bodyX);
+
+            // 地形夹紧即为"不可达边界"：着地时前方是墙或悬崖 → 本次移动到此为止
+            if (_movement.IsGrounded && _movement.WouldBlockAhead(dir))
+            {
+                _blocked = true;
+                _enemy?.StopMovement();
+                return;
+            }
+
+            _movement.PendingInput.MoveDir   = dir;
+            _movement.PendingInput.MoveSpeed = _speed;   // 0 → MoveHorizontal 用配置步速
+            _movement.PendingInput.WantStop  = false;
+
+            // 兜底：命令了移动却推不动（撞上未纳入检测层的碰撞体等）
+            if (_stall.Tick(bodyX, Time.fixedDeltaTime))
+            {
+                _blocked = true;
+                _enemy?.StopMovement();
+            }
+        }
+
+        // ── 纯函数（便于无场景单测）──────────────────────────────────────
+        /// <summary>身体中心 X 是否已进入目标 X 的停止距离内。</summary>
+        public static bool Arrived(float currentX, float targetX, float stopDistance)
+            => Mathf.Abs(targetX - currentX) <= stopDistance;
+
+        /// <summary>
+        /// 游走目标 X：自当前位置朝 <paramref name="sign"/> 方向，
+        /// 在 [minRange, maxRange] 区间内按插值系数 <paramref name="t"/>(0..1) 取点。
+        /// </summary>
+        public static float WanderX(float currentX, float minRange, float maxRange, float sign, float t)
+            => currentX + sign * Mathf.Lerp(minRange, Mathf.Max(minRange, maxRange), Mathf.Clamp01(t));
+    }
+}
+```
+
+- [ ] **Step 4: 编译门 + 测试**
+
+预期 0 错误；EditMode **206 条**全绿（199 + 新增 7）。
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs \
+        Assets/Tests/EditMode/Enemies/GroundNavigatorLogicTests.cs
+git commit -m "feat(enemy): 新增 GroundNavigator 地面直接移动导航(+7 纯函数单测)"
+```
+
+---
+
+# 阶段 P2：消费者切换（唯一需重点比对行为的阶段）
+
+## Task 5: `FlyingDirectNavigator` → `FlyingNavigator`（改接口）
+
+**Files:**
+- Rename: `Navigation/FlyingDirectNavigator.cs` → `Navigation/FlyingNavigator.cs`（连同 `.meta`，`git mv` 保 GUID）
+- Modify: 重写为新接口
+
+- [ ] **Step 1: 改名（保 GUID）**
+
+```bash
+cd Assets/_Game/Scripts/Enemies/Navigation
+git mv FlyingDirectNavigator.cs FlyingNavigator.cs
+git mv FlyingDirectNavigator.cs.meta FlyingNavigator.cs.meta
+```
+
+- [ ] **Step 2: 改类名与接口**
+
+- 类声明改为 `public sealed class FlyingNavigator : MonoBehaviour, IEnemyNavigator`
+- **删除**：4 个事件（`OnLinkStarted`/`OnLinkCompleted`/`OnNavPathFailed`/`OnGoalReached`）、
+  `IsOnLink`/`CurrentLinkType`/`CurrentLinkStart`/`CurrentLinkEnd`、`LastMoveObstructed`、
+  `TryGetClosestReachable`、`IsNearEdge`、`CanReach`、`WalkToRandomOnSegment`、`ResolveStandablePoint`、
+  以及 `_goalFired` 字段。
+- **改名**：`RequestMoveTo` → `MoveTowards`（新增幂等判断）、`StopNavigation` → `Stop`、
+  `IsAtDestination()` → `HasArrived` 属性、`WalkToRandom()` → `TryPickWanderPoint(out Vector2)`。
+- **新增**：`public bool IsBlocked => false;`（飞行直取，无地形阻挡概念）
+- `UpdateChase()` 中原先触发 `OnGoalReached` 的分支，改为置 `_arrived = true`。
+- 状态字段改为：`Vector2 _target; bool _hasTarget; bool _arrived;`，
+  `IsMoving => _hasTarget && !_arrived;`
+- 悬停逻辑（`UpdateHover`）与朝向逻辑**保持不变**。
+
+- [ ] **Step 3: 编译门 + 测试** → 0 错误、206 条全绿
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add Assets/_Game/Scripts/Enemies/Navigation/
+git commit -m "refactor(enemy): FlyingDirectNavigator 改名 FlyingNavigator 并切换到 IEnemyNavigator"
+```
+
+---
+
+## Task 6: `EnemyBase` / `EnemyLocomotion` / 编辑器面板切换到新接口
+
+**Files:**
+- Modify: `Enemies/EnemyBase.cs`、`Enemies/Navigation/EnemyLocomotion.cs`、`Editor/Enemies/EnemyLocomotionEditor.cs`
+
+- [ ] **Step 1: `EnemyBase` 换类型**
+
+- 字段：`protected IPathAgent _nav;` → `protected IEnemyNavigator _nav;`
+- 属性：`public IPathAgent Nav => _nav;` → `public IEnemyNavigator Nav => _nav;`
+- `Awake`：`_nav = GetComponent<IPathAgent>() ?? new NullPathAgent();`
+  → `_nav = GetComponent<IEnemyNavigator>() ?? new NullEnemyNavigator();`
+- 更新类头注释中提到 `IPathAgent` 的措辞。
+- `MoveTo(Vector2)` 内部对 `_nav.RequestMoveTo` 的调用改为 `_nav.MoveTowards`；
+  `StopMovement()` 内对 `_nav.StopNavigation()` 的调用改为 `_nav.Stop()`（按实际代码定位）。
+
+- [ ] **Step 2: `EnemyLocomotion` — Wander 改用新接口**
+
+`TickWander()` 整体替换为：
+```csharp
+        /// <summary>
+        /// 就近随机游走：朝随机取的目标点走，**到达或被地形夹停**即视为本次游走结束，
+        /// 停顿 [_wanderPauseMin, _wanderPauseMax] 秒（期间播 Idle）后再挑下一个点。
+        /// 走到平台边缘停下转身是预期表现——可达性由移动层夹紧决定，不做地形扫描。
+        /// </summary>
+        private void TickWander()
+        {
+            var nav = _enemy.Nav;
+            if (nav == null) return;
+
+            // 仍在推进：清停顿态，等到达/受阻
+            if (nav.IsMoving) { _wanderPausing = false; return; }
+
+            // 到达、受阻或尚未出发：先停顿计时，再挑下一个点
+            if (!_wanderPausing)
+            {
+                _wanderPausing    = true;
+                _wanderPauseTimer = Random.Range(_wanderPauseMin, Mathf.Max(_wanderPauseMin, _wanderPauseMax));
+            }
+
+            _wanderPauseTimer -= Time.deltaTime;
+            if (_wanderPauseTimer <= 0f)
+            {
+                _wanderPausing = false;
+                if (nav.TryPickWanderPoint(out var point)) nav.MoveTowards(point);
+            }
+        }
+```
+
+- [ ] **Step 3: `EnemyLocomotion` — Waypoints 去掉吸附**
+
+- 删除字段 `_wpResolvedGoal` 的"吸附"语义相关：保留 `_wpResolvedGoal` 作为**当前路点坐标**缓存，
+  删除 `_wpResolveOk` 字段及其 `DebugResolveOk` 只读属性。
+- `SetWaypointGoal()` 替换为：
+```csharp
+        /// <summary>取当前路点坐标并出发。路点若摆在崖外/墙后，敌人会走到边缘被夹停 → IsBlocked → 结算推进下一个。</summary>
+        private void SetWaypointGoal()
+        {
+            _wpResolvedGoal = _waypoints[_wpIndex].position;
+            _enemy.Nav?.MoveTowards(_wpResolvedGoal);
+        }
+```
+- `case PatrolStrategy.Waypoints:` 中：
+  - `bool obstructedSettled = nav != null && nav.LastMoveObstructed && !nav.IsMoving;`
+    → `bool obstructedSettled = nav != null && nav.IsBlocked;`
+  - 末尾的 `else if (nav != null && !nav.IsMoving && !nav.LastMoveObstructed) { _enemy.MoveTo(_wpResolvedGoal); }`
+    → 改为 `else if (nav != null && !nav.IsMoving && !nav.IsBlocked && !nav.HasArrived) { nav.MoveTowards(_wpResolvedGoal); }`
+
+- [ ] **Step 4: `EnemyLocomotion` — Approach/Pursue 改用新接口**
+
+`Pursue(Vector2)` 与 `MoveTo(Vector2)`、`Update()` 中 `LocomotionMode.Approach` 分支里
+对 `_enemy.MoveTo(...)` 的调用保持不变（`EnemyBase.MoveTo` 内部已在 Step 1 改为 `MoveTowards`）。
+
+- [ ] **Step 5: `EnemyLocomotionEditor` — 调试面板去掉导航图信息**
+
+- 第 127 行替换为：
+```csharp
+                sb.AppendLine($"Nav 类型: {nav.GetType().Name}   IsMoving: {nav.IsMoving}   HasArrived: {nav.HasArrived}   IsBlocked: {nav.IsBlocked}");
+```
+- **删除**：第 128–133 行（`EnemyNavAgent`/`RawNavAgent`/`HasValidPosition` 相关块）、
+  第 139 行 `_maxSnapDistance` 行及 `ReadMaxSnap` 方法、
+  Waypoints 段中 `CanReach` 与"路点逐个吸附检测"整块（第 152–171 行）、
+  以及 `Diagnose(...)` 里所有引用已删成员之处（按编译错误逐个修正）。
+- Waypoints 段保留：当前索引/ArriveRadius/当前目标/到目标距离。
+
+- [ ] **Step 6: 编译门 + 测试** → 0 错误、206 条全绿
+
+- [ ] **Step 7: 提交**
+
+```bash
+git add Assets/_Game/Scripts/Enemies/EnemyBase.cs \
+        Assets/_Game/Scripts/Enemies/Navigation/EnemyLocomotion.cs \
+        Assets/_Game/Scripts/Editor/Enemies/EnemyLocomotionEditor.cs
+git commit -m "refactor(enemy): 消费者切换到 IEnemyNavigator(Wander/Waypoints 去导航图化,调试面板简化)"
+```
+
+---
+
+## Task 7: 场景敌人换装 `GroundNavigator` + PlayMode 全面验收
+
+**Files:** 场景 `TestRoomA`（不提交场景改动，除非用户要求）
+
+- [ ] **Step 1: 换装组件**
+
+MCP `unity_execute_code`：对 `ENM_CaoZhi`
+- `DestroyImmediate` 掉 `EnemyNavAgent`、PB2d `NavAgent`、`TransformBasedMovement` 三个组件
+- `AddComponent<GroundNavigator>()`
+- 打印确认 `EnemyBase.Nav` 类型为 `GroundNavigator`（需重进 Play 让 Awake 重取）
+
+- [ ] **Step 2: 三种巡逻验收**
+
+进 Play，禁用 AI 大脑，逐一切换 `_patrolStrategy` 并观察 4 秒：
+| 策略 | 预期 |
+|---|---|
+| Wander | 位移 > 0；走到平台边缘停下 → 停顿 → 反向再走；**动画为 Move（不再卡 Idle）** |
+| Pace | 正常来回；顶到崖沿能掉头 |
+| Waypoints | 依次推进路点；路点够不着时受阻结算并推进下一个 |
+
+- [ ] **Step 3: 追击与冲锋验收**
+
+- 启用 AI 大脑，玩家放到同平台 → 敌人应能追击并进入攻击（ApproachAttack）
+- 玩家跳到够不着的位置 → 敌人走到边缘停下（**不卡死、不原地踏步**）
+- 触发 `e001_chase` 冲锋 → 越过锁定点即停、可冲下悬崖、收尾不悬空
+
+- [ ] **Step 4: 退出 Play，确认 Console 无新增报错**
+
+- [ ] **Step 5: 记录结果**
+
+把验收结论写入 `Docs_Dev/Verification/`（沿用现有验证文档风格）并提交该文档。
+
+---
+
+# 阶段 P3–P5：清理
+
+## Task 8: Boss 预制体移除冗余导航组件
+
+- [ ] **Step 1:** 打开 `Assets/_Game/Prefabs/Enemies/ChaoFeng/ENM_ChaoFeng.prefab`，
+  移除 `NavAgent`、`TransformBasedMovement`、`EnemyNavAgent`（已核实 Boss 代码不引用导航）。
+- [ ] **Step 2:** 编译门 + 测试；PlayMode 快速确认 Boss 预制体可正常实例化（无 Missing 组件报错）。
+- [ ] **Step 3:** 提交预制体改动。
+
+## Task 9: 删除 `EnemyNavAgent`、`IPathAgent` 与编辑器中的寻路库用法
+
+- [ ] **Step 1:** 删除 `Assets/_Game/Scripts/Enemies/Navigation/EnemyNavAgent.cs`（+`.meta`）
+  与 `Assets/_Game/Scripts/Enemies/IPathAgent.cs`（+`.meta`）。
+  > `NavLinkType` / `INavLinkHandler` 若仍被 `EnemyMovement`/`BlinkStrikeAbility` 使用则**保留**——
+  > 把 `NavLinkType` 枚举移入 `INavLinkHandler.cs`。
+- [ ] **Step 2:** 删除 `Assets/_Game/Scripts/Editor/Enemies/Navigation/NavSurfaceBakeShortcut.cs`（+`.meta`）。
+- [ ] **Step 3:** `SceneObjectPlacerTool.cs` / `SceneScaffoldTools.cs`：删除 `using PathBerserker2d;`
+  与所有放置 `NavAgent`/`TransformBasedMovement`/`NavSurface` 的代码；敌人放置改为 `AddComponent<GroundNavigator>()`；
+  删除 `PlaceNavSurface` 菜单项。
+- [ ] **Step 4:** 两个 asmdef 移除对 PathBerserker 的引用：
+  `BaseGames.Editor.asmdef`、`BaseGames.Enemies.Navigation.asmdef`。
+- [ ] **Step 5:** 编译门 + 测试 → 0 错误、206 条全绿。
+- [ ] **Step 6:** 提交。
+
+## Task 10: 删除第三方寻路包
+
+- [ ] **Step 1:** 确认 `grep -rn "PathBerserker2d" Assets/_Game Assets/Tests --include=*.cs` **无输出**。
+- [ ] **Step 2:** 场景中删除导航面物体（`TestRoomA` 的 NavSurface 所在 GameObject）。
+- [ ] **Step 3:** 删除 `Assets/PathBerserker2d/` 整目录（含 `.meta`）。
+- [ ] **Step 4:** 编译门 + 测试 → 0 错误、206 条全绿；PlayMode 冒烟：敌人巡逻/追击/冲锋均正常。
+- [ ] **Step 5:** 提交（提交信息注明删除行数）。
+
+---
+
+## 自检记录（写计划时）
+
+- **Spec 覆盖**：§5 接口→Task 3；§6.1 地面实现→Task 4；§6.2 飞行→Task 5；§6.3 Null→Task 3；
+  §7 巡逻/追击→Task 6；§7.1 Pace 修复→Task 2；§8 StallDetector→Task 1+2；
+  §9.1 消费者→Task 6；§9.2 删除清单→Task 8/9/10；§12 测试→Task 1/4 单测 + 各 Task 回归 + Task 7 PlayMode；
+  §13 阶段→Task 1–10 分组。**无遗漏**。
+- **占位符扫描**：无 TBD；新文件均给出完整代码；修改处给出替换后的完整代码或精确删除清单。
+- **类型一致性**：`IEnemyNavigator` 7 成员（`MoveTowards`/`Stop`/`SetSpeed`/`IsMoving`/`HasArrived`/`IsBlocked`/`TryPickWanderPoint`）
+  在 Task 3 定义，Task 4/5/6 用法一致；`StallDetector(windowSeconds, minProgress)` + `Reset(x)` + `Tick(x, dt)`
+  在 Task 1 定义，Task 2/4 用法一致；`GroundNavigator.Arrived/WanderX` 静态签名与测试一致。
+- **测试基线**：191 → Task 1 后 199 → Task 4 后 206，其后不再新增。