illusion-code 0.1.0__py3-none-any.whl

illusion/hooks/schemas.py

@@ -0,0 +1,121 @@
+"""
+钩子配置模式定义
+================
+
+本模块定义钩子的配置数据模型，使用 Pydantic 进行验证。
+
+支持的钩子类型：
+    - CommandHookDefinition: 执行 Shell 命令的钩子
+    - PromptHookDefinition: 使用模型验证条件的钩子
+    - HttpHookDefinition: 发送 HTTP 请求的钩子
+    - AgentHookDefinition: 使用 Agent 进行深度验证的钩子
+
+使用示例：
+    >>> from illusion.hooks.schemas import CommandHookDefinition
+    >>> hook = CommandHookDefinition(type="command", command="echo hello")
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class CommandHookDefinition(BaseModel):
+    """
+    命令钩子定义
+    
+    执行 Shell 命令的钩子类型。
+    
+    Attributes:
+        type: 钩子类型，固定为 "command"
+        command: 要执行的 shell 命令
+        timeout_seconds: 超时时间（秒），默认30秒，范围1-600
+        matcher: 可选的匹配器，用于过滤 payload
+        block_on_failure: 失败时是否阻止后续操作，默认 False
+    """
+
+    type: Literal["command"] = "command"  # 钩子类型标识
+    command: str  # 要执行的命令
+    timeout_seconds: int = Field(default=30, ge=1, le=600)  # 超时时间（秒）
+    matcher: str | None = None  # payload 匹配器
+    block_on_failure: bool = False  # 失败时是否阻塞
+
+
+class PromptHookDefinition(BaseModel):
+    """
+    提示词钩子定义
+    
+    使用大语言模型验证条件的钩子类型。
+    
+    Attributes:
+        type: 钩子类型，固定为 "prompt"
+        prompt: 验证提示词
+        model: 可选的模型名称，默认使用上下文中的模型
+        timeout_seconds: 超时时间（秒），默认30秒，范围1-600
+        matcher: 可选的匹配器，用于过滤 payload
+        block_on_failure: 失败时是否阻止后续操作，默认 True
+    """
+
+    type: Literal["prompt"] = "prompt"  # 钩子类型标识
+    prompt: str  # 验证提示词
+    model: str | None = None  # 可选的模型名称
+    timeout_seconds: int = Field(default=30, ge=1, le=600)  # 超时时间（秒）
+    matcher: str | None = None  # payload 匹配器
+    block_on_failure: bool = True  # 失败时是否阻塞
+
+
+class HttpHookDefinition(BaseModel):
+    """
+    HTTP 钩子定义
+    
+    向 HTTP 端点发送事件载荷的钩子类型。
+    
+    Attributes:
+        type: 钩子类型，固定为 "http"
+        url: 请求目标 URL
+        headers: 可选的请求头字典
+        timeout_seconds: 超时时间（秒），默认30秒，范围1-600
+        matcher: 可选的匹配器，用于过滤 payload
+        block_on_failure: 失败时是否阻止后续操作，默认 False
+    """
+
+    type: Literal["http"] = "http"  # 钩子类型标识
+    url: str  # 请求 URL
+    headers: dict[str, str] = Field(default_factory=dict)  # 请求头
+    timeout_seconds: int = Field(default=30, ge=1, le=600)  # 超时时间（秒）
+    matcher: str | None = None  # payload 匹配器
+    block_on_failure: bool = False  # 失败时是否阻塞
+
+
+class AgentHookDefinition(BaseModel):
+    """
+    Agent 钩子定义
+    
+    使用 Agent 进行深度模型验证的钩子类型。
+    
+    Attributes:
+        type: 钩子类型，固定为 "agent"
+        prompt: 验证提示词
+        model: 可选的模型名称，默认使用上下文中的模型
+        timeout_seconds: 超时时间（秒），默认60秒，范围1-1200
+        matcher: 可选的匹配器，用于过滤 payload
+        block_on_failure: 失败时是否阻止后续操作，默认 True
+    """
+
+    type: Literal["agent"] = "agent"  # 钩子类型标识
+    prompt: str  # 验证提示词
+    model: str | None = None  # 可选的模型名称
+    timeout_seconds: int = Field(default=60, ge=1, le=1200)  # 超时时间（秒）
+    matcher: str | None = None  # payload 匹配器
+    block_on_failure: bool = True  # 失败时是否阻塞
+
+
+# 联合类型：所有钩子定义的联合
+HookDefinition = (
+    CommandHookDefinition
+    | PromptHookDefinition
+    | HttpHookDefinition
+    | AgentHookDefinition
+)

illusion/hooks/types.py

@@ -0,0 +1,86 @@
+"""
+运行时钩子结果类型
+==================
+
+本模块定义钩子执行后的结果类型，包括单个钩子结果和聚合结果。
+
+主要类型：
+    - HookResult: 单个钩子的执行结果
+    - AggregatedHookResult: 多个钩子结果的聚合
+
+使用示例：
+    >>> from illusion.hooks.types import HookResult, AggregatedHookResult
+    >>> result = HookResult(hook_type="command", success=True, output="done")
+    >>> aggregated = AggregatedHookResult(results=[result])
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class HookResult:
+    """
+    单个钩子执行结果
+    
+    存储一个钩子执行后的状态和输出信息。
+    
+    Attributes:
+        hook_type: 钩子类型（command/prompt/http/agent）
+        success: 是否成功执行
+        output: 钩子输出内容
+        blocked: 是否阻止继续执行
+        reason: 阻止原因（当 blocked 为 True 时）
+        metadata: 附加元数据字典
+    """
+
+    hook_type: str  # 钩子类型标识
+    success: bool  # 执行是否成功
+    output: str = ""  # 钩子输出内容
+    blocked: bool = False  # 是否阻止后续操作
+    reason: str = ""  # 阻止原因描述
+    metadata: dict[str, Any] = field(default_factory=dict)  # 额外元数据
+
+
+@dataclass(frozen=True)
+class AggregatedHookResult:
+    """
+    聚合钩子结果
+    
+    聚合多个钩子的执行结果，提供统一的 blocked 和 reason 属性。
+    
+    Attributes:
+        results: 钩子结果列表
+    
+    使用示例：
+        >>> aggregated = AggregatedHookResult(results=[result1, result2])
+        >>> if aggregated.blocked:
+        ...     print(aggregated.reason)
+    """
+
+    results: list[HookResult] = field(default_factory=list)  # 钩子结果列表
+
+    @property
+    def blocked(self) -> bool:
+        """
+        检查是否有任何钩子阻止继续执行
+        
+        Returns:
+            bool: 如果任意一个钩子 blocked 为 True，返回 True
+        """
+        return any(result.blocked for result in self.results)
+
+    @property
+    def reason(self) -> str:
+        """
+        获取第一个阻止原因
+        
+        Returns:
+            str: 第一个 blocked=True 的钩子的 reason，如果没有则返回空字符串
+        """
+        for result in self.results:
+            if result.blocked:
+                return result.reason or result.output
+        return ""

