zhenxun_bot/zhenxun/services/ai/flow/workflow/base.py

from abc import ABC, abstractmethod
import asyncio
from collections.abc import AsyncIterator
from typing import Any

from zhenxun.services.ai.core.exceptions import (
    AbortException,
    ControlFlowExit,
    ToolFatalError,
)
from zhenxun.services.ai.flow.workflow.types import (
    AbortPolicy,
    BaseFailurePolicy,
    PolicyAction,
    StepInput,
    StepOutput,
    StepType,
)
from zhenxun.services.ai.run import RunContext
from zhenxun.services.log import logger


class BaseNode(ABC):
    """工作流节点统一抽象基类"""

    def __init__(
        self,
        name: str,
        requires_confirmation: bool = False,
        confirmation_message: str | None = None,
        failure_policy: BaseFailurePolicy | None = None,
    ):
        """
        初始化工作流节点基类。

        参数:
            name: 节点的唯一名称标识。
            requires_confirmation: 标记该节点在执行前是否需要人工介入授权 (HITL)，默认 False。
            confirmation_message: 挂起等待授权时，向前端/群聊展示的提示文案，默认 None。
            failure_policy: 该节点执行失败时的错误恢复与自愈策略，
                默认使用中断策略 (AbortPolicy)。
        """  # noqa: E501
        self.name = name
        self.requires_confirmation = requires_confirmation
        self.confirmation_message = confirmation_message
        self.failure_policy = failure_policy or AbortPolicy()

    @property
    @abstractmethod
    def node_type(self) -> StepType:
        """节点类型标识 (供子类实现)"""
        pass

    async def _handle_execution_failure(
        self, e: BaseException, step_input: StepInput, context: RunContext, attempt: int
    ) -> tuple[str, StepOutput | None, StepInput | None, Any]:
        """
        解析执行异常并应用容错策略
        """
        if isinstance(e, asyncio.CancelledError):
            raise e

        if isinstance(e, ControlFlowExit):
            logger.info(
                f"⏭️ [控制流拦截] Node '{self.name}' 触发中断信号: "
                f"{type(e).__name__} - {e}"
            )
            content = str(e)
            if getattr(e, "display_content", None):
                content = str(getattr(e, "display_content"))
            elif getattr(e, "display", None):
                content = str(getattr(e, "display"))
            elif getattr(e, "result_output", None):
                content = str(getattr(e, "result_output"))

            output = StepOutput(
                step_name=self.name,
                step_type=self.node_type,
                content=content,
                success=False,
                stop=True,
                error=str(e)
                if isinstance(e, AbortException | ToolFatalError)
                else None,
            )
            return "break", output, None, None

        logger.warning(f"Node '{self.name}' 执行发生异常: {e}")
        policy_result = await self.failure_policy.handle_failure(
            self, e, step_input, context
        )

        if policy_result.action == PolicyAction.RETRY:
            if policy_result.delay > 0:
                await asyncio.sleep(policy_result.delay)
            new_input = policy_result.new_input or step_input
            logger.debug(f"  🔄 [节点重试] `{self.name}` 进行第 {attempt} 次重试...")
            return "continue", None, new_input, None

        elif policy_result.action == PolicyAction.FALLBACK:
            fallback_node = policy_result.fallback_node
            fallback_name = getattr(fallback_node, "name", "FallbackNode")
            logger.info(
                f"🔀 节点 {self.name} 执行失败，触发降级路由至: {fallback_name}"
            )
            return "fallback", None, None, fallback_node

        elif policy_result.action == PolicyAction.CONTINUE:
            logger.warning(f"Node '{self.name}' 执行异常，已被策略自动跳过: {e}")
            output = StepOutput(
                step_name=self.name,
                step_type=self.node_type,
                content=f"节点执行失败，已通过策略自动跳过: {e}",
                success=False,
                stop=False,
                error=str(e),
            )
            return "break", output, None, None
        else:
            logger.error(f"Node '{self.name}' 执行崩溃，已被策略中断执行流: {e}")
            output = StepOutput(
                step_name=self.name,
                step_type=self.node_type,
                content=f"执行崩溃: {e}",
                success=False,
                stop=True,
                error=str(e),
            )
            return "break", output, None, None

    @abstractmethod
    async def run_stream(
        self, step_input: StepInput, context: RunContext
    ) -> AsyncIterator[Any]:
        """子类必须实现的核心流式执行逻辑"""
        yield None

    async def _forward_stream(
        self, stream: AsyncIterator[Any], output_box: list[StepOutput]
    ) -> AsyncIterator[Any]:
        """辅助方法：转发内部流事件，并将最终的 StepOutput 拦截放入 output_box 列表中"""
        async for event in stream:
            if isinstance(event, StepOutput):
                output_box.append(event)
            else:
                yield event

    async def aexecute(self, step_input: StepInput, context: RunContext) -> StepOutput:
        """非流式执行（聚合流并返回最终结果），子类无需重写"""
        output = None
        async for event in self.aexecute_stream(step_input, context):
            if isinstance(event, StepOutput):
                output = event

        if output is None:
            output = StepOutput(
                step_name=self.name,
                step_type=self.node_type,
                content="节点未产生有效输出",
                success=False,
            )
        return output

    async def aexecute_stream(
        self, step_input: StepInput, context: RunContext
    ) -> AsyncIterator[Any]:
        """标准化模板方法：处理缓存快进、授权挂起、异常熔断与生命周期事件分发"""
        logger.debug(f"  ⚙️ [节点] `{self.name}` 开始执行...")

        cached_out = context.state.get("__completed_steps__", {}).get(self.name)
        if (
            cached_out
            and cached_out.success
            and not getattr(cached_out, "is_paused", False)
        ):
            logger.debug(f"⏭️ 快进跳过已完成节点: {self.name}")

            yield cached_out
            return

        if self.requires_confirmation:
            if not context.state.get(f"__hitl_confirmed_{self.name}"):
                msg = (
                    self.confirmation_message
                    or f"⚠️ 工作流即将执行高危步骤：[{self.name}]，等待授权..."
                )
                logger.debug(f"  ⏸️ **[节点挂起]** `{self.name}`: {msg}")

                output = StepOutput(
                    step_name=self.name,
                    step_type=self.node_type,
                    content="[任务已挂起，等待人工授权/输入]",
                    success=True,
                    stop=True,
                    is_paused=True,
                    pause_reason=msg,
                )

                yield output
                return

        current_input = step_input
        attempt = 1

        while True:
            output = None
            try:
                async for event in self.run_stream(current_input, context):
                    if isinstance(event, StepOutput):
                        output = event
                        output.step_name = self.name
                        output.step_type = self.node_type
                    else:
                        yield event

                if output is None:
                    output = StepOutput(
                        step_name=self.name,
                        step_type=self.node_type,
                        content="执行完毕，无数据返回",
                        success=True,
                    )

                context.upstream_results[self.name] = output.content

                break

            except BaseException as e:
                (
                    action_cmd,
                    output,
                    new_input,
                    fallback_node,
                ) = await self._handle_execution_failure(
                    e, current_input, context, attempt
                )
                if action_cmd == "continue":
                    current_input = (
                        new_input if new_input is not None else current_input
                    )
                    attempt += 1
                    continue
                elif action_cmd == "fallback" and fallback_node:
                    async for evt in fallback_node.aexecute_stream(
                        current_input, context
                    ):
                        if isinstance(evt, StepOutput):
                            output = evt
                        else:
                            yield evt
                break

        yield output