jarvis-ai-assistant 0.7.16__py3-none-any.whl → 1.0.2__py3-none-any.whl

jarvis/jarvis_tools/edit_file.py

@@ -1,28 +1,40 @@
-# -*- coding: utf-8 -*-
+"""普通文件编辑工具（基于 search/replace 的非结构化编辑）"""
+
 import os
 import shutil
-import time
-from enum import Enum
-from typing import Any, Dict, List, Optional, Tuple
-
 
+from jarvis.jarvis_utils.output import PrettyOutput
 
-class EditErrorType(Enum):
-    """编辑错误类型枚举"""
-    BLOCK_ID_NOT_FOUND = "block_id_not_found"  # 块id不存在
-    CACHE_INVALID = "cache_invalid"  # 缓存无效
-    MULTIPLE_MATCHES = "multiple_matches"  # 多处匹配
-    SEARCH_NOT_FOUND = "search_not_found"  # 搜索文本未找到
-    PARAMETER_MISSING = "parameter_missing"  # 参数缺失
-    UNSUPPORTED_ACTION = "unsupported_action"  # 不支持的操作
-    OTHER = "other"  # 其他错误
+# -*- coding: utf-8 -*-
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Tuple
 
 
-class EditFileTool:
-    """文件编辑工具，用于对文件进行结构化编辑"""
+class EditFileNormalTool:
+    """普通文件编辑工具，完全基于 search/replace 进行文件编辑"""
 
     name = "edit_file"
-    description = "对文件进行结构化编辑（通过块id），支持同时修改多个文件。\n\n    💡 使用步骤：\n    1. 先使用read_code工具获取文件的结构化块id\n    2. 通过块id进行精确的代码块操作（删除、插入、替换、编辑）\n    3. 避免手动计算行号，减少错误风险\n    4. 可以在一次调用中同时修改多个文件\n\n    📝 支持的操作类型：\n    - delete: 删除块\n    - insert_before: 在块前插入内容\n    - insert_after: 在块后插入内容\n    - replace: 替换整个块\n    - edit: 在块内进行search/replace（需要提供search和replace参数）\n\n    ⚠️ 重要提示：\n    - 不要一次修改太多内容，建议分多次进行，避免超过LLM的上下文窗口大小\n    - 如果修改内容较长（超过2048字符），建议拆分为多个较小的编辑操作"
+    description = (
+        "使用 search/replace 对文件进行普通文本编辑（不依赖块id），支持同时修改多个文件。\n\n"
+        "💡 使用方式：\n"
+        "1. 直接指定要编辑的文件路径\n"
+        "2. 为每个文件提供一组 search/replace 操作\n"
+        "3. 使用精确匹配查找 search 文本，找到匹配后替换为新文本\n\n"
+        "🚀 特殊功能：\n"
+        '- 当 search 为空字符串 "" 时，表示直接重写整个文件，replace 的内容将作为文件的完整新内容\n'
+        "- 如果存在多个diffs且第一个diff的search为空字符串，将只应用第一个diff（重写整个文件），跳过后续所有diffs\n\n"
+        "⚠️ 提示：\n"
+        "- search 使用精确字符串匹配，不支持正则表达式\n"
+        "- **重要：search 必须提供足够的上下文来唯一定位目标位置**，避免匹配到错误的位置。建议包含：\n"
+        "  * 目标代码的前后几行上下文（至少包含目标代码所在函数的签名或关键标识）\n"
+        "  * 目标代码附近的唯一标识符（如函数名、变量名、注释等）\n"
+        "  * 避免使用过短的 search 文本（如单个单词、短字符串），除非能确保唯一性\n"
+        "- 如果某个 search 在文件中找不到精确匹配（search非空时），将导致该文件的编辑失败，文件内容会回滚到原始状态\n"
+        "- 建议在 search 中包含足够的上下文，确保能唯一匹配到目标位置，避免误匹配"
+    )
 
     parameters = {
         "type": "object",
@@ -41,50 +53,36 @@ class EditFileTool:
                             "items": {
                                 "type": "object",
                                 "properties": {
-                                    "block_id": {
-                                        "type": "string",
-                                        "description": "要操作的块id（从read_code工具获取的结构化块id）",
-                                    },
-                                    "action": {
-                                        "type": "string",
-                                        "enum": ["delete", "insert_before", "insert_after", "replace", "edit"],
-                                        "description": "操作类型：delete（删除块）、insert_before（在块前插入）、insert_after（在块后插入）、replace（替换块）、edit（在块内进行search/replace）",
-                                    },
-                                    "content": {
-                                        "type": "string",
-                                        "description": "新内容（对于insert_before、insert_after、replace操作必需，delete和edit操作不需要）",
-                                    },
                                     "search": {
                                         "type": "string",
-                                        "description": "要搜索的文本（对于edit操作必需）",
+                                        "description": '要搜索的原始文本（不支持正则表达式）。当为空字符串""时，表示直接重写整个文件，replace的内容将作为文件的完整新内容。非空时，**重要：必须提供足够的上下文来唯一定位目标位置**，建议包含目标代码的前后几行上下文、函数签名或唯一标识符，避免匹配到错误的位置。',
                                     },
                                     "replace": {
                                         "type": "string",
-                                        "description": "替换后的文本（对于edit操作必需）",
+                                        "description": "替换后的文本（可以为空字符串）",
                                     },
                                 },
-                                "required": ["block_id", "action"],
+                                "required": ["search", "replace"],
                             },
-                            "description": "修改操作列表，每个操作包含一个结构化编辑块",
+                            "description": "普通文本替换操作列表，按顺序依次应用到文件内容",
                         },
                     },
                     "required": ["file_path", "diffs"],
                 },
-                "description": "要修改的文件列表，每个文件包含文件路径和对应的编辑操作列表",
+                "description": "要修改的文件列表，每个文件包含文件路径和对应的 search/replace 操作列表",
             },
         },
         "required": ["files"],
     }
 
     def __init__(self):
-        """初始化文件编辑工具"""
+        """初始化普通文件编辑工具"""
         pass
 
-
     @staticmethod
     def _validate_basic_args(args: Dict[str, Any]) -> Optional[Dict[str, Any]]:
         """验证基本参数
-            
+
         Returns:
             如果验证失败，返回错误响应；否则返回None
         """
@@ -103,305 +101,449 @@ class EditFileTool:
                 "stdout": "",
                 "stderr": "files参数必须是数组类型",
             }
-        
+
         if len(files) == 0:
             return {
                 "success": False,
                 "stdout": "",
                 "stderr": "files数组不能为空",
             }
-        
+
         # 验证每个文件项
         for idx, file_item in enumerate(files):
             if not isinstance(file_item, dict):
                 return {
                     "success": False,
                     "stdout": "",
-                    "stderr": f"files数组第 {idx+1} 项必须是字典类型",
+                    "stderr": f"files数组第 {idx + 1} 项必须是字典类型",
                 }
-            
+
             file_path = file_item.get("file_path")
             diffs = file_item.get("diffs", [])
-            
+
             if not file_path:
                 return {
                     "success": False,
                     "stdout": "",
-                    "stderr": f"files数组第 {idx+1} 项缺少必需参数：file_path",
+                    "stderr": f"files数组第 {idx + 1} 项缺少必需参数：file_path",
                 }
-            
+
             if not diffs:
                 return {
                     "success": False,
                     "stdout": "",
-                    "stderr": f"files数组第 {idx+1} 项缺少必需参数：diffs",
+                    "stderr": f"files数组第 {idx + 1} 项缺少必需参数：diffs",
                 }
