zeling_v2/Docs_Dev/superpowers/plans/2026-07-21-enemy-ability-config-to-so.md

# 敌人能力配置迁移到 AbilitySO 子类 Implementation Plan

> **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:** 把 8 个能力 MonoBehaviour 上直接 `[SerializeField]` 挂载的全部数值/资产参数（动画片段、速度、时长、次数、LayerMask 等）迁移到对应的 `EnemyAbilitySO` 子类 SO；场景对象组件引用（BodyContactDamage/HitBox/HurtBox）保留在脚本。

**Architecture:** `EnemyAbilitySO` 保持基类；为 8 个能力各建 `XxxAbilitySO : EnemyAbilitySO` 子类（放 `Abilities/Configs/`，带 `[CreateAssetMenu]`）承载其参数。`EnemyAbilityBase` 新增 `ResolveConfig<T>()`：把 `_config` 解析为期望子类型，类型不符**显式报错**（无兜底）。每个能力 MonoBehaviour 删除迁走字段、`Awake` 缓存类型化 `_cfg`、使用处改读 `_cfg.xxx`，`_cfg==null` 时安全短路。更新向导 `CharacterWizardWindow` 的批量创建入口按能力类型建正确子类。不动任何 prefab/资产（用户手动重生成）。

**Tech Stack:** Unity 2022.3 (C# 9)、Animancer(`ClipTransition`)、ScriptableObject、UnityEditor、Unity Test Framework(EditMode)、Unity MCP(端口 7890) 做编译门与结构验证。

**设计文档:** `Docs_Dev/superpowers/specs/2026-07-21-enemy-ability-config-to-so-design.md`

**全局约定:**
- **编译门**：`unity_execute_code`(port 7890) 跑 `AssetDatabase.Refresh(); CompilationPipeline.RequestScriptCompilation(); return "ok";` → Bash `sleep 9` → `unity_get_compilation_errors` severity=error 期望 count=0。**绝不**在 `unity_execute_code` 内用 `Thread.Sleep`（会冻结 Unity 主线程）；跨调用等待用 Bash `sleep`。桥接卡死则 `unity_editor_ping` 等恢复；保持 Unity 窗口前台。多实例时选 `zeling_v2`。
- 分支已在 `refactor/ability-config-to-so`。每个 Task 结束提交一次（中文 + 类型前缀）。每次只 `git add` 本 Task 涉及的文件。
- **不修改任何 prefab / `ABL_*.asset`**（用户后续手动重生成替换）。
- 字段命名：SO 内公有字段去掉下划线前缀（对齐 `EnemyAbilitySO`/`EnemyAttackSO` 公有字段风格），保留原 `[Header]/[Tooltip]/[Min]/[Range]` 语义。

---

## 关键事实（实现前必读，均已核实）

- `EnemyAbilityBase`（`Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs`）：`[SerializeField] protected EnemyAbilitySO _config;`（第 22 行）；`protected virtual void Awake()`（第 46 行，做依赖缓存）；`protected EnemyBase _enemy; AnimancerComponent _animancer; Transform _transform;`。子类 MonoBehaviour 可访问 `_config`（protected）。
- `EnemyAbilitySO`（同目录）：公有字段 `abilityId, attackSequence(EnemyAttackSO[]), cooldown, telegraphVfxKey, telegraphDuration, interruptOnHurt, interruptOnStagger, …, exclusionGroup, priority`。带 `[CreateAssetMenu(menuName="BaseGames/Enemies/Enemy Ability", fileName="EAB_")]`。
- `ClipTransition` 是 Animancer 结构体，可作 public 字段序列化到 SO；`clip.Clip` 取底层 `AnimationClip`。
- 部分能力读 `_config?.attackSequence?[0].damageSource`（RepeatSlam/CeilingHangStrike/MeleeVulnerability）——这是**基类字段**，迁移后 `_config` 仍指向子类实例（is-a EnemyAbilitySO），这些行**保持不变**。
- EditMode 测试程序集 `Assets/Tests/EditMode/BaseGames.Tests.EditMode.asmdef` 已引用 `BaseGames.Enemies`，可直接测试能力类型。
- 能力→子类 SO 映射（供 Task 8 向导用，来自 `SceneObjectPlacerTool` 组件挂载）：
  - `ContactChaseAbility` → `ContactChaseAbilitySO`（E001 Chase、E006 Chase）
  - `CeilingHangStrikeAbility` → `CeilingHangStrikeAbilitySO`（E002 CeilingStrike）
  - `AnimatedCeilingDropAbility` → `AnimatedCeilingDropAbilitySO`（E003 Fall）
  - `AppearAbility` → `AppearAbilitySO`（E004 Appear）
  - `RepeatSlamAbility` → `RepeatSlamAbilitySO`（E004 HeadSlam）
  - `FacePlayerAbility` → `FacePlayerAbilitySO`（E004 Flip）
  - `MeleeAttackAbility`/`ProjectileAttackAbility`/`LeapAttackAbility` → 基类 `EnemyAbilitySO`（attackSequence 型，不迁移；E004/E005 Bite、Acid、E006 Leap）
  - E001 Alert（e001_alert）→ 基类 `EnemyAbilitySO`（无对应迁移能力）
  - `MeleeVulnerabilityAbility`/`PlayClipAbility` → 各自子类 SO（框架能力，当前无向导 def 映射，仅 CreateAssetMenu）

---

## Task 1: 基类 `ResolveConfig<T>` + EditMode 测试

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

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

创建 `Assets/Tests/EditMode/Abilities/AbilityConfigResolveTests.cs`：
```csharp
using System.Collections;
using System.Text.RegularExpressions;
using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;
using BaseGames.Enemies.Abilities;

namespace BaseGames.Tests.EditMode.Abilities
{
    public class AbilityConfigResolveTests
    {
        // 测试专用 SO 子类型（不依赖真实 8 个子类，保持本 Task 自包含）
        private sealed class ProbeConfigSO : EnemyAbilitySO { }
        private sealed class OtherConfigSO : EnemyAbilitySO { }

        // 测试探针：跳过基类 Awake 依赖装配，暴露 protected 成员
        private sealed class ProbeAbility : EnemyAbilityBase
        {
            protected override void Awake() { /* 跳过依赖装配，避免测试噪声 */ }
            protected override IEnumerator ExecuteCoroutine() { yield break; }
            public void SetConfig(EnemyAbilitySO c) => _config = c;
            public T Probe<T>() where T : EnemyAbilitySO => ResolveConfig<T>();
        }

        private ProbeAbility Make() => new GameObject("probe").AddComponent<ProbeAbility>();

        [Test]
        public void ResolveConfig_CorrectType_ReturnsInstance()
        {
            var probe = Make();
            var cfg = ScriptableObject.CreateInstance<ProbeConfigSO>();
            probe.SetConfig(cfg);
            Assert.AreSame(cfg, probe.Probe<ProbeConfigSO>());
            Object.DestroyImmediate(cfg);
            Object.DestroyImmediate(probe.gameObject);
        }

        [Test]
        public void ResolveConfig_WrongType_LogsError_ReturnsNull()
        {
            var probe = Make();
            probe.SetConfig(ScriptableObject.CreateInstance<OtherConfigSO>());
            LogAssert.Expect(LogType.Error, new Regex("_config 需为"));
            Assert.IsNull(probe.Probe<ProbeConfigSO>());
            Object.DestroyImmediate(probe.gameObject);
        }

        [Test]
        public void ResolveConfig_Null_LogsError_ReturnsNull()
        {
            var probe = Make();
            probe.SetConfig(null);
            LogAssert.Expect(LogType.Error, new Regex("_config 需为"));
            Assert.IsNull(probe.Probe<ProbeConfigSO>());
            Object.DestroyImmediate(probe.gameObject);
        }
    }
}
```

- [ ] **Step 2: 编译门确认测试因缺 `ResolveConfig` 编译失败** → `unity_get_compilation_errors` 应报 `ResolveConfig` 不存在（预期红）。

- [ ] **Step 3: 在 `EnemyAbilityBase` 加 `ResolveConfig<T>`**

在 `FaceTarget` 方法之后（类内、`EnemyAbilityWaits` 之前）插入：
```csharp
        /// <summary>把 _config 解析为期望的子类型；类型不符/为空时显式报错（不回退）。</summary>
        protected T ResolveConfig<T>() where T : EnemyAbilitySO
        {
            if (_config is T typed) return typed;
            Debug.LogError($"[{GetType().Name}] _config 需为 {typeof(T).Name}，" +
                           $"实际 = {(_config != null ? _config.GetType().Name : "null")}。请重建为正确的子类 SO。", this);
            return null;
        }
```

- [ ] **Step 4: 编译门** → count=0。

- [ ] **Step 5: 跑 EditMode 测试**（Unity Test Runner）

`unity_execute_code`(port 7890) 通过反射跑测试类（或用编辑器 Test Runner）。若用反射直跑：调用三个 `[Test]` 方法，捕获 `AssertionException`；`LogAssert.Expect` 需在 Test Runner 环境内生效，若反射直跑不便，改为在编辑器 `Window > General > Test Runner > EditMode > Run` 手动确认 3/3 通过（在报告中注明验证方式）。期望：3 通过。

- [ ] **Step 6: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs Assets/Tests/EditMode/Abilities/AbilityConfigResolveTests.cs
git commit -m "feat(enemy): EnemyAbilityBase 加 ResolveConfig<T> 类型化配置解析(不匹配显式报错) + EditMode 测试"
```

---

## Task 2: ContactChaseAbilitySO + 迁移 ContactChaseAbility（参考样板）

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/ContactChaseAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/ContactChaseAbility.cs`

- [ ] **Step 1: 建子类 SO**
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>ContactChaseAbility 的配置：起手/循环/收招动画 + 冲刺速度。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Contact Chase Ability", fileName = "ABL_")]
    public class ContactChaseAbilitySO : EnemyAbilitySO
    {
        [Header("动画（起手 / 循环 / 收招）")]
        public ClipTransition startClip; // Skill_Start：张口（一次性）
        public ClipTransition loopClip;  // Skill_Loop：快速爬行追击（循环）
        public ClipTransition endClip;   // Skill_End：收招（一次性）

        [Header("冲刺")]
        [Tooltip("冲刺速度；<=0 时回退用 EnemyStatsSO.RunSpeed(追击速度)")]
        public float dashSpeed = 0f;
    }
}
```

- [ ] **Step 2: 迁移 MonoBehaviour**

先 Read `ContactChaseAbility.cs` 全文。做以下改动：

(a) 删除字段块（第 16-19 行 `_startClip/_loopClip/_endClip` 与第 24-26 行 `_dashSpeed`），**保留** `[Header("接触伤害")] _contactDamage`。删除后字段区变为：
```csharp
        [Header("接触伤害")]
        [SerializeField] private BodyContactDamage _contactDamage;

        private ContactChaseAbilitySO _cfg;

        protected override void Awake()
        {
            base.Awake();
            _cfg = ResolveConfig<ContactChaseAbilitySO>();
        }
