illusion-code 0.1.0__py3-none-any.whl

illusion/tools/file_edit_tool.py

@@ -0,0 +1,283 @@
+"""
+字符串替换文件编辑工具
+======================
+
+本模块提供在现有文件中进行精确字符串替换的功能。
+
+主要组件：
+    - FileEditTool: 替换文件中文本的工具
+
+使用示例：
+    >>> from illusion.tools import FileEditTool
+    >>> tool = FileEditTool()
+"""
+
+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
+
+
+# 模块级集合，跟踪本次会话中已读取的文件
+# FileReadTool 写入此集合；FileEditTool 从中读取
+_read_files: set[str] = set()
+
+
+def mark_file_read(abs_path: str) -> None:
+    """记录文件已被读取（在 FileReadTool 读取后调用）。"""
+    _read_files.add(abs_path)
+
+
+def has_file_been_read(abs_path: str) -> bool:
+    """检查文件是否在本次会话中已被读取。"""
+    return abs_path in _read_files
+
+
+class FileEditToolInput(BaseModel):
+    """文件编辑参数。
+
+    属性：
+        file_path: 要编辑的文件路径
+        old_string: 要替换的现有文本
+        new_string: 替换文本
+        replace_all: 是否替换所有匹配项
+
+    兼容旧参数名：path, old_str, new_str 均可传入，会自动映射。
+    """
+
+    file_path: str = Field(description="Path of the file to edit")
+    old_string: str = Field(description="Existing text to replace")
+    new_string: str = Field(description="Replacement text")
+    replace_all: bool = Field(default=False)
+
+    @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")
+        if "old_str" in values and "old_string" not in values:
+            values["old_string"] = values.pop("old_str")
+        if "new_str" in values and "new_string" not in values:
+            values["new_string"] = values.pop("new_str")
+        return values
+
+
+class FileEditTool(BaseTool):
+    """替换现有文件中的文本。
+
+    用于对文件进行精确的字符串替换编辑。
+    """
+
+    name = "edit_file"
+    description = """Performs exact string replacements in files.
+
+Usage:
+- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + arrow. Everything after that arrow is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
+- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+- Use the smallest old_string that's clearly unique — usually 2-4 adjacent lines is sufficient. Avoid including 10+ lines of context when less uniquely identifies the target."""
+    input_model = FileEditToolInput
+
+    async def execute(
+        self,
+        arguments: FileEditToolInput,
+        context: ToolExecutionContext,
+    ) -> ToolResult:
+        """执行文件编辑操作，替换指定文本并返回差异信息
+        
+        Args:
+            arguments: 文件编辑参数
+            context: 工具执行上下文
+        
+        Returns:
+            ToolResult: 包含编辑结果和差异文本的执行结果
+        """
+        # 解析文件路径
+        path = _resolve_path(context.cwd, arguments.file_path)
+
+        # 拒绝 notebook 文件 — 模型应使用 NotebookEdit
+        if path.suffix.lower() == ".ipynb":
+            return ToolResult(
+                output=".ipynb files must be edited with the notebook_edit tool, not edit_file.",
+                is_error=True,
+            )
+
+        # 处理新文件创建：仅当 old_string 为空时允许
+        if not path.exists():
+            if arguments.old_string:
+                return ToolResult(
+                    output=f"File not found: {path}. To create a new file, set old_string to empty string.",
+                    is_error=True,
+                )
+            # 创建新文件
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(arguments.new_string, encoding="utf-8")
+            mark_file_read(str(path))
+            # 生成新文件内容预览
+            preview = _generate_create_preview(str(path), arguments.new_string)
+            return ToolResult(output=f"Created {path}\n{preview}")
+
+        # 读后编辑强制检查
+        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 edit it. This tool will error if you attempt "
+                    "an edit without reading the file first."
+                ),
+                is_error=True,
+            )
+
+        # 空操作保护
+        if arguments.old_string == arguments.new_string:
+            return ToolResult(
+                output="old_string and new_string are identical — no changes needed.",
+                is_error=True,
+            )
+
+        # 非空文件上的空 old_string
+        original = path.read_text(encoding="utf-8")
+        if not arguments.old_string and original.strip():
+            return ToolResult(
+                output=(
+                    "old_string is empty but the file is not empty. "
+                    "To replace the entire file content, use the Write tool instead."
+                ),
+                is_error=True,
+            )
+
+        # 空文件上的空 old_string = 写入新内容
+        if not arguments.old_string and not original.strip():
+            path.write_text(arguments.new_string, encoding="utf-8")
+            diff_text = _generate_diff(str(path), original, arguments.new_string)
+            return ToolResult(output=f"Updated {path}\n{diff_text}")
+
+        # 检查 old_string 是否存在于文件中
+        if arguments.old_string not in original:
+            # 尝试提供关于文件中内容的帮助上下文
+            _similar = _find_similar_lines(original, arguments.old_string)
+            msg = "old_string was not found in the file."
+            if _similar:
+                msg += f"\n\nThe closest matches in the file are:\n{_similar}"
+            return ToolResult(output=msg, is_error=True)
+
+        # 唯一性检查（当不是替换所有时）
+        if not arguments.replace_all:
+            count = original.count(arguments.old_string)
+            if count > 1:
+                return ToolResult(
+                    output=(
+                        f"old_string appears {count} times in the file. "
+                        "Either provide a larger string with more surrounding context to make it unique, "
+                        "or use replace_all=true to change every instance."
+                    ),
+                    is_error=True,
+                )
+
+        # 应用编辑
+        if arguments.replace_all:
+            updated = original.replace(arguments.old_string, arguments.new_string)
+        else:
+            updated = original.replace(arguments.old_string, arguments.new_string, 1)
+
+        path.write_text(updated, encoding="utf-8")
+        # 生成差异文本
+        diff_text = _generate_diff(str(path), original, updated)
+        return ToolResult(output=f"Updated {path}\n{diff_text}")
+
+
+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()
+
+
+def _find_similar_lines(content: str, target: str, max_lines: int = 5) -> str:
+    """在内容中找到与目标字符串部分匹配的行。
+
+    返回格式化的字符串，显示最接近的匹配，或空字符串。
+    """
+    target_lines = [line.strip() for line in target.splitlines() if line.strip()]
+    if not target_lines:
+        return ""
+
+    content_lines = content.splitlines()
+    matches: list[str] = []
+    first_target = target_lines[0].lower()
+
+    for i, line in enumerate(content_lines):
+        stripped = line.strip().lower()
+        # 检查此行是否包含第一个目标行或被其包含
+        if first_target in stripped or stripped in first_target:
+            start = max(0, i - 1)
+            end = min(len(content_lines), i + 2)
+            block = "\n".join(f"  {j+1}: {content_lines[j]}" for j in range(start, end))
+            matches.append(block)
+            if len(matches) >= max_lines:
+                break
+
+    return "\n\n".join(matches) if matches else ""

