illusion-code 0.1.0__py3-none-any.whl

illusion/plugins/installer.py

@@ -0,0 +1,59 @@
+"""
+插件安装辅助模块
+================
+
+本模块提供插件安装和卸载功能。
+
+主要功能：
+    - 从路径安装插件到用户插件目录
+    - 卸载用户插件
+
+使用示例：
+    >>> from illusion.plugins.installer import install_plugin_from_path, uninstall_plugin
+    >>> install_plugin_from_path("/path/to/plugin")
+    >>> uninstall_plugin("my_plugin")
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from illusion.plugins.loader import get_user_plugins_dir
+
+
+def install_plugin_from_path(source: str | Path) -> Path:
+    """安装插件目录到用户插件目录
+    
+    将源插件目录复制到用户插件目录。
+    
+    Args:
+        source: 插件源目录路径
+    
+    Returns:
+        Path: 安装后的插件目录路径
+    """
+    src = Path(source).resolve()
+    dest = get_user_plugins_dir() / src.name
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest)
+    return dest
+
+
+def uninstall_plugin(name: str) -> bool:
+    """卸载用户插件
+    
+    根据目录名称删除用户插件。
+    
+    Args:
+        name: 插件名称（目录名）
+    
+    Returns:
+        bool: 是否成功卸载
+    """
+    path = get_user_plugins_dir() / name
+    if not path.exists():
+        return False
+    shutil.rmtree(path)
+    return True

illusion/plugins/loader.py

@@ -0,0 +1,301 @@
+"""
+插件发现和加载模块
+==================
+
+本模块实现插件的发现和加载功能。
+
+主要功能：
+    - 发现用户和项目插件目录
+    - 加载插件清单和配置
+    - 解析插件技能、命令、钩子和 MCP 服务器
+
+使用示例：
+    >>> from illusion.plugins.loader import load_plugins, get_user_plugins_dir
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from illusion.config.paths import get_config_dir
+from illusion.plugins.schemas import PluginManifest
+from illusion.plugins.types import LoadedPlugin
+from illusion.skills.loader import _parse_skill_markdown
+from illusion.skills.types import SkillDefinition
+
+logger = logging.getLogger(__name__)
+
+
+def get_user_plugins_dir() -> Path:
+    """获取用户插件目录
+    
+    返回用户级别的插件目录，如果不存在则创建。
+    
+    Returns:
+        Path: 用户插件目录路径
+    """
+    path = get_config_dir() / "plugins"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_project_plugins_dir(cwd: str | Path) -> Path:
+    """获取项目插件目录
+    
+    返回项目级别的插件目录。
+    
+    Args:
+        cwd: 工作目录
+    
+    Returns:
+        Path: 项目插件目录路径
+    """
+    path = Path(cwd).resolve() / ".illusion" / "plugins"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _find_manifest(plugin_dir: Path) -> Path | None:
+    """查找插件清单文件
+    
+    在标准位置或 .claude-plugin/ 目录下查找 plugin.json。
+    
+    Args:
+        plugin_dir: 插件目录
+    
+    Returns:
+        Path | None: 找到的清单文件路径，不存在则返回 None
+    """
+    for candidate in [
+        plugin_dir / "plugin.json",
+        plugin_dir / ".claude-plugin" / "plugin.json",
+    ]:
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def discover_plugin_paths(cwd: str | Path) -> list[Path]:
+    """发现插件目录
+    
+    从用户和项目位置查找所有插件目录。
+    
+    Args:
+        cwd: 工作目录
+    
+    Returns:
+        list[Path]: 插件目录路径列表
+    """
+    roots = [get_user_plugins_dir(), get_project_plugins_dir(cwd)]
+    paths: list[Path] = []
+    for root in roots:
+        if not root.exists():
+            continue
+        for path in sorted(root.iterdir()):
+            if path.is_dir() and _find_manifest(path) is not None:
+                paths.append(path)
+    return paths
+
+
+def load_plugins(settings, cwd: str | Path) -> list[LoadedPlugin]:
+    """从磁盘加载所有插件
+    
+    Args:
+        settings: 设置对象
+        cwd: 工作目录
+    
+    Returns:
+        list[LoadedPlugin]: 已加载的插件列表
+    """
+    plugins: list[LoadedPlugin] = []
+    for path in discover_plugin_paths(cwd):
+        plugin = load_plugin(path, settings.enabled_plugins)
+        if plugin is not None:
+            plugins.append(plugin)
+    return plugins
+
+
+def load_plugin(path: Path, enabled_plugins: dict[str, bool]) -> LoadedPlugin | None:
+    """加载单个插件目录
+    
+    Args:
+        path: 插件目录路径
+        enabled_plugins: 启用的插件配置
+    
+    Returns:
+        LoadedPlugin | None: 已加载的插件，未找到清单则返回 None
+    """
+    manifest_path = _find_manifest(path)
+    if manifest_path is None:
+        return None
+    try:
+        manifest = PluginManifest.model_validate_json(manifest_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        logger.debug("Failed to load plugin manifest from %s: %s", manifest_path, exc)
+        return None
+    enabled = enabled_plugins.get(manifest.name, manifest.enabled_by_default)
+
+    # 从多个位置发现技能
+    skills = _load_plugin_skills(path / manifest.skills_dir)
+
+    # 从 plugin commands/ 目录发现命令
+    commands_dir = path / "commands"
+    if commands_dir.exists():
+        skills.extend(_load_plugin_skills(commands_dir))
+
+    # 从 plugin agents/ 目录发现智能体
+    agents_dir = path / "agents"
+    if agents_dir.exists():
+        skills.extend(_load_plugin_skills(agents_dir))
+
+    # 从 hooks/ 目录或根 hooks.json 发现钩子
+    hooks = _load_plugin_hooks(path / manifest.hooks_file)
+    hooks_dir_file = path / "hooks" / "hooks.json"
+    if not hooks and hooks_dir_file.exists():
+        hooks = _load_plugin_hooks_structured(hooks_dir_file, path)
+
+    mcp = _load_plugin_mcp(path / manifest.mcp_file)
+    mcp_json = path / ".mcp.json"
+    if not mcp and mcp_json.exists():
+        mcp = _load_plugin_mcp(mcp_json)
+
+    return LoadedPlugin(
+        manifest=manifest,
+        path=path,
+        enabled=enabled,
+        skills=skills,
+        hooks=hooks,
+        mcp_servers=mcp,
+        commands=[s for s in skills if s.source == "plugin"],
+    )
+
+
+def _load_plugin_skills(path: Path) -> list[SkillDefinition]:
+    """从目录中的 markdown 和 yaml 文件加载技能定义
+    
+    Args:
+        path: 包含 .md/.yaml/.yml 技能文件的目录
+    
+    Returns:
+        list[SkillDefinition]: 解析后的技能定义列表，如果路径不存在则返回空列表
+    """
+    if not path.exists():
+        return []
+    from illusion.skills.loader import _load_yaml_skill
+
+    skills: list[SkillDefinition] = []
+    for skill_path in sorted(path.iterdir()):
+        if not skill_path.is_file():
+            continue
+        if skill_path.suffix in (".yaml", ".yml"):
+            skill = _load_yaml_skill(skill_path, source="plugin")
+            if skill:
+                skills.append(skill)
+        elif skill_path.suffix == ".md":
+            content = skill_path.read_text(encoding="utf-8")
+            name, description = _parse_skill_markdown(skill_path.stem, content)
+            skills.append(
+                SkillDefinition(
+                    name=name,
+                    description=description,
+                    content=content,
+                    source="plugin",
+                    path=str(skill_path),
+                )
+            )
+    return skills
+
+
+def _load_plugin_hooks(path: Path) -> dict[str, list]:
+    """从平面 hooks.json 文件加载钩子
+    
+    Args:
+        path: hooks JSON 文件路径
+    
+    Returns:
+        dict[str, list]: 事件名称到钩子定义对象列表的字典
+    """
+    if not path.exists():
+        return {}
+    from illusion.hooks.schemas import (
+        AgentHookDefinition,
+        CommandHookDefinition,
+        HttpHookDefinition,
+        PromptHookDefinition,
+    )
+
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    parsed: dict[str, list] = {}
+    for event, hooks in raw.items():
+        parsed[event] = []
+        for hook in hooks:
+            hook_type = hook.get("type")
+            if hook_type == "command":
+                parsed[event].append(CommandHookDefinition.model_validate(hook))
+            elif hook_type == "prompt":
+                parsed[event].append(PromptHookDefinition.model_validate(hook))
+            elif hook_type == "http":
+                parsed[event].append(HttpHookDefinition.model_validate(hook))
+            elif hook_type == "agent":
+                parsed[event].append(AgentHookDefinition.model_validate(hook))
+    return parsed
+
+
+def _load_plugin_hooks_structured(path: Path, plugin_root: Path) -> dict[str, list]:
+    """从结构化 hooks.json 格式加载钩子
+    
+    Args:
+        path: hooks.json 文件路径
+        plugin_root: 插件根目录
+    
+    Returns:
+        dict[str, list]: 解析后的钩子字典
+    """
+    if not path.exists():
+        return {}
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    hooks_data = raw.get("hooks", raw)
+    if not isinstance(hooks_data, dict):
+        return {}
+    parsed: dict[str, list] = {}
+    for event, entries in hooks_data.items():
+        if not isinstance(entries, list):
+            continue
+        parsed[event] = []
+        for entry in entries:
+            hook_list = entry.get("hooks", [])
+            matcher = entry.get("matcher", "")
+            for hook in hook_list:
+                # 将 ${CLAUDE_PLUGIN_ROOT} 替换为实际路径
+                cmd = hook.get("command", "")
+                cmd = cmd.replace("${CLAUDE_PLUGIN_ROOT}", str(plugin_root))
+                parsed[event].append({
+                    "type": hook.get("type", "command"),
+                    "command": cmd,
+                    "matcher": matcher,
+                    "timeout": hook.get("timeout"),
+                })
+    return parsed
+
+
+def _load_plugin_mcp(path: Path) -> dict[str, object]:
+    """从 JSON 文件加载 MCP 服务器配置
+    
+    Args:
+        path: MCP 配置文件路径（例如 .mcp.json）
+    
+    Returns:
+        dict[str, object]: 服务器名称到配置对象的字典
+    """
+    if not path.exists():
+        return {}
+    from illusion.mcp.types import McpJsonConfig
+
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    parsed = McpJsonConfig.model_validate(raw)
+    return parsed.mcpServers

illusion/plugins/schemas.py

@@ -0,0 +1,51 @@
+"""
+插件清单模式模块
+================
+
+本模块定义插件清单的数据模型。
+
+主要组件：
+    - PluginManifest: 插件清单
+
+使用示例：
+    >>> from illusion.plugins.schemas import PluginManifest
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class PluginManifest(BaseModel):
+    """插件清单
+    
+    定义插件的元数据，存储在 plugin.json 或 .claude-plugin/plugin.json 文件中。
+    
+    Attributes:
+        name: 插件名称
+        version: 插件版本
+        description: 插件描述
+        enabled_by_default: 默认是否启用
+        skills_dir: 技能目录名称
+        hooks_file: 钩子文件名
+        mcp_file: MCP 配置文件名
+        author: 作者信息
+        commands: 命令配置
+        agents: 智能体配置
+        skills: 技能配置
+        hooks: 钩子配置
+    """
+
+    name: str  # 插件名称
+    version: str = "0.0.0"  # 插件版本
+    description: str = ""  # 插件描述
+    enabled_by_default: bool = True  # 默认是否启用
+    skills_dir: str = "skills"  # 技能目录名称
+    hooks_file: str = "hooks.json"  # 钩子文件名
+    mcp_file: str = "mcp.json"  # MCP 配置文件名
+    # 扩展字段：可选的 author, commands, agents 等
+    author: dict | None = None  # 作者信息
+    commands: str | list | dict | None = None  # 命令配置
+    agents: str | list | None = None  # 智能体配置
+    skills: str | list | None = None  # 技能配置
+    hooks: str | dict | list | None = None  # 钩子配置

illusion/plugins/types.py

@@ -0,0 +1,56 @@
+"""
+插件运行时类型模块
+==================
+
+本模块定义插件运行时使用的类型。
+
+主要组件：
+    - LoadedPlugin: 已加载的插件
+
+使用示例：
+    >>> from illusion.plugins.types import LoadedPlugin
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from illusion.mcp.types import McpServerConfig
+from illusion.plugins.schemas import PluginManifest
+from illusion.skills.types import SkillDefinition
+
+
+@dataclass(frozen=True)
+class LoadedPlugin:
+    """已加载的插件及其贡献的内容
+    
+    表示一个已加载的插件，包含清单、路径、启用状态、技能、钩子等。
+    
+    Attributes:
+        manifest: 插件清单
+        path: 插件目录路径
+        enabled: 是否启用
+        skills: 技能定义列表
+        hooks: 钩子字典
+        mcp_servers: MCP 服务器配置字典
+        commands: 命令技能列表
+    """
+
+    manifest: PluginManifest  # 插件清单
+    path: Path  # 插件目录路径
+    enabled: bool  # 是否启用
+    skills: list[SkillDefinition] = field(default_factory=list)  # 技能列表
+    hooks: dict[str, list] = field(default_factory=dict)  # 钩子字典
+    mcp_servers: dict[str, McpServerConfig] = field(default_factory=dict)  # MCP 服务器配置
+    commands: list[SkillDefinition] = field(default_factory=list)  # 命令列表
+
+    @property
+    def name(self) -> str:
+        """获取插件名称"""
+        return self.manifest.name
+
+    @property
+    def description(self) -> str:
+        """获取插件描述"""
+        return self.manifest.description

illusion/prompts/__init__.py

@@ -0,0 +1,29 @@
+"""
+提示词模块
+==========
+
+本模块提供 IllusionCode 系统提示词构建功能。
+
+主要组件：
+    - build_system_prompt: 构建系统提示词
+    - build_runtime_system_prompt: 构建运行时系统提示词
+    - discover_claude_md_files: 发现 Claude.md 文件
+    - load_claude_md_prompt: 加载 Claude.md 提示词
+    - get_environment_info: 获取环境信息
+
+使用示例：
+    >>> from illusion.prompts import build_system_prompt, get_environment_info
+"""
+
+from illusion.prompts.claudemd import discover_claude_md_files, load_claude_md_prompt
+from illusion.prompts.context import build_runtime_system_prompt
+from illusion.prompts.system_prompt import build_system_prompt
+from illusion.prompts.environment import get_environment_info
+
+__all__ = [
+    "build_runtime_system_prompt",
+    "build_system_prompt",
+    "discover_claude_md_files",
+    "get_environment_info",
+    "load_claude_md_prompt",
+]

illusion/prompts/claudemd.py

@@ -0,0 +1,74 @@
+"""
+CLAUDE.md 发现和加载模块
+========================
+
+本模块实现 CLAUDE.md 指令文件的发现和加载功能。
+
+主要功能：
+    - 在当前目录中查找 CLAUDE.md 文件
+    - 发现 .claude/rules 目录下的规则文件
+    - 将多个指令文件加载为一个提示词章节
+
+使用示例：
+    >>> from illusion.prompts.claudemd import discover_claude_md_files, load_claude_md_prompt
+    >>> files = discover_claude_md_files("/path/to/project")
+    >>> prompt = load_claude_md_prompt("/path/to/project")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def discover_claude_md_files(cwd: str | Path) -> list[Path]:
+    """发现相关的 CLAUDE.md 指令文件（只在 cwd 中查找）
+
+    Args:
+        cwd: 工作目录
+
+    Returns:
+        list[Path]: 找到的指令文件路径列表
+    """
+    current = Path(cwd).resolve()
+    results: list[Path] = []
+    seen: set[Path] = set()
+
+    for candidate in (
+        current / "CLAUDE.md",
+        current / ".claude" / "CLAUDE.md",
+    ):
+        if candidate.exists() and candidate not in seen:
+            results.append(candidate)
+            seen.add(candidate)
+
+    rules_dir = current / ".claude" / "rules"
+    if rules_dir.is_dir():
+        for rule in sorted(rules_dir.glob("*.md")):
+            if rule not in seen:
+                results.append(rule)
+                seen.add(rule)
+
+    return results
+
+
+def load_claude_md_prompt(cwd: str | Path, *, max_chars_per_file: int = 12000) -> str | None:
+    """将发现的指令文件加载为一个提示词章节
+    
+    Args:
+        cwd: 工作目录
+        max_chars_per_file: 每个文件的最大字符数
+    
+    Returns:
+        str | None: 格式化的提示词章节，如果没有文件则返回 None
+    """
+    files = discover_claude_md_files(cwd)
+    if not files:
+        return None
+
+    lines = ["# Project Instructions"]
+    for path in files:
+        content = path.read_text(encoding="utf-8", errors="replace")
+        if len(content) > max_chars_per_file:
+            content = content[:max_chars_per_file] + "\n...[truncated]..."
+        lines.extend(["", f"## {path}", "```md", content.strip(), "```"])
+    return "\n".join(lines)