```

(b) 使用处替换（`ExecuteCoroutine` 顶部加空配置守卫）：
- `ExecuteCoroutine` 第一行 `Phase = AbilityRunState.Active;` 前加：`if (_cfg == null) yield break;`
- `_startClip.Clip` → `_cfg.startClip.Clip`（两处：判空 + `LockAnim(_startClip.Clip.length)` + `_animancer.Play(_startClip)` + `EnemyAbilityWaits.Get(_startClip.Clip.length)`）
- `_dashSpeed` → `_cfg.dashSpeed`
- `_loopClip.Clip`/`_animancer.Play(_loopClip)` → `_cfg.loopClip.Clip`/`_animancer.Play(_cfg.loopClip)`
- `_endClip` 全部（`OnInterrupted`、`PlaySkillEnd`）→ `_cfg.endClip`；`OnInterrupted` 内条件改为 `if (reason == InterruptReason.ExternalRequest && _cfg != null && _cfg.endClip.Clip != null)`；`PlaySkillEnd` 首行改为 `if (_cfg == null || _cfg.endClip.Clip == null) yield break;`

> 场景引用 `_contactDamage` 及其 `DisableContact()/Cleanup()` 逻辑不动。

- [ ] **Step 3: 编译门** → count=0。

- [ ] **Step 4: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/Configs/ContactChaseAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/ContactChaseAbility.cs
git commit -m "refactor(enemy): ContactChase 参数迁入 ContactChaseAbilitySO(子类)"
```

