mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-10 22:30:02 +08:00
0b32d69c9c
* ♻️ refactor(ai): 重构 AI 服务模块并完善文档注释 - 【重构】统一清理并优化所有 AI 服务模块文件的导入语句，将其移至文件顶部 - 【重构】重构 `hooks.py` 中的 `Hooks` 派发逻辑，使用通用管道函数消除重复代码，并引入 `HookPoint` 描述符 - 【重构】重构工具装饰器实现，新增 `toolkit` 类装饰器，优化 `BaseToolkit` 配置合并与前缀处理 - 【功能】Docker 沙箱容器创建时支持自动注入系统代理环境变量并配置 `ExtraHosts` - 【功能】Jupyter 服务启动前自动清理旧进程并初始化临时目录权限 - 【修复】优化 Pydantic 结构化输出校验失败时的错误信息提取，提供更详细的字段级错误反馈 - 【修复】在 `api.py` 中避免将 `ModelRetry` 和 `ControlFlowExit` 异常错误地包装为 `LLMException` - 【文档】为 AI 服务、沙箱、工具链、工作流等核心模块补充完整的 Docstring 和类型注释 * 📝 docs(ai): 补全核心模块文档注释并清理冗余代码 - 补全 `run/context`、`run/hooks` 和 `tools/engine/registry` 中类与方法的中文文档注释 - 清理 `tools/providers/builtin/sandbox` 中未使用的 `PythonPluginProtocol` 协议及相关导入 - 规范化部分代码的格式与尾随逗号 * ♻️ refactor!(flow): 重构 Task 为 AgentTask 并优化工作流元数据定义 - 【Breaking Change】将 `Task` 重命名为 `AgentTask` 以避免命名冲突 - 更新 Agent、Team、Workflow 等模块中的类型声明与相关逻辑 - 引入 `AutoNodeMeta` 强类型元数据，替换工作流装饰器中的裸字典定义 - 将 `StepMeta`、`ConditionMeta` 和 `RouterMeta` 统一移动至 `types.py` - 优化 `RunnableNode` 对上游 `AgentTask` 的处理与拼接逻辑 - 调整团队协作策略中 `FinishAction` 的返回值为完整结果对象 * ♻️ refactor(workflow): 移除人工确认机制并重构错误策略 - 移除工作流节点的人工确认（HITL）与挂起继续机制 - 删除 `auto` 自动化工作流及相关装饰器文件 - 将错误处理策略类从 `types.py` 拆分并移动到新文件 `policies.py` - 优化节点执行失败时的异常信息格式化输出 - 移除 `WorkflowRunResult` 和 `StepOutput` 中与挂起相关的状态字段 * 🚨 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>
378 lines
15 KiB
Python
378 lines
15 KiB
Python
import asyncio
|
|
from collections.abc import Callable, Mapping, Sequence
|
|
from pathlib import Path
|
|
from typing import Any
|
|
from typing_extensions import Self
|
|
|
|
from pydantic import BaseModel
|
|
|
|
from zhenxun.services.ai.capabilities import AbstractCapability, DynamicCapability
|
|
from zhenxun.services.ai.core.exceptions import ConcurrencyInterruptException
|
|
from zhenxun.services.ai.core.messages import PromptInput
|
|
from zhenxun.services.ai.core.models import CancellationToken
|
|
from zhenxun.services.ai.core.stream_events import EventBus
|
|
from zhenxun.services.ai.flow.agent.agent import CapabilitySource, ToolSource
|
|
from zhenxun.services.ai.flow.agent.models import Persona
|
|
from zhenxun.services.ai.flow.base import BaseRunnable
|
|
from zhenxun.services.ai.flow.team.models import TeamRuntimeConfig, Transition
|
|
from zhenxun.services.ai.flow.team.router import BaseRouter
|
|
from zhenxun.services.ai.flow.team.strategy import (
|
|
BaseTeamStrategy,
|
|
)
|
|
from zhenxun.services.ai.run import AgentRunResult, AgentTask, RunContext
|
|
from zhenxun.services.ai.tools.providers.skills.models import Skill, SkillSource
|
|
from zhenxun.utils.utils import infer_plugin_namespace
|
|
|
|
|
|
class Team(BaseRunnable[AgentRunResult[Any]]):
|
|
"""
|
|
多智能体动态编排与路由控制器 (Facade)。
|
|
继承自 BaseRunnable，支持被嵌套在其他 Team 或 Workflow 中。
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
name: str,
|
|
members: list[BaseRunnable[Any]],
|
|
model: str | Callable[[], str] | None = None,
|
|
strategy: BaseTeamStrategy | None = None,
|
|
description: str | None = None,
|
|
persona: Persona | dict | None = None,
|
|
runtime_config: TeamRuntimeConfig | dict | None = None,
|
|
capabilities: list[CapabilitySource] | None = None,
|
|
skills: Sequence[str | Path | Skill | SkillSource] | None = None,
|
|
):
|
|
"""
|
|
多智能体协作团队初始化。
|
|
|
|
参数:
|
|
name: 团队的名称标识。
|
|
members: 团队成员列表，可以包含 Agent、Workflow 或其他 Team。
|
|
model: (可选) 团队的统一默认模型，将自动被内部的 Leader/Router 继承。
|
|
strategy: (可选) 团队协作策略实例。
|
|
若不传入，必须随后使用 `.with_xxx()` 链式方法配置。
|
|
description: 团队的职能描述，用于上层节点路由。
|
|
persona: 团队的整体人设或宏观设定。
|
|
runtime_config: 团队级别的运行时宏观配置.
|
|
"""
|
|
self.name = name
|
|
self.members = members
|
|
self.model = model
|
|
self.strategy = strategy
|
|
self.description = (
|
|
description
|
|
or f"一个名为 {self.name} 的协作团队，包含 {len(self.members)} 个处理节点。"
|
|
)
|
|
self.persona = persona
|
|
|
|
self.namespace = infer_plugin_namespace() or "unknown"
|
|
|
|
self.capabilities: list[Any] = []
|
|
if capabilities:
|
|
for cap in capabilities:
|
|
if isinstance(cap, AbstractCapability):
|
|
self.capabilities.append(cap)
|
|
elif callable(cap):
|
|
self.capabilities.append(DynamicCapability(cap))
|
|
|
|
if isinstance(runtime_config, dict):
|
|
runtime_config = TeamRuntimeConfig(**runtime_config)
|
|
self.runtime_config = runtime_config or TeamRuntimeConfig(stateless=True)
|
|
|
|
if skills:
|
|
from zhenxun.services.ai.tools.providers.skills.capabilities import (
|
|
SkillCapability,
|
|
)
|
|
|
|
self.capabilities.append(
|
|
SkillCapability(skills=skills, namespace=self.namespace)
|
|
)
|
|
|
|
self.selector_func = (
|
|
getattr(strategy, "selector_func", None) if strategy else None
|
|
)
|
|
|
|
def with_strategy(self, strategy: BaseTeamStrategy) -> Self:
|
|
"""
|
|
挂载自定义的团队协作策略。
|
|
|
|
该方法为第三方扩展策略提供了通用注入通道。
|
|
|
|
参数:
|
|
strategy: 自定义的、继承自 BaseTeamStrategy 的团队协作策略实例。
|
|
"""
|
|
self.strategy = strategy
|
|
self.selector_func = getattr(strategy, "selector_func", None)
|
|
return self
|
|
|
|
def with_routing(
|
|
self,
|
|
state_flow: (
|
|
Mapping[str, Sequence[Transition | str | Any]] | Callable | None
|
|
) = None,
|
|
selector_func: Callable[..., str | None] | None = None,
|
|
router: BaseRouter | None = None,
|
|
leader_model: str | None = None,
|
|
leader_tools: list[ToolSource] | None = None,
|
|
custom_prompt: str | None = None,
|
|
) -> Self:
|
|
"""
|
|
应用路由策略，基于挂载的 Router 进行最合适的专家动态分发。
|
|
|
|
路由策略初始化，通过决策大脑动态路由，将不同的输入重定向至对应的下级智能体。
|
|
|
|
参数:
|
|
state_flow: 状态流转规则字典或动态函数，定义成员之间控制流的物理走向。
|
|
selector_func: 极速硬路由的静态选择函数，返回目标智能体名称。
|
|
router: 自定义的动态路由器实例 (如 LLMRouter, RegexRouter 等)。
|
|
leader_model: 路由节点 (Leader) 使用的大模型名称，若为空则默认继承全局。
|
|
leader_tools: 挂载给路由节点 (Leader) 的专属工具列表。
|
|
custom_prompt: 自定义系统提示词，用于覆盖默认的路由系统提示词。
|
|
"""
|
|
from zhenxun.services.ai.flow.team.strategy import RouteStrategy
|
|
|
|
self.strategy = RouteStrategy(
|
|
state_flow=state_flow,
|
|
selector_func=selector_func,
|
|
router=router,
|
|
leader_model=leader_model,
|
|
leader_tools=leader_tools,
|
|
custom_prompt=custom_prompt,
|
|
)
|
|
self.selector_func = selector_func
|
|
return self
|
|
|
|
def with_coordination(
|
|
self,
|
|
leader_model: str | None = None,
|
|
leader_tools: list[ToolSource] | None = None,
|
|
custom_prompt: str | None = None,
|
|
) -> Self:
|
|
"""
|
|
应用协作策略，Leader 自主规划并主动将子任务委派给 Sub-Agents，最后汇总结果。
|
|
|
|
协作策略初始化，Leader 主动拆解任务并挂载委托工具，
|
|
委派给 Sub-Agents 并汇总结果。
|
|
|
|
参数:
|
|
leader_model: 协调节点 (Leader) 使用的大模型名称，若为空则默认继承全局。
|
|
leader_tools: 挂载给协调节点 (Leader) 的专属附加工具列表。
|
|
custom_prompt: 自定义系统提示词，用于覆盖默认的协调系统提示词。
|
|
"""
|
|
from zhenxun.services.ai.flow.team.strategy import CoordinateStrategy
|
|
|
|
self.strategy = CoordinateStrategy(
|
|
leader_model=leader_model,
|
|
leader_tools=leader_tools,
|
|
custom_prompt=custom_prompt,
|
|
)
|
|
return self
|
|
|
|
def with_broadcast(
|
|
self,
|
|
leader_model: str | None = None,
|
|
leader_tools: list[ToolSource] | None = None,
|
|
custom_prompt: str | None = None,
|
|
) -> Self:
|
|
"""
|
|
应用广播策略，并发让所有成员处理同一个任务，最后由 Leader 总结。
|
|
|
|
广播策略初始化，并发让所有成员处理同一个任务，汇总多方报告，最后由 Leader 总结。
|
|
|
|
参数:
|
|
leader_model: 总结节点 (Leader) 使用的大模型名称，若为空则默认继承全局。
|
|
leader_tools: 挂载给总结节点 (Leader) 的专属附加工具列表。
|
|
custom_prompt: 自定义系统提示词，用于覆盖默认的广播总结系统提示词。
|
|
"""
|
|
from zhenxun.services.ai.flow.team.strategy import BroadcastStrategy
|
|
|
|
self.strategy = BroadcastStrategy(
|
|
leader_model=leader_model,
|
|
leader_tools=leader_tools,
|
|
custom_prompt=custom_prompt,
|
|
)
|
|
return self
|
|
|
|
def with_task(
|
|
self,
|
|
leader_model: str | None = None,
|
|
leader_tools: list[ToolSource] | None = None,
|
|
max_iterations: int = 15,
|
|
blackboard_schema: type[BaseModel] | None = None,
|
|
initial_blackboard_state: BaseModel | None = None,
|
|
custom_prompt: str | None = None,
|
|
) -> Self:
|
|
"""
|
|
应用任务规划策略，Leader 利用工具箱在黑板上拆解任务、
|
|
管理依赖并驱动 Member 执行。
|
|
|
|
任务规划策略初始化，Leader 利用看板在黑板上拆解任务、
|
|
管理依赖并驱动 Member 异步推进。
|
|
|
|
参数:
|
|
leader_model: 规划节点 (Leader) 使用的大模型名称，若为空则默认继承全局。
|
|
leader_tools: 挂载给规划节点 (Leader) 的专属附加工具列表。
|
|
max_iterations: 引擎驱动的状态机最大迭代/循环次数，防止死循环。
|
|
blackboard_schema: 团队共享黑板的数据结构类型 (Pydantic Model 类)。
|
|
initial_blackboard_state: 共享黑板的初始数据状态实例。
|
|
custom_prompt: 自定义系统提示词，用于覆盖默认的规划系统提示词。
|
|
"""
|
|
from zhenxun.services.ai.flow.team.strategy import TaskStrategy
|
|
|
|
self.strategy = TaskStrategy(
|
|
leader_model=leader_model,
|
|
leader_tools=leader_tools,
|
|
max_iterations=max_iterations,
|
|
blackboard_schema=blackboard_schema,
|
|
initial_blackboard_state=initial_blackboard_state,
|
|
custom_prompt=custom_prompt,
|
|
)
|
|
return self
|
|
|
|
def _ensure_strategy(self):
|
|
if self.strategy is None:
|
|
raise RuntimeError(
|
|
f"Team '{self.name}' 尚未绑定任何协作策略！"
|
|
"请先调用 .with_routing() 等链式方法进行配置，"
|
|
"或在初始化时传入 strategy 参数。"
|
|
)
|
|
|
|
async def run(
|
|
self,
|
|
prompt: PromptInput | AgentTask | None = None,
|
|
*,
|
|
context: "RunContext | None" = None,
|
|
capabilities: list[CapabilitySource] | None = None,
|
|
skills: Sequence[str | Path | Skill | SkillSource] | None = None,
|
|
**kwargs: Any,
|
|
) -> AgentRunResult[Any]:
|
|
"""
|
|
团队级运行阻塞核心入口，内部静默分配任务给成员直至汇总结束。
|
|
|
|
参数:
|
|
prompt: 派发给多智能体团队的任务描述 or 契约对象 (AgentTask)。
|
|
context: 显式传入的会话与运行上下文。
|
|
capabilities: 仅针对本次团队执行动态注入的临时拦截器列表。
|
|
kwargs: 透传的其他附加参数。
|
|
|
|
返回:
|
|
AgentRunResult[Any]: 包含最终融合输出、消息历史和用量统计的运行结果对象。
|
|
"""
|
|
self._ensure_strategy()
|
|
if skills:
|
|
from zhenxun.services.ai.tools.providers.skills.capabilities import (
|
|
SkillCapability,
|
|
)
|
|
|
|
capabilities = list(capabilities) if capabilities else []
|
|
capabilities.append(
|
|
SkillCapability(skills=skills, namespace=self.namespace)
|
|
)
|
|
|
|
return await super().run(
|
|
prompt=prompt, context=context, capabilities=capabilities, **kwargs
|
|
)
|
|
|
|
import contextlib
|
|
|
|
@contextlib.asynccontextmanager
|
|
async def run_stream(
|
|
self,
|
|
prompt: PromptInput | AgentTask | None = None,
|
|
*,
|
|
context: "RunContext | None" = None,
|
|
capabilities: list[CapabilitySource] | None = None,
|
|
skills: Sequence[str | Path | Skill | SkillSource] | None = None,
|
|
**kwargs: Any,
|
|
):
|
|
self._ensure_strategy()
|
|
|
|
if context is None:
|
|
context = RunContext()
|
|
|
|
if not hasattr(context, "capabilities"):
|
|
context.capabilities = []
|
|
|
|
if hasattr(self, "capabilities") and self.capabilities:
|
|
context.capabilities.extend(self.capabilities)
|
|
|
|
if skills:
|
|
from zhenxun.services.ai.tools.providers.skills.capabilities import (
|
|
SkillCapability,
|
|
)
|
|
|
|
capabilities = list(capabilities) if capabilities else []
|
|
capabilities.append(
|
|
SkillCapability(skills=skills, namespace=self.namespace)
|
|
)
|
|
|
|
if capabilities:
|
|
for cap in capabilities:
|
|
if isinstance(cap, AbstractCapability):
|
|
context.capabilities.append(cap)
|
|
elif callable(cap):
|
|
context.capabilities.append(DynamicCapability(cap))
|
|
|
|
from zhenxun.services.ai.flow.team.runner import TeamRunner
|
|
from zhenxun.services.ai.run import StreamedRunResult
|
|
|
|
event_bus = EventBus()
|
|
context.run.event_bus = event_bus
|
|
assert self.strategy is not None
|
|
runner = TeamRunner(self, self.strategy)
|
|
|
|
policy = getattr(self.runtime_config, "concurrency_policy", None)
|
|
if policy is None:
|
|
from zhenxun.services.ai.flow.base import ConcurrencyPolicy
|
|
|
|
policy = (
|
|
ConcurrencyPolicy.ALLOW
|
|
if getattr(self.runtime_config, "stateless", True)
|
|
else ConcurrencyPolicy.QUEUE
|
|
)
|
|
|
|
intervention_policy = getattr(self.runtime_config, "intervention_policy", None)
|
|
|
|
from zhenxun.services.ai.utils import ContextUtils
|
|
|
|
lock_id = ContextUtils.extract_concurrency_lock_id(
|
|
context,
|
|
getattr(self.runtime_config, "concurrency_scope", None),
|
|
context.session_id or "default_session",
|
|
)
|
|
|
|
async def _execution_task():
|
|
from zhenxun.services.ai.flow.concurrency import apply_concurrency_policy
|
|
|
|
cancel_token = context.run.cancellation_token or CancellationToken()
|
|
context.run.cancellation_token = cancel_token
|
|
|
|
try:
|
|
async with apply_concurrency_policy(
|
|
session_id=context.session_id or "default_session",
|
|
lock_id=lock_id,
|
|
policy=policy,
|
|
cancel_token=cancel_token,
|
|
intervention_policy=intervention_policy,
|
|
message=prompt,
|
|
):
|
|
async for event in runner.run_stream(prompt, context, **kwargs):
|
|
await event_bus.emit(event)
|
|
except BaseException as e:
|
|
from zhenxun.services.ai.run.models import AgentRunError
|
|
|
|
if isinstance(e, asyncio.CancelledError):
|
|
e = ConcurrencyInterruptException("团队执行已被新请求打断并接管")
|
|
await event_bus.emit(AgentRunError(error=e))
|
|
finally:
|
|
await event_bus.end()
|
|
|
|
task = asyncio.create_task(_execution_task())
|
|
result_obj = StreamedRunResult[Any](event_bus)
|
|
|
|
try:
|
|
yield result_obj
|
|
finally:
|
|
if not task.done():
|
|
task.cancel()
|