illusion-code 0.1.0__py3-none-any.whl

illusion/mcp/config.py

@@ -0,0 +1,140 @@
+"""
+MCP 服务器配置加载模块
+=====================
+
+本模块提供从设置、插件和项目目录加载 MCP 服务器配置的功能。
+
+主要功能：
+    - 从全局设置中加载 MCP 服务器配置
+    - 从已加载的插件中合并 MCP 服务器配置
+    - 从项目级配置目录加载 MCP 服务器配置
+    - 插件配置优先级高于全局设置（同名配置）
+
+函数说明：
+    - load_mcp_server_configs: 加载并合并 MCP 服务器配置
+    - load_project_mcp_configs: 从项目目录加载 MCP 配置
+
+使用示例：
+    >>> from illusion.mcp.config import load_mcp_server_configs
+    >>> configs = load_mcp_server_configs(settings, plugins, cwd="/path/to/project")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from illusion.plugins.types import LoadedPlugin
+
+logger = logging.getLogger(__name__)
+
+
+def load_project_mcp_configs(cwd: str | Path) -> dict[str, object]:
+    """
+    从项目目录加载 MCP 服务器配置
+
+    扫描 <project>/.illusion/mcp/ 目录下的所有 JSON 文件，
+    每个文件可以包含一个或多个 MCP 服务器配置。
+
+    文件格式支持：
+    1. 单个服务器配置（文件名作为服务器名）：
+       {"type": "stdio", "command": "python", "args": ["server.py"]}
+
+    2. 多个服务器配置（使用 mcpServers 键）：
+       {"mcpServers": {"server1": {...}, "server2": {...}}}
+
+    Args:
+        cwd: 当前工作目录
+
+    Returns:
+        dict[str, object]: 服务器名称到配置的映射字典
+    """
+    from pydantic import TypeAdapter
+
+    from illusion.config.paths import get_project_mcp_dir
+    from illusion.mcp.types import McpJsonConfig, McpServerConfig
+
+    _server_adapter = TypeAdapter(McpServerConfig)
+    servers: dict[str, object] = {}
+    mcp_dir = get_project_mcp_dir(cwd)
+
+    if not mcp_dir.exists():
+        return servers
+
+    for json_file in sorted(mcp_dir.glob("*.json")):
+        try:
+            raw = json.loads(json_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("Failed to read MCP config %s: %s", json_file, exc)
+            continue
+
+        # 兼容 mcp_servers（snake_case）键
+        if "mcp_servers" in raw and "mcpServers" not in raw:
+            raw["mcpServers"] = raw.pop("mcp_servers")
+
+        # 尝试解析为多服务器格式（mcpServers 键）
+        if "mcpServers" in raw:
+            try:
+                parsed = McpJsonConfig.model_validate(raw)
+                for name, config in parsed.mcpServers.items():
+                    if getattr(config, "enabled", True):
+                        servers[name] = config
+            except Exception as exc:
+                logger.warning("Failed to parse MCP config %s: %s", json_file, exc)
+            continue
+
+        # 尝试解析为单服务器格式（文件名作为服务器名）
+        try:
+            config = _server_adapter.validate_python(raw)
+            if getattr(config, "enabled", True):
+                server_name = json_file.stem
+                servers[server_name] = config
+        except Exception as exc:
+            logger.warning("Failed to parse MCP config %s: %s", json_file, exc)
+
+    return servers
+
+
+def load_mcp_server_configs(settings, plugins: list[LoadedPlugin], cwd: str | Path | None = None) -> dict[str, object]:
+    """
+    加载 MCP 服务器配置
+
+    从全局设置、项目目录和已加载的插件中合并 MCP 服务器配置。
+    优先级（从高到低）：插件 > 项目级 > 全局设置
+
+    Args:
+        settings: 全局设置对象，包含 mcp_servers 属性
+        plugins: 已加载的插件列表，每个插件包含 mcp_servers 属性
+        cwd: 当前工作目录，用于加载项目级配置
+
+    Returns:
+        dict[str, object]: 服务器名称到配置的映射字典
+                         键的格式为 "插件名:服务器名"（来自插件）或仅"服务器名"（来自其他来源）
+
+    使用示例：
+        >>> configs = load_mcp_server_configs(settings, plugins, cwd="/path/to/project")
+        >>> for name, config in configs.items():
+        ...     print(f"{name}: {config}")
+    """
+    # 从全局设置中获取 MCP 服务器配置（跳过已禁用的服务器）
+    servers = {name: cfg for name, cfg in settings.mcp_servers.items()
+               if getattr(cfg, "enabled", True)}
+
+    # 从项目目录加载 MCP 配置（覆盖全局设置）
+    if cwd is not None:
+        project_configs = load_project_mcp_configs(cwd)
+        servers.update(project_configs)
+
+    # 遍历所有已加载的插件
+    for plugin in plugins:
+        # 跳过未启用的插件
+        if not plugin.enabled:
+            continue
+        # 将插件的 MCP 服务器配置合并到结果中（跳过已禁用的服务器）
+        for name, config in plugin.mcp_servers.items():
+            if not getattr(config, "enabled", True):
+                continue
+            # 使用 "插件名:服务器名" 格式作为键，避免与全局设置冲突
+            servers.setdefault(f"{plugin.manifest.name}:{name}", config)
+    return servers

illusion/mcp/types.py

@@ -0,0 +1,175 @@
+"""
+MCP 配置和状态模型
+==================
+
+本模块定义 MCP（Model Context Protocol）相关的配置和数据类型。
+
+主要功能：
+    - 定义 MCP 服务器配置（STDIO、HTTP、WebSocket）
+    - 定义 MCP 工具和资源信息
+    - 定义 MCP 连接状态
+
+类说明：
+    - McpStdioServerConfig: STDIO 类型 MCP 服务器配置
+    - McpHttpServerConfig: HTTP 类型 MCP 服务器配置
+    - McpWebSocketServerConfig: WebSocket 类型 MCP 服务器配置
+    - McpServerConfig: MCP 服务器配置联合类型
+    - McpJsonConfig: 配置文件格式（用于插件和项目文件）
+    - McpToolInfo: MCP 工具元数据
+    - McpResourceInfo: MCP 资源元数据
+    - McpConnectionStatus: MCP 服务器运行时状态
+
+使用示例：
+    >>> from illusion.mcp.types import McpStdioServerConfig
+    >>> config = McpStdioServerConfig(command="node", args=["server.js"])
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class McpStdioServerConfig(BaseModel):
+    """
+    STDIO 类型 MCP 服务器配置
+    
+    通过标准输入输出流与 MCP 服务器通信的配置。
+    
+    Attributes:
+        type: 服务器类型，固定为 "stdio"
+        command: 要执行的命令
+        args: 命令参数列表
+        env: 环境变量字典
+        cwd: 工作目录
+        log_file: stderr 日志重定向文件路径，设置后 MCP 服务器的 stderr 输出将写入该文件
+    """
+
+    type: Literal["stdio"] = "stdio"
+    command: str
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, str] | None = None
+    cwd: str | None = None
+    log_file: str | None = None
+    enabled: bool = True
+
+
+class McpHttpServerConfig(BaseModel):
+    """
+    HTTP 类型 MCP 服务器配置
+    
+    通过 HTTP 协议与 MCP 服务器通信的配置。
+    
+    Attributes:
+        type: 服务器类型，固定为 "http"
+        url: 服务器 URL 地址
+        headers: HTTP 请求头字典
+    """
+
+    type: Literal["http"] = "http"
+    url: str
+    headers: dict[str, str] = Field(default_factory=dict)
+    enabled: bool = True
+
+
+class McpWebSocketServerConfig(BaseModel):
+    """
+    WebSocket 类型 MCP 服务器配置
+    
+    通过 WebSocket 协议与 MCP 服务器通信的配置。
+    
+    Attributes:
+        type: 服务器类型，固定为 "ws"
+        url: 服务器 WebSocket URL 地址
+        headers: WebSocket 连接请求头字典
+    """
+
+    type: Literal["ws"] = "ws"
+    url: str
+    headers: dict[str, str] = Field(default_factory=dict)
+    enabled: bool = True
+
+
+# MCP 服务器配置联合类型，支持 STDIO、HTTP、WebSocket 三种传输方式
+McpServerConfig = McpStdioServerConfig | McpHttpServerConfig | McpWebSocketServerConfig
+
+
+class McpJsonConfig(BaseModel):
+    """
+    MCP 配置文件格式
+    
+    用于插件和项目文件中的 MCP 服务器配置格式。
+    
+    Attributes:
+        mcp_servers: MCP 服务器名称到配置的映射字典
+    """
+
+    mcpServers: dict[str, McpServerConfig] = Field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class McpToolInfo:
+    """
+    MCP 工具信息
+    
+    MCP 服务器暴露的工具元数据，包含工具名称、描述和输入模式。
+    
+    Attributes:
+        server_name: 所属服务器名称
+        name: 工具名称
+        description: 工具描述
+        input_schema: 工具输入参数的 JSON Schema 定义
+    """
+
+    server_name: str
+    name: str
+    description: str
+    input_schema: dict[str, object]
+
+
+@dataclass(frozen=True)
+class McpResourceInfo:
+    """
+    MCP 资源信息
+    
+    MCP 服务器暴露的资源元数据，包含资源名称、URI 和描述。
+    
+    Attributes:
+        server_name: 所属服务器名称
+        name: 资源名称
+        uri: 资源统一标识符
+        description: 资源描述
+    """
+
+    server_name: str
+    name: str
+    uri: str
+    description: str = ""
+
+
+@dataclass
+class McpConnectionStatus:
+    """
+    MCP 连接状态
+    
+    MCP 服务器的运行时状态信息，包含连接状态、传输类型、认证配置、工具和资源列表。
+    
+    Attributes:
+        name: 服务器名称
+        state: 连接状态（connected/failed/pending/disabled）
+        detail: 状态详情或错误信息
+        transport: 传输类型（stdio/http/ws）
+        auth_configured: 是否配置了认证
+        tools: 该服务器提供的工具列表
+        resources: 该服务器提供的资源列表
+    """
+
+    name: str
+    state: Literal["connected", "failed", "pending", "disabled"]
+    detail: str = ""
+    transport: str = "unknown"
+    auth_configured: bool = False
+    tools: list[McpToolInfo] = field(default_factory=list)
+    resources: list[McpResourceInfo] = field(default_factory=list)

