✨ 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>
2026-10-18 10:40:03 +08:00 · 2026-07-03 08:53:56 +08:00
parent bdc1374848
commit 80fc5b86a7
223 changed files with 41885 additions and 10006 deletions
@@ -0,0 +1,19 @@
+from .base import (
+    AbstractCapability,
+    WrapModelRequestHandler,
+    WrapRunHandler,
+    WrapToolExecuteHandler,
+    WrapToolValidateHandler,
+)
+from .wrappers import CombinedCapability, DynamicCapability, WrapperCapability
+
+__all__ = [
+    "AbstractCapability",
+    "CombinedCapability",
+    "DynamicCapability",
+    "WrapModelRequestHandler",
+    "WrapRunHandler",
+    "WrapToolExecuteHandler",
+    "WrapToolValidateHandler",
+    "WrapperCapability",
+]
@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, Union
+
+from zhenxun.services.ai.core.messages import ChatRequest, ChatResponse
+from zhenxun.services.ai.core.options import GenerationConfig
+
+if TYPE_CHECKING:
+    from zhenxun.services.ai.core.models import LLMContext
+    from zhenxun.services.ai.run import AgentRunResult, RunContext
+
+WrapRunHandler = Callable[[], Awaitable["AgentRunResult[Any]"]]
+"""整个 Agent 运行过程包裹的处理函数类型"""
+
+WrapModelRequestHandler = Callable[
+    ["LLMContext[ChatRequest, ChatResponse]"], Awaitable[ChatResponse]
+]
+"""单次大模型 API 请求包裹的处理函数类型"""
+
+WrapToolValidateHandler = Callable[[str | dict[str, Any]], Awaitable[dict[str, Any]]]
+"""工具参数校验过程包裹的处理函数类型"""
+
+WrapToolExecuteHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+"""单一工具执行过程包裹的处理函数类型"""
+
+
+CapabilityPosition = Literal["outermost", "innermost"]
+"""Capability 在洋葱模型中的固定执行位置（最外层或最内层）"""
+
+CapabilityRef = Union[type["AbstractCapability"], "AbstractCapability"]
+"""对 Capability 的引用，可以是 Capability 实例或类类型"""
+
+
+@dataclass
+class CapabilityOrdering:
+    """定义拦截器 (Capability) 的拓扑排序约束。
+    采用洋葱模型语义：排在列表前面的拦截器在最外层执行。
+    """
+
+    position: CapabilityPosition | None = None
+    """固定位置：outermost (最外层) 或 innermost (最内层)"""
+    wraps: Sequence[CapabilityRef] = ()
+    """当前拦截器必须包裹（即在...之前执行）目标拦截器"""
+    wrapped_by: Sequence[CapabilityRef] = ()
+    """当前拦截器必须被包裹（即在...之后执行）目标拦截器"""
+    requires: Sequence[type["AbstractCapability"]] = ()
+    """当前拦截器依赖的其他拦截器类型，若缺失则报错"""
+
+
+class AbstractCapability:
+    """
+    Agent 能力组件基类协议。
+    所有业务逻辑拦截（限流、权限、动态 Prompt）请在此实现。
+    底层网络重试、并发控制等请勿在此处理。
+    """
+
+    @classmethod
+    def get_serialization_name(cls) -> str | None:
+        """用于 YAML/JSON 反序列化的注册标识符"""
+        return cls.__name__
+
+    @classmethod
+    def from_spec(cls, **kwargs) -> "AbstractCapability":
+        """从 Spec 的 kwargs 中实例化对象"""
+        return cls(**kwargs)
+
+    def __init_subclass__(cls, **kwargs):
+        """自动将继承此类的所有拦截器注册到中心表"""
+        super().__init_subclass__(**kwargs)
+        CapabilityRegistry.register(cls)
+
+    def get_ordering(self) -> CapabilityOrdering | None:
+        """获取该拦截器的拓扑排序约束。子类可重写此方法以锁定执行顺序。"""
+        return None
+
+    async def for_run(self, context: RunContext) -> "AbstractCapability":
+        """获取专用于单次运行的实例。
+        默认返回自身(无状态)。
+        若需要记录单次运行的上下文状态，请返回深/浅拷贝(如 return copy.copy(self))。
+        """
+        return self
+
+    async def get_generation_config(
+        self, context: RunContext
+    ) -> GenerationConfig | None:
+        """运行开始前触发。允许动态下发大模型配置（覆盖或合并 Agent 的默认配置）。"""
+        return None
+
+    async def get_system_prompts(self, context: RunContext) -> list[str]:
+        return []
+
+    async def get_tools(self, context: RunContext) -> list[Any]:
+        return []
+
+    async def prepare_tools(
+        self, context: RunContext, tool_defs: list[Any]
+    ) -> list[Any]:
+        """运行开始前/装配工具时触发。允许动态增删改当前将发往大模型的工具列表。
+        默认实现：无操作，直接返回传入的工具列表。"""
+        return tool_defs
+
+    async def wrap_run(
+        self, context: RunContext, handler: WrapRunHandler
+    ) -> "AgentRunResult[Any]":
+        """包裹整个 Agent 运行过程 (洋葱模型)。"""
+        return await handler()
+
+    async def wrap_model_request(
+        self,
+        context: RunContext,
+        llm_context: LLMContext[ChatRequest, ChatResponse],
+        handler: WrapModelRequestHandler,
+    ) -> ChatResponse:
+        """包裹单次大模型 API 请求 (洋葱模型)。"""
+        return await handler(llm_context)
+
+    async def wrap_tool_validate(
+        self,
+        context: RunContext,
+        tool_name: str,
+        args: str | dict[str, Any],
+        handler: WrapToolValidateHandler,
+    ) -> dict[str, Any]:
+        """包裹工具的参数校验过程 (洋葱模型)。"""
+        return await handler(args)
+
+    async def wrap_tool_execute(
+        self,
+        context: RunContext,
+        tool_name: str,
+        arguments: dict[str, Any],
+        handler: WrapToolExecuteHandler,
+    ) -> Any:
+        """包裹单一工具的执行 (洋葱模型)。"""
+        return await handler(arguments)
+
+
+class CapabilityRegistry:
+    """Capability 序列化注册表"""
+
+    _registry: ClassVar[dict[str, type[AbstractCapability]]] = {}
+
+    @classmethod
+    def register(cls, cap_cls: type[AbstractCapability]):
+        name = cap_cls.get_serialization_name()
+        if name:
+            cls._registry[name] = cap_cls
+
+    @classmethod
+    def get(cls, name: str) -> type[AbstractCapability] | None:
+        return cls._registry.get(name)
@@ -0,0 +1,461 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from zhenxun.models.user_console import UserConsole
+from zhenxun.services.ai.capabilities import (
+    AbstractCapability,
+    WrapModelRequestHandler,
+    WrapToolExecuteHandler,
+)
+from zhenxun.services.ai.core.exceptions import (
+    GuardrailViolationError,
+    LLMException,
+    ModelRetry,
+    ResponseParseException,
+    SchemaParseError,
+    ToolFatalError,
+    UpstreamServerException,
+)
+from zhenxun.services.ai.core.messages import (
+    ChatRequest,
+    ChatResponse,
+    ToolCallPart,
+)
+from zhenxun.services.ai.core.models import LLMContext
+from zhenxun.services.ai.run.context import RunContext
+from zhenxun.services.ai.utils import PermissionUtils
+from zhenxun.services.log import logger
+from zhenxun.utils.enum import GoldHandle
+from zhenxun.utils.exception import InsufficientGold
+
+
+def _get_tool_meta(tool: Any, key: str, default: Any = None) -> Any:
+    """辅助方法：安全地提取工具元数据中指定的键值"""
+    if not tool:
+        return default
+    settings = getattr(tool, "settings", None)
+    meta = (settings.metadata if settings else None) or getattr(tool, "metadata", {})
+    return meta.get(key, default)
+
+
+class StuckDetectionCapability(AbstractCapability):
+    """死循环检测：使用前置请求拦截防止 LLM 陷入无限重试"""
+
+    async def wrap_model_request(
+        self,
+        context: RunContext,
+        llm_context: LLMContext[ChatRequest, ChatResponse],
+        handler: WrapModelRequestHandler,
+    ) -> ChatResponse:
+        import hashlib
+
+        max_repeated_errors = 3
+        action_hashes = []
+        messages = list(llm_context.request.messages)
+        idx = len(messages) - 1
+
+        while idx >= 0:
+            msg = messages[idx]
+            if msg.role == "tool":
+                batch_tool_contents = []
+                while idx >= 0 and messages[idx].role == "tool":
+                    for tr in messages[idx].tool_returns:
+                        batch_tool_contents.append(f"{tr.tool_name}:{tr.output}")
+                    idx -= 1
+
+                if (
+                    idx >= 0
+                    and messages[idx].role == "assistant"
+                    and messages[idx].tool_calls
+                ):
+                    assistant_msg = messages[idx]
+                    batch_tool_calls = []
+                    for tc in assistant_msg.tool_calls:
+                        if isinstance(tc, ToolCallPart):
+                            args_str = (
+                                tc.args
+                                if isinstance(tc.args, str)
+                                else json.dumps(tc.args, ensure_ascii=False)
+                            )
+                            batch_tool_calls.append(f"{tc.tool_name}:{args_str}")
+
+                    batch_tool_calls.sort()
+                    batch_tool_contents.sort()
+
+                    state_str = (
+                        "|".join(batch_tool_calls)
+                        + "||"
+                        + "|".join(batch_tool_contents)
+                    )
+                    state_hash = hashlib.md5(state_str.encode("utf-8")).hexdigest()
+                    action_hashes.append(state_hash)
+                    idx -= 1
+                else:
+                    break
+            elif msg.role == "assistant":
+                idx -= 1
+            else:
+                break
+
+        if len(action_hashes) >= max_repeated_errors:
+            recent_hashes = action_hashes[:max_repeated_errors]
+            if len(set(recent_hashes)) == 1:
+                logger.warning(
+                    "[StuckDetection] 拦截到死循环：连续 "
+                    f"{max_repeated_errors} 次产生完全相同的状态哈希碰撞。"
+                )
+                raise ToolFatalError(
+                    "Agent 触发终极防呆机制：连续 "
+                    f"{max_repeated_errors} 次产生完全相同的"
+                    "无效工具调用状态，已物理阻断以节省 Token。"
+                )
+
+        return await handler(llm_context)
+
+
+class GlobalCycleLimitCapability(AbstractCapability):
+    """全局防死循环检测中间件：跨 Agent 追踪大模型调用总次数"""
+
+    async def wrap_model_request(
+        self,
+        context: RunContext,
+        llm_context: LLMContext[ChatRequest, ChatResponse],
+        handler: WrapModelRequestHandler,
+    ) -> ChatResponse:
+        global_cycles = (
+            context.session.shared_state.get("__global_cycle_count__", 0) + 1
+        )
+        context.session.shared_state["__global_cycle_count__"] = global_cycles
+
+        global_max = llm_context.request.extra.get("__global_max_cycles__")
+        if global_max is None:
+            from zhenxun.services.ai.config import get_llm_config
+
+            global_max = get_llm_config().agent_settings.global_max_cycles
+
+        if global_max is not None and global_cycles > global_max:
+            from zhenxun.services.ai.core.exceptions import AbortException
+
+            logger.error(
+                "🚨 触发全局防护：整个流水线执行步数已达到全局上限 "
+                f"({global_max})，强制熔断！"
+            )
+            raise AbortException(
+                reason=f"全局大模型思考循环次数已超限 ({global_max}次)",
+                display="🚨 系统保护触发：任务过于复杂或陷入多智能体死循环，"
+                "已被强行中断以节省资源。",
+            )
+
+        return await handler(llm_context)
+
+
+class PermissionCapability(AbstractCapability):
+    """权限校验中间件：在执行前根据确定参数进行动态鉴权"""
+
+    async def wrap_tool_execute(
+        self,
+        context: RunContext,
+        tool_name: str,
+        arguments: dict[str, Any],
+        handler: WrapToolExecuteHandler,
+    ) -> dict[str, Any]:
+        tool = context.call.current_tool
+        admin_level = _get_tool_meta(tool, "admin_level", 0)
+        if admin_level > 0:
+            if not await PermissionUtils.check_admin_level(context, admin_level):
+                msg = (
+                    "系统警告：用户权限不足（需要等级 "
+                    f"{admin_level}）。"
+                    "请温和地向用户解释权限不足，并拒绝执行。"
+                )
+                user_id = context.get_user_id()
+                logger.warning(
+                    f"🛡️ [Capability] 权限拦截: 用户 {user_id} 尝试调用 "
+                    f"{getattr(tool, 'name', 'unknown')}"
+                )
+                from zhenxun.services.ai.core.exceptions import ToolFatalError
+
+                raise ToolFatalError(
+                    msg, display_content=f"❌ 权限不足: 需要等级 {admin_level}"
+                )
+        return await handler(arguments)
+
+
+class BillingCapability(AbstractCapability):
+    """经济系统中间件：执行前扣除金币"""
+
+    async def wrap_tool_execute(
+        self,
+        context: RunContext,
+        tool_name: str,
+        arguments: dict[str, Any],
+        handler: WrapToolExecuteHandler,
+    ) -> dict[str, Any]:
+        tool = context.call.current_tool
+        cost_gold = _get_tool_meta(tool, "cost_gold", 0)
+        if cost_gold > 0:
+            user_id = context.get_user_id()
+            platform = context.get_platform()
+            if user_id:
+                try:
+                    await UserConsole.reduce_gold(
+                        user_id,
+                        cost_gold,
+                        GoldHandle.PLUGIN,
+                        f"agent_tool:{getattr(tool, 'name', 'unknown')}",
+                        platform,
+                    )
+                except InsufficientGold:
+                    msg = (
+                        f"系统警告：用户金币不足（需要 {cost_gold} 金币，但余额不够）。"
+                        "请向用户解释金币不足，提醒可通过签到赚取，并拒绝执行。"
+                    )
+                    logger.warning(
+                        f"💰 [Capability] 金币拦截: 用户 {user_id} 尝试调用 "
+                        f"{getattr(tool, 'name', 'unknown')}"
+                    )
+                    from zhenxun.services.ai.core.exceptions import ToolFatalError
+
+                    raise ToolFatalError(
+                        msg, display_content=f"❌ 余额不足: 需要 {cost_gold} 金币"
+                    )
+        return await handler(arguments)
+
+
+class ToolRetryAndReflectionCapability(AbstractCapability):
+    """
+    重试与自愈反思中间件。
+    接管原执行器中的重试计数与致命异常熔断。
+    将 Python 异常优雅地转化为大模型的反思 Prompt。
+    """
+
+    async def wrap_tool_execute(
+        self,
+        context: RunContext,
+        tool_name: str,
+        arguments: dict[str, Any],
+        handler: WrapToolExecuteHandler,
+    ) -> Any:
+        try:
+            return await handler(arguments)
+        except Exception as e:
+            from zhenxun.services.ai.core.exceptions import (
+                AbortException,
+                ControlFlowExit,
+                ToolFatalError,
+                ToolFinishException,
+            )
+            from zhenxun.services.ai.tools.engine.executor import ToolExecutionPolicy
+            from zhenxun.services.ai.tools.models import ToolResult
+
+            if isinstance(e, ControlFlowExit):
+                raise e
+
+            retries = context.run.tool_retries.get(tool_name, 0)
+            retries += 1
+            context.run.tool_retries[tool_name] = retries
+
+            from typing import cast
+
+            from zhenxun.services.ai.tools.core.tool import BaseTool
+
+            tool = cast(BaseTool, context.call.current_tool)
+            policy = ToolExecutionPolicy(tool)
+            max_retries_limit = policy.max_retries
+
+            if isinstance(e, ToolFatalError | ToolFinishException):
+                display_msg = getattr(e, "display_content", f"❌ 系统致命错误: {e}")
+                raise AbortException(reason=str(e), display=display_msg)
+
+            if retries > max_retries_limit:
+                raise AbortException(
+                    reason=f"工具 '{tool_name}' 连续出错达 {retries} 次，超出上限。",
+                    display=f"🚨 工具 '{tool_name}' 已达最大重试次数，执行阻断。",
+                )
+
+            return ToolResult(output=f"执行发生异常: {e}").as_error()
+
+
+class ReflexionCapability(AbstractCapability):
+    """自愈反思与验证引擎 (Reflexion Engine)。
+    统一处理结构化解析失败 and 语义护栏拦截。"""
+
+    async def wrap_tool_execute(self, context, tool_name, arguments, handler):
+        try:
+            return await handler(arguments)
+        except Exception as error:
+            from zhenxun.services.ai.core.engine.structured_parser import (
+                DEFAULT_IVR_TEMPLATE,
+            )
+            from zhenxun.services.ai.core.exceptions import ModelRetry, ToolRetryError
+            from zhenxun.services.ai.tools.models import ToolResult
+
+            if isinstance(error, ToolRetryError | ModelRetry):
+                error_msg = getattr(error, "message", str(error))
+                feedback_prompt = DEFAULT_IVR_TEMPLATE.format(error_msg=error_msg)
+                context.run.add_system_prompt(feedback_prompt)
+                return ToolResult(
+                    output=f"执行失败：{error_msg}",
+                ).as_error()
+            raise error.with_traceback(None) from None
+
+    async def wrap_model_request(
+        self,
+        context: RunContext,
+        llm_context: LLMContext[ChatRequest, ChatResponse],
+        handler: WrapModelRequestHandler,
+    ) -> ChatResponse:
+        output_processor = llm_context.request.extra.get("output_processor")
+        guardrails = llm_context.request.extra.get("guardrails", [])
+
+        if not output_processor and not guardrails:
+            return await handler(llm_context)
+
+        max_retries = llm_context.request.extra.get("max_retries", 3)
+        error_template = (
+            output_processor.error_template if output_processor else "{error_msg}"
+        )
+
+        ivr_messages = list(llm_context.request.messages)
+        last_exception: Exception | None = None
+
+        from zhenxun.services.ai.guardrails import GuardrailPipeline
+
+        pipeline = GuardrailPipeline(guardrails) if guardrails else None
+
+        for attempt in range(max_retries + 1):
+            llm_context.request.messages = list(ivr_messages)
+            current_response_text: str = ""
+
+            try:
+                if pipeline:
+                    llm_context.request.messages = await pipeline.run_input_pipeline(
+                        llm_context.request.messages, context
+                    )
+
+                from typing import cast
+
+                response = await handler(llm_context)
+                current_response_text = response.text
+
+                if response.tool_calls:
+                    return response
+
+                if output_processor:
+                    final_obj = await output_processor.validate_and_parse(
+                        current_response_text, context=context
+                    )
+                else:
+                    final_obj = current_response_text
+
+                if pipeline:
+                    resp_out, final_obj_out = await pipeline.run_output_pipeline(
+                        response, final_obj, context
+                    )
+                    from typing import cast
+
+                    response = cast("ChatResponse", resp_out)
+                    final_obj = final_obj_out
+                    current_response_text = response.text
+
+                response.parsed_obj = final_obj
+                return response
+
+            except Exception as e:
+                from typing import cast
+
+                from zhenxun.services.ai.core.messages import LLMMessage
+
+                is_model_retry = isinstance(e, ModelRetry)
+                is_llm_error = isinstance(e, LLMException)
+                llm_error: LLMException | None = (
+                    cast(LLMException, e) if is_llm_error else None
+                )
+                last_exception = e
+
+                if (
+                    not is_model_retry
+                    and llm_error
+                    and not isinstance(
+                        llm_error, ResponseParseException | UpstreamServerException
+                    )
+                ):
+                    raise e
+
+                if attempt < max_retries:
+                    if is_model_retry:
+                        error_msg = getattr(e, "message", str(e))
+                        raw_response = current_response_text
+                    else:
+                        error_msg = (
+                            llm_error.details.get("validation_error", str(e))
+                            if llm_error
+                            else str(e)
+                        )
+                        raw_response = current_response_text or (
+                            llm_error.details.get("raw_response", "")
+                            if llm_error
+                            else ""
+                        )
+
+                    logger.warning(
+                        "输出校验未通过 "
+                        f"(尝试 {attempt + 1}/{max_retries + 1})。"
+                        f"启动反思修复闭环... 失败原因: {error_msg}"
+                    )
+
+                    if raw_response:
+                        ivr_messages.append(
+                            cast(
+                                LLMMessage,
+                                LLMMessage.assistant_text_response(raw_response),
+                            )
+                        )
+
+                    if isinstance(e, SchemaParseError):
+                        feedback_prompt = (
+                            "### ❌ [格式解析失败]\n"
+                            "你输出的结构化数据（JSON）格式损坏或字段不匹配，"
+                            "未能通过 Schema 校验。\n\n"
+                            "**解析错误报告：**\n"
+                            f"> {error_msg}\n\n"
+                            "**修正要求：** 请仔细检查缺失的必填字段、错误的数据类型或"
+                            "未闭合的括号，严格参考你可用的工具 Schema 定义，"
+                            "重新输出正确格式的数据。"
+                        )
+                    elif isinstance(e, GuardrailViolationError):
+                        feedback_prompt = (
+                            "### 🛡️ [业务护栏违规]\n"
+                            "你输出的数据格式完全正确，但在业务逻辑层触发了合规/风控护栏。\n\n"
+                            "**拦截原因报告：**\n"
+                            f"> {error_msg}\n\n"
+                            "**修正要求：** 请结合上述反馈报告，"
+                            "反思你的决策逻辑或内容生成，"
+                            "在保持数据格式正确的前提下，重新生成符合护栏规范的内容。"
+                        )
+                    else:
+                        if output_processor and error_template:
+                            feedback_prompt = error_template.format(error_msg=error_msg)
+                        else:
+                            from zhenxun.services.ai.core.engine import (
+                                structured_parser as sp,
+                            )
+
+                            feedback_prompt = sp.DEFAULT_IVR_TEMPLATE.format(
+                                error_msg=error_msg
+                            )
+                    ivr_messages.append(
+                        cast(LLMMessage, LLMMessage.user(feedback_prompt))
+                    )
+                    continue
+
+                if llm_error and not getattr(llm_error, "recoverable", True):
+                    raise llm_error.with_traceback(None) from None
+
+        if last_exception:
+            raise last_exception.with_traceback(None) from None
+        raise UpstreamServerException(
+            "反思循环耗尽，未能生成符合所有校验规则的合法结果。",
+        ).with_traceback(None) from None
@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+import graphlib
+from typing import TYPE_CHECKING, Any
+
+from zhenxun.services.ai.core.messages import ChatRequest, ChatResponse
+from zhenxun.services.ai.core.options import GenerationConfig
+
+from .base import (
+    AbstractCapability,
+    CapabilityRef,
+    WrapModelRequestHandler,
+    WrapRunHandler,
+    WrapToolExecuteHandler,
+    WrapToolValidateHandler,
+)
+
+if TYPE_CHECKING:
+    from zhenxun.services.ai.core.models import LLMContext
+    from zhenxun.services.ai.run import AgentRunResult, RunContext
+
+
+def sort_capabilities(caps: list["AbstractCapability"]) -> list["AbstractCapability"]:
+    """使用标准库 graphlib.TopologicalSorter 实现拦截器拓扑排序，解决执行顺序冲突"""
+    if len(caps) <= 1:
+        return caps
+
+    ts = graphlib.TopologicalSorter()
+    n = len(caps)
+    for i in range(n):
+        ts.add(i)
+
+    orderings = [c.get_ordering() for c in caps]
+    leaf_types = [{type(c)} for c in caps]
+
+    def _ref_matches(
+        ref: CapabilityRef, types: set[type], inst: AbstractCapability
+    ) -> bool:
+        if isinstance(ref, type):
+            return any(issubclass(t, ref) for t in types)
+        return inst is ref
+
+    all_types = set().union(*leaf_types)
+    for i, o in enumerate(orderings):
+        if o and o.requires:
+            for req in o.requires:
+                if not any(issubclass(t, req) for t in all_types):
+                    raise ValueError(
+                        f"Capability '{type(caps[i]).__name__}' 依赖 '{req.__name__}' "
+                        f"但未在管线中找到该组件。"
+                    )
+
+    outermost = {i for i, o in enumerate(orderings) if o and o.position == "outermost"}
+    innermost = {i for i, o in enumerate(orderings) if o and o.position == "innermost"}
+
+    for oi in outermost:
+        for j in range(n):
+            if j != oi and j not in outermost:
+                ts.add(j, oi)
+
+    for ii in innermost:
+        for j in range(n):
+            if j != ii and j not in innermost:
+                ts.add(ii, j)
+
+    for i, o in enumerate(orderings):
+        if not o:
+            continue
+        for ref in o.wraps:
+            for j in range(n):
+                if i != j and _ref_matches(ref, leaf_types[j], caps[j]):
+                    ts.add(j, i)
+        for ref in o.wrapped_by:
+            for j in range(n):
+                if i != j and _ref_matches(ref, leaf_types[j], caps[j]):
+                    ts.add(i, j)
+
+    try:
+        order = list(ts.static_order())
+    except graphlib.CycleError:
+        raise ValueError(
+            "Capability 拓扑排序失败，存在循环依赖约束。"
+            "请检查 wraps 或 wrapped_by 的配置。"
+        )
+
+    return [caps[i] for i in order]
+
+
+class CombinedCapability(AbstractCapability):
+    """
+    组合能力容器。
+    将多个 Capability 按顺序融合成一个复合的洋葱模型，
+    处理生命周期的正序/倒序和链式调用。
+    """
+
+    def __init__(self, capabilities: list[AbstractCapability]):
+        flat = []
+        for c in capabilities:
+            if isinstance(c, CombinedCapability):
+                flat.extend(c.capabilities)
+            else:
+                flat.append(c)
+
+        deduped = []
+        seen = set()
+        for c in flat:
+            if id(c) not in seen:
+                seen.add(id(c))
+                deduped.append(c)
+        self.capabilities = sort_capabilities(deduped)
+
+    async def for_run(self, context: RunContext) -> "AbstractCapability":
+        new_caps = []
+        changed = False
+        for cap in self.capabilities:
+            new_cap = await cap.for_run(context)
+            new_caps.append(new_cap)
+            if new_cap is not cap:
+                changed = True
+
+        if changed:
+            return CombinedCapability(new_caps)
+        return self
+
+    async def get_generation_config(
+        self, context: RunContext
+    ) -> GenerationConfig | None:
+        final_config = None
+        for cap in self.capabilities:
+            cap_config = await cap.get_generation_config(context)
+            if cap_config:
+                if final_config is None:
+                    final_config = cap_config
+                else:
+                    final_config = final_config.merge_with(cap_config)
+        return final_config
+
+    async def get_system_prompts(self, context: RunContext) -> list[str]:
+        prompts = []
+        for cap in self.capabilities:
+            prompts.extend(await cap.get_system_prompts(context))
+        return prompts
+
+    async def get_tools(self, context: RunContext) -> list[Any]:
+        tools = []
+        for cap in self.capabilities:
+            tools.extend(await cap.get_tools(context))
+        return tools
+
+    async def prepare_tools(
+        self, context: RunContext, tool_defs: list[Any]
+    ) -> list[Any]:
+        current_defs = list(tool_defs)
+        for cap in self.capabilities:
+            res = await cap.prepare_tools(context, current_defs)
+            if res is not None:
+                current_defs = res
+        return current_defs
+
+    async def wrap_run(
+        self, context: RunContext, handler: WrapRunHandler
+    ) -> "AgentRunResult[Any]":
+        chain = handler
+        for cap in reversed(self.capabilities):
+            chain = _make_wrap_link(cap, "wrap_run", context, {}, chain, None)
+        return await chain()
+
+    async def wrap_model_request(
+        self,
+        context: RunContext,
+        llm_context: LLMContext[ChatRequest, ChatResponse],
+        handler: WrapModelRequestHandler,
+    ) -> ChatResponse:
+        chain = handler
+        for cap in reversed(self.capabilities):
+            chain = _make_wrap_link(
+                cap, "wrap_model_request", context, {}, chain, "llm_context"
+            )
+        return await chain(llm_context)
+
+    async def wrap_tool_validate(
+        self,
+        context: RunContext,
+        tool_name: str,
+        args: str | dict[str, Any],
+        handler: WrapToolValidateHandler,
+    ) -> dict[str, Any]:
+        chain = handler
+        for cap in reversed(self.capabilities):
+            chain = _make_wrap_link(
+                cap,
+                "wrap_tool_validate",
+                context,
+                {"tool_name": tool_name},
+                chain,
+                "args",
+            )
+        return await chain(args)
+
+    async def wrap_tool_execute(
+        self,
+        context: RunContext,
+        tool_name: str,
+        arguments: dict[str, Any],
+        handler: WrapToolExecuteHandler,
+    ) -> Any:
+        chain = handler
+        for cap in reversed(self.capabilities):
+            chain = _make_wrap_link(
+                cap,
+                "wrap_tool_execute",
+                context,
+                {"tool_name": tool_name},
+                chain,
+                "arguments",
+            )
+        return await chain(arguments)
+
+
+def _make_wrap_link(
+    cap: AbstractCapability,
+    hook_name: str,
+    ctx: RunContext,
+    static_kwargs: dict[str, Any],
+    inner_handler: Callable[..., Any],
+    handler_arg: str | None,
+) -> Callable[..., Any]:
+    """构建洋葱模型中间件链的单一闭包节点。"""
+    frozen_kwargs = dict(static_kwargs)
+
+    if handler_arg:
+
+        async def wrapper(value: Any) -> Any:
+            kw = dict(frozen_kwargs)
+            kw[handler_arg] = value
+            hook_method = getattr(cap, hook_name)
+            return await hook_method(ctx, handler=inner_handler, **kw)
+
+        return wrapper
+
+    async def wrapper_no_arg() -> Any:
+        hook_method = getattr(cap, hook_name)
+        return await hook_method(ctx, handler=inner_handler, **frozen_kwargs)
+
+    return wrapper_no_arg
+
+
+class DynamicCapability(AbstractCapability):
+    """动态能力注入：允许在运行时基于上下文生成真正的 Capability"""
+
+    def __init__(self, capability_func: Callable):
+        self.capability_func = capability_func
+
+    @classmethod
+    def get_serialization_name(cls) -> str | None:
+        return None
+
+    async def for_run(self, context: RunContext) -> "AbstractCapability":
+        from nonebot.utils import is_coroutine_callable
+
+        if is_coroutine_callable(self.capability_func):
+            cap = await self.capability_func(context)
+        else:
+            cap = self.capability_func(context)
+        if cap is None:
+            return self
+        return await cap.for_run(context)
+
+
+class WrapperCapability(AbstractCapability):
+    """
+    代理包装能力基类 (Decorator Pattern)。
+    默认将所有生命周期钩子透明透传给内部包裹的 (wrapped) 实例。
+    """
+
+    def __init__(self, wrapped: AbstractCapability):
+        self.wrapped = wrapped
+
+    @classmethod
+    def get_serialization_name(cls) -> str | None:
+        return None
+
+    async def for_run(self, context: RunContext) -> "AbstractCapability":
+        new_wrapped = await self.wrapped.for_run(context)
+        if new_wrapped is self.wrapped:
+            return self
+        import copy
+
+        new_self = copy.copy(self)
+        new_self.wrapped = new_wrapped
+        return new_self
+
+    async def get_generation_config(
+        self, context: RunContext
+    ) -> GenerationConfig | None:
+        return await self.wrapped.get_generation_config(context)
+
+    async def get_system_prompts(self, context: RunContext) -> list[str]:
+        return await self.wrapped.get_system_prompts(context)
+
+    async def get_tools(self, context: RunContext) -> list[Any]:
+        return await self.wrapped.get_tools(context)
+
+    async def prepare_tools(
+        self, context: RunContext, tool_defs: list[Any]
+    ) -> list[Any]:
+        return await self.wrapped.prepare_tools(context, tool_defs)
+
+    async def wrap_run(
+        self, context: RunContext, handler: WrapRunHandler
+    ) -> "AgentRunResult[Any]":
+        return await self.wrapped.wrap_run(context, handler)
+
+    async def wrap_model_request(
+        self,
+        context: RunContext,
+        llm_context: LLMContext[ChatRequest, ChatResponse],
+        handler: WrapModelRequestHandler,
+    ) -> ChatResponse:
+        return await self.wrapped.wrap_model_request(context, llm_context, handler)
+
+    async def wrap_tool_validate(
+        self,
+        context: RunContext,
+        tool_name: str,
+        args: str | dict[str, Any],
+        handler: WrapToolValidateHandler,
+    ) -> dict[str, Any]:
+        return await self.wrapped.wrap_tool_validate(context, tool_name, args, handler)
+
+    async def wrap_tool_execute(
+        self,
+        context: RunContext,
+        tool_name: str,
+        arguments: dict[str, Any],
+        handler: WrapToolExecuteHandler,
+    ) -> Any:
+        return await self.wrapped.wrap_tool_execute(
+            context, tool_name, arguments, handler
+        )