illusion-code 0.1.0__py3-none-any.whl

illusion/memory/search.py

@@ -0,0 +1,83 @@
+"""
+记忆搜索模块
+===========
+
+本模块提供基于启发式的记忆文件搜索功能。
+
+主要功能：
+    - 支持多语言token提取 (ASCII + 汉字)
+    - 根据元数据和内容相关性评分排序
+
+函数说明：
+    - find_relevant_memories: 查找相关记忆文件
+    - _tokenize: 提取搜索token
+
+使用示例：
+    >>> from illusion.memory import find_relevant_memories
+    >>> results = find_relevant_memories("测试查询", cwd=".", max_results=5)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from illusion.memory.scan import scan_memory_files
+from illusion.memory.types import MemoryHeader
+
+
+def find_relevant_memories(
+    query: str,
+    cwd: str | Path,
+    *,
+    max_results: int = 5,
+) -> list[MemoryHeader]:
+    """查找与查询相关的记忆文件
+    
+    评分权重：元数据匹配 2x，body内容匹配 1x，确保标注良好的记忆优先返回。
+    
+    Args:
+        query: 搜索查询字符串
+        cwd: 当前工作目录
+        max_results: 最大返回结果数量
+    
+    Returns:
+        list[MemoryHeader]: 按相关性排序的记忆文件列表
+    """
+    tokens = _tokenize(query)  # 提取搜索token
+    if not tokens:  # 无有效token则返回空列表
+        return []
+
+    scored: list[tuple[float, MemoryHeader]] = []  # 评分结果列表
+    for header in scan_memory_files(cwd, max_files=100):  # 扫描记忆文件
+        meta = f"{header.title} {header.description}".lower()  # 元数据文本
+        body = header.body_preview.lower()  # 内容预览文本
+
+        # 元数据匹配权重2x，内容匹配权重1x
+        meta_hits = sum(1 for t in tokens if t in meta)  # 元数据命中数
+        body_hits = sum(1 for t in tokens if t in body)  # body命中数
+        score = meta_hits * 2.0 + body_hits  # 计算总分
+        if score > 0:  # 有匹配则加入评分列表
+            scored.append((score, header))
+
+    scored.sort(key=lambda item: (-item[0], -item[1].modified_at))  # 按分数和时间排序
+    return [header for _, header in scored[:max_results]]  # 返回Top N结果
+
+
+def _tokenize(text: str) -> set[str]:
+    """从文本中提取搜索token，同时处理ASCII和汉字
+    
+    - ASCII单词token (3字符及以上)
+    - 汉字单字 (每个汉字独立表示含义)
+    
+    Args:
+        text: 输入文本
+    
+    Returns:
+        set[str]: token集合
+    """
+    # ASCII单词token (3+字符)
+    ascii_tokens = {t for t in re.findall(r"[A-Za-z0-9_]+", text.lower()) if len(t) >= 3}
+    # 汉字字符 (每个字符独立表达含义)
+    han_chars = set(re.findall(r"[\u4e00-\u9fff\u3400-\u4dbf]", text))
+    return ascii_tokens | han_chars  # 返回合并后的token集合

illusion/memory/types.py

@@ -0,0 +1,43 @@
+"""
+记忆数据类型模块
+==============
+
+本模块定义 IllusionCode 记忆系统的数据类型。
+
+主要功能：
+    - 定义记忆文件的元数据结构
+    - 支持 YAML frontmatter 解析
+
+类说明：
+    - MemoryHeader: 记忆文件元数据
+
+使用示例：
+    >>> from illusion.memory import MemoryHeader
+    >>> header = MemoryHeader(path=Path("test.md"), title="Test", description="A test", modified_at=1234567890.0)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class MemoryHeader:
+    """记忆文件的元数据信息
+    
+    Attributes:
+        path: 记忆文件的路径
+        title: 记忆文件标题
+        description: 记忆文件描述
+        modified_at: 最后修改时间戳
+        memory_type: 记忆类型 (可选)
+        body_preview: 内容预览文本 (可选)
+    """
+
+    path: Path  # 记忆文件路径
+    title: str  # 标题
+    description: str  # 描述
+    modified_at: float  # 修改时间戳
+    memory_type: str = ""  # 记忆类型
+    body_preview: str = ""  # 内容预览

illusion/output_styles/__init__.py

