♻️ refactor(core): 重构 AI 能力与定时任务调度系统 (#2148)

* ♻️ refactor(core): 重构 AI 能力与定时任务调度系统 - 【AI 能力与工具】重构 Capability 注册与管理机制，引入 CapabilityManager 统一管理 - 移除全局能力注册表，改用声明式装饰器 `@capability` 进行解耦注册 - 重构工具解析器链，使用统一的 BaseToolResolver 代替原有的多个特定解析器 - 增强工具查询过滤，支持通配符匹配、工具箱过滤和排除标签 - 【定时任务调度】重构定时任务管理器，引入 SchedulerRegistry 统一管理任务元数据 - 引入 JobConfig 聚合定时任务配置，支持用户维度的定时任务调度 - 重构执行分发器，支持并发限制、串行间隔和随机延迟打散 - 【运行上下文】引入 ScheduledDeps 以支持后台和定时任务环境下的依赖注入 - 优化 RunContext，支持从定时任务上下文快速构造，并提供 emit 辅助方法 - 【日志与监控】引入 AILoggerProxy，实现 AI 各模块的专属日志输出 - 将各模块的全局 logger 替换为对应的模块专属日志代理 - 【其他优化】修复 Pydantic V1 兼容层中 model_validator 的装饰器兼容性问题 - 在非交互式环境（如定时任务）中自动隐藏 HITL 交互工具以节省 Token * ♻️ refactor(core): 优化内部导入路径并提升 Pydantic 兼容性 - 【重构】将 `services/ai` 模块内的绝对导入重构为相对导入，优化包结构 - 【重构】移除不必要的 `if TYPE_CHECKING` 保护，通过 `from __future__ import annotations` 直接导入类型 - 【清理】清理 `core/messages/types.py` 中未使用的 `AssistantContentUnion` 等联合类型定义 - 【优化】在 `utils/pydantic_compat.py` 中新增 `model_rebuild` 兼容函数，统一 Pydantic V1/V2 的模型重建逻辑 - 【优化】将部分函数内部的延迟导入提升至模块顶部，规范代码结构 * ♻️ refactor(imports): 优化导入路径为相对导入并清理冗余导入 - 【重构】将 AI 服务相关模块中的绝对导入路径修改为相对导入，提升模块内聚性与可移植性 - 【清理】移除多处函数内部或类方法中未使用的冗余导入，避免循环引用和资源浪费 - 【格式化】微调部分工具装饰器和返回语句的格式与尾随逗号 * 🚨 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 18:50:05 +08:00 · 2026-07-10 09:14:06 +08:00
parent 0b32d69c9c
commit 922d092650
132 changed files with 2372 additions and 1972 deletions
@@ -5,9 +5,8 @@ from pathlib import Path
 from typing import Any, Generic, cast

 from zhenxun.services.ai.capabilities import (
-    AbstractCapability,
+    CapabilitySource,
    CombinedCapability,
-    DynamicCapability,
 )
 from zhenxun.services.ai.config import get_llm_config
 from zhenxun.services.ai.context.knowledge.base import BaseKnowledge
@@ -67,7 +66,7 @@ from zhenxun.services.ai.tools.providers.skills.capabilities import (
 )
 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.services.ai.utils.logger import log_agent as logger
 from zhenxun.utils.pydantic_compat import (
    model_construct,
    model_copy,
@@ -78,7 +77,9 @@ from zhenxun.utils.utils import infer_plugin_namespace

 from .engine.builders import (
    AgentProfileResolver,
+    CapabilityBuilder,
    ContextBuilder,
+    SessionBuilder,
    ToolBuilder,
 )
 from .engine.executor import BaseAgentExecutor, StandardAgentExecutor
@@ -94,9 +95,6 @@ ToolSource = (
 )
 """任何可以作为工具提供给大模型的实体对象（函数、基础工具类、字典定义、工具名、工具箱、声明式查询对象）"""

-CapabilitySource = Callable | AbstractCapability
-"""能力/拦截器来源（函数或 AbstractCapability 实例）"""
-

 class AgentBuilder(Generic[AgentDepsT, OutputDataT]):
    """
@@ -148,7 +146,7 @@ class AgentBuilder(Generic[AgentDepsT, OutputDataT]):
        return self

    def with_tools(
-        self, *tools: ToolSource | list[ToolSource]
+        self, *tools: ToolSource | Sequence[ToolSource]
    ) -> "AgentBuilder[AgentDepsT, OutputDataT]":
        """
        配置可供智能体调用的工具列表。
@@ -158,7 +156,7 @@ class AgentBuilder(Generic[AgentDepsT, OutputDataT]):
        """
        current_tools = self._kwargs.setdefault("tools", [])
        for t in tools:
-            if isinstance(t, list):
+            if isinstance(t, Sequence) and not isinstance(t, str):
                current_tools.extend(t)
            else:
                current_tools.append(t)
@@ -353,7 +351,7 @@ class Agent(
        description: str | None = None,
        persona: Persona | dict | None = None,
        model: str | Callable[[], str] | None = None,
-        tools: list[ToolSource] | None = None,
+        tools: Sequence[ToolSource] | None = None,
        skills: Sequence[str | Path | Skill | SkillSource] | None = None,
        generation_config: GenerationConfig | IntentBuilder | dict | None = None,
        response_model: BaseOutputDefinition | type[OutputDataT] | None = None,
@@ -458,14 +456,14 @@ class Agent(

    def _assemble_plugins(self, tools, knowledge, capabilities, skills):
        """私有方法：集中处理各类能力、知识与技能的挂载，消解冗余样板代码"""
-        self.tool_definitions = tools or []
+        self.tool_definitions = list(tools) if tools else []

        if knowledge:
            if not isinstance(knowledge, list):
                knowledge = [knowledge]
            self.tool_definitions.extend(knowledge)

-        self.capabilities: list[AbstractCapability] = []
+        self.capabilities: list[CapabilitySource] = []

        if self.memory_config.long_term.enable and self.memory_config.long_term.agentic:
            self.capabilities.append(
@@ -478,11 +476,7 @@ class Agent(
            )

        if capabilities:
-            for cap in capabilities:
-                if isinstance(cap, AbstractCapability):
-                    self.capabilities.append(cap)
-                elif callable(cap):
-                    self.capabilities.append(DynamicCapability(cap))
+            self.capabilities.extend(capabilities)

        if self.config.enable_hitl:
            self.tool_definitions.append(HITLToolkit())
@@ -789,11 +783,6 @@ class Agent(
        **kwargs: Any,
    ) -> tuple[AgentState, AgentRunResources]:
        """解析任务意图，初始化隔离域与基础状态载体"""
-        from zhenxun.services.ai.flow.agent.engine.builders import (
-            AgentProfileResolver,
-            CapabilityBuilder,
-            SessionBuilder,
-        )

        if context is None:
            raise ValueError("RunContext 不能为空")
@@ -900,7 +889,6 @@ class Agent(
            toolset_funcs=getattr(self, "toolset_funcs", []),
            system_tools=[],
            namespace=self.namespace or "unknown",
-            tool_filter=resources.config.tool_filter,
            run_context=context,
            run_scoped_cap=run_scoped_cap,
        )
@@ -1,6 +1,7 @@
 import asyncio
 from typing import Any, Generic, cast
 from typing_extensions import TypeVar
+import uuid

 from nonebot.adapters import Bot, Event
 from nonebot_plugin_alconna.uniseg import UniMessage
@@ -16,8 +17,9 @@ from zhenxun.services.ai.flow.base import BaseRunnable
 from zhenxun.services.ai.run import AgentRunResult, RunContext
 from zhenxun.services.ai.run.models import AgentRunEnd, AgentRunError
 from zhenxun.services.ai.run.ui import UIController
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_agent as logger
 from zhenxun.utils.message import MessageUtils
+from zhenxun.utils.platform import PlatformUtils

 T_Deps = TypeVar("T_Deps", default=Any)
 T_Out = TypeVar("T_Out", default=str)
@@ -46,8 +48,6 @@ class AgentRunner(Generic[T_Out]):
        )
        if is_stateless and self.context.session_id:
            if not self.context.session_id.startswith("stateless_"):
-                import uuid
-
                self.context.session_id = (
                    f"stateless_{self.context.session_id}_{uuid.uuid4().hex[:8]}"
                )
@@ -126,15 +126,24 @@ class AgentRunner(Generic[T_Out]):
                await MessageUtils.build_message(f"❌ 运行发生错误: {e}").send()
            raise e

-        if final_result and final_result.output and self._bot and self._event:
-            if isinstance(final_result.output, UniMessage):
-                await final_result.output.send(
-                    self._event, bot=self._bot, reply_to=reply_to
-                )
-                final_result.output = final_result.output.extract_plain_text()
+        if final_result and final_result.output and self._bot:
+            msg_to_send = (
+                final_result.output
+                if isinstance(final_result.output, UniMessage)
+                else MessageUtils.build_message(str(final_result.output))
+            )
+            if self._event:
+                await msg_to_send.send(self._event, bot=self._bot, reply_to=reply_to)
            else:
-                final_msg = str(final_result.output)
-                await MessageUtils.build_message(final_msg).send()
+                target = PlatformUtils.get_target(
+                    user_id=self.context.get_user_id(),
+                    group_id=self.context.get_group_id(),
+                )
+                if target:
+                    await msg_to_send.send(target=target, bot=self._bot)
+
+            if isinstance(final_result.output, UniMessage):
+                final_result.output = final_result.output.extract_plain_text()

        if final_result is None:
            raise RuntimeError("智能体运行流异常结束：未返回最终结果。")
@@ -12,7 +12,7 @@ from zhenxun.services.ai.core.messages import TaskLifecycleEvent
 from zhenxun.services.ai.core.options import BaseOutputDefinition, ToolOutput
 from zhenxun.services.ai.guardrails import parse_guardrails
 from zhenxun.services.ai.run import AgentRunResult, AgentTask, RunContext
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_agent as logger


 class OutputValidationCapability(AbstractCapability):
@@ -6,9 +6,7 @@ from typing import Any, cast
 from nonebot.utils import is_coroutine_callable

 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
@@ -22,13 +20,13 @@ from zhenxun.services.ai.flow.agent.capabilities import (
    TaskTrackingCapability,
 )
 from zhenxun.services.ai.flow.agent.models import Persona
-from zhenxun.services.ai.run import GLOBAL_CAPABILITIES, RunContext
+from zhenxun.services.ai.run import 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.tools.models import ResolvedToolPayload
 from zhenxun.services.ai.utils.scope import ScopeSelector
 from zhenxun.utils.pydantic_compat import model_copy

@@ -135,22 +133,21 @@ class CapabilityBuilder:
        if task_obj:
            dynamic_caps.append(TaskTrackingCapability(task_obj, agent_name))

-        run_level_caps = []
-        if profile_capabilities:
-            for cap in profile_capabilities:
-                if isinstance(cap, AbstractCapability):
-                    run_level_caps.append(cap)
-                elif callable(cap):
-                    run_level_caps.append(DynamicCapability(cap))
+        from zhenxun.services.ai.capabilities.manager import capability_manager

-        base_caps = GLOBAL_CAPABILITIES.get("global", []).copy()
-        if namespace != "global" and namespace in GLOBAL_CAPABILITIES:
-            base_caps.extend(GLOBAL_CAPABILITIES[namespace])
+        run_level_caps = capability_manager.resolve_capabilities(
+            profile_capabilities or [], namespace
+        )
+        agent_level_caps = capability_manager.resolve_capabilities(
+            agent_capabilities or [], namespace
+        )
+
+        auto_caps = capability_manager.get_auto_apply_capabilities(namespace)

        combined_cap = CombinedCapability(
-            base_caps
+            auto_caps
            + getattr(context, "capabilities", [])
-            + agent_capabilities
+            + agent_level_caps
            + run_level_caps
            + dynamic_caps
        )
@@ -298,7 +295,6 @@ class ToolBuilder:
        toolset_funcs: list[Any],
        system_tools: list[Any],
        namespace: str,
-        tool_filter: GlobalToolFilter | None,
        run_context: RunContext,
        run_scoped_cap: CombinedCapability,
    ) -> ResolvedToolPayload:
@@ -309,9 +305,8 @@ class ToolBuilder:
        参数：
            tool_definitions: 静态工具或工具集合的定义列表。
            toolset_funcs: 待依赖注入解析的工具集生成函数列表。
-            system_tools: 系统默认强制集成的工具定义列表。
+            system_tools: 系统默认强制集成的工具定义列表.
            namespace: 会话命名空间。
-            tool_filter: 全局的工具过滤条件，此处为占位。
            run_context: 运行上下文对象实例.
            run_scoped_cap: 运行域下的合并能力中间件，用于提供特定的能力工具。

@@ -411,14 +406,14 @@ class ToolBuilder:
            current_tool_defs = list(_cap_res)

        final_defs_map = {d.name.lower(): d for d in current_tool_defs if d}
-        final_effective_tools = ToolCollection()
+        final_effective_tools_list = []
        for t_exec in effective_tools:
            t_name = getattr(t_exec, "name", "unknown")
            if t_name.lower() in final_defs_map:
                cloned_tool = copy.copy(t_exec)
                cloned_tool._dynamic_def = final_defs_map[t_name.lower()]
-                final_effective_tools.append(cloned_tool)
-        return final_effective_tools
+                final_effective_tools_list.append(cloned_tool)
+        return ToolCollection(final_effective_tools_list)


 class SessionBuilder:
@@ -4,7 +4,7 @@ from collections.abc import Awaitable, Callable
 from zhenxun.services.ai.flow.agent.models import AgentRunResources, AgentState
 from zhenxun.services.ai.run.models import AgentRunResult, HandoffPayload
 from zhenxun.services.ai.tools.models import ToolResult
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_agent as logger
 from zhenxun.utils.pydantic_compat import model_construct
 from zhenxun.utils.utils import infer_plugin_namespace

@@ -63,7 +63,7 @@ async def handle_submit_structured(
    parsed_obj = (
        tool_res.directive.payload.get("parsed_obj") if tool_res.directive else None
    )
-    logger.info("✅ 拦截到结构化结果提交，结束循环。")
+    logger.debug("✅ 拦截到结构化结果提交，结束循环。")
    state.is_finished = True
    state.final_result = model_construct(
        AgentRunResult,
@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 import asyncio
 import json
-from typing import Any, cast
+from typing import Any

 from zhenxun.services.ai.capabilities import CombinedCapability
 from zhenxun.services.ai.core.engine.context_renderer import ContextConverter
@@ -15,7 +15,6 @@ from zhenxun.services.ai.core.exceptions import (
 )
 from zhenxun.services.ai.core.messages import (
    AgentMessage,
-    AssistantContentUnion,
    AssistantMessage,
    AudioPart,
    ChatRequest,
@@ -35,19 +34,20 @@ from zhenxun.services.ai.core.stream_events import (
    LLMStartEvent,
    ToolStreamChunkEvent,
 )
-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
+from zhenxun.services.ai.utils.logger import log_agent as logger
 from zhenxun.utils.pydantic_compat import dump_json_safely, model_construct

+from .directive import (
+    DirectiveHandlerFunc,
+    directive_manager,
+)
+

 class BaseAgentExecutor(ABC):
    """
@@ -219,13 +219,12 @@ class StandardAgentExecutor(BaseAgentExecutor):
            messages, run_context
        )

-        if run_context.run.event_bus:
-            await run_context.run.event_bus.emit(
-                LLMStartEvent(
-                    model_name=resources.model_name or "unknown",
-                    messages=flattened_messages,
-                )
+        await run_context.run.emit(
+            LLMStartEvent(
+                model_name=resources.model_name or "unknown",
+                messages=flattened_messages,
            )
+        )

        response = await self._execute_model_request(
            model_name=resources.model_name,
@@ -238,8 +237,7 @@ class StandardAgentExecutor(BaseAgentExecutor):
            cancellation_token=cancellation_token,
        )

-        if run_context.run.event_bus:
-            await run_context.run.event_bus.emit(LLMEndEvent(response=response))
+        await run_context.run.emit(LLMEndEvent(response=response))

        assistant_content = (
            response.content_parts if response.content_parts else response.text
@@ -252,9 +250,7 @@ class StandardAgentExecutor(BaseAgentExecutor):
                    part.metadata["thought_signature"] = response.thought_signature
                    break

-        assistant_message = AssistantMessage(
-            content=cast(list[AssistantContentUnion], response.content_parts)
-        )
+        assistant_message = AssistantMessage(content=response.content_parts)

        if hasattr(response, "parsed_obj") and response.parsed_obj is not None:
            if not isinstance(response.parsed_obj, str):
@@ -376,7 +372,7 @@ class StandardAgentExecutor(BaseAgentExecutor):
                state.messages, resources.model_name or "", base_overhead=0
            )
            logger.debug(
-                f"[TokenTracker] (Iter {state.current_cycle + 1}) "
+                f"(Iter {state.current_cycle + 1}) "
                f"预估将消耗 {est_tokens} Token "
                f"(Model: {resources.model_name or 'Unknown'})"
            )
@@ -444,7 +440,7 @@ class StandardAgentExecutor(BaseAgentExecutor):
            return

        if not response.tool_calls:
-            logger.debug("✅ AgentExecutor：模型未请求工具调用，推理循环结束。")
+            logger.debug("✅ 模型未请求工具调用，推理循环结束。")
            state.is_finished = True
            state.final_result = model_construct(
                AgentRunResult,
@@ -476,8 +472,7 @@ class StandardAgentExecutor(BaseAgentExecutor):

            if is_server_side:
                logger.debug(
-                    "☁️ [AgentExecutor] 检测到云端工具调用: "
-                    f"{call.tool_name}，已跳过本地执行。"
+                    f"☁️ 检测到云端工具调用: {call.tool_name}，已跳过本地执行。"
                )
                async with self.tool_executor._tool_stream_scope(
                    event_bus,
@@ -500,7 +495,7 @@ class StandardAgentExecutor(BaseAgentExecutor):
                client_tool_calls.append(call)

        if not client_tool_calls:
-            logger.info("✅ AgentExecutor：无本地客户端工具需执行，推理循环平滑结束。")
+            logger.info("✅ 无本地客户端工具需执行，推理循环平滑结束。")

            state.is_finished = True
            state.final_result = model_construct(
@@ -638,7 +633,6 @@ class StandardAgentExecutor(BaseAgentExecutor):
        self, state: AgentState, resources: AgentRunResources
    ) -> AgentRunResult[Any]:
        run_context = resources.run_context
-        event_bus = run_context.run.event_bus

        if not resources.config.enable_fallback_summary:
            raise UpstreamServerException(
@@ -646,17 +640,15 @@ class StandardAgentExecutor(BaseAgentExecutor):
            )

        logger.warning(
-            f"AgentExecutor 达到最大循环次数 ({resources.config.max_cycles})，"
-            "触发兜底总结机制。"
+            f"达到最大循环次数 ({resources.config.max_cycles})，触发兜底总结机制。"
        )

-        if event_bus:
-            await event_bus.emit(
-                ToolStreamChunkEvent(
-                    tool_name="System",
-                    content="⏳ 思考过程过于复杂，正在强制生成最终总结...",
-                )
+        await run_context.run.emit(
+            ToolStreamChunkEvent(
+                tool_name="System",
+                content="⏳ 思考过程过于复杂，正在强制生成最终总结...",
            )
+        )

        fallback_msg = LLMMessage.user(
            "### 🚨 [系统强制指令]\n"
@@ -1,12 +1,15 @@
-"""
-Agent 相关静态声明类型定义
-"""
+from __future__ import annotations

 from collections.abc import Sequence
+from pathlib import Path
 from typing import Any

 from pydantic import BaseModel, ConfigDict, Field

+from zhenxun.services.ai.capabilities import CapabilitySource, CombinedCapability
+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.context.memory.types import SessionMetadata
 from zhenxun.services.ai.core.messages import (
    AgentMessage,
@@ -18,8 +21,9 @@ from zhenxun.services.ai.core.messages import (
 from zhenxun.services.ai.core.options import GenerationConfig
 from zhenxun.services.ai.flow.base import BaseRuntimeConfig
 from zhenxun.services.ai.run import RunContext
+from zhenxun.services.ai.run.models import AgentRunResult, AgentTask, HandoffPayload
+from zhenxun.services.ai.tools.core.toolkit import BaseToolkit
 from zhenxun.services.ai.tools.engine.registry import ToolCollection
-from zhenxun.services.ai.tools.models import GlobalToolFilter
 from zhenxun.utils.pydantic_compat import model_copy


@@ -60,15 +64,14 @@ class AgentConfig(BaseRuntimeConfig):

    message_history: Sequence[AgentMessage] | None = Field(default=None)
    """初始化的底层对话历史记录。"""
-    tool_filter: GlobalToolFilter | None = Field(default=None)
-    """全局工具过滤器，限制本次运行可用的工具池。"""
-    memory: Any | None = Field(default=None)
+
+    memory: MemoryConfig | MemoryBuilder | bool | None = Field(default=None)
    """单次运行级别的记忆门面覆盖 (支持 bool, MemoryConfig, MemoryBuilder)。"""
    generation_config: GenerationConfig | None = Field(default=None)
    """单次运行覆盖的大模型生成配置。"""
-    capabilities: list[Any] | None = Field(default=None)
+    capabilities: list[CapabilitySource] | None = Field(default=None)
    """仅针对本次运行动态注入的临时拦截器/能力组件列表。"""
-    skills: Sequence[Any] | None = Field(default=None)
+    skills: Sequence[str | Path | Any] | None = Field(default=None)
    """仅针对本次运行动态注入的临时技能集合。"""
    executor: Any | None = Field(default=None)
    """单次运行覆盖的核心执行引擎策略 (BaseAgentExecutor)。"""
@@ -128,11 +131,11 @@ class AgentState(BaseModel):
    """拦截到的早期终止输出结果"""
    should_terminate: bool = False
    """标记是否应提前终止循环"""
-    handoff_triggered: Any | None = None
+    handoff_triggered: HandoffPayload | None = None
    """标记是否触发了移交"""
    is_finished: bool = False
    """标记大模型循环是否彻底结束"""
-    final_result: Any | None = None
+    final_result: AgentRunResult[Any] | None = None
    """最终的运行结果 (AgentRunResult)"""
    origin_msg_len: int = 0
    """初始进入循环时的消息历史长度 (用于增量保存记忆)"""
@@ -160,15 +163,15 @@ class AgentRunResources(BaseModel):
    """保留依赖注入(DI)与黑板引用的全局运行时上下文"""
    session_meta: SessionMetadata | None = None
    """隔离会话的元信息(Session ID, 命名空间, 权限等)"""
-    memory_reader: Any | None = None
+    memory_reader: MemoryReader | None = None
    """用于读取短/中/长期上下文记忆的读取器"""
-    memory_writer: Any | None = None
+    memory_writer: MemoryWriter | None = None
    """用于将对话历史安全落盘的写入器"""
-    run_scoped_cap: Any | None = None
+    run_scoped_cap: CombinedCapability | None = None
    """聚合了 Agent/AgentTask/全局 的复合能力拦截器 (CombinedCapability)"""
-    task_obj: Any | None = None
+    task_obj: AgentTask | None = None
    """(如有) 解析后的结构化数据任务契约"""
-    toolkits: list[Any] = Field(default_factory=list)
+    toolkits: list[BaseToolkit] = Field(default_factory=list)
    """当前轮次生效的工具箱列表 (需要执行生命周期挂载)"""
    config: AgentConfig = Field(default_factory=AgentConfig)
    """Agent 全局与运行时的统一策略配置"""