feat(ai): Build() 校验「非终态必须有出口」,堵住零报错的永久卡死

BrainBuilder.Build() 此前只做正向校验——边指向的态是否已声明(RequireState
的同款关切);反向从不检查。一个已声明却没有任何出边的非终态,会让敌人进去
就永久停在那里,且全程零报错。计划里点名的风险点是 BossFragments.PhaseTransition:
它按设计不自带出边,出口全靠调用方补挂,漏一条就把 Boss 锁死。

做法:AiState 加 IsTerminal,StateBuilder 加 .Terminal() 显式标记,
AiStateFragments.Terminal() 自带该标记;Build() 对「非终态且无出口」抛异常。

「有出口」的判定比计划原话严一档,两点都是照 AiRuntime 的实际行为定的:
- 自转换不算——Switch 对 Target == 当前态直接 return false,根本出不去;
- 全局转换不算——全局事件边要外部推信号才触发,不是自主出口。把它算作出口,
  等于让「只有死了才出得去」的死角通过校验,而那恰是本校验要暴露的东西。

校验放在 Build() 而非各生产入口:生产的完整图装配点是 AiScript.GetOrBuildGraph
与 AiRecipeSO 两处,放 Build() 能让将来新增的入口默认受保护。代价是模块单测
需要一条别的路——单个 IUnawareModule / IEngagementModule 按设计只声明自己的态,
升级边由 PerceptionSkeleton 事后挂,单独构建时的死角是正常中间态而非缺陷。
为此加 BuildPartial():跳过本项校验,其余照旧。

测试侧按语义分两类处理,没有一刀切:
- 概念上确实是终态的(Dead)标 .Terminal(),保留 Build() 的全量校验;
- 隔离验证单个模块/片段的部分图改用 BuildPartial();
- AiScriptTests / AiDefinitionRegistryTests 的夹具经 GetOrBuildGraph 走生产
  Build(),给桩汇态补了回边——这两条本就该验完整图。
- 断言 Build() 因别的原因抛异常的用例原样保留。
PerceptionSkeleton 与嘲风图建的都是完整图,无需改动即通过——这本身就是覆盖。

验证:编译 0 错;EditMode 269/269(264 + 新增 5)。
加校验后曾有 49 条既有测试变红,全部为上述两类夹具,逐条按语义修正后转绿。

