# BrainGraph 第 1 阶段：核心运行时 实现计划

> **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:** 实现 BrainGraph 决策框架的纯 C# 核心运行时（不可变状态图 + fluent builder + 每实例运行时 + 条件/事件转换 + IsControllable 让位门 + trace + 池复用重置），全部用 EditMode 单测覆盖，零 Unity 场景依赖。

**Architecture:** HFSM 骨干。声明层（`AiScript.Build`）用 `BrainBuilder` 构建成不可变共享 `AiGraph`（每敌人类型一份 flyweight）；每个敌人实例持有一个轻量 `AiRuntime`，通过 `IAiContext`（暴露 `ISensor/IMover/ICombatant/IActorVitals/Blackboard` 的能力接口）驱动真实子系统。核心层只依赖 `BaseGames.Core` + `UnityEngine`（用 `Vector2` 等值类型），用假的能力接口即可完整单测。

**Tech Stack:** Unity 2022+, C#, Unity Test Framework (NUnit, EditMode), asmdef。

**Spec:** `Docs/superpowers/specs/2026-07-03-enemy-ai-framework-design.md`（本阶段覆盖其 §3.1/§3.2/§3.3 的条件+事件转换、§3.6 IsControllable 门、§3.8 池复用重置；§3.4 能力编排 sugar、§3.7 AiScheduler、§4 完整接口方法集、§6 交付面、§7 组件与适配器留待后续阶段）。

---

## 文件结构（本阶段新建）

新程序集 `BaseGames.AI`，位于 `Assets/_Game/Scripts/AI/`：

- `BaseGames.AI.asmdef` — 新程序集，仅引用 `BaseGames.Core`。
- `AiSignal.cs` — 推送信号枚举。
- `IAiContext.cs` — 上下文接口（聚合能力接口 + 黑板）。
- `ISensor.cs` / `IMover.cs` / `ICombatant.cs` / `IActorVitals.cs` — 能力接口（本阶段只声明被测试消费的最小成员，完整成员集在第 3 阶段接适配器时按需补齐）。
- `Blackboard.cs` — 具名、可枚举的 AI 临时值容器。
- `Transition.cs` — 一条转换（条件型 / 事件型 + 可读标签 + 优先级）。
- `AiState.cs` — 一个状态（OnEnter/Tick/OnExit + 出边转换列表）。
- `AiGraph.cs` — 不可变状态图（状态字典 + 入口 + 全局/父层转换）。
- `BrainBuilder.cs` — fluent builder，含 `StateBuilder` / `TransitionBuilder` / `GlobalBuilder`。
- `AiScript.cs` — 抽象声明基类 + `AiDefinitionAttribute`。
- `TransitionRecord.cs` — trace 记录（from/to/trigger）。
- `AiRuntime.cs` — 每实例执行器（Tick、转换评估、门、事件队列、trace、Reset）。

测试（`Assets/Tests/EditMode/AI/`）：
- `BlackboardTests.cs`、`BrainBuilderTests.cs`、`AiRuntimeTests.cs`、`Fakes/FakeAiContext.cs`。
- 修改 `Assets/Tests/EditMode/BaseGames.Tests.EditMode.asmdef` 增加 `BaseGames.AI` 引用。

> 命名/注释不得出现任何参考游戏名（CLAUDE.md 第 4 条）。

---

## Task 1: 新建 `BaseGames.AI` 程序集与基础类型

**Files:**
- Create: `Assets/_Game/Scripts/AI/BaseGames.AI.asmdef`
- Create: `Assets/_Game/Scripts/AI/AiSignal.cs`
- Create: `Assets/_Game/Scripts/AI/Blackboard.cs`
- Create: `Assets/Tests/EditMode/AI/BlackboardTests.cs`
- Modify: `Assets/Tests/EditMode/BaseGames.Tests.EditMode.asmdef`

- [ ] **Step 1: 创建程序集定义**

`Assets/_Game/Scripts/AI/BaseGames.AI.asmdef`：

```json
{
  "name": "BaseGames.AI",
  "rootNamespace": "BaseGames.AI",
  "references": [
    "BaseGames.Core"
  ],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "versionDefines": [],
  "noEngineReferences": false
}
```

- [ ] **Step 2: 创建 `AiSignal` 枚举**

`Assets/_Game/Scripts/AI/AiSignal.cs`：

```csharp
namespace BaseGames.AI
{
    /// <summary>决策层的推送信号，用于事件驱动的状态转换（不靠轮询）。</summary>
    public enum AiSignal
    {
        Damaged,      // 受到伤害
        Parried,      // 被弹反
        Staggered,    // 进入硬直
        KnockedUp,    // 被击飞
        Died,         // 死亡
        PlayerSpotted,// 首次侦测到玩家
        AbilityEnded, // 当前能力协程结束/被打断
        PhaseChanged  // Boss 阶段变更
    }
}
```

- [ ] **Step 3: 在测试程序集里加 `BaseGames.AI` 引用**

修改 `Assets/Tests/EditMode/BaseGames.Tests.EditMode.asmdef` 的 `references` 数组，加入一行 `"BaseGames.AI"`（放在 `"BaseGames.Core"` 之后）：

```json
  "references": [
    "BaseGames.Combat.StatusEffects",
    "BaseGames.Combat",
    "BaseGames.Core",
    "BaseGames.AI",
    "BaseGames.Core.Events",
    "BaseGames.Core.Save",
    "BaseGames.EventChain",
    "UnityEngine.TestRunner",
    "UnityEditor.TestRunner"
  ],
```

- [ ] **Step 4: 写失败测试 —— Blackboard 读写与枚举**

`Assets/Tests/EditMode/AI/BlackboardTests.cs`：