illusion/tools/file_read_tool.py

@@ -0,0 +1,294 @@
+"""
+文件读取工具
+===========
+
+本模块提供读取本地文件系统文件的功能，支持文本文件和图片文件。
+
+主要组件：
+    - FileReadTool: 读取文本文件和图片文件的工具
+
+使用示例：
+    >>> from illusion.tools import FileReadTool
+    >>> tool = FileReadTool()
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import mimetypes
+from pathlib import Path
+
+from pydantic import BaseModel, Field, model_validator
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+# 图片文件扩展名集合
+_IMAGE_EXTENSIONS: frozenset[str] = frozenset({
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg",
+})
+
+# 图片文件大小限制（字节）
+_IMAGE_SIZE_LIMIT: int = 20 * 1024 * 1024  # 20 MB
+
+
+def _is_image_file(path: Path) -> bool:
+    """检测文件是否为图片文件。"""
+    return path.suffix.lower() in _IMAGE_EXTENSIONS
+
+
+def _get_media_type(path: Path) -> str:
+    """获取文件的 MIME 类型。"""
+    media_type, _ = mimetypes.guess_type(str(path))
+    if media_type:
+        return media_type
+    fallback = {
+        ".svg": "image/svg+xml",
+    }
+    return fallback.get(path.suffix.lower(), "application/octet-stream")
+
+
+class FileReadToolInput(BaseModel):
+    """文件读取参数。
+
+    属性：
+        file_path: 要读取的文件路径
+        offset: 起始行号（从 0 开始）
+        limit: 返回的行数限制
+
+    兼容旧参数名：path 也可传入，会自动映射。
+    """
+
+    file_path: str = Field(description="Path of the file to read")
+    offset: int = Field(default=0, ge=0, description="Zero-based starting line")
+    limit: int = Field(default=2000, ge=1, le=2000, description="Number of lines to return")
+
+    @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 FileReadTool(BaseTool):
+    """读取文本文件和图片文件。
+
+    支持图片（PNG, JPG, GIF, WebP 等），通过 base64 编码传递给多模态模型。
+    """
+
+    name = "read_file"
+    description = """Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a file_path to a file assume that file_path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool allows Illusion Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Illusion Code is a multimodal LLM.
+- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
+- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
+- You will regularly be asked to read screenshots. If the user provides a file_path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents."""
+    input_model = FileReadToolInput
+
+    def is_read_only(self, arguments: FileReadToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(
+        self,
+        arguments: FileReadToolInput,
+        context: ToolExecutionContext,
+    ) -> ToolResult:
+        # 解析文件路径
+        path = _resolve_path(context.cwd, arguments.file_path)
+        # 检查文件是否存在
+        if not path.exists():
+            return ToolResult(output=f"File not found: {path}", is_error=True)
+        # 检查是否为目录
+        if path.is_dir():
+            return ToolResult(output=f"Cannot read directory: {path}", is_error=True)
+
+        # 检测是否为 Jupyter notebook
+        if path.suffix.lower() == ".ipynb":
+            return self._read_notebook_file(path, arguments)
+
+        # 检测是否为图片文件
+        if _is_image_file(path):
+            return self._read_image_file(path)
+
+        # 读取文本文件
+        return self._read_text_file(path, arguments)
+
+    def _read_image_file(self, path: Path) -> ToolResult:
+        """读取图片文件并返回 base64 编码数据。"""
+        raw = path.read_bytes()
+        file_size = len(raw)
+
+        # 检查文件大小限制
+        if file_size > _IMAGE_SIZE_LIMIT:
+            limit_mb = _IMAGE_SIZE_LIMIT // (1024 * 1024)
+            return ToolResult(
+                output=f"Image file too large: {file_size} bytes exceeds {limit_mb} MB limit",
+                is_error=True,
+            )
+
+        media_type = _get_media_type(path)
+        encoded = base64.b64encode(raw).decode("ascii")
+
+        # 生成输出描述
+        size_str = _human_size(file_size)
+        output = f"[image file: {path} ({size_str}, {media_type})]"
+
+        return ToolResult(
+            output=output,
+            metadata={
+                "media_category": "image",
+                "media_type": media_type,
+                "media_data": encoded,
+                "media_path": str(path),
+                "media_size": file_size,
+            },
+        )
+
+    def _read_notebook_file(self, path: Path, arguments: FileReadToolInput) -> ToolResult:
+        """读取 Jupyter notebook 文件，解析所有单元格及其输出。"""
+        try:
+            raw = path.read_text(encoding="utf-8")
+            nb = json.loads(raw)
+        except (json.JSONDecodeError, UnicodeDecodeError) as e:
+            return ToolResult(output=f"Failed to parse notebook {path}: {e}", is_error=True)
+
+        cells = nb.get("cells", [])
+        if not cells:
+            return ToolResult(output=f"System reminder: The notebook at {path} exists but has no cells.")
+
+        # 应用 offset/limit 到单元格级别
+        selected_cells = cells[arguments.offset : arguments.offset + arguments.limit]
+        if not selected_cells:
+            return ToolResult(
+                output=f"System reminder: No cells in selected range (offset={arguments.offset}, limit={arguments.limit}) for {path}"
+            )
+
+        output_parts: list[str] = []
+        for cell in selected_cells:
+            idx = cells.index(cell)
+            cell_type = cell.get("cell_type", "code")
+            source = "".join(cell.get("source", ""))
+            if isinstance(source, list):
+                source = "".join(source)
+
+            if cell_type == "markdown":
+                output_parts.append(f"## Cell {idx} (markdown)\n{source}")
+            elif cell_type == "code":
+                exec_count = cell.get("execution_count")
+                status = f"executed, count={exec_count}" if exec_count is not None else "not executed"
+                output_parts.append(f"## Cell {idx} (code) [{status}]")
+                if source.strip():
+                    output_parts.append(source)
+                else:
+                    output_parts.append("(empty cell)")
+
+                # 格式化输出
+                outputs = cell.get("outputs", [])
+                if outputs:
+                    output_parts.append("\n**Outputs:**")
+                    for out in outputs:
+                        out_type = out.get("output_type", "")
+                        if out_type == "stream":
+                            text = "".join(out.get("text", ""))
+                            if isinstance(text, list):
+                                text = "".join(text)
+                            name = out.get("name", "stdout")
+                            output_parts.append(f"[{name}]:\n{text}")
+                        elif out_type == "execute_result":
+                            data = out.get("data", {})
+                            text = data.get("text/plain", "")
+                            if isinstance(text, list):
+                                text = "".join(text)
+                            output_parts.append(f"[result]: {text}")
+                        elif out_type == "error":
+                            ename = out.get("ename", "Error")
+                            evalue = out.get("evalue", "")
+                            traceback = out.get("traceback", [])
+                            if isinstance(traceback, list):
+                                traceback_text = "\n".join(traceback)
+                            else:
+                                traceback_text = str(traceback)
+                            output_parts.append(f"[error]: {ename}: {evalue}\n{traceback_text}")
+                        elif out_type == "display_data":
+                            data = out.get("data", {})
+                            text = data.get("text/plain", "")
+                            if isinstance(text, list):
+                                text = "".join(text)
+                            if text:
+                                output_parts.append(f"[display]: {text}")
+                            if "image/png" in data:
+                                output_parts.append("[display]: <image/png>")
+                elif exec_count is not None:
+                    output_parts.append("\n**Outputs:** (none)")
+            else:
+                source = "".join(cell.get("source", ""))
+                if isinstance(source, list):
+                    source = "".join(source)
+                output_parts.append(f"## Cell {idx} ({cell_type})\n{source}")
+
+            output_parts.append("")  # 单元格间空行
+
+        # 注册文件已被读取
+        from illusion.tools.file_edit_tool import mark_file_read
+        mark_file_read(str(path))
+
+        return ToolResult(output="\n".join(output_parts).strip())
+
+    def _read_text_file(self, path: Path, arguments: FileReadToolInput) -> ToolResult:
+        """读取文本文件。"""
+        raw = path.read_bytes()
+        if b"\x00" in raw:
+            return ToolResult(output=f"Binary file cannot be read as text: {path}", is_error=True)
+
+        text = raw.decode("utf-8", errors="replace")
+        lines = text.splitlines()
+        selected = lines[arguments.offset : arguments.offset + arguments.limit]
+        numbered = [
+            f"{arguments.offset + index + 1:>6}\t{line}"
+            for index, line in enumerate(selected)
+        ]
+        if not numbered:
+            return ToolResult(
+                output=f"System reminder: The file at {path} exists but has empty contents."
+            )
+
+        # 注册文件已被读取（用于读后编辑强制检查）
+        from illusion.tools.file_edit_tool import mark_file_read
+        mark_file_read(str(path))
+
+        return ToolResult(output="\n".join(numbered))
+
+
+def _human_size(size: int) -> str:
+    """将字节数转为人类可读的大小字符串。"""
+    if size < 1024:
+        return f"{size} B"
+    if size < 1024 * 1024:
+        return f"{size / 1024:.1f} KB"
+    return f"{size / (1024 * 1024):.1f} MB"
+
+
+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()