illusion-code 0.1.0__py3-none-any.whl

illusion/ui/protocol.py

@@ -0,0 +1,384 @@
+"""
+Protocol 协议模块
+==============
+
+本模块定义 React 终端前后端通信的结构化协议模型。
+
+主要功能：
+    - 前端请求模型（FrontendRequest）
+    - 后端事件模型（BackendEvent）
+    - 转录项模型（TranscriptItem）
+    - 任务快照模型（TaskSnapshot）
+
+类说明：
+    - FrontendRequest: 前端请求模型
+    - BackendEvent: 后端事件模型
+    - TranscriptItem: 转录项模型
+    - TaskSnapshot: 任务快照模型
+
+使用示例：
+    >>> from illusion.ui.protocol import FrontendRequest, BackendEvent, TranscriptItem
+    >>> 
+    >>> # 创建前端请求
+    >>> request = FrontendRequest(type="submit_line", line="帮我写一个程序")
+    >>> 
+    >>> # 创建后端事件
+    >>> event = BackendEvent.ready(state, tasks, commands)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from illusion.state.app_state import AppState
+from illusion.bridge.manager import BridgeSessionRecord
+from illusion.mcp.types import McpConnectionStatus
+from illusion.tasks.types import TaskRecord, to_task_display_status
+
+
+class FrontendRequest(BaseModel):
+    """前端请求模型。
+
+    表示从 React 前端发送到 Python 后端的请求。
+
+    Attributes:
+        type: 请求类型
+        line: 提交的行内容
+        command: 命令名称
+        command: 命令值
+        request_id: 请求 ID
+        allowed: 是否允许
+        always_allow: 是否总是允许
+        tool_name: 工具名称
+        answer: 用户答案
+    """
+
+    type: Literal[
+        "submit_line",
+        "stop",
+        "permission_response",
+        "question_response",
+        "list_sessions",
+        "select_command",
+        "apply_select_command",
+        "shutdown",
+    ]
+    line: str | None = None
+    command: str | None = None
+    value: str | None = None
+    request_id: str | None = None
+    allowed: bool | None = None
+    always_allow: bool | None = None
+    tool_name: str | None = None
+    answer: str | None = None
+
+
+class TranscriptItem(BaseModel):
+    """转录项模型。
+
+    表示前端呈现的一行转录内容。
+
+    Attributes:
+        role: 角色（system/user/assistant/tool/tool_result/log）
+        text: 文本内容
+        tool_name: 工具名称
+        tool_input: 工具输入参数
+        is_error: 是否为错误
+        reasoning: 思考文本（可选）
+    """
+
+    role: Literal["system", "user", "assistant", "tool", "tool_result", "log"]
+    text: str
+    tool_name: str | None = None
+    tool_input: dict[str, Any] | None = None
+    is_error: bool | None = None
+    reasoning: str | None = None
+    tool_use_id: str | None = None
+
+
+class TaskSnapshot(BaseModel):
+    """任务快照模型。
+
+    UI安全的任务表示形式。
+
+    Attributes:
+        id: 任务 ID
+        type: 任务类型
+        status: 任务状态
+        description: 任务描述
+        metadata: 元数据字典
+    """
+
+    id: str
+    type: str
+    status: str
+    description: str
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+    @classmethod
+    def from_record(cls, record: TaskRecord) -> "TaskSnapshot":
+        """从任务记录创建任务快照。
+
+        Args:
+            record: 任务记录
+
+        Returns:
+            TaskSnapshot: 任务快照
+        """
+        return cls(
+            id=record.id,
+            type=record.type,
+            status=to_task_display_status(record.status),
+            description=record.description,
+            metadata=dict(record.metadata),
+        )
+
+
+class BackendEvent(BaseModel):
+    """后端事件模型。
+
+    表示从 Python 后端发送到 React 前端的事件。
+
+    Attributes:
+        type: 事件类型
+        select_options: 选择选项列表
+        message: 消息文本
+        item: 转录项
+        state: 状态字典
+        tasks: 任务快照列表
+        mcp_servers: MCP 服务器状态列表
+        bridge_sessions: 桥接会话列表
+        commands: 命令列表
+        modal: 模态对话框配置
+        tool_name: 工具名称
+        tool_input: 工具输入参数
+        tool_output: 工具输出
+        is_error: 是否为错误
+        phase: 当前会话阶段
+        tool_count: 工具链中的工具数量
+        todo_items: 待办事项列表
+        todo_markdown: 待办事项 Markdown
+        plan_mode: 计划模式
+        swarm_teammates: Swarm 队友列表
+        swarm_notifications: Swarm 通知列表
+        reasoning: 思考增量或最终思考文本
+        command_result_data: 指令结果数据
+    """
+
+    type: Literal[
+        "ready",
+        "state_snapshot",
+        "tasks_snapshot",
+        "transcript_item",
+        "assistant_delta",
+        "assistant_complete",
+        "line_complete",
+        "tool_started",
+        "tool_input_updated",
+        "tool_completed",
+        "tool_chain_started",
+        "tool_chain_completed",
+        "clear_transcript",
+        "replace_transcript",
+        "modal_request",
+        "select_request",
+        "todo_update",
+        "plan_mode_change",
+        "swarm_status",
+        "command_result",
+        "bg_agent_status",
+        "error",
+        "shutdown",
+    ]
+    select_options: list[dict[str, Any]] | None = None
+    message: str | None = None
+    item: TranscriptItem | None = None
+    state: dict[str, Any] | None = None
+    tasks: list[TaskSnapshot] | None = None
+    mcp_servers: list[dict[str, Any]] | None = None
+    bridge_sessions: list[dict[str, Any]] | None = None
+    commands: list[str] | None = None
+    modal: dict[str, Any] | None = None
+    tool_name: str | None = None
+    tool_input: dict[str, Any] | None = None
+    tool_use_id: str | None = None
+    output: str | None = None
+    is_error: bool | None = None
+    phase: str | None = None          # 当前会话阶段
+    tool_count: int | None = None     # 工具链中的工具数量
+    # 新增字段用于增强事件
+    todo_items: list[dict[str, Any]] | None = None
+    todo_markdown: str | None = None
+    plan_mode: str | None = None
+    swarm_teammates: list[dict[str, Any]] | None = None
+    swarm_notifications: list[dict[str, Any]] | None = None
+    reasoning: str | None = None
+    command_result_data: dict[str, Any] | None = None
+    items: list[TranscriptItem] | None = None
+
+    @classmethod
+    def ready(
+        cls,
+        state: AppState,
+        tasks: list[TaskRecord],
+        commands: list[str],
+    ) -> "BackendEvent":
+        """创建就绪事件。
+
+        Args:
+            state: 应用状态
+            tasks: 任务记录列表
+            commands: 命令列表
+
+        Returns:
+            BackendEvent: 就绪事件
+        """
+        return cls(
+            type="ready",
+            state=_state_payload(state),
+            tasks=[TaskSnapshot.from_record(task) for task in tasks],
+            mcp_servers=[],
+            bridge_sessions=[],
+            commands=commands,
+        )
+
+    @classmethod
+    def state_snapshot(cls, state: AppState) -> "BackendEvent":
+        """创建状态快照事件。
+
+        Args:
+            state: 应用状态
+
+        Returns:
+            BackendEvent: 状态快照事件
+        """
+        return cls(type="state_snapshot", state=_state_payload(state))
+
+    @classmethod
+    def tasks_snapshot(cls, tasks: list[TaskRecord]) -> "BackendEvent":
+        """创建任务快照事件。
+
+        Args:
+            tasks: 任务记录列表
+
+        Returns:
+            BackendEvent: 任务快照事件
+        """
+        return cls(
+            type="tasks_snapshot",
+            tasks=[TaskSnapshot.from_record(task) for task in tasks],
+        )
+
+    @classmethod
+    def status_snapshot(
+        cls,
+        *,
+        state: AppState,
+        mcp_servers: list[McpConnectionStatus],
+        bridge_sessions: list[BridgeSessionRecord],
+    ) -> "BackendEvent":
+        """创建状态快照事件（包含 MCP 和桥接信息）。
+
+        Args:
+            state: 应用状态
+            mcp_servers: MCP 服务器状态列表
+            bridge_sessions: 桥接会话列表
+
+        Returns:
+            BackendEvent: 状态快照事件
+        """
+        return cls(
+            type="state_snapshot",
+            state=_state_payload(state),
+            mcp_servers=[
+                {
+                    "name": server.name,
+                    "state": server.state,
+                    "detail": server.detail,
+                    "transport": server.transport,
+                    "auth_configured": server.auth_configured,
+                    "tool_count": len(server.tools),
+                    "resource_count": len(server.resources),
+                }
+                for server in mcp_servers
+            ],
+            bridge_sessions=[
+                {
+                    "session_id": session.session_id,
+                    "command": session.command,
+                    "cwd": session.cwd,
+                    "pid": session.pid,
+                    "status": session.status,
+                    "started_at": session.started_at,
+                    "output_path": session.output_path,
+                }
+                for session in bridge_sessions
+            ],
+        )
+
+
+def _state_payload(state: AppState) -> dict[str, Any]:
+    """将应用状态转换为载荷字典。
+
+    Args:
+        state: 应用状态
+
+    Returns:
+        dict[str, Any]: 状态载荷
+    """
+    from illusion.swarm.agent_executor import list_active_agents
+    return {
+        "model": state.model,
+        "cwd": state.cwd,
+        "provider": state.provider,
+        "auth_status": state.auth_status,
+        "base_url": state.base_url,
+        "permission_mode": _format_permission_mode(state.permission_mode),
+        "ui_language": state.ui_language,
+        "fast_mode": state.fast_mode,
+        "effort": state.effort,
+        "passes": state.passes,
+        "mcp_connected": state.mcp_connected,
+        "mcp_failed": state.mcp_failed,
+        "bridge_sessions": state.bridge_sessions,
+        "output_style": state.output_style,
+        "show_thinking": state.show_thinking,
+        "phase": state.phase,
+        "session_id": state.session_id,
+        "context_window": state.context_window,
+        "context_tokens": state.context_tokens,
+        "agent_count": len(list_active_agents()),
+    }
+
+
+# 权限模式标签映射
+_MODE_LABELS = {
+    "default": "Default",
+    "plan": "Plan Mode",
+    "full_auto": "Auto",
+    "PermissionMode.DEFAULT": "Default",
+    "PermissionMode.PLAN": "Plan Mode",
+    "PermissionMode.FULL_AUTO": "Auto",
+}
+
+
+def _format_permission_mode(raw: str) -> str:
+    """将原始权限模式转换为人类可读的标签。
+
+    Args:
+        raw: 原始权限模式字符串
+
+    Returns:
+        str: 格式化的权限模式标签
+    """
+    return _MODE_LABELS.get(raw, raw)
+
+
+__all__ = [
+    "BackendEvent",
+    "FrontendRequest",
+    "TaskSnapshot",
+    "TranscriptItem",
+]

illusion/ui/react_launcher.py

@@ -0,0 +1,280 @@
+"""
+React Launcher React 启动器模块
+=========================
+
+本模块实现默认的 React 终端前端启动器。
+
+主要功能：
+    - 解析前端目录路径
+    - 构建后端启动命令
+    - 启动 React 终端 UI
+
+函数说明：
+    - get_frontend_dir: 获取前端目录路径
+    - build_backend_command: 构建后端启动命令
+    - launch_react_tui: 启动 React 终端 UI
+
+使用示例：
+    >>> from illusion.ui.react_launcher import launch_react_tui, get_frontend_dir
+    >>> 
+    >>> # 启动 React TUI
+    >>> exit_code = await launch_react_tui(prompt="帮我写一个程序")
+    >>> 
+    >>> # 获取前端目录
+    >>> frontend_dir = get_frontend_dir()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _resolve_npm() -> str:
+    """解析 npm 可执行文件路径（在 Windows 上为 npm.cmd）。
+
+    Returns:
+        str: npm 可执行文件路径
+    """
+    npm = shutil.which("npm") or "npm"
+    if sys.platform == "win32" and not npm.endswith((".cmd", ".bat", ".exe")):
+        for ext in (".cmd", ".bat", ".exe"):
+            candidate = npm + ext
+            if Path(candidate).exists():
+                return candidate
+    return npm
+
+
+def _resolve_node() -> str:
+    """解析 node 可执行文件路径。
+
+    Windows 上优先使用 npm 同目录的 node.exe，避免 Python nodejs-wheel
+    包装器干扰。
+
+    Returns:
+        str: node 可执行文件路径
+    """
+    npm = shutil.which("npm")
+    if npm is not None:
+        sibling = Path(npm).parent / "node.exe"
+        if sibling.exists() and sys.platform == "win32":
+            return str(sibling)
+    return shutil.which("node") or "node"
+
+
+def _resolve_tsx_bin(frontend_dir: Path) -> list[str] | None:
+    """直接解析 tsx 可执行文件路径，跳过 npm exec 开销。
+
+    Args:
+        frontend_dir: 前端目录路径
+
+    Returns:
+        list[str] | None: tsx 启动命令列表，未找到时返回 None
+    """
+    node = _resolve_node()
+    # Windows: node_modules/.bin/tsx.cmd
+    if sys.platform == "win32":
+        tsx_cmd = frontend_dir / "node_modules" / ".bin" / "tsx.cmd"
+        if tsx_cmd.exists():
+            return [str(tsx_cmd)]
+    # Unix: node_modules/.bin/tsx
+    tsx_bin = frontend_dir / "node_modules" / ".bin" / "tsx"
+    if tsx_bin.exists():
+        return [node, str(tsx_bin)]
+    # 直接调用 tsx 的 CLI 入口
+    tsx_mjs = frontend_dir / "node_modules" / "tsx" / "dist" / "cli.mjs"
+    if tsx_mjs.exists():
+        return [node, str(tsx_mjs)]
+    return None
+
+
+def get_frontend_dir() -> Path:
+    """返回 React 终端前端目录。
+
+    按以下顺序检查：
+    1. 已安装包内的打包文件（pip install）
+    2. 开发仓库布局（source checkout）
+
+    Returns:
+        Path: 前端目录路径
+    """
+    # 1. 已安装包内的打包文件：illusion/_frontend/
+    pkg_frontend = Path(__file__).resolve().parent.parent / "_frontend"
+    if (pkg_frontend / "package.json").exists():
+        return pkg_frontend
+
+    # 2. 开发仓库：<repo>/frontend/terminal/
+    repo_root = Path(__file__).resolve().parents[3]
+    dev_frontend = repo_root / "frontend" / "terminal"
+    if (dev_frontend / "package.json").exists():
+        return dev_frontend
+
+    # 回退到包路径（将显示清晰的错误消息）
+    return pkg_frontend
+
+
+def build_backend_command(
+    *,
+    cwd: str | None = None,
+    model: str | None = None,
+    max_turns: int | None = None,
+    base_url: str | None = None,
+    system_prompt: str | None = None,
+    api_key: str | None = None,
+    api_format: str | None = None,
+    effort: str | None = None,
+) -> list[str]:
+    """返回 React 前端用于生成后端主机的命令。
+
+    Args:
+        cwd: 工作目录
+        model: 模型名称
+        max_turns: 最大对话轮次
+        base_url: API 基础 URL
+        system_prompt: 系统提示词
+        api_key: API 密钥
+        api_format: API 格式
+        effort: 推理强度级别
+
+    Returns:
+        list[str]: 后端启动命令列表
+    """
+    command = [sys.executable, "-m", "illusion", "--backend-only"]
+    if cwd:
+        command.extend(["--cwd", cwd])
+    if model:
+        command.extend(["--model", model])
+    if max_turns is not None:
+        command.extend(["--max-turns", str(max_turns)])
+    if base_url:
+        command.extend(["--base-url", base_url])
+    if system_prompt:
+        command.extend(["--system-prompt", system_prompt])
+    if api_key:
+        command.extend(["--api-key", api_key])
+    if api_format:
+        command.extend(["--api-format", api_format])
+    if effort:
+        command.extend(["--effort", effort])
+    return command
+
+
+async def launch_react_tui(
+    *,
+    prompt: str | None = None,
+    cwd: str | None = None,
+    model: str | None = None,
+    max_turns: int | None = None,
+    base_url: str | None = None,
+    system_prompt: str | None = None,
+    api_key: str | None = None,
+    api_format: str | None = None,
+    effort: str | None = None,
+) -> int:
+    """启动 React 终端前端作为默认 UI。
+
+    Args:
+        prompt: 初始提示词
+        cwd: 工作目录
+        model: 模型名称
+        max_turns: 最大对话轮次
+        base_url: API 基础 URL
+        system_prompt: 系统提示词
+        api_key: API 密钥
+        api_format: API 格式
+        effort: 推理强度级别
+
+    Returns:
+        int: 退出代码
+    """
+    frontend_dir = get_frontend_dir()
+    package_json = frontend_dir / "package.json"
+    if not package_json.exists():
+        raise RuntimeError(f"React terminal frontend is missing: {package_json}")
+
+    # 解析 npm 路径
+    npm = _resolve_npm()
+
+    # 检查并安装依赖
+    if not (frontend_dir / "node_modules").exists():
+        install_kwargs: dict = {}
+        if sys.platform == "win32":
+            install_kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+        install = await asyncio.create_subprocess_exec(
+            npm,
+            "install",
+            "--no-fund",
+            "--no-audit",
+            cwd=str(frontend_dir),
+            **install_kwargs,
+        )
+        if await install.wait() != 0:
+            raise RuntimeError("Failed to install React terminal frontend dependencies")
+
+    # 设置环境变量
+    env = os.environ.copy()
+    env["ILLUSION_FRONTEND_CONFIG"] = json.dumps(
+        {
+            "backend_command": build_backend_command(
+                cwd=cwd or str(Path.cwd()),
+                model=model,
+                max_turns=max_turns,
+                base_url=base_url,
+                system_prompt=system_prompt,
+                api_key=api_key,
+                api_format=api_format,
+                effort=effort,
+            ),
+            "initial_prompt": prompt,
+        }
+    )
+    node = _resolve_node()
+    dist_entry = frontend_dir / "dist" / "index.mjs"
+
+    if dist_entry.exists():
+        # 优先使用 esbuild 预编译产物（最快启动路径）
+        process = await asyncio.create_subprocess_exec(
+            node,
+            str(dist_entry),
+            cwd=str(frontend_dir),
+            env=env,
+            stdin=None,
+            stdout=None,
+            stderr=None,
+        )
+    else:
+        # 回退到 tsx 实时编译（开发模式）
+        tsx_cmd = _resolve_tsx_bin(frontend_dir)
+        if tsx_cmd is not None:
+            process = await asyncio.create_subprocess_exec(
+                *tsx_cmd,
+                "src/index.tsx",
+                cwd=str(frontend_dir),
+                env=env,
+                stdin=None,
+                stdout=None,
+                stderr=None,
+            )
+        else:
+            # 最终回退：通过 npm exec 调用 tsx
+            process = await asyncio.create_subprocess_exec(
+                npm,
+                "exec",
+                "--",
+                "tsx",
+                "src/index.tsx",
+                cwd=str(frontend_dir),
+                env=env,
+                stdin=None,
+                stdout=None,
+                stderr=None,
+            )
+    return await process.wait()
+
+
+__all__ = ["build_backend_command", "get_frontend_dir", "launch_react_tui"]