illusion/mcp/__init__.py

@@ -0,0 +1,104 @@
+"""
+MCP 模块
+========
+
+本模块提供 MCP（Model Context Protocol）客户端和管理功能。
+
+主要组件：
+    - McpClientManager: MCP 客户端管理器
+    - McpServerConfig: MCP 服务器配置
+    - McpStdioServerConfig: STDIO 服务器配置
+    - McpHttpServerConfig: HTTP 服务器配置
+    - McpWebSocketServerConfig: WebSocket 服务器配置
+    - McpToolInfo: MCP 工具信息
+    - McpResourceInfo: MCP 资源信息
+    - McpConnectionStatus: MCP 连接状态
+    - load_mcp_server_configs: 加载 MCP 服务器配置
+    - load_project_mcp_configs: 加载项目级 MCP 配置
+
+使用示例：
+    >>> from illusion.mcp import McpClientManager, load_mcp_server_configs
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# 类型检查时导入，避免循环依赖
+if TYPE_CHECKING:  # pragma: no cover
+    from illusion.mcp.client import McpClientManager
+    from illusion.mcp.types import (
+        McpConnectionStatus,
+        McpHttpServerConfig,
+        McpJsonConfig,
+        McpResourceInfo,
+        McpServerConfig,
+        McpStdioServerConfig,
+        McpToolInfo,
+        McpWebSocketServerConfig,
+    )
+
+__all__ = [
+    "McpClientManager",
+    "McpConnectionStatus",
+    "McpHttpServerConfig",
+    "McpJsonConfig",
+    "McpResourceInfo",
+    "McpServerConfig",
+    "McpStdioServerConfig",
+    "McpToolInfo",
+    "McpWebSocketServerConfig",
+    "load_mcp_server_configs",
+    "load_project_mcp_configs",
+]
+
+
+def __getattr__(name: str):
+    # 延迟导入 McpClientManager，避免不必要的导入开销
+    if name == "McpClientManager":
+        from illusion.mcp.client import McpClientManager
+
+        return McpClientManager
+    # 延迟导入 load_mcp_server_configs
+    if name == "load_mcp_server_configs":
+        from illusion.mcp.config import load_mcp_server_configs
+
+        return load_mcp_server_configs
+    # 延迟导入 load_project_mcp_configs
+    if name == "load_project_mcp_configs":
+        from illusion.mcp.config import load_project_mcp_configs
+
+        return load_project_mcp_configs
+    # 延迟导入类型定义
+    if name in {
+        "McpConnectionStatus",
+        "McpHttpServerConfig",
+        "McpJsonConfig",
+        "McpResourceInfo",
+        "McpServerConfig",
+        "McpStdioServerConfig",
+        "McpToolInfo",
+        "McpWebSocketServerConfig",
+    }:
+        from illusion.mcp.types import (
+            McpConnectionStatus,
+            McpHttpServerConfig,
+            McpJsonConfig,
+            McpResourceInfo,
+            McpServerConfig,
+            McpStdioServerConfig,
+            McpToolInfo,
+            McpWebSocketServerConfig,
+        )
+
+        return {
+            "McpConnectionStatus": McpConnectionStatus,
+            "McpHttpServerConfig": McpHttpServerConfig,
+            "McpJsonConfig": McpJsonConfig,
+            "McpResourceInfo": McpResourceInfo,
+            "McpServerConfig": McpServerConfig,
+            "McpStdioServerConfig": McpStdioServerConfig,
+            "McpToolInfo": McpToolInfo,
+            "McpWebSocketServerConfig": McpWebSocketServerConfig,
+        }[name]
+    raise AttributeError(name)

illusion/mcp/client.py

@@ -0,0 +1,377 @@
+"""
+MCP 客户端管理器模块
+===================
+
+本模块提供 MCP（Model Context Protocol）客户端管理功能。
+
+主要功能：
+    - 管理 MCP 服务器连接
+    - 暴露 MCP 工具和资源
+    - 支持 STDIO 传输类型连接
+    - 提供工具调用和资源读取接口
+
+类说明：
+    - McpClientManager: MCP 客户端管理器类
+
+使用示例：
+    >>> from illusion.mcp.client import McpClientManager
+    >>> from illusion.mcp.types import McpStdioServerConfig
+    >>> 
+    >>> configs = {"my_server": McpStdioServerConfig(command="node", args=["server.js"])}
+    >>> manager = McpClientManager(configs)
+    >>> await manager.connect_all()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from contextlib import AsyncExitStack
+from typing import Any
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.types import CallToolResult, ReadResourceResult
+
+from illusion.mcp.types import (
+    McpConnectionStatus,
+    McpResourceInfo,
+    McpStdioServerConfig,
+    McpToolInfo,
+)
+
+
+class McpClientManager:
+    """
+    MCP 客户端管理器
+    
+    管理与 MCP 服务器的连接，并暴露服务器提供的工具和资源。
+    支持 STDIO 传输类型的服务器连接。
+    
+    Attributes:
+        _server_configs: 服务器名称到配置的映射
+        _statuses: 服务器名称到连接状态的映射
+        _sessions: 服务器名称到客户端会话的映射
+        _stacks: 服务器名称到异步退出栈的映射
+    
+    使用示例：
+        >>> manager = McpClientManager(configs)
+        >>> await manager.connect_all()
+        >>> tools = manager.list_tools()
+    """
+
+    def __init__(self, server_configs: dict[str, object]) -> None:
+        """
+        初始化 MCP 客户端管理器
+        
+        Args:
+            server_configs: 服务器名称到配置的映射字典
+        """
+        self._server_configs = server_configs
+        # 初始化所有服务器状态为 pending（待连接）
+        self._statuses: dict[str, McpConnectionStatus] = {
+            name: McpConnectionStatus(
+                name=name,
+                state="pending",
+                transport=getattr(config, "type", "unknown"),
+            )
+            for name, config in server_configs.items()
+        }
+        self._sessions: dict[str, ClientSession] = {}  # 存储活跃的客户端会话
+        self._stacks: dict[str, AsyncExitStack] = {}   # 存储异步上下文管理器栈
+
+    async def connect_all(self) -> None:
+        """
+        连接所有已配置的 STDIO 类型 MCP 服务器
+
+        并行连接所有 STDIO 类型的服务器以加速启动，
+        其他类型的服务器标记为失败（当前版本仅支持 STDIO）。
+        """
+        # 收集需要并行连接的 STDIO 服务器
+        stdio_tasks: list[tuple[str, McpStdioServerConfig]] = []
+        for name, config in self._server_configs.items():
+            if isinstance(config, McpStdioServerConfig):
+                stdio_tasks.append((name, config))
+            else:
+                # 其他传输类型标记为失败
+                self._statuses[name] = McpConnectionStatus(
+                    name=name,
+                    state="failed",
+                    transport=config.type,
+                    auth_configured=bool(getattr(config, "headers", None)),
+                    detail=f"Unsupported MCP transport in current build: {config.type}",
+                )
+
+        # 并行连接所有 STDIO 服务器
+        if stdio_tasks:
+            await asyncio.gather(
+                *(self._connect_stdio(name, config) for name, config in stdio_tasks),
+            )
+
+    async def reconnect_all(self) -> None:
+        """
+        重新连接所有已配置的服务器
+        
+        先关闭所有现有连接，然后重置状态并重新建立连接。
+        """
+        await self.close()
+        # 重置所有服务器状态为 pending
+        self._statuses = {
+            name: McpConnectionStatus(name=name, state="pending", transport=getattr(config, "type", "unknown"))
+            for name, config in self._server_configs.items()
+        }
+        await self.connect_all()
+
+    def update_server_config(self, name: str, config: object) -> None:
+        """
+        替换内存中的服务器配置
+        
+        Args:
+            name: 服务器名称
+            config: 新的服务器配置对象
+        """
+        self._server_configs[name] = config
+
+    def get_server_config(self, name: str) -> object | None:
+        """
+        获取指定的服务器配置
+        
+        Args:
+            name: 服务器名称
+        
+        Returns:
+            服务器配置对象，如果不存在则返回 None
+        """
+        return self._server_configs.get(name)
+
+    async def close(self) -> None:
+        """
+        关闭所有活跃的 MCP 会话
+        
+        释放所有资源，包括关闭流和清理会话。
+        """
+        # 关闭所有异步上下文栈
+        for stack in list(self._stacks.values()):
+            await stack.aclose()
+        self._stacks.clear()
+        self._sessions.clear()
+
+    def list_statuses(self) -> list[McpConnectionStatus]:
+        """
+        获取所有已配置服务器的状态列表
+        
+        Returns:
+            按服务器名称排序的连接状态列表
+        """
+        return [self._statuses[name] for name in sorted(self._statuses)]
+
+    def list_tools(self) -> list[McpToolInfo]:
+        """
+        获取所有已连接 MCP 服务器提供的工具列表
+        
+        Returns:
+            合并后的工具信息列表
+        """
+        tools: list[McpToolInfo] = []
+        for status in self.list_statuses():
+            tools.extend(status.tools)
+        return tools
+
+    def list_resources(self, *, server_name: str | None = None) -> list[McpResourceInfo]:
+        """
+        获取所有已连接 MCP 服务器提供的资源列表
+         
+        Returns:
+            合并后的资源信息列表
+        """
+        if server_name is not None:
+            status = self._statuses.get(server_name)
+            if status is None:
+                return []
+            return list(status.resources)
+        resources: list[McpResourceInfo] = []
+        for status in self.list_statuses():
+            resources.extend(status.resources)
+        return resources
+
+    async def call_tool(self, server_name: str, tool_name: str, arguments: dict[str, Any]) -> str:
+        """
+        调用指定的 MCP 工具
+        
+        在指定服务器上调用工具并返回字符串形式的结果。
+        
+        Args:
+            server_name: 服务器名称
+            tool_name: 工具名称
+            arguments: 工具参数字典
+        
+        Returns:
+            工具执行结果的字符串形式
+        """
+        session = self._require_session(server_name)
+        result: CallToolResult = await session.call_tool(tool_name, arguments)
+        parts: list[str] = []
+        # 处理返回的内容，支持文本和其他类型
+        for item in result.content:
+            if getattr(item, "type", None) == "text":
+                parts.append(getattr(item, "text", ""))
+            else:
+                parts.append(item.model_dump_json())
+        # 如果有结构化内容但没有文本 parts，添加结构化内容
+        if result.structuredContent and not parts:
+            parts.append(str(result.structuredContent))
+        # 如果没有输出，返回默认消息
+        if not parts:
+            parts.append("(no output)")
+        return "\n".join(parts).strip()
+
+    async def read_resource(self, server_name: str, uri: str) -> str:
+        """
+        读取指定的 MCP 资源
+        
+        从指定服务器读取资源并返回字符串形式的内容。
+        
+        Args:
+            server_name: 服务器名称
+            uri: 资源统一标识符
+        
+        Returns:
+            资源内容的字符串形式
+        """
+        session = self._require_session(server_name)
+        result: ReadResourceResult = await session.read_resource(uri)
+        parts: list[str] = []
+        for item in result.contents:
+            text = getattr(item, "text", None)
+            if text is not None:
+                parts.append(text)
+            else:
+                parts.append(str(getattr(item, "blob", "")))
+        return "\n".join(parts).strip()
+
+    async def _connect_stdio(self, name: str, config: McpStdioServerConfig) -> None:
+        """
+        连接 STDIO 类型的 MCP 服务器
+        
+        建立与 STDIO 服务器的连接，初始化会话，并获取服务器提供的工具和资源列表。
+        
+        Args:
+            name: 服务器名称
+            config: STDIO 服务器配置
+        """
+        stack = AsyncExitStack()
+        try:
+            # 确定 stderr 输出目标：如果配置了 log_file 则重定向到文件
+            errlog = sys.stderr
+            if config.log_file:
+                from pathlib import Path
+                log_path = Path(config.log_file)
+                log_path.parent.mkdir(parents=True, exist_ok=True)
+                errlog = open(log_path, "a", encoding="utf-8")
+                stack.callback(errlog.close)
+
+            # 创建 STDIO 客户端连接
+            read_stream, write_stream = await stack.enter_async_context(
+                stdio_client(
+                    StdioServerParameters(
+                        command=config.command,
+                        args=config.args,
+                        env=config.env,
+                        cwd=config.cwd,
+                    ),
+                    errlog=errlog,
+                )
+            )
+            # 创建客户端会话
+            session = await stack.enter_async_context(ClientSession(read_stream, write_stream))
+            await session.initialize()
+            # 获取服务器提供的工具列表
+            tool_result = await session.list_tools()
+            # 转换工具信息为内部数据模型
+            tools = [
+                McpToolInfo(
+                    server_name=name,
+                    name=tool.name,
+                    description=tool.description or "",
+                    input_schema=dict(tool.inputSchema or {"type": "object", "properties": {}}),
+                )
+                for tool in tool_result.tools
+            ]
+            # 获取服务器提供的资源列表（可选能力，服务器可能不支持）
+            resources: list[McpResourceInfo] = []
+            try:
+                resource_result = await session.list_resources()
+                resources = [
+                    McpResourceInfo(
+                        server_name=name,
+                        name=resource.name or str(resource.uri),
+                        uri=str(resource.uri),
+                        description=resource.description or "",
+                    )
+                    for resource in resource_result.resources
+                ]
+            except Exception:
+                # 服务器不支持 resources 能力，忽略错误
+                pass
+            # 获取资源模板（部分服务器只暴露模板，不暴露静态资源）
+            try:
+                template_result = await session.list_resource_templates()
+                template_items = getattr(template_result, "resourceTemplates", None)
+                if template_items is None:
+                    template_items = getattr(template_result, "resource_templates", [])
+                for template in template_items or []:
+                    template_uri = str(
+                        getattr(template, "uriTemplate", None)
+                        or getattr(template, "uri_template", None)
+                        or ""
+                    ).strip()
+                    if not template_uri:
+                        continue
+                    if any(item.uri == template_uri for item in resources):
+                        continue
+                    resources.append(
+                        McpResourceInfo(
+                            server_name=name,
+                            name=getattr(template, "name", None) or template_uri,
+                            uri=template_uri,
+                            description=getattr(template, "description", "") or "",
+                        )
+                    )
+            except Exception:
+                # 服务器不支持 resource templates 能力，忽略错误
+                pass
+            # 保存会话和栈
+            self._sessions[name] = session
+            self._stacks[name] = stack
+            # 更新连接状态为已连接
+            self._statuses[name] = McpConnectionStatus(
+                name=name,
+                state="connected",
+                transport=config.type,
+                auth_configured=bool(config.env),
+                tools=tools,
+                resources=resources,
+            )
+        except Exception as exc:
+            # 连接失败，清理资源并更新状态
+            await stack.aclose()
+            self._statuses[name] = McpConnectionStatus(
+                name=name,
+                state="failed",
+                transport=config.type,
+                auth_configured=bool(config.env),
+                detail=str(exc),
+            )
+
+    def _require_session(self, server_name: str) -> ClientSession:
+        """获取服务器会话，不存在时抛出可读错误。"""
+        session = self._sessions.get(server_name)
+        if session is not None:
+            return session
+        status = self._statuses.get(server_name)
+        if status is None:
+            raise ValueError(f"Unknown MCP server: {server_name}")
+        detail = f" ({status.detail})" if status.detail else ""
+        raise ValueError(
+            f"MCP server '{server_name}' is not connected (state={status.state}{detail})"
+        )