cloneloop 0.1.0__py3-none-any.whl

mcp_ai_supervisor/server.py

@@ -0,0 +1,654 @@
+#!/usr/bin/env python3
+"""
+MCP AI Supervisor 伺服器主要模組
+
+此模組提供 MCP (Model Context Protocol) 的增強回饋收集功能，
+支援智能環境檢測，自動使用 Web UI 介面。
+
+主要功能：
+- MCP 工具實現
+- 介面選擇（Web UI）
+- 環境檢測 (SSH Remote, WSL, Local)
+- 國際化支援
+- 圖片處理與上傳
+- 命令執行與結果展示
+- 專案目錄管理
+
+主要 MCP 工具：
+- interactive_feedback: 收集用戶互動回饋
+- get_system_info: 獲取系統環境資訊
+
+日誌約定：
+- `logger.info` / `warning`：核心鏈路與 Agent 流式（`AgentBridge`）輸出；進程啟動時由
+  `_configure_supervisor_logging()` 將 ``mcp_ai_supervisor`` 包掛到 stderr，無需 MCP_DEBUG
+  即可在 Cursor MCP 日誌中查看。級別可由 ``MCP_SUPERVISOR_LOG_LEVEL`` 覆寫。
+- `debug_log`：詳情輸出，僅在環境變數 MCP_DEBUG 開啟時寫入 stderr。
+
+作者: Fábio Ferreira (原作者)
+增強: Minidoracat (Web UI, 圖片支援, 環境檢測)
+重構: 模塊化設計
+"""
+
+import base64
+import io
+import json
+import logging
+import os
+import sys
+import time
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from uuid import uuid4
+from pathlib import Path
+from typing import Annotated, Any, Optional
+
+from .log_writer import get_logger as _get_struct_logger
+
+# _mcp_logger 延迟初始化：必须在 project_directory 可用之后才能创建
+_mcp_logger = None
+
+# 弹窗 request_id 管理：key=project_dir, value=(request_id, summary)
+# summary 相同时复用 request_id，防止重试关闭弹窗
+_project_request_ids: dict[str, tuple[str, str]] = {}
+
+# 缓存 MCP roots（Cursor 工作区路径），首次查询后不再重复请求
+_cached_roots: list[str] | None = None
+
+# 兼容：旧代码部分仍使用标准 logging（第三方库和 _configure_supervisor_logging）
+logger = logging.getLogger(__name__)
+
+from fastmcp import Context, FastMCP
+from mcp.types import ImageContent, TextContent
+from pydantic import Field
+
+# 導入統一的調試功能
+from .debug import server_debug_log as debug_log
+
+# 導入多語系支援
+# 導入錯誤處理框架
+from .utils.error_handler import ErrorHandler, ErrorType
+
+# 導入資源管理器
+from .utils.resource_manager import create_temp_file
+
+# 導入提取到 helpers/ 的函數（解決循環 import）
+from .helpers.image_helpers import process_images
+from .helpers.feedback_helpers import create_feedback_text, save_feedback_to_file
+
+
+# ===== 編碼初始化 =====
+def init_encoding():
+    """初始化編碼設置，確保正確處理中文字符"""
+    try:
+        # Windows 特殊處理
+        if sys.platform == "win32":
+            import msvcrt
+
+            # 設置為二進制模式
+            msvcrt.setmode(sys.stdin.fileno(), os.O_BINARY)
+            msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)
+
+            # 重新包裝為 UTF-8 文本流，並禁用緩衝
+            # 修復 union-attr 錯誤 - 安全獲取 buffer 或 detach
+            stdin_buffer = getattr(sys.stdin, "buffer", None)
+            if stdin_buffer is None and hasattr(sys.stdin, "detach"):
+                stdin_buffer = sys.stdin.detach()
+
+            stdout_buffer = getattr(sys.stdout, "buffer", None)
+            if stdout_buffer is None and hasattr(sys.stdout, "detach"):
+                stdout_buffer = sys.stdout.detach()
+
+            sys.stdin = io.TextIOWrapper(
+                stdin_buffer, encoding="utf-8", errors="replace", newline=None
+            )
+            sys.stdout = io.TextIOWrapper(
+                stdout_buffer,
+                encoding="utf-8",
+                errors="replace",
+                newline="",
+                write_through=True,  # 關鍵：禁用寫入緩衝
+            )
+        else:
+            # 非 Windows 系統的標準設置
+            if hasattr(sys.stdout, "reconfigure"):
+                sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            if hasattr(sys.stdin, "reconfigure"):
+                sys.stdin.reconfigure(encoding="utf-8", errors="replace")
+
+        # 設置 stderr 編碼（用於調試訊息）
+        if hasattr(sys.stderr, "reconfigure"):
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+        return True
+    except Exception:
+        # 如果編碼設置失敗，嘗試基本設置
+        try:
+            if hasattr(sys.stdout, "reconfigure"):
+                sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            if hasattr(sys.stdin, "reconfigure"):
+                sys.stdin.reconfigure(encoding="utf-8", errors="replace")
+            if hasattr(sys.stderr, "reconfigure"):
+                sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+        except:
+            pass
+        return False
+
+
+# 初始化編碼（在導入時就執行）
+_encoding_initialized = init_encoding()
+
+# ===== 常數定義 =====
+SERVER_NAME = "AI 監工 MCP"
+
+
+# 初始化 MCP 服務器
+from . import __version__
+
+
+# 確保 log_level 設定為正確的大寫格式
+fastmcp_settings = {}
+
+# 檢查環境變數並設定正確的 log_level
+env_log_level = os.getenv("FASTMCP_LOG_LEVEL", "").upper()
+if env_log_level in ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"):
+    fastmcp_settings["log_level"] = env_log_level
+else:
+    # 預設使用 INFO 等級
+    fastmcp_settings["log_level"] = "INFO"
+
+@asynccontextmanager
+async def _mcp_lifespan(server: Any) -> AsyncIterator[dict]:
+    """MCP 生命周期：服务就绪时通知 Workbench，关闭时注销。"""
+    _notify_workbench_lifecycle("online")
+    try:
+        yield {}
+    finally:
+        _notify_workbench_lifecycle("offline")
+
+
+def _notify_workbench_lifecycle(event: str) -> None:
+    """通知 Workbench MCP 进程状态变化（best-effort）"""
+    try:
+        from .web.main import get_web_ui_manager
+        manager = get_web_ui_manager()
+        client = manager._workbench_client
+        if client:
+            if event == "online":
+                client.notify_process_online()
+            else:
+                client.notify_process_offline()
+    except Exception:
+        pass
+
+
+mcp: Any = FastMCP(SERVER_NAME, lifespan=_mcp_lifespan)
+
+
+# ===== 工具函數 =====
+def is_wsl_environment() -> bool:
+    """
+    檢測是否在 WSL (Windows Subsystem for Linux) 環境中運行
+
+    Returns:
+        bool: True 表示 WSL 環境，False 表示其他環境
+    """
+    try:
+        # 檢查 /proc/version 文件是否包含 WSL 標識
+        if os.path.exists("/proc/version"):
+            with open("/proc/version") as f:
+                version_info = f.read().lower()
+                if "microsoft" in version_info or "wsl" in version_info:
+                    debug_log("检测到 WSL 环境（通过 /proc/version）")
+                    return True
+
+        # 檢查 WSL 相關環境變數
+        wsl_env_vars = ["WSL_DISTRO_NAME", "WSL_INTEROP", "WSLENV"]
+        for env_var in wsl_env_vars:
+            if os.getenv(env_var):
+                debug_log(f"检测到 WSL 环境变量: {env_var}")
+                return True
+
+        # 檢查是否存在 WSL 特有的路徑
+        wsl_paths = ["/mnt/c", "/mnt/d", "/proc/sys/fs/binfmt_misc/WSLInterop"]
+        for path in wsl_paths:
+            if os.path.exists(path):
+                debug_log(f"检测到 WSL 特有路径: {path}")
+                return True
+
+    except Exception as e:
+        debug_log(f"WSL 检测过程中发生错误: {e}")
+
+    return False
+
+
+async def _resolve_roots_from_cursor(ctx: Context) -> list[str]:
+    """从 Cursor 获取 MCP roots（工作区路径列表）。
+
+    Cursor 可能返回裸路径（/Users/...）而非标准 file:// URI，
+    导致 MCP SDK 的 Pydantic 验证失败。这里做了兼容处理。
+    """
+    # 优先尝试标准 API
+    try:
+        roots = await ctx.list_roots()
+        paths = [
+            r.uri[7:] if r.uri.startswith("file://") else r.uri
+            for r in roots
+            if r.uri.startswith("file://") or r.uri.startswith("/")
+        ]
+        if paths:
+            logger.info("[MCP Roots] resolved %d paths via list_roots()", len(paths))
+            return paths
+    except Exception:
+        pass
+
+    # 回退：Cursor 返回裸路径时 Pydantic 验证失败，手动构造 JSONRPC 请求
+    try:
+        from mcp.types import ListRootsRequest, ServerRequest
+        from pydantic import BaseModel
+
+        class _LooseRoot(BaseModel, extra="allow"):
+            uri: str = ""
+            name: str | None = None
+
+        class _LooseListRootsResult(BaseModel, extra="allow"):
+            roots: list[_LooseRoot] = []
+
+        result = await ctx.session.send_request(
+            ServerRequest(ListRootsRequest()),
+            _LooseListRootsResult,
+        )
+        paths = []
+        for r in result.roots:
+            uri = r.uri
+            if uri.startswith("file://"):
+                paths.append(uri[7:])
+            elif uri.startswith("/"):
+                paths.append(uri)
+        logger.info("[MCP Roots] resolved %d paths via loose fallback: %s", len(paths), paths)
+        return paths
+    except Exception as e:
+        logger.warning("[MCP Roots] all attempts failed: %s", e)
+        return []
+
+
+# ===== MCP 工具定義 =====
+#
+# interactive_feedback：主 AI 与监工循环的唯一定型入口（JSON-RPC → 本函数 → DelegateManager）。
+# get_system_info：环境探测辅助；详细 stderr 调试仍由 MCP_DEBUG 控制（见 debug_log）。
+#
+@mcp.tool()
+async def interactive_feedback(
+    ctx: Context,
+    project_directory: Annotated[str, Field(description="项目目录路径")] = ".",
+    summary: Annotated[
+        str, Field(description="本轮工作内容的详细摘要：做了哪些修改、分析了什么、解决了什么问题（不少于30字）")
+    ] = "我已完成了您请求的任务。",
+    timeout: Annotated[int, Field(description="等待用户反馈的超时时间（秒）")] = 600,
+    # === 新增参数：循环机制与模式支持 ===
+    mode: Annotated[
+        Optional[str],
+        Field(description="运行模式覆盖: semi/manual，未指定时读取环境变量 MCP_DELEGATE_MODE（默认 manual）"),
+    ] = None,
+    intention: Annotated[
+        str, Field(description="AI 下一步的计划或意图说明（打算做什么、等待什么确认），注意：工作内容摘要请放在 summary 中")
+    ] = "",
+    original_task: Annotated[
+        str, Field(description="用户原始任务（首次调用时传入）")
+    ] = "",
+    task_complete: Annotated[
+        bool, Field(description="是否声明任务完成")
+    ] = False,
+    changed_files: Annotated[
+        Optional[list], Field(description="本次改动的文件列表")
+    ] = None,
+) -> list:
+    """Interactive feedback collection tool for LLM agents.
+
+    USAGE RULES:
+    1. During any process, task, or conversation, whether asking, replying, or completing phased tasks, you must call this tool to ask for feedback.
+    2. Unless receiving termination instructions, all steps must repeatedly call this tool.
+    3. Whenever user feedback is received, if the feedback content is not empty, you must call this tool again and adjust behavior based on the feedback content.
+    4. Only when the user explicitly indicates "end" or "no more interaction needed" can you stop calling this tool, and the process is considered complete.
+    5. You should summarize what have done, and provide project directory through args to let user know what you have done to provide feedback for next step.
+
+    Args:
+        project_directory: Project directory path for context
+        summary: Detailed summary of work done this round: what was modified, analyzed, or resolved (min 30 chars). Put your work content here, NOT in intention.
+        timeout: Timeout in seconds for waiting user feedback (default: 600 seconds)
+        mode: Override run mode (semi/manual). Falls back to MCP_DELEGATE_MODE env var, then 'manual'.
+        intention: AI's next-step plan or intent (what you plan to do next, what confirmation you're waiting for). Do NOT put work summaries here.
+        original_task: User's original task description (pass on first call)
+        task_complete: Whether AI declares the task as complete
+        changed_files: List of files changed in this round
+
+    Returns:
+        list: List containing TextContent and ImageContent objects representing user feedback
+    """
+    # [核心节点] MCP 工具入口：之后统一进入 DelegateManager.process（模式 / 完成验证 / Agent）
+    global _mcp_logger, _cached_roots
+    _call_start = time.monotonic()
+    _call_id = uuid4().hex[:8]
+
+    # 当 project_directory 为默认值 "." 或无效路径时，从 MCP roots 自动推断
+    _needs_roots = project_directory == "." or not os.path.exists(project_directory)
+    if _needs_roots:
+        if _cached_roots is None:
+            _cached_roots = await _resolve_roots_from_cursor(ctx)
+        if _cached_roots:
+            # 优先选择包含当前 MCP 源码的 root（处理多工作区场景）
+            _mcp_src = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+            project_directory = _cached_roots[0]
+            for _r in _cached_roots:
+                if _mcp_src.startswith(_r):
+                    project_directory = _r
+                    break
+            logger.info("[MCP Roots] using root: %s (from %s)", project_directory, _cached_roots)
+
+    # 生成 request_id：summary 相同视为同一请求的重试，复用 request_id
+    _resolved_dir = os.path.abspath(project_directory) if os.path.exists(project_directory) else os.path.abspath(os.getcwd())
+    _prev_req = _project_request_ids.get(_resolved_dir)
+    if _prev_req and _prev_req[1] == summary:
+        _request_id = _prev_req[0]
+    else:
+        _request_id = uuid4().hex[:8]
+        _project_request_ids[_resolved_dir] = (_request_id, summary)
+    if _mcp_logger is None:
+        _mcp_logger = _get_struct_logger("agent", project_directory=_resolved_dir)
+
+    _proj_name = os.path.basename(_resolved_dir)
+    _mcp_logger.info(
+        f"project={_proj_name} session=- timeout={timeout} call={_call_id}",
+        f"[MCP_CALL] mode={mode} task_complete={task_complete} "
+        f"summary_chars={len(summary or '')} intention_chars={len(intention or '')} "
+        f"changed_files={len(changed_files) if changed_files else 0}",
+    )
+    cf_list = "\n    ".join(changed_files) if changed_files else "(无)"
+    _qoder_pid = os.getenv("VSCODE_PID", "(unknown)")
+    debug_log(
+        f"[MCP入口] ━━━ AI → MCP interactive_feedback ━━━\n"
+        f"  MCP PID={os.getpid()}, VSCODE_PID={_qoder_pid}\n"
+        f"  project: {project_directory}\n"
+        f"  mode: {mode}, task_complete: {task_complete}, timeout: {timeout}\n"
+        f"  original_task: {original_task or '(未提供)'}\n"
+        f"  summary: {summary}\n"
+        f"  intention: {intention}\n"
+        f"  changed_files ({len(changed_files) if changed_files else 0}个):\n    {cf_list}"
+    )
+
+    try:
+        if not os.path.exists(project_directory):
+            project_directory = os.getcwd()
+        project_directory = os.path.abspath(project_directory)
+
+        # 通过 DelegateManager 编排处理
+        from .web.core.delegate_manager import get_delegate_manager
+
+        delegate = get_delegate_manager()
+
+        result = await delegate.process(
+            project_directory=project_directory,
+            summary=summary,
+            timeout=timeout,
+            mode=mode,
+            intention=intention,
+            original_task=original_task,
+            task_complete=task_complete,
+            changed_files=changed_files,
+            call_id=_call_id,
+            request_id=_request_id,
+        )
+
+        total_chars = sum(len(item.text) for item in result if hasattr(item, "text"))
+        all_text = "\n---块分隔---\n".join(
+            item.text for item in result if hasattr(item, "text")
+        ) or "(空)"
+        debug_log(
+            f"[MCP出口] MCP → AI 返回: {len(result)}个内容块, "
+            f"总字符数={total_chars}\n"
+            f"  完整内容:\n{all_text}"
+        )
+        # [核心节点] 正常返回主 AI；异常路径见下方 except（仍返回 TextContent，避免 JSON-RPC 失败）
+        _duration_ms = int((time.monotonic() - _call_start) * 1000)
+        if _mcp_logger:
+            _mcp_logger.info(
+                f"project={_proj_name} session=- duration_ms={_duration_ms} call={_call_id}",
+                f"[MCP_CALL_COMPLETE] result_type=success content_blocks={len(result)} "
+                f"total_text_chars={total_chars}",
+            )
+        return result
+
+    except Exception as e:
+        # 使用統一錯誤處理，但不影響 JSON RPC 響應
+        error_id = ErrorHandler.log_error_with_context(
+            e,
+            context={"operation": "回饋收集", "project_dir": project_directory},
+            error_type=ErrorType.SYSTEM,
+        )
+
+        # 生成用戶友好的錯誤信息
+        user_error_msg = ErrorHandler.format_user_error(e, include_technical=False)
+        debug_log(f"反馈收集错误 [错误ID: {error_id}]: {e!s}")
+        if _mcp_logger:
+            _mcp_logger.error(
+                f"project={_proj_name} error_id={error_id} call={_call_id}",
+                f"[MCP_ERROR] error_type={type(e).__name__} error_message={user_error_msg[:200]}",
+                exc_info=True,
+            )
+        return [TextContent(type="text", text=user_error_msg)]
+
+
+async def launch_web_feedback_ui(project_dir: str, summary: str, timeout: int) -> dict:
+    """
+    啟動 Web UI 收集回饋，支援自訂超時時間
+
+    Args:
+        project_dir: 專案目錄路徑
+        summary: AI 工作摘要
+        timeout: 超時時間（秒）
+
+    Returns:
+        dict: 收集到的回饋資料
+    """
+    # [核心节点] Semi/Manual 用户反馈通道；由 DelegateManager 在适当时机 await（非 MCP 工具直连）
+    if _mcp_logger:
+        _mcp_logger.info(
+            f"project={os.path.basename(project_dir)} timeout={timeout}",
+            f"[MCP_CALL] launch_web_feedback_ui summary_chars={len(summary or '')}",
+        )
+    debug_log(f"启动 Web UI 界面，超时时间: {timeout} 秒")
+
+    try:
+        # 使用新的 web 模組
+        from .web import launch_web_feedback_ui as web_launch
+
+        # 傳遞 timeout 參數給 Web UI
+        return await web_launch(project_dir, summary, timeout)
+    except ImportError as e:
+        # 使用統一錯誤處理
+        error_id = ErrorHandler.log_error_with_context(
+            e,
+            context={"operation": "Web UI 模組導入", "module": "web"},
+            error_type=ErrorType.DEPENDENCY,
+        )
+        user_error_msg = ErrorHandler.format_user_error(
+            e, ErrorType.DEPENDENCY, include_technical=False
+        )
+        debug_log(f"Web UI 模块导入失败 [错误ID: {error_id}]: {e}")
+
+        return {
+            "command_logs": "",
+            "interactive_feedback": user_error_msg,
+            "images": [],
+        }
+
+
+@mcp.tool()
+def get_system_info() -> str:
+    """
+    获取系统环境信息
+
+    Returns:
+        str: JSON 格式的系统信息
+    """
+    # [核心节点] 辅助诊断：与 interactive_feedback 编排无关，供主 AI / 人工排查环境
+    if _mcp_logger:
+        _mcp_logger.info("", "[MCP_CALL] get_system_info")
+    system_info = {
+        "平台": sys.platform,
+        "Python 版本": sys.version.split()[0],
+        "WSL 环境": is_wsl_environment(),
+        "界面类型": "桌面模式 (Tauri)",
+        "环境变量": {
+            "MCP_DESKTOP_MODE": os.getenv("MCP_DESKTOP_MODE"),
+            "MCP_WEB_PORT": os.getenv("MCP_WEB_PORT"),
+            "MCP_DEBUG": os.getenv("MCP_DEBUG"),
+            "MCP_SUPERVISOR_LOG_LEVEL": os.getenv("MCP_SUPERVISOR_LOG_LEVEL"),
+            "MCP_LANGUAGE": os.getenv("MCP_LANGUAGE"),
+            # 循环机制与模式相关环境变量
+            "MCP_DELEGATE_MODE": os.getenv("MCP_DELEGATE_MODE", "semi"),
+            "MCP_COUNTDOWN_SECONDS": os.getenv("MCP_COUNTDOWN_SECONDS", "15"),
+            "MCP_MAX_RETRIES": os.getenv("MCP_MAX_RETRIES", "100"),
+            "MCP_AUTO_HIDE": os.getenv("MCP_AUTO_HIDE", "true"),
+        },
+    }
+
+    return json.dumps(system_info, ensure_ascii=False, indent=2)
+
+
+def _get_log_dir() -> Path:
+    """获取日志目录 ``~/.mcp/logs/``，不存在则自动创建。"""
+    log_dir = Path.home() / ".mcp" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+def _get_daily_log_path() -> Path:
+    """返回按日期命名的日志文件路径，格式: ``~/.mcp/logs/mcp-supervisor-YYYY-MM-DD.log``。"""
+    from datetime import datetime
+    today = datetime.now().strftime("%Y-%m-%d")
+    return _get_log_dir() / f"mcp-supervisor-{today}.log"
+
+
+def _configure_supervisor_logging() -> None:
+    """为 ``mcp_ai_supervisor`` 包挂 stderr + 文件 双 Handler。
+
+    - **stderr Handler**: 输出到 stderr，供 IDE（Cursor/Qoder）捕获
+    - **FileHandler**: 按日期写入 ``~/.mcp/logs/mcp-supervisor-YYYY-MM-DD.log``，
+      确保即使 IDE 不捕获 stderr，也能有持久化日志可查
+
+    环境变量 ``MCP_SUPERVISOR_LOG_LEVEL`` 可覆写级别
+    （默认与 ``FASTMCP_LOG_LEVEL`` 或 INFO 一致）。
+    """
+    pkg = logging.getLogger("mcp_ai_supervisor")
+    if pkg.handlers:
+        return
+    raw = (
+        os.getenv("MCP_SUPERVISOR_LOG_LEVEL")
+        or os.getenv("FASTMCP_LOG_LEVEL")
+        or "INFO"
+    ).upper()
+    level = getattr(logging, raw, logging.INFO)
+
+    # === Handler 1: stderr（供 IDE 捕获） ===
+    stderr_handler = logging.StreamHandler(sys.stderr)
+    stderr_handler.setLevel(logging.DEBUG)
+    stderr_handler.setFormatter(
+        logging.Formatter("%(levelname)s: %(name)s: %(message)s")
+    )
+    pkg.addHandler(stderr_handler)
+
+    # === Handler 2: 按日期文件（持久化，不依赖 IDE） ===
+    try:
+        file_handler = logging.FileHandler(
+            str(_get_daily_log_path()), encoding="utf-8"
+        )
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s %(levelname)s %(name)s: %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+        pkg.addHandler(file_handler)
+    except Exception:
+        # 文件写入失败（权限等）时静默降级，不影响主流程
+        pass
+
+    pkg.setLevel(level)
+    pkg.propagate = False
+
+
+# ===== 主程式入口 =====
+def main():
+    """主要入口點，用於套件執行
+    收集用戶的互動回饋，支援文字和圖片
+    此工具使用 Web UI 介面收集用戶回饋，支援智能環境檢測。
+
+    用戶可以：
+    1. 執行命令來驗證結果
+    2. 提供文字回饋
+    3. 上傳圖片作為回饋
+    4. 查看 AI 的工作摘要
+
+    調試模式：
+    - 設置環境變數 MCP_DEBUG=true 可啟用詳細調試輸出
+    - 生產環境建議關閉調試模式以避免輸出干擾
+
+
+    """
+    # 启动时恢复残留的活跃对话记录
+    try:
+        from .web.core.conversation_recorder import get_conversation_recorder
+        get_conversation_recorder().recover_active_sessions()
+    except Exception as _recover_err:
+        debug_log(f"对话记录恢复失败（不影响主流程）: {_recover_err}")
+
+    # 檢查是否啟用調試模式
+    debug_enabled = os.getenv("MCP_DEBUG", "").lower() in ("true", "1", "yes", "on")
+
+    if debug_enabled:
+        debug_log("🚀 启动互动式反馈收集 MCP 服务器")
+        debug_log(f"   服务器名称: {SERVER_NAME}")
+        debug_log(f"   版本: {__version__}")
+        debug_log(f"   平台: {sys.platform}")
+        debug_log(f"   编码初始化: {'成功' if _encoding_initialized else '失败'}")
+        debug_log("   界面类型: 桌面模式 (Tauri)")
+        debug_log("   等待来自 AI 助手的调用...")
+        debug_log("准备启动 MCP 服务器...")
+        debug_log("调用 mcp.run()...")
+
+    _start_time = time.time()
+    _startup_logger = None
+    try:
+        _configure_supervisor_logging()
+
+        # [MCP_START] 记录 MCP 进程启动
+        _startup_logger = _get_struct_logger("agent", project_directory=os.getcwd())
+        _startup_logger.info(
+            f"pid={os.getpid()} version={__version__}",
+            "[MCP_START] MCP Server 启动",
+        )
+
+        mcp.run()
+    except KeyboardInterrupt:
+        # [MCP_SHUTDOWN] 记录正常退出
+        _uptime = int(time.time() - _start_time)
+        _shutdown_logger = _mcp_logger or _startup_logger
+        if _shutdown_logger:
+            _shutdown_logger.info(
+                f"pid={os.getpid()} uptime_seconds={_uptime}",
+                "[MCP_SHUTDOWN] 收到中断信号，正常退出",
+            )
+        if debug_enabled:
+            debug_log("收到中断信号，正常退出")
+        sys.exit(0)
+    except Exception as e:
+        if debug_enabled:
+            debug_log(f"MCP 服务器启动失败: {e}")
+            import traceback
+            debug_log(f"详细错误: {traceback.format_exc()}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

mcp_ai_supervisor/utils/__init__.py

@@ -0,0 +1,28 @@
+"""
+MCP AI Supervisor 工具模組
+============================
+
+提供各種工具類和函數，包括錯誤處理、資源管理等。
+"""
+
+from .error_handler import ErrorHandler, ErrorType
+from .resource_manager import (
+    ResourceManager,
+    cleanup_all_resources,
+    create_temp_dir,
+    create_temp_file,
+    get_resource_manager,
+    register_process,
+)
+
+
+__all__ = [
+    "ErrorHandler",
+    "ErrorType",
+    "ResourceManager",
+    "cleanup_all_resources",
+    "create_temp_dir",
+    "create_temp_file",
+    "get_resource_manager",
+    "register_process",
+]

mcp_ai_supervisor/utils/error_handler.py

@@ -0,0 +1,10 @@
+"""代理模块：重定向到 mcp_supervisor_core.error_handler
+
+重构过渡期保持向后兼容。
+Phase 3 删除 src/ 时此文件一并删除。
+"""
+from mcp_supervisor_core.error_handler import *  # noqa: F401,F403
+from mcp_supervisor_core.error_handler import (  # noqa: F401
+    ErrorHandler,
+    ErrorType,
+)