---

## Task 3: RepeatSlamAbilitySO + 迁移 RepeatSlamAbility

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/RepeatSlamAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/RepeatSlamAbility.cs`

- [ ] **Step 1: 建子类 SO**
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>RepeatSlamAbility 的配置：起手/循环/收招动画 + 砸地行为参数。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Repeat Slam Ability", fileName = "ABL_")]
    public class RepeatSlamAbilitySO : EnemyAbilitySO
    {
        [Header("动画")]
        public ClipTransition startClip;
        public ClipTransition loopClip;
        public ClipTransition endClip;

        [Header("行为配置")]
        [Tooltip("每次砸地时 HitBox 激活时长（秒）")]
        public float hitActiveTime = 0.15f;
        [Tooltip("砸地次数")]
        public int slamCount = 2;
        [Tooltip("最后一次砸地收招后额外等待时间（秒）")]
        public float staggerDuration = 1.2f;
    }
}
```

- [ ] **Step 2: 迁移 MonoBehaviour**

Read `RepeatSlamAbility.cs` 全文。改动：

(a) 删除第 15-18 行动画字段块与第 23-29 行 `_hitActiveTime/_slamCount/_staggerDuration`，**保留** `[Header("打击")] HitBox _hitBox`。字段区改为：
```csharp
        [Header("打击")]
        [SerializeField] private HitBox _hitBox;

        private RepeatSlamAbilitySO _cfg;

        protected override void Awake()
        {
            base.Awake();
            _cfg = ResolveConfig<RepeatSlamAbilitySO>();
        }
```

(b) 使用处替换：
- `ExecuteCoroutine` 顶 `Phase = AbilityRunState.Active;` 前加 `if (_cfg == null) yield break;`
- `_startClip` → `_cfg.startClip`（判空 + Play + `Get(_startClip.Clip.length)`）
- `_slamCount` → `_cfg.slamCount`
- `_loopClip` → `_cfg.loopClip`；`_hitActiveTime` → `_cfg.hitActiveTime`（第 46、52 行）
- `_endClip` → `_cfg.endClip`；`_staggerDuration` → `_cfg.staggerDuration`（第 59-66 行两处）
- `_config?.attackSequence?.Length > 0 ? _config.attackSequence[0].damageSource : null` **保持不变**（基类字段）。
- `OnInterrupted` 的 `_hitBox?.Deactivate();` 不动。

