LLM 输出：          {            "name": "read_file",            "arguments": {"file_path": "/src/main.py"}          }          外部系统：          1. 解析这个请求          2. 执行 read_file("/src/main.py")          3. 把结果返回给 LLM

{  "name": "edit_file",  "description": "Edit a file by replacing a specific text section",  "parameters": {    "type": "object",    "properties": {      "file_path": {        "type": "string",        "description": "Absolute path to the file"      },      "old_str": {        "type": "string",        "description": "The text to search for and replace"      },      "new_str": {        "type": "string",        "description": "The text to replace with"      }    },    "required": ["file_path", "old_str", "new_str"]  }}

# read_file：支持 offset + limit，避免一次读取超大文件def read_file(file_path: str, offset: int = 1, limit: int = 2000) -> str:    """读取文件指定行范围"""    with open(file_path, 'r') as f:        lines = f.readlines()    return ''.join(lines[offset-1:offset-1+limit])# edit_file：基于搜索替换，比"覆盖整个文件"更安全def edit_file(file_path: str, old_str: str, new_str: str) -> str:    """精确替换文件中的文本片段"""    content = Path(file_path).read_text()    if old_str not in content:        return "Error: old_str not found in file"    new_content = content.replace(old_str, new_str, 1)  # 只替换第一个匹配    Path(file_path).write_text(new_content)    return "File edited successfully"

write_file 的风险：          Agent 需要输出整个文件内容 → 容易丢失代码 → 一次失误全毁          edit_file 的优势：          Agent 只需输出要修改的部分 → 改动最小化 → 出错范围可控

Agent 请求调用工具       ↓  ToolRouter       ↓  ┌────┼────┐  ↓    ↓    ↓文件工具 搜索工具 命令工具

class ToolRouter:    def register(self, tool: BaseTool) -> None:        """注册工具"""    def get_tool(self, name: str) -> BaseTool | None:        """按名称查找工具"""    def get_all_schemas(self) -> list[dict]:        """获取所有工具的 Schema（给 LLM 用）"""    async def execute(self, name: str, arguments: dict) -> ToolResult:        """执行工具"""

class BaseTool:    def requires_confirmation(self) -> bool:        """是否需要用户确认"""        return False  # 默认不需要class DeleteFileTool(BaseTool):    def requires_confirmation(self) -> bool:        return True  # 删除文件需要确认class RunCommandTool(BaseTool):    def requires_confirmation(self) -> bool:        return True  # 执行命令需要确认

Agent 请求 delete_file("/important/config.yaml")       ↓  requires_confirmation? → Yes       ↓  弹出确认框：Agent 想要删除 config.yaml，是否允许？       ↓  用户确认 → 执行  用户拒绝 → 返回 "User declined this operation"

BLOCKED_COMMANDS = [    "rm -rf /",       # 删除整个系统    "format C:",      # 格式化磁盘    "shutdown",        # 关机    "curl | bash",    # 远程执行脚本    "chmod 777",      # 危险权限]

def validate_path(file_path: str, allowed_dirs: list[str]) -> bool:    """确保文件操作只在允许的目录内"""    abs_path = os.path.abspath(file_path)    return any(abs_path.startswith(d) for d in allowed_dirs)

太粗：code_editor(action="modify", file="a.py", content="...")  → LLM 不知道有哪些 action，容易用错太细：insert_line(), delete_line(), replace_line(), append_line()  → 工具太多，LLM 选择困难适中：edit_file(old_str, new_str)  → 一个工具覆盖所有修改场景，参数语义清晰

# 不好：返回整个文件内容def grep(pattern, path):    # 返回所有匹配行 + 前后 10 行上下文    # 一个 grep 可能返回 5000 行# 好：限制返回行数def grep(pattern, path, max_results=50):    # 最多返回 50 行匹配结果

# 不好return "Error: file not found"# 好return "Error: file '/src/main.py' not found. Use list_directory('/src') to see available files."

# 不好description = "Read a file"# 好description = """Read file content. Use this when you need to:- Understand existing code before modifying it- Check current file state- Find specific code patternsAlways read a file BEFORE editing it."""