docs(enemy): 计划同步——AiStateFragments 空能力 id 改建图期报错

原稿沿用旧代码的静默跳过写法。AiStateFragments 成为公开原语后，
定制 AiScript 漏配 id 会产出"存在但什么都不做"的状态且无报错，
与 T1 引入 BrainBuilder.RequireState 的理由是同一类失败，不应双标。
校验放建图期而非每帧回调，兼顾快速失败与热路径开销。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Docs_Dev/superpowers/plans/2026-07-29-enemy-ai-composable-modules.md

@@ -492,17 +492,23 @@ namespace BaseGames.Enemies
         /// 用于追击、冲锋这类"只要还在这个状态就该一直在做"的能力。
         /// </summary>
         public static BrainBuilder.StateBuilder Ability(BrainBuilder b, string state, string abilityId)
-            => b.State(state)
+        {
+            RequireAbilityId(state, abilityId);
+            return b.State(state)
                 .OnEnter(x => EnsureAbility(x, abilityId))
                 .Tick  (x => EnsureAbility(x, abilityId))
                 .OnExit(x => x.Combat.InterruptAbilities());
+        }
 
         /// <summary>
         /// 由能力驱动的一次性态：只在进入时触发，不每帧重触发。
         /// 用于死亡等一次性演出——若用 Ability()，演出播完会被 Tick 无限重播。
         /// </summary>
         public static BrainBuilder.StateBuilder AbilityOnce(BrainBuilder b, string state, string abilityId)
-            => b.State(state).OnEnter(x => EnsureAbility(x, abilityId));
+        {
+            RequireAbilityId(state, abilityId);
+            return b.State(state).OnEnter(x => EnsureAbility(x, abilityId));
+        }
 
         /// <summary>
         /// 无行为的终态。不需要在这里停移动——转入本态时，上一个态的 OnExit 已经收尾。
@@ -517,15 +523,30 @@ namespace BaseGames.Enemies
             else                             x.Locomotion.SetMode(mode);
         }
 
+        // 建图期校验：空 id 会让状态存在却什么都不做——敌人杵着不动、无任何报错，
+        // 正是 BrainBuilder.RequireState 要防的同一类静默失败。放建图期而非运行时回调里，
+        // 既能快速失败，也省掉热路径上每帧一次的判空。
+        static void RequireAbilityId(string state, string abilityId)
+        {
+            if (string.IsNullOrEmpty(abilityId))
+                throw new ArgumentException(
+                    $"AiStateFragments: 状态 '{state}' 未配置能力 id。若该状态本就不需要能力" +
+                    "（如死亡演出交给物理状态机），请改用 Terminal()。", nameof(abilityId));
+        }
+
         static void EnsureAbility(IAiContext x, string abilityId)
         {
-            if (!string.IsNullOrEmpty(abilityId) && !x.Combat.IsAbilityRunning(abilityId))
+            if (!x.Combat.IsAbilityRunning(abilityId)) x.Combat.UseAbility(abilityId);
-                x.Combat.UseAbility(abilityId);
         }
     }
 }
 ```
 
+> 注：`RequireAbilityId` 是计划执行中根据质量审查加入的（原稿沿用了旧代码里
+> `if (!string.IsNullOrEmpty(abilityId) && ...)` 的静默跳过）。旧写法在 `AiStateFragments`
+> 成为**公开**原语后不可接受——定制 AiScript 直接调用时，漏配 id 会产出一个什么都不做的
+> 状态且无任何报错。`Terminal()` 才是"本就不需要能力"的正确出口。
+
 - [ ] **Step 5: 运行测试确认通过**
 
 运行 `AiStateFragmentsTests`。期望：5 项全部 PASS。