```csharp
using NUnit.Framework;
using UnityEngine;
using BaseGames.AI;

namespace BaseGames.Tests.EditMode.AI
{
    public class BlackboardTests
    {
        [Test]
        public void SetThenGet_ReturnsValue()
        {
            var bb = new Blackboard();
            bb.Set("lastKnown", new Vector2(3f, 4f));
            Assert.AreEqual(new Vector2(3f, 4f), bb.Get<Vector2>("lastKnown"));
        }

        [Test]
        public void Get_MissingKey_ReturnsDefault()
        {
            var bb = new Blackboard();
            Assert.AreEqual(0f, bb.Get<float>("nope"));
        }

        [Test]
        public void Keys_EnumeratesAllSetKeys()
        {
            var bb = new Blackboard();
            bb.Set("a", 1);
            bb.Set("b", 2);
            CollectionAssert.AreEquivalent(new[] { "a", "b" }, bb.Keys);
        }

        [Test]
        public void Clear_RemovesAll()
        {
            var bb = new Blackboard();
            bb.Set("a", 1);
            bb.Clear();
            CollectionAssert.IsEmpty(bb.Keys);
        }

        [Test]
        public void Snapshot_ReturnsKeyToStringMap_ForIntrospection()
        {
            var bb = new Blackboard();
            bb.Set("hp", 0.5f);
            var snap = bb.Snapshot();
            Assert.AreEqual("0.5", snap["hp"]);
        }
    }
}
```

- [ ] **Step 5: 运行测试确认失败**

Run（Unity Test Runner，EditMode，或 CLI）：`Unity -runTests -testPlatform EditMode -testFilter BlackboardTests`
Expected: 编译失败 / FAIL —— `Blackboard` 未定义。

- [ ] **Step 6: 实现 `Blackboard`**

`Assets/_Game/Scripts/AI/Blackboard.cs`：

```csharp
using System.Collections.Generic;
using System.Globalization;

namespace BaseGames.AI
{
    /// <summary>
    /// 具名、可枚举的 AI 临时值容器（每敌人实例一份）。
    /// 保留"具名"是为了让调试器/MCP 能通用枚举当前值（见 spec §3.5）。
    /// </summary>
    public sealed class Blackboard
    {
        readonly Dictionary<string, object> _values = new Dictionary<string, object>();

        public void Set<T>(string key, T value) => _values[key] = value;

        public T Get<T>(string key)
            => _values.TryGetValue(key, out var v) && v is T t ? t : default;

        public bool Has(string key) => _values.ContainsKey(key);

        public IReadOnlyCollection<string> Keys => _values.Keys;

        public void Clear() => _values.Clear();

        /// <summary>供调试器/MCP 自省：key → 值的字符串表示。</summary>
        public Dictionary<string, string> Snapshot()
        {
            var result = new Dictionary<string, string>(_values.Count);
            foreach (var kv in _values)
            {
                result[kv.Key] = kv.Value is System.IFormattable f
                    ? f.ToString(null, CultureInfo.InvariantCulture)
                    : kv.Value?.ToString() ?? "null";
            }
            return result;
        }
    }
}
```

- [ ] **Step 7: 运行测试确认通过**

Run: EditMode `BlackboardTests`
Expected: PASS（5 项全绿）。

- [ ] **Step 8: 提交**

```bash
git add Assets/_Game/Scripts/AI/BaseGames.AI.asmdef Assets/_Game/Scripts/AI/BaseGames.AI.asmdef.meta \
        Assets/_Game/Scripts/AI/AiSignal.cs Assets/_Game/Scripts/AI/AiSignal.cs.meta \
        Assets/_Game/Scripts/AI/Blackboard.cs Assets/_Game/Scripts/AI/Blackboard.cs.meta \
        Assets/Tests/EditMode/AI Assets/Tests/EditMode/BaseGames.Tests.EditMode.asmdef
git commit -m "feat(ai): BrainGraph 核心程序集 + AiSignal + Blackboard(可自省)"
```

---

## Task 2: 能力接口、上下文、AiScript 声明基类

**Files:**
- Create: `Assets/_Game/Scripts/AI/ISensor.cs`
- Create: `Assets/_Game/Scripts/AI/IMover.cs`
- Create: `Assets/_Game/Scripts/AI/ICombatant.cs`
- Create: `Assets/_Game/Scripts/AI/IActorVitals.cs`
- Create: `Assets/_Game/Scripts/AI/IAiContext.cs`
- Create: `Assets/_Game/Scripts/AI/AiScript.cs`

> 本阶段接口只声明**测试消费到的最小成员**（YAGNI）。第 3 阶段接适配器时，按 spec §4 的完整映射表补齐其余方法（`SlotDetects`/`JumpTo`/`UseSkillWeighted`/`SetPoiseLevel` 等）。

- [ ] **Step 1: `ISensor`**

`Assets/_Game/Scripts/AI/ISensor.cs`：

```csharp
using UnityEngine;

namespace BaseGames.AI
{
    /// <summary>感知能力接口（第 3 阶段由 SensorAdapter 适配 PhysicsPerceptionSystem/ThreatAssessor）。</summary>
    public interface ISensor
    {
        bool SeesPlayer();
        bool InRange(float range);      // 内部用平方距离比较
        bool LostFor(float seconds);    // 丢失玩家已持续 seconds
        Vector2 LastKnown { get; }
    }
}
```

- [ ] **Step 2: `IMover`**

`Assets/_Game/Scripts/AI/IMover.cs`：

```csharp
using UnityEngine;

namespace BaseGames.AI
{
    /// <summary>移动能力接口（第 3 阶段由 MoverAdapter 适配 IPathAgent/EnemyMovement）。</summary>
    public interface IMover
    {
        void MoveTo(Vector2 target);
        void FacePlayer();
        void Stop();
        void WalkRandom();
        void LookAround();
    }
}
```

- [ ] **Step 3: `ICombatant`**

`Assets/_Game/Scripts/AI/ICombatant.cs`：

```csharp
namespace BaseGames.AI
{
    /// <summary>战斗/能力调度接口（第 3 阶段由 CombatantAdapter 适配 EnemyAbilityRegistry）。</summary>
    public interface ICombatant
    {
        bool UseAbility(string abilityId);
        bool IsAbilityRunning(string abilityId = null); // null = 任意能力
        bool NoAbilityRunning { get; }
        bool CanUseAbility(string abilityId);
    }
}
```

- [ ] **Step 4: `IActorVitals`**

`Assets/_Game/Scripts/AI/IActorVitals.cs`：

```csharp
namespace BaseGames.AI
{
    /// <summary>生命体征/受控状态接口（第 3 阶段由 VitalsAdapter 适配 EnemyStats/EnemyBase）。</summary>
    public interface IActorVitals
    {
        bool IsAlive { get; }
        /// <summary>物理态是否为 Controlled——决策层仅在此为真时推进（IsControllable 让位门, spec §3.6）。</summary>
        bool IsControllable { get; }
        float HpPercent { get; }
        bool HpBelow(float ratio);
    }
}
```

- [ ] **Step 5: `IAiContext`**