illusion/memory/__init__.py

@@ -0,0 +1,36 @@
+"""
+记忆模块
+========
+
+本模块提供 IllusionCode 记忆/上下文管理功能。
+
+主要组件：
+    - add_memory_entry: 添加记忆条目
+    - find_relevant_memories: 查找相关记忆
+    - get_memory_entrypoint: 获取记忆入口点
+    - get_project_memory_dir: 获取项目记忆目录
+    - list_memory_files: 列出记忆文件
+    - load_memory_prompt: 加载记忆提示词
+    - remove_memory_entry: 移除记忆条目
+    - scan_memory_files: 扫描记忆文件
+
+使用示例：
+    >>> from illusion.memory import add_memory_entry, find_relevant_memories
+"""
+
+from illusion.memory.memdir import load_memory_prompt
+from illusion.memory.manager import add_memory_entry, list_memory_files, remove_memory_entry
+from illusion.memory.paths import get_memory_entrypoint, get_project_memory_dir
+from illusion.memory.scan import scan_memory_files
+from illusion.memory.search import find_relevant_memories
+
+__all__ = [
+    "add_memory_entry",
+    "find_relevant_memories",
+    "get_memory_entrypoint",
+    "get_project_memory_dir",
+    "list_memory_files",
+    "load_memory_prompt",
+    "remove_memory_entry",
+    "scan_memory_files",
+]