@@ -0,0 +1,15 @@
+"""
+输出样式模块导出
+============
+
+本模块导出 output_styles 子目录中的公共接口。
+
+导出内容：
+    - OutputStyle: 输出样式数据类
+    - get_output_styles_dir: 获取自定义输出样式目录
+    - load_output_styles: 加载输出样式
+"""
+
+from illusion.output_styles.loader import OutputStyle, get_output_styles_dir, load_output_styles
+
+__all__ = ["OutputStyle", "get_output_styles_dir", "load_output_styles"]

illusion/output_styles/loader.py

@@ -0,0 +1,64 @@
+"""
+输出样式加载模块
+=============
+
+本模块提供输出样式的加载功能。
+
+主要功能：
+    - 获取自定义输出样式目录
+    - 加载内置和自定义输出样式
+
+类说明：
+    - OutputStyle: 命名输出样式数据类
+    - get_output_styles_dir: 获取自定义输出样式目录
+    - load_output_styles: 加载内置和自定义输出样式
+
+使用示例：
+    >>> from illusion.output_styles import load_output_styles
+    >>> # 加载输出样式
+    >>> styles = load_output_styles()
+    >>> for style in styles:
+    >>>     print(style.name, style.source)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from illusion.config.paths import get_config_dir
+
+
+@dataclass(frozen=True)
+class OutputStyle:
+    """命名输出样式。"""
+
+    name: str
+    content: str
+    source: str
+
+
+def get_output_styles_dir() -> Path:
+    """返回自定义输出样式目录。"""
+    path = get_config_dir() / "output_styles"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def load_output_styles() -> list[OutputStyle]:
+    """加载内置和自定义输出样式。"""
+    # 内置样式
+    styles = [
+        OutputStyle(name="default", content="Standard rich console output.", source="builtin"),
+        OutputStyle(name="minimal", content="Very terse plain-text output.", source="builtin"),
+    ]
+    # 加载自定义样式
+    for path in sorted(get_output_styles_dir().glob("*.md")):
+        styles.append(
+            OutputStyle(
+                name=path.stem,
+                content=path.read_text(encoding="utf-8"),
+                source="user",
+            )
+        )
+    return styles

illusion/permissions/__init__.py

@@ -0,0 +1,39 @@
+"""
+权限模块
+========
+
+本模块提供 IllusionCode 权限检查和管理功能。
+
+主要组件：
+    - PermissionChecker: 权限检查器
+    - PermissionDecision: 权限决策
+    - PermissionMode: 权限模式
+
+使用示例：
+    >>> from illusion.permissions import PermissionChecker, PermissionMode
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from illusion.permissions.checker import PermissionChecker, PermissionDecision
+    from illusion.permissions.modes import PermissionMode
+
+__all__ = ["PermissionChecker", "PermissionDecision", "PermissionMode"]
+
+
+def __getattr__(name: str):
+    if name in {"PermissionChecker", "PermissionDecision"}:
+        from illusion.permissions.checker import PermissionChecker, PermissionDecision
+
+        return {
+            "PermissionChecker": PermissionChecker,
+            "PermissionDecision": PermissionDecision,
+        }[name]
+    if name == "PermissionMode":
+        from illusion.permissions.modes import PermissionMode
+
+        return PermissionMode
+    raise AttributeError(name)

illusion/permissions/checker.py

