illusion-code 0.1.0__py3-none-any.whl

illusion/hooks/executor.py

@@ -0,0 +1,397 @@
+"""
+钩子执行引擎
+============
+
+本模块实现钩子的核心执行逻辑，支持多种钩子类型的异步执行。
+
+支持的钩子类型：
+    - CommandHookDefinition: 执行 Shell 命令
+    - HttpHookDefinition: 发送 HTTP 请求
+    - PromptHookDefinition: 使用模型验证
+    - AgentHookDefinition: 使用 Agent 深度验证
+
+主要组件：
+    - HookExecutionContext: 钩子执行上下文
+    - HookExecutor: 钩子执行器
+
+使用示例：
+    >>> from illusion.hooks.executor import HookExecutor, HookExecutionContext
+    >>> executor = HookExecutor(registry, context)
+    >>> result = await executor.execute(event, payload)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import json
+import os
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from illusion.api.client import ApiMessageCompleteEvent, ApiMessageRequest, SupportsStreamingMessages
+from illusion.engine.messages import ConversationMessage
+from illusion.hooks.events import HookEvent
+from illusion.hooks.loader import HookRegistry
+from illusion.hooks.schemas import (
+    AgentHookDefinition,
+    CommandHookDefinition,
+    HookDefinition,
+    HttpHookDefinition,
+    PromptHookDefinition,
+)
+from illusion.hooks.types import AggregatedHookResult, HookResult
+from illusion.sandbox import SandboxUnavailableError
+from illusion.utils.shell import create_shell_subprocess
+
+
+@dataclass
+class HookExecutionContext:
+    """
+    钩子执行上下文
+    
+    存储钩子执行所需的环境信息。
+    
+    Attributes:
+        cwd: 当前工作目录
+        api_client: API 客户端实例
+        default_model: 默认模型名称
+    """
+
+    cwd: Path  # 当前工作目录
+    api_client: SupportsStreamingMessages  # API 客户端
+    default_model: str  # 默认模型名称
+
+
+class HookExecutor:
+    """
+    钩子执行器
+    
+    管理钩子注册表和执行上下文，提供异步钩子执行能力。
+    
+    Attributes:
+        _registry: 钩子注册表
+        _context: 执行上下文
+    
+    使用示例：
+        >>> executor = HookExecutor(registry, context)
+        >>> result = await executor.execute(HookEvent.PRE_TOOL_USE, payload)
+    """
+
+    def __init__(self, registry: HookRegistry, context: HookExecutionContext) -> None:
+        self._registry = registry  # 钩子注册表
+        self._context = context  # 执行上下文
+
+    def update_registry(self, registry: HookRegistry) -> None:
+        """
+        替换活动的钩子注册表
+        
+        Args:
+            registry: 新的钩子注册表
+        """
+        self._registry = registry
+
+    def update_context(
+        self,
+        *,
+        api_client: SupportsStreamingMessages | None = None,
+        default_model: str | None = None,
+    ) -> None:
+        """
+        更新活动的钩子执行上下文
+        
+        Args:
+            api_client: 新的 API 客户端（可选）
+            default_model: 新的默认模型（可选）
+        """
+        if api_client is not None:
+            self._context.api_client = api_client
+        if default_model is not None:
+            self._context.default_model = default_model
+
+    async def execute(self, event: HookEvent, payload: dict[str, Any]) -> AggregatedHookResult:
+        """
+        执行事件对应的所有匹配钩子
+        
+        Args:
+            event: 钩子事件类型
+            payload: 事件载荷数据
+        
+        Returns:
+            AggregatedHookResult: 聚合的钩子执行结果
+        """
+        results: list[HookResult] = []  # 存储执行结果
+        # 遍历注册表中该事件的所有钩子
+        for hook in self._registry.get(event):
+            # 检查钩子是否与 payload 匹配
+            if not _matches_hook(hook, payload):
+                continue
+            # 根据钩子类型执行相应的处理方法
+            if isinstance(hook, CommandHookDefinition):
+                results.append(await self._run_command_hook(hook, event, payload))
+            elif isinstance(hook, HttpHookDefinition):
+                results.append(await self._run_http_hook(hook, event, payload))
+            elif isinstance(hook, PromptHookDefinition):
+                results.append(await self._run_prompt_like_hook(hook, event, payload, agent_mode=False))
+            elif isinstance(hook, AgentHookDefinition):
+                results.append(await self._run_prompt_like_hook(hook, event, payload, agent_mode=True))
+        return AggregatedHookResult(results=results)
+
+    async def _run_command_hook(
+        self,
+        hook: CommandHookDefinition,
+        event: HookEvent,
+        payload: dict[str, Any],
+    ) -> HookResult:
+        """
+        执行命令钩子
+        
+        Args:
+            hook: 命令钩子定义
+            event: 钩子事件
+            payload: 事件载荷
+        
+        Returns:
+            HookResult: 钩子执行结果
+        """
+        # 注入参数到命令中
+        command = _inject_arguments(hook.command, payload, shell_escape=True)
+        try:
+            # 创建子进程执行命令
+            process = await create_shell_subprocess(
+                command,
+                cwd=self._context.cwd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env={
+                    **os.environ,
+                    "illusion_HOOK_EVENT": event.value,  # 设置事件环境变量
+                    "illusion_HOOK_PAYLOAD": json.dumps(payload),  # 设置载荷环境变量
+                },
+            )
+        except SandboxUnavailableError as exc:
+            # 沙箱不可用时返回失败结果
+            return HookResult(
+                hook_type=hook.type,
+                success=False,
+                blocked=hook.block_on_failure,
+                reason=str(exc),
+            )
+
+        try:
+            # 等待命令完成，设置超时
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=hook.timeout_seconds,
+            )
+        except asyncio.TimeoutError:
+            # 超时杀死进程
+            process.kill()
+            await process.wait()
+            return HookResult(
+                hook_type=hook.type,
+                success=False,
+                blocked=hook.block_on_failure,
+                reason=f"command hook timed out after {hook.timeout_seconds}s",
+            )
+
+        # 合并 stdout 和 stderr
+        output = "\n".join(
+            part for part in (
+                stdout.decode("utf-8", errors="replace").strip(),
+                stderr.decode("utf-8", errors="replace").strip(),
+            ) if part
+        )
+        success = process.returncode == 0  # 检查退出码
+        return HookResult(
+            hook_type=hook.type,
+            success=success,
+            output=output,
+            blocked=hook.block_on_failure and not success,
+            reason=output or f"command hook failed with exit code {process.returncode}",
+            metadata={"returncode": process.returncode},
+        )
+
+    async def _run_http_hook(
+        self,
+        hook: HttpHookDefinition,
+        event: HookEvent,
+        payload: dict[str, Any],
+    ) -> HookResult:
+        """
+        执行 HTTP 钩子
+        
+        Args:
+            hook: HTTP 钩子定义
+            event: 钩子事件
+            payload: 事件载荷
+        
+        Returns:
+            HookResult: 钩子执行结果
+        """
+        try:
+            # 创建异步 HTTP 客户端并发送请求
+            async with httpx.AsyncClient(timeout=hook.timeout_seconds) as client:
+                response = await client.post(
+                    hook.url,
+                    json={"event": event.value, "payload": payload},
+                    headers=hook.headers,
+                )
+            success = response.is_success  # 检查响应状态
+            output = response.text  # 响应内容
+            return HookResult(
+                hook_type=hook.type,
+                success=success,
+                output=output,
+                blocked=hook.block_on_failure and not success,
+                reason=output or f"http hook returned {response.status_code}",
+                metadata={"status_code": response.status_code},
+            )
+        except Exception as exc:
+            # 异常时返回失败结果
+            return HookResult(
+                hook_type=hook.type,
+                success=False,
+                blocked=hook.block_on_failure,
+                reason=str(exc),
+            )
+
+    async def _run_prompt_like_hook(
+        self,
+        hook: PromptHookDefinition | AgentHookDefinition,
+        event: HookEvent,
+        payload: dict[str, Any],
+        *,
+        agent_mode: bool,
+    ) -> HookResult:
+        """
+        执行提示词或 Agent 钩子
+        
+        Args:
+            hook: 提示词或 Agent 钩子定义
+            event: 钩子事件
+            payload: 事件载荷
+            agent_mode: 是否使用 Agent 模式
+        
+        Returns:
+            HookResult: 钩子执行结果
+        """
+        # 注入参数到提示词中
+        prompt = _inject_arguments(hook.prompt, payload)
+        # 构建系统提示词前缀
+        prefix = (
+            "You are validating whether a hook condition passes in illusion. "
+            "Return strict JSON: {\"ok\": true} or {\"ok\": false, \"reason\": \"...\"}."
+        )
+        if agent_mode:
+            # Agent 模式需要更详细的推理
+            prefix += " Be more thorough and reason over the payload before deciding."
+        
+        # 构建 API 请求
+        request = ApiMessageRequest(
+            model=hook.model or self._context.default_model,  # 使用指定模型或默认模型
+            messages=[ConversationMessage.from_user_text(prompt)],
+            system_prompt=prefix,
+            max_tokens=512,
+        )
+
+        text_chunks: list[str] = []  # 存储文本块
+        final_event: ApiMessageCompleteEvent | None = None  # 最终事件
+        # 流式获取响应
+        async for event_item in self._context.api_client.stream_message(request):
+            if isinstance(event_item, ApiMessageCompleteEvent):
+                final_event = event_item
+            else:
+                text_chunks.append(event_item.text)
+
+        # 合并文本块
+        text = "".join(text_chunks)
+        # 如果有最终消息，使用最终消息的文本
+        if final_event is not None and final_event.message.text:
+            text = final_event.message.text
+
+        # 解析钩子返回的 JSON
+        parsed = _parse_hook_json(text)
+        if parsed["ok"]:
+            return HookResult(hook_type=hook.type, success=True, output=text)
+        return HookResult(
+            hook_type=hook.type,
+            success=False,
+            output=text,
+            blocked=hook.block_on_failure,
+            reason=parsed.get("reason", "hook rejected the event"),
+        )
+
+
+def _matches_hook(hook: HookDefinition, payload: dict[str, Any]) -> bool:
+    """
+    检查钩子是否与 payload 匹配
+    
+    Args:
+        hook: 钩子定义
+        payload: 事件载荷
+    
+    Returns:
+        bool: 是否匹配
+    """
+    # 获取匹配器
+    matcher = getattr(hook, "matcher", None)
+    if not matcher:
+        return True  # 没有匹配器则匹配所有
+    # 从 payload 中提取匹配主题
+    subject = str(payload.get("tool_name") or payload.get("prompt") or payload.get("event") or "")
+    # 使用 fnmatch 进行模式匹配
+    return fnmatch.fnmatch(subject, matcher)
+
+
+def _inject_arguments(
+    template: str, payload: dict[str, Any], *, shell_escape: bool = False
+) -> str:
+    """
+    将 payload 注入到模板字符串中
+    
+    Args:
+        template: 包含 $ARGUMENTS 占位符的模板
+        payload: 要注入的数据
+        shell_escape: 是否对 payload 进行 Shell 转义
+    
+    Returns:
+        str: 注入后的字符串
+    """
+    # 序列化 payload 为 JSON 字符串
+    serialized = json.dumps(payload, ensure_ascii=True)
+    if shell_escape:
+        # 对 Shell 命令进行转义
+        serialized = shlex.quote(serialized)
+    # 替换模板中的占位符
+    return template.replace("$ARGUMENTS", serialized)
+
+
+def _parse_hook_json(text: str) -> dict[str, Any]:
+    """
+    解析钩子返回的 JSON 响应
+    
+    Args:
+        text: 钩子返回的文本
+    
+    Returns:
+        dict: 解析后的结果字典
+    """
+    try:
+        # 尝试解析 JSON
+        parsed = json.loads(text)
+        # 验证格式
+        if isinstance(parsed, dict) and isinstance(parsed.get("ok"), bool):
+            return parsed
+    except json.JSONDecodeError:
+        pass
+    # 尝试简单文本匹配
+    lowered = text.strip().lower()
+    if lowered in {"ok", "true", "yes"}:
+        return {"ok": True}
+    # 返回失败结果
+    return {"ok": False, "reason": text.strip() or "hook returned invalid JSON"}

illusion/hooks/hot_reload.py

@@ -0,0 +1,74 @@
+"""
+钩子热重载模块
+==============
+
+本模块提供基于设置文件的热重载功能，当设置文件发生变化时自动重新加载钩子。
+
+主要组件：
+    - HookReloader: 钩子定义热重载器
+
+使用示例：
+    >>> from pathlib import Path
+    >>> from illusion.hooks.hot_reload import HookReloader
+    >>> reloader = HookReloader(Path("settings.yaml"))
+    >>> registry = reloader.current_registry()
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from illusion.config import load_settings
+from illusion.hooks.loader import HookRegistry, load_hook_registry
+
+
+class HookReloader:
+    """
+    钩子热重载器
+    
+    监控设置文件变化，在文件修改时自动重新加载钩子注册表。
+    
+    Attributes:
+        _settings_path: 设置文件路径
+        _last_mtime_ns: 上次文件修改时间（纳秒）
+        _registry: 当前钩子注册表
+    
+    使用示例：
+        >>> reloader = HookReloader(Path("settings.yaml"))
+        >>> registry = reloader.current_registry()
+    """
+
+    def __init__(self, settings_path: Path) -> None:
+        self._settings_path = settings_path  # 设置文件路径
+        self._last_mtime_ns = -1  # 初始为无效时间戳
+        self._registry = HookRegistry()  # 初始空注册表
+
+    def current_registry(self) -> HookRegistry:
+        """
+        获取当前注册表，必要时重新加载
+        
+        检查设置文件的修改时间，如果发生变化则重新加载钩子。
+        
+        Returns:
+            HookRegistry: 当前的钩子注册表
+        
+        注意：
+            - 如果文件不存在，返回空注册表
+            - 只有当文件修改时间变化时才重新加载
+        """
+        try:
+            # 获取文件状态信息
+            stat = self._settings_path.stat()
+        except FileNotFoundError:
+            # 文件不存在时，重置注册表
+            self._registry = HookRegistry()
+            self._last_mtime_ns = -1
+            return self._registry
+
+        # 检查文件是否被修改
+        if stat.st_mtime_ns != self._last_mtime_ns:
+            self._last_mtime_ns = stat.st_mtime_ns  # 更新修改时间
+            # 重新加载设置并构建注册表
+            self._registry = load_hook_registry(load_settings(self._settings_path))
+        
+        return self._registry  # 返回当前注册表

