illusion-code 0.1.0__py3-none-any.whl

illusion/engine/query_engine.py

@@ -0,0 +1,343 @@
+"""高级对话引擎。
+
+本模块提供高级对话引擎，管理对话历史和工具感知的模型循环。
+
+主要功能：
+    - 管理对话历史
+    - 执行用户消息提交
+    - 支持待续工具调用继续
+    - 跟踪令牌使用成本
+
+主要类：
+    - QueryEngine: 对话引擎主类
+
+使用示例：
+    >>> from illusion.engine import QueryEngine
+    >>> engine = QueryEngine(
+    ...     api_client=client,
+    ...     tool_registry=registry,
+    ...     permission_checker=checker,
+    ...     cwd=".",
+    ...     model="claude-3-opus",
+    ...     system_prompt="你是一个助手"
+    ... )
+    >>> async for event in engine.submit_message("你好"):
+    ...     print(event)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import AsyncIterator
+
+from illusion.api.client import SupportsStreamingMessages
+from illusion.api.effort import EffortLevel
+from illusion.engine.cost_tracker import CostTracker
+from illusion.engine.messages import ConversationMessage, ToolResultBlock
+from illusion.engine.query import AskUserPrompt, BackgroundAgentTracker, PermissionPrompt, QueryContext, run_query
+from illusion.engine.stream_events import StreamEvent
+from illusion.hooks import HookExecutor
+from illusion.permissions.checker import PermissionChecker
+from illusion.services.compact import AutoCompactState
+from illusion.services.file_history import FileHistoryState, track_edit, make_snapshot
+from illusion.tools.base import ToolRegistry
+
+
+class QueryEngine:
+    """拥有对话历史和工具感知模型循环的高级引擎。
+
+    管理整个对话生命周期，包括消息提交、工具执行、成本跟踪等。
+
+    Attributes:
+        messages: 当前对话历史（只读）
+        max_turns: 每个用户输入的最大智能体轮次数
+        total_usage: 跨所有轮次的总使用量
+
+    使用示例：
+        >>> engine = QueryEngine(
+        ...     api_client=client,
+        ...     tool_registry=registry,
+        ...     permission_checker=checker,
+        ...     cwd=".",
+        ...     model="claude-3-opus",
+        ...     system_prompt="你是一个助手"
+        ... )
+    """
+
+    def __init__(
+        self,
+        *,
+        api_client: SupportsStreamingMessages,
+        tool_registry: ToolRegistry,
+        permission_checker: PermissionChecker,
+        cwd: str | Path,
+        model: str,
+        system_prompt: str,
+        max_tokens: int = 4096,
+        max_turns: int | None = 8,
+        permission_prompt: PermissionPrompt | None = None,
+        ask_user_prompt: AskUserPrompt | None = None,
+        hook_executor: HookExecutor | None = None,
+        tool_metadata: dict[str, object] | None = None,
+        effort: EffortLevel | None = None,
+        session_id: str = "",
+    ) -> None:
+        self._api_client = api_client  # API客户端
+        self._tool_registry = tool_registry  # 工具注册表
+        self._permission_checker = permission_checker  # 权限检查器
+        self._cwd = Path(cwd).resolve()  # 当前工作目录
+        self._model = model  # 模型名称
+        self._system_prompt = system_prompt  # 系统提示词
+        self._max_tokens = max_tokens  # 最大令牌数
+        self._max_turns = max_turns  # 最大轮次
+        self._permission_prompt = permission_prompt  # 权限提示回调
+        self._ask_user_prompt = ask_user_prompt  # 用户询问回调
+        self._hook_executor = hook_executor  # 钩子执行器
+        self._tool_metadata = tool_metadata or {}  # 工具元数据
+        self._effort = effort  # effort 级别
+        self._messages: list[ConversationMessage] = []  # 对话消息历史
+        self._cost_tracker = CostTracker()  # 成本跟踪器
+        self._bg_agent_tracker = BackgroundAgentTracker()  # 后台代理追踪器
+        self._compact_state = AutoCompactState()  # 自动压缩状态（跨会话持久）
+        self._file_history: FileHistoryState | None = None  # 文件历史状态
+        self._session_id: str = session_id or ""  # 会话 ID（用于文件历史目录）
+
+    @property
+    def effort(self) -> EffortLevel | None:
+        """返回当前的 effort 级别。
+
+        Returns:
+            EffortLevel | None: 当前的 effort 级别
+        """
+        return self._effort
+
+    @effort.setter
+    def effort(self, value: EffortLevel | None) -> None:
+        """设置 effort 级别。
+
+        Args:
+            value: 新的 effort 级别
+        """
+        self._effort = value
+
+    @property
+    def messages(self) -> list[ConversationMessage]:
+        """返回当前对话历史。
+
+        Returns:
+            list[ConversationMessage]: 消息列表的副本
+        """
+        return list(self._messages)
+
+    @property
+    def max_turns(self) -> int | None:
+        """返回每个用户输入的最大智能体轮次数（如果有上限）。
+
+        Returns:
+            int | None: 最大轮次数或None（无限制）
+        """
+        return self._max_turns
+
+    @property
+    def total_usage(self):
+        """返回跨所有轮次的总使用量。
+
+        Returns:
+            UsageSnapshot: 累积的使用量快照
+        """
+        return self._cost_tracker.total
+
+    def clear(self) -> None:
+        """清除内存中的对话历史。
+
+        同时重置成本跟踪器。
+        """
+        self._messages.clear()
+        self._cost_tracker = CostTracker()
+
+    def set_system_prompt(self, prompt: str) -> None:
+        """更新未来轮次的活跃系统提示词。
+
+        Args:
+            prompt: 新的系统提示词
+        """
+        self._system_prompt = prompt
+
+    def set_model(self, model: str) -> None:
+        """更新未来轮次的活跃模型。
+
+        Args:
+            model: 新的模型名称
+        """
+        self._model = model
+
+    def set_api_client(self, api_client: SupportsStreamingMessages) -> None:
+        """更新未来轮次的活跃API客户端。
+
+        Args:
+            api_client: 新的API客户端
+        """
+        self._api_client = api_client
+
+    def set_max_turns(self, max_turns: int | None) -> None:
+        """更新每个用户输入的最大智能体轮次数。
+
+        Args:
+            max_turns: 最大轮次数，None表示无限制
+        """
+        self._max_turns = None if max_turns is None else max(1, int(max_turns))
+
+    def set_permission_checker(self, checker: PermissionChecker) -> None:
+        """更新未来轮次的活跃权限检查器。
+
+        Args:
+            checker: 新的权限检查器
+        """
+        self._permission_checker = checker
+
+    def load_messages(self, messages: list[ConversationMessage]) -> None:
+        """替换内存中的对话历史。
+
+        Args:
+            messages: 新的消息列表
+        """
+        self._messages = list(messages)
+
+    @property
+    def file_history(self) -> FileHistoryState | None:
+        """返回文件历史状态。"""
+        return self._file_history
+
+    def _extract_file_paths(self, tool_name: str, tool_input: dict) -> list[str]:
+        """从工具输入中提取文件路径。"""
+        path_keys = ("path", "file_path", "notebook_path")
+        paths = []
+        for key in path_keys:
+            if key in tool_input and isinstance(tool_input[key], str):
+                paths.append(tool_input[key])
+        return paths
+
+    def has_pending_continuation(self) -> bool:
+        """当对话以等待后续模型轮次的工具结果结束时返回True。
+
+        用于检查是否有待续的工具调用需要继续执行。
+
+        Returns:
+            bool: 是否有待续的继续
+        """
+        if not self._messages:
+            return False
+        last = self._messages[-1]
+        if last.role != "user":
+            return False
+        if not any(isinstance(block, ToolResultBlock) for block in last.content):
+            return False
+        for msg in reversed(self._messages[:-1]):
+            if msg.role != "assistant":
+                continue
+            return bool(msg.tool_uses)
+        return False
+
+    async def submit_message(self, prompt: str) -> AsyncIterator[StreamEvent]:
+        """追加用户消息并执行查询循环。
+
+        Args:
+            prompt: 用户输入的提示词
+
+        Yields:
+            StreamEvent: 流式事件
+
+        使用示例：
+            >>> async for event in engine.submit_message("你好"):
+            ...     print(event)
+        """
+        # 初始化文件历史状态（如尚未初始化）
+        if self._file_history is None:
+            self._file_history = FileHistoryState(
+                session_id=self._session_id or __import__('uuid').uuid4().hex[:12],
+                cwd=str(self._cwd),
+            )
+
+        # 将用户文本转换为消息并添加到历史记录
+        self._messages.append(ConversationMessage.from_user_text(prompt))
+
+        # 为这条用户消息创建文件历史快照（用消息列表长度作为 ID）
+        make_snapshot(self._file_history, str(len(self._messages)))
+
+        # 文件历史回调：工具执行前备份文件
+        def _on_before_tool_execute(tool_name: str, tool_input: dict) -> None:
+            if self._file_history is None:
+                return
+            # 跳过只读工具（如 grep、glob），它们不会修改文件
+            tool = self._tool_registry.get(tool_name)
+            if tool is not None:
+                try:
+                    parsed_input = tool.input_model.model_validate(tool_input)
+                    if tool.is_read_only(parsed_input):
+                        return
+                except Exception:
+                    pass
+            for fpath in self._extract_file_paths(tool_name, tool_input):
+                track_edit(self._file_history, fpath)
+
+        context = QueryContext(
+            api_client=self._api_client,
+            tool_registry=self._tool_registry,
+            permission_checker=self._permission_checker,
+            cwd=self._cwd,
+            model=self._model,
+            system_prompt=self._system_prompt,
+            max_tokens=self._max_tokens,
+            max_turns=self._max_turns,
+            permission_prompt=self._permission_prompt,
+            ask_user_prompt=self._ask_user_prompt,
+            hook_executor=self._hook_executor,
+            tool_metadata=self._tool_metadata,
+            effort=self._effort,
+            bg_agent_tracker=self._bg_agent_tracker,
+            compact_state=self._compact_state,
+            on_before_tool_execute=_on_before_tool_execute,
+        )
+        async for event, usage in run_query(context, self._messages):
+            if usage is not None:
+                self._cost_tracker.add(usage)  # 累加使用量
+            yield event
+        # 同步工具导致的 CWD 变更（如 enter/exit_worktree）
+        if context.cwd != self._cwd:
+            self._cwd = context.cwd
+
+    async def continue_pending(self, *, max_turns: int | None = None) -> AsyncIterator[StreamEvent]:
+        """继续被中断的工具循环，而不追加新的用户消息。
+
+        用于恢复之前因工具执行而中断的对话。
+
+        Args:
+            max_turns: 最大轮次数（可选，默认使用引擎设置）
+
+        Yields:
+            StreamEvent: 流式事件
+        """
+        context = QueryContext(
+            api_client=self._api_client,
+            tool_registry=self._tool_registry,
+            permission_checker=self._permission_checker,
+            cwd=self._cwd,
+            model=self._model,
+            system_prompt=self._system_prompt,
+            max_tokens=self._max_tokens,
+            max_turns=max_turns if max_turns is not None else self._max_turns,
+            permission_prompt=self._permission_prompt,
+            ask_user_prompt=self._ask_user_prompt,
+            hook_executor=self._hook_executor,
+            tool_metadata=self._tool_metadata,
+            effort=self._effort,
+            bg_agent_tracker=self._bg_agent_tracker,
+            compact_state=self._compact_state,
+        )
+        async for event, usage in run_query(context, self._messages):
+            if usage is not None:
+                self._cost_tracker.add(usage)  # 累加使用量
+            yield event
+        # 同步工具导致的 CWD 变更（如 enter/exit_worktree）
+        if context.cwd != self._cwd:
+            self._cwd = context.cwd

illusion/engine/stream_events.py

@@ -0,0 +1,169 @@
+"""查询引擎产生的事件。
+
+本模块定义查询引擎在执行过程中产生的各种事件类型。
+
+主要事件类：
+    - AssistantTextDelta: 助手文本增量
+    - AssistantTurnComplete: 助手轮次完成
+    - ToolExecutionStarted: 工具执行开始
+    - ToolExecutionCompleted: 工具执行完成
+    - ToolChainStarted: 工具链开始
+    - ToolChainCompleted: 工具链完成
+    - ErrorEvent: 错误事件
+    - StatusEvent: 状态事件
+
+使用示例：
+    >>> from illusion.engine.stream_events import StreamEvent, AssistantTextDelta
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from illusion.api.usage import UsageSnapshot
+from illusion.engine.messages import ConversationMessage
+
+
+class SessionPhase(Enum):
+    """智能体会话阶段。
+
+    Attributes:
+        IDLE: 空闲状态
+        THINKING: 思考中
+        TOOL_EXECUTING: 工具执行中
+    """
+
+    IDLE = "idle"
+    THINKING = "thinking"
+    TOOL_EXECUTING = "tool_executing"
+
+
+@dataclass(frozen=True)
+class AssistantTextDelta:
+    """增量助手文本。
+
+    在流式响应过程中逐步产生的文本片段。
+
+    Attributes:
+        text: 新增的文本内容
+        reasoning: 新增的思考内容（可选）
+    """
+
+    text: str
+    reasoning: str | None = None
+
+
+@dataclass(frozen=True)
+class AssistantTurnComplete:
+    """助手轮次完成。
+
+    当助手完成一个完整的响应轮次时产生，包含最终消息和使用量统计。
+
+    Attributes:
+        message: 助手生成的消息
+        usage: 本轮使用的令牌统计
+    """
+
+    message: ConversationMessage
+    usage: UsageSnapshot
+
+
+@dataclass(frozen=True)
+class ToolExecutionStarted:
+    """引擎即将执行工具。
+
+    在工具执行开始时产生，包含工具名称和输入参数。
+
+    Attributes:
+        tool_name: 工具名称
+        tool_input: 工具输入参数字典
+        tool_use_id: 工具调用ID（可选，用于去重提前通知的工具调用）
+    """
+
+    tool_name: str
+    tool_input: dict[str, Any]
+    tool_use_id: str = ""
+
+
+@dataclass(frozen=True)
+class ToolExecutionCompleted:
+    """工具执行完成。
+
+    工具执行完成后产生，包含工具名称、输出结果和是否出错。
+
+    Attributes:
+        tool_name: 工具名称
+        output: 工具执行输出
+        is_error: 是否为错误结果
+        tool_use_id: 工具调用ID（可选，用于匹配并发工具调用的结果）
+    """
+
+    tool_name: str
+    output: str
+    is_error: bool = False
+    tool_use_id: str = ""
+
+
+@dataclass(frozen=True)
+class ErrorEvent:
+    """应向用户显示的错误。
+
+    包含错误信息和是否可恢复。
+
+    Attributes:
+        message: 错误消息
+        recoverable: 是否可恢复（默认True）
+    """
+
+    message: str
+    recoverable: bool = True
+
+
+@dataclass(frozen=True)
+class StatusEvent:
+    """向用户显示的瞬态系统状态消息。
+
+    Attributes:
+        message: 状态消息内容
+        bg_agent: 是否为后台代理相关状态（用于前端 shimmer 区域显示）
+    """
+
+    message: str
+    bg_agent: bool = False
+
+
+@dataclass(frozen=True)
+class ToolChainStarted:
+    """一批工具执行即将开始。
+
+    Attributes:
+        tool_count: 即将执行的工具数量
+    """
+
+    tool_count: int
+
+
+@dataclass(frozen=True)
+class ToolChainCompleted:
+    """批处理中的所有工具已完成执行。
+
+    Attributes:
+        results_summary: 工具执行结果摘要列表
+    """
+
+    results_summary: list[dict[str, Any]]
+
+
+# 事件联合类型：所有可能的流事件类型
+StreamEvent = (
+    AssistantTextDelta
+    | AssistantTurnComplete
+    | ToolExecutionStarted
+    | ToolExecutionCompleted
+    | ErrorEvent
+    | StatusEvent
+    | ToolChainStarted
+    | ToolChainCompleted
+)

