mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-10-19 11:10:10 +08:00
♻️ refactor(tools): 重构工具装饰器系统并优化沙箱与文档注释 (#2147)
* ♻️ 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>
This commit is contained in:
Rumio
co-authored by
webjoin111
pre-commit-ci[bot]
webjoin111
pre-commit-ci[bot]
parent
80fc5b86a7
commit
0b32d69c9c
@@ -6,10 +6,16 @@ from typing import Any, Generic, cast
|
||||
|
||||
from zhenxun.services.ai.capabilities import (
|
||||
AbstractCapability,
|
||||
CombinedCapability,
|
||||
DynamicCapability,
|
||||
)
|
||||
from zhenxun.services.ai.config import get_llm_config
|
||||
from zhenxun.services.ai.context.knowledge.base import BaseKnowledge
|
||||
from zhenxun.services.ai.context.memory.builder import MemoryBuilder
|
||||
from zhenxun.services.ai.context.memory.capabilities import (
|
||||
AgenticMemoryCapability,
|
||||
SlotMemoryCapability,
|
||||
)
|
||||
from zhenxun.services.ai.context.memory.models import MemoryConfig
|
||||
from zhenxun.services.ai.core.exceptions import (
|
||||
ConcurrencyInterruptException,
|
||||
@@ -28,20 +34,15 @@ from zhenxun.services.ai.core.options import (
|
||||
from zhenxun.services.ai.core.protocols.tool import ToolExecutable, ToolResolvable
|
||||
from zhenxun.services.ai.core.stream_events import AgentStreamEvent, EventBus
|
||||
from zhenxun.services.ai.core.templates import PromptTemplate
|
||||
from zhenxun.services.ai.flow.agent.engine.builders import ToolBuilder
|
||||
from zhenxun.services.ai.flow.agent.models import (
|
||||
AgentConfig,
|
||||
AgentRunResources,
|
||||
AgentState,
|
||||
Persona,
|
||||
)
|
||||
from zhenxun.services.ai.flow.base import BaseRunnable
|
||||
from zhenxun.services.ai.guardrails import GuardrailSource
|
||||
from zhenxun.services.ai.flow.base import BaseRunnable, ConcurrencyPolicy
|
||||
from zhenxun.services.ai.flow.concurrency import apply_concurrency_policy
|
||||
from zhenxun.services.ai.guardrails import GuardrailSource, parse_guardrails
|
||||
from zhenxun.services.ai.llm.builder import IntentBuilder
|
||||
from zhenxun.services.ai.message_builder import MessageBuilder
|
||||
from zhenxun.services.ai.run import (
|
||||
AgentRunResult,
|
||||
AgentTask,
|
||||
RunContext,
|
||||
Task,
|
||||
)
|
||||
from zhenxun.services.ai.run.context import AgentDepsT
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
@@ -52,10 +53,20 @@ from zhenxun.services.ai.run.models import (
|
||||
OutputDataT,
|
||||
StreamedRunResult,
|
||||
)
|
||||
from zhenxun.services.ai.tools.core.tool import BaseTool
|
||||
from zhenxun.services.ai.run.subscribers import (
|
||||
DefaultUISubscriber,
|
||||
TelemetrySubscriber,
|
||||
)
|
||||
from zhenxun.services.ai.tools.bridges.delegate import DelegateTool
|
||||
from zhenxun.services.ai.tools.core.tool import BaseTool, FunctionTool
|
||||
from zhenxun.services.ai.tools.core.toolkit import BaseToolkit
|
||||
from zhenxun.services.ai.tools.models import Query
|
||||
from zhenxun.services.ai.tools.models import Query, ToolOptions
|
||||
from zhenxun.services.ai.tools.providers.builtin.hitl import HITLToolkit
|
||||
from zhenxun.services.ai.tools.providers.skills.capabilities import (
|
||||
SkillCapability,
|
||||
)
|
||||
from zhenxun.services.ai.tools.providers.skills.models import Skill, SkillSource
|
||||
from zhenxun.services.ai.utils import ContextUtils
|
||||
from zhenxun.services.log import logger
|
||||
from zhenxun.utils.pydantic_compat import (
|
||||
model_construct,
|
||||
@@ -65,7 +76,18 @@ from zhenxun.utils.pydantic_compat import (
|
||||
)
|
||||
from zhenxun.utils.utils import infer_plugin_namespace
|
||||
|
||||
from .engine.executor import BaseAgentExecutor
|
||||
from .engine.builders import (
|
||||
AgentProfileResolver,
|
||||
ContextBuilder,
|
||||
ToolBuilder,
|
||||
)
|
||||
from .engine.executor import BaseAgentExecutor, StandardAgentExecutor
|
||||
from .models import (
|
||||
AgentConfig,
|
||||
AgentRunResources,
|
||||
AgentState,
|
||||
Persona,
|
||||
)
|
||||
|
||||
ToolSource = (
|
||||
Callable | BaseTool | dict[str, Any] | str | BaseToolkit | ToolResolvable | Query
|
||||
@@ -413,8 +435,6 @@ class Agent(
|
||||
self.tool_filters = []
|
||||
self.toolset_funcs = []
|
||||
self._event_listeners: dict[type[AgentStreamEvent], list[Callable]] = {}
|
||||
from zhenxun.services.ai.guardrails import parse_guardrails
|
||||
|
||||
self._guardrails = parse_guardrails(guardrails)
|
||||
|
||||
self.memory_config = MemoryBuilder.resolve(memory)
|
||||
@@ -428,8 +448,6 @@ class Agent(
|
||||
self.engine_config = self.config
|
||||
|
||||
if self.config.enable_hitl is None:
|
||||
from zhenxun.services.ai.config import get_llm_config
|
||||
|
||||
self.config.enable_hitl = get_llm_config().agent_settings.enable_hitl
|
||||
|
||||
self.config.stateless = not self.memory_config.short_term.enable
|
||||
@@ -450,19 +468,11 @@ class Agent(
|
||||
self.capabilities: list[AbstractCapability] = []
|
||||
|
||||
if self.memory_config.long_term.enable and self.memory_config.long_term.agentic:
|
||||
from zhenxun.services.ai.context.memory.capabilities import (
|
||||
AgenticMemoryCapability,
|
||||
)
|
||||
|
||||
self.capabilities.append(
|
||||
AgenticMemoryCapability(self.memory_config, self.namespace)
|
||||
)
|
||||
|
||||
if self.memory_config.slots.enable:
|
||||
from zhenxun.services.ai.context.memory.capabilities import (
|
||||
SlotMemoryCapability,
|
||||
)
|
||||
|
||||
self.capabilities.append(
|
||||
SlotMemoryCapability(self.memory_config, self.namespace)
|
||||
)
|
||||
@@ -475,15 +485,9 @@ class Agent(
|
||||
self.capabilities.append(DynamicCapability(cap))
|
||||
|
||||
if self.config.enable_hitl:
|
||||
from zhenxun.services.ai.tools.providers.builtin.hitl import HITLToolkit
|
||||
|
||||
self.tool_definitions.append(HITLToolkit())
|
||||
|
||||
if skills:
|
||||
from zhenxun.services.ai.tools.providers.skills.capabilities import (
|
||||
SkillCapability,
|
||||
)
|
||||
|
||||
self.capabilities.append(
|
||||
SkillCapability(skills=skills, namespace=self.namespace)
|
||||
)
|
||||
@@ -502,9 +506,6 @@ class Agent(
|
||||
"""
|
||||
|
||||
def decorator(f: Callable):
|
||||
from zhenxun.services.ai.tools.core.tool import FunctionTool
|
||||
from zhenxun.services.ai.tools.models import ToolOptions
|
||||
|
||||
tool_name = name or f.__name__
|
||||
tool_desc = description or f.__doc__ or "未提供描述"
|
||||
base_settings = settings or getattr(f, "__tool_settings__", ToolOptions())
|
||||
@@ -566,15 +567,11 @@ class Agent(
|
||||
if func is None:
|
||||
|
||||
def decorator(f: Callable):
|
||||
from zhenxun.services.ai.guardrails import parse_guardrails
|
||||
|
||||
self._guardrails.extend(parse_guardrails([f]))
|
||||
return f
|
||||
|
||||
return decorator
|
||||
else:
|
||||
from zhenxun.services.ai.guardrails import parse_guardrails
|
||||
|
||||
self._guardrails.extend(parse_guardrails([func]))
|
||||
return func
|
||||
|
||||
@@ -594,13 +591,11 @@ class Agent(
|
||||
|
||||
async def __resolve_to_tools__(self) -> list[ToolExecutable]:
|
||||
"""协议支持：将自身 Agent 转化为可被上级调用的工具"""
|
||||
from zhenxun.services.ai.tools.bridges.delegate import DelegateTool
|
||||
|
||||
return [DelegateTool(self)]
|
||||
|
||||
async def run(
|
||||
self,
|
||||
prompt: PromptInput | Task | None = None,
|
||||
prompt: PromptInput | AgentTask | None = None,
|
||||
*,
|
||||
config: AgentConfig | dict | None = None,
|
||||
deps: AgentDepsT | None = None,
|
||||
@@ -611,7 +606,7 @@ class Agent(
|
||||
智能体单次运行阻塞核心入口，内部使用上下文管理器静默消费事件流直至执行结束。
|
||||
|
||||
参数:
|
||||
prompt: 用户输入的消息内容或标准数据契约任务对象 (Task)。
|
||||
prompt: 用户输入的消息内容或标准数据契约任务对象 (AgentTask)。
|
||||
deps: 强类型的外部依赖注入对象 (例如 NoneBot 的 Bot, Event)。
|
||||
context: 显式传入的运行时与会话上下文 (RunContext)。
|
||||
config: 单次运行时的动态配置覆盖字典或对象。
|
||||
@@ -628,7 +623,7 @@ class Agent(
|
||||
@contextlib.asynccontextmanager
|
||||
async def run_stream(
|
||||
self,
|
||||
prompt: PromptInput | Task | None = None,
|
||||
prompt: PromptInput | AgentTask | None = None,
|
||||
*,
|
||||
config: AgentConfig | dict | None = None,
|
||||
deps: AgentDepsT | None = None,
|
||||
@@ -648,10 +643,6 @@ class Agent(
|
||||
effective_config = self.config.merge_with(override_conf)
|
||||
|
||||
if effective_config.skills:
|
||||
from zhenxun.services.ai.tools.providers.skills.capabilities import (
|
||||
SkillCapability,
|
||||
)
|
||||
|
||||
if effective_config.capabilities is None:
|
||||
effective_config.capabilities = []
|
||||
effective_config.capabilities.append(
|
||||
@@ -661,11 +652,6 @@ class Agent(
|
||||
)
|
||||
bus = event_bus or EventBus()
|
||||
|
||||
from zhenxun.services.ai.run.subscribers import (
|
||||
DefaultUISubscriber,
|
||||
TelemetrySubscriber,
|
||||
)
|
||||
|
||||
TelemetrySubscriber().attach(bus)
|
||||
|
||||
if self._event_listeners:
|
||||
@@ -674,8 +660,6 @@ class Agent(
|
||||
|
||||
def _make_handler(callback_func: Callable) -> Callable:
|
||||
async def _di_handler(event: AgentStreamEvent):
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
|
||||
await DependencyInjector.invoke(
|
||||
callback_func, {"stream_event": event}, safe_context
|
||||
)
|
||||
@@ -700,8 +684,6 @@ class Agent(
|
||||
|
||||
policy = getattr(self.config, "concurrency_policy", None)
|
||||
if policy is None:
|
||||
from zhenxun.services.ai.flow.base import ConcurrencyPolicy
|
||||
|
||||
policy = (
|
||||
ConcurrencyPolicy.ALLOW
|
||||
if getattr(self.config, "stateless", True)
|
||||
@@ -710,8 +692,6 @@ class Agent(
|
||||
|
||||
intervention_policy = getattr(self.config, "intervention_policy", None)
|
||||
|
||||
from zhenxun.services.ai.utils import ContextUtils
|
||||
|
||||
lock_id = ContextUtils.extract_concurrency_lock_id(
|
||||
safe_context,
|
||||
getattr(self.config, "concurrency_scope", None),
|
||||
@@ -719,8 +699,6 @@ class Agent(
|
||||
)
|
||||
|
||||
async def _execution_task():
|
||||
from zhenxun.services.ai.flow.concurrency import apply_concurrency_policy
|
||||
|
||||
cancel_token = safe_context.run.cancellation_token or CancellationToken()
|
||||
safe_context.run.cancellation_token = cancel_token
|
||||
|
||||
@@ -767,16 +745,16 @@ class Agent(
|
||||
task.cancel()
|
||||
|
||||
def _parse_task_prompt(
|
||||
self, prompt: PromptInput | Task | None
|
||||
) -> tuple[Task | None, Any | None, list[Any], Any, list[Any]]:
|
||||
"""解析输入意图，提取数据契约 (Task)"""
|
||||
self, prompt: PromptInput | AgentTask | None
|
||||
) -> tuple[AgentTask | None, Any | None, list[Any], Any, list[Any]]:
|
||||
"""解析输入意图，提取数据契约 (AgentTask)"""
|
||||
task_obj = None
|
||||
final_prompt_payload = None
|
||||
extra_tools = []
|
||||
run_output_type = self.response_model
|
||||
task_guardrails = []
|
||||
|
||||
if isinstance(prompt, Task):
|
||||
if isinstance(prompt, AgentTask):
|
||||
task_obj = prompt
|
||||
if task_obj.response_model:
|
||||
run_output_type = task_obj.response_model
|
||||
@@ -803,7 +781,7 @@ class Agent(
|
||||
|
||||
async def on_state_init(
|
||||
self,
|
||||
prompt: PromptInput | Task | None = None,
|
||||
prompt: PromptInput | AgentTask | None = None,
|
||||
context: RunContext[AgentDepsT] | None = None,
|
||||
config: AgentConfig | None = None,
|
||||
cancellation_token: Any = None,
|
||||
@@ -886,11 +864,6 @@ class Agent(
|
||||
self, state: AgentState, resources: AgentRunResources
|
||||
) -> None:
|
||||
"""装配记忆与提示词上下文、解析可用工具集"""
|
||||
from zhenxun.services.ai.capabilities import CombinedCapability
|
||||
from zhenxun.services.ai.flow.agent.engine.builders import (
|
||||
AgentProfileResolver,
|
||||
ContextBuilder,
|
||||
)
|
||||
|
||||
context = resources.run_context
|
||||
reader = resources.memory_reader
|
||||
@@ -961,8 +934,6 @@ class Agent(
|
||||
messages_for_run.extend(context.run.messages)
|
||||
|
||||
if final_prompt_payload is not None:
|
||||
from zhenxun.services.ai.message_builder import MessageBuilder
|
||||
|
||||
if msgs := await MessageBuilder.normalize_to_llm_messages(
|
||||
final_prompt_payload, bot=context.get_bot(), event=context.get_event()
|
||||
):
|
||||
@@ -986,8 +957,6 @@ class Agent(
|
||||
self, state: AgentState, resources: AgentRunResources
|
||||
) -> AgentRunResult[OutputDataT]:
|
||||
"""真正调度大模型执行器并执行记忆落盘"""
|
||||
from zhenxun.services.ai.flow.agent.engine.executor import StandardAgentExecutor
|
||||
|
||||
context = resources.run_context
|
||||
|
||||
for tk in resources.toolkits:
|
||||
@@ -1027,7 +996,7 @@ class Agent(
|
||||
|
||||
async def _run_step(
|
||||
self,
|
||||
prompt: PromptInput | Task | None = None,
|
||||
prompt: PromptInput | AgentTask | None = None,
|
||||
*,
|
||||
context: RunContext[AgentDepsT],
|
||||
config: AgentConfig,
|
||||
@@ -1046,8 +1015,6 @@ class Agent(
|
||||
)
|
||||
await self.on_context_build(state, resources)
|
||||
|
||||
from zhenxun.services.ai.capabilities import CombinedCapability
|
||||
|
||||
run_scoped_cap = (
|
||||
resources.run_scoped_cap
|
||||
if isinstance(resources.run_scoped_cap, CombinedCapability)
|
||||
|
||||
@@ -10,7 +10,8 @@ from zhenxun.services.ai.core.engine.structured_parser import (
|
||||
from zhenxun.services.ai.core.exceptions import UpstreamServerException
|
||||
from zhenxun.services.ai.core.messages import TaskLifecycleEvent
|
||||
from zhenxun.services.ai.core.options import BaseOutputDefinition, ToolOutput
|
||||
from zhenxun.services.ai.run import AgentRunResult, RunContext, Task
|
||||
from zhenxun.services.ai.guardrails import parse_guardrails
|
||||
from zhenxun.services.ai.run import AgentRunResult, AgentTask, RunContext
|
||||
from zhenxun.services.log import logger
|
||||
|
||||
|
||||
@@ -33,8 +34,6 @@ class OutputValidationCapability(AbstractCapability):
|
||||
self.output_type = output_type
|
||||
self.raw_schema = raw_schema
|
||||
|
||||
from zhenxun.services.ai.guardrails import parse_guardrails
|
||||
|
||||
self.guardrails = parse_guardrails(guardrails)
|
||||
self.processor = None
|
||||
self.submit_tool = None
|
||||
@@ -114,7 +113,7 @@ class OutputValidationCapability(AbstractCapability):
|
||||
class TaskTrackingCapability(AbstractCapability):
|
||||
"""数据契约任务状态追踪与事件遥测组件"""
|
||||
|
||||
def __init__(self, task: Task, agent_name: str):
|
||||
def __init__(self, task: AgentTask, agent_name: str):
|
||||
self.task = task
|
||||
self.agent_name = agent_name
|
||||
|
||||
|
||||
@@ -5,19 +5,31 @@ from typing import Any, cast
|
||||
|
||||
from nonebot.utils import is_coroutine_callable
|
||||
|
||||
from zhenxun.services.ai.capabilities import CombinedCapability
|
||||
from zhenxun.services.ai.capabilities import (
|
||||
AbstractCapability,
|
||||
CombinedCapability,
|
||||
DynamicCapability,
|
||||
)
|
||||
from zhenxun.services.ai.context.memory.builder import MemoryBuilder
|
||||
from zhenxun.services.ai.context.memory.engine import MemoryReader, MemoryWriter
|
||||
from zhenxun.services.ai.context.memory.models import MemoryConfig
|
||||
from zhenxun.services.ai.core.messages import LLMMessage
|
||||
from zhenxun.services.ai.context.memory.types import SessionMetadata
|
||||
from zhenxun.services.ai.core.messages import LLMMessage, TextPart
|
||||
from zhenxun.services.ai.core.options import GenerationConfig
|
||||
from zhenxun.services.ai.core.templates import PromptTemplate
|
||||
from zhenxun.services.ai.flow.agent.capabilities import (
|
||||
OutputValidationCapability,
|
||||
TaskTrackingCapability,
|
||||
)
|
||||
from zhenxun.services.ai.flow.agent.models import Persona
|
||||
from zhenxun.services.ai.run import RunContext
|
||||
from zhenxun.services.ai.run import GLOBAL_CAPABILITIES, RunContext
|
||||
from zhenxun.services.ai.run.di import DependencyInjector
|
||||
from zhenxun.services.ai.tools.engine.registry import (
|
||||
ToolCollection,
|
||||
tool_provider_manager,
|
||||
)
|
||||
from zhenxun.services.ai.tools.models import GlobalToolFilter, ResolvedToolPayload
|
||||
from zhenxun.services.ai.utils.scope import ScopeSelector
|
||||
from zhenxun.utils.pydantic_compat import model_copy
|
||||
|
||||
|
||||
@@ -28,8 +40,17 @@ class AgentProfileResolver:
|
||||
def resolve_memory(
|
||||
agent_memory_config: MemoryConfig, override_memory: Any | None
|
||||
) -> MemoryConfig:
|
||||
from zhenxun.services.ai.context.memory.builder import MemoryBuilder
|
||||
"""
|
||||
解析并合并 Memory 记忆域的配置。
|
||||
支持从外部覆盖配置并重新构建。
|
||||
|
||||
参数：
|
||||
agent_memory_config: 预置的 Agent 默认记忆域配置对象。
|
||||
override_memory: 运行时覆盖的记忆域配置，可为 dict, MemoryConfig 或其他合法结构。
|
||||
|
||||
返回：
|
||||
MemoryConfig: 合并并生成的运行时记忆域配置实例。
|
||||
""" # noqa: E501
|
||||
if override_memory is not None:
|
||||
return MemoryBuilder.resolve(override_memory)
|
||||
return model_copy(agent_memory_config, deep=True)
|
||||
@@ -40,6 +61,18 @@ class AgentProfileResolver:
|
||||
cap_config: GenerationConfig | None,
|
||||
profile_config: GenerationConfig | None,
|
||||
) -> GenerationConfig:
|
||||
"""
|
||||
解析并合并多层 GenerationConfig 模型生成配置。
|
||||
优先级顺序由低到高为：基础配置 -> 拦截器能力配置 -> 运行时 Profile 覆盖配置。
|
||||
|
||||
参数：
|
||||
base_config: 基础的模型生成配置对象。
|
||||
cap_config: 拦截器能力中提取出的模型生成参数配置。
|
||||
profile_config: 运行时传入的 Profile 覆盖参数配置。
|
||||
|
||||
返回：
|
||||
GenerationConfig: 合并多层配置后生成的最终运行时生成配置实例。
|
||||
"""
|
||||
final_gen_config = model_copy(base_config, deep=True)
|
||||
if cap_config:
|
||||
final_gen_config = final_gen_config.merge_with(cap_config)
|
||||
@@ -49,7 +82,7 @@ class AgentProfileResolver:
|
||||
|
||||
|
||||
class CapabilityBuilder:
|
||||
"""拦截器能力组装器：负责合并 Agent, Task, Profile 和全局的中间件"""
|
||||
"""拦截器能力组装器：负责合并 Agent, AgentTask, Profile 和全局的中间件"""
|
||||
|
||||
@staticmethod
|
||||
async def build_for_run(
|
||||
@@ -64,15 +97,25 @@ class CapabilityBuilder:
|
||||
profile_capabilities: list | None,
|
||||
context: RunContext,
|
||||
) -> CombinedCapability:
|
||||
from zhenxun.services.ai.capabilities import (
|
||||
AbstractCapability,
|
||||
DynamicCapability,
|
||||
)
|
||||
from zhenxun.services.ai.flow.agent.capabilities import (
|
||||
OutputValidationCapability,
|
||||
TaskTrackingCapability,
|
||||
)
|
||||
"""
|
||||
为当前的 Agent 运行实例组装并实例化所有能力拦截器中间件。
|
||||
整合全局能力、任务追踪、格式校验以及动态注入的能力。
|
||||
|
||||
参数：
|
||||
agent_name: 执行推理的 Agent 标识名。
|
||||
namespace: 会话所归属的命名空间。
|
||||
output_type: 期待大模型返回的结构化 Pydantic 模型类型（支持 None 或 str）。
|
||||
raw_schema: 原始结构化 Schema 定义字典。
|
||||
agent_guardrails: Agent 自身定义的业务语义安全护栏列表。
|
||||
task_guardrails: 本次任务定义的业务语义安全护栏列表。
|
||||
task_obj: 被追踪的任务上下文对象实例。
|
||||
agent_capabilities: Agent 定义的静态拦截器列表。
|
||||
profile_capabilities: 运行时动态传入的能力或中间件列表。
|
||||
context: 运行上下文对象实例。
|
||||
|
||||
返回：
|
||||
CombinedCapability: 已经过运行初始化完毕的合并能力拦截器实例。
|
||||
"""
|
||||
dynamic_caps = []
|
||||
combined_guardrails = agent_guardrails + task_guardrails
|
||||
|
||||
@@ -100,10 +143,6 @@ class CapabilityBuilder:
|
||||
elif callable(cap):
|
||||
run_level_caps.append(DynamicCapability(cap))
|
||||
|
||||
from zhenxun.services.ai.run import (
|
||||
GLOBAL_CAPABILITIES,
|
||||
)
|
||||
|
||||
base_caps = GLOBAL_CAPABILITIES.get("global", []).copy()
|
||||
if namespace != "global" and namespace in GLOBAL_CAPABILITIES:
|
||||
base_caps.extend(GLOBAL_CAPABILITIES[namespace])
|
||||
@@ -129,8 +168,20 @@ class ContextBuilder:
|
||||
run_scoped_cap: CombinedCapability,
|
||||
persona: Persona | None = None,
|
||||
) -> tuple[str, list[Any]]:
|
||||
"""解析提示词，返回 (静态系统提示词文本, 动态独立消息列表) 元组"""
|
||||
"""
|
||||
解析、合并并渲染 Agent 的系统提示词和上下文记忆。
|
||||
包含对依赖参数的动态注入和 Jinja 模板渲染。
|
||||
|
||||
参数：
|
||||
instruction: 任务级别的初始指令或提示词模板。
|
||||
system_prompts: 系统提示词生成函数（支持依赖注入）列表。
|
||||
run_context: 运行上下文对象实例。
|
||||
run_scoped_cap: 运行域下的合并能力中间件。
|
||||
persona: 设定的 Agent 人设配置实例。
|
||||
|
||||
返回：
|
||||
tuple[str, list[Any]]: 包含 (渲染后的静态系统提示词文本, 渲染后的动态消息列表) 的元组。
|
||||
""" # noqa: E501
|
||||
static_instructions = []
|
||||
dynamic_messages = []
|
||||
|
||||
@@ -174,7 +225,7 @@ class ContextBuilder:
|
||||
static_instructions.append("\n\n".join(persona_parts))
|
||||
|
||||
if instruction:
|
||||
static_instructions.append("## 本次任务指令 (Task)")
|
||||
static_instructions.append("## 本次任务指令 (AgentTask)")
|
||||
|
||||
if instruction:
|
||||
if isinstance(instruction, PromptTemplate):
|
||||
@@ -205,7 +256,6 @@ class ContextBuilder:
|
||||
render_context.update(run_context.state)
|
||||
|
||||
rendered_dynamic_messages = []
|
||||
from zhenxun.services.ai.core.messages import TextPart
|
||||
|
||||
for msg in dynamic_messages:
|
||||
if msg.role == "system":
|
||||
@@ -252,7 +302,22 @@ class ToolBuilder:
|
||||
run_context: RunContext,
|
||||
run_scoped_cap: CombinedCapability,
|
||||
) -> ResolvedToolPayload:
|
||||
"""解析、合并并过滤工具集"""
|
||||
"""
|
||||
解析并合并来自静态定义、动态函数依赖以及能力的工具列表。
|
||||
通过工具提供者管理器完成工具的具体实例化及参数绑定。
|
||||
|
||||
参数：
|
||||
tool_definitions: 静态工具或工具集合的定义列表。
|
||||
toolset_funcs: 待依赖注入解析的工具集生成函数列表。
|
||||
system_tools: 系统默认强制集成的工具定义列表。
|
||||
namespace: 会话命名空间。
|
||||
tool_filter: 全局的工具过滤条件，此处为占位。
|
||||
run_context: 运行上下文对象实例.
|
||||
run_scoped_cap: 运行域下的合并能力中间件，用于提供特定的能力工具。
|
||||
|
||||
返回：
|
||||
ResolvedToolPayload: 解析完毕并附带依赖绑定关系的工具负载载体。
|
||||
"""
|
||||
defs_to_resolve = list(tool_definitions)
|
||||
|
||||
for ts_func in toolset_funcs:
|
||||
@@ -304,7 +369,18 @@ class ToolBuilder:
|
||||
tool_filters: list[Callable],
|
||||
run_scoped_cap: CombinedCapability,
|
||||
) -> ToolCollection:
|
||||
"""处理生命周期：在工具发往执行器前，进行最终的 Schema 拦截和清洗"""
|
||||
"""
|
||||
在将工具发往模型执行器之前，触发最终的过滤器与能力拦截，进行 schema 的清洗。
|
||||
|
||||
参数：
|
||||
effective_tools: 备选的工具执行实例列表。
|
||||
context: 运行上下文对象实例。
|
||||
tool_filters: 运行时自定义工具过滤与清洗函数列表。
|
||||
run_scoped_cap: 运行域下的合并能力中间件，提供拦截入口。
|
||||
|
||||
返回：
|
||||
ToolCollection: 准备就绪的、可直接发往模型的最终有效工具执行集。
|
||||
"""
|
||||
current_tool_defs = []
|
||||
for t_exec in effective_tools:
|
||||
if hasattr(t_exec, "get_definition"):
|
||||
@@ -355,10 +431,18 @@ class SessionBuilder:
|
||||
agent_name: str,
|
||||
effective_memory: MemoryConfig,
|
||||
) -> tuple[Any, Any, Any]:
|
||||
from zhenxun.services.ai.context.memory.engine import MemoryReader, MemoryWriter
|
||||
from zhenxun.services.ai.context.memory.types import SessionMetadata
|
||||
from zhenxun.services.ai.utils.scope import ScopeSelector
|
||||
"""
|
||||
根据当前用户、群组和平台标识，动态隔离前缀，计算并构建会话与记忆存储的读写门面。
|
||||
|
||||
参数：
|
||||
context: 运行上下文对象实例。
|
||||
namespace: 当前会话的命名空间。
|
||||
agent_name: 执行推理的 Agent 标识名。
|
||||
effective_memory: 运行时最终生效的 MemoryConfig 配置对象。
|
||||
|
||||
返回：
|
||||
tuple[Any, Any, Any]: 包含 (SessionMetadata 会话元数据, MemoryReader 记忆读取器, MemoryWriter 记忆写入器) 的元组。
|
||||
""" # noqa: E501
|
||||
bot_id = None
|
||||
bot_inst = context.get_bot()
|
||||
if bot_inst and hasattr(bot_inst, "self_id"):
|
||||
|
||||
@@ -3,6 +3,7 @@ import asyncio
|
||||
import json
|
||||
from typing import Any, cast
|
||||
|
||||
from zhenxun.services.ai.capabilities import CombinedCapability
|
||||
from zhenxun.services.ai.core.engine.context_renderer import ContextConverter
|
||||
from zhenxun.services.ai.core.engine.token_counter import (
|
||||
parse_usage_info,
|
||||
@@ -36,9 +37,12 @@ from zhenxun.services.ai.core.stream_events import (
|
||||
)
|
||||
from zhenxun.services.ai.flow.agent.engine.directive import (
|
||||
DirectiveHandlerFunc,
|
||||
directive_manager,
|
||||
)
|
||||
from zhenxun.services.ai.flow.agent.models import AgentRunResources, AgentState
|
||||
from zhenxun.services.ai.llm.engine.router import LLMOrchestrator
|
||||
from zhenxun.services.ai.run import AgentRunResult, RunContext
|
||||
from zhenxun.services.ai.run.session import session_manager
|
||||
from zhenxun.services.ai.tools.engine.executor import ToolExecutor
|
||||
from zhenxun.services.ai.tools.models import ToolResult
|
||||
from zhenxun.services.log import logger
|
||||
@@ -279,9 +283,6 @@ class StandardAgentExecutor(BaseAgentExecutor):
|
||||
extra: dict[str, Any] | None = None,
|
||||
cancellation_token: Any = None,
|
||||
) -> ChatResponse:
|
||||
from zhenxun.services.ai.capabilities import CombinedCapability
|
||||
from zhenxun.services.ai.llm.engine.router import LLMOrchestrator
|
||||
|
||||
request = ChatRequest(
|
||||
messages=messages,
|
||||
config=config,
|
||||
@@ -315,8 +316,6 @@ class StandardAgentExecutor(BaseAgentExecutor):
|
||||
) -> AgentRunResult[Any]:
|
||||
"""覆盖基类的模板方法，实现灵活的 while 控制流和 FOLLOW_UP 合并"""
|
||||
await self.on_start(state, resources)
|
||||
from zhenxun.services.ai.run.session import session_manager
|
||||
|
||||
session_info = await session_manager.get_or_create(
|
||||
resources.run_context.session_id or "default_session"
|
||||
)
|
||||
@@ -388,9 +387,6 @@ class StandardAgentExecutor(BaseAgentExecutor):
|
||||
self, state: AgentState, resources: AgentRunResources
|
||||
) -> None:
|
||||
run_context = resources.run_context
|
||||
|
||||
from zhenxun.services.ai.run.session import session_manager
|
||||
|
||||
session_info = await session_manager.get_or_create(
|
||||
run_context.session_id or "default_session"
|
||||
)
|
||||
@@ -499,8 +495,6 @@ class StandardAgentExecutor(BaseAgentExecutor):
|
||||
None,
|
||||
)
|
||||
if return_part:
|
||||
from zhenxun.services.ai.tools.models import ToolResult
|
||||
|
||||
box["result"] = ToolResult(output=return_part.output)
|
||||
else:
|
||||
client_tool_calls.append(call)
|
||||
@@ -606,8 +600,6 @@ class StandardAgentExecutor(BaseAgentExecutor):
|
||||
if not tool_calls or not tool_results:
|
||||
return
|
||||
|
||||
from zhenxun.services.ai.flow.agent.engine.directive import directive_manager
|
||||
|
||||
for i, res_or_exc in enumerate(tool_results):
|
||||
original_call = tool_calls[i]
|
||||
tool_res = None
|
||||
|
||||
@@ -165,7 +165,7 @@ class AgentRunResources(BaseModel):
|
||||
memory_writer: Any | None = None
|
||||
"""用于将对话历史安全落盘的写入器"""
|
||||
run_scoped_cap: Any | None = None
|
||||
"""聚合了 Agent/Task/全局 的复合能力拦截器 (CombinedCapability)"""
|
||||
"""聚合了 Agent/AgentTask/全局 的复合能力拦截器 (CombinedCapability)"""
|
||||
task_obj: Any | None = None
|
||||
"""(如有) 解析后的结构化数据任务契约"""
|
||||
toolkits: list[Any] = Field(default_factory=list)
|
||||
|
||||
Reference in New Issue
Block a user