illusion/memory/manager.py

@@ -0,0 +1,94 @@
+"""
+记忆管理模块
+==========
+
+本模块提供记忆文件的管理操作功能。
+
+主要功能：
+    - 列出项目记忆文件
+    - 添加/移除记忆条目
+
+函数说明：
+    - list_memory_files: 列出记忆文件
+    - add_memory_entry: 添加记忆条目
+    - remove_memory_entry: 移除记忆条目
+
+使用示例：
+    >>> from illusion.memory import list_memory_files, add_memory_entry, remove_memory_entry
+    >>> files = list_memory_files(".")
+    >>> path = add_memory_entry(".", "Test", "# Test memory content")
+    >>> remove_memory_entry(".", "test")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from re import sub
+
+from illusion.memory.paths import get_memory_entrypoint, get_project_memory_dir
+
+
+def list_memory_files(cwd: str | Path) -> list[Path]:
+    """列出项目的所有记忆markdown文件
+    
+    Args:
+        cwd: 当前工作目录
+    
+    Returns:
+        list[Path]: 排序后的记忆文件路径列表
+    """
+    memory_dir = get_project_memory_dir(cwd)  # 获取记忆目录
+    return sorted(path for path in memory_dir.glob("*.md"))  # 返回排序后的文件列表
+
+
+def add_memory_entry(cwd: str | Path, title: str, content: str) -> Path:
+    """创建记忆文件并添加到MEMORY.md索引
+    
+    Args:
+        cwd: 当前工作目录
+        title: 记忆标题
+        content: 记忆内容
+    
+    Returns:
+        Path: 创建的记忆文件路径
+    """
+    memory_dir = get_project_memory_dir(cwd)  # 获取记忆目录
+    slug = sub(r"[^a-zA-Z0-9]+", "_", title.strip().lower()).strip("_") or "memory"  # 转换为slug
+    path = memory_dir / f"{slug}.md"  # 构建文件路径
+    path.write_text(content.strip() + "\n", encoding="utf-8")  # 写入内容
+
+    entrypoint = get_memory_entrypoint(cwd)  # 获取入口点
+    existing = entrypoint.read_text(encoding="utf-8") if entrypoint.exists() else "# Memory Index\n"  # 读取现有内容
+    if path.name not in existing:  # 如果不存在
+        existing = existing.rstrip() + f"\n- [{title}]({path.name})\n"  # 添加索引条目
+        entrypoint.write_text(existing, encoding="utf-8")  # 写入索引
+    return path  # 返回创建的文件路径
+
+
+def remove_memory_entry(cwd: str | Path, name: str) -> bool:
+    """删除记忆文件及其在MEMORY.md中的索引条目
+    
+    Args:
+        cwd: 当前工作目录
+        name: 记忆文件名称 (不带.md扩展名)
+    
+    Returns:
+        bool: 是否成功删除
+    """
+    memory_dir = get_project_memory_dir(cwd)  # 获取记忆目录
+    matches = [path for path in memory_dir.glob("*.md") if path.stem == name or path.name == name]  # 查找匹配文件
+    if not matches:  # 没有匹配
+        return False
+    path = matches[0]  # 取第一个匹配
+    if path.exists():  # 文件存在
+        path.unlink()  # 删除文件
+
+    entrypoint = get_memory_entrypoint(cwd)  # 获取入口点
+    if entrypoint.exists():  # 入口点存在
+        lines = [
+            line  # 保留的行
+            for line in entrypoint.read_text(encoding="utf-8").splitlines()
+            if path.name not in line  # 排除包含删除文件名的行
+        ]
+        entrypoint.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")  # 重写入口点
+    return True  # 返回成功

illusion/memory/memdir.py

@@ -0,0 +1,58 @@
+"""
+记忆提示词模块
+=============
+
+本模块提供记忆相关的提示词构建功能。
+
+主要功能：
+    - 加载项目记忆提示词段落
+    - 格式化记忆目录信息
+
+函数说明：
+    - load_memory_prompt: 加载记忆提示词
+
+使用示例：
+    >>> from illusion.memory import load_memory_prompt
+    >>> prompt = load_memory_prompt(".", max_entrypoint_lines=200)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from illusion.memory.paths import get_memory_entrypoint, get_project_memory_dir
+
+
+def load_memory_prompt(cwd: str | Path, *, max_entrypoint_lines: int = 200) -> str | None:
+    """构建当前项目的记忆提示词段落
+    
+    Args:
+        cwd: 当前工作目录
+        max_entrypoint_lines: 入口点文件最大行数
+    
+    Returns:
+        str | None: 格式化后的记忆提示词，如果失败返回None
+    """
+    memory_dir = get_project_memory_dir(cwd)  # 获取记忆目录
+    entrypoint = get_memory_entrypoint(cwd)  # 获取入口点文件
+    lines = [
+        "# Memory",  # 标题
+        f"- Persistent memory directory: {memory_dir}",  # 记忆目录
+        "- Use this directory to store durable user or project context that should survive future sessions.",  # 说明1
+        "- Prefer concise topic files plus an index entry in MEMORY.md.",  # 说明2
+    ]
+
+    if entrypoint.exists():  # 入口点文件存在
+        content_lines = entrypoint.read_text(encoding="utf-8").splitlines()[:max_entrypoint_lines]  # 读取内容
+        if content_lines:  # 有内容
+            lines.extend(["", "## MEMORY.md", "```md", *content_lines, "```"])  # 添加到提示词
+    else:  # 入口点不存在
+        lines.extend(
+            [
+                "",  # 空行
+                "## MEMORY.md",  # 标题
+                "(not created yet)",  # 提示未创建
+            ]
+        )
+
+    return "\n".join(lines)  # 返回合并后的字符串