`Assets/_Game/Scripts/AI/IAiContext.cs`：

```csharp
namespace BaseGames.AI
{
    /// <summary>
    /// 传给所有状态回调 / 转换条件的上下文。声明层的 lambda 只能通过它访问实例，
    /// 不得闭包捕获具体敌人——这是 lambda 挂在共享 AiGraph 上的前提（spec §3.8）。
    /// </summary>
    public interface IAiContext
    {
        ISensor Sensor { get; }
        IMover Mover { get; }
        ICombatant Combat { get; }
        IActorVitals Vitals { get; }
        Blackboard Blackboard { get; }
    }
}
```

- [ ] **Step 6: `AiScript` 抽象基类 + 特性**

`Assets/_Game/Scripts/AI/AiScript.cs`：

```csharp
using System;

namespace BaseGames.AI
{
    /// <summary>标注一个 AiScript 对应的敌人类型 id，供 AiDefinitionRegistry 反射收集（第 3 阶段）。</summary>
    [AttributeUsage(AttributeTargets.Class, Inherited = false)]
    public sealed class AiDefinitionAttribute : Attribute
    {
        public string Id { get; }
        public AiDefinitionAttribute(string id) => Id = id;
    }

    /// <summary>
    /// 一种敌人 AI 的声明基类（唯一事实来源）。子类实现 Build 用 fluent 描述状态机。
    /// 构建结果 AiGraph 每类型只建一次、实例共享（flyweight, spec §3.1）。
    /// </summary>
    public abstract class AiScript
    {
        AiGraph _cached;

        /// <summary>惰性构建并缓存共享 AiGraph。</summary>
        public AiGraph GetOrBuildGraph()
        {
            if (_cached == null)
            {
                var b = new BrainBuilder();
                Build(b);
                _cached = b.Build();
            }
            return _cached;
        }

        protected abstract void Build(BrainBuilder b);
    }
}
```

- [ ] **Step 7: 编译校验（无独立测试，类型将由后续任务的测试消费）**

Run: 触发 Unity 编译（MCP `unity_get_compilation_errors` 或切到 Editor）。
Expected: 无编译错误（`BrainBuilder`/`AiGraph` 尚未定义会报错 —— 因此本步骤仅创建接口文件，`AiScript.cs` 依赖的 `BrainBuilder`/`AiGraph` 在 Task 3、4 定义；**先不提交，与 Task 3、4 连续完成后一并编译**）。

> 说明：`AiScript.cs` 引用了 Task 3/4 才定义的 `BrainBuilder`/`AiGraph`。执行时先完成 Step 1-5（接口，可独立编译），Step 6 的 `AiScript.cs` 可暂缓到 Task 4 之后再落，或与 Task 3、4 合并提交。TDD 顺序见下方 Task 3。

- [ ] **Step 8: 提交接口层**

```bash
git add Assets/_Game/Scripts/AI/ISensor.cs Assets/_Game/Scripts/AI/IMover.cs \
        Assets/_Game/Scripts/AI/ICombatant.cs Assets/_Game/Scripts/AI/IActorVitals.cs \
        Assets/_Game/Scripts/AI/IAiContext.cs \
        Assets/_Game/Scripts/AI/*.meta
git commit -m "feat(ai): BrainGraph 能力接口(ISensor/IMover/ICombatant/IActorVitals)+IAiContext"
```

---

## Task 3: `Transition` 与 `AiState`

**Files:**
- Create: `Assets/_Game/Scripts/AI/Transition.cs`
- Create: `Assets/_Game/Scripts/AI/AiState.cs`
- Create: `Assets/_Game/Scripts/AI/TransitionRecord.cs`

这两个是数据结构（无独立行为测试），其行为由 Task 4（builder）与 Task 5/6（runtime）的测试覆盖。因此本任务只创建类型 + 编译校验，不单独写测试。

- [ ] **Step 1: `Transition`**

`Assets/_Game/Scripts/AI/Transition.cs`：

```csharp
using System;

namespace BaseGames.AI
{
    /// <summary>一条转换：条件型（Condition 非空）或事件型（Event 非空）。二者互斥。</summary>
    public sealed class Transition
    {
        public string Target { get; }
        public Func<IAiContext, bool> Condition { get; }   // 条件型：pull，按 LOD 频率评估
        public AiSignal? Event { get; }                    // 事件型：push，收到信号即触发
        public string Label { get; }                        // 可读标签（条件源码文本 / 事件名）

        Transition(string target, Func<IAiContext, bool> condition, AiSignal? evt, string label)
        {
            Target = target;
            Condition = condition;
            Event = evt;
            Label = label;
        }

        public static Transition OnCondition(string target, Func<IAiContext, bool> condition, string label)
            => new Transition(target, condition, null, label);

        public static Transition OnEvent(string target, AiSignal evt)
            => new Transition(target, null, evt, "on " + evt);

        public bool IsEvent => Event.HasValue;
    }
}
```

- [ ] **Step 2: `TransitionRecord`（trace 用）**

`Assets/_Game/Scripts/AI/TransitionRecord.cs`：

```csharp
namespace BaseGames.AI
{
    /// <summary>一次已发生的转换，供调试器/MCP 自省"最近为何转换"。</summary>
    public readonly struct TransitionRecord
    {
        public readonly string From;
        public readonly string To;
        public readonly string Trigger; // 条件标签或事件名

        public TransitionRecord(string from, string to, string trigger)
        {
            From = from;
            To = to;
            Trigger = trigger;
        }

        public override string ToString() => $"{From} -> {To} : {Trigger}";
    }
}
```

- [ ] **Step 3: `AiState`**

`Assets/_Game/Scripts/AI/AiState.cs`：

```csharp
using System;
using System.Collections.Generic;

namespace BaseGames.AI
{
    /// <summary>一个状态：进入/每帧/退出钩子 + 出边转换列表（按优先级有序，首个命中即转）。</summary>
    public sealed class AiState
    {
        public string Name { get; }
        public Action<IAiContext> OnEnter { get; internal set; }
        public Action<IAiContext, float> OnTick { get; internal set; } // (ctx, dt)
        public Action<IAiContext> OnExit { get; internal set; }
        public List<Transition> Transitions { get; } = new List<Transition>();

        public AiState(string name) => Name = name;
    }
}
```

- [ ] **Step 4: 编译校验**