illusion/hooks/loader.py

@@ -0,0 +1,133 @@
+"""
+钩子加载器模块
+==============
+
+本模块提供从设置和插件加载钩子注册表的功能。
+
+主要功能：
+    - HookRegistry: 按事件分组存储钩子
+    - load_hook_registry: 从设置对象加载钩子注册表
+
+使用示例：
+    >>> from illusion.hooks.loader import HookRegistry, load_hook_registry
+    >>> registry = load_hook_registry(settings, plugins)
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from illusion.hooks.events import HookEvent
+from illusion.hooks.schemas import HookDefinition
+
+
+class HookRegistry:
+    """
+    钩子注册表
+    
+    按事件类型分组存储钩子定义，支持注册、获取和摘要生成。
+    
+    Attributes:
+        _hooks: 事件到钩子列表的映射字典
+    
+    使用示例：
+        >>> registry = HookRegistry()
+        >>> registry.register(HookEvent.PRE_TOOL_USE, hook_def)
+        >>> hooks = registry.get(HookEvent.PRE_TOOL_USE)
+    """
+
+    def __init__(self) -> None:
+        # 初始化钩子字典，使用 defaultdict 自动创建空列表
+        self._hooks: dict[HookEvent, list[HookDefinition]] = defaultdict(list)
+
+    def register(self, event: HookEvent, hook: HookDefinition) -> None:
+        """
+        注册一个钩子
+        
+        Args:
+            event: 钩子触发事件
+            hook: 钩子定义
+        """
+        # 将钩子添加到对应事件的列表中
+        self._hooks[event].append(hook)
+
+    def get(self, event: HookEvent) -> list[HookDefinition]:
+        """
+        获取指定事件的所有钩子
+        
+        Args:
+            event: 钩子触发事件
+        
+        Returns:
+            list[HookDefinition]: 钩子定义列表
+        """
+        # 返回事件对应的钩子列表的副本
+        return list(self._hooks.get(event, []))
+
+    def summary(self) -> str:
+        """
+        生成人类可读的钩子摘要
+        
+        Returns:
+            str: 格式化的钩子摘要字符串
+        """
+        lines: list[str] = []  # 存储摘要行
+        # 遍历所有事件类型
+        for event in HookEvent:
+            hooks = self.get(event)  # 获取事件对应的钩子
+            if not hooks:
+                continue  # 跳过没有钩子的事件
+            lines.append(f"{event.value}:")  # 添加事件名称
+            # 遍历每个钩子
+            for hook in hooks:
+                # 获取匹配器属性
+                matcher = getattr(hook, "matcher", None)
+                # 获取详情属性（command/prompt/url 之一）
+                detail = getattr(hook, "command", None) or getattr(hook, "prompt", None) or getattr(hook, "url", None) or ""
+                suffix = f" matcher={matcher}" if matcher else ""  # 匹配器后缀
+                lines.append(f"  - {hook.type}{suffix}: {detail}")  # 添加钩子详情
+        return "\n".join(lines)  # 拼接所有行
+
+
+def load_hook_registry(settings, plugins=None) -> HookRegistry:
+    """
+    从设置对象加载钩子注册表
+    
+    从主设置和插件中收集钩子定义，构建完整的注册表。
+    
+    Args:
+        settings: 包含 hooks 属性的设置对象
+        plugins: 可选的插件列表
+    
+    Returns:
+        HookRegistry: 加载完成的钩子注册表
+    
+    使用示例：
+        >>> registry = load_hook_registry(settings, plugins)
+    """
+    registry = HookRegistry()  # 创建新的注册表实例
+    
+    # 遍历设置中的钩子配置
+    for raw_event, hooks in settings.hooks.items():
+        try:
+            # 尝试将字符串转换为 HookEvent 枚举
+            event = HookEvent(raw_event)
+        except ValueError:
+            continue  # 跳过无效的事件名称
+        # 遍历事件中的钩子定义并注册
+        for hook in hooks:
+            registry.register(event, hook)
+    
+    # 遍历插件中的钩子配置
+    for plugin in plugins or []:
+        if not plugin.enabled:
+            continue  # 跳过未启用的插件
+        # 遍历插件的钩子配置
+        for raw_event, hooks in plugin.hooks.items():
+            try:
+                event = HookEvent(raw_event)
+            except ValueError:
+                continue  # 跳过无效的事件名称
+            for hook in hooks:
+                registry.register(event, hook)
+    
+    return registry  # 返回加载完成的注册表