illusion/hooks/__init__.py

@@ -0,0 +1,67 @@
+"""
+钩子模块
+========
+
+本模块提供 IllusionCode 钩子系统功能。
+
+主要组件：
+    - HookEvent: 钩子事件
+    - HookExecutionContext: 钩子执行上下文
+    - HookExecutor: 钩子执行器
+    - HookRegistry: 钩子注册表
+    - HookResult: 钩子结果
+    - AggregatedHookResult: 聚合钩子结果
+    - load_hook_registry: 加载钩子注册表
+
+使用示例：
+    >>> from illusion.hooks import HookRegistry, HookExecutor
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from illusion.hooks.events import HookEvent
+    from illusion.hooks.executor import HookExecutionContext, HookExecutor
+    from illusion.hooks.loader import HookRegistry
+    from illusion.hooks.types import AggregatedHookResult, HookResult
+
+__all__ = [
+    "AggregatedHookResult",
+    "HookEvent",
+    "HookExecutionContext",
+    "HookExecutor",
+    "HookRegistry",
+    "HookResult",
+    "load_hook_registry",
+]
+
+
+def __getattr__(name: str):
+    if name == "HookEvent":
+        from illusion.hooks.events import HookEvent
+
+        return HookEvent
+    if name in {"HookExecutionContext", "HookExecutor"}:
+        from illusion.hooks.executor import HookExecutionContext, HookExecutor
+
+        return {
+            "HookExecutionContext": HookExecutionContext,
+            "HookExecutor": HookExecutor,
+        }[name]
+    if name in {"HookRegistry", "load_hook_registry"}:
+        from illusion.hooks.loader import HookRegistry, load_hook_registry
+
+        return {
+            "HookRegistry": HookRegistry,
+            "load_hook_registry": load_hook_registry,
+        }[name]
+    if name in {"AggregatedHookResult", "HookResult"}:
+        from illusion.hooks.types import AggregatedHookResult, HookResult
+
+        return {
+            "AggregatedHookResult": AggregatedHookResult,
+            "HookResult": HookResult,
+        }[name]
+    raise AttributeError(name)

illusion/hooks/events.py

@@ -0,0 +1,43 @@
+"""
+钩子事件定义模块
+================
+
+本模块定义 IllusionCode 支持的钩子事件类型。
+
+支持的事件：
+    - SESSION_START: 会话开始时触发
+    - SESSION_END: 会话结束时触发
+    - PRE_TOOL_USE: 工具使用前触发
+    - POST_TOOL_USE: 工具使用后触发
+
+使用示例：
+    >>> from illusion.hooks.events import HookEvent
+    >>> event = HookEvent.PRE_TOOL_USE
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class HookEvent(str, Enum):
+    """
+    钩子事件枚举
+    
+    定义可以触发钩子的所有事件类型。
+    
+    枚举值：
+        SESSION_START: 会话开始事件
+        SESSION_END: 会话结束事件
+        PRE_TOOL_USE: 工具使用前事件
+        POST_TOOL_USE: 工具使用后事件
+    
+    使用示例：
+        >>> event = HookEvent.PRE_TOOL_USE
+        >>> print(event.value)  # 输出: "pre_tool_use"
+    """
+
+    SESSION_START = "session_start"  # 会话开始
+    SESSION_END = "session_end"  # 会话结束
+    PRE_TOOL_USE = "pre_tool_use"  # 工具使用前
+    POST_TOOL_USE = "post_tool_use"  # 工具使用后