Run: Unity 编译（`unity_get_compilation_errors`）。
Expected: 无新错误（这些类型自洽；`AiScript.cs` 仍缺 `BrainBuilder`/`AiGraph` → Task 4 补齐）。

- [ ] **Step 5: 提交**

```bash
git add Assets/_Game/Scripts/AI/Transition.cs Assets/_Game/Scripts/AI/AiState.cs \
        Assets/_Game/Scripts/AI/TransitionRecord.cs Assets/_Game/Scripts/AI/*.meta
git commit -m "feat(ai): BrainGraph Transition/AiState/TransitionRecord 数据结构"
```

---

## Task 4: `AiGraph` 与 `BrainBuilder`（fluent 声明）

**Files:**
- Create: `Assets/_Game/Scripts/AI/AiGraph.cs`
- Create: `Assets/_Game/Scripts/AI/BrainBuilder.cs`
- Create: `Assets/Tests/EditMode/AI/BrainBuilderTests.cs`

- [ ] **Step 1: 写失败测试 —— builder 构建出正确的图结构**

`Assets/Tests/EditMode/AI/BrainBuilderTests.cs`：

```csharp
using NUnit.Framework;
using BaseGames.AI;

namespace BaseGames.Tests.EditMode.AI
{
    public class BrainBuilderTests
    {
        static AiGraph BuildSample()
        {
            var b = new BrainBuilder();
            b.Entry("Patrol");
            b.Global().To("Dead").OnEvent(AiSignal.Died);
            b.State("Patrol")
                .To("Chase").When(c => c.Sensor.SeesPlayer(), "SeesPlayer");
            b.State("Chase")
                .To("Patrol").When(c => c.Sensor.LostFor(2f), "LostFor(2s)");
            b.State("Dead");
            return b.Build();
        }

        [Test]
        public void Build_SetsEntryState()
        {
            Assert.AreEqual("Patrol", BuildSample().EntryState);
        }

        [Test]
        public void Build_RegistersAllStates()
        {
            var g = BuildSample();
            CollectionAssert.AreEquivalent(
                new[] { "Patrol", "Chase", "Dead" },
                System.Linq.Enumerable.ToList(g.StateNames));
        }

        [Test]
        public void Build_UsesExplicitConditionLabel()
        {
            var g = BuildSample();
            var t = g.GetState("Patrol").Transitions[0];
            Assert.AreEqual("SeesPlayer", t.Label);
        }

        [Test]
        public void Build_UnlabeledCondition_FallsBackToCond()
        {
            var b = new BrainBuilder();
            b.Entry("A");
            b.State("A").To("B").When(c => true);
            b.State("B");
            var g = b.Build();
            Assert.AreEqual("cond", g.GetState("A").Transitions[0].Label);
        }

        [Test]
        public void Build_GlobalTransitionsAreSeparate()
        {
            var g = BuildSample();
            Assert.AreEqual(1, g.GlobalTransitions.Count);
            Assert.AreEqual("Dead", g.GlobalTransitions[0].Target);
            Assert.AreEqual(AiSignal.Died, g.GlobalTransitions[0].Event);
        }

        [Test]
        public void Build_UnknownTransitionTarget_Throws()
        {
            var b = new BrainBuilder();
            b.Entry("A");
            b.State("A").To("Nonexistent").When(c => true);
            Assert.Throws<System.InvalidOperationException>(() => b.Build());
        }
    }
}
```

- [ ] **Step 2: 运行测试确认失败**

Run: EditMode `BrainBuilderTests`
Expected: 编译失败 —— `AiGraph`/`BrainBuilder` 未定义。

- [ ] **Step 3: 实现 `AiGraph`**

`Assets/_Game/Scripts/AI/AiGraph.cs`：

```csharp
using System.Collections.Generic;

namespace BaseGames.AI
{
    /// <summary>
    /// 不可变状态图，每敌人类型构建一次、所有实例共享（flyweight, spec §3.1/§3.8）。
    /// 既被 AiRuntime 执行，又被 MermaidExporter/调试器只读投影。
    /// </summary>
    public sealed class AiGraph
    {
        readonly Dictionary<string, AiState> _states;
        public string EntryState { get; }
        public IReadOnlyList<Transition> GlobalTransitions { get; }

        public AiGraph(string entry, Dictionary<string, AiState> states, IReadOnlyList<Transition> globals)
        {
            EntryState = entry;
            _states = states;
            GlobalTransitions = globals;
        }

        public AiState GetState(string name) => _states[name];
        public bool HasState(string name) => _states.ContainsKey(name);
        public IEnumerable<string> StateNames => _states.Keys;
        public IEnumerable<AiState> States => _states.Values;
    }
}
```

- [ ] **Step 4: 实现 `BrainBuilder`（含 `StateBuilder`/`TransitionBuilder`/`GlobalBuilder`）**

`Assets/_Game/Scripts/AI/BrainBuilder.cs`：

