zero-agent-core 0.2.0__py3-none-any.whl

agent_core/mcp/client.py

@@ -0,0 +1,212 @@
+"""MCP stdio 客户端适配器。
+
+Core 提供标准 MCP 会话管理和工具调用，不包含任何 Cesium、航线或业务白名单。
+应用层可以基于 ``McpToolCaller`` 包装自己的受限客户端。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import Mapping
+from contextlib import AsyncExitStack
+from pathlib import Path
+from typing import Protocol, cast
+
+from agent_core.mcp.errors import McpConnectionError, McpTimeoutError, McpToolError
+
+JsonObject = dict[str, object]
+_INHERITED_ENV_KEYS = frozenset(
+    {
+        "COMSPEC",
+        "HOME",
+        "LANG",
+        "PATH",
+        "PATHEXT",
+        "SYSTEMROOT",
+        "TEMP",
+        "TMP",
+        "USERPROFILE",
+    }
+)
+
+
+class McpToolCaller(Protocol):
+    """MCP 工具调用端口。"""
+
+    async def list_tools(self) -> list[str]: ...
+
+    async def call_tool(self, name: str, arguments: Mapping[str, object] | None = None) -> JsonObject: ...
+
+
+class McpToolClient:
+    """按需启动 MCP stdio 服务，并在生命周期内复用同一个会话。"""
+
+    def __init__(
+        self,
+        *,
+        command: str,
+        entrypoint: Path,
+        timeout_seconds: float,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        if timeout_seconds <= 0:
+            raise ValueError("timeout_seconds 必须大于 0")
+        self._command = command
+        self._entrypoint = entrypoint
+        self._timeout_seconds = timeout_seconds
+        self._env = dict(env or {})
+        self._session: object | None = None
+        self._runner_task: asyncio.Task[None] | None = None
+        self._ready: asyncio.Future[None] | None = None
+        self._close_requested: asyncio.Event | None = None
+        self._terminal_error: McpConnectionError | McpTimeoutError | None = None
+        self._start_lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        """启动会话并等待 MCP initialize 完成。"""
+        if self._session is not None:
+            return
+        async with self._start_lock:
+            if self._session is not None:
+                return
+            if not await asyncio.to_thread(self._entrypoint.is_file):
+                raise McpConnectionError(f"MCP 入口不存在：{self._entrypoint}")
+            if self._runner_task is None or self._runner_task.done():
+                loop = asyncio.get_running_loop()
+                self._ready = loop.create_future()
+                self._close_requested = asyncio.Event()
+                self._terminal_error = None
+                self._runner_task = asyncio.create_task(
+                    self._run_session(self._ready, self._close_requested),
+                    name=f"mcp-session:{self._entrypoint.name}",
+                )
+            ready = self._ready
+        if ready is None:
+            raise McpConnectionError("MCP 会话启动状态无效")
+        await asyncio.shield(ready)
+
+    async def list_tools(self) -> list[str]:
+        """列出 MCP 服务公开的工具名称。"""
+        session = await self._require_session()
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                result = await session.list_tools()  # type: ignore[attr-defined]
+        except TimeoutError as exc:
+            raise McpTimeoutError("MCP tools/list 超时") from exc
+        except Exception as exc:
+            raise McpToolError(f"MCP tools/list 调用失败：{exc}") from exc
+        return [str(tool.name) for tool in result.tools]
+
+    async def call_tool(self, name: str, arguments: Mapping[str, object] | None = None) -> JsonObject:
+        """调用 MCP 工具并要求其返回结构化对象。"""
+        session = await self._require_session()
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                result = await session.call_tool(name, dict(arguments or {}))  # type: ignore[attr-defined]
+        except TimeoutError as exc:
+            raise McpTimeoutError(f"MCP 工具 {name} 调用超时") from exc
+        except Exception as exc:
+            raise McpToolError(f"MCP 工具 {name} 调用失败：{exc}") from exc
+        if result.isError:
+            message = self._text_content(result.content) or "服务返回 isError=true"
+            raise McpToolError(f"MCP 工具 {name} 失败：{message}")
+        structured = result.structuredContent
+        if isinstance(structured, dict):
+            return cast(JsonObject, structured)
+        text = self._text_content(result.content)
+        if not text:
+            raise McpToolError(f"MCP 工具 {name} 未返回可读取的内容")
+        try:
+            decoded = json.loads(text)
+        except json.JSONDecodeError:
+            return {"content": text}
+        if isinstance(decoded, dict):
+            return cast(JsonObject, decoded)
+        return {"content": decoded}
+
+    async def aclose(self) -> None:
+        """关闭 MCP 会话及其 stdio 子进程。"""
+        async with self._start_lock:
+            task = self._runner_task
+            close_requested = self._close_requested
+            self._runner_task = None
+            self._ready = None
+            self._close_requested = None
+        if task is None:
+            return
+        if close_requested is not None:
+            close_requested.set()
+        await asyncio.shield(task)
+
+    async def __aenter__(self) -> McpToolClient:
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.aclose()
+
+    async def _require_session(self) -> object:
+        await self.start()
+        if self._session is not None:
+            return self._session
+        if self._terminal_error is not None:
+            raise self._terminal_error
+        raise McpConnectionError("MCP 会话初始化失败")
+
+    async def _run_session(self, ready: asyncio.Future[None], close_requested: asyncio.Event) -> None:
+        """在同一协程内持有 MCP 的异步上下文，保证会话生命周期完整。"""
+        stack = AsyncExitStack()
+        try:
+            try:
+                from mcp import ClientSession, StdioServerParameters
+                from mcp.client.stdio import stdio_client
+            except ImportError as exc:
+                raise McpConnectionError("MCP stdio 适配器需要安装 agent-core[mcp]") from exc
+            params = StdioServerParameters(
+                command=self._command,
+                args=[str(self._entrypoint)],
+                # 只继承启动子进程必需的系统变量，避免把模型密钥等无关秘密透传给 MCP。
+                env={
+                    **{key: value for key, value in os.environ.items() if key.upper() in _INHERITED_ENV_KEYS},
+                    **self._env,
+                },
+            )
+            async with asyncio.timeout(self._timeout_seconds):
+                read, write = await stack.enter_async_context(stdio_client(params))
+                session = await stack.enter_async_context(ClientSession(read, write))
+                await session.initialize()
+            self._session = session
+            ready.set_result(None)
+            await close_requested.wait()
+        except TimeoutError:
+            timeout_error = McpTimeoutError(f"MCP 初始化超时：{self._entrypoint.name}")
+            self._terminal_error = timeout_error
+            if not ready.done():
+                ready.set_exception(timeout_error)
+        except BaseException as exc:
+            connection_error = (
+                exc
+                if isinstance(exc, McpConnectionError)
+                else McpConnectionError(f"无法启动或维持 MCP 服务：{self._entrypoint}（{exc}）")
+            )
+            self._terminal_error = connection_error
+            if not ready.done():
+                ready.set_exception(connection_error)
+        finally:
+            self._session = None
+            try:
+                await stack.aclose()
+            except BaseException as exc:
+                self._terminal_error = McpConnectionError(f"关闭 MCP 服务失败：{self._entrypoint}（{exc}）")
+
+    @staticmethod
+    def _text_content(content: object) -> str | None:
+        if not isinstance(content, list):
+            return None
+        texts = [text for item in content if isinstance((text := getattr(item, "text", None)), str)]
+        return "\n".join(texts) if texts else None
+
+
+__all__ = ["JsonObject", "McpToolCaller", "McpToolClient"]

agent_core/mcp/errors.py

@@ -0,0 +1,26 @@
+"""MCP 通用错误类型。
+
+这些错误描述连接、超时和工具调用语义，与 Cesium、地图或任何具体业务无关。
+具体集成可以在此基础上继续定义领域错误。
+"""
+
+from agent_core.errors import AgentError
+
+
+class McpError(AgentError):
+    """MCP 基础错误。"""
+
+
+class McpConnectionError(McpError):
+    """MCP 连接或会话初始化失败。"""
+
+
+class McpTimeoutError(McpError):
+    """MCP 初始化、列举工具或调用工具超时。"""
+
+
+class McpToolError(McpError):
+    """MCP 服务返回工具执行失败或无效结果。"""
+
+
+__all__ = ["McpConnectionError", "McpError", "McpTimeoutError", "McpToolError"]

agent_core/middleware/__init__.py

@@ -0,0 +1,26 @@
+"""Agent 中间件。"""
+
+# 兼容旧导入路径；能力实现分别归属 hitl 和 compaction 领域模块。
+from agent_core.compaction.token_limit import TokenLimitMiddleware
+from agent_core.hitl.core import HumanInTheLoopMiddleware
+from agent_core.middleware.base import (
+    LoggingMiddleware,
+    Middleware,
+    MiddlewareAction,
+    MiddlewareContext,
+    MiddlewareManager,
+    MiddlewareResult,
+    RetryMiddleware,
+)
+
+__all__ = [
+    "HumanInTheLoopMiddleware",
+    "LoggingMiddleware",
+    "Middleware",
+    "MiddlewareAction",
+    "MiddlewareContext",
+    "MiddlewareManager",
+    "MiddlewareResult",
+    "RetryMiddleware",
+    "TokenLimitMiddleware",
+]

agent_core/middleware/base.py

@@ -0,0 +1,283 @@
+"""中间件机制实现。
+
+中间件可以在以下时机注入逻辑：
+1. before_model : LLM 调用前
+2. after_model  : LLM 调用后
+3. before_tool  : 工具执行前
+4. after_tool   : 工具执行后
+
+用法：
+    agent = ReActAgent(
+        llm=llm,
+        tool_executor=executor,
+        middleware=[
+            LoggingMiddleware(),
+            RetryMiddleware(max_retries=3),
+            TokenLimitMiddleware(max_tokens=4000),
+            HumanInTheLoopMiddleware(approval_needed=["takeoff_drone"]),
+        ],
+    )
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from agent_core.errors import (
+    ModelRateLimitError,
+    ModelTimeoutError,
+    ModelUnavailableError,
+)
+from agent_core.protocol.messages import Message
+
+logger = logging.getLogger(__name__)
+
+
+# ──────────────────────────────────────────────
+# 基础数据类型
+# ──────────────────────────────────────────────
+
+
+class MiddlewareAction(Enum):
+    CONTINUE = "continue"  # 继续执行
+    STOP = "stop"  # 停止执行（中止整个循环）
+    MODIFY = "modify"  # 修改数据（如裁剪消息历史）
+    RETRY = "retry"  # 重试当前 LLM 调用
+    ERROR = "error"  # 返回错误
+
+
+@dataclass
+class MiddlewareResult:
+    action: MiddlewareAction
+    data: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+
+@dataclass
+class MiddlewareContext:
+    messages: list[Message] = field(default_factory=list)
+    iteration: int = 0
+    tool_name: str | None = None
+    tool_args: dict[str, Any] = field(default_factory=dict)
+    tool_result: str | None = None
+    llm_response: Message | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    # 运行时事件上报入口。它让通用中间件可以记录压缩、重试等事件，
+    # 同时保持对独立单元测试和旧 Vanilla 调用方的兼容。
+    emit: Callable[..., Any] | None = None
+
+
+# ──────────────────────────────────────────────
+# 基类
+# ──────────────────────────────────────────────
+
+
+class Middleware:
+    """中间件基类，子类按需重写钩子方法。"""
+
+    @property
+    def name(self) -> str:
+        return self.__class__.__name__
+
+    async def before_model(self, context: MiddlewareContext) -> MiddlewareResult:
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def after_model(self, context: MiddlewareContext) -> MiddlewareResult:
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def before_tool(self, context: MiddlewareContext) -> MiddlewareResult:
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def after_tool(self, context: MiddlewareContext) -> MiddlewareResult:
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+
+# ──────────────────────────────────────────────
+# 中间件管理器
+# ──────────────────────────────────────────────
+
+
+class MiddlewareManager:
+    def __init__(self, middlewares: list[Middleware] | None = None) -> None:
+        self._middlewares = middlewares or []
+
+    def add(self, middleware: Middleware) -> None:
+        self._middlewares.append(middleware)
+
+    async def execute_before_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        return await self._run_chain("before_model", ctx)
+
+    async def execute_after_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        return await self._run_chain("after_model", ctx)
+
+    async def execute_before_tool(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        return await self._run_chain("before_tool", ctx)
+
+    async def execute_after_tool(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        return await self._run_chain("after_tool", ctx)
+
+    async def handle_exception(self, exc: Exception, ctx: MiddlewareContext) -> bool:
+        """让支持异常重试的中间件决定是否再次调用模型。"""
+        for mw in self._middlewares:
+            handler = getattr(mw, "handle_exception", None)
+            if handler is None:
+                continue
+            if await handler(exc, ctx):
+                return True
+        return False
+
+    async def _run_chain(self, hook: str, ctx: MiddlewareContext) -> MiddlewareResult:
+        modified_data: dict[str, Any] = {}
+        for mw in self._middlewares:
+            logger.debug("中间件 %s.%s", mw.name, hook)
+            previous_messages = ctx.messages
+            result: MiddlewareResult = await getattr(mw, hook)(ctx)
+            if result.action == MiddlewareAction.MODIFY:
+                # MODIFY 有两种合法写法：替换 ctx 字段（推荐），或在 data 中携带修改。
+                # 此处对账：本轮替换了 ctx.messages 时以 ctx 为准，防止 data 携带的
+                # 同名旧值把 ctx 的修改覆盖掉（Agent Loop 只读取聚合后的 data）。
+                if result.data:
+                    modified_data.update(result.data)
+                if ctx.messages is not previous_messages:
+                    modified_data["messages"] = ctx.messages
+                continue
+            if result.action != MiddlewareAction.CONTINUE:
+                logger.info("中间件 %s 阻断: action=%s", mw.name, result.action)
+                return result
+        if modified_data:
+            return MiddlewareResult(action=MiddlewareAction.MODIFY, data=modified_data)
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+
+# ──────────────────────────────────────────────
+# 内置中间件 1：日志
+# ──────────────────────────────────────────────
+
+
+class LoggingMiddleware(Middleware):
+    """记录所有 LLM / 工具调用的日志。"""
+
+    async def before_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        logger.info("[Log] before_model: iter=%d, msgs=%d", ctx.iteration, len(ctx.messages))
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def after_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        r = ctx.llm_response
+        logger.info(
+            "[Log] after_model: content_len=%d, tool_calls=%d",
+            len(r.content) if r else 0,
+            len(r.tool_calls) if r else 0,
+        )
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def before_tool(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        logger.info("[Log] before_tool: %s args=%s", ctx.tool_name, ctx.tool_args)
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def after_tool(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        logger.info(
+            "[Log] after_tool: %s result_len=%d",
+            ctx.tool_name,
+            len(ctx.tool_result) if ctx.tool_result else 0,
+        )
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+
+# ──────────────────────────────────────────────
+# 内置中间件 2：重试（生产级，支持指数退避）
+# ──────────────────────────────────────────────
+
+
+class RetryMiddleware(Middleware):
+    """自动重试失败的 LLM 调用。
+
+    处理场景：
+    - 空响应
+    - 模型适配器统一转换后的限流、超时和服务不可用错误
+
+    退避策略：wait = base_delay * (backoff_factor ** attempt)
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        backoff_factor: float = 2.0,
+        max_delay: float = 60.0,
+    ) -> None:
+        self._max_retries = max_retries
+        self._base_delay = base_delay
+        self._backoff_factor = backoff_factor
+        self._max_delay = max_delay
+
+    def _should_retry(self, exc: Exception) -> bool:
+        """判断异常是否值得重试。"""
+        return isinstance(
+            exc,
+            (ModelRateLimitError, ModelTimeoutError, ModelUnavailableError),
+        ) or bool(getattr(exc, "retryable", False))
+
+    async def after_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        r = ctx.llm_response
+        retry_count = ctx.metadata.get("retry_count", 0)
+
+        if retry_count >= self._max_retries:
+            return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+        # 空响应触发重试
+        if r is not None and not r.content and not r.tool_calls:
+            wait = min(
+                self._base_delay * (self._backoff_factor**retry_count),
+                self._max_delay,
+            )
+            logger.warning(
+                "[Retry] 空响应，第 %d/%d 次重试，等待 %.1fs",
+                retry_count + 1,
+                self._max_retries,
+                wait,
+            )
+            await asyncio.sleep(wait)
+            ctx.metadata["retry_count"] = retry_count + 1
+            return MiddlewareResult(
+                action=MiddlewareAction.RETRY,
+                data={"retry_count": retry_count + 1},
+            )
+
+        return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+    async def handle_exception(
+        self,
+        exc: Exception,
+        ctx: MiddlewareContext,
+    ) -> bool:
+        """外部调用：判断异常是否应重试，并执行等待。
+
+        Returns:
+            True 表示调用方应重试，False 表示直接抛出。
+        """
+        if not self._should_retry(exc):
+            return False
+
+        retry_count = ctx.metadata.get("retry_count", 0)
+        if retry_count >= self._max_retries:
+            return False
+
+        wait = min(
+            self._base_delay * (self._backoff_factor**retry_count),
+            self._max_delay,
+        )
+        logger.warning(
+            "[Retry] %s，第 %d/%d 次重试，等待 %.1fs",
+            type(exc).__name__,
+            retry_count + 1,
+            self._max_retries,
+            wait,
+        )
+        await asyncio.sleep(wait)
+        ctx.metadata["retry_count"] = retry_count + 1
+        return True

agent_core/model/__init__.py

@@ -0,0 +1,73 @@
+"""模型协议和模型工厂公共导出。"""
+
+from agent_core.model.catalog import (
+    ModelOption,
+    catalog_payload,
+    default_model_catalog,
+    provider_display_name,
+)
+from agent_core.model.core import (
+    ContextUsage,
+    ModelAdapter,
+    ModelProviderFactory,
+    ModelProviderRegistry,
+    StreamChunk,
+    build_tool_definition,
+    create_model_provider,
+    default_model_provider_registry,
+    register_model_provider,
+)
+from agent_core.model.governance import (
+    GovernedModelAdapter,
+    ModelExecutionPolicy,
+    SlidingWindowRateLimiter,
+    model_execution_scope,
+)
+from agent_core.model.providers import (
+    MODEL_PROVIDER_REGISTRY,
+    AnthropicProvider,
+    GeminiProvider,
+    OllamaProvider,
+    OpenAIProvider,
+    create_llm_provider,
+    known_context_window,
+)
+from agent_core.model.structured import (
+    StructuredOutputResult,
+    StructuredOutputSpec,
+    chat_structured,
+    parse_structured_output,
+    validate_json_schema,
+)
+
+__all__ = [
+    "MODEL_PROVIDER_REGISTRY",
+    "AnthropicProvider",
+    "ContextUsage",
+    "GeminiProvider",
+    "GovernedModelAdapter",
+    "ModelAdapter",
+    "ModelExecutionPolicy",
+    "ModelOption",
+    "ModelProviderFactory",
+    "ModelProviderRegistry",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "SlidingWindowRateLimiter",
+    "StreamChunk",
+    "StructuredOutputResult",
+    "StructuredOutputSpec",
+    "build_tool_definition",
+    "catalog_payload",
+    "chat_structured",
+    "create_llm_provider",
+    "create_model_provider",
+    "default_model_catalog",
+    "default_model_provider_registry",
+    "known_context_window",
+    "model_execution_scope",
+    "parse_structured_output",
+    "provider_display_name",
+    "register_model_provider",
+    "validate_json_schema",
+]

agent_core/model/catalog.py

@@ -0,0 +1,73 @@
+"""模型目录和运行时选择协议。
+
+目录只包含浏览器可以看到的模型标识和能力，不包含 API Key、地址或其他密钥。
+具体应用可以传入自己的目录，模型工厂仍由 ``model.core`` 负责创建适配器。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ModelOption:
+    """一个可供用户选择的模型。"""
+
+    provider: str
+    model: str
+    label: str
+    context_window_tokens: int | None = None
+    capabilities: frozenset[str] = field(
+        default_factory=lambda: frozenset({"chat", "stream", "tool_calling"})
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "provider": self.provider,
+            "model": self.model,
+            "label": self.label,
+            "context_window_tokens": self.context_window_tokens,
+            "capabilities": sorted(self.capabilities),
+        }
+
+
+def default_model_catalog() -> tuple[ModelOption, ...]:
+    """返回不依赖第三方 SDK 的安全默认目录。"""
+    return (
+        ModelOption("openai", "gpt-4o-mini", "OpenAI · GPT-4o mini", 128_000),
+        ModelOption("openai", "gpt-4.1-mini", "OpenAI · GPT-4.1 mini", 1_047_576),
+        ModelOption("anthropic", "claude-3-5-sonnet-latest", "Anthropic · Claude Sonnet"),
+        ModelOption("gemini", "gemini-2.0-flash", "Gemini · 2.0 Flash"),
+        ModelOption("ollama", "qwen2.5:7b", "Ollama · Qwen 2.5 7B"),
+    )
+
+
+#: provider 内部标识（小写）到 UI 显示名的映射。
+PROVIDER_DISPLAY_NAMES: dict[str, str] = {
+    "openai": "OpenAI",
+    "anthropic": "Anthropic",
+    "gemini": "Gemini",
+    "ollama": "Ollama",
+}
+
+
+def provider_display_name(provider: str) -> str:
+    """把 provider 标识转成展示名；未知 provider 原样返回（不强行改写）。"""
+    return PROVIDER_DISPLAY_NAMES.get(provider.strip().lower(), provider)
+
+
+def catalog_payload(
+    options: tuple[ModelOption, ...] | list[ModelOption] | None = None,
+) -> list[dict[str, Any]]:
+    """把模型目录转换为 API 可返回的 JSON。"""
+    return [item.to_dict() for item in (options or default_model_catalog())]
+
+
+__all__ = [
+    "PROVIDER_DISPLAY_NAMES",
+    "ModelOption",
+    "catalog_payload",
+    "default_model_catalog",
+    "provider_display_name",
+]