-            
+
             if not isinstance(diffs, list):
                 return {
                     "success": False,
                     "stdout": "",
-                    "stderr": f"files数组第 {idx+1} 项的diffs参数必须是数组类型",
+                    "stderr": f"files数组第 {idx + 1} 项的diffs参数必须是数组类型",
                 }
-        
+
         return None
 
     @staticmethod
-    def _get_file_cache(agent: Any, filepath: str) -> Optional[Dict[str, Any]]:
-        """获取文件的缓存信息
-        
+    def _read_file_with_backup(file_path: str) -> Tuple[str, Optional[str]]:
+        """读取文件并创建备份
+
         Args:
-            agent: Agent实例
-            filepath: 文件路径
-            
+            file_path: 文件路径
+
         Returns:
-            缓存信息字典，如果不存在则返回None
+            (文件内容, 备份文件路径或None)
         """
-        if not agent:
-            return None
-        
-        cache = agent.get_user_data("read_code_cache")
-        if not cache:
-            return None
-        
-        abs_path = os.path.abspath(filepath)
-        return cache.get(abs_path)
+        abs_path = os.path.abspath(file_path)
+        os.makedirs(os.path.dirname(abs_path), exist_ok=True)
+
+        file_content = ""
+        backup_path = None
+        if os.path.exists(abs_path):
+            with open(abs_path, "r", encoding="utf-8") as f:
+                file_content = f.read()
+            # 创建备份文件
+            backup_path = abs_path + ".bak"
+            try:
+                shutil.copy2(abs_path, backup_path)
+            except Exception:
+                # 备份失败不影响主流程
+                backup_path = None
+
+        return file_content, backup_path
 
     @staticmethod
-    def _is_cache_valid(cache_info: Optional[Dict[str, Any]], filepath: str) -> bool:
-        """检查缓存是否有效
-        
+    def _write_file_with_rollback(
+        abs_path: str, content: str, backup_path: Optional[str]
+    ) -> Tuple[bool, Optional[str]]:
+        """写入文件，失败时回滚
+
         Args:
-            cache_info: 缓存信息字典
-            filepath: 文件路径
-            
+            abs_path: 文件绝对路径
+            content: 要写入的内容
+            backup_path: 备份文件路径或None
+
         Returns:
-            True表示缓存有效，False表示缓存无效
+            (是否成功, 错误信息或None)
         """
-        if not cache_info:
-            return False
-        
         try:
-            # 检查文件是否存在
-            if not os.path.exists(filepath):
-                return False
-            
-            # 检查文件修改时间是否变化
-            current_mtime = os.path.getmtime(filepath)
-            cached_mtime = cache_info.get("file_mtime")
-            
-            if cached_mtime is None or abs(current_mtime - cached_mtime) > 0.1:  # 允许0.1秒的误差
-                return False
-            
-            # 检查缓存数据结构是否完整
-            if "id_list" not in cache_info or "blocks" not in cache_info or "total_lines" not in cache_info:
-                return False
-            
-            return True
-        except Exception:
-            return False
+            with open(abs_path, "w", encoding="utf-8") as f:
+                f.write(content)
+            return (True, None)
+        except Exception as write_error:
+            # 写入失败，尝试回滚
+            if backup_path and os.path.exists(backup_path):
+                try:
+                    shutil.copy2(backup_path, abs_path)
+                    os.remove(backup_path)
+                except Exception:
+                    pass
+            error_msg = f"文件写入失败: {str(write_error)}"
+            PrettyOutput.auto_print(f"❌ {error_msg}")
+            return (False, error_msg)
+
+    @staticmethod
+    def _validate_normal_diff(
+        diff: Dict[str, Any], idx: int
+    ) -> Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
+        """验证并转换 normal 类型的 diff
+
+        Returns:
+            (错误响应或None, 规范化后的diff或None)
+        """
+        search = diff.get("search")
+        replace = diff.get("replace")
+
+        if search is None:
+            return (
+                {
+                    "success": False,
+                    "stdout": "",
+                    "stderr": f"第 {idx} 个diff缺少search参数",
+                },
+                None,
+            )
+        if not isinstance(search, str):
+            return (
+                {
+                    "success": False,
+                    "stdout": "",
+                    "stderr": f"第 {idx} 个diff的search参数必须是字符串",
+                },
+                None,
+            )
+        # 允许空字符串作为search参数，表示直接重写整个文件
+
+        if replace is None:
+            return (
+                {
+                    "success": False,
+                    "stdout": "",
+                    "stderr": f"第 {idx} 个diff缺少replace参数",
+                },
+                None,
+            )
+        if not isinstance(replace, str):
+            return (
+                {
+                    "success": False,
+                    "stdout": "",
+                    "stderr": f"第 {idx} 个diff的replace参数必须是字符串",
+                },
+                None,
+            )
+
+        return (
+            None,
+            {
+                "search": search,
+                "replace": replace,
+            },
+        )
 
     @staticmethod
-    def _find_block_by_id_in_cache(cache_info: Dict[str, Any], block_id: str) -> Optional[Dict[str, Any]]:
-        """从缓存中根据块id定位代码块
-        
+    def _count_matches(content: str, search_text: str) -> int:
+        """统计文本在内容中的匹配次数
+
         Args:
-            cache_info: 缓存信息字典
-            block_id: 块id
-            
+            content: 文件内容
+            search_text: 要搜索的文本
+
         Returns:
-            如果找到，返回包含 content 的字典；否则返回 None
+            匹配次数
         """
-        if not cache_info:
-            return None
-        
-        # 直接从 blocks 字典中查找
-        blocks = cache_info.get("blocks", {})
-        block = blocks.get(block_id)
-        if block:
-            return {
-                "content": block.get("content", ""),
-            }
-        
-        return None
+        if not search_text:
+            return 0
+        return content.count(search_text)
 
     @staticmethod
-    def _update_cache_timestamp(agent: Any, filepath: str) -> None:
-        """更新缓存的时间戳
-        
+    def _generate_diff_preview(
+        original_content: str,
+        modified_content: str,
+        file_path: str,
+        match_count: int,
+        search_text: str,
+        replace_text: str,
+        agent: Optional[Any] = None,
+        token_ratio: float = 0.3,
+    ) -> str:
+        """生成修改后的预览diff
+
         Args:
-            agent: Agent实例
-            filepath: 文件路径
+            original_content: 原始文件内容
+            modified_content: 修改后的文件内容
+            file_path: 文件路径
+            match_count: 匹配次数
+            search_text: 搜索文本
+            replace_text: 替换文本
+            agent: 可选的 agent 实例，用于获取剩余 token 数量
+            token_ratio: token 使用比例（默认 0.3，即 30%）
+
+        Returns:
+            预览diff字符串
         """
-        if not agent:
-            return
-        
-        cache = agent.get_user_data("read_code_cache")
-        if not cache:
-            return
-        
-        abs_path = os.path.abspath(filepath)
-        if abs_path in cache:
-            cache[abs_path]["read_time"] = time.time()
-            # 更新文件修改时间
+        import difflib
+
+        # 生成统一的diff格式
+        original_lines = original_content.splitlines(keepends=True)
+        modified_lines = modified_content.splitlines(keepends=True)
+
+        # 使用difflib生成统一的diff
+        diff = list(
+            difflib.unified_diff(
+                original_lines,
+                modified_lines,
+                fromfile=f"a/{file_path}",
+                tofile=f"b/{file_path}",
+                lineterm="",
+            )
+        )
+
+        diff_preview = "".join(diff)
+
+        # 根据剩余token计算最大字符数
+        max_diff_chars = None
+
+        # 优先尝试使用 agent 获取剩余 token（更准确，包含对话历史）
+        if agent:
             try:
-                if os.path.exists(abs_path):
-                    cache[abs_path]["file_mtime"] = os.path.getmtime(abs_path)
+                remaining_tokens = agent.get_remaining_token_count()
+                if remaining_tokens > 0:
+                    # 使用剩余 token 的指定比例作为字符限制（1 token ≈ 4字符）
+                    max_diff_chars = int(remaining_tokens * token_ratio * 4)
+                    if max_diff_chars <= 0:
+                        max_diff_chars = None
             except Exception:
                 pass
-            agent.set_user_data("read_code_cache", cache)
+
+        # 回退方案：使用输入窗口的指定比例转换为字符数
+        if max_diff_chars is None:
+            try:
+                from jarvis.jarvis_utils.config import get_max_input_token_count
+
+                max_input_tokens = get_max_input_token_count()
+                max_diff_chars = int(max_input_tokens * token_ratio * 4)
+            except Exception:
+                # 如果获取失败，使用默认值（约 10000 字符）
+                max_diff_chars = 10000
+
+        # 限制diff长度
+        if len(diff_preview) > max_diff_chars:
+            diff_preview = (
+                diff_preview[:max_diff_chars] + "\n... (diff 内容过长，已截断)"
+            )
+
+        return diff_preview
 
     @staticmethod
-    def _validate_structured(diff: Dict[str, Any], idx: int) -> Tuple[Optional[Dict[str, Any]], Optional[Dict[str, str]]]:
-        """验证并转换structured类型的diff
-        
+    def _confirm_multiple_matches(
+        agent: Any,
+        file_path: str,
+        original_content: str,
+        modified_content: str,
+        match_count: int,
+        search_text: str,
+        replace_text: str,
+    ) -> bool:
+        """使用 agent 确认多个匹配是否应该继续
+
+        Args:
+            agent: Agent 实例
+            file_path: 文件路径
+            original_content: 原始文件内容
+            modified_content: 修改后的文件内容
+            match_count: 匹配次数
+            search_text: 搜索文本
+            replace_text: 替换文本
+
         Returns:
-            (错误响应或None, patch字典或None)
+            True 表示确认继续，False 表示取消
         """
-        block_id = diff.get("block_id")
-        action = diff.get("action")
-        content = diff.get("content")
-        
-        if block_id is None:
-            return ({
-                "success": False,
-                "stdout": "",
-                "stderr": f"第 {idx+1} 个diff缺少block_id参数",
-            }, None)
-        if not isinstance(block_id, str):
-            return ({
-                "success": False,
-                "stdout": "",
-                "stderr": f"第 {idx+1} 个diff的block_id参数必须是字符串",
-            }, None)
-        if not block_id.strip():
-            return ({
-                "success": False,
-                "stdout": "",
-                "stderr": f"第 {idx+1} 个diff的block_id参数不能为空",
-            }, None)
-        
-        if action is None:
-            return ({
-                "success": False,
-                "stdout": "",
-                "stderr": f"第 {idx+1} 个diff缺少action参数",
-            }, None)
-        if not isinstance(action, str):
-            return ({
-                "success": False,
-                "stdout": "",
-                "stderr": f"第 {idx+1} 个diff的action参数必须是字符串",
-            }, None)
-        if action not in ["delete", "insert_before", "insert_after", "replace", "edit"]:
-            return ({
-                "success": False,
-                "stdout": "",
-                "stderr": f"第 {idx+1} 个diff的action参数必须是 delete、insert_before、insert_after、replace 或 edit 之一",
-            }, None)
-        
-        # 对于edit操作，需要search和replace参数
-        if action == "edit":
-            search = diff.get("search")
-            replace = diff.get("replace")
-            if search is None:
-                return ({
-                    "success": False,
-                    "stdout": "",
-                    "stderr": f"第 {idx+1} 个diff的action为 edit，需要提供search参数",
-                }, None)
-            if not isinstance(search, str):
-                return ({
-                    "success": False,
-                    "stdout": "",
-                    "stderr": f"第 {idx+1} 个diff的search参数必须是字符串",
-                }, None)
-            if replace is None:
-                return ({
-                    "success": False,
-                    "stdout": "",
-                    "stderr": f"第 {idx+1} 个diff的action为 edit，需要提供replace参数",
-                }, None)
-            if not isinstance(replace, str):
-                return ({
-                    "success": False,
-                    "stdout": "",
-                    "stderr": f"第 {idx+1} 个diff的replace参数必须是字符串",
-                }, None)
-        # 对于非delete和非edit操作，content是必需的
-        elif action != "delete":
-            if content is None:
-                return ({
-                    "success": False,
-                    "stdout": "",
-                    "stderr": f"第 {idx+1} 个diff的action为 {action}，需要提供content参数",
-                }, None)
-            if not isinstance(content, str):
-                return ({
-                    "success": False,
-                    "stdout": "",
-                    "stderr": f"第 {idx+1} 个diff的content参数必须是字符串",
-            }, None)
-        
-        patch = {
-            "STRUCTURED_BLOCK_ID": block_id,
-            "STRUCTURED_ACTION": action,
-        }
-        if content is not None:
-            patch["STRUCTURED_CONTENT"] = content
-        if action == "edit":
-            patch["STRUCTURED_SEARCH"] = diff.get("search")
-            patch["STRUCTURED_REPLACE"] = diff.get("replace")
-        return (None, patch)
+        try:
+            from jarvis.jarvis_agent import Agent
 
+            agent_instance: Agent = agent
+            if not agent_instance or not agent_instance.model:
+                # 如果没有 agent 或 model，默认不继续
+                return False
+
+            # 生成预览diff
+            diff_preview = EditFileNormalTool._generate_diff_preview(
+                original_content,
+                modified_content,
+                file_path,
+                match_count,
+                search_text,
+                replace_text,
+                agent=agent_instance,
+                token_ratio=0.3,  # 使用30%的剩余token用于diff预览
+            )
+
+            prompt = f"""检测到文件编辑操作中，search 文本在文件中存在多处匹配，需要您确认是否继续修改：
+
+文件路径：{file_path}
+
+匹配统计：
+- 匹配数量: {match_count}
+- 搜索文本长度: {len(search_text)} 字符
+- 替换文本长度: {len(replace_text)} 字符
+
+修改预览（diff）：
+{diff_preview}
+
+请仔细分析以上代码变更，判断这些修改是否合理。可能的情况包括：
+1. 这些匹配位置都是您想要修改的，修改是正确的
+2. 这些匹配位置不是您想要的，或者需要更精确的定位
+3. 修改可能影响其他不相关的代码
+
+请使用以下协议回答（必须包含且仅包含以下标记之一）：
+- 如果认为这些修改是合理的，回答: <!!!YES!!!>
+- 如果认为这些修改不合理或存在风险，回答: <!!!NO!!!>
+
+请严格按照协议格式回答，不要添加其他内容。"""
+
+            PrettyOutput.auto_print("🤖 正在询问大模型确认多处匹配的修改是否合理...")
+            response = agent_instance.model.chat_until_success(prompt)
+            response_str = str(response or "")
+
+            # 使用确定的协议标记解析回答
+            if "<!!!YES!!!>" in response_str:
+                PrettyOutput.auto_print("✅ 大模型确认：修改合理，继续执行")
+                return True
+            elif "<!!!NO!!!>" in response_str:
+                PrettyOutput.auto_print("⚠️ 大模型确认：修改不合理，取消操作")
+                return False
+            else:
+                # 如果无法找到协议标记，默认认为不合理（保守策略）
+                PrettyOutput.auto_print(
+                    f"⚠️ 无法找到协议标记，默认认为不合理。回答内容: {response_str[:200]}"
+                )
+                return False
+        except Exception as e:
+            # 确认过程出错，默认不继续
+            PrettyOutput.auto_print(f"⚠️ 确认过程出错: {e}，默认取消操作")
+            return False
 
     @staticmethod
-    def _convert_diffs_to_patches(diffs: List[Dict[str, Any]]) -> Tuple[Optional[Dict[str, Any]], List[Dict[str, str]]]:
-        """验证并转换diffs为内部patches格式
-        
-        Returns:
-            (错误响应或None, patches列表)
+    def _apply_normal_edits_to_content(
+        original_content: str,
+        diffs: List[Dict[str, Any]],
+        agent: Optional[Any] = None,
+        file_path: Optional[str] = None,
+        start_idx: int = 0,
+    ) -> Tuple[bool, str, Optional[Dict[str, Any]], Optional[int]]:
+        """对文件内容按顺序应用普通 search/replace 编辑（使用字符串替换）
+
+        Args:
+            original_content: 原始文件内容（或已部分修改的内容）
+            diffs: diff 列表
+            agent: 可选的 agent 实例
+            file_path: 可选的文件路径
+            start_idx: 从哪个 diff 索引开始处理（0-based，用于继续处理剩余 diffs）
+
+        返回:
+            (是否成功, 新内容或错误信息, 确认信息字典或None, 需要确认的diff索引或None)
+            确认信息字典包含: match_count, search_text, replace_text, modified_content, current_content
         """