```csharp
using System;
using System.Collections.Generic;

namespace BaseGames.AI
{
    /// <summary>fluent builder：声明层的唯一入口。构建出不可变 AiGraph。</summary>
    public sealed class BrainBuilder
    {
        readonly Dictionary<string, AiState> _states = new Dictionary<string, AiState>();
        readonly List<Transition> _globals = new List<Transition>();
        string _entry;

        public BrainBuilder Entry(string stateName)
        {
            _entry = stateName;
            return this;
        }

        public StateBuilder State(string name)
        {
            if (!_states.TryGetValue(name, out var s))
            {
                s = new AiState(name);
                _states[name] = s;
            }
            return new StateBuilder(this, s);
        }

        public GlobalBuilder Global() => new GlobalBuilder(this);

        internal void AddGlobal(Transition t) => _globals.Add(t);

        public AiGraph Build()
        {
            if (string.IsNullOrEmpty(_entry))
                throw new InvalidOperationException("BrainBuilder: 未设置 Entry 状态。");
            if (!_states.ContainsKey(_entry))
                throw new InvalidOperationException($"BrainBuilder: Entry 状态 '{_entry}' 未声明。");

            // 校验所有转换目标存在（根因暴露，不做下游兜底, CLAUDE.md 第 6 条）
            foreach (var s in _states.Values)
                foreach (var t in s.Transitions)
                    if (!_states.ContainsKey(t.Target))
                        throw new InvalidOperationException(
                            $"BrainBuilder: 状态 '{s.Name}' 的转换指向未声明状态 '{t.Target}'。");
            foreach (var t in _globals)
                if (!_states.ContainsKey(t.Target))
                    throw new InvalidOperationException(
                        $"BrainBuilder: 全局转换指向未声明状态 '{t.Target}'。");

            return new AiGraph(_entry, _states, _globals);
        }

        // ---- 嵌套 builder ----

        public sealed class StateBuilder
        {
            readonly BrainBuilder _owner;
            readonly AiState _state;
            internal StateBuilder(BrainBuilder owner, AiState state) { _owner = owner; _state = state; }

            public StateBuilder OnEnter(Action<IAiContext> fn) { _state.OnEnter = fn; return this; }
            public StateBuilder Tick(Action<IAiContext> fn) { _state.OnTick = (c, _) => fn(c); return this; }
            public StateBuilder Tick(Action<IAiContext, float> fn) { _state.OnTick = fn; return this; }
            public StateBuilder OnExit(Action<IAiContext> fn) { _state.OnExit = fn; return this; }

            public TransitionBuilder To(string target) => new TransitionBuilder(_owner, this, _state, target);
        }

        public sealed class TransitionBuilder
        {
            readonly BrainBuilder _owner;
            readonly StateBuilder _stateBuilder;
            readonly AiState _state;
            readonly string _target;
            internal TransitionBuilder(BrainBuilder owner, StateBuilder sb, AiState state, string target)
            { _owner = owner; _stateBuilder = sb; _state = state; _target = target; }

            /// <summary>
            /// 条件转换。label 为可读标签（用于 Mermaid 边 / trace 触发原因），
            /// C# 9 环境下需显式传入；不传则回退为 "cond"。
            /// （升级到 C# 10 后可改用 [CallerArgumentExpression] 自动抓取源码文本。）
            /// </summary>
            public StateBuilder When(Func<IAiContext, bool> cond, string label = null)
            {
                _state.Transitions.Add(Transition.OnCondition(_target, cond, label ?? "cond"));
                return _stateBuilder;
            }

            /// <summary>事件转换。</summary>
            public StateBuilder OnEvent(AiSignal evt)
            {
                _state.Transitions.Add(Transition.OnEvent(_target, evt));
                return _stateBuilder;
            }

            /// <summary>在本状态停留 seconds 秒后转换（读 runtime 的状态计时器）。</summary>
            public StateBuilder After(float seconds)
            {
                _state.Transitions.Add(Transition.OnCondition(
                    _target, c => AiRuntime.TimeInState(c) >= seconds, $"after {seconds}s"));
                return _stateBuilder;
            }
        }

        public sealed class GlobalBuilder
        {
            readonly BrainBuilder _owner;
            string _pendingTarget;
            internal GlobalBuilder(BrainBuilder owner) { _owner = owner; }

            public GlobalBuilder To(string target) { _pendingTarget = target; return this; }

            public GlobalBuilder OnEvent(AiSignal evt)
            {
                _owner.AddGlobal(Transition.OnEvent(_pendingTarget, evt));
                return this;
            }

            public GlobalBuilder When(Func<IAiContext, bool> cond, string label = null)
            {
                _owner.AddGlobal(Transition.OnCondition(_pendingTarget, cond, label ?? "cond"));
                return this;
            }
        }
    }
}
```

> 注：`After()` 引用了 `AiRuntime.TimeInState(c)`（Task 5 定义的静态辅助，通过 context 取当前 runtime 的状态计时器）。若执行到本任务时 `AiRuntime` 尚未定义，先临时把 `After` 的实现体改为 `throw new NotImplementedException()` 以通过编译，Task 5 完成后回填（回填是同一函数体，非占位）。测试 `BrainBuilderTests` 不覆盖 `After`，不受影响。
> 
> **标签方案（C# 9 环境，Unity 2022.3）**：转换的可读标签走**显式可选字符串**（`When(cond, "SeesPlayer")`）。声明时建议给关键条件转换传标签，使 Mermaid 边 / trace 触发原因可读；不传则回退为 `"cond"`。**不使用 `[CallerArgumentExpression]`**（那是 C# 10 特性，本项目 Unity 2022.3 用 C# 9，编译器不会填充）。将来升级语言级别后可无痛切换为自动抓取。

- [ ] **Step 5: 运行测试确认通过**

Run: EditMode `BrainBuilderTests`
Expected: PASS（5 项）。若 `After` 临时抛异常，本测试不涉及，仍应全绿。

- [ ] **Step 6: 补落 `AiScript.cs`（Task 2 Step 6 暂缓的文件）并编译**

此时 `BrainBuilder`/`AiGraph` 已存在，创建/确认 `AiScript.cs`（内容见 Task 2 Step 6），编译应通过。

- [ ] **Step 7: 提交**

```bash
git add Assets/_Game/Scripts/AI/AiGraph.cs Assets/_Game/Scripts/AI/BrainBuilder.cs \
        Assets/_Game/Scripts/AI/AiScript.cs Assets/Tests/EditMode/AI/BrainBuilderTests.cs \
        Assets/_Game/Scripts/AI/*.meta Assets/Tests/EditMode/AI/*.meta
git commit -m "feat(ai): BrainGraph AiGraph + BrainBuilder(fluent, 条件源码标签, 目标校验)"
```

---

## Task 5: `AiRuntime` —— Tick、条件转换、IsControllable 让位门、状态计时器

**Files:**
- Create: `Assets/_Game/Scripts/AI/AiRuntime.cs`
- Create: `Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs`
- Create: `Assets/Tests/EditMode/AI/AiRuntimeTests.cs`

- [ ] **Step 1: 写测试替身 `FakeAiContext`**

`Assets/Tests/EditMode/AI/Fakes/FakeAiContext.cs`：

