mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-28 23:50:03 +08:00
254 lines
9.0 KiB
Python
254 lines
9.0 KiB
Python
|
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
|