docs(enemy): 计划新增 T5b——BrainBuilder.DeclareState 防模块间状态名冲突

契约质量审查提出：模块化后 State() 的"有则取"语义使两个独立模块取同名状态时后者静默覆盖前者回调。与 T1 的 RequireState 是同一类失败的两面，趁 0 个模块实现时补代价最低。附带补充交战/死亡层 "为何单阶段 Build 足够"的不变量说明。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-29 11:57:57 +08:00
parent 17e71dac39
commit 5dcbce6019
1 changed files with 124 additions and 0 deletions
@@ -680,6 +680,130 @@ git commit -m "feat(enemy): 未发现层/交战层/死亡层三个模块契约"
 ---
 ## Task 5b: `BrainBuilder.DeclareState` 防状态名冲突
 > 本任务是执行 T5 后由契约质量审查提出并采纳的追加项，非原稿内容。
 >
 > **风险来由**：`BrainBuilder.State(name)` 是「有则取、无则建」。改造前 `PerceptionStateMachine`
 > 是单个函数独占全部状态名，撞名不可能发生。改成「策划在下拉里自由组合三层独立模块」之后，
 > 两个不同作者的模块取了同一个状态名（或某模块内部态叫 `Alert`，撞上骨架保留的那个），
 > 后声明者的 `.OnEnter/.Tick/.OnExit` 会**静默覆盖**前者 —— 敌人跑错行为且零报错。
 >
 > 这与 T1 的 `RequireState` 是同一类失败的两面：`RequireState` 守「挂边到未声明的态」，
 > `DeclareState` 守「重复声明同一个态」。趁只有 0 个模块实现时补，代价最低。
 **Files:**
 - Modify: `Assets/_Game/Scripts/AI/BrainBuilder.cs`
 - Modify: `Assets/_Game/Scripts/Enemies/AIBrain/Modules/AiStateFragments.cs`
 - Modify: `Assets/_Game/Scripts/Enemies/AIBrain/Modules/IEngagementModule.cs`
 - Modify: `Assets/_Game/Scripts/Enemies/AIBrain/Modules/IDeathModule.cs`
 - Test: `Assets/Tests/EditMode/AI/BrainBuilderTests.cs`
 - [ ] **Step 1: 写失败测试**
 在 `BrainBuilderTests.cs` 类体内追加：
 ```csharp
        [Test]
        public void DeclareState_Throws_OnDuplicateName()
        {
            var b = new BrainBuilder();
            b.DeclareState("Dup");
            var ex = Assert.Throws<System.InvalidOperationException>(() => b.DeclareState("Dup"));
            StringAssert.Contains("Dup", ex.Message);
        }
        [Test]
        public void DeclareState_ReturnsUsableBuilder_OnFirstDeclare()
        {
            var b = new BrainBuilder();
            b.Entry("A");
            b.DeclareState("A").To("B").When(c => true, "go");
            b.DeclareState("B");
            Assert.DoesNotThrow(() => b.Build());
        }
        [Test]
        public void State_StaysLenient_ForAttachingToDeclaredState()
        {
            // State() 仍是"有则取"——骨架要给模块已声明的态挂升级边，靠的就是这个。
            var b = new BrainBuilder();
            b.Entry("A");
            b.DeclareState("A");
            Assert.DoesNotThrow(() => b.State("A").To("A").When(c => false, "noop"));
        }
 ```
 - [ ] **Step 2: 运行测试确认失败**
 运行 `BrainBuilderTests`。期望：编译错误 `'BrainBuilder' does not contain a definition for 'DeclareState'`。
 - [ ] **Step 3: 实现 `DeclareState`**
 在 `BrainBuilder.cs` 的 `RequireState` 之后插入：
 ```csharp
        /// <summary>
        /// 首次声明一个状态。名字已存在即抛——防止两个独立模块取了同名状态时，
        /// 后者的 OnEnter/Tick/OnExit 静默覆盖前者（敌人跑错行为且零报错）。
        /// 只有"首次声明行为"的调用点用它；给已声明的态挂边仍用 State()。
        /// </summary>
        public StateBuilder DeclareState(string name)
        {
            if (_states.ContainsKey(name))
                throw new InvalidOperationException(
                    $"BrainBuilder: 状态 '{name}' 已被声明过。两个模块取了同名状态会互相覆盖回调——" +
                    "请给其中一个换个不冲突的名字。");
            return State(name);
        }
 ```
 - [ ] **Step 4: 让四个建态原语走 `DeclareState`**
 `AiStateFragments.cs` 中，把四个原语里的 `b.State(state)` 全部换成 `b.DeclareState(state)`
 （`Locomotion` / `Ability` / `AbilityOnce` / `Terminal` 各一处）。私有辅助方法不动。
 - [ ] **Step 5: 给交战层 / 死亡层契约补一条不变量说明**
 `IEngagementModule.cs` 的接口 XML 注释末尾追加一段：
 ```
    /// 为何本层只需单阶段 Build（而未发现层要拆 Declare/Link）：骨架只把边**指向**
    /// EntryState，从不在本模块自己的状态上挂边，所以 Build 内声明的边不会被外部抢占。
    /// 将来若修改骨架、使其向交战态挂边，必须先回来重新审视本契约。
 ```
 `IDeathModule.cs` 的接口 XML 注释末尾追加：
 ```
    /// 同 IEngagementModule：骨架只把全局 Died 边指向 EntryState，不在死亡链内部挂边，
    /// 故单阶段 Build 足够。
 ```
 并在 `IUnawareModule.cs` 的 `Entry` 成员注释上补一句区分：
 ```
        /// <summary>图入口（出生态）。注意与交战/死亡层的 EntryState 不同：
        /// 本属性会成为整张图唯一的 BrainBuilder.Entry，而 EntryState 只是别处 To() 的目标。</summary>
 ```
 - [ ] **Step 6: 运行测试确认通过**
 运行 `BrainBuilderTests` 与 `AiStateFragmentsTests`，再跑全量 EditMode。
 期望：新增 3 个测试，全量从 222 变为 225，0 失败。
 > 若有既有测试因重复声明而失败，**停下报告** —— 那说明框架里本来就存在重复声明，
 > 是真问题，不要靠把 `DeclareState` 改宽松来绕过。
 - [ ] **Step 7: 提交**
 ```bash
 git add Assets/_Game/Scripts/AI/BrainBuilder.cs Assets/_Game/Scripts/Enemies/AIBrain/Modules Assets/Tests/EditMode/AI/BrainBuilderTests.cs
 git commit -m "feat(ai): BrainBuilder.DeclareState——重复声明状态即报错，防模块间同名静默覆盖"
 ```
 ---
 ## Task 6: 未发现层三个模块
 **Files:**