- [ ] **Step 3: 编译门** → count=0。

- [ ] **Step 4: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/Configs/RepeatSlamAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/RepeatSlamAbility.cs
git commit -m "refactor(enemy): RepeatSlam 参数迁入 RepeatSlamAbilitySO(子类)"
```

---

## Task 4: CeilingHangStrikeAbilitySO + 迁移 CeilingHangStrikeAbility

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/CeilingHangStrikeAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/CeilingHangStrikeAbility.cs`

- [ ] **Step 1: 建子类 SO**
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>CeilingHangStrikeAbility 的配置：出击/悬挂/收回动画 + 悬挂窗口时长。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Ceiling Hang Strike Ability", fileName = "ABL_")]
    public class CeilingHangStrikeAbilitySO : EnemyAbilitySO
    {
        [Header("动画")]
        public ClipTransition strikeClip;
        public ClipTransition loopClip;
        public ClipTransition endClip;

        [Header("行为")]
        [Tooltip("脆弱悬挂窗口持续时间（秒）")]
        public float hangDuration = 2f;
    }
}
```

- [ ] **Step 2: 迁移 MonoBehaviour**

Read `CeilingHangStrikeAbility.cs`。改动：

(a) 删第 15-18 行动画字段块 + 第 24-26 行 `_hangDuration`，**保留** `[Header("碰撞")] HitBox _attackHitBox; HurtBox _hurtBox`。字段区改为：
```csharp
        [Header("碰撞")]
        [SerializeField] private HitBox  _attackHitBox;
        [SerializeField] private HurtBox _hurtBox;

        private CeilingHangStrikeAbilitySO _cfg;

        protected override void Awake()
        {
            base.Awake();
            _cfg = ResolveConfig<CeilingHangStrikeAbilitySO>();
        }
```

(b) 使用处替换：
- `ExecuteCoroutine` 顶 `Phase = AbilityRunState.Active;` 前加 `if (_cfg == null) yield break;`
- `_strikeClip` → `_cfg.strikeClip`（判空 + Play + `Get(_strikeClip.Clip.length)`）
- `_loopClip` → `_cfg.loopClip`
- `_hangDuration` → `_cfg.hangDuration`
- `_endClip` → `_cfg.endClip`
- `_config?.attackSequence?...damageSource` **保持不变**。
- `_attackHitBox`/`_hurtBox` 相关不动。

- [ ] **Step 3: 编译门** → count=0。

- [ ] **Step 4: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/Configs/CeilingHangStrikeAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/CeilingHangStrikeAbility.cs
git commit -m "refactor(enemy): CeilingHangStrike 参数迁入 CeilingHangStrikeAbilitySO(子类)"
```

---

## Task 5: AnimatedCeilingDropAbilitySO + 迁移 AnimatedCeilingDropAbility

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/AnimatedCeilingDropAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/AnimatedCeilingDropAbility.cs`

- [ ] **Step 1: 建子类 SO**
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>AnimatedCeilingDropAbility 的配置：下落动画 + 物理下落/落地参数。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Animated Ceiling Drop Ability", fileName = "ABL_")]
    public class AnimatedCeilingDropAbilitySO : EnemyAbilitySO
    {
        [Header("动画")]
        [Tooltip("下落循环动画（旋转下落姿态，循环播放直到落地）")]
        public ClipTransition fallLoopClip;

        [Header("物理下落")]
        [Tooltip("切换 Dynamic 后使用的重力倍率")]
        public float fallGravityScale = 3.5f;
        [Tooltip("下落超时保护（秒），超时后强制继续执行")]
        public float maxFallTime = 3f;
        public LayerMask groundMask;

        [Header("落地后")]
        [Tooltip("落地后恢复帧延迟（秒），之后切换为 Patrol 阶段")]
        public float recoveryTime = 0.1f;
    }
}
```

- [ ] **Step 2: 迁移 MonoBehaviour**

Read `AnimatedCeilingDropAbility.cs`。注意本类**已有** `Awake` 重写（缓存 `_rb`）。改动：

(a) 删第 16-29 行的动画/物理/落地数值字段（`_fallLoopClip/_fallGravityScale/_maxFallTime/_groundMask/_recoveryTime`），**保留** `[SerializeField] private BodyContactDamage _contactDamage;` 与 `private Rigidbody2D _rb;`。字段区改为：
```csharp
        [Header("落地后")]
        [SerializeField] private BodyContactDamage _contactDamage;

        private AnimatedCeilingDropAbilitySO _cfg;
        private Rigidbody2D _rb;
```

(b) 现有 `Awake` 重写内补解析（保留 `base.Awake()` 与 `_rb` 缓存）：
```csharp
        protected override void Awake()
        {
            base.Awake();
            _cfg = ResolveConfig<AnimatedCeilingDropAbilitySO>();
            _rb = GetComponentInParent<Rigidbody2D>();
        }
```

