mofox-plugin-dev-toolkit 0.2.1__py3-none-any.whl

mpdt/utils/plugin_parser.py

@@ -0,0 +1,196 @@
+"""
+插件名称解析器
+使用 AST 解析插件文件，提取运行时插件名称
+"""
+
+import ast
+from pathlib import Path
+from typing import Optional
+
+
+def extract_plugin_name(plugin_path: Path) -> str | None:
+    """从插件目录提取运行时插件名称
+
+    Args:
+        plugin_path: 插件目录路径
+
+    Returns:
+        插件名称，如果解析失败返回 None
+
+    Example:
+        >>> extract_plugin_name(Path("my_awesome_plugin"))
+        "awesome_plugin"  # 从 plugin.py 中的 plugin_name 属性读取
+    """
+    plugin_file = plugin_path / "plugin.py"
+
+    if not plugin_file.exists():
+        return None
+
+    try:
+        with open(plugin_file, "r", encoding="utf-8") as f:
+            source = f.read()
+
+        tree = ast.parse(source)
+
+        # 查找 BasePlugin 的子类
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                # 检查是否继承自 BasePlugin
+                is_base_plugin = False
+                for base in node.bases:
+                    if isinstance(base, ast.Name) and base.id == "BasePlugin":
+                        is_base_plugin = True
+                        break
+
+                if not is_base_plugin:
+                    continue
+
+                # 查找 plugin_name 属性
+                for item in node.body:
+                    # 处理普通赋值: plugin_name = "xxx"
+                    if isinstance(item, ast.Assign):
+                        for target in item.targets:
+                            if isinstance(target, ast.Name) and target.id == "plugin_name":
+                                if isinstance(item.value, ast.Constant):
+                                    return item.value.value
+
+                    # 处理带类型注解的赋值: plugin_name: str = "xxx"
+                    elif isinstance(item, ast.AnnAssign):
+                        if isinstance(item.target, ast.Name) and item.target.id == "plugin_name":
+                            if item.value and isinstance(item.value, ast.Constant):
+                                return item.value.value
+
+        return None
+
+    except Exception:
+        return None
+
+
+def get_plugin_info(plugin_path: Path) -> dict:
+    """获取插件详细信息
+
+    Args:
+        plugin_path: 插件目录路径
+
+    Returns:
+        包含插件信息的字典:
+        {
+            "dir_name": "my_awesome_plugin",
+            "plugin_name": "awesome_plugin",
+            "class_name": "MyAwesomePlugin",
+            "path": "/path/to/plugin",
+            "has_plugin_file": True,
+            "parse_success": True
+        }
+    """
+    info = {
+        "dir_name": plugin_path.name,
+        "plugin_name": None,
+        "class_name": None,
+        "path": str(plugin_path.absolute()),
+        "has_plugin_file": False,
+        "parse_success": False,
+    }
+
+    plugin_file = plugin_path / "plugin.py"
+
+    if not plugin_file.exists():
+        return info
+
+    info["has_plugin_file"] = True
+
+    try:
+        with open(plugin_file, "r", encoding="utf-8") as f:
+            source = f.read()
+
+        tree = ast.parse(source)
+
+        # 查找 BasePlugin 的子类
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                # 检查是否继承自 BasePlugin
+                is_base_plugin = False
+                for base in node.bases:
+                    if isinstance(base, ast.Name) and base.id == "BasePlugin":
+                        is_base_plugin = True
+                        break
+
+                if not is_base_plugin:
+                    continue
+
+                info["class_name"] = node.name
+
+                # 查找 plugin_name 属性
+                for item in node.body:
+                    # 处理普通赋值: plugin_name = "xxx"
+                    if isinstance(item, ast.Assign):
+                        for target in item.targets:
+                            if isinstance(target, ast.Name) and target.id == "plugin_name":
+                                if isinstance(item.value, ast.Constant):
+                                    info["plugin_name"] = item.value.value
+                                    info["parse_success"] = True
+                                    break
+
+                    # 处理带类型注解的赋值: plugin_name: str = "xxx"
+                    elif isinstance(item, ast.AnnAssign):
+                        if isinstance(item.target, ast.Name) and item.target.id == "plugin_name":
+                            if item.value and isinstance(item.value, ast.Constant):
+                                info["plugin_name"] = item.value.value
+                                info["parse_success"] = True
+                                break
+
+                # 找到 BasePlugin 子类后跳出
+                if info["class_name"]:
+                    break
+
+        return info
+
+    except Exception as e:
+        info["error"] = str(e)
+        return info
+
+
+def validate_plugin_structure(plugin_path: Path) -> tuple[bool, list[str]]:
+    """验证插件目录结构
+
+    Args:
+        plugin_path: 插件目录路径
+
+    Returns:
+        (是否有效, 错误/警告消息列表)
+    """
+    messages = []
+
+    if not plugin_path.is_dir():
+        return False, ["路径不是一个目录"]
+
+    # 检查必需文件
+    required_files = {"plugin.py": "插件主文件", "__init__.py": "包初始化文件"}
+
+    for filename, description in required_files.items():
+        file_path = plugin_path / filename
+        if not file_path.exists():
+            messages.append(f"缺少 {description}: {filename}")
+
+    # 如果缺少必需文件，直接返回
+    if messages:
+        return False, messages
+
+    # 检查 plugin.py 是否可以解析
+    plugin_name = extract_plugin_name(plugin_path)
+    if not plugin_name:
+        messages.append("无法从 plugin.py 中提取 plugin_name")
+        messages.append("请确保有一个继承自 BasePlugin 的类，并定义了 plugin_name 属性")
+        return False, messages
+
+    # 检查推荐文件
+    recommended_files = {"config.toml": "配置文件", "README.md": "说明文档"}
+
+    for filename, description in recommended_files.items():
+        file_path = plugin_path / filename
+        if not file_path.exists():
+            messages.append(f"建议添加 {description}: {filename}")
+
+    # 如果只有建议性消息，仍然返回有效
+    has_errors = any("缺少" in msg or "无法" in msg for msg in messages)
+    return not has_errors, messages

