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,329 @@
|
||||
import asyncio
|
||||
from collections.abc import AsyncIterator
|
||||
from typing import TYPE_CHECKING, Any
|
||||
import uuid
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from zhenxun.services.ai.flow.workflow.nodes import NodeSource
|
||||
from zhenxun.services.ai.run import StreamedRunResult
|
||||
|
||||
|
||||
from zhenxun.services.ai.core.exceptions import ControlFlowExit, ToolRetryError
|
||||
from zhenxun.services.ai.core.messages import PromptInput, UsageInfo
|
||||
from zhenxun.services.ai.core.stream_events import EventBus
|
||||
from zhenxun.services.ai.flow.base import BaseRunnable, BaseRuntimeConfig
|
||||
from zhenxun.services.ai.flow.workflow.nodes import Steps
|
||||
from zhenxun.services.ai.flow.workflow.types import (
|
||||
StepInput,
|
||||
StepOutput,
|
||||
WorkflowRunResult,
|
||||
)
|
||||
from zhenxun.services.ai.run import RunContext
|
||||
from zhenxun.services.ai.tools.core.tool import FunctionTool
|
||||
from zhenxun.services.log import logger
|
||||
|
||||
|
||||
class Workflow(BaseRunnable[WorkflowRunResult]):
|
||||
"""
|
||||
工作流顶层容器 (The Workflow Facade)。
|
||||
继承自 BaseRunnable，支持被作为节点嵌套在 Team 或 其他工作流中。
|
||||
"""
|
||||
|
||||
def __init__(self, name: str, steps: list["NodeSource"], description: str = ""):
|
||||
"""
|
||||
静态图元工作流容器初始化。
|
||||
|
||||
参数:
|
||||
name: 工作流的名称标识。
|
||||
steps: 工作流的节点列表（按列表顺序构成串行或嵌套结构）。
|
||||
description: 工作流的说明描述，用于被 Agent 调用时理解其功能。
|
||||
"""
|
||||
self.name = name
|
||||
self.description = description
|
||||
self.id = uuid.uuid4().hex
|
||||
|
||||
self.root_steps = Steps(steps=steps, name=f"{self.name}_Root")
|
||||
self.runtime_config = BaseRuntimeConfig(stateless=True)
|
||||
self.persona = None
|
||||
|
||||
def _build_result(
|
||||
self,
|
||||
initial_input: StepInput,
|
||||
safe_context: RunContext,
|
||||
final_output: StepOutput,
|
||||
) -> WorkflowRunResult:
|
||||
flat_outputs = {}
|
||||
|
||||
def _extract(out: StepOutput):
|
||||
flat_outputs[out.step_name] = out
|
||||
if out.steps:
|
||||
for o in out.steps:
|
||||
_extract(o)
|
||||
|
||||
if final_output:
|
||||
_extract(final_output)
|
||||
|
||||
paused_step = next(
|
||||
(
|
||||
v.step_name
|
||||
for v in reversed(list(flat_outputs.values()))
|
||||
if getattr(v, "is_paused", False) and v.step_name
|
||||
),
|
||||
None,
|
||||
)
|
||||
status = (
|
||||
"paused"
|
||||
if paused_step
|
||||
else ("completed" if final_output and final_output.success else "error")
|
||||
)
|
||||
|
||||
return WorkflowRunResult(
|
||||
workflow_id=self.id,
|
||||
workflow_name=self.name,
|
||||
status=status,
|
||||
original_input=initial_input.input,
|
||||
state=safe_context.state,
|
||||
step_outputs=flat_outputs,
|
||||
last_step_content=final_output.content if final_output else None,
|
||||
final_output=final_output,
|
||||
paused_step_name=paused_step,
|
||||
)
|
||||
|
||||
def bind(self, **kwargs: Any) -> Any:
|
||||
"""DI 注入语法糖"""
|
||||
from nonebot.params import Depends
|
||||
|
||||
async def _dependency() -> "Workflow":
|
||||
return self
|
||||
|
||||
return Depends(_dependency)
|
||||
|
||||
async def reply(
|
||||
self, prompt: PromptInput | None = None, reply_to: bool = False, **kwargs: Any
|
||||
) -> WorkflowRunResult:
|
||||
"""
|
||||
工作流交互执行语法糖，隐式提取上下文并自动将最终流水线产出发送回复给用户。
|
||||
|
||||
参数:
|
||||
prompt: 传入工作流入口根节点的初始参数或指令。
|
||||
reply_to: 是否将结果作为回复消息发送 (at用户或引用原消息)。
|
||||
kwargs: 追加的工作流附带参数 (additional_data)。
|
||||
|
||||
返回:
|
||||
WorkflowRunResult: 包含执行状态、断点快照、各节点产出的全量工作流结果对象。
|
||||
"""
|
||||
from zhenxun.utils.message import MessageUtils
|
||||
|
||||
ctx = RunContext()
|
||||
bot = ctx.get_bot()
|
||||
event = ctx.get_event()
|
||||
|
||||
res = await self.run(prompt=prompt, context=ctx, **kwargs)
|
||||
|
||||
if bot and event:
|
||||
if res.status == "completed" and res.final_output:
|
||||
msg = (
|
||||
str(res.final_output.content)
|
||||
if res.final_output.content
|
||||
else "执行完毕"
|
||||
)
|
||||
await MessageUtils.build_message(msg).send(reply_to=reply_to)
|
||||
elif res.status == "paused":
|
||||
pause_msg = (
|
||||
f"⏸️ 工作流执行已被挂起，停在步骤: {res.paused_step_name}。"
|
||||
"请提供授权或人工输入后继续。"
|
||||
)
|
||||
await MessageUtils.build_message(pause_msg).send(reply_to=reply_to)
|
||||
elif res.status == "error":
|
||||
err_msg = res.final_output.error if res.final_output else "未知异常"
|
||||
await MessageUtils.build_message(
|
||||
f"❌ 工作流执行发生错误: {err_msg}"
|
||||
).send(reply_to=reply_to)
|
||||
|
||||
return res
|
||||
|
||||
async def run(
|
||||
self,
|
||||
prompt: PromptInput | None = None,
|
||||
*,
|
||||
context: RunContext | None = None,
|
||||
**kwargs: Any,
|
||||
) -> WorkflowRunResult:
|
||||
"""
|
||||
工作流单次运行阻塞核心入口，遍历所有图元节点直至终止。
|
||||
|
||||
参数:
|
||||
prompt: 传入工作流入口根节点的初始参数或指令。
|
||||
context: 显式传入的会话与运行上下文。
|
||||
kwargs: 追加的工作流附带参数 (additional_data)。
|
||||
|
||||
返回:
|
||||
WorkflowRunResult: 包含执行状态、断点快照、各节点产出的全量工作流结果对象。
|
||||
"""
|
||||
session_id = (
|
||||
context.session_id if context and context.session_id else f"wf_{self.id}"
|
||||
)
|
||||
safe_context = context or RunContext(session_id=session_id)
|
||||
|
||||
logger.debug(f"🏭 **工作流 [{self.name}] 启动**")
|
||||
|
||||
initial_input = StepInput(input=prompt)
|
||||
if kwargs:
|
||||
initial_input.additional_data.update(kwargs)
|
||||
|
||||
try:
|
||||
final_output = await self.root_steps.aexecute(initial_input, safe_context)
|
||||
|
||||
logger.debug(f"🏭 **工作流 [{self.name}] 运行结束**")
|
||||
|
||||
return self._build_result(initial_input, safe_context, final_output)
|
||||
|
||||
except BaseException as e:
|
||||
if isinstance(e, ControlFlowExit):
|
||||
logger.debug(f"⏭️ 工作流执行被业务控制流安全中止: {e}")
|
||||
dummy_output = StepOutput(content=str(e), success=False)
|
||||
return self._build_result(initial_input, safe_context, dummy_output)
|
||||
|
||||
raise e
|
||||
|
||||
import contextlib
|
||||
|
||||
@contextlib.asynccontextmanager
|
||||
async def run_stream(
|
||||
self,
|
||||
prompt: PromptInput | None = None,
|
||||
*,
|
||||
context: RunContext | None = None,
|
||||
**kwargs: Any,
|
||||
) -> AsyncIterator["StreamedRunResult[Any]"]:
|
||||
"""对齐 BaseRunnable 接口的流式上下文管理器"""
|
||||
from zhenxun.services.ai.run import StreamedRunResult
|
||||
from zhenxun.services.ai.run.models import AgentRunError
|
||||
|
||||
event_bus = EventBus()
|
||||
if context:
|
||||
context.run.event_bus = event_bus
|
||||
|
||||
async def _execution_task():
|
||||
try:
|
||||
async for event in self._internal_stream(prompt, context, **kwargs):
|
||||
await event_bus.emit(event)
|
||||
except BaseException as e:
|
||||
await event_bus.emit(AgentRunError(error=e))
|
||||
finally:
|
||||
await event_bus.end()
|
||||
|
||||
task = asyncio.create_task(_execution_task())
|
||||
try:
|
||||
yield StreamedRunResult[Any](event_bus)
|
||||
finally:
|
||||
if not task.done():
|
||||
task.cancel()
|
||||
|
||||
async def _internal_stream(
|
||||
self,
|
||||
prompt: PromptInput | None = None,
|
||||
context: RunContext | None = None,
|
||||
**kwargs: Any,
|
||||
) -> AsyncIterator[Any]:
|
||||
"""原 arun_stream 逻辑改名，供内部 _execution_task 调用"""
|
||||
session_id = (
|
||||
context.session_id if context and context.session_id else f"wf_{self.id}"
|
||||
)
|
||||
safe_context = context or RunContext(session_id=session_id)
|
||||
|
||||
logger.debug(f"🏭 **工作流 [{self.name}] 启动**")
|
||||
|
||||
initial_input = StepInput(input=prompt)
|
||||
if kwargs:
|
||||
initial_input.additional_data.update(kwargs)
|
||||
|
||||
try:
|
||||
final_output = None
|
||||
async for event in self.root_steps.aexecute_stream(
|
||||
initial_input, safe_context
|
||||
):
|
||||
if isinstance(event, StepOutput):
|
||||
final_output = event
|
||||
else:
|
||||
yield event
|
||||
|
||||
if final_output:
|
||||
logger.debug(f"🏭 **工作流 [{self.name}] 运行结束**")
|
||||
|
||||
from zhenxun.services.ai.run import AgentRunResult
|
||||
from zhenxun.services.ai.run.models import AgentRunEnd
|
||||
|
||||
wf_result = self._build_result(
|
||||
initial_input, safe_context, final_output
|
||||
)
|
||||
agent_res = AgentRunResult(
|
||||
output=wf_result.last_step_content,
|
||||
structured_data=wf_result,
|
||||
usage=UsageInfo(),
|
||||
)
|
||||
yield AgentRunEnd(result=agent_res)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
async def acontinue_run(
|
||||
self,
|
||||
run_result: WorkflowRunResult,
|
||||
user_auth_data: dict[str, Any] | None = None,
|
||||
context: RunContext | None = None,
|
||||
) -> WorkflowRunResult:
|
||||
safe_context = context or RunContext(session_id=f"wf_{self.id}")
|
||||
safe_context.state.update(run_result.state)
|
||||
|
||||
safe_context.state["__completed_steps__"] = run_result.step_outputs.copy()
|
||||
for step_name, out in run_result.step_outputs.items():
|
||||
safe_context.upstream_results[step_name] = out.content
|
||||
|
||||
if run_result.paused_step_name:
|
||||
safe_context.state[f"__hitl_confirmed_{run_result.paused_step_name}"] = True
|
||||
if user_auth_data:
|
||||
safe_context.state[f"__hitl_input_{run_result.paused_step_name}"] = (
|
||||
user_auth_data
|
||||
)
|
||||
|
||||
resume_input = StepInput(
|
||||
input=run_result.original_input,
|
||||
previous_step_content=run_result.last_step_content,
|
||||
)
|
||||
|
||||
logger.debug(
|
||||
f"🚀 工作流 [{self.name}] 状态已恢复，"
|
||||
f"正在快进到步骤: {run_result.paused_step_name}..."
|
||||
)
|
||||
|
||||
final_output = await self.root_steps.aexecute(resume_input, safe_context)
|
||||
|
||||
return self._build_result(resume_input, safe_context, final_output)
|
||||
|
||||
def as_tool(self, tool_name: str | None = None) -> FunctionTool:
|
||||
async def _execute_workflow_tool(prompt: str, context: RunContext) -> str:
|
||||
run_result = await self.run(prompt=prompt, context=context)
|
||||
output = run_result.final_output
|
||||
|
||||
if output and output.success:
|
||||
return (
|
||||
f"工作流 [{self.name}] 执行完毕。最终流水线产出:\n{output.content}"
|
||||
)
|
||||
|
||||
raise ToolRetryError(
|
||||
f"工作流执行失败: {output.error if output else 'unknown'}，"
|
||||
"请尝试换种方式处理。"
|
||||
)
|
||||
|
||||
final_tool_name = tool_name or f"trigger_workflow_{self.id}"
|
||||
|
||||
tool_desc = (
|
||||
f"触发执行专属流水线: {self.name}。\n"
|
||||
f"描述: {self.description}\n"
|
||||
f"注意：如果你认为该工作流能完全解决用户的问题，请立刻调用此工具，"
|
||||
f"并将用户的诉求提炼后作为 prompt 传入。"
|
||||
)
|
||||
|
||||
return FunctionTool(
|
||||
func=_execute_workflow_tool, name=final_tool_name, description=tool_desc
|
||||
)
|
||||
Reference in New Issue
Block a user