illusion/memory/paths.py

@@ -0,0 +1,57 @@
+"""
+记忆路径模块
+==========
+
+本模块提供持久化项目记忆的路径管理功能。
+
+主要功能：
+    - 生成基于项目路径的唯一记忆目录
+    - 管理MEMORY.md入口点文件
+
+函数说明：
+    - get_project_memory_dir: 获取项目记忆目录
+    - get_memory_entrypoint: 获取记忆入口点文件
+
+使用示例：
+    >>> from illusion.memory import get_project_memory_dir, get_memory_entrypoint
+    >>> mem_dir = get_project_memory_dir(".")
+    >>> entrypoint = get_memory_entrypoint(".")
+"""
+
+from __future__ import annotations
+
+from hashlib import sha1
+from pathlib import Path
+
+from illusion.config.paths import get_data_dir
+
+
+def get_project_memory_dir(cwd: str | Path) -> Path:
+    """获取项目持久化记忆目录
+    
+    目录名格式: {项目名}-{sha1哈希前12位}
+    使用项目路径的哈希确保唯一性
+    
+    Args:
+        cwd: 当前工作目录
+    
+    Returns:
+        Path: 记忆目录的Path对象
+    """
+    path = Path(cwd).resolve()  # 解析为绝对路径
+    digest = sha1(str(path).encode("utf-8")).hexdigest()[:12]  # 计算哈希
+    memory_dir = get_data_dir() / "memory" / f"{path.name}-{digest}"  # 构建目录路径
+    memory_dir.mkdir(parents=True, exist_ok=True)  # 创建目录
+    return memory_dir  # 返回目录
+
+
+def get_memory_entrypoint(cwd: str | Path) -> Path:
+    """获取项目记忆入口点文件
+    
+    Args:
+        cwd: 当前工作目录
+    
+    Returns:
+        Path: MEMORY.md文件的Path对象
+    """
+    return get_project_memory_dir(cwd) / "MEMORY.md"  # 返回入口点文件路径

