mcp-supervisor-core 0.1.0__py3-none-any.whl

mcp_supervisor_core/__init__.py

@@ -0,0 +1,7 @@
+"""MCP Supervisor Core — 基础设施包
+
+提供日志、路径、错误处理、国际化等底层工具，
+被 mcp-server 和 workbench-server 共同依赖。
+"""
+
+__version__ = "0.1.0"

mcp_supervisor_core/debug.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+統一調試日誌模組
+================
+
+提供統一的調試日誌功能，確保調試輸出不會干擾 MCP 通信。
+所有調試輸出都會發送到 stderr，並且只在調試模式啟用時才輸出。
+
+使用方法：
+```python
+from .debug import debug_log
+
+debug_log("這是一條調試信息")
+```
+
+環境變數控制：
+- MCP_DEBUG=true/1/yes/on: 啟用調試模式
+- MCP_DEBUG=false/0/no/off: 關閉調試模式（默認）
+
+作者: Minidoracat
+"""
+
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+# === 文件日志句柄（懒初始化，按日期自动切换） ===
+_log_file = None
+_log_date: str = ""
+
+
+def _get_file_logger():
+    """获取当日的文件日志句柄，日期变化时自动切换新文件。"""
+    global _log_file, _log_date
+    today = datetime.now().strftime("%Y-%m-%d")
+    if _log_file is not None and _log_date == today:
+        return _log_file
+    # 关闭旧句柄
+    if _log_file is not None:
+        try:
+            _log_file.close()
+        except Exception:
+            pass
+    try:
+        log_dir = Path.home() / ".mcp" / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        _log_file = open(log_dir / f"mcp-supervisor-{today}.log", "a", encoding="utf-8")
+        _log_date = today
+    except Exception:
+        _log_file = None
+    return _log_file
+
+
+def debug_log(message: Any, prefix: str = "DEBUG") -> None:
+    """
+    输出调试信息到 stderr + 文件日志，避免污染 stdout（MCP JSON-RPC 通信通道）
+
+    - **stderr**: 仅在 ``MCP_DEBUG=true`` 时输出，供 IDE 捕获
+    - **文件日志**: 始终写入 ``~/.mcp/logs/mcp-supervisor-YYYY-MM-DD.log``，
+      确保即使 IDE 不捕获 stderr 也有日志可查
+
+    Args:
+        message: 要输出的调试信息
+        prefix: 调试信息的前缀标识，默认为 "DEBUG"
+    """
+    try:
+        if not isinstance(message, str):
+            message = str(message)
+    except Exception:
+        return
+
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    formatted = f"[{prefix}] {message}"
+
+    # === 写入 stderr（仅 MCP_DEBUG 开启时） ===
+    if os.getenv("MCP_DEBUG", "").lower() in ("true", "1", "yes", "on"):
+        try:
+            print(formatted, file=sys.stderr, flush=True)
+        except UnicodeEncodeError:
+            safe = message.encode("ascii", errors="replace").decode("ascii")
+            print(f"[{prefix}] {safe}", file=sys.stderr, flush=True)
+        except Exception:
+            pass
+
+    # === 写入文件日志（始终写入） ===
+    try:
+        fh = _get_file_logger()
+        if fh is not None:
+            fh.write(f"{timestamp} {formatted}\n")
+            fh.flush()
+    except Exception:
+        pass
+
+
+def i18n_debug_log(message: Any) -> None:
+    """國際化模組專用的調試日誌"""
+    debug_log(message, "I18N")
+
+
+def server_debug_log(message: Any) -> None:
+    """伺服器模組專用的調試日誌"""
+    debug_log(message, "SERVER")
+
+
+def web_debug_log(message: Any) -> None:
+    """Web UI 模組專用的調試日誌"""
+    debug_log(message, "WEB")
+
+
+# === 日志限流器 ===
+_rate_limit_last: dict[str, float] = {}
+
+
+def debug_log_throttled(
+    message: Any,
+    prefix: str = "DEBUG",
+    *,
+    key: str,
+    interval_seconds: float = 60.0,
+) -> None:
+    """限流版 debug_log：同一 key 在 interval_seconds 内最多输出一次。"""
+    import time
+
+    now = time.monotonic()
+    last = _rate_limit_last.get(key, 0.0)
+    if now - last < interval_seconds:
+        return
+    _rate_limit_last[key] = now
+    debug_log(message, prefix)
+
+
+def is_debug_enabled() -> bool:
+    """檢查是否啟用了調試模式"""
+    return os.getenv("MCP_DEBUG", "").lower() in ("true", "1", "yes", "on")
+
+
+def set_debug_mode(enabled: bool) -> None:
+    """設置調試模式（用於測試）"""
+    os.environ["MCP_DEBUG"] = "true" if enabled else "false"

mcp_supervisor_core/error_handler.py

@@ -0,0 +1,450 @@
+"""
+統一錯誤處理框架
+================
+
+提供統一的錯誤處理機制，包括：
+- 錯誤類型分類
+- 用戶友好錯誤信息
+- 錯誤上下文記錄
+- 解決方案建議
+- 國際化支持
+
+注意：此模組不會影響 JSON RPC 通信，所有錯誤處理都在應用層進行。
+"""
+
+import os
+import time
+import traceback
+from enum import Enum
+from typing import Any
+
+from .debug import debug_log
+
+
+class ErrorType(Enum):
+    """錯誤類型枚舉"""
+
+    NETWORK = "network"  # 網絡相關錯誤
+    FILE_IO = "file_io"  # 文件 I/O 錯誤
+    PROCESS = "process"  # 進程相關錯誤
+    TIMEOUT = "timeout"  # 超時錯誤
+    USER_CANCEL = "user_cancel"  # 用戶取消操作
+    SYSTEM = "system"  # 系統錯誤
+    PERMISSION = "permission"  # 權限錯誤
+    VALIDATION = "validation"  # 數據驗證錯誤
+    DEPENDENCY = "dependency"  # 依賴錯誤
+    CONFIGURATION = "config"  # 配置錯誤
+
+
+class ErrorSeverity(Enum):
+    """錯誤嚴重程度"""
+
+    LOW = "low"  # 低：不影響核心功能
+    MEDIUM = "medium"  # 中：影響部分功能
+    HIGH = "high"  # 高：影響核心功能
+    CRITICAL = "critical"  # 嚴重：系統無法正常運行
+
+
+class ErrorHandler:
+    """統一錯誤處理器"""
+
+    # 錯誤類型到用戶友好信息的映射
+    _ERROR_MESSAGES = {
+        ErrorType.NETWORK: {
+            "zh-TW": "網絡連接出現問題",
+            "zh-CN": "网络连接出现问题",
+            "en": "Network connection issue",
+        },
+        ErrorType.FILE_IO: {
+            "zh-TW": "文件讀寫出現問題",
+            "zh-CN": "文件读写出现问题",
+            "en": "File read/write issue",
+        },
+        ErrorType.PROCESS: {
+            "zh-TW": "進程執行出現問題",
+            "zh-CN": "进程执行出现问题",
+            "en": "Process execution issue",
+        },
+        ErrorType.TIMEOUT: {
+            "zh-TW": "操作超時",
+            "zh-CN": "操作超时",
+            "en": "Operation timeout",
+        },
+        ErrorType.USER_CANCEL: {
+            "zh-TW": "用戶取消了操作",
+            "zh-CN": "用户取消了操作",
+            "en": "User cancelled the operation",
+        },
+        ErrorType.SYSTEM: {
+            "zh-TW": "系統出現問題",
+            "zh-CN": "系统出现问题",
+            "en": "System issue",
+        },
+        ErrorType.PERMISSION: {
+            "zh-TW": "權限不足",
+            "zh-CN": "权限不足",
+            "en": "Insufficient permissions",
+        },
+        ErrorType.VALIDATION: {
+            "zh-TW": "數據驗證失敗",
+            "zh-CN": "数据验证失败",
+            "en": "Data validation failed",
+        },
+        ErrorType.DEPENDENCY: {
+            "zh-TW": "依賴組件出現問題",
+            "zh-CN": "依赖组件出现问题",
+            "en": "Dependency issue",
+        },
+        ErrorType.CONFIGURATION: {
+            "zh-TW": "配置出現問題",
+            "zh-CN": "配置出现问题",
+            "en": "Configuration issue",
+        },
+    }
+
+    # 錯誤解決建議
+    _ERROR_SOLUTIONS = {
+        ErrorType.NETWORK: {
+            "zh-TW": ["檢查網絡連接是否正常", "確認防火牆設置", "嘗試重新啟動應用程序"],
+            "zh-CN": ["检查网络连接是否正常", "确认防火墙设置", "尝试重新启动应用程序"],
+            "en": [
+                "Check network connection",
+                "Verify firewall settings",
+                "Try restarting the application",
+            ],
+        },
+        ErrorType.FILE_IO: {
+            "zh-TW": ["檢查文件是否存在", "確認文件權限", "檢查磁盤空間是否足夠"],
+            "zh-CN": ["检查文件是否存在", "确认文件权限", "检查磁盘空间是否足够"],
+            "en": [
+                "Check if file exists",
+                "Verify file permissions",
+                "Check available disk space",
+            ],
+        },
+        ErrorType.PROCESS: {
+            "zh-TW": [
+                "檢查進程是否正在運行",
+                "確認系統資源是否足夠",
+                "嘗試重新啟動相關服務",
+            ],
+            "zh-CN": [
+                "检查进程是否正在运行",
+                "确认系统资源是否足够",
+                "尝试重新启动相关服务",
+            ],
+            "en": [
+                "Check if process is running",
+                "Verify system resources",
+                "Try restarting related services",
+            ],
+        },
+        ErrorType.TIMEOUT: {
+            "zh-TW": ["增加超時時間設置", "檢查網絡延遲", "稍後重試操作"],
+            "zh-CN": ["增加超时时间设置", "检查网络延迟", "稍后重试操作"],
+            "en": [
+                "Increase timeout settings",
+                "Check network latency",
+                "Retry the operation later",
+            ],
+        },
+        ErrorType.PERMISSION: {
+            "zh-TW": ["以管理員身份運行", "檢查文件/目錄權限", "聯繫系統管理員"],
+            "zh-CN": ["以管理员身份运行", "检查文件/目录权限", "联系系统管理员"],
+            "en": [
+                "Run as administrator",
+                "Check file/directory permissions",
+                "Contact system administrator",
+            ],
+        },
+    }
+
+    @staticmethod
+    def get_current_language() -> str:
+        """獲取當前語言設置"""
+        try:
+            # 嘗試從 i18n 模組獲取當前語言
+            from ..i18n import get_i18n_manager
+
+            return get_i18n_manager().get_current_language()
+        except Exception:
+            # 回退到環境變數或默認語言
+            return os.getenv("MCP_LANGUAGE", "zh-TW")
+
+    @staticmethod
+    def get_i18n_error_message(error_type: ErrorType) -> str:
+        """從國際化系統獲取錯誤信息"""
+        try:
+            from ..i18n import get_i18n_manager
+
+            i18n = get_i18n_manager()
+            key = f"errors.types.{error_type.value}"
+            message = i18n.t(key)
+            # 如果返回的是鍵本身，說明沒有找到翻譯，使用回退
+            if message == key:
+                raise Exception("Translation not found")
+            return message
+        except Exception:
+            # 回退到內建映射
+            language = ErrorHandler.get_current_language()
+            error_messages = ErrorHandler._ERROR_MESSAGES.get(error_type, {})
+            return error_messages.get(
+                language, error_messages.get("zh-TW", "發生未知錯誤")
+            )
+
+    @staticmethod
+    def get_i18n_error_solutions(error_type: ErrorType) -> list[str]:
+        """從國際化系統獲取錯誤解決方案"""
+        try:
+            from ..i18n import get_i18n_manager
+
+            i18n = get_i18n_manager()
+            key = f"errors.solutions.{error_type.value}"
+            i18n_result = i18n.t(key)
+
+            # 修復類型推斷問題 - 使用 Any 類型並明確檢查
+            from typing import Any
+
+            result: Any = i18n_result
+
+            # 檢查是否為列表類型且非空
+            if isinstance(result, list) and len(result) > 0:
+                return result
+
+            # 如果不是列表或為空，使用回退
+            raise Exception("Solutions not found or invalid format")
+        except Exception:
+            # 回退到內建映射
+            language = ErrorHandler.get_current_language()
+            solutions_dict = ErrorHandler._ERROR_SOLUTIONS.get(error_type, {})
+            return solutions_dict.get(language, solutions_dict.get("zh-TW", []))
+
+    @staticmethod
+    def classify_error(error: Exception) -> ErrorType:
+        """
+        根據異常類型自動分類錯誤
+
+        Args:
+            error: Python 異常對象
+
+        Returns:
+            ErrorType: 錯誤類型
+        """
+        error_name = type(error).__name__
+        error_message = str(error).lower()
+
+        # 超時錯誤（優先檢查，避免被網絡錯誤覆蓋）
+        if "timeout" in error_name.lower() or "timeout" in error_message:
+            return ErrorType.TIMEOUT
+
+        # 權限錯誤（優先檢查，避免被文件錯誤覆蓋）
+        if "permission" in error_name.lower():
+            return ErrorType.PERMISSION
+        if any(
+            keyword in error_message
+            for keyword in ["permission denied", "access denied", "forbidden"]
+        ):
+            return ErrorType.PERMISSION
+
+        # 網絡相關錯誤
+        if any(
+            keyword in error_name.lower()
+            for keyword in ["connection", "network", "socket"]
+        ):
+            return ErrorType.NETWORK
+        if any(
+            keyword in error_message for keyword in ["connection", "network", "socket"]
+        ):
+            return ErrorType.NETWORK
+
+        # 文件 I/O 錯誤
+        if any(
+            keyword in error_name.lower() for keyword in ["file", "ioerror"]
+        ):  # 使用更精確的匹配
+            return ErrorType.FILE_IO
+        if any(
+            keyword in error_message
+            for keyword in ["file", "directory", "no such file"]
+        ):
+            return ErrorType.FILE_IO
+
+        # 進程相關錯誤
+        if any(keyword in error_name.lower() for keyword in ["process", "subprocess"]):
+            return ErrorType.PROCESS
+        if any(
+            keyword in error_message for keyword in ["process", "command", "executable"]
+        ):
+            return ErrorType.PROCESS
+
+        # 驗證錯誤（僅按類名匹配 validation，避免 ValueError/TypeError 因含 value/type 被誤判）
+        if "validation" in error_name.lower():
+            return ErrorType.VALIDATION
+        # asyncio 流讀取單行超限等，消息類似 separator/chunk/limit
+        if "separator" in error_message and "chunk" in error_message:
+            return ErrorType.SYSTEM
+
+        # 配置錯誤
+        if any(
+            keyword in error_message for keyword in ["config", "setting", "environment"]
+        ):
+            return ErrorType.CONFIGURATION
+
+        # 默認為系統錯誤
+        return ErrorType.SYSTEM
+
+    @staticmethod
+    def format_user_error(
+        error: Exception,
+        error_type: ErrorType | None = None,
+        context: dict[str, Any] | None = None,
+        include_technical: bool = False,
+    ) -> str:
+        """
+        將技術錯誤轉換為用戶友好的錯誤信息
+
+        Args:
+            error: Python 異常對象
+            error_type: 錯誤類型（可選，會自動分類）
+            context: 錯誤上下文信息
+            include_technical: 是否包含技術細節
+
+        Returns:
+            str: 用戶友好的錯誤信息
+        """
+        # 自動分類錯誤類型
+        if error_type is None:
+            error_type = ErrorHandler.classify_error(error)
+
+        # 獲取當前語言
+        language = ErrorHandler.get_current_language()
+
+        # 獲取用戶友好的錯誤信息（優先使用國際化系統）
+        user_message = ErrorHandler.get_i18n_error_message(error_type)
+
+        # 構建完整的錯誤信息
+        parts = [f"❌ {user_message}"]
+
+        # 添加上下文信息
+        if context:
+            if context.get("operation"):
+                if language == "en":
+                    parts.append(f"Operation: {context['operation']}")
+                else:
+                    parts.append(f"操作：{context['operation']}")
+
+            if context.get("file_path"):
+                if language == "en":
+                    parts.append(f"File: {context['file_path']}")
+                else:
+                    parts.append(f"文件：{context['file_path']}")
+
+        # 添加技術細節（如果需要）
+        if include_technical:
+            if language == "en":
+                parts.append(f"Technical details: {type(error).__name__}: {error!s}")
+            else:
+                parts.append(f"技術細節：{type(error).__name__}: {error!s}")
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def get_error_solutions(error_type: ErrorType) -> list[str]:
+        """
+        獲取錯誤解決建議
+
+        Args:
+            error_type: 錯誤類型
+
+        Returns:
+            List[str]: 解決建議列表
+        """
+        return ErrorHandler.get_i18n_error_solutions(error_type)
+
+    @staticmethod
+    def log_error_with_context(
+        error: Exception,
+        context: dict[str, Any] | None = None,
+        error_type: ErrorType | None = None,
+        severity: ErrorSeverity = ErrorSeverity.MEDIUM,
+    ) -> str:
+        """
+        記錄帶上下文的錯誤信息（不影響 JSON RPC）
+
+        Args:
+            error: Python 異常對象
+            context: 錯誤上下文信息
+            error_type: 錯誤類型
+            severity: 錯誤嚴重程度
+
+        Returns:
+            str: 錯誤 ID，用於追蹤
+        """
+        # 生成錯誤 ID
+        error_id = f"ERR_{int(time.time())}_{id(error) % 10000}"
+
+        # 自動分類錯誤
+        if error_type is None:
+            error_type = ErrorHandler.classify_error(error)
+
+        # 錯誤記錄已通過 debug_log 輸出，無需額外存儲
+
+        # 記錄到調試日誌（不影響 JSON RPC）
+        debug_log(f"錯誤記錄 [{error_id}]: {error_type.value} - {error!s}")
+
+        if context:
+            debug_log(f"錯誤上下文 [{error_id}]: {context}")
+
+        # 對於嚴重錯誤，記錄完整堆棧跟蹤
+        if severity in [ErrorSeverity.HIGH, ErrorSeverity.CRITICAL]:
+            debug_log(f"錯誤堆棧 [{error_id}]:\n{traceback.format_exc()}")
+
+        return error_id
+
+    @staticmethod
+    def create_error_response(
+        error: Exception,
+        context: dict[str, Any] | None = None,
+        error_type: ErrorType | None = None,
+        include_solutions: bool = True,
+        for_user: bool = True,
+    ) -> dict[str, Any]:
+        """
+        創建標準化的錯誤響應
+
+        Args:
+            error: Python 異常對象
+            context: 錯誤上下文
+            error_type: 錯誤類型
+            include_solutions: 是否包含解決建議
+            for_user: 是否為用戶界面使用
+
+        Returns:
+            Dict[str, Any]: 標準化錯誤響應
+        """
+        # 自動分類錯誤
+        if error_type is None:
+            error_type = ErrorHandler.classify_error(error)
+
+        # 記錄錯誤
+        error_id = ErrorHandler.log_error_with_context(error, context, error_type)
+
+        # 構建響應
+        response = {
+            "success": False,
+            "error_id": error_id,
+            "error_type": error_type.value,
+            "message": ErrorHandler.format_user_error(
+                error, error_type, context, include_technical=not for_user
+            ),
+        }
+
+        # 添加解決建議
+        if include_solutions:
+            solutions = ErrorHandler.get_error_solutions(error_type)
+            response["solutions"] = solutions  # 即使為空列表也添加
+
+        # 添加上下文（僅用於調試）
+        if context and not for_user:
+            response["context"] = context
+
+        return response