@@ -0,0 +1,174 @@
+"""
+权限检查模块
+============
+
+本模块实现权限检查功能，用于控制工具执行的权限。
+
+主要功能：
+    - 检查工具是否允许执行
+    - 支持路径级别的权限规则
+    - 支持命令级别的权限规则
+    - 根据权限模式决定是否需要用户确认
+
+类说明：
+    - PermissionDecision: 权限决策结果
+    - PathRule: 路径权限规则
+    - PermissionChecker: 权限检查器
+
+使用示例：
+    >>> from illusion.permissions import PermissionChecker, PermissionDecision, PermissionMode
+    >>> from illusion.config.settings import PermissionSettings
+    >>> checker = PermissionChecker(settings)
+    >>> decision = checker.evaluate("Bash", is_read_only=False, file_path="/path/to/file")
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+from dataclasses import dataclass
+
+from illusion.config.settings import PermissionSettings
+from illusion.permissions.modes import PermissionMode
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PermissionDecision:
+    """权限决策结果
+
+    表示检查工具调用是否允许执行的结果。
+
+    Attributes:
+        allowed: 是否允许执行该工具
+        requires_confirmation: 是否需要用户确认
+        reason: 决策原因说明
+        auto_blocked: 是否为系统自动阻止（如计划模式），而非用户显式拒绝
+    """
+
+    allowed: bool  # 是否允许执行
+    requires_confirmation: bool = False  # 是否需要用户确认
+    reason: str = ""  # 决策原因
+    auto_blocked: bool = False  # 系统自动阻止（计划模式等）
+
+
+@dataclass(frozen=True)
+class PathRule:
+    """基于 glob 模式的路径权限规则
+    
+    用于控制对特定路径的访问权限。
+    
+    Attributes:
+        pattern: glob 模式字符串
+        allow: True 表示允许，False 表示拒绝
+    """
+
+    pattern: str  # glob 模式
+    allow: bool  # True = 允许, False = 拒绝
+
+
+class PermissionChecker:
+    """权限检查器
+    
+    根据配置的权限模式和规则评估工具使用权限。
+    
+    Attributes:
+        _settings: 权限设置对象
+        _path_rules: 解析后的路径规则列表
+    
+    使用示例：
+        >>> checker = PermissionChecker(settings)
+        >>> decision = checker.evaluate("Read", is_read_only=True)
+    """
+
+    def __init__(self, settings: PermissionSettings) -> None:
+        """初始化权限检查器
+        
+        Args:
+            settings: 权限设置对象
+        """
+        self._settings = settings
+        # 从设置中解析路径规则
+        self._path_rules: list[PathRule] = []
+        for rule in getattr(settings, "path_rules", []):
+            pattern = getattr(rule, "pattern", None) or (rule.get("pattern") if isinstance(rule, dict) else None)
+            allow = getattr(rule, "allow", True) if not isinstance(rule, dict) else rule.get("allow", True)
+            if isinstance(pattern, str) and pattern.strip():
+                self._path_rules.append(PathRule(pattern=pattern.strip(), allow=allow))
+            else:
+                log.warning(
+                    "跳过路径规则，pattern 字段缺失为空或非字符串: %r",
+                    rule,
+                )
+
+    def evaluate(
+        self,
+        tool_name: str,
+        *,
+        is_read_only: bool,
+        file_path: str | None = None,
+        command: str | None = None,
+    ) -> PermissionDecision:
+        """评估工具是否允许执行
+        
+        根据权限模式和规则检查工具是否可以立即执行。
+        
+        Args:
+            tool_name: 工具名称
+            is_read_only: 是否为只读工具
+            file_path: 相关的文件路径
+            command: 执行的命令字符串
+        
+        Returns:
+            PermissionDecision: 权限决策结果
+        """
+        # 显式的工具拒绝列表
+        if tool_name in self._settings.denied_tools:
+            return PermissionDecision(allowed=False, reason=f"{tool_name} is explicitly denied")
+
+        # 显式的工具允许列表
+        if tool_name in self._settings.allowed_tools:
+            return PermissionDecision(allowed=True, reason=f"{tool_name} is explicitly allowed")
+
+        # 检查路径级别规则
+        if file_path and self._path_rules:
+            for rule in self._path_rules:
+                if fnmatch.fnmatch(file_path, rule.pattern):
+                    if not rule.allow:
+                        return PermissionDecision(
+                            allowed=False,
+                            reason=f"Path {file_path} matches deny rule: {rule.pattern}",
+                        )
+
+        # 检查命令拒绝模式（例如拒绝 "rm -rf /"）
+        if command:
+            for pattern in getattr(self._settings, "denied_commands", []):
+                if isinstance(pattern, str) and fnmatch.fnmatch(command, pattern):
+                    return PermissionDecision(
+                        allowed=False,
+                        reason=f"Command matches deny pattern: {pattern}",
+                    )
+
+        # 完全自动模式：允许一切
+        if self._settings.mode == PermissionMode.FULL_AUTO:
+            return PermissionDecision(allowed=True, reason="Auto mode allows all tools")
+
+        # 只读工具始终允许
+        if is_read_only:
+            return PermissionDecision(allowed=True, reason="read-only tools are allowed")
+
+        # 计划模式：阻止变更工具（自动阻止，不终止查询循环）
+        if self._settings.mode == PermissionMode.PLAN:
+            return PermissionDecision(
+                allowed=False,
+                reason="Plan mode blocks mutating tools until the user exits plan mode",
+                auto_blocked=True,
+            )
+
+        # 默认模式：变更工具需要确认
+        return PermissionDecision(
+            allowed=False,
+            requires_confirmation=True,
+            reason="Mutating tools require user confirmation in default mode",
+        )

illusion/permissions/modes.py

@@ -0,0 +1,38 @@
+"""
+权限模式定义模块
+================
+
+本模块定义 IllusionCode 支持的权限模式。
+
+主要功能：
+    - DEFAULT 模式：变更工具需要用户确认
+    - PLAN 模式：阻止所有变更工具执行
+    - FULL_AUTO 模式：允许所有工具自动执行
+
+类说明：
+    - PermissionMode: 权限模式枚举
+
+使用示例：
+    >>> from illusion.permissions.modes import PermissionMode
+    >>> mode = PermissionMode.FULL_AUTO
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class PermissionMode(str, Enum):
+    """权限模式枚举
+    
+    定义 Agent 执行工具时的权限级别。
+    
+    Attributes:
+        DEFAULT: 默认模式，变更工具需要用户确认
+        PLAN: 计划模式，阻止所有变更工具
+        FULL_AUTO: 完全自动模式，允许所有工具
+    """
+
+    DEFAULT = "default"  # 默认模式，变更工具需要用户确认
+    PLAN = "plan"  # 计划模式，阻止所有变更工具
+    FULL_AUTO = "full_auto"  # 完全自动模式

