basegames/zeling_v2
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
24c612930e85b6a47b50997409fbd47a0a30da11
zeling_v2/Docs_Dev/superpowers/plans/2026-07-30-boss-ai-single-track.md
T
joywayer 24c612930e docs(enemy): 记录 EditMode 不触发 Awake 的坑，并分派两处越界发现 
执行须知第 4 条：EditMode 下 AddComponent 不调用 Awake（Task 4 实测证实）。
后果是 EnemyAbilityBase._enemy 留空使 CanUse 恒假——依赖它的断言在修复前
也会通过，成为永远不会失败的测试。做法是给测试子类加 RunAwake() 显式触发，
不要反射直写字段。

Task 5 追加：IAttackCandidate 的 CanUse 注释补上 enabled 这一维。
Task 21 追加：EnemyQuotaManager._maxActiveBehaviorTrees 改名须带
FormerlySerializedAs，否则丢场景配置值。
2026-07-30 13:30:44 +08:00

2916 lines
123 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Boss AI 双轨统一 实施计划
> **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:** 把 Boss 的决策层与执行层一并归并到小怪轨（BrainGraph + `EnemyAbilitySO`），退役 `BossSkillSO` / `BossSkillExecutor` 整套旧轨及其两条脚手架创建链路，并让嘲风真正能打。
**Architecture:** 决策归 AI 图（每 Boss 一个 `AiScript` 定制类），编排归动画时间轴（clip + 归一化时机 + 动画事件），"能不能用"归招式自己（`CanUse` + 组件启用），"选哪个"归 `EnemyAttackSelector`，演出归旁挂组件。Boss 专属仅一个 `IBossControl` facet（阶段）+ 几个旁挂 MonoBehaviour。
**Tech Stack:** Unity 6 / C# 9、Animancer、UI Toolkit（编辑器）、NUnit（EditMode 测试）、自研 `BrainGraph`（`BrainBuilder` / `AiRuntime` / `AiGraph`）
**Spec:** `Docs_Dev/superpowers/specs/2026-07-30-boss-ai-single-track-design.md`
---
## 执行须知
### 分两阶段，各自独立可提交
- **阶段一（Task 1–15）：只加不删。** 每个 Task 结束时工程编译通过、测试全绿。阶段一末尾嘲风已能用新轨打起来，旧轨仍在但已无人调用。
- **阶段二（Task 16–21）：删旧轨。** 顺序不可乱：先改引用方（`BossBase` / `BossResource` / 两个脚手架），再删被引用的类型；先删资产，再删脚本。
**任何时刻工程都必须能编译。** 每个 Task 的最后一步都是提交。
### 怎么跑测试与编译检查
本项目无命令行测试入口，一律经 Unity Editor：
- **编译检查**：MCP `mcp__unity__unity_get_compilation_errors`。期望 `0 errors, 0 warnings`。
- **跑 EditMode 测试**：Unity 菜单 `Window > General > Test Runner` → `EditMode` 页 → 选中目标测试 → `Run Selected`。
或经 MCP `mcp__unity__unity_execute_menu_item`。
- **三件自检工具**（阶段末尾跑）：
- `BaseGames/Tools/Validation/Validate All ScriptableObjects`
- `BaseGames/Addressables/Validate Address Keys`
- `BaseGames/Tools/Maintenance/Physics2D Layer Matrix/Check`
⚠️ **MCP 卡死排查**：Unity 编辑器窗口失焦会让 MCP 队列无限期卡住（不是超时）。若某个 MCP 调用长时间无返回，把 Unity 窗口置前即可恢复，不要盲目重试。
### 两个实测踩过的坑（Task 3 执行时发现）
**1. `EnemyBase.Abilities` 属性遮蔽 `BaseGames.Enemies.Abilities` 命名空间。**
`EnemyBase` 有 `public EnemyAbilityRegistry Abilities { get; }`。在**类型位置**
`new Abilities.EnemyAttackSelector(...)` 能编译（解析为命名空间），但在**成员访问位置**
`Abilities.EnemyAttackSelector.SomeConst` 编译失败（解析为那个属性）。
在 `EnemyBase` 内引用该命名空间下的静态成员时必须写全 `BaseGames.Enemies.Abilities.…`。
Task 16 / 17 都要改 `EnemyBase`，会再遇到。
**2. `unity_get_compilation_errors` 在程序集编译成功时不报警告。**
Unity 只对**编译失败**的程序集给出完整诊断集。`ChargeAbility.cs:29-30` 有两个既存
`CS0414`（`[SerializeField]` 但从未读取），在绿色构建下完全不可见。
所以"0 errors 0 warnings"是这个上报口径下的结果，不等于真的零警告——
后续任务若在构建一度失败时看到这两条，那是既存问题，不是自己引入的。
**3. MCP 测试运行器忽略过滤参数。** `unity_testing_run_tests` 的 `testFilter` / `filter` 无效，
每次都跑整个 EditMode 套件。这不影响正确性（等于免费拿到全量回归），但别把全量结果误读成过滤结果。
**4. ⚠️ EditMode 下 `AddComponent` 不触发 `Awake`。**（Task 4 实测证实）
普通 MonoBehaviour 在编辑模式下 `AddComponent` 后 `Awake` **不会被调用**。
后果：任何依赖 `Awake` 解析引用的成员在 EditMode 测试里都是未初始化状态。
具体地，`EnemyAbilityBase._enemy` 会留空，使 `CanUse` **恒为 false**——
断言"禁用后不可用"会在修复前也通过，是个永远不会失败的测试。
做法：给测试用的子类加一个 `public void RunAwake() => Awake();` 显式触发，
**不要**用反射直写字段——前者跑的是真实的 `GetComponentInParent` 解析路径，后者是伪造结果。
只检查 `enabled` 标志本身（如阶段门的启停断言）则不需要 `Awake`。
### 项目硬约束
1. **禁止下游兜底**（CLAUDE.md 第 6 条）：不要用 `?? 默认值` / `try-catch` / `if(null) return` 掩盖上游漏配。缺配置就 `Debug.LogError` 或抛异常。
2. **代码里禁止出现其他游戏名**（CLAUDE.md 第 4 条）：注释 / `[Tooltip]` / `[Header]` / 命名一律只描述功能。
3. **已关闭 Domain Reload**：新增的 SO 运行时缓存态必须走 `PlayModeResetHook`；静态态走 `[RuntimeInitializeOnLoadMethod]`。本计划新增的都是 MonoBehaviour 运行时态，靠 `OnSpawn` 重置。
4. **资产必须经脚手架创建**（第 2 条）：不裸 `CreateAsset`。这正是 Task 13–15 存在的原因。
---
## 文件结构
### 新建
| 文件 | 责任 |
|---|---|
| `Assets/_Game/Scripts/AI/IBossControl.cs` | Boss 专属决策面（阶段 + 资源满值查询）。放 `BaseGames.AI`，不引用 Enemies |
| `Assets/_Game/Scripts/Enemies/Boss/BossPhaseAbilityGate.cs` | 阶段=换招池：按阶段启停能力组件 |
| `Assets/_Game/Scripts/Enemies/Boss/BossArenaAnchors.cs` | 竞技场锚点集合（一组 Transform） |
| `Assets/_Game/Scripts/Enemies/Boss/BossFightTrigger.cs` | 开战触发：发 `EVT_BossFightStarted` + `AiSignal.Engaged` |
| `Assets/_Game/Scripts/Enemies/AIBrain/Modules/BossFragments.cs` | Boss 图共享建态片段（阶段过渡 / 逼近选招 / 移动到锚点） |
| `Assets/_Game/Scripts/Enemies/AIBrain/Ai/ChaoFengAi.cs` | 嘲风的 `AiScript` 定制图 |
| `Assets/Tests/EditMode/AI/Fakes/FakeBossControl.cs` | 测试用 `IBossControl` 假实现 |
| `Assets/Tests/EditMode/AI/ChaoFengAiTests.cs` | 嘲风图状态序列断言 |
| `Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs` | 阶段门启停集断言 |
| `Assets/Tests/EditMode/Enemies/EnemyBrainContextBossFacetTests.cs` | 非 Boss 访问 `Boss` facet 抛异常 |
| `Assets/Tests/EditMode/Combat/HurtBoxMultiplierTests.cs` | 弱点倍率断言 |
### 修改
| 文件 | 改动 |
|---|---|
| `Assets/_Game/Scripts/AI/IAiContext.cs` | `+ IBossControl Boss { get; }` |
| `Assets/_Game/Scripts/AI/AiSignal.cs` | `+ Engaged` |
| `Assets/_Game/Scripts/Enemies/AIBrain/EnemyBrainContext.cs` | 实现 `Boss`（非 Boss 抛异常） |
| `Assets/_Game/Scripts/Enemies/Boss/BossBase.cs` | 实现 `IBossControl`；接阶段门；阶段二瘦身约 150 行 |
| `Assets/_Game/Scripts/Enemies/Boss/BossResource.cs` | `+ IsFull`；阶段二删自动触发 |
| `Assets/_Game/Scripts/Enemies/Boss/BossResourceConfigSO.cs` | 阶段二删自动触发三字段 |
| `Assets/_Game/Scripts/Enemies/Boss/ChaoFengBoss.cs` | `StopBehaviorTree()` 调用点改名 |
| `Assets/_Game/Scripts/Enemies/Abilities/AttackSelectionMode.cs` | `+ WeightedRandomAntiRepeat` |
| `Assets/_Game/Scripts/Enemies/Abilities/EnemyAttackSelector.cs` | 防重复权重折扣 |
| `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs` | `CanUse += enabled`；阶段二删 `TelegraphRoutine` |
| `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs` | `+ designNote`；`fileName → ABL_`；阶段二删 telegraph 两字段 |
| `Assets/_Game/Scripts/Enemies/EnemyStatsSO.cs` | `+ attackAntiRepeatFactor` |
| `Assets/_Game/Scripts/Enemies/EnemyBase.cs` | 选招器传系数；阶段二改名 `NotifyDecisionStop`、删 `ConsumeParryEvent` |
| `Assets/_Game/Scripts/Enemies/Behaviors/EnemyDeathSequence.cs` | 调用点改名 |
| `Assets/_Game/Scripts/Enemies/AIBrain/Modules/Engagement/ApproachAttackEngagement.cs` | 建态逻辑提 `internal static` |
| `Assets/_Game/Scripts/Animation/EnemyAnimationEvents.cs` | `+ 4 case`、`+ _hurtBox` / `_feedback` |
| `Assets/_Game/Scripts/Combat/HurtBox.cs` | `+ _damageMultiplier` |
| `Assets/_Game/Scripts/Editor/Character/CharacterWizardWindow.cs` | Boss 页改建 `EnemyAbilitySO` |
| `Assets/_Game/Scripts/Editor/Scene/SceneObjectPlacerTool.cs` | `PlaceChaoFeng` 改挂新轨组件 |
| `Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs` | `+ Boss` |
| `Assets/Tests/EditMode/Enemies/EnemyAttackSelectorTests.cs` | `+ 防重复测试` |
### 删除（阶段二）
```
Assets/_Game/Data/Enemies/ChaoFeng/Abilities/ABL_ChaoFeng_{Boomerang,FanCombo,TornadoSmall,TornadoLarge,WindStone}.asset
Assets/_Game/Scripts/Enemies/Boss/BossSkillSO.cs
Assets/_Game/Scripts/Enemies/Boss/AttackPatternSO.cs
Assets/_Game/Scripts/Enemies/Boss/SkillSequenceSO.cs
Assets/_Game/Scripts/Enemies/Boss/BossSkillExecutor.cs
Assets/_Game/Scripts/Enemies/Boss/BossSkillTypes.cs
Assets/_Game/Scripts/Enemies/Boss/WeakPointSystem.cs
Assets/_Game/Scripts/Enemies/Boss/Patterns/TelegraphSystem.cs
Assets/_Game/Scripts/Editor/Modules/BossSkillModule.cs
Assets/_Game/Scripts/Editor/Enemies/BossSkillSequenceWindow.cs
```
---
# 阶段一：加通（只加不删）
## Task 1: `IBossControl` 接口与 `IAiContext.Boss` 接缝
**Files:**
- Create: `Assets/_Game/Scripts/AI/IBossControl.cs`
- Modify: `Assets/_Game/Scripts/AI/IAiContext.cs`
- Create: `Assets/Tests/EditMode/AI/Fakes/FakeBossControl.cs`
- Modify: `Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs`
- [ ] **Step 1: 建 `IBossControl`**
`Assets/_Game/Scripts/AI/IBossControl.cs`：
```csharp
namespace BaseGames.AI
{
/// <summary>
/// Boss 专属决策面。挂在 <see cref="IAiContext"/> 上供 Boss 图读取阶段状态、发起阶段过渡、
/// 查询竞技场锚点。只暴露"决策需要知道的"，过渡演出与无敌帧由实现方（BossBase）负责。
/// 非 Boss 敌人访问 <see cref="IAiContext.Boss"/> 会抛异常——这是有意的显式失败。
/// </summary>
public interface IBossControl
{
/// <summary>当前阶段索引（出生为 0）。</summary>
int CurrentPhase { get; }
/// <summary>是否处于阶段过渡（无敌 + 过渡演出）期间。</summary>
bool IsPhaseTransitioning { get; }
/// <summary>Boss 资源是否已满（无资源组件时恒为 false）。</summary>
bool ResourceFull { get; }
/// <summary>发起阶段过渡：无敌 invincibleDuration 秒后切入 targetPhase。</summary>
void BeginPhaseTransition(int targetPhase, float invincibleDuration);
// 竞技场锚点两成员（AnchorAt / DistanceToAnchor）在 Task 10 与
// BossArenaAnchors 组件一并加入——此刻加会让 Task 2–8 期间 BossBase 编译不过。
}
}
```
> `using UnityEngine;` 此刻还用不上（`Vector2` 在 Task 10 才引入），先不写，Task 10 再加。
- [ ] **Step 2: `IAiContext` 加 `Boss`**
`Assets/_Game/Scripts/AI/IAiContext.cs`，在 `Blackboard Blackboard { get; }` 之后追加：
```csharp
/// <summary>
/// Boss 专属决策面。**非 Boss 敌人访问本属性会抛 InvalidOperationException**——
/// 小怪图误用 Boss 边必须立刻暴露，不返回空对象把问题盖住。
/// </summary>
IBossControl Boss { get; }
```
- [ ] **Step 3: 建 `FakeBossControl`**
`Assets/Tests/EditMode/AI/Fakes/FakeBossControl.cs`：
```csharp
using BaseGames.AI;
namespace BaseGames.Tests.EditMode.AI
{
public sealed class FakeBossControl : IBossControl
{
public int Phase;
public bool Transitioning;
public bool Full;
// 记录最近一次过渡请求，供断言"图确实发起了过渡"
public int LastTargetPhase = -1;
public float LastDuration = -1f;
public int BeginCallCount;
// 锚点：测试按下标直给坐标；距离由测试直接设定
public UnityEngine.Vector2[] Anchors = new UnityEngine.Vector2[0];
public float DistanceToAnchorValue;
public int CurrentPhase => Phase;
public bool IsPhaseTransitioning => Transitioning;
public bool ResourceFull => Full;
public void BeginPhaseTransition(int targetPhase, float invincibleDuration)
{
LastTargetPhase = targetPhase;
LastDuration = invincibleDuration;
BeginCallCount++;
Transitioning = true; // 由测试手工置回 false 模拟过渡结束
}
public UnityEngine.Vector2 AnchorAt(int index) => Anchors[index];
public float DistanceToAnchor(int index) => DistanceToAnchorValue;
}
}
```
- [ ] **Step 4: `FakeAiContext` 暴露 `Boss`**
`Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs`，在 `FakeAiContext` 类里追加字段与属性：
```csharp
public FakeBossControl B = new FakeBossControl();
public IBossControl Boss => B;
```
- [ ] **Step 5: 编译检查**
MCP `mcp__unity__unity_get_compilation_errors`。
期望：因 `EnemyBrainContext` 未实现 `Boss` 而报 1 个错误
（`'EnemyBrainContext' does not implement interface member 'IAiContext.Boss'`）——下一个 Task 修。
- [ ] **Step 6: 暂不提交**
本 Task 故意留下编译错误，与 Task 2 合并提交。跳过提交，直接进 Task 2。
---
## Task 2: `EnemyBrainContext` 实现 `Boss`，`BossBase` 实现 `IBossControl`
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/AIBrain/EnemyBrainContext.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Boss/BossBase.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Boss/BossResource.cs`
- Test: `Assets/Tests/EditMode/Enemies/EnemyBrainContextBossFacetTests.cs`
- [ ] **Step 1: 写失败测试**
`Assets/Tests/EditMode/Enemies/EnemyBrainContextBossFacetTests.cs`：
```csharp
using System;
using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;
using BaseGames.Enemies;
namespace BaseGames.Tests.EditMode.Enemies
{
public class EnemyBrainContextBossFacetTests
{
// EnemyBase.Awake 会对缺失的碰撞体/引用报错，这些与本测试无关。
[SetUp] public void SetUp() => LogAssert.ignoreFailingMessages = true;
[TearDown] public void TearDown() => LogAssert.ignoreFailingMessages = false;
static T MakeEnemy<T>(string name) where T : EnemyBase
{
var go = new GameObject(name);
return go.AddComponent<T>();
}
[Test]
public void NonBoss_AccessingBossFacet_Throws()
{
var enemy = MakeEnemy<EnemyBase>("plain-enemy");
var ctx = new EnemyBrainContext(enemy);
Assert.Throws<InvalidOperationException>(() => { var _ = ctx.Boss; });
UnityEngine.Object.DestroyImmediate(enemy.gameObject);
}
[Test]
public void Boss_AccessingBossFacet_ReturnsTheBoss()
{
var boss = MakeEnemy<BossBase>("boss");
var ctx = new EnemyBrainContext(boss);
Assert.AreSame(boss, ctx.Boss);
Assert.AreEqual(0, ctx.Boss.CurrentPhase);
Assert.IsFalse(ctx.Boss.IsPhaseTransitioning);
Assert.IsFalse(ctx.Boss.ResourceFull); // 未挂 BossResource
UnityEngine.Object.DestroyImmediate(boss.gameObject);
}
}
}
```
- [ ] **Step 2: 跑测试确认失败**
Test Runner → EditMode → `EnemyBrainContextBossFacetTests`。
期望：编译失败（`EnemyBrainContext` 未实现 `Boss`、`BossBase` 未实现 `IBossControl`）。
- [ ] **Step 3: `BossResource` 加 `IsFull`**
`Assets/_Game/Scripts/Enemies/Boss/BossResource.cs`，在 `NormalizedValue` 属性之后追加：
```csharp
/// <summary>资源是否已达上限（供 AI 图条件边判定"可放大招"）。</summary>
public bool IsFull => _config != null && _config.maxValue > 0f
&& _currentValue >= _config.maxValue;
```
- [ ] **Step 4: `BossBase` 实现 `IBossControl`**
`Assets/_Game/Scripts/Enemies/Boss/BossBase.cs`：
1. 类声明改为：
```csharp
public class BossBase : EnemyBase, BaseGames.AI.IBossControl
```
2. 在 `public int CurrentPhase => _currentPhase;` 之后追加：
```csharp
/// <summary>Boss 资源是否已满（未挂资源组件时恒为 false）。IBossControl 实现。</summary>
public bool ResourceFull => _bossResource != null && _bossResource.IsFull;
```
`CurrentPhase` / `IsPhaseTransitioning` / `BeginPhaseTransition(int, float)` 三个成员已存在且签名匹配，
无需改动（`BeginPhaseTransition` 的可选参数不影响接口实现）。
3. 顺带把 `CurrentPhase` 与 `IsBossSkillExecuting` 的注释里残留的 `BD_UseBossSkill` / `BD Task` 字样删掉
（行为树债，CLAUDE.md 第 4 条同款问题）：
```csharp
/// <summary>当前是否有 Boss 技能正在执行。</summary>
public bool IsBossSkillExecuting => _skillExecutor != null && _skillExecutor.IsExecuting;
```
```csharp
/// <summary>当前 Boss 阶段索引。IBossControl 实现。</summary>
public int CurrentPhase => _currentPhase;
```
- [ ] **Step 5: `EnemyBrainContext` 实现 `Boss`**
`Assets/_Game/Scripts/Enemies/AIBrain/EnemyBrainContext.cs`：
1. 文件顶部加 `using System;`（现有 using 只有 `UnityEngine` 与 `BaseGames.AI`）。
2. 字段与构造函数改为：
```csharp
readonly EnemyBase _enemy;
readonly BossBase _boss;
readonly Blackboard _blackboard = new Blackboard();
Vector2 _lastKnown;
float _lostTimer;
public EnemyBrainContext(EnemyBase enemy)
{
_enemy = enemy;
_boss = enemy as BossBase; // 非 Boss 为 null，Boss facet 访问时显式抛
}
```
3. 在 `public Blackboard Blackboard => _blackboard;` 之后追加：
```csharp
/// <summary>
/// Boss 专属决策面。非 Boss 敌人访问即抛——小怪图误挂了 Boss 边必须立刻暴露，
/// 不返回空对象让错误静默通过（CLAUDE.md 第 6 条）。
/// </summary>
public IBossControl Boss => _boss ?? throw new InvalidOperationException(
$"[EnemyBrainContext] '{_enemy.name}' 不是 Boss（未挂 BossBase 或其子类），" +
"但它的 AI 图访问了 IAiContext.Boss。请检查该敌人是否误用了 Boss 专属的图或图片段。");
```
- [ ] **Step 6: 跑测试确认通过**
Test Runner → EditMode → `EnemyBrainContextBossFacetTests`。期望：2 passed。
- [ ] **Step 7: 全量 EditMode 回归**
Test Runner → EditMode → `Run All`。期望：全绿（`FakeAiContext` 已在 Task 1 补上 `Boss`）。
- [ ] **Step 8: 提交**
```bash
git add Assets/_Game/Scripts/AI/IBossControl.cs Assets/_Game/Scripts/AI/IBossControl.cs.meta \
Assets/_Game/Scripts/AI/IAiContext.cs \
Assets/_Game/Scripts/Enemies/AIBrain/EnemyBrainContext.cs \
Assets/_Game/Scripts/Enemies/Boss/BossBase.cs \
Assets/_Game/Scripts/Enemies/Boss/BossResource.cs \
Assets/Tests/EditMode/AI/Fakes/ \
Assets/Tests/EditMode/Enemies/EnemyBrainContextBossFacetTests.cs \
Assets/Tests/EditMode/Enemies/EnemyBrainContextBossFacetTests.cs.meta
git commit -m "feat(ai): 新增 IBossControl facet——Boss 阶段状态经 IAiContext 供图读取
非 Boss 敌人访问 IAiContext.Boss 显式抛 InvalidOperationException，
不返回空对象掩盖小怪图误挂 Boss 边的错误。BossResource 补 IsFull 供图条件边判定。"
```
---
## Task 3: 选招器防重复
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/AttackSelectionMode.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAttackSelector.cs`
- Modify: `Assets/_Game/Scripts/Enemies/EnemyStatsSO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/EnemyBase.cs`
- Test: `Assets/Tests/EditMode/Enemies/EnemyAttackSelectorTests.cs`
- [ ] **Step 1: 写失败测试**
`Assets/Tests/EditMode/Enemies/EnemyAttackSelectorTests.cs`，在 `Weighted_NeverPicksIneligible` 之后追加：
```csharp
// ── WeightedRandomAntiRepeat ─────────────────────────────────────────
static EnemyAttackSelector SelAntiRepeat(float factor, params IAttackCandidate[] cs)
=> new EnemyAttackSelector(new List<IAttackCandidate>(cs), factor);
[Test]
public void AntiRepeat_ZeroFactor_NeverPicksSameTwiceWhenAlternativeExists()
{
var a = new FakeCandidate { WeightV = 1f };
var b = new FakeCandidate { WeightV = 1f };
var s = SelAntiRepeat(0f, a, b);
var prev = s.Select(true, true, AttackSelectionMode.WeightedRandomAntiRepeat);
for (int i = 0; i < 100; i++)
{
var cur = s.Select(true, true, AttackSelectionMode.WeightedRandomAntiRepeat);
Assert.AreNotSame(prev, cur, "系数为 0 时不应连续选中同一招");
prev = cur;
}
}
[Test]
public void AntiRepeat_ZeroFactor_SingleCandidate_StillReturnsIt()
{
// 只有一招时折扣会把权重压到 0，WeightedPick 返回 -1；
// 必须退化为 Priority 路径把它选出来，否则敌人永远不出手。
var only = new FakeCandidate { WeightV = 1f };
var s = SelAntiRepeat(0f, only);
for (int i = 0; i < 10; i++)
Assert.AreSame(only, s.Select(true, true, AttackSelectionMode.WeightedRandomAntiRepeat));
}
[Test]
public void AntiRepeat_DiscountsPreviousPick_ButDoesNotBanIt()
{
// 系数 0.5：a 被选过后权重折半，但仍有机会再被选中。
var a = new FakeCandidate { WeightV = 1f };
var b = new FakeCandidate { WeightV = 1f };
var s = SelAntiRepeat(0.5f, a, b);
s.Select(true, true, AttackSelectionMode.WeightedRandomAntiRepeat);
int repeats = 0;
var prev = s.LastPicked;
for (int i = 0; i < 400; i++)
{
var cur = s.Select(true, true, AttackSelectionMode.WeightedRandomAntiRepeat);
if (ReferenceEquals(cur, prev)) repeats++;
prev = cur;
}
Assert.Greater(repeats, 0, "折扣不应等于禁用");
Assert.Less (repeats, 200, "折扣后重复率应低于无折扣时的约 50%");
}
[Test]
public void AntiRepeat_IneligiblePrevious_DoesNotBlockOthers()
{
var a = new FakeCandidate { WeightV = 1f };
var b = new FakeCandidate { WeightV = 1f };
var s = SelAntiRepeat(0f, a, b);
var first = s.Select(true, true, AttackSelectionMode.WeightedRandomAntiRepeat);
((FakeCandidate)first).CanUseV = false; // 上一招进冷却
var second = s.Select(true, true, AttackSelectionMode.WeightedRandomAntiRepeat);
Assert.IsNotNull(second);
Assert.AreNotSame(first, second);
}
[Test]
public void PlainWeighted_DoesNotApplyAntiRepeat()
{
// WeightedRandom 模式下唯一候选恒被选中（回归：折扣不得泄漏到旧模式）
var only = new FakeCandidate { WeightV = 1f };
var s = SelAntiRepeat(0f, only);
for (int i = 0; i < 10; i++)
Assert.AreSame(only, s.Select(true, true, AttackSelectionMode.WeightedRandom));
}
```
- [ ] **Step 2: 跑测试确认失败**
Test Runner → EditMode → `EnemyAttackSelectorTests`。
期望：编译失败（`AttackSelectionMode.WeightedRandomAntiRepeat` 不存在、构造函数无第二参数、`LastPicked` 不存在）。
- [ ] **Step 3: 加枚举值**
`Assets/_Game/Scripts/Enemies/Abilities/AttackSelectionMode.cs` 全文替换为：
```csharp
namespace BaseGames.Enemies.Abilities
{
/// <summary>多攻击选招策略。</summary>
public enum AttackSelectionMode
{
WeightedRandom, // 合格集内按 weight 加权随机
Priority, // 合格集内取 priority 最高（并列取首个）
WeightedRandomAntiRepeat, // 同 WeightedRandom，但对上一次选中的招施加权重折扣，压低连续重复
}
}
```
⚠️ 新值必须**追加在末尾**：枚举按整数序列化，插在中间会让已有资产的选招模式静默变成另一种。
- [ ] **Step 4: 选招器实现折扣**
`Assets/_Game/Scripts/Enemies/Abilities/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;
// 权重缓冲区（与 _candidates 等长，每次选招复用）：避免每次选招 new List 造成 GC
private readonly List<float> _weightBuf;
// 防重复折扣系数：0 = 有替代时绝不连续重复，1 = 不惩罚
private readonly float _antiRepeatFactor;
private IAttackCandidate _lastPicked;
public EnemyAttackSelector(IEnumerable<IAttackCandidate> candidates, float antiRepeatFactor = 0.3f)
{
_candidates = new List<IAttackCandidate>(candidates);
_weightBuf = new List<float>(_candidates.Count);
_antiRepeatFactor = Mathf.Clamp01(antiRepeatFactor);
}
public int Count => _candidates.Count;
/// <summary>上一次实际选中的招（防重复折扣的作用对象；供测试与调试面板读取）。</summary>
public IAttackCandidate LastPicked => _lastPicked;
/// <summary>对象池复用 / 阶段切换时清除防重复记忆。</summary>
public void ResetRepeatMemory() => _lastPicked = null;
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)
{
switch (mode)
{
case AttackSelectionMode.Priority:
return Remember(SelectByPriority(hasLOS, grounded));
case AttackSelectionMode.WeightedRandomAntiRepeat:
return Remember(SelectByWeight(hasLOS, grounded, antiRepeat: true));
default:
return Remember(SelectByWeight(hasLOS, grounded, antiRepeat: false));
}
}
// 只在真选中了东西时更新记忆：选空时保留上一招，避免"空一帧就清掉防重复"。
private IAttackCandidate Remember(IAttackCandidate pick)
{
if (pick != null) _lastPicked = pick;
return pick;
}
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, bool antiRepeat)
{
// 有效权重：不合格候选填 0（由共享原语保证零权重项绝不被选中）。缓冲区复用 → 选招零 GC。
_weightBuf.Clear();
for (int i = 0; i < _candidates.Count; i++)
{
var c = _candidates[i];
float w = Eligible(c, hasLOS, grounded) ? Mathf.Max(0f, c.Weight) : 0f;
// 防重复：上一招权重打折。折扣可把权重压到 0——此时若它是唯一候选，
// 下面的 Priority 退化路径会把它选出来，不会出现"敌人永远不出手"。
if (antiRepeat && w > 0f && ReferenceEquals(c, _lastPicked))
w *= _antiRepeatFactor;
_weightBuf.Add(w);
}
int idx = BaseGames.Core.WeightedPick.Index(_weightBuf);
if (idx >= 0) return _candidates[idx];
// 无正权重（合格候选权重全 0，或全被防重复折扣压平）→ 退化为按 Priority 选(并列取首个)
return SelectByPriority(hasLOS, grounded);
}
}
}
```
- [ ] **Step 5: 跑测试确认通过**
Test Runner → EditMode → `EnemyAttackSelectorTests`。期望：全部 passed（原 10 个 + 新 5 个 = 15）。
- [ ] **Step 6: `EnemyStatsSO` 加系数字段**
`Assets/_Game/Scripts/Enemies/EnemyStatsSO.cs`，在 `attackSelectionMode` 字段之后追加：
```csharp
[Tooltip("WeightedRandomAntiRepeat 模式下，上一次选中的招的权重折扣系数。" +
"0 = 有替代招时绝不连续重复；1 = 不惩罚。仅该模式生效")]
[Range(0f, 1f)] public float attackAntiRepeatFactor = 0.3f;
```
- [ ] **Step 7: `EnemyBase` 把系数传给选招器**
`Assets/_Game/Scripts/Enemies/EnemyBase.cs` 的 `BuildAttackSelector()`，最后一行改为：
```csharp
// 折扣系数是策划配置项，未配 StatsSO 的敌人用 0.3 这个合法业务缺省（非掩盖漏配：
// 该模式本身是可选的，没配就等于用默认折扣）。
float antiRepeat = _statsSO != null ? _statsSO.attackAntiRepeatFactor : 0.3f;
_attackSelector = new Abilities.EnemyAttackSelector(candidates, antiRepeat);
```
- [ ] **Step 8: 阶段切换清空防重复记忆**
`Assets/_Game/Scripts/Enemies/Boss/BossBase.cs` 的 `EnterPhase(int phase)`，把
`LastUsedSkillId = null;` 那一行下面追加：
```csharp
// 新阶段换招池，上一阶段的防重复记忆不应跨阶段影响选招
AttackSelector?.ResetRepeatMemory();
```
- [ ] **Step 9: 编译 + 全量回归**
MCP `unity_get_compilation_errors` 期望 0 errors 0 warnings；Test Runner → EditMode → `Run All` 期望全绿。
- [ ] **Step 10: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/AttackSelectionMode.cs \
Assets/_Game/Scripts/Enemies/Abilities/EnemyAttackSelector.cs \
Assets/_Game/Scripts/Enemies/EnemyStatsSO.cs \
Assets/_Game/Scripts/Enemies/EnemyBase.cs \
Assets/_Game/Scripts/Enemies/Boss/BossBase.cs \
Assets/Tests/EditMode/Enemies/EnemyAttackSelectorTests.cs
git commit -m "feat(enemy): 选招器支持防重复折扣——WeightedRandomAntiRepeat
上一次选中的招按 EnemyStatsSO.attackAntiRepeatFactor 折扣权重（默认 0.3）。
折扣把唯一候选压到 0 时退化为 Priority 路径，不会出现敌人永不出手。
阶段切换清空防重复记忆。取代 BossBase.UseBossSkillWeighted 里的同名逻辑。"
```
---
## Task 4: 禁用的能力不可用
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs`
- Test: `Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs`（本 Task 只建文件与第一个测试）
- [ ] **Step 1: 写失败测试**
`Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs`：
```csharp
using System.Collections;
using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;
using BaseGames.Enemies.Abilities;
namespace BaseGames.Tests.EditMode.Enemies
{
public class BossPhaseAbilityGateTests
{
/// 最小可实例化能力：不播动画、不碰 HitBox，只为验证启停与 CanUse。
private sealed class StubAbility : EnemyAbilityBase
{
protected override IEnumerator ExecuteCoroutine() { yield break; }
}
// EnemyAbilityBase.Awake 找不到 EnemyBase 会报错，与本测试无关。
[SetUp] public void SetUp() => LogAssert.ignoreFailingMessages = true;
[TearDown] public void TearDown() => LogAssert.ignoreFailingMessages = false;
[Test]
public void DisabledAbility_IsNotUsable()
{
// 必须先挂 EnemyBase：否则 _enemy==null 会让 CanUse 恒假，
// 这条断言在修复前也会"通过"，成为一个永远不会失败的测试。
var go = new GameObject("ability-host");
go.AddComponent<EnemyBase>(); // 裸 EnemyBase 的 _currentState=Controlled → IsAlive 为真
var ab = go.AddComponent<StubAbility>();
Assert.IsTrue(ab.CanUse,
"前提：启用且宿主存活时应可用——否则下一条断言分不清是 enabled 还是别的门在起作用");
ab.enabled = false;
Assert.IsFalse(ab.CanUse, "禁用的能力组件不可用——否则选招器会选中一个启不动协程的招");
Object.DestroyImmediate(go);
}
}
}
```
> `using BaseGames.Enemies;` 需一并加入 using 区（`EnemyBase` 在该命名空间）。
> `EnemyBase.Awake` 末尾的 `_stats.Initialize(_statsSO)` 会在裸物体上 NRE，
> 但那发生在所有组件解析之后，不影响本测试；`LogAssert.ignoreFailingMessages` 已覆盖噪声。
- [ ] **Step 2: 跑测试确认失败**
Test Runner → EditMode → `BossPhaseAbilityGateTests.DisabledAbility_IsNotUsable`。
期望：**第一条断言通过、第二条 FAIL**——`CanUse` 当前不看 `enabled`，禁用后仍返回 true。
若两条都过，说明测试没测到 `enabled` 这一维，停下来修测试再继续。
- [ ] **Step 3: `CanUse` 纳入 `enabled`**
`Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs`，把 `CanUse` 改为：
```csharp
/// <summary>
/// 统一可用性查询：组件启用 + 冷却完毕 + 未执行中 + 宿主存活。
/// enabled 这一维供阶段门使用——被阶段禁用的能力不得进入选招候选，
/// 否则选招器会选中它然后 StartCoroutine 在禁用组件上必然失败。
/// </summary>
public virtual bool CanUse => enabled && !_isRunning && !IsOnCooldown
&& _enemy != null && _enemy.IsAlive;
```
- [ ] **Step 4: 跑测试确认通过**
Test Runner → EditMode → `BossPhaseAbilityGateTests`。期望：1 passed。
- [ ] **Step 5: 全量回归**
Test Runner → EditMode → `Run All`。期望全绿。
⚠️ 若有测试因"能力默认 enabled=true 但断言了别的路径"而失败，说明该测试原本依赖了错误行为，按新语义修断言。
- [ ] **Step 6: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs \
Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs \
Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs.meta
git commit -m "fix(enemy): 禁用的能力组件不再报告可用
CanUse 纳入 enabled。此前禁用组件仍返回 true，选招器会选中一个
StartCoroutine 必然失败的招。这也是阶段门（按阶段启停能力）的前提。"
```
---
## Task 5: `BossPhaseAbilityGate` 阶段门
**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Boss/BossPhaseAbilityGate.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Boss/BossBase.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/IAttackCandidate.cs`（一行文档修正，见下）
- Test: `Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs`（Task 4 已建，本 Task 追加三条）
> **前置说明**：`StubAbility` 与 `_host` / `TearDown` 骨架在 Task 4 已经建好，含
> `public void RunAwake() => Awake();`（EditMode 不自动跑 `Awake`，见执行须知第 4 条）。
> 本 Task 的三条测试只断言 `enabled` 标志本身，**不需要** `RunAwake`。
>
> **顺带修正**：`IAttackCandidate.cs` 第 9 行把 `CanUse` 注释为 `// 未冷却 + 未运行 + 存活`，
> Task 4 加了 `enabled` 这一维后该注释已不完整。改为 `// 组件启用 + 未冷却 + 未运行 + 存活`。
- [ ] **Step 1: 写失败测试**
`Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs`：
先在文件顶部的 using 区补两行：
```csharp
using System.Reflection;
using BaseGames.Enemies;
```
再在 `DisabledAbility_IsNotUsable` 之后追加：
```csharp
// 阶段门的 _entries 是私有序列化字段——与放置脚手架同样用反射写入。
static void SetEntries(BossPhaseAbilityGate gate, params (EnemyAbilityBase ab, int[] phases)[] items)
{
var arr = new BossPhaseAbilityGate.PhaseEntry[items.Length];
for (int i = 0; i < items.Length; i++)
arr[i] = new BossPhaseAbilityGate.PhaseEntry { ability = items[i].ab, phases = items[i].phases };
typeof(BossPhaseAbilityGate)
.GetField("_entries", BindingFlags.NonPublic | BindingFlags.Instance)
.SetValue(gate, arr);
}
[Test]
public void ApplyPhase_EnablesOnlyAbilitiesAllowedInThatPhase()
{
var go = new GameObject("boss");
var gate = go.AddComponent<BossPhaseAbilityGate>();
var p0 = go.AddComponent<StubAbility>();
var p1Go = new GameObject("p1"); p1Go.transform.SetParent(go.transform);
var p1 = p1Go.AddComponent<StubAbility>();
SetEntries(gate, (p0, new[] { 0 }), (p1, new[] { 1 }));
gate.ApplyPhase(0);
Assert.IsTrue (p0.enabled);
Assert.IsFalse(p1.enabled);
gate.ApplyPhase(1);
Assert.IsFalse(p0.enabled);
Assert.IsTrue (p1.enabled);
Object.DestroyImmediate(go);
}
[Test]
public void ApplyPhase_EmptyPhaseArrayMeansAllPhases()
{
var go = new GameObject("boss");
var gate = go.AddComponent<BossPhaseAbilityGate>();
var any = go.AddComponent<StubAbility>();
SetEntries(gate, (any, new int[0]));
gate.ApplyPhase(0); Assert.IsTrue(any.enabled);
gate.ApplyPhase(7); Assert.IsTrue(any.enabled);
Object.DestroyImmediate(go);
}
[Test]
public void ApplyPhase_UnlistedAbilityIsUntouched()
{
var go = new GameObject("boss");
var gate = go.AddComponent<BossPhaseAbilityGate>();
var listed = go.AddComponent<StubAbility>();
var otherGo = new GameObject("unlisted"); otherGo.transform.SetParent(go.transform);
var unlisted = otherGo.AddComponent<StubAbility>();
SetEntries(gate, (listed, new[] { 1 }));
gate.ApplyPhase(0);
Assert.IsFalse(listed.enabled, "登记的能力应被阶段门管控");
Assert.IsTrue (unlisted.enabled, "未登记的能力不受阶段门影响");
Object.DestroyImmediate(go);
}
```
- [ ] **Step 2: 跑测试确认失败**
Test Runner → EditMode → `BossPhaseAbilityGateTests`。期望：编译失败（`BossPhaseAbilityGate` 不存在）。
- [ ] **Step 3: 建阶段门组件**
`Assets/_Game/Scripts/Enemies/Boss/BossPhaseAbilityGate.cs`：
```csharp
using System;
using UnityEngine;
using BaseGames.Enemies.Abilities;
namespace BaseGames.Enemies
{
/// <summary>
/// 阶段 = 换招池：按当前阶段启用 / 禁用能力组件。
/// 被禁用的能力其 <see cref="EnemyAbilityBase.CanUse"/> 为 false，
/// 因此自动从 <see cref="EnemyAttackSelector"/> 的候选里消失——阶段门不需要碰选招器。
///
/// 由 <see cref="BossBase.EnterPhase"/> 与 <see cref="BossBase.OnSpawn"/> 直接调用
/// （而非订阅阶段频道），保证与阶段切换严格同序。
/// </summary>
public sealed class BossPhaseAbilityGate : MonoBehaviour
{
[Serializable]
public struct PhaseEntry
{
[Tooltip("受阶段管控的能力组件")]
public EnemyAbilityBase ability;
[Tooltip("该能力可用的阶段索引；空数组 = 全阶段可用")]
public int[] phases;
}
[Tooltip("阶段可用性表。未登记的能力不受本组件影响（保持其自身启用状态）")]
[SerializeField] private PhaseEntry[] _entries;
/// <summary>把指定阶段的启用集应用到所有登记的能力。</summary>
public void ApplyPhase(int phase)
{
if (_entries == null) return;
for (int i = 0; i < _entries.Length; i++)
{
var e = _entries[i];
if (e.ability == null) continue;
e.ability.enabled = IsAllowed(e.phases, phase);
}
}
private static bool IsAllowed(int[] phases, int phase)
{
if (phases == null || phases.Length == 0) return true; // 空 = 全阶段
for (int i = 0; i < phases.Length; i++)
if (phases[i] == phase) return true;
return false;
}
#if UNITY_EDITOR
// 漏配显式报错，不静默跳过（CLAUDE.md 第 6 条）
private void OnValidate()
{
if (_entries == null) return;
for (int i = 0; i < _entries.Length; i++)
if (_entries[i].ability == null)
Debug.LogError(
$"[BossPhaseAbilityGate] {name} 第 {i} 项未指定能力组件，该行不会生效。", this);
}
#endif
}
}
```
- [ ] **Step 4: 跑测试确认通过**
Test Runner → EditMode → `BossPhaseAbilityGateTests`。期望：4 passed。
- [ ] **Step 5: `BossBase` 接上阶段门**
`Assets/_Game/Scripts/Enemies/Boss/BossBase.cs`：
1. 在 `[SerializeField] private BossResource _bossResource;` 之后追加：
```csharp
[Header("阶段招池门（可选）")]
[Tooltip("按阶段启用 / 禁用能力组件；未挂载则所有能力全阶段可用")]
[SerializeField] private BossPhaseAbilityGate _phaseGate;
```
2. `Awake()` 里，在 `if (_bossResource == null) ...` 之后追加：
```csharp
if (_phaseGate == null) _phaseGate = GetComponentInChildren<BossPhaseAbilityGate>(true);
```
3. `EnterPhase(int phase)` 里，在 `AttackSelector?.ResetRepeatMemory();`（Task 3 加的）之后追加：
```csharp
// 阶段 = 换招池：先换池，再广播阶段事件，保证订阅方看到的是新池
_phaseGate?.ApplyPhase(phase);
```
⚠️ 顺序：必须在 `_onBossPhaseChanged?.Raise(...)` **之前**。
4. `OnSpawn()` 里，在 `_currentPhase = 0;` 之后追加：
```csharp
_phaseGate?.ApplyPhase(0); // 对象池复用：回到阶段 0 的启用集
```
> 选招器的防重复记忆**不在这里**重置——Task 3 的代码审查发现它该归 `EnemyBase.OnSpawn()`
> （覆盖全部池化敌人，而非只有 Boss），已在 Task 3 的修正里落地。此处只管阶段门。
- [ ] **Step 6: 编译 + 全量回归**
MCP `unity_get_compilation_errors` 期望 0/0；`Run All` 期望全绿。
- [ ] **Step 7: 提交**
```bash
git add Assets/_Game/Scripts/Enemies/Boss/BossPhaseAbilityGate.cs \
Assets/_Game/Scripts/Enemies/Boss/BossPhaseAbilityGate.cs.meta \
Assets/_Game/Scripts/Enemies/Boss/BossBase.cs \
Assets/Tests/EditMode/Enemies/BossPhaseAbilityGateTests.cs
git commit -m "feat(enemy): BossPhaseAbilityGate——阶段即换招池
按阶段启停能力组件，被禁用的招经 CanUse 自动退出选招候选，
阶段门不需要碰选招器。取代 BossSkillSO.availablePhaseIndices。
EnterPhase 先换池后广播；OnSpawn 回阶段 0（对象池复用）。"
```
---
## Task 6: `HurtBox` 弱点伤害倍率
**Files:**
- Modify: `Assets/_Game/Scripts/Combat/HurtBox.cs`
- Test: `Assets/Tests/EditMode/Combat/HurtBoxMultiplierTests.cs`
- [ ] **Step 1: 写失败测试**
`Assets/Tests/EditMode/Combat/HurtBoxMultiplierTests.cs`：
```csharp
using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;
using BaseGames.Combat;
namespace BaseGames.Tests.EditMode.Combat
{
public class HurtBoxMultiplierTests
{
[SetUp] public void SetUp() => LogAssert.ignoreFailingMessages = true;
[TearDown] public void TearDown() => LogAssert.ignoreFailingMessages = false;
[Test]
public void DefaultMultiplier_IsOne()
{
var go = new GameObject("hurtbox");
var hb = go.AddComponent<HurtBox>();
Assert.AreEqual(1f, hb.DamageMultiplier);
Object.DestroyImmediate(go);
}
[Test]
public void SetDamageMultiplier_ClampsToNonNegative()
{
var go = new GameObject("hurtbox");
var hb = go.AddComponent<HurtBox>();
hb.SetDamageMultiplier(2.5f);
Assert.AreEqual(2.5f, hb.DamageMultiplier);
hb.SetDamageMultiplier(-3f);
Assert.AreEqual(0f, hb.DamageMultiplier, "负倍率无意义，钳到 0");
Object.DestroyImmediate(go);
}
[Test]
public void ApplyMultiplier_ScalesRawAmount_AndFloorsAtOne()
{
var go = new GameObject("hurtbox");
var hb = go.AddComponent<HurtBox>();
hb.SetDamageMultiplier(2f);
Assert.AreEqual(20, hb.ApplyDamageMultiplier(10));
hb.SetDamageMultiplier(0f);
Assert.AreEqual(1, hb.ApplyDamageMultiplier(10), "倍率 0 也至少造成 1 点，与防御减免同规则");
hb.SetDamageMultiplier(1f);
Assert.AreEqual(10, hb.ApplyDamageMultiplier(10), "倍率 1 时数值原样通过");
Object.DestroyImmediate(go);
}
}
}
```
- [ ] **Step 2: 跑测试确认失败**
Test Runner → EditMode → `HurtBoxMultiplierTests`。
期望：编译失败（`DamageMultiplier` / `SetDamageMultiplier` / `ApplyDamageMultiplier` 不存在）。
- [ ] **Step 3: 实现倍率**
`Assets/_Game/Scripts/Combat/HurtBox.cs`：
1. 在 `public void SetInvincible(bool value) => _isHurtBoxInvincible = value;` 附近追加字段与 API：
```csharp
// 本 HurtBox 专属的受击倍率（弱点部位 > 1；默认 1 = 无影响）。
// 由能力在弱点窗口期间开关，语义与"这个部位更脆弱"一致。
private float _damageMultiplier = 1f;
/// <summary>本 HurtBox 当前的受击伤害倍率。</summary>
public float DamageMultiplier => _damageMultiplier;
/// <summary>设置受击倍率（弱点窗口开合时调用）。负值钳到 0。</summary>
public void SetDamageMultiplier(float value)
=> _damageMultiplier = UnityEngine.Mathf.Max(0f, value);
/// <summary>
/// 按本 HurtBox 的倍率缩放伤害。最低 1 点，与防御减免同规则
/// （倍率为 0 也不该让攻击完全无效——那属于无敌帧的语义，不是弱点倍率的）。
/// </summary>
public int ApplyDamageMultiplier(int raw)
=> _damageMultiplier == 1f
? raw
: UnityEngine.Mathf.Max(1, UnityEngine.Mathf.RoundToInt(raw * _damageMultiplier));
```
2. 在 `ReceiveDamage` 的伤害管线里插入倍率步骤——找到现有的第 5 步：
```csharp
// 5. 计算 FinalDamage（防御减免，最低 1）
int finalDamage = UnityEngine.Mathf.Max(1, info.Amount - _owner.Defense);
```
改为：
```csharp
// 5. 本 HurtBox 受击倍率（弱点部位；默认 1 时无影响）
info.Amount = ApplyDamageMultiplier(info.Amount);
// 6. 计算 FinalDamage（防御减免，最低 1）
int finalDamage = UnityEngine.Mathf.Max(1, info.Amount - _owner.Defense);
```
并把该行之后原本的注释编号 `// 6.` `// 7.` `// 8.` 依次改为 `// 7.` `// 8.` `// 9.`。
- [ ] **Step 4: 跑测试确认通过**
Test Runner → EditMode → `HurtBoxMultiplierTests`。期望：3 passed。
- [ ] **Step 5: 全量回归 + 提交**
`Run All` 期望全绿。
```bash
git add Assets/_Game/Scripts/Combat/HurtBox.cs \
Assets/Tests/EditMode/Combat/HurtBoxMultiplierTests.cs \
Assets/Tests/EditMode/Combat/HurtBoxMultiplierTests.cs.meta
git commit -m "feat(combat): HurtBox 自带受击伤害倍率
倍率归 HurtBox 自己（弱点部位就是一个倍率 > 1 的 HurtBox），
取代 WeakPointSystem 那份写进私有字段却零调用者的倍率。
默认 1 时数值原样通过，现有行为不变。"
```
---
## Task 7: 敌人侧动画事件补接四件
**Files:**
- Modify: `Assets/_Game/Scripts/Animation/EnemyAnimationEvents.cs`
本 Task 无自动化测试：动画事件路由需要真实 Animancer 时间轴驱动，属手动验证范畴。
验证方式写在 Step 4。
- [ ] **Step 1: 补两个子系统引用**
`Assets/_Game/Scripts/Animation/EnemyAnimationEvents.cs`：
1. 顶部 using 区追加：
```csharp
using BaseGames.Feedback;
```
2. `[Header("子系统引用")]` 区块改为：
```csharp
[Header("子系统引用")]
[SerializeField] private HitBox[] _hitBoxes;
[SerializeField] private HurtBox _hurtBox;
[SerializeField] private EnemyBase _enemy;
```
3. 在 `_bindings` 字段之后追加私有字段：
```csharp
private IFeedbackPlayer _feedback;
```
4. `Awake()` 改为：
```csharp
private void Awake()
{
if (_enemy == null)
_enemy = GetComponentInParent<EnemyBase>();
// IFeedbackPlayer 由父层或同层实现（EnemyFeedback / NullFeedbackPlayer），与玩家侧同写法
_feedback = GetComponentInParent<IFeedbackPlayer>() ?? NullFeedbackPlayer.Instance;
foreach (var b in _bindings)
AnimationEventBinder.Bind(b.clip, b.config, this);
}
```
- [ ] **Step 2: 补四个 case**
`HandleEvent` 的 switch，在 `case AnimationEventType.DisableHitBox:` 之后插入：
```csharp
// ── 无敌帧 ────────────────────────────────────────────────
// 时长由动画时间轴上两个事件的间距表达，不在代码里写常量。
case AnimationEventType.EnableIFrame:
_hurtBox?.SetInvincible(true);
break;
case AnimationEventType.DisableIFrame:
_hurtBox?.SetInvincible(false);
break;
```
在 `case AnimationEventType.AnimationComplete:` 之前插入：
```csharp
// ── 通用反馈 ──────────────────────────────────────────────
// 音效预警：在起手帧播一段可辨识的音，让玩家提前缩小招式可能性。
case AnimationEventType.TriggerFeedback:
if (!string.IsNullOrEmpty(payload))
_feedback.TriggerPreset(payload);
break;
case AnimationEventType.PlaySFX:
if (!string.IsNullOrEmpty(payload))
_feedback.PlaySFXById(payload);
break;
```
- [ ] **Step 3: 编译检查**
MCP `unity_get_compilation_errors`。期望 0 errors 0 warnings。
- [ ] **Step 4: 手动验证（记录到提交说明）**
在 Unity 里检查：任一挂有 `EnemyAnimationEvents` 的敌人 Inspector 上出现新的 `_hurtBox` 槽位。
若项目当前无敌人预制体（E001–E006 已删，见 `Docs_Dev` 中的预制体延后决策），仅确认编译通过与
Inspector 字段出现即可；实际路由在 Task 15 放置嘲风后连同弱点窗口一起验证。
- [ ] **Step 5: 提交**
```bash
git add Assets/_Game/Scripts/Animation/EnemyAnimationEvents.cs
git commit -m "feat(animation): 敌人侧动画事件补接无敌帧与反馈四件
EnableIFrame/DisableIFrame → HurtBox.SetInvincible（与玩家侧同形态，
无敌时长由动画时间轴上两事件间距表达）；TriggerFeedback/PlaySFX →
IFeedbackPlayer，用于音效预警。此前敌人侧只接了 7/20 个事件类型。"
```
---
## Task 8: `EnemyAbilitySO` 设计备注与命名对齐
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs`
- [ ] **Step 1: 加 `designNote`，改 `fileName`，清行为树残留**
`Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs`：
1. `CreateAssetMenu` 改为（与 `AssetFolderSpec.md` 的 `ABL_` 及两个向导的实际命名对齐；
同目录的 `PlayClipAbilitySO` 等子类已在用 `ABL_`）：
```csharp
[CreateAssetMenu(menuName = "BaseGames/Enemies/Enemy Ability", fileName = "ABL_")]
```
2. `[Header("标识")]` 区块改为（顺带删掉 `abilityId` 注释里的行为树残留字样）：
```csharp
[Header("标识")]
[Tooltip("能力唯一 id（全小写英文 + 下划线，如 \"melee_combo\" / \"blink_strike\"）。" +
"AI 图与选招器通过它引用本能力")]
public string abilityId = "ability_id";
[TextArea(1, 4)]
[Tooltip("设计备注（仅供编辑器参考，不影响运行）")]
public string designNote;
```
- [ ] **Step 2: 编译 + 回归 + 提交**
MCP `unity_get_compilation_errors` 期望 0/0；`Run All` 期望全绿。
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs
git commit -m "feat(enemy): EnemyAbilitySO 补设计备注，命名前缀对齐规范
+ designNote（目标体量下能力数量大，设计意图需就近记录）。
fileName 由 EAB_ 改为 ABL_——AssetFolderSpec 第 298 行、两个向导
以及 PlayClipAbilitySO 等子类都用 ABL_，此前只有基类是 EAB_。
顺带清掉 abilityId 注释里的行为树残留字样。"
```
---
## Task 9: `AiSignal.Engaged` 与 `BossFragments`
**Files:**
- Modify: `Assets/_Game/Scripts/AI/AiSignal.cs`
- Modify: `Assets/_Game/Scripts/Enemies/AIBrain/Modules/Engagement/ApproachAttackEngagement.cs`
- Create: `Assets/_Game/Scripts/Enemies/AIBrain/Modules/BossFragments.cs`
- [ ] **Step 1: 加 `Engaged` 信号**
`Assets/_Game/Scripts/AI/AiSignal.cs` 全文替换为：
```csharp
namespace BaseGames.AI
{
/// <summary>
/// 外部 → 决策层的事件信号。事件边不受 IsControllable 让位门阻挡。
/// 只保留真有发送方与消费方的值——无发送方的占位枚举只会变成死值。
/// </summary>
public enum AiSignal
{
/// <summary>敌人已死亡：由 EnemyBase.PerformDeath / NotifyDecisionStop 发出，让决策停止。</summary>
Died,
/// <summary>开战：由竞技场触发器（BossFightTrigger）发出，让 Boss 从静置态进入入场演出。</summary>
Engaged,
}
}
```
- [ ] **Step 2: `ApproachAttackEngagement` 建态逻辑提为静态**
`Assets/_Game/Scripts/Enemies/AIBrain/Modules/Engagement/ApproachAttackEngagement.cs`，
把 `Build` 方法替换为下面两段（态名参数化，使 Boss 图能建多组逼近↔攻击）：
```csharp
public void Build(BrainBuilder b, string rest)
=> Declare(b, Approach, Attack, rest);
/// <summary>
/// 建一组「逼近 ↔ 到射程选招攻击」。态名参数化，供本模块与 Boss 图共用同一份实现
/// （Boss 可能有多个阶段各一组，如地面组与空中组）。
/// 返回 Approach 态的 builder，调用方可在其上继续挂自己的出边（如阶段过渡）。
/// </summary>
internal static BrainBuilder.StateBuilder Declare(
BrainBuilder b, string approach, string attack, string rest)
{
var approachBuilder = b.DeclareState(approach)
.OnEnter(x => x.Locomotion.Pursue(x.Sensor.LastKnown))
.Tick (x => x.Locomotion.Pursue(x.Sensor.LastKnown))
.OnExit(x => x.Locomotion.Stop())
// 边序：attackInRange 先于 leftAllZones。前提是攻击射程恒小于感知区
// （EnemyAttackSelector.Eligible 的 InAttackRange 门），故"够得着"不会在
// "已脱离全部感知"之后仍成立，两条件不会相争。若将来出现射程大于追击区的招式，
// 那属于射程/感知区配置错误，由 AI 配方校验器报出，不要靠调整此处边序绕开。
.To(attack).When(x => x.Combat.HasEligibleAttack(), "attackInRange")
.To(rest) .When(AiStateFragments.LostAllZones, "leftAllZones");
// 攻击一旦起手就打完：刻意不挂 leftAllZones 边。
// 玩家在前摇中跑出感知区时招式仍完整打完，之后经逼近态自然脱战——
// 只多一帧，且消除了"起手到一半凭空收招"的观感缺陷。
b.DeclareState(attack)
.OnEnter(x => { x.Locomotion.Stop(); x.Combat.UseBestAttack(); })
.OnExit (x => x.Combat.InterruptAbilities())
.To(approach).When(x => !x.Combat.IsAbilityRunning(), "attackDone");
return approachBuilder;
}
```
- [ ] **Step 3: 建 `BossFragments`**
`Assets/_Game/Scripts/Enemies/AIBrain/Modules/BossFragments.cs`：
```csharp
using System;
using UnityEngine;
using BaseGames.AI;
namespace BaseGames.Enemies
{
/// <summary>
/// Boss 图的共享建态片段。与 <see cref="AiStateFragments"/> 同级——是静态建态原语，
/// 不是可插拔模块：Boss 图手写，重复的形状抽成片段即可，不需要 SO 下拉与多态序列化。
/// </summary>
public static class BossFragments
{
/// <summary>
/// 阶段过渡态：进入时发起过渡（无敌 + 演出由 BossBase 负责），过渡结束后由调用方挂出边。
/// 只发起一次——OnEnter 而非 Tick，因为 BossBase.BeginPhaseTransition 对重入会告警。
/// </summary>
public static BrainBuilder.StateBuilder PhaseTransition(
BrainBuilder b, string state, int targetPhase, float invincibleDuration)
{
if (targetPhase < 0)
throw new ArgumentOutOfRangeException(nameof(targetPhase),
$"BossFragments.PhaseTransition: 状态 '{state}' 的目标阶段不能为负。");
if (invincibleDuration <= 0f)
throw new ArgumentOutOfRangeException(nameof(invincibleDuration),
$"BossFragments.PhaseTransition: 状态 '{state}' 的无敌时长必须 > 0——" +
"为 0 意味着过渡演出期间可被打断，这不是阶段过渡的语义。");
return b.DeclareState(state)
.OnEnter(x =>
{
x.Locomotion.Stop();
x.Combat.InterruptAbilities();
x.Boss.BeginPhaseTransition(targetPhase, invincibleDuration);
});
}
/// <summary>
/// 一组「逼近 ↔ 到射程选招攻击」。转发到 ApproachAttackEngagement 的共享实现，
/// 使模块路径与 Boss 图路径永远是同一份行为。
/// 返回逼近态的 builder，调用方可继续挂阶段过渡等出边。
/// </summary>
public static BrainBuilder.StateBuilder ApproachAttack(
BrainBuilder b, string approach, string attack, string rest)
=> ApproachAttackEngagement.Declare(b, approach, attack, rest);
/// <summary>
/// 移动到第 index 个竞技场锚点（<see cref="BossArenaAnchors"/>），到位后由调用方挂出边。
/// 坐标经 IBossControl 取得——声明层的 lambda 不得闭包捕获具体实例。
/// </summary>
public static BrainBuilder.StateBuilder MoveToAnchor(BrainBuilder b, string state, int index)
{
if (index < 0)
throw new ArgumentOutOfRangeException(nameof(index),
$"BossFragments.MoveToAnchor: 状态 '{state}' 的锚点下标不能为负。");
return b.DeclareState(state)
.OnEnter(x => x.Locomotion.MoveTo(x.Boss.AnchorAt(index)))
.OnExit (x => x.Locomotion.Stop());
}
/// <summary>共享条件：已到达第 index 个锚点（容差内）。</summary>
public static Func<IAiContext, bool> AtAnchor(int index, float tolerance = 0.2f)
=> x => x.Boss.DistanceToAnchor(index) <= tolerance;
}
}
```
- [ ] **Step 4: 编译检查**
MCP `unity_get_compilation_errors`。
期望：`BossFragments.MoveToAnchor` / `AtAnchor` 引用了 `IBossControl.AnchorAt` /
`DistanceToAnchor` 而它们尚未声明，报 2 个错误——由 Task 10 Step 0 补上。
**本 Task 不单独提交，与 Task 10 合并提交。**
---
## Task 10: `BossArenaAnchors` 竞技场锚点（与 Task 9 合并提交）
**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Boss/BossArenaAnchors.cs`
- Modify: `Assets/_Game/Scripts/AI/IBossControl.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Boss/BossBase.cs`
- [ ] **Step 0: `IBossControl` 补锚点两成员**
`Assets/_Game/Scripts/AI/IBossControl.cs`：文件顶部加 `using UnityEngine;`，
并在 `BeginPhaseTransition` 之后（替换 Task 1 留下的那两行说明注释）追加：
```csharp
/// <summary>第 index 个竞技场锚点的世界坐标。未挂锚点组件 / 下标越界即抛。</summary>
Vector2 AnchorAt(int index);
/// <summary>Boss 当前位置到第 index 个锚点的距离。未挂锚点组件 / 下标越界即抛。</summary>
float DistanceToAnchor(int index);
```
同步更新 `Assets/Tests/EditMode/AI/Fakes/FakeBossControl.cs`——Task 1 已把
`Anchors` / `DistanceToAnchorValue` 两个字段与两个实现写好，此处只需确认它们存在。
- [ ] **Step 1: 建组件**
`Assets/_Game/Scripts/Enemies/Boss/BossArenaAnchors.cs`：
```csharp
using UnityEngine;
namespace BaseGames.Enemies
{
/// <summary>
/// 竞技场锚点集合：Boss 定点走位（跳到悬空平台、传送到房间固定角落）的坐标来源。
/// 挂在 Boss 上；锚点物体本身放在场景里（随房间布局走，不进 SO）。
///
/// AI 图不直接持有本组件——坐标经 <see cref="BaseGames.AI.IBossControl.AnchorAt"/> 取得
/// （图的 lambda 不得闭包捕获实例）。BossBase 在 Awake 解析本组件并转发。
/// </summary>
public sealed class BossArenaAnchors : MonoBehaviour
{
[Tooltip("锚点物体（顺序即下标，AI 图按下标引用）")]
[SerializeField] private Transform[] _anchors;
public int Count => _anchors != null ? _anchors.Length : 0;
/// <summary>取第 index 个锚点坐标。下标越界或漏配即抛——不静默回退到自身位置。</summary>
public Vector2 At(int index)
{
if (_anchors == null || index < 0 || index >= _anchors.Length)
throw new System.IndexOutOfRangeException(
$"[BossArenaAnchors] {name} 请求锚点下标 {index}，但只配了 {Count} 个。" +
"请在 Inspector 补齐锚点，或修正 AI 图里的下标。");
var t = _anchors[index];
if (t == null)
throw new System.InvalidOperationException(
$"[BossArenaAnchors] {name} 第 {index} 个锚点为空引用。请在 Inspector 指定。");
return t.position;
}
#if UNITY_EDITOR
private void OnValidate()
{
if (_anchors == null) return;
for (int i = 0; i < _anchors.Length; i++)
if (_anchors[i] == null)
Debug.LogError($"[BossArenaAnchors] {name} 第 {i} 个锚点未指定。", this);
}
private void OnDrawGizmosSelected()
{
if (_anchors == null) return;
Gizmos.color = new Color(1f, 0.8f, 0.2f, 0.9f);
for (int i = 0; i < _anchors.Length; i++)
{
if (_anchors[i] == null) continue;
Gizmos.DrawWireSphere(_anchors[i].position, 0.35f);
UnityEditor.Handles.Label(_anchors[i].position, $"anchor {i}");
}
}
#endif
}
}
```
- [ ] **Step 2: `BossBase` 解析锚点组件并实现两个 facet 成员**
`Assets/_Game/Scripts/Enemies/Boss/BossBase.cs`：
1. 在 `_phaseGate` 字段之后追加：
```csharp
[Header("竞技场锚点（可选）")]
[Tooltip("定点走位用的锚点集合；AI 图未用到锚点片段时可留空")]
[SerializeField] private BossArenaAnchors _arenaAnchors;
```
2. `Awake()` 里，在 `_phaseGate` 解析之后追加：
```csharp
if (_arenaAnchors == null) _arenaAnchors = GetComponentInChildren<BossArenaAnchors>(true);
```
3. 在 `ResourceFull` 属性之后追加两个 facet 成员：
```csharp
/// <summary>第 index 个竞技场锚点坐标。IBossControl 实现。未挂锚点组件即抛——
/// AI 图用了锚点片段却没配锚点是配置错误，必须暴露而非回退到自身位置。</summary>
public Vector2 AnchorAt(int index) => RequireAnchors().At(index);
/// <summary>当前位置到第 index 个锚点的距离。IBossControl 实现。</summary>
public float DistanceToAnchor(int index)
=> Vector2.Distance(transform.position, RequireAnchors().At(index));
private BossArenaAnchors RequireAnchors()
=> _arenaAnchors != null ? _arenaAnchors : throw new System.InvalidOperationException(
$"[BossBase] '{name}' 的 AI 图使用了竞技场锚点，但未挂 BossArenaAnchors 组件。" +
"请挂上该组件并配好锚点，或从 AI 图里移除锚点片段。");
```
4. 顶部 using 区确认已有 `using UnityEngine;`（现有代码已用 `SerializeField`，必然已有）。
> `BossBase` 已在 Task 2 声明实现 `BaseGames.AI.IBossControl`，本步补齐新增的两个成员。
- [ ] **Step 4: 编译检查**
MCP `unity_get_compilation_errors`。期望 0 errors 0 warnings（Task 9 的报错此时消解）。
- [ ] **Step 5: 全量回归 + 提交（含 Task 9）**
`Run All` 期望全绿。
```bash
git add Assets/_Game/Scripts/AI/AiSignal.cs \
Assets/_Game/Scripts/AI/IBossControl.cs \
Assets/_Game/Scripts/Enemies/AIBrain/Modules/Engagement/ApproachAttackEngagement.cs \
Assets/_Game/Scripts/Enemies/AIBrain/Modules/BossFragments.cs \
Assets/_Game/Scripts/Enemies/AIBrain/Modules/BossFragments.cs.meta \
Assets/_Game/Scripts/Enemies/Boss/BossArenaAnchors.cs \
Assets/_Game/Scripts/Enemies/Boss/BossArenaAnchors.cs.meta \
Assets/_Game/Scripts/Enemies/Boss/BossBase.cs \
Assets/Tests/EditMode/AI/Fakes/FakeBossControl.cs
git commit -m "feat(ai): Boss 图共享片段 + 竞技场锚点 + AiSignal.Engaged
BossFragments：阶段过渡 / 逼近选招 / 移动到锚点三个静态建态片段。
ApproachAttackEngagement 的建态逻辑提为 internal static Declare（态名参数化），
模块路径与 Boss 图路径共用同一份行为，Boss 可建多组（地面组/空中组）。
锚点坐标经 IBossControl.AnchorAt / DistanceToAnchor 暴露，不走黑板——
EnemyAiBrain._context 是私有的（BossBase 无从写入），且 ResetScratch 会清黑板
带来隐式时序约束。锚点本就是 Boss 专属知识，归 Boss facet 更直。
锚点漏配 / 下标越界显式抛，不回退到自身位置。"
```
---
## Task 11: `ChaoFengAi` 定制图
**Files:**
- Create: `Assets/_Game/Scripts/Enemies/AIBrain/Ai/ChaoFengAi.cs`
- Test: `Assets/Tests/EditMode/AI/ChaoFengAiTests.cs`
- [ ] **Step 1: 写失败测试**
`Assets/Tests/EditMode/AI/ChaoFengAiTests.cs`：
```csharp
using NUnit.Framework;
using BaseGames.AI;
using BaseGames.Enemies;
namespace BaseGames.Tests.EditMode.AI
{
public class ChaoFengAiTests
{
static AiRuntime Run(FakeAiContext ctx)
=> new AiRuntime(new ChaoFengAi().GetOrBuildGraph(), ctx);
static FakeAiContext Ctx()
{
var c = new FakeAiContext();
c.S.Chase = true; // 竞技场内玩家恒在追逐区
c.S.Vision = true;
return c;
}
[Test]
public void StartsInWait_UntilEngaged()
{
var ctx = Ctx();
var rt = Run(ctx);
Assert.AreEqual(ChaoFengAi.Wait, rt.CurrentStateName);
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Wait, rt.CurrentStateName, "未开战前不应自行进入战斗");
}
[Test]
public void Engaged_EntersIntro_ThenGround()
{
var ctx = Ctx();
var rt = Run(ctx);
rt.Send(AiSignal.Engaged);
Assert.AreEqual(ChaoFengAi.Intro, rt.CurrentStateName);
CollectionAssert.Contains(ctx.C.Used, ChaoFengAi.IntroAbility);
ctx.C.Running = null; // 入场演出播完
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Ground, rt.CurrentStateName);
}
[Test]
public void Ground_ApproachAttackLoop()
{
var ctx = Ctx();
var rt = Run(ctx);
rt.Send(AiSignal.Engaged);
ctx.C.Running = null; rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Ground, rt.CurrentStateName);
ctx.C.Eligible = true;
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.GroundAttack, rt.CurrentStateName);
CollectionAssert.Contains(ctx.C.Used, "best");
ctx.C.Running = null; // 招式打完
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Ground, rt.CurrentStateName);
}
[Test]
public void HpBelowHalf_TransitionsToAirPhase()
{
var ctx = Ctx();
var rt = Run(ctx);
rt.Send(AiSignal.Engaged);
ctx.C.Running = null; rt.Tick(0.1f);
ctx.V.Hp = 0.4f;
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.PhaseTx, rt.CurrentStateName);
Assert.AreEqual(1, ctx.B.BeginCallCount, "阶段过渡只应发起一次");
Assert.AreEqual(1, ctx.B.LastTargetPhase);
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.PhaseTx, rt.CurrentStateName, "过渡期间不得提前转出");
Assert.AreEqual(1, ctx.B.BeginCallCount, "过渡期间不得重复发起");
ctx.B.Transitioning = false; // 过渡结束
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Air, rt.CurrentStateName);
}
[Test]
public void Air_HoverAttackLoop()
{
var ctx = Ctx();
var rt = Run(ctx);
rt.Send(AiSignal.Engaged);
ctx.C.Running = null; rt.Tick(0.1f);
ctx.V.Hp = 0.4f; rt.Tick(0.1f);
ctx.B.Transitioning = false; rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Air, rt.CurrentStateName);
ctx.C.Eligible = true;
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.AirAttack, rt.CurrentStateName);
ctx.C.Running = null;
rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Air, rt.CurrentStateName);
}
[Test]
public void Died_GoesToDeathFromAnyState()
{
var ctx = Ctx();
var rt = Run(ctx);
rt.Send(AiSignal.Engaged);
rt.Send(AiSignal.Died);
Assert.AreEqual(ChaoFengAi.Death, rt.CurrentStateName);
}
[Test]
public void AirPhase_DoesNotFallBackToGround()
{
// 阶段单向推进：进了空中阶段就不再回地面阶段（招池已换）
var ctx = Ctx();
var rt = Run(ctx);
rt.Send(AiSignal.Engaged);
ctx.C.Running = null; rt.Tick(0.1f);
ctx.V.Hp = 0.4f; rt.Tick(0.1f);
ctx.B.Transitioning = false; rt.Tick(0.1f);
ctx.V.Hp = 0.9f; // 即使血量回升
for (int i = 0; i < 5; i++) rt.Tick(0.1f);
Assert.AreEqual(ChaoFengAi.Air, rt.CurrentStateName);
}
}
}
```
- [ ] **Step 2: 跑测试确认失败**
Test Runner → EditMode → `ChaoFengAiTests`。期望：编译失败（`ChaoFengAi` 不存在）。
> 若 `AiRuntime` 的事件入口不是 `Send(AiSignal)`，打开 `Assets/_Game/Scripts/AI/AiRuntime.cs`
> 确认实际方法名并统一改测试（`EnemyAiBrain.Send` 是对它的转发，方法名应一致）。
- [ ] **Step 3: 写 `ChaoFengAi`**
`Assets/_Game/Scripts/Enemies/AIBrain/Ai/ChaoFengAi.cs`：
```csharp
using BaseGames.AI;
namespace BaseGames.Enemies
{
/// <summary>
/// 嘲风的 AI 图（定制路径：Boss 数量少、彼此差异大，手写图而非配方）。
///
/// 阶段 0（地面）：逼近 ↔ 选招。四个地面招由 BossPhaseAbilityGate 在阶段 0 放行。
/// 阶段 1（空中）：悬停 ↔ 选招。风石由阶段门在阶段 1 放行，地面四招被禁用。
///
/// 招式的射程 / 冷却 / 权重全归各能力自己的 EnemyAbilitySO；本图只决定
/// 「什么时候该逼近、什么时候该出手、什么时候该换阶段」。
/// 死亡不在本图：EnemyBase.PerformDeath 发 Died 事件，全局边把决策停在 Death 终态。
/// </summary>
[AiDefinition("ChaoFeng")]
public sealed class ChaoFengAi : AiScript
{
public const string Wait = "Wait";
public const string Intro = "Intro";
public const string Ground = "Ground";
public const string GroundAttack = "GroundAttack";
public const string PhaseTx = "PhaseTransition";
public const string Air = "Air";
public const string AirAttack = "AirAttack";
public const string Death = "Death";
/// <summary>入场演出能力 id（对应 ABL_ChaoFeng_Intro 资产的 abilityId）。</summary>
public const string IntroAbility = "chaofeng_intro";
/// <summary>空中阶段的血量阈值。</summary>
private const float AirPhaseHpRatio = 0.5f;
/// <summary>阶段过渡无敌时长，须 ≥ 浮空上升时长 + 缓冲。</summary>
private const float PhaseTxInvincible = 2f;
protected override void Build(BrainBuilder b)
{
b.Entry(Wait);
// 竞技场触发前静置：不巡逻、不警觉（Boss 不搜敌，等玩家进场）
AiStateFragments.Locomotion(b, Wait, LocomotionMode.Idle)
.To(Intro).OnEvent(AiSignal.Engaged);
// 入场演出：一次性能力，播完进战
AiStateFragments.AbilityOnce(b, Intro, IntroAbility)
.To(Ground).When(x => !x.Combat.IsAbilityRunning(IntroAbility), "introDone");
// 阶段 0（地面）：逼近 ↔ 选招。rest 指回自身——Boss 不脱战。
BossFragments.ApproachAttack(b, Ground, GroundAttack, rest: Ground)
.To(PhaseTx).When(x => x.Vitals.HpBelow(AirPhaseHpRatio), "hp<50%");
// 阶段过渡：无敌 + 浮空演出由 ChaoFengBoss.OnBeginPhaseTransition 承担
BossFragments.PhaseTransition(b, PhaseTx, targetPhase: 1, invincibleDuration: PhaseTxInvincible)
.To(Air).When(x => !x.Boss.IsPhaseTransitioning, "txDone");
// 阶段 1（空中）：悬停朝向玩家 ↔ 选招。阶段单向推进，不回地面阶段。
AiStateFragments.Locomotion(b, Air, LocomotionMode.Face)
.To(AirAttack).When(x => x.Combat.HasEligibleAttack(), "attackInRange");
// 与地面攻击态同语义：起手就打完，不挂脱战边
b.DeclareState(AirAttack)
.OnEnter(x => { x.Locomotion.Stop(); x.Combat.UseBestAttack(); })
.OnExit (x => x.Combat.InterruptAbilities())
.To(Air).When(x => !x.Combat.IsAbilityRunning(), "attackDone");
// 死亡终态：演出走物理层（ChaoFengBoss.Die 的击败序列）
AiStateFragments.Terminal(b, Death);
b.Global().To(Death).OnEvent(AiSignal.Died);
}
}
}
```
- [ ] **Step 4: 跑测试确认通过**
Test Runner → EditMode → `ChaoFengAiTests`。期望：7 passed。
- [ ] **Step 5: 确认注册表能发现它**
Test Runner → EditMode → `AiDefinitionRegistryTests`。期望全绿。
另在 Unity Console 里确认 `AiDefinitionRegistry` 的 id 列表包含 `ChaoFeng`
（若注册表有调试打印入口则用它；否则在 Task 15 放置嘲风时由 `_definitionId` 下拉验证）。
- [ ] **Step 6: 全量回归 + 提交**
`Run All` 期望全绿。
```bash
git add Assets/_Game/Scripts/Enemies/AIBrain/Ai/ChaoFengAi.cs \
Assets/_Game/Scripts/Enemies/AIBrain/Ai/ChaoFengAi.cs.meta \
Assets/Tests/EditMode/AI/ChaoFengAiTests.cs \
Assets/Tests/EditMode/AI/ChaoFengAiTests.cs.meta
git commit -m "feat(enemy): 嘲风 AI 图（BrainGraph 定制路径）
Wait →(Engaged) Intro → Ground⇄GroundAttack →(hp<50%) PhaseTx → Air⇄AirAttack。
Boss 不脱战（rest 指回自身）、阶段单向推进、起手就打完。
死亡不在图上：全局 Died 边进 Death 终态，演出归物理层。
7 条 EditMode 断言覆盖状态序列、过渡只发起一次、血量回升不回退阶段。"
```
---
## Task 12: `BossFightTrigger` 开战触发
**Files:**
- Create: `Assets/_Game/Scripts/Enemies/Boss/BossFightTrigger.cs`
- [ ] **Step 1: 建触发器**
`Assets/_Game/Scripts/Enemies/Boss/BossFightTrigger.cs`：
```csharp
using UnityEngine;
using BaseGames.AI;
using BaseGames.Core.Events;
namespace BaseGames.Enemies
{
/// <summary>
/// Boss 开战触发：玩家进入竞技场触发区时，广播开战事件并让 Boss 的决策层从静置态进战。
/// 此前 EVT_BossFightStarted 全项目零发送方，Boss 永远不会开战。
///
/// 放在 Boss 房间入口的触发区上（Collider2D + isTrigger）。只触发一次。
/// </summary>
[RequireComponent(typeof(Collider2D))]
public sealed class BossFightTrigger : MonoBehaviour
{
[Header("目标 Boss")]
[Tooltip("要唤醒的 Boss 的决策层组件")]
[SerializeField] private EnemyAiBrain _bossBrain;
[Header("事件频道")]
[Tooltip("EVT_BossFightStarted — payload 为 bossId，驱动 BGM / 状态机 / HUD")]
[SerializeField] private StringEventChannelSO _onBossFightStarted;
[Tooltip("EVT_BossFightToggled — true 表示开始，驱动 Boss 血条与 BGM 切换")]
[SerializeField] private BoolEventChannelSO _onBossFightToggled;
[Header("标识")]
[Tooltip("Boss id，与 BossBase._bossId 一致")]
[SerializeField] private string _bossId;
[Header("触发条件")]
[Tooltip("玩家所在的层")]
[SerializeField] private LayerMask _playerLayers;
private bool _fired;
private void Awake()
{
var col = GetComponent<Collider2D>();
if (!col.isTrigger)
Debug.LogError($"[BossFightTrigger] {name} 的 Collider2D 未勾选 Is Trigger，无法触发开战。", this);
if (_bossBrain == null)
Debug.LogError($"[BossFightTrigger] {name} 未指定目标 Boss 的 EnemyAiBrain，开战不会生效。", this);
if (string.IsNullOrEmpty(_bossId))
Debug.LogError($"[BossFightTrigger] {name} 未填 bossId，BGM / 血条无法定位该 Boss。", this);
}
private void OnTriggerEnter2D(Collider2D other)
{
if (_fired) return;
if ((_playerLayers.value & (1 << other.gameObject.layer)) == 0) return;
_fired = true;
_onBossFightStarted?.Raise(_bossId);
_onBossFightToggled?.Raise(true);
_bossBrain.Send(AiSignal.Engaged);
}
/// <summary>供存档回载 / 重试时复位（Boss 未被击败则重新可触发）。</summary>
public void ResetTrigger() => _fired = false;
}
}
```
- [ ] **Step 2: 确认 `EnemyAiBrain.Send` 存在且为 public**
打开 `Assets/_Game/Scripts/Enemies/AIBrain/EnemyAiBrain.cs`，确认 `public void Send(AiSignal)`。
若不存在，按 `EnemyBase.StopBehaviorTree` 里 `_brain?.Send(...)` 的调用形态补一个 public 转发。
- [ ] **Step 3: 编译检查 + 提交**
MCP `unity_get_compilation_errors` 期望 0/0。
```bash
git add Assets/_Game/Scripts/Enemies/Boss/BossFightTrigger.cs \
Assets/_Game/Scripts/Enemies/Boss/BossFightTrigger.cs.meta
git commit -m "feat(enemy): BossFightTrigger——补上缺失的开战触发
EVT_BossFightStarted 此前全项目零发送方，Boss 永远不开战。
触发时广播开战事件并向 Boss 决策层发 AiSignal.Engaged。
漏配目标 Brain / bossId / isTrigger 一律显式报错。"
```
---
## Task 13: `CharacterWizardWindow` Boss 页改造
**Files:**
- Modify: `Assets/_Game/Scripts/Editor/Character/CharacterWizardWindow.cs`
**为什么必须改**：它是 5 个空 `BossSkillSO` 资产的创建链路。不改则改完代码仍会源源不断产出旧轨资产（CLAUDE.md 第 2、6 条）。
- [ ] **Step 1: 删死引用**
1. 删第 8 行 `using BaseGames.Boss;`（仅为 `BossSkillSO` 而存在）。
2. 删第 80 行的 `_bossId` 字段及其 `// kept for legacy SkillSequenceSO queries if any` 注释
（死字段 + 行为树/旧轨残留注释）。若编译报有其他引用，一并清掉。
- [ ] **Step 2: 改招式定义表**
把 `ChaoFengSkillDefs`（约第 709–716 行）替换为：
```csharp
/// <summary>
/// 嘲风能力集。阶段可用性不在 SO 上——由 BossPhaseAbilityGate 承载
/// （见放置工具 PlaceChaoFeng），这里只记录供说明文本使用。
/// rangeRadius 必须 > 0：category==Attack 且射程为 0 的招永远够不着玩家，
/// EnemyAbilitySO.Validate 与 EnemyBase.BuildAttackSelector 都会显式报错。
/// </summary>
private static readonly (string name, string id, System.Type soType,
float rangeRadius, float cooldown, float weight, int phase)[]
ChaoFengAbilityDefs =
{
("Intro", "chaofeng_intro", typeof(PlayClipAbilitySO), 0f, 0f, 0f, -1),
("Boomerang", "boomerang", typeof(PlayClipAbilitySO), 9f, 4.0f, 1.0f, 0),
("FanCombo", "fan_combo", typeof(EnemyAbilitySO), 2.5f, 2.5f, 1.5f, 0),
("TornadoSmall", "tornado_small", typeof(PlayClipAbilitySO), 8f, 3.5f, 1.2f, 0),
("TornadoLarge", "tornado_large", typeof(PlayClipAbilitySO), 12f, 6.0f, 0.8f, 0),
("WindStone", "wind_stone", typeof(PlayClipAbilitySO), 12f, 3.0f, 1.0f, 1),
};
```
说明：
- `Intro` 是入场演出，`phase = -1` 表示不进选招池（`category` 保持 `None`、`rangeRadius = 0`）。
- `FanCombo` 是多段近战，用基类 `EnemyAbilitySO` 配 `attackSequence`（`MeleeAttackAbility` 消费）。
- 其余四招是「播 clip，判定与生成靠动画事件」，用 `PlayClipAbilitySO`。
- [ ] **Step 3: 改资产工厂**
把 `CreateChaoFengSkillSO`（约第 692–706 行）替换为：
```csharp
private static void CreateChaoFengAbilitySO(
string abilityName, string abilityId, System.Type soType,
float rangeRadius, float cooldown, float weight, int phase)
{
const string dir = "Assets/_Game/Data/Enemies/ChaoFeng/Abilities";
string name = $"ABL_ChaoFeng_{abilityName}";
var so = EditorScaffoldUtils.CreateSOAsset(soType, dir, name) as EnemyAbilitySO;
if (so == null) return;
so.abilityId = abilityId;
so.designNote = phase < 0
? "入场演出，不进选招池"
: $"阶段 {phase} 招式；阶段可用性由 BossPhaseAbilityGate 配置";
so.cooldown = cooldown;
if (phase < 0)
{
so.category = AbilityCategory.None;
so.rangeRadius = 0f;
so.weight = 0f;
}
else
{
so.category = AbilityCategory.Attack;
so.rangeRadius = rangeRadius; // 必须 > 0，否则选招器永远选不中
so.weight = weight;
}
EditorUtility.SetDirty(so);
AssetDatabase.SaveAssets();
}
```
✔ 无需新增辅助：`EditorScaffoldUtils.CreateSOAsset(System.Type soType, string folder, string assetName)`
**已存在**（`Assets/_Game/Scripts/Editor/Shared/EditorScaffoldUtils.cs:178`，返回 `ScriptableObject`，
与泛型版同样是"已存在则返回 null 不覆盖"）。上面代码里的 `as EnemyAbilitySO` 强转即依赖它。
- [ ] **Step 4: 改一键创建与提示文案**
把 `CreateAllChaoFengSOs`（约第 718–727 行）替换为：
```csharp
private static void CreateAllChaoFengSOs()
{
CreateChaoFengStatsSO();
CreateChaoFengAnimConfigSO();
foreach (var (n, id, t, r, cd, w, ph) in ChaoFengAbilityDefs)
CreateChaoFengAbilitySO(n, id, t, r, cd, w, ph);
AssetDatabase.SaveAssets();
EditorUtility.DisplayDialog("创建完成",
"全部嘲风 SO 已创建（已存在的跳过）。\n" +
"接下来：\n" +
"1. 用「放置嘲风到场景并绑定 SO」生成组件树；\n" +
"2. 检查 EnemyAiBrain._definitionId = ChaoFeng；\n" +
"3. 检查各能力组件的 _config 已绑定对应 ABL_ 资产；\n" +
"4. 在 BossPhaseAbilityGate 上确认阶段表（地面四招=阶段0，风石=阶段1）。",
"确定");
}
```
- [ ] **Step 5: 改工厂按钮与状态面板**
1. `BuildBossTab` 里的 factory 循环（约第 333–338 行）改为：
```csharp
foreach (var (abName, abId, soType, r, cd, w, ph) in ChaoFengAbilityDefs)
{
string cName = abName; string cId = abId; System.Type cType = soType;
float cR = r, cCd = cd, cW = w; int cPh = ph;
factory.Add(MakeFactoryButton($"ABL_ChaoFeng_{cName}.asset",
() => { CreateChaoFengAbilitySO(cName, cId, cType, cR, cCd, cW, cPh); RefreshSOStatus(); }));
}
```
2. `BuildBossStatus`（约第 785–801 行）的 `foreach` 改为：
```csharp
foreach (var (abName, _, _, _, _, _, _) in ChaoFengAbilityDefs)
checks.Add(($"ABL_ChaoFeng_{abName}",
FindAtPath<EnemyAbilitySO>($"{ablDir}/ABL_ChaoFeng_{abName}.asset")));
```
3. 在该 `foreach` 之后追加一行 AI 图状态检查：
```csharp
// AI 图是代码定义的（定制路径），没有资产可查——用注册表确认它被反射收集到了
bool hasAiGraph = System.Array.IndexOf(BaseGames.AI.AiDefinitionRegistry.Ids, "ChaoFeng") >= 0;
_bossStatusPanel.Add(MakeStatusGrid(checks.ToArray()));
_bossStatusPanel.Add(new UnityEngine.UIElements.Label(
hasAiGraph ? "✔ AI 图 ChaoFengAi 已注册（定制路径 _definitionId = ChaoFeng）"
: "✘ AI 图 ChaoFengAi 未注册——检查 [AiDefinition(\"ChaoFeng\")] 特性"));
```
并把原来那行单独的 `_bossStatusPanel.Add(MakeStatusGrid(checks.ToArray()));` 删掉（已并入上面）。
⚠️ `AiDefinitionRegistry.Ids` 的实际成员名以 `Assets/_Game/Scripts/AI/AiDefinitionRegistry.cs` 为准，
按实际签名调整；语义是「注册表里有没有 ChaoFeng」。
- [ ] **Step 6: 改跳转按钮与放置说明**
1. 删第 365 行 `jumpGroup.Add(MakeJumpButton("Boss 技能序列查看器", BossSkillSequenceWindow.OpenWindow));`
（该窗口将在 Task 20 删除）。
2. 第 367 行标签改为 `"Data Hub（敌人 / 能力）"`。
3. 第 348 行的 `MakeHelpBox` 文案改为：
```csharp
root.Add(MakeHelpBox("放置嘲风完整组件树（ChaoFengBoss + 浮空控制器 + 击倒计数 + " +
"EnemyAiBrain + BossPhaseAbilityGate + 5 个能力组件 + " +
"Phase1 HitBox × 4 + 炮口 × 3）。"));
```
- [ ] **Step 7: 编译检查**
MCP `unity_get_compilation_errors`。期望 0 errors 0 warnings。
⚠️ 此时状态面板会显示 5 个 `ABL_ChaoFeng_*` 缺失——**这是正确的**：磁盘上那 5 个是 `BossSkillSO`，
不是 `EnemyAbilitySO`。Task 15 会删旧建新。
- [ ] **Step 8: 提交**
```bash
git add Assets/_Game/Scripts/Editor/Character/CharacterWizardWindow.cs
git commit -m "refactor(editor): 角色向导 Boss 页改产出 EnemyAbilitySO
该向导是 5 个空 BossSkillSO 资产的创建链路——不改则会持续产出旧轨资产。
招式表扩为带 soType / rangeRadius / cooldown / weight 的形式（与
GetEnemyAbilityDefs 对齐），阶段可用性移交 BossPhaseAbilityGate。
产出时强制 rangeRadius > 0，不把责任推给下游作者。
状态面板改查 EnemyAbilitySO，并新增 AI 图注册状态一行。"
```
---
## Task 14: `SceneObjectPlacerTool.PlaceChaoFeng` 改造
**Files:**
- Modify: `Assets/_Game/Scripts/Editor/Scene/SceneObjectPlacerTool.cs`
- [ ] **Step 1: 换组件：执行器 → 决策层 + 阶段门 + 能力组件**
把第 1089 行：
```csharp
BossSkillExecutor skillExec = GetOrAddComponent<BossSkillExecutor>(go);
```
替换为：
```csharp
EnemyAiBrain brain = GetOrAddComponent<EnemyAiBrain>(go);
BossPhaseAbilityGate phaseGate = GetOrAddComponent<BossPhaseAbilityGate>(go);
// 五个招式各一个能力组件（Intro 与四个地面/空中招）
var abIntro = GetOrAddComponent<PlayClipAbility>(GetOrCreateChild(go.transform, "ABL_Intro").gameObject);
var abFan = GetOrAddComponent<MeleeAttackAbility>(GetOrCreateChild(go.transform, "ABL_FanCombo").gameObject);
var abBoomer = GetOrAddComponent<PlayClipAbility>(GetOrCreateChild(go.transform, "ABL_Boomerang").gameObject);
var abTornadoS = GetOrAddComponent<PlayClipAbility>(GetOrCreateChild(go.transform, "ABL_TornadoSmall").gameObject);
var abTornadoL = GetOrAddComponent<PlayClipAbility>(GetOrCreateChild(go.transform, "ABL_TornadoLarge").gameObject);
var abWind = GetOrAddComponent<PlayClipAbility>(GetOrCreateChild(go.transform, "ABL_WindStone").gameObject);
```
> 一招一个子物体：`EnemyAbilityBase` 带 `[DisallowMultipleComponent]`，同一物体上放不了两个
> 同类型能力（四个 `PlayClipAbility`）。`EnemyAbilityRegistry.CollectFrom(gameObject)` 是
> 递归收集，子物体上的能力同样会被注册。
- [ ] **Step 2: 改 HitBox 注释**
第 1098 行注释改为：
```csharp
// Phase1 攻击 HitBox（默认禁用；由能力按 EnemyAttackSO.hitBoxSlot 归一化时机开关）。
```
- [ ] **Step 3: 删执行器接线，改绑能力 `_config`**
删第 1125 行 `AssignReference(skillExec, "_animancer", animancer, report);`。
把第 1161–1175 行（收集 `BossSkillSO` 赋给执行器那一整段，含 `AssignString(skillExec, "_bossId", ...)`
与 `AssignObjectArray(skillExec, "_hitBoxes", ...)`）替换为：
```csharp
// 决策层：Boss 走定制路径（AiScript），不用配方
AssignString(brain, "_definitionId", "ChaoFeng", report);
// 能力 SO 绑定（一招一组件）
var abilityWiring = new (Object comp, string assetName)[]
{
(abIntro, "ABL_ChaoFeng_Intro"),
(abFan, "ABL_ChaoFeng_FanCombo"),
(abBoomer, "ABL_ChaoFeng_Boomerang"),
(abTornadoS, "ABL_ChaoFeng_TornadoSmall"),
(abTornadoL, "ABL_ChaoFeng_TornadoLarge"),
(abWind, "ABL_ChaoFeng_WindStone"),
};
foreach (var (comp, assetName) in abilityWiring)
{
Object so = FindFirstAsset(assetName);
if (so != null) AssignReference(comp, "_config", so, report);
else report.Add($"未找到 EnemyAbilitySO：{assetName}，" +
"请先在角色向导 Boss 页「一键创建全部 ChaoFeng SO」后重新运行本放置操作。");
}
// 近战三段 HitBox 走命名槽位（EnemyAttackSO.hitBoxSlot 按名索引）
AssignHitBoxSlots(abFan, new[] { ("fan_1", fan1), ("fan_2", fan2), ("fan_3", fan3) }, report);
// 阶段招池：地面四招 = 阶段 0，风石 = 阶段 1，Intro 不受阶段管控（全阶段，但 category=None 不进选招池）
AssignPhaseGate(phaseGate, new (Object ability, int[] phases)[]
{
(abFan, new[] { 0 }),
(abBoomer, new[] { 0 }),
(abTornadoS, new[] { 0 }),
(abTornadoL, new[] { 0 }),
(abWind, new[] { 1 }),
}, report);
```
- [ ] **Step 4: 加两个反射写入辅助**
在 `SceneObjectPlacerTool` 的「敌人放置辅助方法」区（第 1199 行之后）追加：
```csharp
/// <summary>写入 MeleeAttackAbility 的命名 HitBox 槽位数组（私有序列化字段，经反射）。</summary>
private static void AssignHitBoxSlots(
BaseGames.Enemies.Abilities.MeleeAttackAbility ability,
(string slotName, BaseGames.Combat.HitBox hitBox)[] slots,
System.Collections.Generic.List<string> report)
{
if (ability == null) { report.Add("AssignHitBoxSlots：能力组件为空，跳过。"); return; }
var arr = new BaseGames.Enemies.Abilities.MeleeAttackAbility.HitBoxSlot[slots.Length];
for (int i = 0; i < slots.Length; i++)
arr[i] = new BaseGames.Enemies.Abilities.MeleeAttackAbility.HitBoxSlot
{ slotName = slots[i].slotName, hitBox = slots[i].hitBox };
var f = typeof(BaseGames.Enemies.Abilities.MeleeAttackAbility).GetField(
"_hitBoxSlots", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
if (f == null) { report.Add("AssignHitBoxSlots：找不到 _hitBoxSlots 字段，接线失败。"); return; }
Undo.RecordObject(ability, "Assign HitBox Slots");
f.SetValue(ability, arr);
EditorUtility.SetDirty(ability);
report.Add($"✔ 已绑定 {slots.Length} 个命名 HitBox 槽位到 {ability.GetType().Name}。");
}
/// <summary>写入 BossPhaseAbilityGate 的阶段表（私有序列化字段，经反射）。</summary>
private static void AssignPhaseGate(
BaseGames.Enemies.BossPhaseAbilityGate gate,
(Object ability, int[] phases)[] entries,
System.Collections.Generic.List<string> report)
{
if (gate == null) { report.Add("AssignPhaseGate：阶段门组件为空，跳过。"); return; }
var arr = new BaseGames.Enemies.BossPhaseAbilityGate.PhaseEntry[entries.Length];
for (int i = 0; i < entries.Length; i++)
arr[i] = new BaseGames.Enemies.BossPhaseAbilityGate.PhaseEntry
{
ability = entries[i].ability as BaseGames.Enemies.Abilities.EnemyAbilityBase,
phases = entries[i].phases,
};
var f = typeof(BaseGames.Enemies.BossPhaseAbilityGate).GetField(
"_entries", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
if (f == null) { report.Add("AssignPhaseGate：找不到 _entries 字段，接线失败。"); return; }
Undo.RecordObject(gate, "Assign Phase Gate");
f.SetValue(gate, arr);
EditorUtility.SetDirty(gate);
report.Add($"✔ 已写入阶段招池表（{entries.Length} 项）。");
}
```
- [ ] **Step 5: 接阶段门与锚点到 `BossBase`**
在第 1132 行（`AssignReference(bossBase, "_windStoneMuzzle", ...)`）之后追加：
```csharp
AssignReference(bossBase, "_phaseGate", phaseGate, report);
```
- [ ] **Step 6: 改报告文案**
把第 1186–1191 行的四条 `report.Add` 替换为：
```csharp
report.Add("★ FanCombo 三段 HitBox 已绑为命名槽位 fan_1 / fan_2 / fan_3，" +
"在各 EATK_ 资产的 hitBoxSlot 里填对应名字。");
report.Add("★ 回旋扇 / 龙卷 / 风石的生成由技能 clip 上的 SpawnProjectile 动画事件驱动，" +
"payload 填 boomerang / tornado_small / tornado_large / wind_stone；" +
"炮口引用留在 ChaoFengBoss 上，无需再拖到 SO。");
report.Add("★ 回旋扇收招 / 阶段过渡 / 击败演出等动画 Clip 待美术接入后在 ChaoFengBoss Inspector 指定。");
report.Add("★ AI：Boss 走定制路径，EnemyAiBrain._definitionId 已设为 ChaoFeng（对应 ChaoFengAi）。" +
"小怪才用配方（_recipe）。");
report.Add("★ 开战触发：Boss 房间入口需另放一个带 BossFightTrigger 的触发区，" +
"指向本 Boss 的 EnemyAiBrain 并填 bossId=ChaoFeng，否则 Boss 不会开战。");
```
- [ ] **Step 7: 清 E004 的旧轨提示**
删第 405–407 行里那条 `report.Add("★ 挂载 BossSkillExecutor 并指定 BossSkillSO 列表（技能执行层）。");`
（E004 归属已定为精英怪，走 `ApproachAttackEngagement`，不再是 Boss 轨）。
- [ ] **Step 8: 确认 using 与编译**
文件顶部按需补 `using BaseGames.Enemies.Abilities;`（若尚未引入）。
MCP `unity_get_compilation_errors`。期望 0 errors 0 warnings。
- [ ] **Step 9: 提交**
```bash
git add Assets/_Game/Scripts/Editor/Scene/SceneObjectPlacerTool.cs
git commit -m "refactor(editor): PlaceChaoFeng 改挂新轨——决策层 + 阶段门 + 能力组件
BossSkillExecutor 换为 EnemyAiBrain(_definitionId=ChaoFeng) +
BossPhaseAbilityGate + 6 个能力组件（一招一子物体，绕开
DisallowMultipleComponent）。HitBox 改绑命名槽位，阶段招池经反射写入。
顺带删掉 E004 上的 BossSkillExecutor 旧轨提示（已定为精英怪）。"
```
---
## Task 15: 重建嘲风资产与对象树，跑通并自检
**Files:**
- Delete: `Assets/_Game/Data/Enemies/ChaoFeng/Abilities/ABL_ChaoFeng_*.asset`（5 个 + `.meta`）
- Create（经向导）: 同目录 6 个新 `ABL_ChaoFeng_*.asset`
- Modify: `Assets/_Game/Prefabs/Enemies/ChaoFeng/ENM_ChaoFeng.prefab`
- [ ] **Step 1: 删 5 个旧资产**
这 5 个是空 `BossSkillSO`，且新资产要占用同名路径（`CreateSOAsset` 遇同名会跳过），必须先删。
```bash
cd "E:/Works/Unity/Projects/zeling_v2"
rm Assets/_Game/Data/Enemies/ChaoFeng/Abilities/ABL_ChaoFeng_Boomerang.asset* \
Assets/_Game/Data/Enemies/ChaoFeng/Abilities/ABL_ChaoFeng_FanCombo.asset* \
Assets/_Game/Data/Enemies/ChaoFeng/Abilities/ABL_ChaoFeng_TornadoSmall.asset* \
Assets/_Game/Data/Enemies/ChaoFeng/Abilities/ABL_ChaoFeng_TornadoLarge.asset* \
Assets/_Game/Data/Enemies/ChaoFeng/Abilities/ABL_ChaoFeng_WindStone.asset*
```
回 Unity 让它刷新资产库（`Assets > Refresh` 或切窗口聚焦）。
- [ ] **Step 2: 用向导重建 6 个能力资产**
Unity 菜单打开角色向导（`CharacterWizardWindow`）→ `Boss` 页 → `★ 一键创建全部 ChaoFeng SO`。
期望：`Abilities/` 下出现 6 个资产
（`Intro` / `Boomerang` / `FanCombo` / `TornadoSmall` / `TornadoLarge` / `WindStone`），
状态面板 6 项全为 ✔，且底部显示 `✔ AI 图 ChaoFengAi 已注册`。
抽查 `ABL_ChaoFeng_FanCombo.asset`：`abilityId = fan_combo`、`category = Attack`、
`rangeRadius = 2.5`、`cooldown = 2.5`、`weight = 1.5`。
- [ ] **Step 3: 确认活动场景，放置新的嘲风对象树**
⚠️ **先确认活动场景**——场景脚手架会写入当前活动场景，跑错场景会污染错误场景。
打开 `Assets/_Game/Scenes/Testings/TestRoomA.unity` 并确保它是活动场景。
向导 `Boss` 页 → `放置嘲风到场景并绑定 SO`。
期望报告里出现：
- `✔ 已绑定 6 个能力 SO`（或 6 条 `_config` 接线成功）
- `✔ 已绑定 3 个命名 HitBox 槽位`
- `✔ 已写入阶段招池表（5 项）`
- 五条 `★` 提示（槽位 / 动画事件 payload / 待接 Clip / 定制路径 / 开战触发）
Inspector 检查新对象：`EnemyAiBrain._definitionId = ChaoFeng`、`_recipe` 为空；
`BossPhaseAbilityGate` 5 行阶段表齐全；6 个 `ABL_*` 子物体各自 `_config` 已绑。
- [ ] **Step 4: 用新对象覆盖预制体**
选中场景里新生成的嘲风根物体 → 拖到 `Assets/_Game/Prefabs/Enemies/ChaoFeng/ENM_ChaoFeng.prefab` 上覆盖
（或 `右键 > Prefab > Replace`）。
覆盖的理由：旧预制体上带 `BossSkillExecutor` 与指向已删资产的 `_skills`，
不覆盖则 Task 20 删脚本后它会变成 missing script。这也与「敌人预制体由脚手架统一产出」的既有决策一致。
- [ ] **Step 5: 放一个开战触发区**
场景里新建一个空物体 `BossFightTrigger_ChaoFeng`，加 `BoxCollider2D`（勾 `Is Trigger`）+ `BossFightTrigger`：
- `_bossBrain` → 嘲风的 `EnemyAiBrain`
- `_bossId` → `ChaoFeng`
- `_playerLayers` → `Player`
- `_onBossFightStarted` → `EVT_BossFightStarted`
- `_onBossFightToggled` → `EVT_BossFightToggled`
保存场景。
- [ ] **Step 6: 进播放模式验证**
进 Play，走进触发区。期望：
1. Console 无报错（尤其无 `IAiContext.Boss` 异常、无阶段门漏配报错）。
2. 嘲风从静置转入入场态（若 Intro clip 未接，`PlayClipAbility` 会立刻结束，直接进 `Ground`——正常）。
3. 打到 50% 血量以下时进入阶段过渡（`ChaoFengFloatController.FloatUp` 起效），过渡结束进空中阶段。
4. 用 `EnemyDebugOverlay` 观察 `CurrentStateName` 序列符合 `ChaoFengAiTests` 的断言。
⚠️ 动画 Clip 未接入时招式判定不会真正生效，这属于美术资源缺口，不是本次范围。
**只要状态机流转正确、无报错即视为通过**，并把观察到的状态序列记进提交说明。
- [ ] **Step 7: 跑三件自检**
- `BaseGames/Tools/Validation/Validate All ScriptableObjects` → 期望 0 error
（尤其 `EnemyAbilitySO.Validate` 对 `category==Attack && rangeRadius<=0` 的报错不应出现）
- `BaseGames/Addressables/Validate Address Keys` → 期望 0 error
- `BaseGames/Tools/Maintenance/Physics2D Layer Matrix/Check` → 期望通过
- [ ] **Step 8: 提交**
```bash
git add -A Assets/_Game/Data/Enemies/ChaoFeng/ \
Assets/_Game/Prefabs/Enemies/ChaoFeng/ \
Assets/_Game/Scenes/Testings/TestRoomA.unity
git commit -m "feat(enemy): 嘲风迁移到新轨——能力资产 + 对象树 + 开战触发
删 5 个空 BossSkillSO，用向导重建 6 个 EnemyAbilitySO（含入场演出）。
预制体经放置工具重新产出：EnemyAiBrain(_definitionId=ChaoFeng) +
BossPhaseAbilityGate + 6 个能力组件，不再有 BossSkillExecutor。
TestRoomA 加开战触发区。三件自检 0 error。
验证：状态序列 Wait →(进触发区) Intro → Ground⇄GroundAttack →
(hp<50%) PhaseTransition → Air⇄AirAttack，无报错。
动画 Clip 待美术接入，判定时序届时再校。"
```
---
# 阶段二：删旧轨
> ⚠️ 顺序不可乱：先改引用方（Task 16–18），再删被引用的类型（Task 19）。
## Task 16: `BossBase` 瘦身
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/Boss/BossBase.cs`
- [ ] **Step 1: 删技能执行相关成员**
`Assets/_Game/Scripts/Enemies/Boss/BossBase.cs` 删除以下全部内容：
1. 字段：`_skillExecutor`（含 `[Header("技能执行器")]`）、`_onParrySuccess`（含其 `[Header]` 与 `[Tooltip]`）、
`_weightedCandidates`、`_candidateWeights`、`_singleSkillBuf`、`_counterStaggerCoroutine`
2. 属性：`IsBossSkillExecuting`、`LastUsedSkillId`
3. 方法：`UseBossSkill`、`UseBossSkillWeighted`、`IsSkillAvailableInPhase`、`CheckResourceCost`、
`HandleParrySuccess`、`ApplyCounterResponse`、`ExecuteCounterEffect`、`CounterStaggerCoroutine`
4. `Awake()` 里 `if (_skillExecutor == null) ...` 那一行
5. `OnEnable()` 里 `_onParrySuccess?.Subscribe(HandleParrySuccess).AddTo(_subs);` 那一行
（若 `OnEnable` 因此只剩 `base.OnEnable();`，整个 override 一并删掉）
6. `EnterPhase()` 里 `_skillExecutor?.InterruptCurrentSkill();` 改为 `_abilities.InterruptAll(Abilities.InterruptReason.ExternalRequest);`
—— 阶段切换仍须打断在跑的招，只是打断对象从执行器换成能力注册表
7. `PhaseTransitionCoroutine()` 里 `_skillExecutor?.InterruptCurrentSkill();` 同样替换
8. `OnSpawn()` 里 `_skillExecutor?.ResetAllCooldowns();` 删掉
（能力冷却随 `EnemyAbilityBase` 实例，对象池复用时另有机制；若发现冷却未重置，
在 `EnemyAbilityBase` 上补一个 `ResetCooldown()` 并由 `EnemyBase.OnSpawn` 遍历调用——
**这属于既有缺陷，若出现请单独记录，不要在本 Task 顺手改**）
9. `LastUsedSkillId = null;` 两处（`EnterPhase` 与 `OnSpawn`）删掉——防重复记忆已归选招器
10. using 区里因此不再需要的 `using BaseGames.Boss;`、`using BaseGames.Parry;`
11. **清掉本文件残余的三处行为树残留**（Task 1+2 执行时发现并留待此处，因为本 Task 正好重写这片区域）：
- 第 76 行附近的区段注释 `// ── 技能执行（BD Task 调用入口）` —— 随该区段一并删除
- `BeginPhaseTransition` 文档里的 `BD_BossPhaseTransition 检查 IsPhaseTransitioning 来等待过渡完成。`
—— 改为 `AI 图挂 When(x => !x.Boss.IsPhaseTransitioning) 边等待过渡完成。`
- `BeginPhaseTransition` 重入告警里的运行时字符串 `请检查行为树逻辑是否重复触发阶段切换。`
—— 改为 `请检查 AI 图是否重复触发阶段切换。`（这条是开发期真的会看到的日志，不能留）
- [ ] **Step 2: 编译检查**
MCP `unity_get_compilation_errors`。
期望：`EnemyDebugOverlay.cs:113` 报错（引用了已删的 `IsBossSkillExecuting`）。下一步修。
- [ ] **Step 3: 修 `EnemyDebugOverlay`**
`Assets/_Game/Scripts/Enemies/EnemyDebugOverlay.cs` 第 113 行那条 `BossSkillExec` 显示，替换为阶段信息
（Boss 现在没有独立执行器，有价值的是阶段与过渡状态）：
```csharp
list.Add($"Phase: {_boss.CurrentPhase}" +
(_boss.IsPhaseTransitioning ? " <color=#ffcc44>(transitioning)</color>" : ""));
```
- [ ] **Step 4: 编译 + 全量回归 + 提交**
MCP `unity_get_compilation_errors` 期望 0/0；`Run All` 期望全绿。
```bash
git add Assets/_Game/Scripts/Enemies/Boss/BossBase.cs \
Assets/_Game/Scripts/Enemies/EnemyDebugOverlay.cs
git commit -m "refactor(enemy): BossBase 瘦身——删技能执行与弹反反制两套
技能选取/执行归 EnemyAttackSelector + EnemyAbilityBase（阶段一已就位），
BossBase 不再持有 BossSkillExecutor。阶段切换改用能力注册表打断在跑的招。
弹反反制整套删除：它订阅的是全局弹反成功频道，无来源过滤——
玩家弹反任意小怪都会让场上 Boss 硬直。正确形态是 EnemyBase.ReceiveParry
（谁被弹反谁硬直），其接线为独立后续任务。
调试面板的 BossSkillExec 行换为阶段与过渡状态。"
```
---
## Task 17: `EnemyBase` 清行为树债
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/EnemyBase.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Behaviors/EnemyDeathSequence.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Boss/ChaoFengBoss.cs`
- [ ] **Step 1: 删 `ConsumeParryEvent` 及其状态**
`Assets/_Game/Scripts/Enemies/EnemyBase.cs`（约第 405–425 行）删除：
- 字段 `_wasParried`、`_parryTimestamp`、常量 `ParryEventTTL` 及其注释
- 方法 `ConsumeParryEvent()` 整个（零调用者）
并把 `ReceiveParry` 里对 `_wasParried` / `_parryTimestamp` 的两行赋值删掉，注释更新为：
```csharp
/// <summary>
/// 被弹反时调用：强制进入 Stagger 并在 staggerDuration 秒后恢复。
/// Stagger 期间 IsControllable 为 false，AI 决策自动让位——不需要额外的 AI 信号。
/// ⚠️ 目前**零调用者**：弹反管线（HurtBox → ParrySystem.ConsumeParry）拿不到攻击者引用，
/// 接线是一件独立任务（DamageInfo 加 attacker，或弹反成功时回调发起攻击的 HitBox）。
/// </summary>
public virtual void ReceiveParry(float staggerDuration = 0.5f)
{
if (!IsAlive) return;
ForceState(EnemyStateType.Stagger);
_abilities.InterruptAll(InterruptReason.Stagger);
ScheduleStateRecovery(EnemyStateType.Stagger, staggerDuration);
}
```
- [ ] **Step 2: `StopBehaviorTree` 改名**
`Assets/_Game/Scripts/Enemies/EnemyBase.cs` 第 656–664 行改为：
```csharp
/// <summary>
/// 通知决策层终止（死亡演出 / 出场演出期间调用，防止决策继续覆盖演出逻辑）。
/// 与 PerformDeath 发的 Died 信号幂等（重复 Died 无害）。
/// 供配置型行为组件（如 EnemyDeathSequence）调用，故为 public。
/// </summary>
public void NotifyDecisionStop()
{
_brain?.Send(BaseGames.AI.AiSignal.Died);
}
```
- [ ] **Step 3: 改两个调用点**
1. `Assets/_Game/Scripts/Enemies/Behaviors/EnemyDeathSequence.cs` 第 63 行：
```csharp
if (_stopDecisionLayer) _enemy?.NotifyDecisionStop();
```
并把该组件上的序列化字段 `_stopBehaviorTree` 重命名为 `_stopDecisionLayer`，加迁移特性保住已有资产的值：
```csharp
[UnityEngine.Serialization.FormerlySerializedAs("_stopBehaviorTree")]
[Tooltip("死亡演出开始时通知决策层终止，防止 AI 继续覆盖演出")]
[SerializeField] private bool _stopDecisionLayer = true;
```
⚠️ 若该字段的默认值原本不是 `true`，保持原默认值不变——本 Task 只改名，不改行为。
2. `Assets/_Game/Scripts/Enemies/Boss/ChaoFengBoss.cs` 第 188 行：
```csharp
NotifyDecisionStop();
```
- [ ] **Step 4: 编译 + 全量回归 + 提交**
MCP `unity_get_compilation_errors` 期望 0/0；`Run All` 期望全绿。
```bash
git add Assets/_Game/Scripts/Enemies/EnemyBase.cs \
Assets/_Game/Scripts/Enemies/Behaviors/EnemyDeathSequence.cs \
Assets/_Game/Scripts/Enemies/Boss/ChaoFengBoss.cs
git commit -m "refactor(enemy): 清行为树债——StopBehaviorTree 改名，删 ConsumeParryEvent
StopBehaviorTree → NotifyDecisionStop（方法体早已只是发 Died 信号）。
EnemyDeathSequence 的 _stopBehaviorTree 字段同步改名，带 FormerlySerializedAs 保值。
ConsumeParryEvent 及其 TTL 状态删除：零调用者，且 ForceState(Stagger) +
IsControllable 让位门已是更优表达，不需要第二条受击通道。"
```
---
## Task 18: `BossResource` 去自动触发
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/Boss/BossResourceConfigSO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Boss/BossResource.cs`
- [ ] **Step 1: 删配置里的自动触发三字段**
`Assets/_Game/Scripts/Enemies/Boss/BossResourceConfigSO.cs` 删除：
`autoTriggerOnFull`、`fullTriggerSkill`（类型是即将删除的 `BossSkillSO`）、`resetValueAfterTrigger`
三个字段及相关 `[Header]` / `[Tooltip]`。
在类注释里追加一句说明去向：
```csharp
/// <remarks>
/// 资源满值不再由本组件自动放招——那是绕过决策层直接执行，违反「AI 只决策、能力负责实现」。
/// 现在的形态是：本组件只维护数值，AI 图挂一条 When(x => x.Boss.ResourceFull) 边进专属招态。
/// </remarks>
```
- [ ] **Step 2: 删运行时的自动触发**
`Assets/_Game/Scripts/Enemies/Boss/BossResource.cs`：
1. 删字段 `_fullTriggered`
2. 删方法 `OnReachFull()` 整个
3. `AddValue(float delta)` 简化为：
```csharp
private void AddValue(float delta)
{
_currentValue = Mathf.Clamp(_currentValue + delta, 0f, _config.maxValue);
}
```
4. 类注释里 `- 满值时若 autoTriggerOnFull，自动让 BossBase 执行配置的技能。` 那一行，改为：
```csharp
/// - 满值时 <see cref="IsFull"/> 为真，由 AI 图的条件边决定放什么招（决策不在本组件）。
```
5. `OnBossUseSkill()` 的注释里 `由 BossBase.UseBossSkill 触发` 改为
`由使用了资源的能力触发（Boss 的招在自己的 EnemyAbilityBase 里调用）`。
- [ ] **Step 3: 编译 + 提交**
MCP `unity_get_compilation_errors` 期望 0/0。
```bash
git add Assets/_Game/Scripts/Enemies/Boss/BossResource.cs \
Assets/_Game/Scripts/Enemies/Boss/BossResourceConfigSO.cs
git commit -m "refactor(enemy): BossResource 去掉自动放招，触发权交回 AI 图
满值时由 BossResource 直接调 UseBossSkill 是绕过决策层执行，
违反「AI 只决策、能力负责实现」。现在只维护数值并暴露 IsFull，
AI 图挂 When(x => x.Boss.ResourceFull) 边进专属招态。
顺带解除对即将删除的 BossSkillSO 的依赖。"
```
---
## Task 19: 删旧轨 9 个脚本
**Files:**
- Delete: 9 个脚本（见下）
- [ ] **Step 1: 确认零引用**
```bash
cd "E:/Works/Unity/Projects/zeling_v2"
grep -rn "BossSkillSO\|BossSkillExecutor\|AttackPatternSO\|SkillSequenceSO\|WeakPointSystem\|TelegraphSystem\|BossSkillModule\|BossSkillSequenceWindow\|InteractionTag\|VulnerabilityWindow\|PlayerCounterResponse\|CounterType\|ArenaEvent\|IArenaInteractable\|BossResourceCost\|BossSkillCategory\|BossSkillType\|VulnTriggerType\|WeakPointType" \
Assets --include=*.cs
```
期望：**只命中将被删除的那 9 个文件自身**。若命中其他文件，先修那些引用再继续。
- [ ] **Step 2: 删文件（含 `.meta`）**
```bash
cd "E:/Works/Unity/Projects/zeling_v2"
rm Assets/_Game/Scripts/Enemies/Boss/BossSkillSO.cs* \
Assets/_Game/Scripts/Enemies/Boss/AttackPatternSO.cs* \
Assets/_Game/Scripts/Enemies/Boss/SkillSequenceSO.cs* \
Assets/_Game/Scripts/Enemies/Boss/BossSkillExecutor.cs* \
Assets/_Game/Scripts/Enemies/Boss/BossSkillTypes.cs* \
Assets/_Game/Scripts/Enemies/Boss/WeakPointSystem.cs* \
Assets/_Game/Scripts/Editor/Modules/BossSkillModule.cs* \
Assets/_Game/Scripts/Editor/Enemies/BossSkillSequenceWindow.cs*
rm -r Assets/_Game/Scripts/Enemies/Boss/Patterns
rm -f Assets/_Game/Scripts/Enemies/Boss/Patterns.meta
```
⚠️ `Patterns/` 是**独立程序集**（`BaseGames.Enemies.Boss.Patterns.asmdef`，`autoReferenced: true`）。
已核实**零外部引用**（无任何 asmdef 的 `references` 含它），因此可随目录整包删除。
删除后无需改动任何其他 asmdef。
- [ ] **Step 3: 编译 + 全量回归**
回 Unity 刷新。MCP `unity_get_compilation_errors` 期望 0 errors 0 warnings；`Run All` 期望全绿。
⚠️ 若 Console 出现 missing script 警告，检查是哪个预制体/场景仍引用旧组件——
`ENM_ChaoFeng.prefab` 已在 Task 15 重建，`TestRoomA` 里可能还有旧的嘲风实例，删掉它并保存场景。
- [ ] **Step 4: 打开 Data Hub 与角色向导确认无异常**
- `DataHubWindow`：`BossSkillModule` 已删，其他模块应正常列出（该模块经反射发现，无显式注册点）。
- 角色向导 `Boss` 页：状态面板 6 个 ✔ + AI 图 ✔，跳转按钮不再有"Boss 技能序列查看器"。
- [ ] **Step 5: 提交**
```bash
git add -A Assets/_Game/Scripts/Enemies/Boss/ Assets/_Game/Scripts/Editor/
git commit -m "refactor(enemy)!: 删除旧 Boss 轨 9 个脚本
BossSkillSO / AttackPatternSO / SkillSequenceSO / BossSkillExecutor /
BossSkillTypes / WeakPointSystem / TelegraphSystem / BossSkillModule /
BossSkillSequenceWindow。
判据「有更优替代才删」逐项对应：
- 编排 → EnemyAbilitySO + EnemyAttackSO（归一化时机 / 槽位 HitBox）
- 阶段门 → BossPhaseAbilityGate
- 选招 → EnemyAttackSelector + WeightedRandomAntiRepeat
- 可弹反 → DamageSourceSO.Flags(CanBeParried)，HurtBox 已在判定
- 弱点倍率 → HurtBox 自带倍率（原实现的 GetDamageMultiplier 零调用者）
- 预警 → clip 姿态 + 动画事件（TriggerFeedback / PlaySFX 已补接）
- 竞技场联动 → EnemySpawnerOnEvent；BossSkillEventChannelSO 本就零订阅方
- 霸体窗口 → EnemyAttackSO.hasPoiseWindow 四字段
能力资产的编辑器总览视图随 BossSkillModule 一并消失，
后续补 EnemyAbilityModule（优先级低于 AiDefinitionValidator）。"
```
---
## Task 20: 删预警旧路径
**Files:**
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs`
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs`
- [ ] **Step 1: 确认无资产在用**
```bash
cd "E:/Works/Unity/Projects/zeling_v2"
grep -rn "telegraphVfxKey\|telegraphDuration" Assets --include=*.asset --include=*.prefab --include=*.unity
```
期望：无命中（若有命中，说明有资产配了预警 VFX——先把该效果迁到 clip 的
`TriggerFeedback` 动画事件上，再继续）。
- [ ] **Step 2: 删 SO 上的两个字段**
`Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs` 删除整个：
```csharp
[Header("预警（Telegraph）")]
[Tooltip("预警 VFX key（IObjectPoolService.Spawn 的池 key），为空则跳过")]
public string telegraphVfxKey = "";
[Min(0f)] public float telegraphDuration = 0f;
```
- [ ] **Step 3: 删 `TelegraphRoutine` 与其调用**
`Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs`：
1. 删 `TelegraphRoutine()` 整个方法
2. `RunInternal()` 里删掉这两行：
```csharp
if (_config != null && _config.telegraphDuration > 0f)
yield return TelegraphRoutine();
```
3. `Phase = AbilityRunState.Telegraph;` 那行删掉（不再有 Telegraph 阶段），
`RunInternal` 开头改为：
```csharp
_isRunning = true;
Phase = AbilityRunState.Windup;
try
{
yield return ExecuteCoroutine();
Phase = AbilityRunState.Recovery;
}
```
4. 若 `AbilityRunState.Telegraph` 枚举值因此零消费者，一并从
`Assets/_Game/Scripts/Enemies/Abilities/AbilityRunState.cs` 删掉。
⚠️ 先 grep 确认：`grep -rn "AbilityRunState.Telegraph" Assets --include=*.cs`。
有其他消费者就保留枚举值，只删预警协程。
5. 顶部 using 区里因此不再需要的 `using BaseGames.Core;` / `using BaseGames.Core.Pool;`
—— **先 grep 确认文件里没有其他用途再删**。
- [ ] **Step 4: 编译 + 全量回归 + 提交**
MCP `unity_get_compilation_errors` 期望 0/0；`Run All` 期望全绿。
```bash
git add Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilitySO.cs \
Assets/_Game/Scripts/Enemies/Abilities/EnemyAbilityBase.cs \
Assets/_Game/Scripts/Enemies/Abilities/AbilityRunState.cs
git commit -m "refactor(enemy): 删预警旧路径，预警统一走动画
telegraphVfxKey / telegraphDuration / TelegraphRoutine 删除。
预警的正确载体是 clip 本身——姿态在动画里，音效与特效在动画事件上
（PlaySFX / TriggerFeedback 已于阶段一补接）。旧路径会在动画之前
插一段无动画的静止等待，是同一件事的第二条平行路。"
```
---
## Task 21: 收尾自检与文档
**Files:**
- Modify: `Docs/Guides/` 下的敌人 / Boss 指导手册
- Modify: `Docs_Dev/superpowers/specs/2026-07-30-boss-ai-single-track-design.md`
- [ ] **Step 1: 全量自检**
- MCP `unity_get_compilation_errors` → 0 errors 0 warnings
- Test Runner → EditMode → `Run All` → 全绿
- `BaseGames/Tools/Validation/Validate All ScriptableObjects` → 0 error
- `BaseGames/Addressables/Validate Address Keys` → 0 error
- `BaseGames/Tools/Maintenance/Physics2D Layer Matrix/Check` → 通过
- 进 Play 走一遍 TestRoomA 的嘲风战：状态序列与 Task 15 Step 6 一致，无报错
- [ ] **Step 2: 全库残留扫描**
```bash
cd "E:/Works/Unity/Projects/zeling_v2"
grep -rn "BossSkill\|WeakPoint\|Telegraph\|AttackPattern\|SkillSequence\|StopBehaviorTree\|BD_\|行为树" \
Assets/_Game/Scripts --include=*.cs
```
`BossSkill|WeakPoint|Telegraph|AttackPattern|SkillSequence|StopBehaviorTree` 期望无命中（相关类型已删）。
`BD_|行为树` **预期仍有命中**——Task 3 执行时实测 `Assets/_Game/Scripts/Enemies/` 下约 20 处，
散落在 `EnemyAnimationConfigSO` / `SensorSlotNames` / `EnemyAbilityBase` / `EnemyDeathSequence`
/ `ChaoFengBoss` 等文件的注释与 `[Tooltip]` 里。其中一部分会随 Task 16/17/19/20 自然消失
（`BossSkillSO`、`TelegraphSystem` 整文件删除；`BossBase`、`EnemyBase`、`EnemyDeathSequence`
在各自任务里改到）。**本步负责清掉剩余的**：逐个改为只描述功能的表述，不删除功能性内容。
清完后再跑一次 grep，此时才应无命中。
**已点名的一处需特别处理**：`EnemyQuotaManager` 有序列化字段 `_maxActiveBehaviorTrees`
与注释 `等价于旧的禁用行为树`（Task 4 执行时发现）。字段改名会丢已有场景/预制体上的配置值，
必须加 `[UnityEngine.Serialization.FormerlySerializedAs("_maxActiveBehaviorTrees")]`
再改为 `_maxActiveBrains`（该管理器实际裁剪的是 `EnemyAiBrain`，不是能力组件）。
- [ ] **Step 3: 更新指导手册**
在 `Docs/Guides/` 的敌人 / Boss 章节新增一节「Boss AI 怎么写」，内容覆盖：
1. Boss 走定制路径：写 `[AiDefinition("<BossId>")] class XxxAi : AiScript`，`EnemyAiBrain._definitionId` 填该 id（不用 `_recipe`）
2. 可用的建态原语：`AiStateFragments`（Locomotion / Ability / AbilityOnce / Terminal）+ `BossFragments`（PhaseTransition / ApproachAttack / MoveToAnchor / AtAnchor）
3. 阶段 = 换招池：`BossPhaseAbilityGate` 配阶段表，不在 SO 上写阶段
4. 一招怎么配：`EnemyAbilitySO`（+ 类型化子类）+ `EnemyAttackSO`；判定 / 生成 / 音效 / 无敌帧全挂动画事件
5. 开战：`BossFightTrigger` 发 `AiSignal.Engaged`
6. 死亡不在 AI 层：`Die` / `PerformDeath` + `NotifyDecisionStop`
7. 以 `ChaoFengAi` 为完整范例逐行讲解
- [ ] **Step 4: spec 标记为已实施**
`Docs_Dev/superpowers/specs/2026-07-30-boss-ai-single-track-design.md` 顶部状态行改为：
```markdown
> 日期：2026-07-30　　状态：**已实施**（阶段一 Task 1–15、阶段二 Task 16–20）
```
并在 §13 注记末尾追加实施期发现的偏差（若有），例如实际选用的黑板写入位置、
`AbilityRunState.Telegraph` 是否保留、`ReceiveParry` 接线仍为待办等。
- [ ] **Step 5: 提交**
```bash
git add Docs/Guides/ Docs_Dev/superpowers/specs/2026-07-30-boss-ai-single-track-design.md
git commit -m "docs(enemy): Boss AI 单轨落地——新增作者指南，spec 标记已实施
指南覆盖定制路径写法、建态原语、阶段门、招式配置、开战触发、
死亡归属，以 ChaoFengAi 为完整范例。
记录仍为待办的两项：ReceiveParry 接线（需 DamageInfo 带攻击者）、
EnemyAbilityModule（能力资产编辑器总览）。"
```
---
## 后续独立任务（不在本计划范围）
| 任务 | 缘由 |
|---|---|
| `ReceiveParry` 接线 | `DamageInfo` 无攻击者引用，需在 Combat 层补（加 attacker 或弹反成功时回调 `HitBox`）。见 spec §6.2 |
| `EnemyAbilityModule` 编辑器总览 | `BossSkillModule` 删除后能力资产无编辑器视图。见 spec §6.4 |
| `AiDefinitionValidator` | 防 450+ 能力引用出错，优先级高于上一项。见组合式模块 spec §6 |
| `BossEncounterCoordinator` | 多体 Boss 交替出招令牌。等真设计双体 Boss 时再做。见 spec §7.2 |
| 嘲风动画 Clip 接入 | 美术资源缺口。Clip 到位后校招式判定时序与预警节奏 |
Reference in New Issue View Git Blame Copy Permalink