变异验证:注释掉 ChaoFengAi 里 PhaseTx 的 txDone 出边后,ChaoFengAiTests
8 条全部变红,报错精确点名 'PhaseTransition';还原后复验 269/269。
本改动之前,同样的删除是零报错的——Boss 会静默锁死在过渡态,
这正是本校验存在的理由。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-31 13:21:07 +08:00
co-authored by Claude Opus 5
parent 30a880c922
commit 0f676b0e88
14 changed files with 184 additions and 26 deletions
+15 -11
View File
@@ -7,6 +7,10 @@ namespace BaseGames.Tests.EditMode.AI
/// BrainGraph 框架健壮性/边界测试:构图校验、转换优先级、全局转换、
/// 事件与条件优先、队列信号、自转换、trace 上限、Blackboard、dt 传递。
/// 与 AiRuntimeTests(主干行为)互补,覆盖易回归的边角。
///
/// 本文件的夹具多为「A → 桩汇态」的最小图,汇态刻意不挂出边,
/// 因此用 BuildPartial() 构建——它跳过「非终态必须有出口」校验,
/// 其余校验照旧。断言 Build() 抛异常的用例仍用 Build()。
/// </summary>
public class AiFrameworkTests
{
@@ -66,7 +70,7 @@ namespace BaseGames.Tests.EditMode.AI
.To("B").When(c => true, "first")
.To("C").When(c => true, "second"); // 两者都真,先声明的 B 胜
b.State("B"); b.State("C");
var rt = new AiRuntime(b.Build(), new FakeAiContext());
var rt = new AiRuntime(b.BuildPartial(), new FakeAiContext());
rt.Tick(0.1f);
Assert.AreEqual("B", rt.CurrentStateName);
}
@@ -80,7 +84,7 @@ namespace BaseGames.Tests.EditMode.AI
b.Global().To("Panic").When(c => c.Vitals.HpBelow(0.3f), "lowHp");
var ctx = new FakeAiContext();
ctx.V.Hp = 0.1f;
var rt = new AiRuntime(b.Build(), ctx);
var rt = new AiRuntime(b.BuildPartial(), ctx);
rt.Tick(0.1f);
Assert.AreEqual("Panic", rt.CurrentStateName);
}
@@ -93,7 +97,7 @@ namespace BaseGames.Tests.EditMode.AI
b.State("A").To("B").When(c => true, "local");
b.State("B"); b.State("G");
b.Global().To("G").When(c => true, "global"); // 全局先评估
var rt = new AiRuntime(b.Build(), new FakeAiContext());
var rt = new AiRuntime(b.BuildPartial(), new FakeAiContext());
rt.Tick(0.1f);
Assert.AreEqual("G", rt.CurrentStateName);
}
@@ -109,7 +113,7 @@ namespace BaseGames.Tests.EditMode.AI
.To("ByCond").When(c => true, "cond") // 条件恒真
.To("ByEvent").OnEvent(AiSignal.Died); // 事件优先(Tick 第1步)
b.State("ByCond"); b.State("ByEvent");
var rt = new AiRuntime(b.Build(), new FakeAiContext());
var rt = new AiRuntime(b.BuildPartial(), new FakeAiContext());
rt.Send(AiSignal.Died);
rt.Tick(0.1f);
Assert.AreEqual("ByEvent", rt.CurrentStateName);
@@ -124,7 +128,7 @@ namespace BaseGames.Tests.EditMode.AI
b.State("B");
var ctx = new FakeAiContext();
ctx.S.Sees = true;
var rt = new AiRuntime(b.Build(), ctx);
var rt = new AiRuntime(b.BuildPartial(), ctx);
rt.Send(AiSignal.Died); // A 无 Died 转换 → 被消费掉,不阻塞条件评估
rt.Tick(0.1f);
Assert.AreEqual("B", rt.CurrentStateName);
@@ -141,7 +145,7 @@ namespace BaseGames.Tests.EditMode.AI
b.State("A").To("B").OnEvent(AiSignal.Died);
b.State("B").OnEnter(c => c.Blackboard.Set("enters", c.Blackboard.Get<int>("enters") + 1));
var ctx = new FakeAiContext();
var rt = new AiRuntime(b.Build(), ctx);
var rt = new AiRuntime(b.BuildPartial(), ctx);
rt.Send(AiSignal.Died);
rt.Send(AiSignal.Died);
rt.Tick(0.1f);
@@ -162,7 +166,7 @@ namespace BaseGames.Tests.EditMode.AI
.OnEnter(c => c.Blackboard.Set("enters", c.Blackboard.Get<int>("enters") + 1))
.To("A").When(c => true, "self"); // 自转换
var ctx = new FakeAiContext();
var rt = new AiRuntime(b.Build(), ctx); // 构造进入 → enters=1
var rt = new AiRuntime(b.BuildPartial(), ctx); // 构造进入 → enters=1
rt.Tick(0.1f); // 自转换应 no-op,不重跑 OnEnter
Assert.AreEqual(1, ctx.BB.Get<int>("enters"));
Assert.AreEqual("A", rt.CurrentStateName);
@@ -178,7 +182,7 @@ namespace BaseGames.Tests.EditMode.AI
.To("B").When(c => true, "go");
b.State("B");
var ctx = new FakeAiContext();
var rt = new AiRuntime(b.Build(), ctx);
var rt = new AiRuntime(b.BuildPartial(), ctx);
rt.Tick(0.1f); // 转换发生 → 当帧不应执行 A 的 OnTick
Assert.AreEqual("B", rt.CurrentStateName);
Assert.IsFalse(ctx.BB.Has("ticked"));
@@ -191,7 +195,7 @@ namespace BaseGames.Tests.EditMode.AI
b.Entry("A");
b.State("A").Tick((c, dt) => c.Blackboard.Set("dt", dt)); // 无转换
var ctx = new FakeAiContext();
var rt = new AiRuntime(b.Build(), ctx);
var rt = new AiRuntime(b.BuildPartial(), ctx);
rt.Tick(0.25f);
Assert.AreEqual(0.25f, ctx.BB.Get<float>("dt"), 1e-5f);
}
@@ -221,7 +225,7 @@ namespace BaseGames.Tests.EditMode.AI
b.Global().To("Dead").OnEvent(AiSignal.Died);
var ctx = new FakeAiContext();
ctx.V.Controllable = false; // 受击中(若无事件本会挂起)
var rt = new AiRuntime(b.Build(), ctx);
var rt = new AiRuntime(b.BuildPartial(), ctx);
rt.Send(AiSignal.Died);
rt.Tick(0.1f);
Assert.AreEqual("Dead", rt.CurrentStateName);
@@ -236,7 +240,7 @@ namespace BaseGames.Tests.EditMode.AI
b.State("A").To("B").When(c => false, "t1"); // 第一次声明
b.State("A").To("C").When(c => true, "t2"); // 再次 State("A") 应取同一状态,累加转换
b.State("B"); b.State("C");
var graph = b.Build();
var graph = b.BuildPartial();
Assert.AreEqual(2, graph.GetState("A").Transitions.Count);
var rt = new AiRuntime(graph, new FakeAiContext());
rt.Tick(0.1f); // t1 假、t2 真 → C