-        patches = []
-        for idx, diff in enumerate(diffs):
-            if not isinstance(diff, dict):
-                return ({
-                    "success": False,
-                    "stdout": "",
-                    "stderr": f"第 {idx+1} 个diff必须是字典类型",
-                }, [])
-            
-            # 所有diff都是structured类型
-            error_response, patch = EditFileTool._validate_structured(diff, idx + 1)
-            
-            if error_response:
-                return (error_response, [])
-            
-            if patch:
-                patches.append(patch)
-        
-        return (None, patches)
+        content = original_content
+
+        for idx, diff in enumerate(diffs[start_idx:], start=start_idx + 1):
+            search = diff["search"]
+            replace = diff["replace"]
+
+            # 处理空字符串search的特殊情况
+            if search == "":
+                # 空字符串表示直接重写整个文件
+                content = replace
+                # 空search只处理第一个diff，跳过后续所有diffs
+                break
+
+            # 验证 search 文本
+            if not isinstance(search, str):
+                error_info = f"第 {idx} 个diff失败：search 文本必须是字符串"
+                return False, error_info, None, None
+
+            # 统计匹配次数
+            match_count = EditFileNormalTool._count_matches(content, search)
+
+            if match_count == 0:
+                # 找不到匹配
+                error_info = f"第 {idx} 个diff失败：未找到精确匹配的文本"
+                if search:
+                    error_info += f"\n搜索文本: {search[:200]}..."
+                    error_info += (
+                        "\n💡 提示：如果搜索文本在文件中存在但未找到匹配，可能是因为："
+                    )
+                    error_info += "\n   1. 搜索文本包含不可见字符或格式不匹配（建议检查空格、换行等）"
+                    error_info += "\n   2. **文件可能已被更新**：如果文件在其他地方被修改了，搜索文本可能已经不存在或已改变"
+                    if file_path:
+                        error_info += f"\n   💡 建议：使用 `read_code` 工具重新读取文件 `{file_path}` 查看当前内容，"
+                        error_info += "\n      确认文件是否已被更新，然后根据实际内容调整 search 文本"
+                return False, error_info, None, None
+
+            if match_count == 1:
+                # 唯一匹配，直接替换
+                content = content.replace(search, replace, 1)
+            else:
+                # 多个匹配，需要确认
+                # 生成修改后的内容（替换所有匹配）
+                modified_content = content.replace(search, replace)
+                # 返回确认信息，包含当前内容以便继续处理后续 diffs
+                confirm_info = {
+                    "match_count": match_count,
+                    "search_text": search,
+                    "replace_text": replace,
+                    "modified_content": modified_content,
+                    "current_content": content,  # 保存当前内容，用于继续处理
+                    "diff_idx": idx,  # 保存当前 diff 索引
+                }
+                error_info = (
+                    f"第 {idx} 个diff失败：发现 {match_count} 处匹配，需要确认后再修改"
+                )
+                return False, error_info, confirm_info, idx
+
+        return True, content, None, None
 
     def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
-        """执行文件编辑操作（支持同时修改多个文件）"""
+        """执行普通 search/replace 文件编辑操作（支持同时修改多个文件）"""
         try:
-            # 验证基本参数
-            error_response = EditFileTool._validate_basic_args(args)
+            # 验证基本参数（files 结构）
+            error_response = EditFileNormalTool._validate_basic_args(args)
             if error_response:
                 return error_response
-            
+
             files = args.get("files", [])
-            agent = args.get("agent", None)
+            # 获取 agent 实例（v1.0 协议中 agent 在 args 中）
+            agent = args.get("agent")
 
             # 记录 PATCH 操作调用统计
             try:
                 from jarvis.jarvis_stats.stats import StatsManager
 
-                StatsManager.increment("patch", group="tool")
+                StatsManager.increment("patch_normal", group="tool")
             except Exception:
                 pass
 
-            # 处理每个文件
             all_results = []
             overall_success = True
             successful_files = []
@@ -411,22 +553,164 @@ class EditFileTool:
                 file_path = file_item.get("file_path")
                 diffs = file_item.get("diffs", [])
 