```csharp
using System.Collections.Generic;
using UnityEngine;
using BaseGames.AI;

namespace BaseGames.Tests.EditMode.AI
{
    public sealed class FakeSensor : ISensor
    {
        public bool Sees; public float LostForValue; public Vector2 Last;
        public bool SeesPlayer() => Sees;
        public bool InRange(float range) => Sees; // 简化：可见即在范围
        public bool LostFor(float seconds) => LostForValue >= seconds;
        public Vector2 LastKnown => Last;
    }

    public sealed class FakeMover : IMover
    {
        public List<string> Calls = new List<string>();
        public void MoveTo(Vector2 t) => Calls.Add("MoveTo");
        public void FacePlayer() => Calls.Add("FacePlayer");
        public void Stop() => Calls.Add("Stop");
        public void WalkRandom() => Calls.Add("WalkRandom");
        public void LookAround() => Calls.Add("LookAround");
    }

    public sealed class FakeCombat : ICombatant
    {
        public string Running; public List<string> Used = new List<string>();
        public bool UseAbility(string id) { Used.Add(id); Running = id; return true; }
        public bool IsAbilityRunning(string id = null) => id == null ? Running != null : Running == id;
        public bool NoAbilityRunning => Running == null;
        public bool CanUseAbility(string id) => true;
    }

    public sealed class FakeVitals : IActorVitals
    {
        public bool Alive = true; public bool Controllable = true; public float Hp = 1f;
        public bool IsAlive => Alive;
        public bool IsControllable => Controllable;
        public float HpPercent => Hp;
        public bool HpBelow(float ratio) => Hp < ratio;
    }

    public sealed class FakeAiContext : IAiContext
    {
        public FakeSensor S = new FakeSensor();
        public FakeMover M = new FakeMover();
        public FakeCombat C = new FakeCombat();
        public FakeVitals V = new FakeVitals();
        public Blackboard BB = new Blackboard();
        public ISensor Sensor => S;
        public IMover Mover => M;
        public ICombatant Combat => C;
        public IActorVitals Vitals => V;
        public Blackboard Blackboard => BB;
    }
}
```

- [ ] **Step 2: 写失败测试 —— Tick、条件转换、门、计时器**

`Assets/Tests/EditMode/AI/AiRuntimeTests.cs`：

```csharp
using NUnit.Framework;
using BaseGames.AI;

namespace BaseGames.Tests.EditMode.AI
{
    public class AiRuntimeTests
    {
        static AiGraph Graph()
        {
            var b = new BrainBuilder();
            b.Entry("Patrol");
            b.Global().To("Dead").OnEvent(AiSignal.Died);
            b.State("Patrol")
                .Tick(c => c.Mover.WalkRandom())
                .To("Chase").When(c => c.Sensor.SeesPlayer(), "SeesPlayer");
            b.State("Chase")
                .OnEnter(c => c.Mover.FacePlayer())
                .Tick(c => c.Mover.MoveTo(c.Sensor.LastKnown))
                .To("Search").When(c => c.Sensor.LostFor(2f), "LostFor(2s)");
            b.State("Search")
                .To("Patrol").After(3f);
            b.State("Dead");
            return b.Build();
        }

        [Test]
        public void StartsAtEntry()
        {
            var rt = new AiRuntime(Graph(), new FakeAiContext());
            Assert.AreEqual("Patrol", rt.CurrentStateName);
        }

        [Test]
        public void Tick_RunsCurrentStateTickAction()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            rt.Tick(0.1f);
            CollectionAssert.Contains(ctx.M.Calls, "WalkRandom");
        }

        [Test]
        public void ConditionTransition_FiresAndRunsEnterExit()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            ctx.S.Sees = true;
            rt.Tick(0.1f);
            Assert.AreEqual("Chase", rt.CurrentStateName);
            CollectionAssert.Contains(ctx.M.Calls, "FacePlayer"); // Chase.OnEnter
        }

        [Test]
        public void Gate_SuspendsDecisionWhenNotControllable()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            ctx.S.Sees = true;
            ctx.V.Controllable = false;   // 受击中
            rt.Tick(0.1f);
            Assert.AreEqual("Patrol", rt.CurrentStateName); // 未转换
            Assert.IsTrue(rt.IsSuspended);
            CollectionAssert.DoesNotContain(ctx.M.Calls, "WalkRandom"); // Tick 也不跑
        }

        [Test]
        public void Gate_ResumesAndReevaluatesWhenControllable()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            ctx.S.Sees = true;
            ctx.V.Controllable = false;
            rt.Tick(0.1f);
            ctx.V.Controllable = true;    // 恢复
            rt.Tick(0.1f);
            Assert.AreEqual("Chase", rt.CurrentStateName);
        }

        [Test]
        public void After_UsesStateTimer()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            ctx.S.Sees = true; rt.Tick(0.1f);                 // -> Chase
            ctx.S.Sees = false; ctx.S.LostForValue = 5f; rt.Tick(0.1f); // -> Search
            Assert.AreEqual("Search", rt.CurrentStateName);
            rt.Tick(1f); rt.Tick(1f);
            Assert.AreEqual("Search", rt.CurrentStateName);   // 未满 3s
            rt.Tick(1.5f);
            Assert.AreEqual("Patrol", rt.CurrentStateName);   // 累计 >3s
        }
    }
}
```

- [ ] **Step 3: 运行测试确认失败**

Run: EditMode `AiRuntimeTests`
Expected: 编译失败 —— `AiRuntime` 未定义。

- [ ] **Step 4: 实现 `AiRuntime`（本任务先实现条件转换 + 门 + 计时器；事件转换在 Task 6 追加）**

`Assets/_Game/Scripts/AI/AiRuntime.cs`：