(c) 使用处替换：
- `ExecuteCoroutine` 顶 `Phase = AbilityRunState.Active;` 前加 `if (_cfg == null) yield break;`
- `_fallLoopClip` → `_cfg.fallLoopClip`
- `_fallGravityScale` → `_cfg.fallGravityScale`
- `_maxFallTime` → `_cfg.maxFallTime`
- `_recoveryTime` → `_cfg.recoveryTime`
- `IsGrounded()` 内 `_groundMask` → `_cfg.groundMask`（注意：`IsGrounded` 是普通方法，`_cfg` 为实例字段可访问；若 `_cfg` 可能为 null，此路径仅在 `ExecuteCoroutine` 守卫通过后调用，安全）
- `_contactDamage`、`_rb`、`OnInterrupted` 不动。

- [ ] **Step 3: 编译门** → count=0。

- [ ] **Step 4: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/Configs/AnimatedCeilingDropAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/AnimatedCeilingDropAbility.cs
git commit -m "refactor(enemy): AnimatedCeilingDrop 参数迁入 AnimatedCeilingDropAbilitySO(子类)"
```

---

## Task 6: MeleeVulnerabilityAbilitySO + 迁移 MeleeVulnerabilityAbility

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/MeleeVulnerabilityAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/MeleeVulnerabilityAbility.cs`

- [ ] **Step 1: 建子类 SO**
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>MeleeVulnerabilityAbility 的配置：攻击动画 + 打击归一化时机 + 后摇脆弱时长。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Melee Vulnerability Ability", fileName = "ABL_")]
    public class MeleeVulnerabilityAbilitySO : EnemyAbilitySO
    {
        [Header("动画")]
        public ClipTransition attackClip;

        [Header("打击时间（0~1 归一化，基于 Clip 时长）")]
        [Range(0f, 1f)] public float hitEnterT = 0.30f;
        [Range(0f, 1f)] public float hitExitT  = 0.60f;

        [Header("后摇脆弱窗口")]
        [Tooltip("HurtBox 激活时间（秒）")]
        public float staggerDuration = 1.0f;
    }
}
```

- [ ] **Step 2: 迁移 MonoBehaviour**

Read `MeleeVulnerabilityAbility.cs`。改动：

(a) 删第 15-16 行 `_attackClip`、第 22-24 行 `_hitEnterT/_hitExitT`、第 26-28 行 `_staggerDuration`，**保留** `[Header("碰撞")] HitBox _hitBox; HurtBox _hurtBox`。字段区改为：
```csharp
        [Header("碰撞")]
        [SerializeField] private HitBox  _hitBox;
        [SerializeField] private HurtBox _hurtBox;

        private MeleeVulnerabilityAbilitySO _cfg;

        protected override void Awake()
        {
            base.Awake();
            _cfg = ResolveConfig<MeleeVulnerabilityAbilitySO>();
        }
```

(b) 使用处替换：
- `ExecuteCoroutine` 顶 `Phase = AbilityRunState.Active;` 前加 `if (_cfg == null) yield break;`
- `_attackClip` → `_cfg.attackClip`（判空 + `len = _attackClip.Clip.length` + Play）
- `_hitEnterT` → `_cfg.hitEnterT`；`_hitExitT` → `_cfg.hitExitT`
- `_staggerDuration` → `_cfg.staggerDuration`
- `_config?.attackSequence?...damageSource` **保持不变**。
- `_hitBox`/`_hurtBox`、`OnInterrupted` 不动。

- [ ] **Step 3: 编译门** → count=0。

- [ ] **Step 4: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/Configs/MeleeVulnerabilityAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/MeleeVulnerabilityAbility.cs
git commit -m "refactor(enemy): MeleeVulnerability 参数迁入 MeleeVulnerabilityAbilitySO(子类)"
```

---

## Task 7: 三个单片段能力（Appear / FacePlayer / PlayClip）子类 SO + 迁移

**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/AppearAbilitySO.cs`
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/FacePlayerAbilitySO.cs`
- Create: `Assets/_Game/Scripts/Enemies/Abilities/Configs/PlayClipAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/AppearAbility.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/FacePlayerAbility.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/PlayClipAbility.cs`

- [ ] **Step 1: 建三个子类 SO**

`AppearAbilitySO.cs`:
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>AppearAbility 的配置：出场动画。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Appear Ability", fileName = "ABL_")]
    public class AppearAbilitySO : EnemyAbilitySO
    {
        public ClipTransition appearClip;
    }
}
```
`FacePlayerAbilitySO.cs`:
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>FacePlayerAbility 的配置：转身/翻转动画。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Face Player Ability", fileName = "ABL_")]
    public class FacePlayerAbilitySO : EnemyAbilitySO
    {
        public ClipTransition faceClip;
    }
}
```
`PlayClipAbilitySO.cs`:
```csharp
using Animancer;
using UnityEngine;

namespace BaseGames.Enemies.Abilities
{
    /// <summary>PlayClipAbility 的配置：待播放的单个动画 Clip。</summary>
    [CreateAssetMenu(menuName = "BaseGames/Enemies/Abilities/Play Clip Ability", fileName = "ABL_")]
    public class PlayClipAbilitySO : EnemyAbilitySO
    {
        public ClipTransition clip;
    }
}
```