-                # 转换diffs为patches
-                error_response, patches = EditFileTool._convert_diffs_to_patches(diffs)
-                if error_response:
-                    all_results.append(f"❌ {file_path}: {error_response.get('stderr', '参数验证失败')}")
+                # 校验并规范化 diffs
+                normalized_diffs: List[Dict[str, Any]] = []
+                for idx, diff in enumerate(diffs, start=1):
+                    if not isinstance(diff, dict):
+                        all_results.append(
+                            f"❌ {file_path}: 第 {idx} 个diff必须是字典类型"
+                        )
+                        failed_files.append(file_path)
+                        overall_success = False
+                        normalized_diffs = []
+                        break
+
+                    error, normalized = EditFileNormalTool._validate_normal_diff(
+                        diff, idx
+                    )
+                    if error:
+                        all_results.append(
+                            f"❌ {file_path}: {error.get('stderr', '参数验证失败')}"
+                        )
+                        failed_files.append(file_path)
+                        overall_success = False
+                        normalized_diffs = []
+                        break
+
+                    if normalized is not None:
+                        normalized_diffs.append(normalized)
+
+                if not normalized_diffs:
+                    # 该文件的diffs有问题，已记录错误，跳过
+                    continue
+
+                # 读取原始内容并创建备份
+                (
+                    original_content,
+                    backup_path,
+                ) = EditFileNormalTool._read_file_with_backup(file_path)
+
+                # 应用所有普通编辑，使用循环处理所有可能的确认情况
+                current_content = original_content
+                current_start_idx = 0
+                success = False
+                result_or_error = ""
+                max_confirm_iterations = len(normalized_diffs) * 2  # 防止无限循环
+                confirm_iteration = 0
+
+                while confirm_iteration < max_confirm_iterations:
+                    (
+                        iter_success,
+                        iter_result_or_error,
+                        iter_confirm_info,
+                        iter_confirm_diff_idx,
+                    ) = EditFileNormalTool._apply_normal_edits_to_content(
+                        current_content,
+                        normalized_diffs,
+                        agent=agent,
+                        file_path=file_path,
+                        start_idx=current_start_idx,
+                    )
+
+                    if iter_success:
+                        # 所有 diffs 处理成功
+                        success = True
+                        result_or_error = iter_result_or_error
+                        break
+
+                    # 处理失败，检查是否需要确认
+                    if (
+                        iter_confirm_info
+                        and agent
+                        and iter_confirm_diff_idx is not None
+                    ):
+                        # 需要确认
+                        confirmed = EditFileNormalTool._confirm_multiple_matches(
+                            agent,
+                            file_path,
+                            original_content,
+                            iter_confirm_info["modified_content"],
+                            iter_confirm_info["match_count"],
+                            iter_confirm_info["search_text"],
+                            iter_confirm_info["replace_text"],
+                        )
+
+                        if confirmed:
+                            # 确认继续，应用当前 diff 的所有匹配替换
+                            current_content = iter_confirm_info["modified_content"]
+                            current_diff_idx = iter_confirm_info.get(
+                                "diff_idx", iter_confirm_diff_idx
+                            )
+                            # 从下一个 diff 继续处理
+                            # current_diff_idx 是 1-based（第几个 diff），转换为 0-based 列表索引
+                            # 例如：diff_idx=2 表示第 2 个 diff（diffs[1]），下一个是 diffs[2]，所以 start_idx=2
+                            # 注意：current_diff_idx 是 1-based，下一个 diff 的 0-based 索引正好等于 current_diff_idx
+                            current_start_idx = current_diff_idx
+                            confirm_iteration += 1
+                            # 继续循环处理剩余 diffs
+                            continue
+                        else:
+                            # 确认取消
+                            if backup_path and os.path.exists(backup_path):
+                                try:
+                                    os.remove(backup_path)
+                                except Exception:
+                                    pass
+                            result_or_error = "操作已取消（发现多处匹配，已确认不继续）"
+                            all_results.append(f"❌ {file_path}: {result_or_error}")
+                            failed_files.append(file_path)
+                            overall_success = False
+                            success = False  # 标记为失败，跳出循环
+                            break
+                    else:
+                        # 没有确认信息或没有 agent，直接失败
+                        success = False
+                        result_or_error = iter_result_or_error
+                        break
+
+                if not success:
+                    # 处理失败，确保有错误信息
+                    if confirm_iteration >= max_confirm_iterations:
+                        # 达到最大确认次数，可能陷入循环
+                        if not result_or_error:
+                            result_or_error = f"处理失败：达到最大确认次数限制（{max_confirm_iterations}），可能存在循环确认问题"
+                    elif not result_or_error:
+                        # 如果没有设置错误信息，使用默认错误信息
+                        result_or_error = "处理失败：未知错误"
+
+                    # 处理失败
+                    if backup_path and os.path.exists(backup_path):
+                        try:
+                            os.remove(backup_path)
+                        except Exception:
+                            pass
+                    all_results.append(f"❌ {file_path}: {result_or_error}")
                     failed_files.append(file_path)
                     overall_success = False
                     continue
 
-                # 执行编辑
-                success, result = self._fast_edit(file_path, patches, agent)
+                # 编辑成功，继续写入文件
+                result_or_error = result_or_error  # 此时 result_or_error 是新内容
 
-                if success:
+                # 写入文件（失败时回滚）
+                abs_path = os.path.abspath(file_path)
+                (
+                    write_success,
+                    write_error,
+                ) = EditFileNormalTool._write_file_with_rollback(
+                    abs_path, result_or_error, backup_path
+                )
+                if write_success:
+                    # 写入成功，删除备份文件
+                    if backup_path and os.path.exists(backup_path):
+                        try:
+                            os.remove(backup_path)
+                        except Exception:
+                            pass
                     all_results.append(f"✅ {file_path}: 修改成功")
                     successful_files.append(file_path)
                 else:
-                    all_results.append(f"❌ {file_path}: {result}")
+                    all_results.append(f"❌ {file_path}: {write_error}")
                     failed_files.append(file_path)
                     overall_success = False
 
@@ -436,12 +720,12 @@ class EditFileTool:
                 output_lines.append(f"✅ 成功修改 {len(successful_files)} 个文件:")
                 for file_path in successful_files:
                     output_lines.append(f"   - {file_path}")
-            
+
             if failed_files:
                 output_lines.append(f"\n❌ 失败 {len(failed_files)} 个文件:")
                 for file_path in failed_files:
                     output_lines.append(f"   - {file_path}")
-            
+
             stdout_text = "\n".join(all_results)
             summary = "\n".join(output_lines) if output_lines else ""
 
@@ -452,615 +736,30 @@ class EditFileTool:
                     "stderr": "",
                 }
             else:
+                # 失败时，stderr 应该包含详细的错误信息，而不仅仅是文件列表
+                # 从 all_results 中提取失败文件的详细错误信息
+                failed_details = []
+                for result in all_results:
+                    if result.startswith("❌"):
+                        failed_details.append(result)
+
+                # 如果有详细的错误信息，使用它们；否则使用 summary
+                stderr_content = (
+                    "\n".join(failed_details)
+                    if failed_details
+                    else (summary if summary else "部分文件修改失败")
+                )
+
                 return {
                     "success": False,
                     "stdout": stdout_text + ("\n\n" + summary if summary else ""),
-                    "stderr": summary if summary else "部分文件修改失败",
+                    "stderr": stderr_content,
                 }
 
         except Exception as e:
             error_msg = f"文件编辑失败: {str(e)}"
-            print(f"❌ {error_msg}")
+            PrettyOutput.auto_print(f"❌ {error_msg}")
             return {"success": False, "stdout": "", "stderr": error_msg}
 