```csharp
using System.Collections.Generic;

namespace BaseGames.AI
{
    /// <summary>
    /// 每敌人实例一份的轻量执行器（spec §3.2）。持有当前状态、状态计时器、trace。
    /// 共享的 AiGraph 不持有任何实例态。
    /// </summary>
    public sealed class AiRuntime
    {
        readonly AiGraph _graph;
        readonly IAiContext _ctx;
        AiState _current;
        float _timeInState;

        readonly Queue<AiSignal> _pending = new Queue<AiSignal>();
        readonly List<TransitionRecord> _trace = new List<TransitionRecord>();
        const int TraceCap = 16;

        public AiRuntime(AiGraph graph, IAiContext ctx)
        {
            _graph = graph;
            _ctx = ctx;
            EnterInitial();
        }

        public string CurrentStateName => _current.Name;
        public bool IsSuspended { get; private set; }
        public IReadOnlyList<TransitionRecord> Trace => _trace;
        public float TimeInStateValue => _timeInState;

        void EnterInitial()
        {
            _current = _graph.GetState(_graph.EntryState);
            _timeInState = 0f;
            _current.OnEnter?.Invoke(_ctx);
        }

        /// <summary>供 BrainBuilder.After() 通过 context 读取当前 runtime 的状态计时器。</summary>
        static readonly System.Runtime.CompilerServices.ConditionalWeakTable<IAiContext, AiRuntime> _byContext
            = new System.Runtime.CompilerServices.ConditionalWeakTable<IAiContext, AiRuntime>();
        internal static float TimeInState(IAiContext ctx)
            => _byContext.TryGetValue(ctx, out var rt) ? rt._timeInState : 0f;

        public void Tick(float dt)
        {
            _byContext.Remove(_ctx);
            _byContext.Add(_ctx, this);

            // IsControllable 让位门（spec §3.6）：受击/硬直/击飞时挂起，不推进决策也不跑 Tick。
            if (!_ctx.Vitals.IsControllable)
            {
                IsSuspended = true;
                return;
            }
            IsSuspended = false;

            _timeInState += dt;

            if (TryTransition())
                return; // 本帧发生转换，新状态下一帧再 Tick

            _current.OnTick?.Invoke(_ctx, dt);
        }

        bool TryTransition()
        {
            // 全局/父层转换优先（本任务只评估条件型；事件型在 Task 6 处理）
            foreach (var t in _graph.GlobalTransitions)
                if (!t.IsEvent && t.Condition(_ctx))
                    return Switch(t);

            foreach (var t in _current.Transitions)
                if (!t.IsEvent && t.Condition(_ctx))
                    return Switch(t);

            return false;
        }

        bool Switch(Transition t)
        {
            var from = _current.Name;
            _current.OnExit?.Invoke(_ctx);
            _current = _graph.GetState(t.Target);
            _timeInState = 0f;
            RecordTrace(new TransitionRecord(from, t.Target, t.Label));
            _current.OnEnter?.Invoke(_ctx);
            return true;
        }

        void RecordTrace(TransitionRecord r)
        {
            _trace.Add(r);
            if (_trace.Count > TraceCap) _trace.RemoveAt(0);
        }

        /// <summary>对象池复用时重置到初始态，清空所有实例态（spec §3.8）。</summary>
        public void Reset()
        {
            _pending.Clear();
            _trace.Clear();
            _ctx.Blackboard.Clear();
            IsSuspended = false;
            EnterInitial();
        }
    }
}
```

- [ ] **Step 5: 回填 `BrainBuilder.After`（若 Task 4 曾临时抛异常）**

确认 `BrainBuilder.TransitionBuilder.After` 的实现体为（Task 4 Step 4 所示的正式版）：
```csharp
_state.Transitions.Add(Transition.OnCondition(
    _target, c => AiRuntime.TimeInState(c) >= seconds, $"after {seconds}s"));
```

- [ ] **Step 6: 运行测试确认通过**

Run: EditMode `AiRuntimeTests`
Expected: PASS（6 项：入口、Tick、条件转换、门挂起、门恢复重评估、After 计时器）。

- [ ] **Step 7: 提交**

```bash
git add Assets/_Game/Scripts/AI/AiRuntime.cs Assets/_Game/Scripts/AI/BrainBuilder.cs \
        Assets/Tests/EditMode/AI/Fakes Assets/Tests/EditMode/AI/AiRuntimeTests.cs \
        Assets/_Game/Scripts/AI/*.meta Assets/Tests/EditMode/AI/*.meta Assets/Tests/EditMode/AI/Fakes/*.meta
git commit -m "feat(ai): AiRuntime 条件转换+IsControllable让位门+状态计时器+trace+Reset"
```

---

## Task 6: `AiRuntime` 事件转换 + trace 触发原因 + 池复用测试

**Files:**
- Modify: `Assets/_Game/Scripts/AI/AiRuntime.cs`
- Modify: `Assets/Tests/EditMode/AI/AiRuntimeTests.cs`

- [ ] **Step 1: 追加失败测试 —— 事件转换（push）、优先级、Reset**

在 `AiRuntimeTests` 类中追加：

```csharp
        [Test]
        public void EventTransition_FiresOnSignal_EvenBeforeTick()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            rt.Send(AiSignal.Died);
            rt.Tick(0.1f);
            Assert.AreEqual("Dead", rt.CurrentStateName);
        }

        [Test]
        public void EventTransition_FiresEvenWhenNotControllable()
        {
            // 死亡等事件不受让位门限制（门只挡决策推进/条件评估，不挡事件）
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            ctx.V.Controllable = false;
            rt.Send(AiSignal.Died);
            rt.Tick(0.1f);
            Assert.AreEqual("Dead", rt.CurrentStateName);
        }

        [Test]
        public void Trace_RecordsTriggerReason()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            ctx.S.Sees = true;
            rt.Tick(0.1f);
            Assert.AreEqual(1, rt.Trace.Count);
            Assert.AreEqual("Patrol", rt.Trace[0].From);
            Assert.AreEqual("Chase", rt.Trace[0].To);
            StringAssert.Contains("SeesPlayer", rt.Trace[0].Trigger);
        }

        [Test]
        public void Reset_ReturnsToEntryAndClearsState()
        {
            var ctx = new FakeAiContext();
            var rt = new AiRuntime(Graph(), ctx);
            ctx.S.Sees = true; rt.Tick(0.1f); // -> Chase
            ctx.BB.Set("scratch", 42);
            rt.Reset();
            Assert.AreEqual("Patrol", rt.CurrentStateName);
            Assert.IsEmpty(rt.Trace);
            Assert.IsFalse(ctx.BB.Has("scratch"));
        }
```

- [ ] **Step 2: 运行确认新测试失败**

Run: EditMode `AiRuntimeTests`
Expected: `EventTransition_*` FAIL（`Send` 未实现事件处理），`Reset_*`/`Trace_*` 可能已过（视 Task 5 实现）；至少事件相关 2 项失败。

- [ ] **Step 3: 实现事件处理**

在 `AiRuntime.cs` 追加 `Send` 并在 `Tick` 开头处理事件队列（事件不受让位门限制）。修改如下：

在字段区已有 `_pending`。新增方法：

```csharp
        /// <summary>推送一个信号，用于事件驱动转换（push, spec §3.3/§4.1）。</summary>
        public void Send(AiSignal signal) => _pending.Enqueue(signal);
```

将 `Tick` 改为先排空事件（不受门限制），再走门 + 条件：