mpdt/utils/template_engine.py

@@ -0,0 +1,112 @@
+"""
+模板引擎
+"""
+
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, Template
+
+
+class TemplateEngine:
+    """模板引擎类"""
+
+    def __init__(self, template_dir: Path | str | None = None):
+        """
+        初始化模板引擎
+
+        Args:
+            template_dir: 模板目录路径
+        """
+        if template_dir:
+            self.template_dir = Path(template_dir)
+            self.env = Environment(
+                loader=FileSystemLoader(str(self.template_dir)),
+                trim_blocks=True,
+                lstrip_blocks=True,
+            )
+        else:
+            # 使用默认模板目录
+            default_template_dir = Path(__file__).parent.parent / "templates"
+            self.template_dir = default_template_dir
+
+            if default_template_dir.exists():
+                self.env = Environment(
+                    loader=FileSystemLoader(str(default_template_dir)),
+                    trim_blocks=True,
+                    lstrip_blocks=True,
+                )
+            else:
+                self.env = None
+
+    def render_string(self, template_string: str, context: dict[str, Any]) -> str:
+        """
+        渲染字符串模板
+
+        Args:
+            template_string: 模板字符串
+            context: 模板变量
+
+        Returns:
+            渲染后的字符串
+        """
+        template = Template(template_string, trim_blocks=True, lstrip_blocks=True)
+        return template.render(**context)
+
+    def render_file(self, template_name: str, context: dict[str, Any]) -> str:
+        """
+        渲染文件模板
+
+        Args:
+            template_name: 模板文件名
+            context: 模板变量
+
+        Returns:
+            渲染后的字符串
+        """
+        if self.env is None:
+            raise ValueError("模板目录不存在，无法加载文件模板")
+
+        template = self.env.get_template(template_name)
+        return template.render(**context)
+
+    def render_to_file(self, template_name: str, context: dict[str, Any], output_path: Path | str) -> None:
+        """
+        渲染模板并写入文件
+
+        Args:
+            template_name: 模板文件名
+            context: 模板变量
+            output_path: 输出文件路径
+        """
+        content = self.render_file(template_name, context)
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(content, encoding="utf-8")
+
+
+def prepare_common_context(**kwargs: Any) -> dict[str, Any]:
+    """
+    准备通用模板变量
+
+    Args:
+        **kwargs: 额外的变量
+
+    Returns:
+        模板变量字典
+    """
+    from datetime import datetime
+
+    from mpdt.utils.file_ops import get_git_user_info
+
+    git_info = get_git_user_info()
+
+    context = {
+        "timestamp": datetime.now().isoformat(),
+        "year": datetime.now().year,
+        "author": git_info.get("name", ""),
+        "author_email": git_info.get("email", ""),
+    }
+
+    context.update(kwargs)
+    return context

mpdt/validators/__init__.py