-    @staticmethod
-    def _read_file_with_backup(file_path: str) -> Tuple[str, Optional[str]]:
-        """读取文件并创建备份
-        
-        Args:
-            file_path: 文件路径
-            
-        Returns:
-            (文件内容, 备份文件路径或None)
-        """
-        abs_path = os.path.abspath(file_path)
-        os.makedirs(os.path.dirname(abs_path), exist_ok=True)
-        
-        file_content = ""
-        backup_path = None
-        if os.path.exists(abs_path):
-            with open(abs_path, "r", encoding="utf-8") as f:
-                file_content = f.read()
-            # 创建备份文件
-            backup_path = abs_path + ".bak"
-            try:
-                shutil.copy2(abs_path, backup_path)
-            except Exception:
-                # 备份失败不影响主流程
-                backup_path = None
-        
-        return file_content, backup_path
-
-    @staticmethod
-    def _order_patches_by_range(patches: List[Dict[str, str]]) -> List[Dict[str, str]]:
-        """按顺序返回补丁列表
-        
-        注意：对于结构化编辑，由于需要在实际应用时才能获取块的行号范围，
-        这里暂时按原始顺序返回。如果需要优化，可以在应用时动态排序。
-        
-        Args:
-            patches: 补丁列表
-            
-        Returns:
-            补丁列表（当前按原始顺序返回）
-        """
-        # 对于结构化编辑，暂时按原始顺序处理
-        # 如果需要按行号排序，需要在应用时动态获取块的行号范围
-        return patches
-
-
-    @staticmethod
-    def _restore_file_from_cache(cache_info: Dict[str, Any]) -> str:
-        """从缓存恢复文件内容
-        
-        Args:
-            cache_info: 缓存信息字典
-            
-        Returns:
-            恢复的文件内容字符串（与原始文件内容完全一致）
-        """
-        if not cache_info:
-            return ""
-        
-        # 按照 id_list 的顺序恢复
-        id_list = cache_info.get("id_list", [])
-        blocks = cache_info.get("blocks", {})
-        file_ends_with_newline = cache_info.get("file_ends_with_newline", False)
-        
-        result = []
-        for idx, block_id in enumerate(id_list):
-            block = blocks.get(block_id)
-            if block:
-                content = block.get('content', '')
-                if content:
-                    result.append(content)
-                    # 在块之间添加换行符（最后一个块后面根据文件是否以换行符结尾决定）
-                    is_last_block = (idx == len(id_list) - 1)
-                    if is_last_block:
-                        # 最后一个块：如果文件以换行符结尾，添加换行符
-                        if file_ends_with_newline:
-                            result.append('\n')
-                    else:
-                        # 非最后一个块：在块之间添加换行符
-                        result.append('\n')
-        
-        return ''.join(result) if result else ""
-
-    @staticmethod
-    def _apply_structured_edit_to_cache(
-        cache_info: Dict[str, Any],
-        block_id: str,
-        action: str,
-        new_content: Optional[str] = None,
-        search: Optional[str] = None,
-        replace: Optional[str] = None
-    ) -> Tuple[bool, Optional[str], Optional[EditErrorType]]:
-        """在缓存中应用结构化编辑
-        
-        Args:
-            cache_info: 缓存信息字典（会被修改）
-            block_id: 块id（字符串，从read_code工具获取）
-            action: 操作类型（delete, insert_before, insert_after, replace, edit）
-            new_content: 新内容（对于非delete和非edit操作）
-            search: 要搜索的文本（对于edit操作）
-            replace: 替换后的文本（对于edit操作）
-            
-        Returns:
-            (是否成功, 错误信息, 错误类型)
-        """
-        if not cache_info:
-            return (False, "缓存信息不完整", EditErrorType.CACHE_INVALID)
-        
-        # 从 blocks 字典中查找
-        blocks = cache_info.get("blocks", {})
-        block = blocks.get(block_id)
-        
-        if block is None:
-            return (False, f"未找到块id: {block_id}。请使用read_code工具查看文件的结构化块id。", EditErrorType.BLOCK_ID_NOT_FOUND)
-        
-        # 根据操作类型执行编辑
-        if action == "delete":
-            # 删除块：将当前块的内容清空
-            block['content'] = ""
-            return (True, None, None)
-        
-        elif action == "insert_before":
-            # 在块前插入：在当前块的内容前面插入文本
-            if new_content is None:
-                return (False, "insert_before操作需要提供content参数", EditErrorType.PARAMETER_MISSING)
-            
-            current_content = block.get('content', '')
-            # 自动添加换行符：在插入内容后添加换行符（如果插入内容不以换行符结尾）
-            if new_content and not new_content.endswith('\n'):
-                new_content = new_content + '\n'
-            block['content'] = new_content + current_content
-            return (True, None, None)
-        
-        elif action == "insert_after":
-            # 在块后插入：在当前块的内容后面插入文本
-            if new_content is None:
-                return (False, "insert_after操作需要提供content参数", EditErrorType.PARAMETER_MISSING)
-            
-            current_content = block.get('content', '')
-            # 自动添加换行符：在插入内容前添加换行符（如果插入内容不以换行符开头）
-            # 避免重复换行符：如果当前内容以换行符结尾，则不需要添加
-            if new_content and not new_content.startswith('\n'):
-                # 如果当前内容不以换行符结尾，则在插入内容前添加换行符
-                if not current_content or not current_content.endswith('\n'):
-                    new_content = '\n' + new_content
-            block['content'] = current_content + new_content
-            return (True, None, None)
-        
-        elif action == "replace":
-            # 替换块
-            if new_content is None:
-                return (False, "replace操作需要提供content参数", EditErrorType.PARAMETER_MISSING)
-            
-            block['content'] = new_content
-            return (True, None, None)
-        
-        elif action == "edit":
-            # 在块内进行search/replace
-            if search is None:
-                return (False, "edit操作需要提供search参数", EditErrorType.PARAMETER_MISSING)
-            if replace is None:
-                return (False, "edit操作需要提供replace参数", EditErrorType.PARAMETER_MISSING)
-            
-            current_content = block.get('content', '')
-            
-            # 检查匹配次数：必须刚好只有一处匹配
-            match_count = current_content.count(search)
-            if match_count == 0:
-                return (False, f"在块 {block_id} 中未找到要搜索的文本: {search[:100]}...", EditErrorType.SEARCH_NOT_FOUND)
-            elif match_count > 1:
-                # 找到所有匹配位置，并显示上下文
-                lines = current_content.split('\n')
-                matches_info = []
-                search_lines = search.split('\n')
-                search_line_count = len(search_lines)
-                
-                # 使用更精确的方法查找所有匹配位置（处理多行搜索）
-                start_pos = 0
-                match_idx = 0
-                while match_idx < match_count and start_pos < len(current_content):
-                    pos = current_content.find(search, start_pos)
-                    if pos == -1:
-                        break
-                    
-                    # 计算匹配位置所在的行号
-                    content_before_match = current_content[:pos]
-                    line_idx = content_before_match.count('\n')
-                    
-                    # 显示上下文（前后各2行）
-                    start_line = max(0, line_idx - 2)
-                    end_line = min(len(lines), line_idx + search_line_count + 2)
-                    context_lines = lines[start_line:end_line]
-                    context = '\n'.join([
-                        f"  {start_line + i + 1:4d}: {context_lines[i]}" 
-                        for i in range(len(context_lines))
-                    ])
-                    
-                    # 标记匹配的行
-                    match_start_in_context = line_idx - start_line
-                    match_end_in_context = match_start_in_context + search_line_count
-                    matches_info.append(f"匹配位置 {len(matches_info) + 1} (行 {line_idx + 1}):\n{context}")
-                    
-                    start_pos = pos + 1  # 继续查找下一个匹配
-                    match_idx += 1
-                    
-                    if len(matches_info) >= 5:  # 最多显示5个匹配位置
-                        break
-                
-                matches_preview = "\n\n".join(matches_info)
-                if match_count > len(matches_info):
-                    matches_preview += f"\n\n... 还有 {match_count - len(matches_info)} 处匹配未显示"
-                
-                search_preview = search[:100] + "..." if len(search) > 100 else search
-                error_msg = (
-                    f"在块 {block_id} 中找到 {match_count} 处匹配，但 edit 操作要求刚好只有一处匹配。\n"
-                    f"搜索文本: {search_preview}\n\n"
-                    f"匹配位置详情:\n{matches_preview}\n\n"
-                    f"💡 提示：请提供更多的上下文（如包含前后几行代码）来唯一标识要替换的位置。"
-                )
-                return (False, error_msg, EditErrorType.MULTIPLE_MATCHES)
-            
-            # 在块内进行替换（只替换第一次出现，此时已经确认只有一处）
-            block['content'] = current_content.replace(search, replace, 1)
-            return (True, None, None)
-        
-        else:
-            return (False, f"不支持的操作类型: {action}", EditErrorType.UNSUPPORTED_ACTION)
-
-    @staticmethod
-    def _format_patch_description(patch: Dict[str, str]) -> str:
-        """格式化补丁描述用于错误信息
-        
-        Args:
-            patch: 补丁字典
-            
-        Returns:
-            补丁描述字符串
-        """
-        if "STRUCTURED_BLOCK_ID" in patch:
-            block_id = patch.get('STRUCTURED_BLOCK_ID', '')
-            action = patch.get('STRUCTURED_ACTION', '')
-            if action == "edit":
-                search = patch.get('STRUCTURED_SEARCH', '')
-                replace = patch.get('STRUCTURED_REPLACE', '')
-                search_preview = search[:50] + "..." if len(search) > 50 else search
-                replace_preview = replace[:50] + "..." if len(replace) > 50 else replace
-                return f"结构化编辑: block_id={block_id}, action={action}, search={search_preview}, replace={replace_preview}"
-            else:
-                content = patch.get('STRUCTURED_CONTENT', '')
-                if content:
-                    content_preview = content[:100] + "..." if len(content) > 100 else content
-                    return f"结构化编辑: block_id={block_id}, action={action}, content={content_preview}"
-                else:
-                    return f"结构化编辑: block_id={block_id}, action={action}"
-        else:
-            return "未知的补丁格式"
-
-    @staticmethod
-    def _generate_error_summary(
-        abs_path: str,
-        failed_patches: List[Dict[str, Any]],
-        patch_count: int,
-        successful_patches: int
-    ) -> str:
-        """生成错误摘要
-        
-        Args:
-            abs_path: 文件绝对路径
-            failed_patches: 失败的补丁列表
-            patch_count: 总补丁数
-            successful_patches: 成功的补丁数
-            
-        Returns:
-            错误摘要字符串
-        """
-        error_details = []
-        has_block_id_error = False  # 是否有块id相关错误
-        has_cache_error = False  # 是否有缓存相关错误
-        has_multiple_matches_error = False  # 是否有多处匹配错误
-        has_other_error = False  # 是否有其他错误
-        
-        for p in failed_patches:
-            patch = p["patch"]
-            patch_desc = EditFileTool._format_patch_description(patch)
-            error_msg = p['error']
-            error_type = p.get('error_type')  # 获取错误类型（如果存在）
-            error_details.append(f"  - 失败的补丁: {patch_desc}\n    错误: {error_msg}")
-            
-            # 优先使用错误类型进行判断（如果存在），否则回退到字符串匹配
-            if error_type:
-                if error_type == EditErrorType.BLOCK_ID_NOT_FOUND:
-                    has_block_id_error = True
-                elif error_type == EditErrorType.CACHE_INVALID:
-                    has_cache_error = True
-                elif error_type == EditErrorType.MULTIPLE_MATCHES:
-                    has_multiple_matches_error = True
-                else:
-                    has_other_error = True
-            else:
-                # 回退到字符串匹配（兼容旧代码或异常情况）
-                error_msg_lower = error_msg.lower()
-                
-                # 块id相关错误：检查是否包含"块id"和"未找到"/"不存在"/"找不到"等关键词
-                if ("块id" in error_msg or "block_id" in error_msg_lower or "block id" in error_msg_lower) and (
-                    "未找到" in error_msg or "不存在" in error_msg or "找不到" in error_msg or 
-                    "not found" in error_msg_lower
-                ):
-                    has_block_id_error = True
-                # 缓存相关错误：检查是否包含"缓存"或"cache"关键词
-                elif ("缓存" in error_msg or "cache" in error_msg_lower) and (
-                    "信息不完整" in error_msg or "无效" in error_msg or "过期" in error_msg or
-                    "invalid" in error_msg_lower or "expired" in error_msg_lower
-                ):
-                    has_cache_error = True
-                # 多处匹配错误：检查是否包含"匹配"和数量相关的关键词
-                elif ("匹配" in error_msg or "match" in error_msg_lower) and (
-                    "处" in error_msg or "个" in error_msg or "multiple" in error_msg_lower or
-                    ("找到" in error_msg and ("处" in error_msg or "个" in error_msg))
-                ):
-                    # 识别多处匹配错误（错误消息中已经包含了详细提示）
-                    has_multiple_matches_error = True
-                else:
-                    has_other_error = True
-        
-        if successful_patches == 0:
-            summary = (
-                f"文件 {abs_path} 修改失败（全部失败，文件未修改）。\n"
-                f"失败: {len(failed_patches)}/{patch_count}.\n"
-                f"失败详情:\n" + "\n".join(error_details)
-            )
-        else:
-            summary = (
-                f"文件 {abs_path} 修改部分成功。\n"
-                f"成功: {successful_patches}/{patch_count}, "
-                f"失败: {len(failed_patches)}/{patch_count}.\n"
-                f"失败详情:\n" + "\n".join(error_details)
-            )
-        
-        # 根据错误类型添加不同的提示
-        # 注意：多处匹配错误的错误消息中已经包含了详细提示，不需要额外添加
-        hints = []
-        if has_block_id_error:
-            hints.append("💡 块id不存在：请检查块id是否正确，或使用 read_code 工具重新读取文件以获取最新的块id列表。")
-        if has_cache_error:
-            hints.append("💡 缓存问题：文件可能已被外部修改，请使用 read_code 工具重新读取文件。")
-        if has_other_error and not (has_block_id_error or has_cache_error or has_multiple_matches_error):
-            hints.append("💡 提示：请检查块id、操作类型和参数是否正确。")
-        
-        if hints:
-            summary += "\n\n" + "\n".join(hints)
-        
-        return summary
-
-    @staticmethod
-    def _write_file_with_rollback(
-        abs_path: str,
-        content: str,
-        backup_path: Optional[str]
-    ) -> Tuple[bool, Optional[str]]:
-        """写入文件，失败时回滚
-        
-        Args:
-            abs_path: 文件绝对路径
-            content: 要写入的内容
-            backup_path: 备份文件路径或None
-            
-        Returns:
-            (是否成功, 错误信息或None)
-        """
-        try:
-            with open(abs_path, "w", encoding="utf-8") as f:
-                f.write(content)
-            return (True, None)
-        except Exception as write_error:
-            # 写入失败，尝试回滚
-            if backup_path and os.path.exists(backup_path):
-                try:
-                    shutil.copy2(backup_path, abs_path)
-                    os.remove(backup_path)
-                except Exception:
-                    pass
-            error_msg = f"文件写入失败: {str(write_error)}"
-            print(f"❌ {error_msg}")
-            return (False, error_msg)
-
-    @staticmethod
-    def _fast_edit(file_path: str, patches: List[Dict[str, str]], agent: Any = None) -> Tuple[bool, str]:
-        """快速应用补丁到文件
-
-        该方法基于缓存进行编辑：
-        1. 先检查缓存有效性，无效则提示重新读取
-        2. 在缓存中应用所有补丁
-        3. 从缓存恢复文件内容并写入
-        4. 更新缓存的时间戳
-
-        Args:
-            file_path: 要修改的文件路径，支持绝对路径和相对路径
-            patches: 补丁列表，每个补丁包含 STRUCTURED_BLOCK_ID
-            agent: Agent实例，用于访问缓存
-
-        Returns:
-            Tuple[bool, str]:
-                返回处理结果元组，第一个元素表示是否所有补丁都成功应用，
-                第二个元素为结果信息，全部成功时为修改后的文件内容，部分或全部失败时为错误信息
-        """
-        abs_path = os.path.abspath(file_path)
-        backup_path = None
-        
-        try:
-            # 检查缓存有效性
-            cache_info = EditFileTool._get_file_cache(agent, abs_path)
-            if not EditFileTool._is_cache_valid(cache_info, abs_path):
-                error_msg = (
-                    f"⚠️ 缓存无效或文件已被外部修改。\n"
-                    f"📋 文件: {abs_path}\n"
-                    f"💡 请先使用 read_code 工具重新读取文件，然后再进行编辑。"
-                )
-                return False, error_msg
-            
-            # 创建缓存副本，避免直接修改原缓存
-            cache_copy = {
-                "id_list": list(cache_info["id_list"]),  # 浅拷贝列表
-                "blocks": {k: v.copy() for k, v in cache_info["blocks"].items()},  # 深拷贝字典
-                "total_lines": cache_info["total_lines"],
-                "read_time": cache_info.get("read_time", time.time()),
-                "file_mtime": cache_info.get("file_mtime", 0),
-                "file_ends_with_newline": cache_info.get("file_ends_with_newline", False),
-            }
-            
-            # 创建备份
-            if os.path.exists(abs_path):
-                backup_path = abs_path + ".bak"
-                try:
-                    shutil.copy2(abs_path, backup_path)
-                except Exception:
-                    backup_path = None
-            
-            # 对补丁进行排序
-            ordered_patches = EditFileTool._order_patches_by_range(patches)
-            patch_count = len(ordered_patches)
-            failed_patches: List[Dict[str, Any]] = []
-            successful_patches = 0
-            
-            # 在缓存中应用所有补丁
-            for patch in ordered_patches:
-                # 结构化编辑模式
-                if "STRUCTURED_BLOCK_ID" in patch:
-                    block_id = patch.get("STRUCTURED_BLOCK_ID", "")
-                    action = patch.get("STRUCTURED_ACTION", "")
-                    new_content = patch.get("STRUCTURED_CONTENT")
-                    search = patch.get("STRUCTURED_SEARCH")
-                    replace = patch.get("STRUCTURED_REPLACE")
-                    try:
-                        success, error_msg, error_type = EditFileTool._apply_structured_edit_to_cache(
-                            cache_copy, block_id, action, new_content, search, replace
-                        )
-                        if success:
-                            successful_patches += 1
-                        else:
-                            failed_patches.append({"patch": patch, "error": error_msg, "error_type": error_type})
-                    except Exception as e:
-                        error_msg = (
-                            f"结构化编辑执行出错: {str(e)}\n"
-                            f"block_id: {block_id}, action: {action}"
-                        )
-                        failed_patches.append({"patch": patch, "error": error_msg, "error_type": EditErrorType.OTHER})
-                else:
-                    # 如果不支持的模式，记录错误
-                    error_msg = "不支持的补丁格式。支持的格式: STRUCTURED_BLOCK_ID"
-                    failed_patches.append({"patch": patch, "error": error_msg, "error_type": EditErrorType.OTHER})
-            
-            # 如果有失败的补丁，且没有成功的补丁，则不写入文件
-            if failed_patches and successful_patches == 0:
-                if backup_path and os.path.exists(backup_path):
-                    try:
-                        os.remove(backup_path)
-                    except Exception:
-                        pass
-                summary = EditFileTool._generate_error_summary(
-                    abs_path, failed_patches, patch_count, successful_patches
-                )
-                print(f"❌ {summary}")
-                return False, summary
-            
-            # 从缓存恢复文件内容
-            modified_content = EditFileTool._restore_file_from_cache(cache_copy)
-            if not modified_content:
-                error_msg = (
-                    "从缓存恢复文件内容失败。\n"
-                    "可能原因：缓存数据结构损坏或文件结构异常。\n\n"
-                    "💡 提示：请使用 read_code 工具重新读取文件，然后再进行编辑。"
-                )
-                if backup_path and os.path.exists(backup_path):
-                    try:
-                        os.remove(backup_path)
-                    except Exception:
-                        pass
-                return False, error_msg
-            
-            # 写入文件
-            success, error_msg = EditFileTool._write_file_with_rollback(abs_path, modified_content, backup_path)
-            if not success:
-                # 写入失败通常是权限、磁盘空间等问题，不需要重新读取文件
-                error_msg += (
-                    "\n\n💡 提示：文件写入失败，可能是权限不足、磁盘空间不足或文件被锁定。"
-                    "请检查文件权限和磁盘空间，或稍后重试。"
-                )
-                return False, error_msg
-            
-            # 写入成功，更新缓存
-            if agent:
-                cache = agent.get_user_data("read_code_cache")
-                if cache and abs_path in cache:
-                    # 更新缓存内容
-                    cache[abs_path] = cache_copy
-                    # 更新缓存时间戳
-                    EditFileTool._update_cache_timestamp(agent, abs_path)
-                    agent.set_user_data("read_code_cache", cache)
-            
-            # 写入成功，删除备份文件
-            if backup_path and os.path.exists(backup_path):
-                try:
-                    os.remove(backup_path)
-                except Exception:
-                    pass
-            
-            # 如果有失败的补丁，返回部分成功信息
-            if failed_patches:
-                summary = EditFileTool._generate_error_summary(
-                    abs_path, failed_patches, patch_count, successful_patches
-                )
-                print(f"❌ {summary}")
-                return False, summary
-            
-            return True, modified_content
-            
-        except Exception as e:
-            # 发生异常时，尝试回滚
-            if backup_path and os.path.exists(backup_path):
-                try:
-                    shutil.copy2(backup_path, abs_path)
-                    os.remove(backup_path)
-                except Exception:
-                    pass
-            
-            # 根据异常类型给出不同的提示
-            error_type = type(e).__name__
-            error_str = str(e)
-            
-            # 检查是否是权限错误
-            is_permission_error = (
-                error_type == "PermissionError" or
-                (error_type == "OSError" and hasattr(e, 'errno') and e.errno == 13) or
-                "Permission denied" in error_str or
-                "权限" in error_str or
-                "permission" in error_str.lower()
-            )
-            
-            # 检查是否是磁盘空间错误
-            is_space_error = (
-                (error_type == "OSError" and hasattr(e, 'errno') and e.errno == 28) or
-                "No space left" in error_str or
-                "No space" in error_str or
-                "ENOSPC" in error_str or
-                "磁盘" in error_str or
-                "空间" in error_str
-            )
-            
-            # 检查是否是文件不存在错误
-            is_not_found_error = (
-                error_type == "FileNotFoundError" or
-                (error_type == "OSError" and hasattr(e, 'errno') and e.errno == 2) or
-                "No such file" in error_str or
-                "文件不存在" in error_str
-            )
-            
-            # 检查是否是缓存或块相关错误（这些通常是我们自己的错误消息）
-            is_cache_error = (
-                "cache" in error_str.lower() or
-                "缓存" in error_str or
-                "未找到块id" in error_str or
-                "块id" in error_str
-            )
-            
-            if is_permission_error:
-                hint = "💡 提示：文件权限不足，请检查文件权限或使用管理员权限运行。"
-            elif is_space_error:
-                hint = "💡 提示：磁盘空间不足，请清理磁盘空间后重试。"
-            elif is_not_found_error:
-                hint = "💡 提示：文件不存在，请检查文件路径是否正确。"
-            elif is_cache_error:
-                hint = "💡 提示：缓存或块id相关错误，请使用 read_code 工具重新读取文件，然后再进行编辑。"
-            elif "block" in error_str.lower() or "块" in error_str:
-                hint = "💡 提示：块操作错误，请使用 read_code 工具重新读取文件，然后再进行编辑。"
-            else:
-                hint = f"💡 提示：发生未知错误（{error_type}），请检查错误信息或重试。如问题持续，请使用 read_code 工具重新读取文件。"
-            
-            error_msg = f"文件修改失败: {error_str}\n\n{hint}"
-            print(f"❌ {error_msg}")
-            return False, error_msg
 
+__all__ = ["EditFileNormalTool"]