```csharp
        public void Tick(float dt)
        {
            _byContext.Remove(_ctx);
            _byContext.Add(_ctx, this);

            // 1) 事件转换：push，最高优先，且不受 IsControllable 门限制
            while (_pending.Count > 0)
            {
                var sig = _pending.Dequeue();
                if (TryEventTransition(sig))
                    return; // 事件触发转换后本帧结束
            }

            // 2) IsControllable 让位门
            if (!_ctx.Vitals.IsControllable)
            {
                IsSuspended = true;
                return;
            }
            IsSuspended = false;

            _timeInState += dt;

            // 3) 条件转换
            if (TryTransition())
                return;

            _current.OnTick?.Invoke(_ctx, dt);
        }

        bool TryEventTransition(AiSignal sig)
        {
            foreach (var t in _graph.GlobalTransitions)
                if (t.IsEvent && t.Event.Value == sig)
                    return Switch(t);
            foreach (var t in _current.Transitions)
                if (t.IsEvent && t.Event.Value == sig)
                    return Switch(t);
            return false;
        }
```

> `Reset()` 中已有 `_pending.Clear()`（Task 5），无需改动。

- [ ] **Step 4: 运行测试确认全通过**

Run: EditMode `AiRuntimeTests`
Expected: PASS（Task 5 的 6 项 + 本任务 4 项 = 10 项全绿）。

- [ ] **Step 5: 提交**

```bash
git add Assets/_Game/Scripts/AI/AiRuntime.cs Assets/Tests/EditMode/AI/AiRuntimeTests.cs
git commit -m "feat(ai): AiRuntime 事件转换(push,不受门限制)+trace触发原因+池复用重置测试"
```

---

## Task 7: 阶段自检与文档回链

**Files:**
- Modify: `Docs/superpowers/specs/2026-07-03-enemy-ai-framework-design.md`（在文末追加"实现进度"回链，可选）

- [ ] **Step 1: 全量跑核心测试**

Run: EditMode 全部 `BaseGames.Tests.EditMode.AI.*`
Expected: `BlackboardTests`(5) + `BrainBuilderTests`(5) + `AiRuntimeTests`(10) 全 PASS。

- [ ] **Step 2: 编译零错误确认**

Run: `unity_get_compilation_errors`
Expected: 无错误、无警告（除已知的 CallerArgumentExpression 兼容处理）。

- [ ] **Step 3: 验证 flyweight 共享（手动断言脚本，可选）**

用 MCP `unity_execute_code` 执行：构造一个测试 `AiScript` 子类，调用两次 `GetOrBuildGraph()`，断言返回**同一引用**（`ReferenceEquals == true`）→ 证明每类型只建一份、实例共享。

- [ ] **Step 4: 提交阶段收尾**

```bash
git add -A
git commit -m "chore(ai): BrainGraph 第1阶段核心运行时收尾——全测试通过"
```

---

## 后续阶段路线图（各自展开为独立计划）

本阶段交付"可独立单测、可工作的状态机核心"。后续阶段依赖它，届时各写一份计划：

- **第 2 阶段：能力编排 sugar + AiScheduler**
  - `AbilitySequence` + `Seq.Select/Sequence` fluent（选招→Execute→while(IsRunning)等待→重评估，spec §3.4）。
  - 嵌套子状态机（层级 HFSM，供 Boss 阶段），`AiScheduler` LOD 错峰调度（spec §3.7）。
- **第 3 阶段：能力接口完整成员 + 适配器 + 组件 + 信号接线**
  - 按 spec §4 补齐 4 接口全部方法；`SensorAdapter/MoverAdapter/CombatantAdapter/VitalsAdapter`（`BaseGames.Enemies.AI` asmdef，去 Opsive 引用、加 `BaseGames.AI`）。
  - `EnemyAiBrain : MonoBehaviour` + `AiDefinitionRegistry`（反射收集 `[AiDefinition]`，`RuntimeInitializeOnLoadMethod` 重置，遵关闭域重载约束）。
  - `EnemyBase` raise `AiSignal`（受击/弹反/死亡/发现玩家/能力结束/阶段变更），移除 `#if GRAPH_DESIGNER` BT 集成；`IPoolable` 回收回调调 `AiRuntime.Reset()`。
- **第 4 阶段：交付面**
  - `MermaidExporter`（`AiGraph→stateDiagram-v2`，菜单 + MCP 静态入口，spec §6.1）。
  - `AiDebugService`（ServiceLocator 注册，`ListAgents/GetAgent/ExportMermaid/SetPaused/Step/ForceState`，spec §6.3）。
  - `Editor/BrainGraphDebuggerWindow`（实时高亮 + trace + 黑板 + 能力 + 门状态，spec §6.2）。
- **第 5 阶段：脚手架接线 + 试点 + 退役 BD**
  - 扩展 `SceneObjectPlacerTool`/`CharacterWizardWindow` 自动挂 `EnemyAiBrain` + 绑定定义/参数 SO（消除 `SceneObjectPlacerTool.cs:354/524` 手动 TODO）。
  - 试点 `E001_CaoZhi`（PlayMode 行为验收）+ `ChaoFengBoss`（多阶段/加权技能/弱点窗口）。
  - parity 后批量迁移，删除 49 个 `BD_*`、`EnemyBase` BT 集成、`com.opsive.*` 包（spec §8）。

---

## 自检记录（writing-plans self-review）

- **Spec 覆盖**：本阶段对应 spec §3.1(共享图)/§3.2(轻量运行时)/§3.3(条件+事件转换)/§3.6(IsControllable门)/§3.8(池复用重置、无实例捕获约束经 IAiContext 落实)。§3.4/§3.5黑板已建/§3.7/§4完整/§6/§7/§8 明确列入后续阶段路线图，无遗漏。
- **占位扫描**：无 TBD/TODO 占位；`After` 的临时抛异常 + Task 5 回填是明确的两步实现（非占位），已注明回填内容与顺序。
- **类型一致性**：`IAiContext.Sensor/Mover/Combat/Vitals/Blackboard`、`AiRuntime.CurrentStateName/IsSuspended/Trace/Send/Reset/Tick`、`Transition.OnCondition/OnEvent/IsEvent/Label`、`BrainBuilder.Entry/State/Global/Build`、`StateBuilder.OnEnter/Tick/OnExit/To`、`TransitionBuilder.When/OnEvent/After` 跨任务命名一致。
- **环境适配**：Unity 2022.3 = C# 9。转换标签走显式可选字符串（不用 C# 10 的 CallerArgumentExpression）；`After` 用状态计时器、事件转换用 `AiSignal`，均 C# 9 兼容。