- [ ] **Step 2: 迁移 AppearAbility**

Read `AppearAbility.cs`。删 `[SerializeField] private ClipTransition _appearClip;`，加：
```csharp
        private AppearAbilitySO _cfg;

        protected override void Awake()
        {
            base.Awake();
            _cfg = ResolveConfig<AppearAbilitySO>();
        }
```
`ExecuteCoroutine` 改为：
```csharp
        protected override IEnumerator ExecuteCoroutine()
        {
            Phase = AbilityRunState.Active;
            if (_cfg == null || _cfg.appearClip.Clip == null) yield break;

            _animancer.Play(_cfg.appearClip);
            yield return EnemyAbilityWaits.Get(_cfg.appearClip.Clip.length);
        }
```

- [ ] **Step 3: 迁移 FacePlayerAbility**

Read `FacePlayerAbility.cs`。删 `_faceClip`，加同款 `_cfg`(类型 `FacePlayerAbilitySO`) + `Awake`。`CanUse` 重写不动。`ExecuteCoroutine` 尾部改：
```csharp
            _enemy.FacePlayer();

            if (_cfg == null || _cfg.faceClip.Clip == null) yield break;

            _animancer.Play(_cfg.faceClip);
            yield return EnemyAbilityWaits.Get(_cfg.faceClip.Clip.length);
```

- [ ] **Step 4: 迁移 PlayClipAbility**

Read `PlayClipAbility.cs`。删 `_clip`，加同款 `_cfg`(类型 `PlayClipAbilitySO`) + `Awake`。`ExecuteCoroutine` 改：
```csharp
        protected override IEnumerator ExecuteCoroutine()
        {
            Phase = AbilityRunState.Active;
            if (_cfg == null || _cfg.clip.Clip == null) yield break;

            _animancer.Play(_cfg.clip);
            yield return EnemyAbilityWaits.Get(_cfg.clip.Clip.length);
        }
```

- [ ] **Step 5: 编译门** → count=0。

- [ ] **Step 6: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/Configs/AppearAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/Configs/FacePlayerAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/Configs/PlayClipAbilitySO.cs Assets/_Game/Scripts/Enemies/Abilities/AppearAbility.cs Assets/_Game/Scripts/Enemies/Abilities/FacePlayerAbility.cs Assets/_Game/Scripts/Enemies/Abilities/PlayClipAbility.cs
git commit -m "refactor(enemy): Appear/FacePlayer/PlayClip 参数迁入各自子类 SO"
```

---

## Task 8: 脚手架——向导按能力类型创建正确子类 SO

**Files:**
- Modify: `Assets/_Game/Scripts/Editor/Shared/EditorScaffoldUtils.cs`（加 Type 版 `CreateSOAsset` 重载）
- Modify: `Assets/_Game/Scripts/Editor/Character/CharacterWizardWindow.cs`（def 带类型 + 透传）

- [ ] **Step 1: `EditorScaffoldUtils` 加 Type 版 `CreateSOAsset` 重载**

Read `EditorScaffoldUtils.cs` 现有泛型 `CreateSOAsset<T>`（约 154 行）。在其后加非泛型重载（复用同样的存在性检查/建目录/保存逻辑）：
```csharp
        /// <summary>按运行时 Type 创建 SO 资产（用于需要动态子类型的场景，如能力子类 SO）。</summary>
        public static ScriptableObject CreateSOAsset(System.Type soType, string folder, string assetName)
        {
            string dir  = folder.TrimEnd('/');
            string path = $"{dir}/{assetName}.asset";

            if (AssetDatabase.LoadAssetAtPath<ScriptableObject>(path) != null)
            {
                Debug.LogWarning($"[EditorScaffoldUtils] 资产已存在，跳过创建：{path}");
                return null;
            }

            EnsureFolder(dir);
            var asset = ScriptableObject.CreateInstance(soType);
            AssetDatabase.CreateAsset(asset, path);
            AssetDatabase.SaveAssets();
            return asset;
        }
