mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-12 23:40:03 +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,279 @@
|
||||
"""
|
||||
运行时（Run）相关核心类型定义
|
||||
"""
|
||||
|
||||
from collections.abc import AsyncIterator
|
||||
import json
|
||||
from typing import Any, Generic, cast
|
||||
from typing_extensions import TypeVar
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
|
||||
|
||||
from zhenxun.services.ai.core.messages import AgentMessage, LLMMessage, UsageInfo
|
||||
from zhenxun.services.ai.core.stream_events import (
|
||||
AgentStreamEvent,
|
||||
EventBus,
|
||||
ToolCallStartEvent,
|
||||
ToolStreamChunkEvent,
|
||||
)
|
||||
from zhenxun.utils.pydantic_compat import model_dump, model_validator
|
||||
|
||||
|
||||
class ChatSummary(BaseModel):
|
||||
total: int = 0
|
||||
"""大模型调用总次数"""
|
||||
total_latency_ms: float = 0.0
|
||||
"""大模型调用总耗时（毫秒）"""
|
||||
by_stop_reason: dict[str, int] = Field(default_factory=dict)
|
||||
"""按停止原因分类的大模型调用计数"""
|
||||
|
||||
|
||||
class ToolSummary(BaseModel):
|
||||
total: int = 0
|
||||
"""工具执行总次数"""
|
||||
ok: int = 0
|
||||
"""工具成功执行次数"""
|
||||
error: int = 0
|
||||
"""工具执行失败次数"""
|
||||
total_latency_ms: float = 0.0
|
||||
"""工具执行总耗时（毫秒）"""
|
||||
by_name: dict[str, dict[str, Any]] = Field(default_factory=dict)
|
||||
"""按工具名称细分的执行状态统计"""
|
||||
|
||||
|
||||
class AgentRunSummary(BaseModel):
|
||||
"""Agent 单次运行的全局可观测性遥测摘要"""
|
||||
|
||||
chats: ChatSummary = Field(default_factory=ChatSummary)
|
||||
"""大模型调用遥测摘要"""
|
||||
tools: ToolSummary = Field(default_factory=ToolSummary)
|
||||
"""工具执行遥测摘要"""
|
||||
usage: UsageInfo = Field(default_factory=UsageInfo)
|
||||
"""Token 消耗总计"""
|
||||
total_latency_ms: float = 0.0
|
||||
"""智能体运行总耗时（毫秒）"""
|
||||
|
||||
|
||||
class HandoffPayload(BaseModel):
|
||||
"""移交信息载荷"""
|
||||
|
||||
target: str
|
||||
"""移交的目标智能体名称"""
|
||||
reason: str = ""
|
||||
"""移交的原因描述"""
|
||||
context_data: Any = ""
|
||||
"""随移交传递的上下文数据"""
|
||||
|
||||
|
||||
OutputDataT = TypeVar("OutputDataT", default=str)
|
||||
|
||||
|
||||
class AgentRunResult(BaseModel, Generic[OutputDataT]):
|
||||
"""Agent 单次无状态运行的结果"""
|
||||
|
||||
output: OutputDataT
|
||||
"""最终输出数据"""
|
||||
messages: list[AgentMessage] = Field(default_factory=list)
|
||||
"""本次运行产生/更新的历史消息"""
|
||||
usage: UsageInfo = Field(default_factory=UsageInfo)
|
||||
"""本次运行的Token消耗总计"""
|
||||
structured_data: Any | None = None
|
||||
"""拦截到的结构化结果字典"""
|
||||
telemetry: AgentRunSummary | None = None
|
||||
"""单次运行的完整可观测性遥测摘要"""
|
||||
handoff: HandoffPayload | None = None
|
||||
"""向外抛出的软移交载荷（存在时说明Agent发起了移交请求）"""
|
||||
|
||||
class Config:
|
||||
arbitrary_types_allowed = True
|
||||
|
||||
@property
|
||||
def llm_messages(self) -> list[LLMMessage]:
|
||||
"""动态视图：过滤掉内部业务事件 (AgentEvent)，
|
||||
仅返回纯净的底层聊天消息历史"""
|
||||
return [m for m in self.messages if isinstance(m, LLMMessage)]
|
||||
|
||||
|
||||
class AgentRunStart(AgentStreamEvent):
|
||||
"""智能体运行开始"""
|
||||
|
||||
agent_name: str
|
||||
"""启动运行的智能体名称"""
|
||||
|
||||
|
||||
class AgentRunError(AgentStreamEvent):
|
||||
"""智能体运行发生异常"""
|
||||
|
||||
error: BaseException
|
||||
"""智能体运行过程中抛出的异常"""
|
||||
|
||||
|
||||
class AgentRunEnd(AgentStreamEvent):
|
||||
"""智能体运行完全结束"""
|
||||
|
||||
result: AgentRunResult[Any]
|
||||
"""智能体运行结束后的完整结果"""
|
||||
|
||||
|
||||
class StreamedRunResult(Generic[OutputDataT]):
|
||||
"""
|
||||
智能体流式运行的结果代理对象。
|
||||
提供高度解耦的方法来消费底层事件流，支持获取纯净文本或全部事件。
|
||||
"""
|
||||
|
||||
def __init__(self, event_bus: EventBus):
|
||||
self._event_bus = event_bus
|
||||
self.is_complete: bool = False
|
||||
self._result: AgentRunResult[OutputDataT] | None = None
|
||||
|
||||
async def stream_events(self) -> AsyncIterator[Any]:
|
||||
"""获取底层的所有原始事件（包含工具调用过程等）"""
|
||||
from zhenxun.services.ai.run.models import AgentRunEnd, AgentRunError
|
||||
|
||||
async for event in self._event_bus:
|
||||
if isinstance(event, AgentRunEnd):
|
||||
self._result = cast(AgentRunResult[OutputDataT], event.result)
|
||||
self.is_complete = True
|
||||
elif isinstance(event, AgentRunError):
|
||||
raise event.error.with_traceback(None) from None
|
||||
yield event
|
||||
|
||||
async def stream_text(self, delta: bool = False) -> AsyncIterator[str]:
|
||||
"""
|
||||
过滤大模型的输出文本。
|
||||
"""
|
||||
full_text = ""
|
||||
async for _ in self.stream_events():
|
||||
pass
|
||||
|
||||
if self._result is not None:
|
||||
output = self._result.output
|
||||
if isinstance(output, str):
|
||||
full_text = output
|
||||
else:
|
||||
if isinstance(output, BaseModel):
|
||||
full_text = json.dumps(model_dump(output), ensure_ascii=False)
|
||||
else:
|
||||
full_text = str(output)
|
||||
|
||||
if delta:
|
||||
yield full_text
|
||||
else:
|
||||
yield full_text
|
||||
|
||||
async def get_output(self) -> OutputDataT:
|
||||
"""阻塞并等待整个 Agent 执行完毕，返回最终的解析输出数据"""
|
||||
if self._result is not None:
|
||||
return self._result.output
|
||||
|
||||
async for _ in self.stream_events():
|
||||
pass
|
||||
|
||||
if self._result is None:
|
||||
raise RuntimeError("Agent 运行异常结束，未产生最终结果。")
|
||||
|
||||
return self._result.output
|
||||
|
||||
async def get_run_result(self) -> AgentRunResult[OutputDataT]:
|
||||
"""获取完整的运行结果对象（包含 Token 消耗等）"""
|
||||
if self._result is not None:
|
||||
return self._result
|
||||
|
||||
await self.get_output()
|
||||
|
||||
return cast(AgentRunResult[OutputDataT], self._result)
|
||||
|
||||
async def forward_to(
|
||||
self, target_event_bus: EventBus | None, prefix_name: str
|
||||
) -> AgentRunResult[OutputDataT]:
|
||||
"""将底层的事件流自动格式化并转发给另一个事件发射器，
|
||||
常用于 DelegateTool 嵌套调用"""
|
||||
async for event in self.stream_events():
|
||||
if not target_event_bus:
|
||||
continue
|
||||
|
||||
if isinstance(event, ToolStreamChunkEvent):
|
||||
await target_event_bus.emit(
|
||||
ToolStreamChunkEvent(
|
||||
tool_name=f"{prefix_name} -> {event.tool_name}",
|
||||
content=event.content,
|
||||
metadata=event.metadata,
|
||||
)
|
||||
)
|
||||
elif isinstance(event, ToolCallStartEvent):
|
||||
intent_str = (
|
||||
f" (意图: {event.intent})" if getattr(event, "intent", None) else ""
|
||||
)
|
||||
await target_event_bus.emit(
|
||||
ToolStreamChunkEvent(
|
||||
tool_name=prefix_name,
|
||||
content=f"🔁 正在调用工具: {event.tool_name}...{intent_str}",
|
||||
)
|
||||
)
|
||||
|
||||
return await self.get_run_result()
|
||||
|
||||
|
||||
class TaskResult(BaseModel):
|
||||
"""单个数据契约任务的执行结果"""
|
||||
|
||||
task_id: str
|
||||
"""关联的任务唯一 ID"""
|
||||
|
||||
output: Any
|
||||
"""任务的实际产出（如果是结构化任务，则为解析后的 Pydantic 实例；否则为纯文本）"""
|
||||
|
||||
raw_response: str | None = None
|
||||
"""大模型返回的原始纯文本内容"""
|
||||
|
||||
usage: UsageInfo = Field(default_factory=UsageInfo)
|
||||
"""该任务执行期间的 Token 消耗统计"""
|
||||
|
||||
model_config = ConfigDict(arbitrary_types_allowed=True)
|
||||
|
||||
|
||||
class Task(BaseModel):
|
||||
"""标准化数据契约（意图载体 Payload），定义大模型需要做什么及产出什么格式"""
|
||||
|
||||
id: str = Field(default_factory=lambda: __import__("uuid").uuid4().hex)
|
||||
"""任务的唯一标识符"""
|
||||
|
||||
name: str | None = None
|
||||
"""任务的简短名称"""
|
||||
|
||||
description: str
|
||||
"""详细的任务指令（告诉大模型具体需要做什么）"""
|
||||
|
||||
expected_output: str
|
||||
"""预期输出的自然语言描述（指导大模型如何组织最终答案）"""
|
||||
|
||||
response_model: Any | None = None
|
||||
"""强制要求返回的强类型结构 (Pydantic Model) 或
|
||||
OutputDefinition，为空则返回普通文本"""
|
||||
|
||||
tools: list[str | Any] | None = None
|
||||
"""针对此特定任务动态追加或覆盖的工具列表"""
|
||||
|
||||
guardrails: list[Any] | None = None
|
||||
"""护栏验证列表。支持传入函数、BaseGuardrail 实例，
|
||||
或直接传入自然语言字符串规则（自动转为 LLM 裁判）"""
|
||||
|
||||
_parsed_guardrails: list[Any] = PrivateAttr(default_factory=list)
|
||||
|
||||
model_config = ConfigDict(arbitrary_types_allowed=True)
|
||||
|
||||
@model_validator(mode="after")
|
||||
def _parse_and_set_guardrails(self) -> "Task":
|
||||
from zhenxun.services.ai.guardrails import parse_guardrails
|
||||
|
||||
self._parsed_guardrails = parse_guardrails(self.guardrails)
|
||||
return self
|
||||
|
||||
|
||||
__all__ = [
|
||||
"AgentRunResult",
|
||||
"OutputDataT",
|
||||
"StreamedRunResult",
|
||||
"Task",
|
||||
"TaskResult",
|
||||
]
|
||||
Reference in New Issue
Block a user