illusion/memory/scan.py

@@ -0,0 +1,120 @@
+"""
+记忆文件扫描模块
+================
+
+本模块提供记忆文件的扫描和解析功能。
+
+主要功能：
+    - 扫描项目中的记忆Markdown文件
+    - 解析YAML frontmatter提取元数据
+    - 按修改时间排序返回记忆列表
+
+函数说明：
+    - scan_memory_files: 扫描记忆文件
+    - _parse_memory_file: 解析单个记忆文件
+
+使用示例：
+    >>> from illusion.memory import scan_memory_files
+    >>> headers = scan_memory_files(".", max_files=50)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from illusion.memory.paths import get_project_memory_dir
+from illusion.memory.types import MemoryHeader
+
+
+def scan_memory_files(cwd: str | Path, *, max_files: int = 50) -> list[MemoryHeader]:
+    """扫描并返回记忆文件头，按最新修改时间排序
+    
+    Args:
+        cwd: 当前工作目录
+        max_files: 最大返回文件数量
+    
+    Returns:
+        list[MemoryHeader]: 按修改时间倒序排列的记忆头列表
+    """
+    memory_dir = get_project_memory_dir(cwd)  # 获取记忆目录
+    headers: list[MemoryHeader] = []  # 初始化头列表
+    for path in memory_dir.glob("*.md"):  # 遍历所有md文件
+        if path.name == "MEMORY.md":  # 跳过索引文件
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")  # 读取文件内容
+        except OSError:  # 读取失败则跳过
+            continue
+        header = _parse_memory_file(path, text)  # 解析文件
+        headers.append(header)  # 添加到列表
+    headers.sort(key=lambda item: item.modified_at, reverse=True)  # 按时间倒序排序
+    return headers[:max_files]  # 返回Top N结果
+
+
+def _parse_memory_file(path: Path, content: str) -> MemoryHeader:
+    """解析记忆文件，提取YAML frontmatter中的元数据
+    
+    支持从frontmatter提取: name, description, type
+    如果没有frontmatter，使用第一行非空非标题行作为description
+    
+    Args:
+        path: 文件路径
+        content: 文件内容
+    
+    Returns:
+        MemoryHeader: 解析后的记忆头
+    """
+    lines = content.splitlines()  # 分割行
+    title = path.stem  # 默认使用文件名作为标题
+    description = ""  # 描述
+    memory_type = ""  # 记忆类型
+    body_start = 0  # 内容起始行索引
+
+    # 解析YAML frontmatter (--- ... ---)
+    if lines and lines[0].strip() == "---":  # 检查是否有frontmatter
+        for i, line in enumerate(lines[1:], 1):  # 遍历内容行
+            if line.strip() == "---":  # 找到结束标记
+                for fm_line in lines[1:i]:  # 解析frontmatter
+                    key, _, value = fm_line.partition(":")  # 分割键值对
+                    key = key.strip()  # 清理键
+                    value = value.strip().strip("'\"")  # 清理值
+                    if not value:  # 跳过空值
+                        continue
+                    if key == "name":  # 名称字段
+                        title = value
+                    elif key == "description":  # 描述字段
+                        description = value
+                    elif key == "type":  # 类型字段
+                        memory_type = value
+                body_start = i + 1  # 内容从结束标记后开始
+                break
+
+    # 后备方案：第一行非空非frontmatter非标题行作为描述
+    desc_line_idx: int | None = None  # 描述行索引
+    if not description:  # 如果没有描述
+        for idx, line in enumerate(lines[body_start:body_start + 10], body_start):  # 遍历前10���
+            stripped = line.strip()  # 去除空白
+            if stripped and stripped != "---" and not stripped.startswith("#"):  # 非空非标记非标题
+                description = stripped[:200]  # 截取前200字符
+                desc_line_idx = idx  # 记录行索引
+                break
+
+    # 从frontmatter之后的内容构建body preview
+    # 排除已用作description的行以保持搜索评分一致性
+    body_lines = [
+        line.strip()  # 去除空白
+        for idx, line in enumerate(lines[body_start:], body_start)
+        if line.strip()  # 非空行
+        and not line.strip().startswith("#")  # 非标题行
+        and idx != desc_line_idx  # 排除描述行
+    ]
+    body_preview = " ".join(body_lines)[:300]  # 合并并截断
+
+    return MemoryHeader(
+        path=path,  # 文件路径
+        title=title,  # 标题
+        description=description,  # 描述
+        modified_at=path.stat().st_mtime,  # 修改时间
+        memory_type=memory_type,  # 记忆类型
+        body_preview=body_preview,  # 内容预览
+    )