illusion-code 0.1.0__py3-none-any.whl

illusion/tools/file_write_tool.py

@@ -0,0 +1,184 @@
+"""
+文件写入工具
+===========
+
+本模块提供写入完整文件内容到本地文件系统的功能。
+
+主要组件：
+    - FileWriteTool: 写入完整文件内容的工具
+
+使用示例：
+    >>> from illusion.tools import FileWriteTool
+    >>> tool = FileWriteTool()
+"""
+
+from __future__ import annotations
+
+from difflib import unified_diff
+from pathlib import Path
+
+from pydantic import BaseModel, Field, model_validator
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class FileWriteToolInput(BaseModel):
+    """文件写入参数。
+
+    属性：
+        file_path: 要写入的文件路径
+        content: 完整的文件内容
+        create_directories: 是否创建父目录
+
+    兼容旧参数名：path 也可传入，会自动映射。
+    """
+
+    file_path: str = Field(description="Path of the file to write")
+    content: str = Field(description="Full file contents")
+    create_directories: bool = Field(default=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_fields(cls, values: dict) -> dict:
+        """将旧参数名映射到新参数名，确保向后兼容。"""
+        if "path" in values and "file_path" not in values:
+            values["file_path"] = values.pop("path")
+        return values
+
+
+class FileWriteTool(BaseTool):
+    """写入完整的文件内容。
+
+    用于创建新文件或完全重写现有文件。
+    """
+
+    name = "write_file"
+    description = """Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
+"""
+    input_model = FileWriteToolInput
+
+    async def execute(
+        self,
+        arguments: FileWriteToolInput,
+        context: ToolExecutionContext,
+    ) -> ToolResult:
+        """执行文件写入操作，对新文件返回内容预览，对已有文件返回差异信息
+        
+        Args:
+            arguments: 文件写入参数
+            context: 工具执行上下文
+        
+        Returns:
+            ToolResult: 包含写入结果和差异/预览文本的执行结果
+        """
+        # 解析文件路径
+        path = _resolve_path(context.cwd, arguments.file_path)
+
+        # 对于已有文件，执行读后写强制检查
+        if path.exists():
+            from illusion.tools.file_edit_tool import has_file_been_read, mark_file_read
+            if not has_file_been_read(str(path)):
+                return ToolResult(
+                    output=(
+                        f"You must read the file at {path} using the Read tool "
+                        "before you can write to it. This tool will fail if you attempt "
+                        "a write without reading the file first."
+                    ),
+                    is_error=True,
+                )
+
+        # 如果需要，创建父目录
+        if arguments.create_directories:
+            path.parent.mkdir(parents=True, exist_ok=True)
+
+        # 判断是创建还是更新
+        is_update = path.exists()
+
+        # 对于已有文件，读取原始内容以生成diff
+        original = ""
+        if is_update:
+            original = path.read_text(encoding="utf-8")
+
+        # 写入文件内容
+        path.write_text(arguments.content, encoding="utf-8")
+
+        # 写入后将文件标记为已读，以便后续编辑
+        from illusion.tools.file_edit_tool import mark_file_read
+        mark_file_read(str(path))
+
+        # 生成差异或预览
+        if is_update:
+            diff_text = _generate_diff(str(path), original, arguments.content)
+            return ToolResult(output=f"Updated {path}\n{diff_text}")
+        else:
+            preview = _generate_create_preview(str(path), arguments.content)
+            return ToolResult(output=f"Created {path}\n{preview}")
+
+
+def _generate_diff(file_path: str, original: str, updated: str, context_lines: int = 3) -> str:
+    """生成统一差异格式的文本
+
+    Args:
+        file_path: 文件路径
+        original: 原始内容
+        updated: 更新后内容
+        context_lines: 上下文行数
+
+    Returns:
+        str: 差异文本
+    """
+    original_lines = original.splitlines(keepends=True)
+    updated_lines = updated.splitlines(keepends=True)
+    diff_lines = list(unified_diff(
+        original_lines,
+        updated_lines,
+        fromfile=f"a/{file_path}",
+        tofile=f"b/{file_path}",
+        n=context_lines,
+    ))
+    if not diff_lines:
+        return ""
+    return "".join(diff_lines).rstrip()
+
+
+def _generate_create_preview(file_path: str, content: str, max_lines: int = 10) -> str:
+    """生成新文件创建的内容预览
+
+    Args:
+        file_path: 文件路径
+        content: 文件内容
+        max_lines: 最大预览行数
+
+    Returns:
+        str: 预览文本
+    """
+    lines = content.splitlines()
+    total = len(lines)
+    if total <= max_lines:
+        return content
+    preview_lines = lines[:max_lines]
+    remaining = total - max_lines
+    return "\n".join(preview_lines) + f"\n... +{remaining} lines"
+
+
+def _resolve_path(base: Path, candidate: str) -> Path:
+    """解析相对路径为绝对路径。
+
+    参数：
+        base: 基础目录
+        candidate: 候选路径（可能是相对路径）
+
+    返回：
+        解析后的绝对路径
+    """
+    path = Path(candidate).expanduser()
+    if not path.is_absolute():
+        path = base / path
+    return path.resolve()

illusion/tools/glob_tool.py

@@ -0,0 +1,165 @@
+"""
+Glob 工具 - 使用 ripgrep 列出匹配的文件。
+
+核心原则：让 rg 去碰文件系统，Python 只处理结果。
+"""
+
+import logging
+
+from pydantic import BaseModel, Field
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+from illusion.utils.ripgrep import run_rg, RipgrepError
+
+logger = logging.getLogger(__name__)
+
+
+class GlobToolInput(BaseModel):
+    """Glob工具的参数模型
+
+    Attributes:
+        pattern: 相对于工作目录的glob模式
+        root: 可选的搜索根目录
+        limit: 返回结果数量限制
+    """
+
+    pattern: str = Field(description="Glob pattern relative to the working directory")
+    root: str | None = Field(default=None, description="Optional search root")
+    limit: int = Field(default=200, ge=1, le=5000)
+
+
+def split_absolute_glob_pattern(pattern: str) -> tuple[str, str]:
+    """
+    拆分绝对路径 glob 模式为根路径和相对模式。
+
+    Args:
+        pattern: 绝对路径 glob 模式，如 "E:/repo/**/*.py"
+
+    Returns:
+        (根路径, 相对模式) 元组
+    """
+    # 查找第一个通配符
+    wildcard_chars = ["*", "?", "[", "{"]
+    min_idx = len(pattern)
+    for char in wildcard_chars:
+        idx = pattern.find(char)
+        if idx != -1 and idx < min_idx:
+            min_idx = idx
+
+    # 查找最后一个路径分隔符（在通配符之前）
+    last_sep = -1
+    for i in range(min_idx - 1, -1, -1):
+        if pattern[i] in ("/", "\\"):
+            last_sep = i
+            break
+
+    if last_sep == -1:
+        return ".", pattern
+
+    root = pattern[:last_sep]
+    relative = pattern[last_sep + 1:]
+
+    # 处理 Windows 驱动器号
+    if len(root) == 2 and root[1] == ":":
+        root = root + "\\"
+
+    return root, relative
+
+
+class GlobTool(BaseTool):
+    """列出匹配glob模式的文件
+
+    使用说明：
+    - 快速的文件模式匹配工具，适用于任何规模的代码库
+    - 支持glob模式如 "**/*.js" 或 "src/**/*.ts"
+    - 返回按修改时间排序的匹配文件路径
+    - 当需要按名称模式查找文件时使用此工具
+    - 当进行开放性搜索可能需要多轮glob和grep时，使用Agent工具
+    """
+
+    name = "glob"
+    description = """- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths sorted by modification time
+- Use this tool when you need to find files by name patterns
+- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead"""
+    input_model = GlobToolInput
+
+    def is_read_only(self, arguments: GlobToolInput) -> bool:
+        """返回工具是否为只读操作
+
+        Args:
+            arguments: 工具输入参数
+
+        Returns:
+            bool: 始终返回True，glob是只读操作
+        """
+        del arguments
+        return True
+
+    async def execute(self, arguments: GlobToolInput, context: ToolExecutionContext) -> ToolResult:
+        """执行glob搜索
+
+        Args:
+            arguments: 工具输入参数
+            context: 工具执行上下文
+
+        Returns:
+            ToolResult: 搜索结果
+        """
+        pattern = arguments.pattern
+        path = arguments.root
+
+        # 处理绝对路径模式
+        if not path and (":\\" in pattern or pattern.startswith("/")):
+            path, pattern = split_absolute_glob_pattern(pattern)
+        elif not path:
+            path = "."
+
+        # 构建 rg 参数
+        args = ["--files"]
+
+        # 默认包含隐藏文件
+        args.append("--hidden")
+
+        # 默认不尊重 .gitignore
+        args.append("--no-ignore")
+
+        # Glob 模式
+        args.extend(["--glob", pattern])
+
+        # 排除 VCS 目录
+        for vcs in [".git", ".svn", ".hg", ".bzr", ".jj", ".sl"]:
+            args.extend(["--glob", f"!{vcs}"])
+
+        # 搜索路径
+        args.append(path)
+
+        try:
+            stdout, stderr, returncode = await run_rg(args)
+
+            # 退出码 1 表示无匹配
+            if returncode == 1:
+                return ToolResult(output="(no matches)")
+
+            # 其他非零退出码表示错误
+            if returncode != 0:
+                raise RipgrepError(f"rg 执行失败（退出码 {returncode}）: {stderr}")
+
+            # 解析结果
+            lines = stdout.strip().split("\n")
+            if not lines or (len(lines) == 1 and not lines[0]):
+                return ToolResult(output="(no matches)")
+
+            # 限制结果数量
+            limit = arguments.limit
+            if limit and len(lines) > limit:
+                lines = lines[:limit]
+
+            return ToolResult(output="\n".join(lines))
+
+        except RipgrepError:
+            raise
+        except Exception as e:
+            logger.error(f"glob 执行失败: {e}")
+            raise RipgrepError(f"glob 执行失败: {e}")

illusion/tools/grep_tool.py

@@ -0,0 +1,190 @@
+"""
+Grep 工具 - 使用 ripgrep 搜索文件内容。
+
+核心原则：让 rg 去碰文件系统，Python 只处理结果。
+"""
+
+import logging
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+from illusion.utils.ripgrep import run_rg, RipgrepError
+
+logger = logging.getLogger(__name__)
+
+
+class GrepToolInput(BaseModel):
+    """Grep工具的参数模型
+
+    Attributes:
+        pattern: 要搜索的正则表达式
+        path: 要搜索的文件或目录
+        glob: 文件过滤glob（如 "*.js", "**/*.tsx"）
+        output_mode: 输出模式：content显示匹配行，files_with_matches只显示文件路径（默认），count显示匹配计数
+        context_before: 匹配前的行数
+        context_after: 匹配后的行数
+        context: 匹配周围的行数（覆盖-B/-A）
+        case_sensitive: 是否区分大小写
+        type: rg --type 过滤器（如 "js", "py", "rust"）
+        multiline: 启用多行匹配（rg -U --multiline-dotall）
+        head_limit: 最大结果数（0=无限制）
+        offset: 跳过前N个结果
+    """
+
+    pattern: str = Field(description="Regular expression to search for")
+    path: str | None = Field(default=None, description="File or directory to search")
+    glob: str | None = Field(default=None, description='File filter glob (e.g., "*.js", "**/*.tsx")')
+    output_mode: Literal["content", "files_with_matches", "count"] = Field(
+        default="files_with_matches",
+        description="Output mode: content shows matching lines, files_with_matches shows only file paths (default), count shows match counts",
+    )
+    context_before: int | None = Field(default=None, description="Lines before match")
+    context_after: int | None = Field(default=None, description="Lines after match")
+    context: int | None = Field(default=None, description="Lines around match (overrides -B/-A)")
+    case_sensitive: bool = Field(default=True, description="Case sensitive search")
+    type: str | None = Field(default=None, description='rg --type filter (e.g., "js", "py", "rust")')
+    multiline: bool = Field(default=False, description="Enable multiline matching (rg -U --multiline-dotall)")
+    head_limit: int = Field(default=250, ge=0, description="Max results (0 = unlimited)")
+    offset: int = Field(default=0, ge=0, description="Skip first N results")
+
+
+class GrepTool(BaseTool):
+    """搜索文本文件的正则表达式模式
+
+    使用说明：
+    - 始终使用Grep进行搜索任务。永远不要调用Bash命令中的grep或rg。Grep工具已针对正确的权限和访问进行优化
+    - 支持完整正则表达式语法（如 "log.*Error", "function\\s+\\w+"）
+    - 使用glob参数过滤文件（如 "*.js", "**/*.tsx"）或type参数（如 "js", "py", "rust"）
+    - 输出模式："content"显示匹配行，"files_with_matches"只显示文件路径（默认），"count"显示匹配计数
+    - 对于需要多轮搜索的开放性搜索使用Agent工具
+    - 模式语法：使用ripgrep（不是grep）- 字面大括号需要转义（使用 `interface\\{\\}` 在Go代码中查找 `interface{}`）
+    - 多行匹配：默认模式仅在单行内匹配。对于跨行模式如 `struct \\{[\\s\\S]*?field`，使用 `multiline: true`
+    """
+
+    name = "grep"
+    description = """A powerful search tool built on ripgrep
+
+Usage:
+- ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
+- Use Agent tool for open-ended searches requiring multiple rounds
+- Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)
+- Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`"""
+    input_model = GrepToolInput
+
+    def is_read_only(self, arguments: GrepToolInput) -> bool:
+        """返回工具是否为只读操作
+
+        Args:
+            arguments: 工具输入参数
+
+        Returns:
+            bool: 始终返回True，grep是只读操作
+        """
+        del arguments
+        return True
+
+    async def execute(self, arguments: GrepToolInput, context: ToolExecutionContext) -> ToolResult:
+        """执行grep搜索
+
+        Args:
+            arguments: 工具输入参数
+            context: 工具执行上下文
+
+        Returns:
+            ToolResult: 搜索结果
+        """
+        path = arguments.path or "."
+
+        # 构建 rg 参数
+        args = ["--hidden"]
+
+        # 排除 VCS 目录
+        for vcs in [".git", ".svn", ".hg", ".bzr", ".jj", ".sl"]:
+            args.extend(["--glob", f"!{vcs}"])
+
+        # 行长限制
+        args.extend(["--max-columns", "500"])
+
+        # 大小写
+        if not arguments.case_sensitive:
+            args.append("-i")
+
+        # 多行模式
+        if arguments.multiline:
+            args.extend(["-U", "--multiline-dotall"])
+
+        # 输出模式
+        if arguments.output_mode == "files_with_matches":
+            args.append("-l")
+        elif arguments.output_mode == "count":
+            args.append("-c")
+        else:
+            args.append("-n")  # 行号
+
+        # 上下文行
+        context_lines = arguments.context or 0
+        if context_lines:
+            args.extend(["-C", str(context_lines)])
+        else:
+            if arguments.context_before is not None:
+                args.extend(["-B", str(arguments.context_before)])
+            if arguments.context_after is not None:
+                args.extend(["-A", str(arguments.context_after)])
+
+        # 文件类型
+        if arguments.type:
+            args.extend(["--type", arguments.type])
+
+        # Glob 过滤
+        if arguments.glob:
+            # 保持大括号模式如 *.{ts,tsx} 完整
+            parts = arguments.glob.split()
+            for part in parts:
+                args.extend(["--glob", part])
+
+        # 搜索模式（以 - 开头的模式用 -e 前缀）
+        pattern = arguments.pattern
+        if pattern.startswith("-"):
+            args.extend(["-e", pattern])
+        else:
+            args.append(pattern)
+
+        # 搜索路径
+        args.append(path)
+
+        try:
+            stdout, stderr, returncode = await run_rg(args)
+
+            # 退出码 1 表示无匹配
+            if returncode == 1:
+                return ToolResult(output="(no matches)")
+
+            # 其他非零退出码表示错误
+            if returncode != 0:
+                raise RipgrepError(f"rg 执行失败（退出码 {returncode}）: {stderr}")
+
+            # 解析结果
+            lines = stdout.strip().split("\n")
+            if not lines or (len(lines) == 1 and not lines[0]):
+                return ToolResult(output="(no matches)")
+
+            # 应用分页
+            offset = arguments.offset
+            head_limit = arguments.head_limit
+            if offset > 0:
+                lines = lines[offset:]
+            if head_limit > 0 and len(lines) > head_limit:
+                lines = lines[:head_limit]
+
+            return ToolResult(output="\n".join(lines))
+
+        except RipgrepError:
+            raise
+        except Exception as e:
+            logger.error(f"grep 执行失败: {e}")
+            raise RipgrepError(f"grep 执行失败: {e}")

illusion/tools/list_mcp_resources_tool.py

@@ -0,0 +1,80 @@
+"""
+MCP 资源列表工具
+================
+
+本模块提供列出 MCP 资源的功能。
+
+主要组件：
+    - ListMcpResourcesTool: 列出 MCP 服务器上的资源
+
+使用示例：
+    >>> from illusion.tools import ListMcpResourcesTool
+    >>> tool = ListMcpResourcesTool(manager)
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from illusion.mcp.client import McpClientManager
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class ListMcpResourcesToolInput(BaseModel):
+    """MCP 资源列表参数。"""
+
+    server: str | None = Field(
+        default=None,
+        description="Optional MCP server name to filter resources",
+    )
+
+
+class ListMcpResourcesTool(BaseTool):
+    """列出从已连接服务器发现的 MCP 资源。
+
+    用于查看可用的 MCP 服务器资源。
+    """
+
+    name = "list_mcp_resources"
+    description = """List available resources from configured MCP servers.
+Each result line is formatted as "server_name:uri description".
+
+Parameters:
+- server (optional): The name of a specific MCP server to get resources from. If not provided,
+  resources from all servers will be returned. If the specified server is unknown or has no
+  resources, a diagnostic message is returned."""
+    input_model = ListMcpResourcesToolInput
+
+    def __init__(self, manager: McpClientManager) -> None:
+        self._manager = manager
+
+    def is_read_only(self, arguments: ListMcpResourcesToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(self, arguments: ListMcpResourcesToolInput, context: ToolExecutionContext) -> ToolResult:
+        del context
+        server = (arguments.server or "").strip() or None
+        # 获取资源（支持按 server 过滤）
+        resources = self._manager.list_resources(server_name=server)
+        if not resources:
+            statuses_getter = getattr(self._manager, "list_statuses", None)
+            if callable(statuses_getter):
+                statuses = statuses_getter()
+                if server is not None:
+                    status = next((item for item in statuses if item.name == server), None)
+                    if status is None:
+                        return ToolResult(output=f"Unknown MCP server: {server}", is_error=True)
+                    detail = f" ({status.detail})" if status.detail else ""
+                    return ToolResult(
+                        output=f"(no MCP resources on server '{server}', state={status.state}{detail})"
+                    )
+                connected = [item.name for item in statuses if item.state == "connected"]
+                if connected:
+                    return ToolResult(
+                        output=f"(no MCP resources from connected servers: {', '.join(connected)})"
+                    )
+            return ToolResult(output="(no MCP resources)")
+        return ToolResult(
+            output="\n".join(f"{item.server_name}:{item.uri} {item.description}".strip() for item in resources)
+        )