@@ -0,0 +1,26 @@
+"""
+验证器模块
+"""
+
+from .auto_fix_validator import AutoFixValidator
+from .base import BaseValidator, ValidationIssue, ValidationLevel, ValidationResult
+from .component_validator import ComponentValidator
+from .config_validator import ConfigValidator
+from .metadata_validator import MetadataValidator
+from .structure_validator import StructureValidator
+from .style_validator import StyleValidator
+from .type_validator import TypeValidator
+
+__all__ = [
+    "BaseValidator",
+    "ValidationResult",
+    "ValidationIssue",
+    "ValidationLevel",
+    "StructureValidator",
+    "MetadataValidator",
+    "ComponentValidator",
+    "ConfigValidator",
+    "StyleValidator",
+    "TypeValidator",
+    "AutoFixValidator",
+]

mpdt/validators/auto_fix_validator.py

@@ -0,0 +1,182 @@
+"""自动修复验证器
+
+提供自动修复常见问题的功能
+"""
+
+import ast
+from pathlib import Path
+
+from .base import BaseValidator, ValidationResult
+
+
+class AutoFixValidator(BaseValidator):
+    """自动修复验证器
+
+    自动修复插件中的常见问题
+    """
+
+    def __init__(self, plugin_path: Path):
+        super().__init__(plugin_path)
+        self.fixes_applied = []
+
+    def validate(self) -> ValidationResult:
+        """执行自动修复（实际上是 fix 而非 validate）"""
+        result = ValidationResult(
+            validator_name="AutoFixValidator",
+            success=True
+        )
+
+        plugin_name = self._get_plugin_name()
+        if not plugin_name:
+            result.add_error("无法确定插件名称")
+            return result
+
+        # 修复缺失的元数据
+        self._fix_missing_metadata(result)
+
+        # 修复导入顺序
+        self._fix_import_order(result)
+
+        # 汇总修复结果
+        if self.fixes_applied:
+            result.add_info(f"应用了 {len(self.fixes_applied)} 个自动修复")
+            for fix in self.fixes_applied:
+                result.add_info(fix)
+        else:
+            result.add_info("未发现可自动修复的问题")
+
+        return result
+
+    def _fix_missing_metadata(self, result: ValidationResult) -> None:
+        """修复缺失的元数据字段"""
+        init_file = self.plugin_path / "__init__.py"
+        if not init_file.exists():
+            return
+
+        try:
+            content = init_file.read_text(encoding="utf-8")
+            tree = ast.parse(content)
+
+            # 查找 __plugin_meta__ 定义
+            meta_found = False
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Assign):
+                    for target in node.targets:
+                        if isinstance(target, ast.Name) and target.id == "__plugin_meta__":
+                            meta_found = True
+                            break
+
+            if not meta_found:
+                # 添加基本的 __plugin_meta__ 定义
+                plugin_name = self._get_plugin_name()
+                meta_template = f'''
+from src.plugin_system import PluginMetadata
+
+__plugin_meta__ = PluginMetadata(
+    name="{plugin_name}",
+    description="插件描述",
+    usage="插件使用说明",
+    version="0.1.0",
+    author="",
+    license="MIT"
+)
+'''
+                # 在文件开头添加
+                new_content = meta_template + "\n" + content
+                init_file.write_text(new_content, encoding="utf-8")
+                self.fixes_applied.append("添加缺失的 __plugin_meta__ 定义到 __init__.py")
+
+        except Exception as e:
+            result.add_warning(f"无法自动修复元数据: {e}")
+
+    def _fix_import_order(self, result: ValidationResult) -> None:
+        """修复导入顺序（使用 ruff --fix）"""
+        try:
+            import subprocess
+
+            # 查找所有 Python 文件
+            python_files = list(self.plugin_path.rglob("*.py"))
+
+            for py_file in python_files:
+                # 使用 ruff 的 isort 规则修复导入顺序
+                subprocess.run(
+                    ["ruff", "check", "--select", "I", "--fix", str(py_file)],
+                    capture_output=True,
+                    check=False  # 不因错误退出而失败
+                )
+
+            self.fixes_applied.append("修复导入顺序")
+
+        except Exception:
+            # 如果 ruff 未安装，静默失败
+            pass
+
+    def fix_component_metadata(self, component_file: Path, component_class: str, missing_fields: list[str]) -> bool:
+        """修复组件缺失的元数据字段
+
+        Args:
+            component_file: 组件文件路径
+            component_class: 组件类名
+            missing_fields: 缺失的字段列表
+
+        Returns:
+            是否成功修复
+        """
+        try:
+            content = component_file.read_text(encoding="utf-8")
+            tree = ast.parse(content)
+
+            # 查找组件类
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef) and node.name == component_class:
+                    # 在类定义中添加缺失的字段
+                    indent = "    "  # 4 个空格缩进
+                    fields_to_add = []
+
+                    for field in missing_fields:
+                        # 根据字段类型生成默认值
+                        if field.endswith("_name"):
+                            value = f'"{component_class.lower().replace("_", "-")}"'
+                        elif field.endswith("_description"):
+                            value = f'"{component_class} 组件"'
+                        else:
+                            value = '""'
+
+                        fields_to_add.append(f"{indent}{field}: str = {value}")
+
+                    # 找到类体的第一行（文档字符串后）
+                    lines = content.split('\n')
+                    class_line = None
+                    for i, line in enumerate(lines):
+                        if f"class {component_class}" in line:
+                            class_line = i
+                            break
+
+                    if class_line is not None:
+                        # 找到插入位置（类定义后，第一个方法前）
+                        insert_line = class_line + 1
+
+                        # 跳过文档字符串
+                        if insert_line < len(lines) and '"""' in lines[insert_line]:
+                            while insert_line < len(lines) and not lines[insert_line].strip().endswith('"""'):
+                                insert_line += 1
+                            insert_line += 1
+
+                        # 插入字段
+                        for field_def in fields_to_add:
+                            lines.insert(insert_line, field_def)
+                            insert_line += 1
+
+                        # 写回文件
+                        new_content = '\n'.join(lines)
+                        component_file.write_text(new_content, encoding="utf-8")
+
+                        self.fixes_applied.append(
+                            f"为 {component_class} 添加缺失的元数据字段: {', '.join(missing_fields)}"
+                        )
+                        return True
+
+            return False
+
+        except Exception:
+            return False