```
> 若现有泛型版有额外步骤（如 Selection/Ping），读后与之保持一致；此重载只需产出资产。

- [ ] **Step 2: `GetEnemyAbilityDefs` 加 SO 类型**

在 `CharacterWizardWindow.cs`，把 `GetEnemyAbilityDefs` 的返回元组从 `(string ablName, string ablId)` 扩为 `(string ablName, string ablId, System.Type soType)`，按关键事实映射填类型（未迁移的用基类 `typeof(EnemyAbilitySO)`）：
```csharp
        private static (string ablName, string ablId, System.Type soType)[] GetEnemyAbilityDefs(string enemyId) => enemyId switch
        {
            "E001" => new[] { ("Alert", "e001_alert", typeof(EnemyAbilitySO)),
                              ("Chase", "e001_chase", typeof(ContactChaseAbilitySO)) },
            "E002" => new[] { ("CeilingStrike", "e002_ceiling_strike", typeof(CeilingHangStrikeAbilitySO)) },
            "E003" => new[] { ("Fall", "e003_fall", typeof(AnimatedCeilingDropAbilitySO)) },
            "E004" => new[] { ("Appear", "e004_appear", typeof(AppearAbilitySO)),
                              ("Bite", "e004_bite", typeof(EnemyAbilitySO)),
                              ("HeadSlam", "e004_headslam", typeof(RepeatSlamAbilitySO)),
                              ("Acid", "e004_acid", typeof(EnemyAbilitySO)),
                              ("Flip", "e004_flip", typeof(FacePlayerAbilitySO)) },
            "E005" => new[] { ("Bite", "e005_bite", typeof(EnemyAbilitySO)),
                              ("Acid", "e005_acid", typeof(EnemyAbilitySO)) },
            "E006" => new[] { ("Leap", "e006_leap", typeof(EnemyAbilitySO)),
                              ("Chase", "e006_chase", typeof(ContactChaseAbilitySO)) },
            _      => System.Array.Empty<(string, string, System.Type)>(),
        };
```
文件顶部若未 `using BaseGames.Enemies.Abilities;` 则补上（这些子类型在该命名空间）。

- [ ] **Step 3: `CreateEnemyAbilitySO` 接受类型 + 调用点透传**

改签名与实现：
```csharp
        private static void CreateEnemyAbilitySO(string enemyId, string ablName, string ablId, System.Type soType)
        {
            string dir  = $"Assets/_Game/Data/Enemies/{enemyId}/Abilities";
            string name = $"ABL_{enemyId}_{ablName}";
            var so = EditorScaffoldUtils.CreateSOAsset(soType, dir, name) as EnemyAbilitySO;
            if (so != null)
            {
                so.abilityId = ablId;
                EditorUtility.SetDirty(so);
                AssetDatabase.SaveAssets();
            }
        }