illusion/platforms.py

@@ -0,0 +1,148 @@
+"""
+平台和功能检测模块
+=================
+
+本模块提供平台检测和功能能力查询功能。
+
+主要功能：
+    - 检测当前运行平台（macOS、Linux、Windows、WSL）
+    - 查询平台支持的功能特性
+
+类型说明：
+    - PlatformName: 平台名称字面量类型
+    - PlatformCapabilities: 平台功能能力数据类
+
+使用示例：
+    >>> from illusion.platforms import get_platform, get_platform_capabilities
+    >>> platform = get_platform()
+    >>> caps = get_platform_capabilities(platform)
+    >>> print(f"支持 POSIX shell: {caps.supports_posix_shell}")
+"""
+
+from __future__ import annotations
+
+import os  # 操作系统相关功能
+import platform  # 平台信息获取
+from dataclasses import dataclass  # 数据类装饰器
+from functools import lru_cache  # 缓存装饰器
+from typing import Literal, Mapping  # 类型注解
+
+# 平台名称类型定义
+PlatformName = Literal["macos", "linux", "windows", "wsl", "unknown"]
+
+
+@dataclass(frozen=True)
+class PlatformCapabilities:
+    """平台功能能力数据类
+    
+    存储影响 shell、swarm 和沙箱决策的平台功能特性。
+    
+    Attributes:
+        name: 平台名称
+        supports_posix_shell: 是否支持 POSIX shell（bash、zsh 等）
+        supports_native_windows_shell: 是否支持原生 Windows shell（PowerShell、CMD）
+        supports_tmux: 是否支持 tmux 会话管理
+        supports_swarm_mailbox: 是否支持 swarm 邮箱功能
+        supports_sandbox_runtime: 是否支持沙箱运行时
+    """
+
+    name: PlatformName  # 平台名称
+    supports_posix_shell: bool  # 是否支持 POSIX shell
+    supports_native_windows_shell: bool  # 是否支持原生 Windows shell
+    supports_tmux: bool  # 是否支持 tmux
+    supports_swarm_mailbox: bool  # 是否支持 swarm 邮箱
+    supports_sandbox_runtime: bool  # 是否支持沙箱运行时
+
+
+def detect_platform(
+    *,
+    system_name: str | None = None,
+    release: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> PlatformName:
+    """检测并返回标准化平台名称
+    
+    通过检测系统信息判断当前运行平台，支持覆盖参数用于测试。
+    
+    Args:
+        system_name: 系统名称覆盖（可选），默认自动检测
+        release: 内核版本覆盖（可选），默认自动检测
+        env: 环境变量映射（可选），默认使用 os.environ
+    
+    Returns:
+        PlatformName: 标准化后的平台名称（macos、linux、windows、wsl、unknown）
+    """
+    env_map = env or os.environ  # 获取环境变量映射
+    system = (system_name or platform.system()).lower()  # 获取系统名称并转小写
+    kernel_release = (release or platform.release()).lower()  # 获取内核版本并转小写
+
+    # Darwin 系统返回 macOS
+    if system == "darwin":
+        return "macos"
+    # Windows 系统返回 windows
+    if system == "windows":
+        return "windows"
+    # Linux 系统检测 WSL
+    if system == "linux":
+        # 检测 WSL 特征：microsoft 字符串或 WSL 环境变量
+        if "microsoft" in kernel_release or env_map.get("WSL_DISTRO_NAME") or env_map.get("WSL_INTEROP"):
+            return "wsl"
+        return "linux"
+    # 未知平台
+    return "unknown"
+
+
+@lru_cache(maxsize=1)
+def get_platform() -> PlatformName:
+    """返回当前进程的检测平台
+    
+    使用 LRU 缓存优化重复调用性能，缓存大小为 1。
+    
+    Returns:
+        PlatformName: 检测到的平台名称
+    """
+    return detect_platform()  # 调用平台检测函数
+
+
+def get_platform_capabilities(platform_name: PlatformName | None = None) -> PlatformCapabilities:
+    """返回指定平台的功能能力矩阵
+    
+    根据平台名称返回对应的功能能力，包括 shell 支持、tmux 支持等信息。
+    
+    Args:
+        platform_name: 平台名称（可选），默认自动检测当前平台
+    
+    Returns:
+        PlatformCapabilities: 平台功能能力对象
+    """
+    name = platform_name or get_platform()  # 获取平台名称，未指定则自动检测
+    # POSIX 平台（macOS、Linux、WSL）
+    if name in {"macos", "linux", "wsl"}:
+        return PlatformCapabilities(
+            name=name,  # 平台名称
+            supports_posix_shell=True,  # 支持 POSIX shell
+            supports_native_windows_shell=False,  # 不支持原生 Windows shell
+            supports_tmux=True,  # 支持 tmux
+            supports_swarm_mailbox=True,  # 支持 swarm 邮箱
+            supports_sandbox_runtime=True,  # 支持沙箱运行时
+        )
+    # Windows 平台
+    if name == "windows":
+        return PlatformCapabilities(
+            name=name,  # 平台名称
+            supports_posix_shell=False,  # 不支持 POSIX shell
+            supports_native_windows_shell=True,  # 支持原生 Windows shell
+            supports_tmux=False,  # 不支持 tmux
+            supports_swarm_mailbox=False,  # 不支持 swarm 邮箱
+            supports_sandbox_runtime=False,  # 不支持沙箱运行时
+        )
+    # 未知平台
+    return PlatformCapabilities(
+        name=name,  # 平台名称
+        supports_posix_shell=False,  # 不支持 POSIX shell
+        supports_native_windows_shell=False,  # 不支持原生 Windows shell
+        supports_tmux=False,  # 不支持 tmux
+        supports_swarm_mailbox=False,  # 不支持 swarm 邮箱
+        supports_sandbox_runtime=False,  # 不支持沙箱运行时
+    )
+

illusion/plugins/__init__.py

@@ -0,0 +1,71 @@
+"""
+插件模块
+========
+
+本模块提供 IllusionCode 插件系统的加载和管理功能。
+
+主要组件：
+    - PluginManifest: 插件清单
+    - LoadedPlugin: 已加载插件
+    - discover_plugin_paths: 发现插件路径
+    - get_project_plugins_dir: 获取项目插件目录
+    - get_user_plugins_dir: 获取用户插件目录
+    - load_plugins: 加载插件
+    - install_plugin_from_path: 从路径安装插件
+    - uninstall_plugin: 卸载插件
+
+使用示例：
+    >>> from illusion.plugins import load_plugins, get_user_plugins_dir
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from illusion.plugins.schemas import PluginManifest
+    from illusion.plugins.types import LoadedPlugin
+
+__all__ = [
+    "LoadedPlugin",
+    "PluginManifest",
+    "discover_plugin_paths",
+    "get_project_plugins_dir",
+    "get_user_plugins_dir",
+    "install_plugin_from_path",
+    "load_plugins",
+    "uninstall_plugin",
+]
+
+
+def __getattr__(name: str):
+    if name in {"discover_plugin_paths", "get_project_plugins_dir", "get_user_plugins_dir", "load_plugins"}:
+        from illusion.plugins.loader import (
+            discover_plugin_paths,
+            get_project_plugins_dir,
+            get_user_plugins_dir,
+            load_plugins,
+        )
+
+        return {
+            "discover_plugin_paths": discover_plugin_paths,
+            "get_project_plugins_dir": get_project_plugins_dir,
+            "get_user_plugins_dir": get_user_plugins_dir,
+            "load_plugins": load_plugins,
+        }[name]
+    if name in {"install_plugin_from_path", "uninstall_plugin"}:
+        from illusion.plugins.installer import install_plugin_from_path, uninstall_plugin
+
+        return {
+            "install_plugin_from_path": install_plugin_from_path,
+            "uninstall_plugin": uninstall_plugin,
+        }[name]
+    if name == "PluginManifest":
+        from illusion.plugins.schemas import PluginManifest
+
+        return PluginManifest
+    if name == "LoadedPlugin":
+        from illusion.plugins.types import LoadedPlugin
+
+        return LoadedPlugin
+    raise AttributeError(name)