mpdt/validators/base.py

@@ -0,0 +1,121 @@
+"""
+验证器基类
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class ValidationLevel(str, Enum):
+    """验证级别"""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class ValidationIssue:
+    """验证问题"""
+
+    level: ValidationLevel
+    message: str
+    file_path: str | None = None
+    line_number: int | None = None
+    suggestion: str | None = None
+
+
+@dataclass
+class ValidationResult:
+    """验证结果"""
+
+    validator_name: str
+    issues: list[ValidationIssue] = field(default_factory=list)
+    success: bool = True
+
+    def add_error(self, message: str, file_path: str | None = None, line_number: int | None = None, suggestion: str | None = None) -> None:
+        """添加错误"""
+        self.issues.append(
+            ValidationIssue(
+                level=ValidationLevel.ERROR,
+                message=message,
+                file_path=file_path,
+                line_number=line_number,
+                suggestion=suggestion,
+            )
+        )
+        self.success = False
+
+    def add_warning(self, message: str, file_path: str | None = None, line_number: int | None = None, suggestion: str | None = None) -> None:
+        """添加警告"""
+        self.issues.append(
+            ValidationIssue(
+                level=ValidationLevel.WARNING,
+                message=message,
+                file_path=file_path,
+                line_number=line_number,
+                suggestion=suggestion,
+            )
+        )
+
+    def add_info(self, message: str, file_path: str | None = None, line_number: int | None = None) -> None:
+        """添加信息"""
+        self.issues.append(
+            ValidationIssue(
+                level=ValidationLevel.INFO,
+                message=message,
+                file_path=file_path,
+                line_number=line_number,
+            )
+        )
+
+    @property
+    def error_count(self) -> int:
+        """错误数量"""
+        return sum(1 for issue in self.issues if issue.level == ValidationLevel.ERROR)
+
+    @property
+    def warning_count(self) -> int:
+        """警告数量"""
+        return sum(1 for issue in self.issues if issue.level == ValidationLevel.WARNING)
+
+    @property
+    def info_count(self) -> int:
+        """信息数量"""
+        return sum(1 for issue in self.issues if issue.level == ValidationLevel.INFO)
+
+
+class BaseValidator(ABC):
+    """验证器基类"""
+
+    def __init__(self, plugin_path: Path):
+        """初始化验证器
+
+        Args:
+            plugin_path: 插件路径
+        """
+        self.plugin_path = plugin_path
+        self.result = ValidationResult(validator_name=self.__class__.__name__)
+
+    @abstractmethod
+    def validate(self) -> ValidationResult:
+        """执行验证
+
+        Returns:
+            ValidationResult: 验证结果
+        """
+        pass
+
+    def _get_plugin_name(self) -> str | None:
+        """获取插件名称（从目录名）
+
+        插件结构: my_plugin/plugin.py
+        """
+        # 检查 plugin.py 是否在根目录
+        if (self.plugin_path / "plugin.py").exists():
+            # 返回插件路径的目录名
+            return self.plugin_path.name
+
+        return None