```
更新两处调用点：
- 工厂按钮循环（约 280-285 行）：`foreach (var (ablName, ablId, soType) in GetEnemyAbilityDefs(id))` 且捕获 `soType`，按钮 lambda 改 `CreateEnemyAbilitySO(id, capturedName, capturedId, capturedType)`（新增 `var capturedType = soType;`）。
- `CreateAllEnemySOs`（约 625-626 行）：`foreach (var (ablName, ablId, soType) in GetEnemyAbilityDefs(id)) CreateEnemyAbilitySO(id, ablName, ablId, soType);`
- `RefreshSOStatus` 里若有 `foreach (var (ablName, ablId) in ...)`（约 773 行 items.Add）也改为解构三元组（忽略 `soType` 用弃元 `_`）。

- [ ] **Step 4: 编译门** → count=0。

- [ ] **Step 5: 提交**
```bash
git add Assets/_Game/Scripts/Editor/Shared/EditorScaffoldUtils.cs Assets/_Game/Scripts/Editor/Character/CharacterWizardWindow.cs
git commit -m "feat(wizard): 敌人能力 SO 按能力类型创建正确子类(向导批量创建产出子类 SO)"
```

---

## Task 9: 端到端结构验证 + 自检 + 收尾

**Files:** 无（仅验证）

- [ ] **Step 1: 结构验证（MCP）——子类 SO 有预期字段、能力已改读 SO**

`unity_execute_code`(port 7890)：反射确认 8 个子类型存在且暴露预期字段；确认对应能力 MonoBehaviour **不再**有旧的 `_startClip/_dashSpeed/…` 序列化字段：
```csharp
var sb=new System.Text.StringBuilder();
var asm = System.AppDomain.CurrentDomain.GetAssemblies();
System.Type Find(string n)=>asm.SelectMany(a=>{try{return a.GetTypes();}catch{return new System.Type[0];}}).FirstOrDefault(x=>x.Name==n);
void CheckSO(string so, string[] fields){ var t=Find(so); if(t==null){sb.AppendLine(so+": MISSING"); return;} foreach(var f in fields){ var fi=t.GetField(f); sb.AppendLine(so+"."+f+": "+(fi!=null?fi.FieldType.Name:"MISSING")); } sb.AppendLine(so+" base="+t.BaseType.Name); }
CheckSO("ContactChaseAbilitySO", new[]{"startClip","loopClip","endClip","dashSpeed"});
CheckSO("RepeatSlamAbilitySO", new[]{"startClip","loopClip","endClip","hitActiveTime","slamCount","staggerDuration"});
CheckSO("CeilingHangStrikeAbilitySO", new[]{"strikeClip","loopClip","endClip","hangDuration"});
CheckSO("AnimatedCeilingDropAbilitySO", new[]{"fallLoopClip","fallGravityScale","maxFallTime","groundMask","recoveryTime"});
CheckSO("MeleeVulnerabilityAbilitySO", new[]{"attackClip","hitEnterT","hitExitT","staggerDuration"});
CheckSO("AppearAbilitySO", new[]{"appearClip"});
CheckSO("FacePlayerAbilitySO", new[]{"faceClip"});
CheckSO("PlayClipAbilitySO", new[]{"clip"});
// 能力 MonoBehaviour 不应再有旧序列化字段
var bindings = System.Reflection.BindingFlags.Instance|System.Reflection.BindingFlags.NonPublic;
void NoOldField(string comp, string oldField){ var t=Find(comp); var fi=t?.GetField(oldField, bindings); sb.AppendLine(comp+" 残留 "+oldField+"="+(fi!=null)); }
NoOldField("ContactChaseAbility","_startClip"); NoOldField("ContactChaseAbility","_dashSpeed");
NoOldField("RepeatSlamAbility","_slamCount"); NoOldField("AnimatedCeilingDropAbility","_groundMask");
NoOldField("MeleeVulnerabilityAbility","_hitEnterT"); NoOldField("AppearAbility","_appearClip");
return sb.ToString();
```
期望：各 SO 字段类型齐全、`base=EnemyAbilitySO`；各能力「残留 = False」。

- [ ] **Step 2: 每个子类 `[CreateAssetMenu]` 可见性抽检**：在编辑器 `Assets > Create > BaseGames/Enemies/Abilities/` 下应能看到 8 个新菜单项（人工抽查 1-2 个，或反射确认类型带 `CreateAssetMenuAttribute`）。

- [ ] **Step 3: SO 自检**：菜单 `BaseGames/Tools/Validation/Validate All ScriptableObjects`（`unity_execute_menu_item`）——期望无因新子类型产生的新错误（现有 `ABL_*.asset` 仍是基类，属用户待重建，若校验器对缺失字段报警属预期，记录即可，不在本 Task 修资产）。

- [ ] **Step 4: grep 确认能力脚本无残留迁移字段声明**
```
rg -n "SerializeField.*(ClipTransition|_dashSpeed|_slamCount|_hitActiveTime|_hangDuration|_fallGravityScale|_maxFallTime|_groundMask|_recoveryTime|_hitEnterT|_hitExitT|_staggerDuration)" Assets/_Game/Scripts/Enemies/Abilities/*.cs
```
期望：0 命中（8 个能力的迁移字段声明都已删除；`Configs/` 子目录里的是 public 字段，不带 `[SerializeField]`，不会命中）。

- [ ] **Step 5: 更新记忆** `editor_scaffold_tools.md` 或新增记忆：记录「敌人能力参数现由 `XxxAbilitySO : EnemyAbilitySO` 子类承载；`EnemyAbilityBase.ResolveConfig<T>` 类型不符显式报错；场景组件引用（BodyContactDamage/HitBox/HurtBox）仍在 MonoBehaviour；向导按能力类型创建子类 SO；现有 ABL_ 资产需重建为子类」。

---

## Self-Review（作者已核对）

- **Spec 覆盖**：§A 子类 SO→Task 2-7（8 个子类）；§B `ResolveConfig` 显式报错→Task 1；§C MonoBehaviour 删字段+读 SO+空守卫→Task 2-7；§D 脚手架/创建入口→Task 8；§E 迁移（用户重建）→全程不动资产 + Task 9 记录；验证→各 Task 编译门 + Task 1 单测 + Task 9 结构验证。场景引用保留→每个迁移 Task 显式「保留」。
- **占位符**：无 TBD；每个 SO 给完整文件；每个 MonoBehaviour 给「删哪些行 + 新字段/Awake 块 + 使用处替换清单 + 空守卫」；Task 8 给完整映射表与调用点。
- **类型一致**：`ResolveConfig<T>() where T : EnemyAbilitySO → T`；子类名 `ContactChaseAbilitySO/RepeatSlamAbilitySO/CeilingHangStrikeAbilitySO/AnimatedCeilingDropAbilitySO/MeleeVulnerabilityAbilitySO/AppearAbilitySO/FacePlayerAbilitySO/PlayClipAbilitySO` 贯穿 Task 2-9；字段名（`startClip/loopClip/endClip/dashSpeed/hitActiveTime/slamCount/staggerDuration/hangDuration/strikeClip/fallLoopClip/fallGravityScale/maxFallTime/groundMask/recoveryTime/attackClip/hitEnterT/hitExitT/appearClip/faceClip/clip`）在 SO 定义与 MonoBehaviour 使用处一致；`CreateSOAsset(Type,…)` 重载签名一致。
- **已知风险**：(1) `_config.attackSequence[...].damageSource` 保持用基类 `_config`（未改 `_cfg`），因 `_cfg` 可能因类型错为 null 而 `_config` 仍有效——已在相关 Task 显式「保持不变」。(2) EditMode 反射跑 `LogAssert` 可能需真 Test Runner——Task 1 Step 5 给了回退（编辑器 Test Runner 手动跑）。(3) 现有 17 个 `ABL_` 资产仍是基类，运行时会触发 `ResolveConfig` 报错——这是**预期的显式报错**，提示用户重建（符合 §6，非缺陷）。