chartflow 0.1__py3-none-any.whl

chartflow/fsm/stage.py

@@ -0,0 +1,2079 @@
+from __future__ import annotations
+"""
+qfsm Stage Module - Base class for finite state machines
+
+This module provides the Stage base class with automatic state discovery,
+behavior tree support, and recursive state execution.
+"""
+
+from colorama import init as colorama_init, Fore, Style
+from PyQt6.QtWidgets import QApplication
+
+
+
+from typing import Any, ClassVar, Self
+from collections.abc import Callable
+
+from chartflow.fsm.meta import StageMachineMeta
+from chartflow.fsm.scheduler import Scheduler
+from chartflow.fsm.utils import EventSystem, GetES
+from chartflow.fsm import stdio as std
+
+import inspect
+import ast
+
+# Color support
+try:
+    colorama_init(autoreset=True)
+    _COLOR_AVAILABLE = True
+except ImportError:
+    _COLOR_AVAILABLE = False
+    # Dummy color classes for when colorama is not available
+    class _DummyColor:
+        def __getattr__(self, name: str) -> str:
+            return ''
+    Fore = _DummyColor()
+    Style = _DummyColor()
+
+# Module-level cache for runtime paramable check results
+# Key: id(method) -> bool
+_RUNTIME_PARAMABLE_CACHE = {}
+
+
+def _getMethodCacheKey(_method):
+    """
+    获取方法的缓存键。
+
+    对于 bound method，使用 (id(obj), func_name) 作为键
+    对于普通函数，使用 id(method) 作为键
+    """
+    # 尝试获取 __func__ 属性（bound method 有这个属性）
+    if hasattr(_method, '__func__'):
+        # 这是一个 bound method
+        # 获取绑定的对象
+        if hasattr(_method, '__self__'):
+            return (id(_method.__self__), id(_method.__func__))
+    # 普通函数或其他可调用对象
+    return id(_method)
+
+
+def _checkMethodAcceptsParam(_method):
+    """
+    检查方法是否接受至少一个参数（可以接受inst参数）。
+
+    使用inspect检查方法的参数，如果方法接受以下情况之一，返回True：
+    - 至少一个位置参数（除了self）
+    - *args
+    - **kwargs
+
+    结果会被缓存到模块级别的 _RUNTIME_PARAMABLE_CACHE 中。
+    同时也会尝试设置到方法的 __runtime_paramable__ 属性（如果可能）。
+
+    优先级：
+    1. 方法上的 __runtime_paramable__ 属性（如果存在）
+    2. 模块级缓存
+    3. 重新计算
+
+    Args:
+        _method: 要检查的方法
+
+    Returns:
+        bool: 如果方法可以接受inst参数则返回True
+    """
+    # 首先检查是否已经有 __runtime_paramable__ 属性
+    # 这允许用户或测试覆盖检查结果
+    if hasattr(_method, '__runtime_paramable__'):
+        return _method.__runtime_paramable__
+
+    # 获取缓存键
+    _cacheKey = _getMethodCacheKey(_method)
+
+    # 检查模块级缓存
+    if _cacheKey in _RUNTIME_PARAMABLE_CACHE:
+        return _RUNTIME_PARAMABLE_CACHE[_cacheKey]
+
+    try:
+        _sig = inspect.signature(_method)
+        _params = list(_sig.parameters.values())
+
+        # 判断是否是 bound method（有 __self__ 属性）
+        _isBoundMethod = hasattr(_method, '__self__')
+
+        # 参数处理逻辑：
+        # - 对于 bound method：签名中已经不包含 self，直接检查所有参数
+        # - 对于普通函数：跳过第一个参数（self/cls）
+        if not _isBoundMethod and _params:
+            # 普通函数，跳过第一个参数（self/cls）
+            _params = _params[1:]
+        # 对于 bound method，不需要跳过任何参数，因为签名已经不包含 self
+
+        # 检查是否有可接受inst的参数
+        _canAccept = False
+        for _p in _params:
+            # 检查是否是VAR_POSITIONAL (*args)
+            if _p.kind == inspect.Parameter.VAR_POSITIONAL:
+                _canAccept = True
+                break
+            # 检查是否是VAR_KEYWORD (**kwargs)
+            if _p.kind == inspect.Parameter.VAR_KEYWORD:
+                _canAccept = True
+                break
+            # 检查是否是POSITIONAL_OR_KEYWORD 或 KEYWORD_ONLY
+            if _p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY):
+                _canAccept = True
+                break
+            # 检查是否是POSITIONAL_ONLY
+            if _p.kind == inspect.Parameter.POSITIONAL_ONLY:
+                _canAccept = True
+                break
+
+        # 尝试设置 __runtime_paramable__ 属性（如果可能）
+        try:
+            setattr(_method, '__runtime_paramable__', _canAccept)
+        except (AttributeError, TypeError):
+            # 对于某些无法设置属性的对象，忽略
+            pass
+
+        # 缓存到模块级缓存
+        _RUNTIME_PARAMABLE_CACHE[_cacheKey] = _canAccept
+        return _canAccept
+
+    except (ValueError, TypeError):
+        # 如果无法获取签名，默认假设可以接受参数
+        _RUNTIME_PARAMABLE_CACHE[_cacheKey] = True
+        return True
+
+
+def _invokeStateMethod(_method, _inst):
+    """
+    调用状态方法，根据方法签名自动决定是否传递inst参数。
+
+    注意：_method 应该是 bound method（从实例上获取的方法），
+    这样 self 已经自动绑定，我们只需要决定是否传递 inst。
+
+    Args:
+        _method: 状态方法（bound method）
+        _inst: 要传递的实例
+
+    Returns:
+        方法的返回值
+    """
+    if _checkMethodAcceptsParam(_method):
+        return _method(_inst)
+    else:
+        return _method()
+
+
+class _NamedNode:
+    """
+    Base class for named nodes in the FSM hierarchy.
+
+    Provides basic naming and identification functionality.
+    """
+
+    NAME: ClassVar[str] = ""
+
+    def __init__(self) -> None:
+        self._uid: int = 0
+        self._name: str = self.NAME
+        self.__parent: _NamedNode | None = None
+        self.__children: list[_NamedNode] = []
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self._name})"
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, self._uid))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _NamedNode):
+            return NotImplemented
+        return self._uid == other._uid and self.__class__ == other.__class__
+
+    @property
+    def parent(self) -> _NamedNode | None:
+        """Get parent node."""
+        return self.__parent
+
+    @property
+    def _children(self) -> list[_NamedNode]:
+        """Get child nodes."""
+        return self.__children
+
+    def _add_child(self, child: _NamedNode) -> None:
+        """Add a child node."""
+        if child.__parent is not None:
+            child.__parent._remove_child(child)
+        self.__children.append(child)
+        child.__parent = self
+
+    def _remove_child(self, child: _NamedNode) -> None:
+        """Remove a child node."""
+        if child in self.__children:
+            self.__children.remove(child)
+            child.__parent = None
+
+class BlackBoard(object):
+    """Data container that can be bound to a Stage instance.
+
+    Users can freely add any attributes to store shared data.
+    """
+    pass
+
+class Stage(_NamedNode, metaclass=StageMachineMeta):
+    """
+    Base class for finite state machines with automatic state discovery.
+    
+    Features:
+    - Automatic state discovery via StageMachineMeta
+    - Recursive state execution with configurable limit
+    - Behavior tree support (sequence, selector, parallel)
+    - Event system integration
+    - Lifecycle hooks (onLoading, onChanged)
+    
+    Class Attributes:
+        NAME: The display name for this stage type
+        LOG: Whether to log state transitions
+        LIMIT: Maximum recursive calls per tick (default: 24)
+    
+    Example:
+        class MyStage(Stage):
+            NAME = "MyStage"
+            
+            def idle(self):
+                if self.should_work:
+                    return "working"
+            
+            def working(self):
+                if self.work_done:
+                    return "idle"
+    """
+    
+    # Class attributes
+    NAME: ClassVar[str] = "Stage"
+    LOG: ClassVar[bool] = True
+    LIMIT: ClassVar[int] = 24
+    
+    # Class-level state tracking (populated by metaclass)
+    __states__: ClassVar[list[str]] = []
+    __recursive__: ClassVar[set[str]] = set()
+    __listens__: ClassVar[dict[str, list[tuple[str, tuple[str, ...]]]]] = {}
+    __behaviors__: ClassVar[dict[str, dict[str, Any]]] = {}
+    IGNORES: ClassVar[list[str]] = []
+
+    def __init__(self, inst: Any = None) -> None:
+        """
+        Initialize the Stage.
+        
+        Args:
+            inst: The bound instance (e.g., game entity, component owner)
+        """
+        super().__init__()
+        
+        # Instance attributes
+        self._inst: Any = inst or BlackBoard()
+        self._current: str | None = None
+        self._recursive_left: int = self.LIMIT
+        self._states_length: int = len(self.__states__)
+        self._uid: int = StageMachineMeta.requireId(self.NAME)
+        self._name: str = f"{self.NAME}{self._uid}"
+        
+        # Event system
+        self._eda: EventSystem = GetES()
+        
+        # Behavior tree context
+        self._bhead: str | None = None
+        self._bhcontext: dict[str, Any] = {}
+        
+        # Initialize to first state if available
+        if self.__states__:
+            self._current = self.__states__[0]
+
+        self.__login_event__()
+        self.onLoading(self._inst)
+
+    def __login_event__(self):
+        for attr in dir(self):
+            if attr.startswith("_") or attr in StageMachineMeta.IGNORES:
+                continue
+            val = getattr(self, attr)
+            if callable(val) and hasattr(val, "_listen_event"):
+                if not isinstance(val._listen_event, str):
+                    raise TypeError(f"[Inner System Load]: method '{attr}'._listen_event get type '{type(val._listen_event)}', which ecpected str.")
+                self.listenFor(val._listen_event, val)
+
+    def __del__(self):
+        for attr in dir(self):
+            if attr.startswith("_") or attr in StageMachineMeta.IGNORES:
+                continue
+            val = getattr(self, attr)
+            if callable(val) and hasattr(val, "_listen_event"):
+                if not isinstance(val._listen_event, str):
+                    raise TypeError(
+                        f"[Inner System Load]: method '{attr}'._listen_event get type '{type(val._listen_event)}', which ecpected str.")
+                self.cancelListen(val._listen_event, val)
+
+    @property
+    def uid(self) -> int:
+        """Get unique identifier."""
+        return self._uid
+
+    @property
+    def name(self) -> str:
+        """Get full name with uid."""
+        return self._name
+
+    @property
+    def current(self) -> str | None:
+        """Get current state name."""
+        return self._current
+
+    @current.setter
+    def current(self, value: str | None) -> None:
+        """Set current state with validation."""
+        if value is not None and value not in self.__states__:
+            raise ValueError(f"Invalid state: {value}")
+        self._current = value
+
+    def onLoading(self, inst: Any) -> None:
+        """
+        Lifecycle hook called after initialization.
+
+        Override this to perform setup after the stage is loaded.
+
+        Args:
+            inst: The bound instance
+        """
+        pass
+
+    def onChanged(self, src: str | None, dst: str | None, inst: Any) -> None:
+        """
+        Lifecycle hook called when state changes.
+
+        Override this to react to state transitions.
+
+        Args:
+            src: Source state name (None if initial)
+            dst: Destination state name (None if terminal)
+            inst: The bound instance
+        """
+        pass
+    
+    def handleStage(self, log: bool = True) -> str | None:
+        """
+        Execute the current state and handle transitions.
+        
+        This is the main execution method that:
+        1. Calls the current state method
+        2. Handles return values (state transitions)
+        3. Supports recursive state execution
+        4. Handles behavior tree composites
+        
+        Args:
+            log: Whether to log state transitions
+            
+        Returns:
+            The final state after execution, or None if no states
+            
+        Example:
+            >>> stage = MyStage()
+            >>> stage.handleStage()  # Execute one tick
+        """
+        if not self._current or self._states_length == 0:
+            return None
+        
+        # Reset recursive counter at start of tick
+        self._recursive_left = self.LIMIT
+        
+        # Execute current state (with recursion support)
+        result = self._execute_state(self._current, log)
+        
+        return result
+    
+    def _execute_state(self, state_name: str, log: bool, pre_result: Any = None, send_enter: bool = True) -> str | None:
+        """
+        Execute a single state and handle its result.
+        This is the entry point for ALL state execution.
+
+        Args:
+            state_name: Name of state to execute
+            log: Whether to log transitions
+            pre_result: Optional pre-computed result (avoids double execution)
+            send_enter: Whether to send 'enter' event (default True)
+
+        Returns:
+            Final state after execution
+        """
+        if self._recursive_left <= 0:
+            # Limit reached, stop recursion
+            return state_name
+
+        self._recursive_left -= 1
+
+        # Check if we have behavior tree context that needs to be resumed
+        # This happens when a sequence/selector/parallel paused and _current was set to a child
+        if self._bhead is not None and state_name != self._bhead and not hasattr(self, '_resuming_behavior'):
+            # We have active behavior tree context and current state is not the root
+            # Check if current state is a child of the behavior tree
+            head_behavior = self.__behaviors__.get(self._bhead)
+            if head_behavior and state_name in head_behavior.get('children', []):
+                # Current state is a child of the active behavior tree
+                # Resume behavior tree execution from the root
+                # Set flag to prevent recursive resuming
+                self._resuming_behavior = True
+                try:
+                    result = self._execute_state(self._bhead, log, pre_result=None, send_enter=False)
+                finally:
+                    if hasattr(self, '_resuming_behavior'):
+                        delattr(self, '_resuming_behavior')
+                return result
+
+        # Get the state method
+        state_method = getattr(self, state_name, None)
+        if state_method is None or not callable(state_method):
+            return state_name
+
+        # Check if this is a behavior tree composite
+        behavior_info = self.__behaviors__.get(state_name)
+        if behavior_info:
+            # Behavior tree composite - let it handle execution
+            # It will eventually call back to _execute_state for child states
+            behavior_result = self._handle_behavior(state_name, behavior_info, log)
+            # Handle the result through _handle_result to ensure proper state transitions
+            # But only if it's a string (state transition) and not a special behavior result
+            if isinstance(behavior_result, str):
+                return self._handle_result(state_name, behavior_result, log)
+            # 行为树完成（True/False），触发 behavior_completed 事件
+            if behavior_result is True or behavior_result is False:
+                self._trigger_behavior_completed_if_needed()
+            return behavior_result
+
+        # Send 'enter' event before executing the state (if requested)
+        # This is the ONLY place where 'enter' event is triggered for regular states
+        if send_enter:
+            self.pushEvent("enter", {
+                "inst": self,
+                "state": state_name
+            })
+
+        # Use pre-computed result if provided, otherwise execute the state method
+        try:
+            if pre_result is not None:
+                result = pre_result
+            else:
+                result = _invokeStateMethod(state_method, self._inst)
+        except Exception as e:
+            # Log error but don't crash
+            if log and self.LOG:
+                print(f"[{self._name}] Error in state '{state_name}': {e}")
+            return state_name
+
+        # Handle result - this may call _transition_to for state changes
+        handled_result = self._handle_result(state_name, result, log)
+
+        # For behavior tree children: preserve None (RUN) semantics
+        # _handle_result converts None to state_name, but we need None for RUN
+        if self._bhead is not None and result is None and handled_result == state_name:
+            return None
+
+        return handled_result
+
+    def _get_state_result(self, state_name: str) -> Any:
+        """
+        Execute a state method and return its raw result (for behavior tree logic).
+
+        Unlike _execute_state which returns the handled result (next state name),
+        this method returns the actual return value from the state method.
+
+        Args:
+            state_name: Name of state to execute
+
+        Returns:
+            Raw return value from the state method
+        """
+        state_method = getattr(self, state_name, None)
+        if state_method is None or not callable(state_method):
+            return None
+
+        try:
+            return _invokeStateMethod(state_method, self._inst)
+        except Exception:
+            return None
+
+    def _handle_result(
+        self,
+        state_name: str,
+        result: Any,
+        log: bool
+    ) -> str | None:
+        """
+        Handle the return value from a state method.
+        ALL state transitions go through _transition_to.
+
+        Return value meanings:
+        - str: Transition to named state (calls _transition_to)
+        - True/None: Success, stay in current state
+        - False: Failure (for behavior trees)
+
+        Args:
+            state_name: Current state name
+            result: Return value from state method
+            log: Whether to log
+
+        Returns:
+            Final state after handling result
+        """
+        # String result = state transition - use _transition_to
+        if isinstance(result, str):
+            if result in self.__states__ or result in self.__behaviors__:
+                # Check if transition was already handled by behavior tree BREAK
+                # If suppress flag is set, the transition already happened in _execute_sequence/_execute_selector/_execute_parallel
+                if getattr(self, "_suppress_changed", False):
+                    # Transition already handled, just return the result
+                    # Clear the flag since we're consuming it
+                    delattr(self, "_suppress_changed")
+                    # But if target is recursive state, we need to execute it
+                    if result in self.__recursive__ and self._recursive_left > 0:
+                        return self._execute_state(result, log)
+                    return result
+
+                # Skip if target state is the same as current state AND state is not recursive
+                # This prevents duplicate events when behavior tree completes and returns parent name
+                # But allows recursive states to re-execute themselves
+                if result == state_name and state_name not in self.__recursive__:
+                    return state_name
+
+                # Transition to new state - _transition_to handles changed event
+                transitioned = self._transition_to(result, state_name, log, result=result)
+
+                # Only execute new state if it's marked as recursive
+                if transitioned and transitioned in self.__recursive__ and self._recursive_left > 0:
+                    return self._execute_state(transitioned, log)
+
+                return transitioned
+            else:
+                # Unknown state, log warning
+                if log and self.LOG:
+                    print(f"[{self._name}] Unknown state: {result}")
+                return state_name
+
+        # None or True = success, stay in state
+        if result is None or result is True:
+            # Check if recursive state should continue (recursive execution, not transition)
+            if state_name in self.__recursive__ and self._recursive_left > 0:
+                return self._execute_state(state_name, log)
+
+            # No behavior tree context: trigger changed event even when staying in same state
+            # This ensures consistency - ALL state execution goes through _transition_to
+            if self._bhead is None:
+                return self._transition_to(state_name, state_name, log, event_type="-", result=result)
+
+            return state_name
+
+        # False = failure (for behavior trees)
+        if result is False:
+            return False  # type: ignore[return-value]
+
+        # Unknown result type, stay in current state
+        return state_name
+    
+    def _handle_behavior(
+        self,
+        state_name: str,
+        behavior_info: dict[str, Any],
+        log: bool
+    ) -> str | None:
+        """
+        Handle behavior tree composite execution with RUN support.
+
+        Supports:
+        - sequence: Execute all children in order, fail if any fails
+        - selector: Execute children until one succeeds
+        - parallel: Execute all children, succeed if any succeeds
+
+        RUN (None) semantics:
+        - Child returns None: pause execution, stay in current state, resume next tick
+        - Uses _bhead and _bhcontext to track execution state across ticks
+
+        Args:
+            state_name: Name of behavior state
+            behavior_info: Behavior configuration dict
+            log: Whether to log
+
+        Returns:
+            Result state, False for failure, or None for RUN
+        """
+        _children = behavior_info.get('children', [])
+        composite: str | None = behavior_info.get('composite')
+
+        # Normalize children to list (handle string case for simple behavior)
+        if isinstance(_children, str):
+            children: list[str] = [_children]
+        else:
+            children: list[str] = _children
+
+        if not children:
+            return state_name
+
+        # Check if resuming: state has context stored in _bhcontext
+        is_resuming = state_name in self._bhcontext
+
+        # If resuming but sequence already completed (index >= len(children)), restart
+        if is_resuming and composite:
+            ctx = self._bhcontext.get(state_name)
+            if ctx:
+                idx = ctx.get("index", 0)
+                if idx >= len(children):
+                    # Sequence completed, restart from beginning
+                    is_resuming = False
+                    del self._bhcontext[state_name]
+                    # Keep the stack and history for context
+
+        # Calculate indent level based on behavior stack depth
+        # Root behavior: indent_level = 0 (0 spaces)
+        # Nested behaviors: indent_level = stack_depth (2, 4, 6... spaces)
+        context_stack: list[str] = self._bhcontext.get("stack", [])
+        if state_name == self._bhead:
+            # Root level behavior (first entry or resuming)
+            indent_level = 0
+        else:
+            # Nested behavior: indent based on stack depth
+            indent_level = len(context_stack)
+        indent = "  " * indent_level
+
+        bold_name = f"{Style.BRIGHT}{self._name}{Style.RESET_ALL}" if _COLOR_AVAILABLE else self._name
+        # Root behavior prints [name], nested behaviors don't
+        prefix = f"[{bold_name}] " if indent_level == 0 else ""
+
+        if self._bhead is None:
+            self._bhead = state_name
+        if not self._bhcontext:
+            self._bhcontext = {"stack": [], "history": []}
+
+        # Send 'enter' event for behavior tree composite node
+        # This allows visualizers to show the node before execution starts
+        if not is_resuming:
+            self.pushEvent("enter", {
+                "inst": self,
+                "state": state_name,
+                "type": "behavior_parent"
+            })
+            # Process Qt events immediately so visualizers update before potential long operations
+            try:
+                app = QApplication.instance()
+                if app:
+                    app.processEvents()
+            except ImportError:
+                pass
+
+        # Execute parent state's method body ONLY on first entry (not when resuming from RUN)
+        # When resuming, we skip parent and continue from where we left off
+        if not is_resuming:
+            state_method = getattr(self, state_name, None)
+            if state_method is not None and callable(state_method):
+                try:
+                    parent_result = state_method(self._inst)
+                except Exception as e:
+                    if log and self.LOG:
+                        print(f"[{self._name}] Error in behavior parent '{state_name}': {e}")
+                    parent_result = None
+
+                # Handle parent result
+                # - String: transition to that state (override behavior tree)
+                # - True/None: continue to execute children
+                # - False: for selector, try children; for others, fail immediately
+                if isinstance(parent_result, str):
+                    self._reset_behavior_context()
+                    # Use _transition_to for state transition (triggers changed event)
+                    return self._transition_to(parent_result, state_name, log, event_type="behavior", result=parent_result)
+                if parent_result is False and composite != 'selector':
+                    # Parent failed, behavior fails immediately (except selector which tries children)
+                    self._bhcontext["__print_result__"] = "FAIL"
+                    self._bhcontext["__print_parent__"] = state_name
+                    self._reset_behavior_context()
+                    return False
+                # Success: store print info and continue to children
+                self._bhcontext["__print_result__"] = "OK"
+                self._bhcontext["__print_parent__"] = state_name
+                self._bhcontext["__print_composite__"] = composite
+                self._bhcontext["__print_children__"] = children
+                # Note: parent execution result is printed by _transition_print
+            else:
+                # No parent method, just store print info
+                self._bhcontext["__print_result__"] = "OK"
+                self._bhcontext["__print_parent__"] = state_name
+                self._bhcontext["__print_composite__"] = composite
+                self._bhcontext["__print_children__"] = children
+                # Note: parent execution result is printed by _transition_print
+        # Note: resuming behavior tree doesn't print anything to keep output clean
+
+        match composite:
+            case 'sequence':
+                return self._execute_sequence(state_name, children, log)
+            case 'selector':
+                return self._execute_selector(state_name, children, log)
+            case 'parallel':
+                return self._execute_parallel(state_name, children, log)
+            case _:
+                # Simple behavior - execute child behavior tree if applicable
+                _child = children[0] if children else None
+                if _child is None:
+                    self._reset_behavior_context()
+                    return state_name
+
+                # Check if child is a behavior tree node
+                _child_behavior = self.__behaviors__.get(_child)
+                if _child_behavior is not None:
+                    # Child is behavior tree - execute it
+                    _result = self._handle_behavior(_child, _child_behavior, log)
+                    # Only reset context if child completed (not RUN/None)
+                    if _result is not None:
+                        # 检查 BREAK 是否已被处理，如果是则不重置上下文（保留标记）
+                        if not getattr(self, '_break_handled', False):
+                            # Send completion event for root behavior before reset
+                            if self._bhead == state_name:
+                                _history = self._bhcontext.get("history", [])
+                                # Record simple behavior result based on child result
+                                _history.append((state_name, "success" if _result is not False else "fail"))
+                                self.pushEvent("behavior_completed", {
+                                    "success": _result is not False,
+                                    "history": _history.copy(),
+                                    "failed_node": _child if _result is False else None
+                                })
+                            self._reset_behavior_context()
+                    return _result
+                else:
+                    # Child is regular state - transition and execute via _transition_to
+                    # _transition_to triggers changed event
+                    self._reset_behavior_context()
+                    return self._transition_to(_child, state_name, log, event_type="behavior", result=_child)
+
+    def _reset_behavior_context(self) -> None:
+        """Reset behavior tree execution context."""
+        self._bhead = None
+        self._bhcontext = {}
+
+    def _trigger_behavior_completed_if_needed(self) -> None:
+        """Trigger behavior_completed event if __behavior_return__ mark exists."""
+        if not self._bhcontext:
+            return
+        behavior_return = self._bhcontext.get("__behavior_return__")
+        if behavior_return is None:
+            return
+        # 获取保存的数据
+        history = self._bhcontext.get("__behavior_history__", [])
+        success = self._bhcontext.get("__behavior_success__")
+        failed_node = self._bhcontext.get("__behavior_failed_node__")
+        if history is not None and success is not None:
+            event_data = {
+                "inst": self,
+                "success": success,
+                "history": history
+            }
+            if failed_node:
+                event_data["failed_node"] = failed_node
+            self.pushEvent("behavior_completed", event_data)
+        # 重置上下文
+        self._reset_behavior_context()
+
+    def _execute_sequence(self, parent_name: str, children: list[str], log: bool) -> str | None:
+        """
+        Execute children in sequence (all must succeed).
+
+        RUN (None) handling:
+        - If a child returns None, pause and resume from the same child next tick
+        - Uses _bhcontext to track current index across ticks
+
+        Args:
+            parent_name: Name of the parent behavior state
+            children: List of child state names
+            log: Whether to log
+
+        Returns:
+            Last successful state, False if any fails, or None if RUN
+        """
+        max_len = getattr(self, '__max_state_len__', 0)
+        bold_name = f"{Style.BRIGHT}{self._name}{Style.RESET_ALL}" if _COLOR_AVAILABLE else self._name
+        context_stack: list[str] = self._bhcontext.get("stack", [])
+
+        # Check if this is first entry or resuming
+        is_first_entry = parent_name not in self._bhcontext
+
+        # Get or initialize sequence context
+        if is_first_entry:
+            seq_context = {"index": 0}
+            self._bhcontext[parent_name] = seq_context
+            # First time: push to stack for calculating children's indent
+            if parent_name not in context_stack:
+                context_stack.append(parent_name)
+        else:
+            seq_context = self._bhcontext[parent_name]
+            # Resuming: ensure stack contains this parent at the top
+            if parent_name not in context_stack:
+                context_stack.append(parent_name)
+            else:
+                # Remove any items above this parent
+                while context_stack and context_stack[-1] != parent_name:
+                    context_stack.pop()
+
+        # Calculate indent based on nesting depth
+        # Root's children: 2 spaces, nested children: 4, 6... spaces
+        indent_level = len(context_stack)
+        child_indent = "  " * indent_level if indent_level > 0 else "  "
+        result_indent = "  " * (indent_level - 1) if indent_level > 1 else ""
+
+        current_index = seq_context["index"]
+
+        # Execute from current index
+        while current_index < len(children):
+            child = children[current_index]
+
+            if child not in self.__states__ and child not in self.__behaviors__:
+                if log and self.LOG:
+                    padded = child.ljust(max_len)
+                    print(f"{child_indent}-> {padded} [{Fore.RED}UNKNOWN - FAIL{Fore.RESET}]")
+                self._reset_behavior_context()
+                return False  # type: ignore[return-value]
+
+            # Check if child is a behavior composite
+            child_behavior = self.__behaviors__.get(child)
+            is_child_behavior = child_behavior is not None
+
+            # Transition to child state - triggers CHANGED event
+            # This ensures every node execution follows: parent -> child transition
+            # Avoid duplicate transition if already at this child (from behavior resume)
+            if self._current != child:
+                self._bhcontext["_transitioning_to"] = child
+                try:
+                    self._transition_to(child, parent_name if is_first_entry else self._current, log, event_type="behavior")
+                finally:
+                    del self._bhcontext["_transitioning_to"]
+
+            # Check if child is a behavior composite - if so, let _handle_behavior execute it
+            # to avoid double execution (once in _get_state_result, once in _handle_behavior)
+            if is_child_behavior:
+                # For behavior children, directly call _handle_behavior to avoid double execution
+                executed_result = self._handle_behavior(child, child_behavior, log)
+                actual_result = executed_result
+
+                # Handle string result (BREAK) from behavior child
+                # Use _transition_to for state transition (triggers changed event)
+                if isinstance(actual_result, str):
+                    # Send compisited event for composite node interruption
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": None
+                    })
+                    # Set suppress flag to prevent parent behavior nodes from firing CHANGED
+                    # Context cleanup will be handled by _transition_to
+                    self._suppress_changed = True
+                    # Transition to new state - _transition_to handles context reset
+                    return self._transition_to(actual_result, child, log, result=actual_result)
+            else:
+                # Only print -> child on first entry, not on resume
+                # (Resume is handled by _execute_state which will call us back if needed)
+                if is_first_entry and log and self.LOG:
+                    # Store first entry flag for _transition_print
+                    self._bhcontext["__is_first_entry__"] = True
+
+                # Process Qt events before executing child to handle pending UI updates
+                try:
+                    app = QApplication.instance()
+                    if app:
+                        app.processEvents()
+                except ImportError:
+                    pass
+
+                # Execute state to get result
+                actual_result = self._get_state_result(child)
+
+                # String result means state transition (BREAK) - use _transition_to
+                if isinstance(actual_result, str):
+                    # Store print info
+                    self._bhcontext["__print_result__"] = "BREAK"
+                    # Send compisited event
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": None
+                    })
+                    # 标记行为树完成（BREAK 情况），但不触发 behavior_completed（在 _transition_to 中统一触发）
+                    # 获取历史记录（对于嵌套行为树，保留完整历史）
+                    history = self._bhcontext.get("history", [])
+                    history.append((child, "break"))
+                    # 设置根行为树的完成标记（如果当前是根行为树或嵌套行为树）
+                    if self._bhead is not None:
+                        self._bhcontext["__behavior_history__"] = history.copy()
+                        self._bhcontext["__behavior_success__"] = True  # BREAK 视为成功
+                    self._bhcontext["__behavior_return__"] = parent_name
+                    # 设置标记表示 BREAK 已处理，防止外层行为树重复处理
+                    # 使用实例变量而不是 bhcontext，因为 bhcontext 会被 _transition_to 重置
+                    self._break_handled = True
+                    # Set suppress flag to prevent parent behavior nodes from firing CHANGED
+                    self._suppress_changed = True
+                    # Transition to new state - _transition_to handles context reset and behavior_completed
+                    return self._transition_to(actual_result, child, log, result=actual_result)
+
+                # Execute state with pre-computed result (only if not None/False)
+                # For None/False, we handle directly without calling _execute_state again
+                if actual_result not in (None, False):
+                    # _execute_state triggers enter event
+                    # Set _resuming_behavior to prevent _execute_state from re-resuming the behavior tree
+                    self._resuming_behavior = True
+                    try:
+                        self._execute_state(child, log, pre_result=actual_result, send_enter=True)
+                    finally:
+                        delattr(self, '_resuming_behavior')
+
+            # Note: changed event and onChanged lifecycle hook are triggered in _transition_to
+            # when transitioning to child state. No need to trigger here.
+
+            # RUN (None): pause execution, resume next tick
+            # But if this is the last child, treat it as success and return child name
+            if actual_result is None:
+                self._bhcontext["__print_result__"] = "RUN"
+                self._bhcontext["__print_child__"] = child
+                # Update _current to the child that returned RUN
+                # This ensures next tick resumes from this child, not parent
+                self._current = child
+                # If last child returned None, complete sequence with this child
+                if current_index == len(children) - 1:
+                    # Last child - complete the sequence
+                    seq_context["index"] = current_index + 1
+                    break
+                # Not last child - pause and resume next tick
+                seq_context["index"] = current_index
+                return None
+
+            # False result means failure
+            if actual_result is False:
+                # Store print info for _transition_print to use
+                self._bhcontext["__print_result__"] = "FAIL"
+                self._bhcontext["__print_child__"] = child
+                self._bhcontext["__print_parent__"] = parent_name
+                # Record failure in history
+                history = self._bhcontext.get("history", [])
+                history.append((child, "fail"))
+                history.append((parent_name, "fail"))
+                # Send compisited event for composite node exit
+                self.pushEvent("compisited", {
+                    "inst": self,
+                    "name": parent_name,
+                    "child": child,
+                    "result": False
+                })
+                # Pop from stack and clean up
+                if context_stack and context_stack[-1] == parent_name:
+                    context_stack.pop()
+                if parent_name in self._bhcontext:
+                    del self._bhcontext[parent_name]
+                # If this was the root behavior, send completion event and trigger return to bhead
+                _bhead = self._bhead
+                if _bhead == parent_name:
+                    self.pushEvent("behavior_completed", {
+                        "success": False,
+                        "history": history.copy(),
+                        "failed_node": child
+                    })
+                    # Only trigger return to bhead if this is the root behavior
+                    # (not if it's a child of parallel/another composite)
+                    self._reset_behavior_context()
+                    self._bhcontext["__behavior_return__"] = _bhead
+                    self._bhcontext["__behavior_failed__"] = True
+                    return self._transition_to(_bhead, child, log, event_type="behavior", result=False)
+                return False  # type: ignore[return-value]
+
+            # Success - store print info
+            self._bhcontext["__print_result__"] = "OK"
+            self._bhcontext["__print_child__"] = child
+
+            # Record success in history
+            history = self._bhcontext.get("history", [])
+            history.append((child, "success"))
+
+            # Move to next child
+            current_index += 1
+            seq_context["index"] = current_index
+
+            # Update _current to the child we just executed
+            self._current = child
+
+            # Pop from stack for clean resume state
+            if context_stack and context_stack[-1] == parent_name:
+                context_stack.pop()
+
+            # If this was the last child, handle completion immediately
+            # instead of returning None (which would pause and cause
+            # resume logic to re-execute the behavior tree)
+            if current_index >= len(children):
+                # Last child completed - handle completion directly
+                # Store print info for _transition_print
+                self._bhcontext["__print_result__"] = "OK"
+                self._bhcontext["__print_parent__"] = parent_name
+
+                # Record parent success in history
+                history.append((parent_name, "success"))
+
+                # Send compisited event for composite node success
+                self.pushEvent("compisited", {
+                    "inst": self,
+                    "name": parent_name,
+                    "child": children[-1] if children else None,
+                    "result": True
+                })
+
+                # Pop from stack and clean up
+                if context_stack and context_stack[-1] == parent_name:
+                    context_stack.pop()
+                if parent_name in self._bhcontext:
+                    del self._bhcontext[parent_name]
+
+                # 标记行为树完成，但不触发 behavior_completed（在 _transition_to 中统一触发）
+                if self._bhead is not None:
+                    self._bhcontext["__behavior_history__"] = history.copy()
+                    self._bhcontext["__behavior_success__"] = True
+                self._bhcontext["__behavior_return__"] = parent_name
+
+                # Update _current to parent_name explicitly via _transition_to
+                # This ensures the next tick will execute from the parent (restarting the sequence)
+                # We call _transition_to with event_type="-" to trigger the changed event
+                # The _suppress_changed flag check in _transition_to will handle duplicate prevention
+                return self._transition_to(parent_name, child, log, event_type="-", result=parent_name)
+
+            # Not the last child - pause execution, resume next tick
+            return None
+
+        # All children completed successfully (reached naturally via loop completion)
+        # This section is now handled above when the last child completes
+        # Store print info for _transition_print
+        self._bhcontext["__print_result__"] = "OK"
+        self._bhcontext["__print_parent__"] = parent_name
+
+        # Record parent success in history
+        history = self._bhcontext.get("history", [])
+        history.append((parent_name, "success"))
+
+        # Send compisited event for composite node success
+        self.pushEvent("compisited", {
+            "inst": self,
+            "name": parent_name,
+            "child": children[-1] if children else None,
+            "result": True
+        })
+
+        # Pop from stack and clean up
+        if context_stack and context_stack[-1] == parent_name:
+            context_stack.pop()
+        if parent_name in self._bhcontext:
+            del self._bhcontext[parent_name]
+
+        # 标记行为树完成，但不触发 behavior_completed（在 _transition_to 中统一触发）
+        # 保存历史记录供后续使用（只要是在行为树中就保存）
+        if self._bhead is not None:
+            self._bhcontext["__behavior_history__"] = history.copy()
+            self._bhcontext["__behavior_success__"] = True
+        # 不在这里重置 bhcontext，让 _transition_to 来处理
+        # 临时标记：告诉 _transition_to 这是行为树内部完成
+        self._bhcontext["__behavior_return__"] = parent_name
+
+        return parent_name
+    
+    def _execute_selector(self, parent_name: str, children: list[str], log: bool) -> str | None:
+        """
+        Execute children until one succeeds.
+
+        RUN (None) handling:
+        - If a child returns None, pause and resume from the same child next tick
+        - If a child returns True/success, the selector succeeds
+        - If a child returns False/failure, try the next child
+
+        Args:
+            parent_name: Name of the parent behavior state
+            children: List of child state names
+            log: Whether to log
+
+        Returns:
+            First successful state, False if all fail, or None if RUN
+        """
+        max_len = getattr(self, '__max_state_len__', 0)
+        bold_name = f"{Style.BRIGHT}{self._name}{Style.RESET_ALL}" if _COLOR_AVAILABLE else self._name
+        context_stack: list[str] = self._bhcontext.get("stack", [])
+
+        # Check if this is first entry or resuming
+        is_first_entry = parent_name not in self._bhcontext
+
+        # Get or initialize selector context
+        if is_first_entry:
+            sel_context = {"index": 0}
+            self._bhcontext[parent_name] = sel_context
+            # First time: push to stack
+            context_stack.append(parent_name)
+        else:
+            sel_context = self._bhcontext[parent_name]
+            # Resuming: ensure stack contains this parent at the top
+            if parent_name not in context_stack:
+                context_stack.append(parent_name)
+            else:
+                while context_stack and context_stack[-1] != parent_name:
+                    context_stack.pop()
+
+        # Calculate indent based on nesting depth
+        # Root's children: 2 spaces, nested children: 4, 6... spaces
+        indent_level = len(context_stack)
+        child_indent = "  " * indent_level if indent_level > 0 else "  "
+        result_indent = "  " * (indent_level - 1) if indent_level > 1 else ""
+
+        current_index = sel_context["index"]
+
+        # Execute from current index
+        while current_index < len(children):
+            child = children[current_index]
+
+            if child not in self.__states__ and child not in self.__behaviors__:
+                if log and self.LOG:
+                    padded = child.ljust(max_len)
+                    print(f"{child_indent}-> {padded} [{Fore.YELLOW}UNKNOWN - SKIP{Fore.RESET}]")
+                current_index += 1
+                sel_context["index"] = current_index
+                continue
+
+            # Check if child is a behavior composite
+            child_behavior = self.__behaviors__.get(child)
+            is_child_behavior = child_behavior is not None
+
+            # Transition to child state - triggers CHANGED event
+            # Avoid duplicate transition if already at this child (from behavior resume)
+            if self._current != child:
+                self._bhcontext["_transitioning_to"] = child
+                try:
+                    self._transition_to(child, parent_name if is_first_entry else self._current, log, event_type="behavior")
+                finally:
+                    del self._bhcontext["_transitioning_to"]
+
+            # Check if child is a behavior composite - if so, let _handle_behavior execute it
+            # NOTE: _handle_behavior sends its own enter event, so we don't send one here for behavior children
+            if is_child_behavior:
+                # For behavior children, directly call _handle_behavior to avoid double execution
+                executed_result = self._handle_behavior(child, child_behavior, log)
+                actual_result = executed_result
+
+                # Handle string result (BREAK) from behavior child
+                # Use _transition_to for state transition (triggers changed event)
+                if isinstance(actual_result, str):
+                    # Send compisited event
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": None
+                    })
+                    # Set suppress flag to prevent parent behavior nodes from firing CHANGED
+                    # Context cleanup will be handled by _transition_to
+                    self._suppress_changed = True
+                    # Transition to new state - _transition_to handles context reset
+                    return self._transition_to(actual_result, child, log, result=actual_result)
+            else:
+                # Only print -> child on first entry, not on resume
+                # Store first entry flag in bhcontext for _transition_print
+                if is_first_entry:
+                    self._bhcontext["__is_first_entry__"] = True
+
+                # Execute state to get result
+                actual_result = self._get_state_result(child)
+
+                # String result means state transition (BREAK) - use _transition_to
+                if isinstance(actual_result, str):
+                    # Store print info
+                    self._bhcontext["__print_result__"] = "BREAK"
+                    # Send compisited event
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": None
+                    })
+                    # Set suppress flag to prevent parent behavior nodes from firing CHANGED
+                    # Context cleanup will be handled by _transition_to
+                    self._suppress_changed = True
+                    # Transition to new state - _transition_to handles context reset
+                    return self._transition_to(actual_result, child, log, result=actual_result)
+
+                # Execute state with pre-computed result
+                # _execute_state triggers enter event
+                # Set _resuming_behavior to prevent _execute_state from re-resuming the behavior tree
+                self._resuming_behavior = True
+                try:
+                    executed_result = self._execute_state(child, log, pre_result=actual_result, send_enter=True)
+                finally:
+                    if hasattr(self, '_resuming_behavior'):
+                        delattr(self, '_resuming_behavior')
+
+            # Use executed_result for behavior tree children, actual_result for regular states
+            effective_result = executed_result if is_child_behavior else actual_result
+
+            # Note: changed event and onChanged lifecycle hook are triggered in _transition_to
+            # when transitioning to child state. No need to trigger here.
+
+            # RUN (None): pause execution, resume next tick
+            # But if this is the last child, treat it as success and return child name
+            if effective_result is None:
+                self._bhcontext["__print_result__"] = "RUN"
+                # If last child returned None, complete selector with this child
+                if current_index == len(children) - 1:
+                    # Last child - complete the selector (treat as success)
+                    sel_context["index"] = current_index + 1
+                    # Record success in history
+                    history = self._bhcontext.get("history", [])
+                    history.append((child, "success"))
+                    history.append((parent_name, "success"))
+                    # Send compisited event for composite node success
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": True
+                    })
+                    # Clean up
+                    if context_stack and context_stack[-1] == parent_name:
+                        context_stack.pop()
+                    if parent_name in self._bhcontext:
+                        del self._bhcontext[parent_name]
+                    # 标记行为树完成，但不触发 behavior_completed（在 _transition_to 中统一触发）
+                    if self._bhead is not None:
+                        self._bhcontext["__behavior_history__"] = history.copy()
+                        self._bhcontext["__behavior_success__"] = True
+                    # 不在这里重置 bhcontext，让 _transition_to 来处理
+                    self._bhcontext["__behavior_return__"] = parent_name
+                    return child
+                # Not last child - pause and resume next tick
+                sel_context["index"] = current_index
+                return None
+
+            # Success (non-False, non-None, non-str result)
+            if effective_result is not False:
+                self._bhcontext["__print_result__"] = "OK"
+                self._bhcontext["__print_child__"] = child
+                # Record success in history
+                history = self._bhcontext.get("history", [])
+                history.append((child, "success"))
+                history.append((parent_name, "success"))
+                # Send compisited event for composite node success
+                self.pushEvent("compisited", {
+                    "inst": self,
+                    "name": parent_name,
+                    "child": child,
+                    "result": True
+                })
+                # Clean up
+                if context_stack and context_stack[-1] == parent_name:
+                    context_stack.pop()
+                if parent_name in self._bhcontext:
+                    del self._bhcontext[parent_name]
+                # 标记行为树完成，但不触发 behavior_completed（在 _transition_to 中统一触发）
+                if self._bhead is not None:
+                    self._bhcontext["__behavior_history__"] = history.copy()
+                    self._bhcontext["__behavior_success__"] = True
+                # 不在这里重置 bhcontext，让 _transition_to 来处理
+                self._bhcontext["__behavior_return__"] = parent_name
+                # Set suppress flag to prevent duplicate CHANGED event
+                # The transition to child was already triggered inside the selector
+                self._suppress_changed = True
+                return child
+
+            # Failure: try next child
+            self._bhcontext["__print_result__"] = "FAIL"
+            self._bhcontext["__print_child__"] = child
+            # Record failure in history
+            history = self._bhcontext.get("history", [])
+            history.append((child, "fail"))
+            current_index += 1
+            sel_context["index"] = current_index
+
+        # All failed
+        # Store print info for _transition_print
+        self._bhcontext["__print_result__"] = "ALL FAILED"
+        self._bhcontext["__print_parent__"] = parent_name
+
+        # Record parent failure in history
+        history = self._bhcontext.get("history", [])
+        history.append((parent_name, "fail"))
+
+        # Send compisited event for composite node failure
+        self.pushEvent("compisited", {
+            "inst": self,
+            "name": parent_name,
+            "child": None,  # All children failed
+            "result": False
+        })
+
+        # Clean up
+        if context_stack and context_stack[-1] == parent_name:
+            context_stack.pop()
+        if parent_name in self._bhcontext:
+            del self._bhcontext[parent_name]
+        # 标记行为树失败完成，但不触发 behavior_completed（在 _transition_to 中统一触发）
+        if self._bhead is not None:
+            self._bhcontext["__behavior_history__"] = history.copy()
+            self._bhcontext["__behavior_success__"] = False
+            self._bhcontext["__behavior_failed_node__"] = parent_name
+        # 不在这里重置 bhcontext，让 _transition_to 来处理
+        self._bhcontext["__behavior_return__"] = parent_name
+        self._bhcontext["__behavior_failed__"] = True
+
+        return False  # type: ignore[return-value]
+
+    def _execute_parallel(self, parent_name: str, children: list[str], log: bool) -> str | None:
+        """
+        Execute all children (any can succeed).
+
+        RUN (None) handling:
+        - If any child returns None, the parallel returns None (RUN)
+        - Tracks which children have completed across ticks
+
+        Args:
+            parent_name: Name of the parent behavior state
+            children: List of child state names
+            log: Whether to log
+
+        Returns:
+            First successful state, False if all fail, or None if RUN
+        """
+        max_len = getattr(self, '__max_state_len__', 0)
+        bold_name = f"{Style.BRIGHT}{self._name}{Style.RESET_ALL}" if _COLOR_AVAILABLE else self._name
+        context_stack: list[str] = self._bhcontext.get("stack", [])
+
+        # Check if this is first entry or resuming
+        is_first_entry = parent_name not in self._bhcontext
+
+        # Get or initialize parallel context
+        if is_first_entry:
+            para_context = {"history": [False] * len(children), "completed": 0, "entered": [False] * len(children)}
+            self._bhcontext[parent_name] = para_context
+            context_stack.append(parent_name)
+        else:
+            para_context = self._bhcontext[parent_name]
+            # Resuming: ensure stack contains this parent at the top
+            if parent_name not in context_stack:
+                context_stack.append(parent_name)
+            else:
+                while context_stack and context_stack[-1] != parent_name:
+                    context_stack.pop()
+
+        # Calculate indent based on nesting depth
+        # Root's children: 2 spaces, nested children: 4, 6... spaces
+        indent_level = len(context_stack)
+        child_indent = "  " * indent_level if indent_level > 0 else "  "
+        result_indent = "  " * (indent_level - 1) if indent_level > 1 else ""
+
+        completed_history = para_context["history"]
+        any_running = False
+        any_success = False
+        last_result: str | None = None
+
+        for i, child in enumerate(children):
+            # Skip already completed children
+            if completed_history[i]:
+                continue
+
+            if child not in self.__states__ and child not in self.__behaviors__:
+                if log and self.LOG:
+                    padded = child.ljust(max_len)
+                    print(f"{child_indent}-> {padded} [{Fore.YELLOW}UNKNOWN - SKIP{Fore.RESET}]")
+                completed_history[i] = True
+                para_context["completed"] += 1
+                continue
+
+            # Check if child is a behavior composite (like _execute_sequence does)
+            child_behavior = self.__behaviors__.get(child)
+            is_child_behavior = child_behavior is not None
+
+            # Transition to child state - triggers CHANGED event
+            # For parallel, all children transition from parent (concurrent execution)
+            # Avoid duplicate transition if:
+            # 1. Already at this child (from behavior resume)
+            # 2. Child is a behavior tree that has already started (has its own context)
+            _already_started = is_child_behavior and child in self._bhcontext
+            if self._current != child and not _already_started:
+                self._bhcontext["_transitioning_to"] = child
+                try:
+                    # Parallel children are concurrent: each branches from the
+                    # parent, so every child transition is parent -> child
+                    # (root -> a, root -> b), never child -> sibling (a -> b).
+                    # Using _current here would chain children like a sequence
+                    # and corrupt both the 'changed' event source and the log.
+                    self._transition_to(child, parent_name, log, event_type="behavior")
+                finally:
+                    del self._bhcontext["_transitioning_to"]
+
+            # Check if child is a behavior composite - if so, let _handle_behavior execute it
+            # NOTE: _handle_behavior sends its own enter event, so we don't send one here for behavior children
+            if is_child_behavior:
+                # For behavior children, directly call _handle_behavior to avoid double execution
+                executed_result = self._handle_behavior(child, child_behavior, log)
+                actual_result = executed_result
+            else:
+                # Only print -> child on first entry, not on resume
+                # Store first entry flag in bhcontext for _transition_print
+                if is_first_entry:
+                    self._bhcontext["__is_first_entry__"] = True
+
+                # Execute state to get result
+                actual_result = self._get_state_result(child)
+                last_result = actual_result
+
+                # Execute state with pre-computed result
+                # _execute_state triggers enter event
+                executed_result = self._execute_state(child, log, pre_result=actual_result, send_enter=True)
+
+            # Use executed_result for behavior tree children, actual_result for regular states
+            effective_result = executed_result if is_child_behavior else actual_result
+
+            # String result handling:
+            # - For regular states: state transition (BREAK) to a new state
+            # - For behavior tree children: if returning self name, it's completion not BREAK
+            if isinstance(effective_result, str):
+                # 检查 BREAK 是否已被内层行为树处理
+                if getattr(self, '_break_handled', False):
+                    # BREAK 已处理，触发外层的 compisited，然后返回
+                    self._break_handled = False
+                    # 先触发外层 parallel 的 compisited
+                    
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": True
+                    })
+                    # 再触发 behavior_completed
+                    has_data = hasattr(self, '_behavior_completion_data')
+                    data_truthy = bool(self._behavior_completion_data) if has_data else False
+                    if has_data and data_truthy:
+                        event_data = {
+                            "inst": self,
+                            "success": self._behavior_completion_data.get("success"),
+                            "history": self._behavior_completion_data.get("history")
+                        }
+                        failed_node = self._behavior_completion_data.get("failed_node")
+                        if failed_node:
+                            event_data["failed_node"] = failed_node
+                        self.pushEvent("behavior_completed", event_data)
+                        self._behavior_completion_data = None
+                    return effective_result
+                # Behavior tree child returning its own name = completion, not BREAK
+                if is_child_behavior and effective_result == child:
+                    # Treat as successful completion, not state transition
+                    completed_history[i] = True
+                    para_context["completed"] += 1
+                    any_success = True
+                    exec_history.append((child, "success"))
+                    last_result = effective_result
+                    # Continue to next child (don't return, process as success)
+                else:
+                    # BREAK: transition to a different state
+                    # Store print info
+                    self._bhcontext["__print_result__"] = "BREAK"
+                    # Send compisited event for composite node interruption
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": None
+                    })
+                    # 标记行为树完成（BREAK 情况），但不触发 behavior_completed（在 _transition_to 中统一触发）
+                    # 获取历史记录（对于嵌套行为树，保留完整历史）
+                    history = self._bhcontext.get("history", [])
+                    history.append((child, "break"))
+                    # 设置根行为树的完成标记（如果当前是根行为树或嵌套行为树）
+                    if self._bhead is not None:
+                        self._bhcontext["__behavior_history__"] = history.copy()
+                        self._bhcontext["__behavior_success__"] = True  # BREAK 视为成功
+                    self._bhcontext["__behavior_return__"] = parent_name
+                    # 触发外层 behavior 的 compisited（对于嵌套行为树）
+                    
+                    self.pushEvent("compisited", {
+                        "inst": self,
+                        "name": parent_name,
+                        "child": child,
+                        "result": True
+                    })
+                    # Set suppress flag to prevent parent behavior nodes from firing CHANGED
+                    self._suppress_changed = True
+                    # Transition to new state - _transition_to handles context reset and behavior_completed
+                    return self._transition_to(effective_result, child, log, result=effective_result)
+
+                # Behavior tree child completed (treated as success above)
+                if is_child_behavior and effective_result == child:
+                    continue
+
+            # Note: changed event and onChanged lifecycle hook are triggered in _transition_to
+            # when transitioning to child state. No need to trigger here.
+
+            # RUN (None): mark as running
+            if effective_result is None:
+                self._bhcontext["__print_result__"] = "RUN"
+                any_running = True
+                continue
+
+            # Mark as completed
+            completed_history[i] = True
+            para_context["completed"] += 1
+
+            # Track success and record in history
+            exec_history = self._bhcontext.get("history", [])
+            if effective_result is not False:
+                any_success = True
+                exec_history.append((child, "success"))
+                self._bhcontext["__print_result__"] = "OK"
+                self._bhcontext["__print_child__"] = child
+            else:
+                exec_history.append((child, "fail"))
+                self._bhcontext["__print_result__"] = "FAIL"
+                self._bhcontext["__print_child__"] = child
+
+        # If any child is still running, return None
+        if any_running:
+            return None
+
+        # Build completion history from loop results
+        # Store print info for _transition_print
+        if any_success:
+            self._bhcontext["__print_result__"] = "OK"
+        else:
+            self._bhcontext["__print_result__"] = "ALL FAILED"
+        self._bhcontext["__print_parent__"] = parent_name
+
+        # Record parent completion
+        exec_history = self._bhcontext.get("history", [])
+        exec_history.append((parent_name, "success" if any_success else "fail"))
+
+        # Send compisited event for composite node completion
+        # Find the first successful child for parallel success case
+        success_child = None
+        if any_success:
+            for i, child in enumerate(children):
+                if completed_history[i] and i < len(children):
+                    # Check if this child was successful
+                    _result = self._get_state_result(child)
+                    if _result is not False:
+                        success_child = child
+                        break
+        
+        self.pushEvent("compisited", {
+            "inst": self,
+            "name": parent_name,
+            "child": success_child,  # None if all failed
+            "result": any_success
+        })
+
+        # Clean up
+        if context_stack and context_stack[-1] == parent_name:
+            context_stack.pop()
+        if parent_name in self._bhcontext:
+            del self._bhcontext[parent_name]
+        # 标记行为树完成，但不触发 behavior_completed（在 _transition_to 中统一触发）
+        if self._bhead is not None:
+            self._bhcontext["__behavior_history__"] = exec_history.copy()
+            self._bhcontext["__behavior_success__"] = any_success
+        # 不在这里重置 bhcontext，让 _transition_to 来处理
+        self._bhcontext["__behavior_return__"] = parent_name
+        if not any_success:
+            self._bhcontext["__behavior_failed__"] = True
+
+        # Restore _current to parent_name so next tick executes from the behavior tree root
+        # not from the last child that was executed
+        self._current = parent_name
+
+        # Return True to indicate success, not the child state name
+        # This prevents _handle_result from treating it as a state transition
+        return True if any_success else False  # type: ignore[return-value]
+
+    def _transition_print(self, new_state: str, old_state: str, log: bool, event_type: str) -> None:
+        """
+        统一处理所有状态切换的输出打印。
+        只能在 _transition_to 中调用。
+        与老版本兼容的输出格式。
+
+        Args:
+            new_state: 新状态名
+            old_state: 旧状态名
+            log: 是否打印
+            event_type: 事件类型
+        """
+        if not log or not self.LOG:
+            return
+
+        # 检查是否是跳转到行为树外部（BREAK）
+        is_break_to_external = (
+            self._bhead is not None and
+            new_state not in self.__behaviors__ and
+            new_state not in self._get_all_behavior_children()
+        )
+
+        # 检查是否需要抑制日志（BREAK 冒泡时），但如果是跳转到外部则不抑制
+        if getattr(self, "_suppress_changed", False) and not is_break_to_external:
+            return
+
+        # 老版本输出格式: std.info(tag, message, extra)
+        # tag: self._name + ".fbm" (普通状态机) 或 ... (行为树内部)
+        # message: old_state -> new_state
+        # extra: ... (递归状态)
+
+        # 确定 tag: 如果在行为树中且不是跳转到外部，使用 ...
+        if self._bhead is not None and not is_break_to_external:
+            tag = "..."
+        else:
+            tag = f"{self._name}.fbm"
+
+        # message: old_state -> new_state
+        message = f"{old_state} -> {new_state}"
+
+        # extra: 递归标记 (如果新状态是递归状态)
+        extra = ""
+        if new_state in self.__recursive__:
+            extra = "..."
+
+        # 输出
+        if extra:
+            std.info(tag, message, extra)
+        else:
+            std.info(tag, message)
+
+    def _get_all_behavior_children(self) -> set[str]:
+        """获取所有行为树的所有子节点。"""
+        children = set()
+        for behavior in self.__behaviors__.values():
+            behavior_children = behavior.get("children", [])
+            if isinstance(behavior_children, str):
+                children.add(behavior_children)
+            else:
+                children.update(behavior_children)
+        return children
+
+    def _transition_to(
+        self,
+        new_state: str,
+        old_state: str,
+        log: bool,
+        event_type: str = "-",
+        result: Any = None
+    ) -> str | None:
+        """
+        Transition to a new state. This is the ONLY place where 'changed' event is triggered.
+
+        Args:
+            new_state: State to transition to
+            old_state: Current state name
+            log: Whether to log
+            event_type: Event type for changed event (e.g., "behavior", "-")
+            result: Result value to include in changed event
+
+        Returns:
+            New state name or None
+        """
+        # 统一打印输出
+        self._transition_print(new_state, old_state, log, event_type)
+
+        if new_state not in self.__states__ and new_state not in self.__behaviors__:
+            return old_state
+
+        self._current = new_state
+
+        # Check if this is a behavior tree internal child transition
+        _bt_target = self._bhcontext.get("_transitioning_to") if self._bhcontext else None
+        _is_bt_child_transition = _bt_target is not None and new_state == _bt_target
+
+        # Check if CHANGED event should be suppressed (for behavior tree BREAK bubbling)
+        _suppress_changed = getattr(self, "_suppress_changed", False)
+
+        # 检查是否是行为树返回标记
+        behavior_return = self._bhcontext.get("__behavior_return__") if self._bhcontext else None
+
+        # 在重置之前保存 behavior_completed 所需的数据
+        # 使用实例变量来跨多次 _transition_to 调用保存数据
+        if self._bhcontext:
+            if self._bhcontext.get("__behavior_history__") is not None:
+                self._behavior_completion_data = {
+                    "history": self._bhcontext.get("__behavior_history__"),
+                    "success": self._bhcontext.get("__behavior_success__"),
+                    "failed_node": self._bhcontext.get("__behavior_failed_node__")
+                }
+                
+        # 从实例变量恢复数据（如果存在）
+        behavior_history = None
+        behavior_success = None
+        behavior_failed_node = None
+        if hasattr(self, '_behavior_completion_data') and self._behavior_completion_data:
+            behavior_history = self._behavior_completion_data.get("history")
+            behavior_success = self._behavior_completion_data.get("success")
+            behavior_failed_node = self._behavior_completion_data.get("failed_node")
+
+        # Reset behavior context on state transition
+        # But preserve it if transitioning to a behavior tree or internal child transition
+        # If suppressing CHANGED (BREAK from child), always reset context
+        root = None
+        # 检查是否是行为树完成后的跳转（通过 __behavior_return__ 标记）
+        is_behavior_completion = behavior_return is not None
+        if (self._bhead is not None or is_behavior_completion) and new_state not in self.__behaviors__ and not _is_bt_child_transition:
+            root = self._bhead if self._bhead is not None else behavior_return
+            self._reset_behavior_context()
+
+        # Call lifecycle hook (always called for state tracking)
+        self.onChanged(old_state, new_state, self._inst)
+
+        # Trigger changed event - ONLY place where this event is fired
+        # But suppress for behavior tree internal bubbling transitions
+        if not _suppress_changed or root:
+            # 如果是行为树返回，触发两次 changed 事件：
+            # 1. 子节点 -> bhead（行为树 parent）
+            # 2. bhead -> new_state（实际目标）
+            if behavior_return and behavior_return != old_state:
+                # BREAK 情况：直接触发一次 CHANGED 事件：子节点 -> new_state
+                
+                event_data = {
+                    "inst": self,
+                    "old": old_state,
+                    "new": new_state,
+                    "type": event_type
+                }
+                if result is not None:
+                    event_data["result"] = result
+                self.pushEvent("changed", event_data)
+
+                # 在 compisited 事件之后触发 behavior_completed
+                # 使用之前保存的数据
+                # 只在根行为树阶段触发（通过检查 behavior_return 是否是根行为树）
+                # 根行为树的判断：behavior_return 不在任何子行为树的 children 中
+                is_root_behavior = True
+                if behavior_return:
+                    for behavior_name, behavior_info in self.__behaviors__.items():
+                        children = behavior_info.get("children", [])
+                        if isinstance(children, str):
+                            children = [children]
+                        if behavior_return in children:
+                            # behavior_return 是某个行为树的子节点，不是根
+                            is_root_behavior = False
+                            break
+                if is_root_behavior and behavior_history is not None and behavior_success is not None:
+                    
+                    event_data = {
+                        "inst": self,
+                        "success": behavior_success,
+                        "history": behavior_history
+                    }
+                    if behavior_failed_node:
+                        event_data["failed_node"] = behavior_failed_node
+                    self.pushEvent("behavior_completed", event_data)
+                    # 清理实例变量，避免重复触发
+                    self._behavior_completion_data = None
+
+                # 清理标记
+                if self._bhcontext and "__behavior_return__" in self._bhcontext:
+                    del self._bhcontext["__behavior_return__"]
+            else:
+                # 普通情况
+                event_data = {
+                    "inst": self,
+                    "old": old_state,
+                    "new": new_state,
+                    "type": event_type
+                }
+                if result is not None:
+                    event_data["result"] = result
+                self.pushEvent("changed", event_data)
+
+        return new_state
+
+    @property
+    def uid(self) -> int:
+        """Unique instance identifier."""
+        return self._uid
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def inst(self) -> Any:
+        return self._inst
+
+    @property
+    def current_state(self) -> str | None:
+        """Get the current state name."""
+        return self._current
+
+    @property
+    def states(self) -> list[str]:
+        """Get list of all available states."""
+        return self.__states__.copy()
+    
+    @property
+    def recursive_states(self) -> set[str]:
+        """Get set of recursive state names."""
+        return self.__recursive__.copy()
+
+    @property
+    def now(self) -> int:
+        """Get current scheduler tick (read-only)."""
+        try:
+            return Scheduler().tick
+        except Exception:
+            return 0
+
+    def goto(self, state_name: str) -> bool:
+        """
+        Manually transition to a state.
+        
+        Args:
+            state_name: Target state name
+            
+        Returns:
+            True if transition succeeded
+        """
+        if state_name not in self.__states__ and state_name not in self.__behaviors__:
+            return False
+        
+        old_state = self._current
+        self._current = state_name
+        self.onChanged(old_state, state_name, self._inst)
+        return True
+
+    # ========================================================================
+    # Event Methods
+    # ========================================================================
+
+    def listenFor(self, event: str, callback: Any, *sources: str) -> Self:
+        """
+        Register an event listener.
+
+        Args:
+            event: Event name to listen for
+            callback: Function to call when event occurs
+            *sources: Optional source filters
+
+        Returns:
+            self for method chaining
+        """
+        self._eda.listenFor(event, callback, *sources)
+        return self
+
+    def cancelListen(self, event: str, callback: Any | None = None) -> bool:
+        """
+        Cancel an event listener.
+
+        Args:
+            event: Event name to stop listening for
+            callback: Specific callback to remove (None = all)
+
+        Returns:
+            True if listener was removed
+        """
+        return self._eda.cancelListen(event, callback)
+
+    def pushEvent(self, event: str, data: Any = None, *targets: str) -> int:
+        """
+        Push an event to listeners.
+
+        Args:
+            event: Event name to push
+            data: Event data
+            *targets: Optional target filters
+
+        Returns:
+            Number of listeners that received the event
+        """
+        # print("stage: ", event, data)
+        return self._eda.pushEvent(event, data, *targets)
+
+    @classmethod
+    def extractNodes(cls) -> Dict[str, Dict[str, Any]]:
+        """
+        静态分析当前 Stage 类的所有状态方法，提取：
+        - 文档字符串 (doc)
+        - 函数体源代码 (code)
+        - 所有静态返回的目标状态 (targets)
+        - 装饰器列表 (decorates)
+
+        适用于 Python 3.8+ (已针对 3.10+ 优化)
+        """
+        result = {}
+        states = cls.__states__
+
+        try:
+            source_file = inspect.getsourcefile(cls)
+            if not source_file:
+                raise FileNotFoundError(f"Source file not found for {cls.__name__}")
+
+            with open(source_file, 'r', encoding='utf-8') as f:
+                source = f.read()
+        except Exception as e:
+            raise RuntimeError(f"Cannot access source code: {e}") from e
+
+        try:
+            module_ast = ast.parse(source)
+        except SyntaxError as e:
+            raise RuntimeError(f"Syntax error in source file: {e}") from e
+
+        # 找到当前类定义
+        target_class_node = None
+        for node in ast.walk(module_ast):
+            if isinstance(node, ast.ClassDef) and node.name == cls.__name__:
+                target_class_node = node
+                break
+
+        if not target_class_node:
+            raise RuntimeError(f"Class {cls.__name__} not found in source file")
+
+        # 遍历类中的所有方法
+        for node in target_class_node.body:
+            if isinstance(node, ast.FunctionDef) and node.name in states:
+                state_name = node.name
+
+                # 【核心修复点 2】从源文本提取代码体
+                code = cls._extract_function_body(source, node)
+
+                # 提取文档字符串
+                doc = ast.get_docstring(node) or ""
+
+                # 提取目标状态
+                targets = cls._extract_static_targets(node, state_name)
+
+                # 提取非 property 装饰器列表
+                decorates = []
+                for decorator in node.decorator_list:
+                    # 排除 property 装饰器
+                    if isinstance(decorator, ast.Name) and decorator.id == 'property':
+                        continue
+                    # 排除 property() 调用
+                    elif isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Name) and decorator.func.id == 'property':
+                        continue
+
+                    # 获取装饰器名称 (处理链式调用如 @dec1 @dec2)
+                    decor_name = cls._get_decorator_name(decorator)
+                    if decor_name:
+                        decorates.append(decor_name)
+
+                result[state_name] = {
+                    "doc": doc,
+                    "code": code,
+                    "targets": targets,
+                    "decorates": decorates
+                }
+
+        return result
+
+    @staticmethod
+    def _extract_function_body(source: str, func_node: ast.FunctionDef) -> str:
+        """
+        从源码字符串中提取函数体，去除 'def ...:' 行和公共缩进。
+        适用于 Python 3.8+ (依赖 end_lineno)
+        """
+        start_line = func_node.lineno
+
+        # Python 3.8+ 保证有 end_lineno
+        if not hasattr(func_node, 'end_lineno'):
+            raise RuntimeError("AST node missing end_lineno. Requires Python 3.8+")
+
+        end_line = func_node.end_lineno
+
+        lines = source.splitlines()
+
+        # 边界检查 (行号从 1 开始，列表索引从 0 开始)
+        if start_line > len(lines) or end_line > len(lines):
+            return ""
+
+        # 截取函数定义行到结束行的所有内容
+        func_lines = lines[start_line - 1: end_line]
+
+        # 去掉第一行 (def ...)
+        body_lines = func_lines[1:]
+
+        if not body_lines:
+            return ""
+
+        # 计算公共缩进
+        first_body_line = body_lines[0]
+        indent = len(first_body_line) - len(first_body_line.lstrip())
+
+        cleaned_lines = []
+        for line in body_lines:
+            if line.strip() == "":
+                cleaned_lines.append("")
+            elif len(line) >= indent:
+                cleaned_lines.append(line[indent:])
+            else:
+                # 防止缩进异常导致截断错误
+                cleaned_lines.append(line)
+
+        return "\n".join(cleaned_lines).rstrip()
+
+    @staticmethod
+    def _extract_static_targets(func_node: ast.FunctionDef, current_state: str) -> List[str]:
+        """
+        使用 AST 静态分析函数中所有 return 的字符串字面量目标。
+        兼容 Python 3.8+ (ast.Constant)
+        """
+        targets = set()
+
+        def _visit(node, depth=0):
+            if isinstance(node, ast.Return):
+                value = node.value
+                if value is None:
+                    return
+
+                # Python 3.8+ 统一使用 ast.Constant
+                if isinstance(value, ast.Constant):
+                    if isinstance(value.value, str):
+                        target = value.value
+                        if target != current_state:
+                            targets.add(target)
+                # 兼容性兜底 (理论上 3.10+ 不需要，但保留以防万一)
+                elif hasattr(ast, 'Str') and isinstance(value, ast.Str):
+                    if value.s != current_state:
+                        targets.add(value.s)
+
+            elif isinstance(node, ast.If):
+                for child in node.body:
+                    _visit(child, depth + 1)
+                for child in node.orelse:
+                    _visit(child, depth + 1)
+
+            elif isinstance(node, ast.IfExp):  # 三元表达式
+                _visit(node.body, depth + 1)
+                _visit(node.orelse, depth + 1)
+
+            # 递归遍历子节点
+            for child in ast.iter_child_nodes(node):
+                _visit(child, depth + 1)
+
+        # 从函数体开始递归
+        for stmt in func_node.body:
+            _visit(stmt)
+
+        return sorted(list(targets))
+
+    @staticmethod
+    def _get_decorator_name(decorator: ast.expr) -> str | None:
+        """
+        从 AST 装饰器节点提取名称字符串。
+        支持简单名称、属性访问 (obj.method) 和带参数的调用 (func(arg))。
+        """
+        if isinstance(decorator, ast.Name):
+            return decorator.id
+        elif isinstance(decorator, ast.Attribute):
+            # 处理 obj.attr 形式
+            return decorator.attr
+        elif isinstance(decorator, ast.Call):
+            # 处理 func(arg) 形式，只取函数名
+            if isinstance(decorator.func, ast.Name):
+                return decorator.func.id
+            elif isinstance(decorator.func, ast.Attribute):
+                return decorator.func.attr
+        return None
+
+__all__ = [
+    'Stage',
+    '_NamedNode',
+]