mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-09 22:00:01 +08:00
✨ feat!(llm): 重构并升级大语言模型服务为全新 AI 智能体框架 (#2146)
* ✨ feat!(llm): 重构并升级大语言模型服务为全新 AI 智能体框架 - 【重构】将原 services/llm 重构并迁移至全新的 services/ai 架构，提供向下兼容垫片 - 【新增】引入 Agent、Team、Workflow 三大智能体与工作流编排范式 - 【新增】引入基于 RAG 的长期向量记忆与中期槽位记忆系统 - 【新增】引入基于 Docker 的安全代码执行沙箱环境 - 【新增】支持 MCP 协议，允许动态管理和调用 MCP 服务 - 【新增】引入输入输出安全合规护栏与自愈反思机制 - 【优化】重构并优化多厂商 API 适配器 (Gemini, OpenAI, DeepSeek, GLM 等) - 【优化】优化日志脱敏与 Token 预估机制 - 【移除】移除旧版 llm default 和 llm reset-key 命令，新增 llm mcp 管理命令 * 🔧 chore(deps): 更新项目依赖与配置 - 添加 mcp、jieba 和 aiodocker 依赖到配置文件及 requirements.txt - 在 pyright 配置中设置 reportMissingImports 为 none - 调整 .gitignore 中 resources 目录的忽略规则 * ♻️ refactor(tools): 重构工具终止机制并清理知识库日志输出 - 统一使用 `context.state["__end_run__"]` 替代 `EndRunResult` 控制任务结束 - 移除文件系统和向量知识库检索工具中 `ToolResult` 的 `.with_log` 调用 - 调整指令处理器（Directive）的返回值为 `tool_res.output` - 修复部分类型检查警告并优化联合类型判断语法 * ♻️ refactor(tools): 重构工具副作用指令与控制流熔断机制 - 引入 `DirectivePayload` 及 `ToolResult` 的子类以结构化表达工具副作用 - 移除通过 `context.state` 传递魔术变量的隐式控制流设计 - 重构 `DirectiveManager` 处理器接口，直接在处理器中修改 `AgentState` 并构建 `AgentRunResult` - 在 `StandardAgentExecutor` 中统一通过 `directive_manager` 调度工具返回的副作用指令 - 补全 `MessageBuilder` 中部分核心方法的文档注释 * 🐛 fix(sandbox): 修复 Docker 沙箱容器状态检测与会话清理逻辑 -【修复】修正 `is_alive` 中直接读取私有属性的问题，改用 `show()` 返回值 -【修复】解决 `execute_code` 中缓存的执行器与当前会话不一致的问题 -【优化】在清理工作区前增加容器存活检测，避免向已死容器发送请求 -【优化】创建容器时增加运行状态校验，若已停止则自动从缓存中移除并重建 -【优化】优化容器销毁和清理逻辑，静默处理容器不存在 (404) 的异常 * 📝 docs(core): 补充核心模块初始化方法的文档注释 * 🚨 auto fix by pre-commit hooks --------- Co-authored-by: webjoin111 <455457521@qq.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Rumio
co-authored by
webjoin111
pre-commit-ci[bot]
webjoin111
pre-commit-ci[bot]
parent
bdc1374848
commit
80fc5b86a7
@@ -0,0 +1,253 @@
|
||||
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
|
||||
Reference in New Issue
Block a user