feat(ai): BrainGraph AiGraph + BrainBuilder(fluent, 显式标签, 目标校验)

2026-07-03 14:04:51 +08:00
parent 3d6cef1f41
commit 6f9fa8c4b8
8 changed files with 301 additions and 0 deletions
@@ -0,0 +1,122 @@
+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}' 未声明。");
+
+            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);
+        }
+
+        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"。
+            /// </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 的状态计时器）。Task 5 回填实现。</summary>
+            public StateBuilder After(float seconds)
+            {
+                // 依赖 AiRuntime.TimeInState（Task 5 定义）。本任务先临时抛异常以通过编译，Task 5 回填正式实现。
+                throw new NotImplementedException("After 将在 Task 5 回填（依赖 AiRuntime 状态计时器）。");
+            }
+        }
+
+        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;
+            }
+        }
+    }
+}