1. 从“聊天”到“实干”：为什么文件读写是AI Agent的质变点

如果你已经跟着前面的教程，成功搭建了一个能说会道的Claude Code，那么恭喜你，你已经迈出了从零到一的关键一步。但此刻，你可能会发现一个尴尬的现实：这个Agent就像一个被关在玻璃房里的天才，它能跟你天马行空地讨论代码逻辑，分析问题头头是道，但当你真正需要它帮你修改一个配置文件、整理一个项目目录，或者分析一份日志时，它却只能“纸上谈兵”，告诉你“你应该这样做”，然后就没有然后了。

这就是“双手篇”要解决的核心问题。我们之前构建的Agent，本质上是一个强大的“思考大脑”（基于ReAct框架的推理和规划能力），但它缺乏与现实世界交互的“双手”。文件读写能力，就是这第一双，也是最重要的一双手。没有它，Agent的所有分析和规划都只是空中楼阁；有了它，Agent才真正从一个“顾问”升级为一个“实干家”，能够自主地、按步骤地操作你电脑上的文件系统，完成从代码生成、文件整理到数据清洗等一系列实际任务。

网络上热门的“Claude Code使用教程”或“AI Agent搭建”，很多都停留在调用API、进行对话的层面。而“赋予读写文件的能力”这一步，才是区分玩具与工具的关键。这不仅仅是添加一个功能，而是为Agent打开了通往“自动化”和“工具调用”世界的大门。理解了这一点，你就能明白为什么诸如“ReAct”、“Agent框架”、“工具调用”这些关键词总是和文件操作紧密联系在一起——它们是构成一个实用AI工作流的核心要素。

2. 核心原理拆解：ReAct框架下的工具调用机制

在动手之前，我们必须先搞清楚Claude Code（或者说，基于类似架构的Agent）是如何“思考”并“使用工具”的。这背后的核心是ReAct（Reasoning + Acting）框架。它不是某个具体的库，而是一种设计范式。

2.1 ReAct的工作循环：思考、行动、观察

你可以把ReAct理解为一个智能体的基本工作流程：

1. 思考（Reason）：基于当前的任务和已有的观察（比如你提的问题、之前工具执行的结果），模型推理出下一步应该做什么。它会生成一段包含“思考过程”和“行动决定”的文本。
2. 行动（Act）：根据上一步的决定，模型选择一个合适的工具（Tool）并调用它，同时生成调用这个工具所需的精确参数。例如，act: read_file(path=“./config.yaml”)。
3. 观察（Observe）：工具执行完毕，将结果（成功的信息或错误信息）返回给模型。这个结果成为新的“观察”。
4. 循环：模型基于新的观察，再次进入“思考”步骤，决定下一步行动，如此循环，直到任务完成或无法继续。

在这个过程中，“文件读写”就是我们提供给Agent的“工具”。我们的核心工作，就是按照框架要求的格式，定义好这些工具，并教会Agent在什么情况下、如何使用它们。

2.2 工具（Tool）的定义与注册

一个工具本质上是一个函数。要让Agent能调用它，我们需要做三件事：

1. 函数实现：用Python写一个真正能读写文件的函数，包含清晰的参数和返回值。
2. 格式描述：用自然语言清晰地描述这个工具是干什么的、需要什么参数、每个参数是什么意思。这部分描述会被送给大模型（如Claude），帮助它理解何时该调用此工具。
3. 框架集成：将这个函数和它的描述，注册到你使用的Agent框架（例如LangChain、LlamaIndex或自定义框架）中，使其成为Agent“工具箱”里的一员。

以read_file工具为例：

• 函数实现：def read_file(path: str) -> str:，内部使用open(path, ‘r’, encoding=‘utf-8’)读取内容。
• 格式描述：“读取指定路径文件的内容。参数path: 文件的绝对或相对路径。”
• 框架集成：调用框架的tool_registry.register(read_file, description=…)方法。

当Agent在“思考”后决定要读取一个文件时，它就会生成类似act: read_file(path=“./project/README.md”)的指令，框架会截取这个指令，找到对应的read_file函数，传入参数“./project/README.md”并执行，最后将文件内容字符串作为“观察”返回给Agent进行下一步推理。

3. 实战：为你的Claude Code打造“文件读写双手”

假设我们基于一个简单的自定义框架（这是理解原理的最佳方式，而非直接使用封装过度的库），我们来一步步实现。

3.1 环境与依赖确认

首先，确保你的Python环境已经就绪。我们不需要特别的深度学习框架，核心是标准库和网络请求。

# 基础环境，假设你已安装Python 3.8+ pip install openai # 或 anthropic， 用于调用Claude API pip install pydantic # 用于数据验证和设置管理，非常推荐 pip install python-dotenv # 用于管理环境变量，保护你的API Key

我们将创建一个新的项目目录，例如claude_code_with_hands。

3.2 定义核心工具函数

在项目根目录下创建tools.py文件。这里我们将实现四个最基础、最核心的文件操作工具。

import os import json import yaml # 如果需要处理yaml，需安装`pip install pyyaml` from pathlib import Path from typing import Any, Optional, List import shutil class FileSystemTools: """文件系统工具集""" @staticmethod def read_file(file_path: str) -> str: """ 读取文本文件内容。 参数: file_path (str): 目标文件的路径（相对或绝对路径）。 返回: str: 文件的内容字符串。 异常: FileNotFoundError: 当文件不存在时抛出。 UnicodeDecodeError: 当文件编码非UTF-8且无法解码时抛出。 """ # 使用pathlib处理路径，更安全、跨平台 path = Path(file_path).resolve() # 解析为绝对路径 if not path.exists(): raise FileNotFoundError(f"文件不存在: {file_path}") if not path.is_file(): raise ValueError(f"路径不是一个文件: {file_path}") # 尝试UTF-8编码读取，这是现代文本文件最通用的编码 try: content = path.read_text(encoding='utf-8') except UnicodeDecodeError: # 如果UTF-8失败，可以尝试系统默认编码或更宽松的方式，这里简单抛错 # 在实际项目中，你可能需要更复杂的编码检测逻辑 raise UnicodeDecodeError(f"无法以UTF-8编码读取文件 {file_path}，请检查文件编码。") return content @staticmethod def write_file(file_path: str, content: str, append: bool = False) -> str: """ 将内容写入文本文件。 参数: file_path (str): 目标文件的路径。 content (str): 要写入的文本内容。 append (bool): 是否为追加模式。默认为False（覆盖模式）。 返回: str: 操作结果的成功信息。 """ path = Path(file_path).resolve() # 确保目标目录存在 path.parent.mkdir(parents=True, exist_ok=True) mode = 'a' if append else 'w' with path.open(mode=mode, encoding='utf-8') as f: f.write(content) action = "追加到" if append else "写入" return f"成功{action}文件: {file_path}" @staticmethod def list_directory(dir_path: str = “.”, recursive: bool = False) -> List[str]: """ 列出目录下的文件和文件夹。 参数: dir_path (str): 要列出的目录路径。默认为当前目录。 recursive (bool): 是否递归列出所有子目录内容。默认为False。 返回: List[str]: 文件/文件夹路径的列表。 """ path = Path(dir_path).resolve() if not path.exists(): raise FileNotFoundError(f"目录不存在: {dir_path}") if not path.is_dir(): raise ValueError(f"路径不是一个目录: {dir_path}") file_list = [] if recursive: # 使用rglob递归遍历 for p in path.rglob(“*”): # 相对路径显示更友好 try: rel_path = p.relative_to(path) except ValueError: rel_path = p file_list.append(str(rel_path)) else: for p in path.iterdir(): file_list.append(p.name) return file_list @staticmethod def file_exists(file_path: str) -> bool: """ 检查文件或目录是否存在。 参数: file_path (str): 要检查的路径。 返回: bool: 存在返回True，否则返回False。 """ path = Path(file_path) return path.exists()

注意：安全是重中之重！上述工具直接操作文件系统，必须施加限制。在生产环境中，绝对不要将工具的工作目录设置为根目录/或用户主目录。务必通过配置将其限制在特定的沙箱目录内，例如workspace/。我们会在后续的Agent配置中体现这一点。

3.3 构建工具描述供模型理解

模型不知道我们的Python函数是什么，它需要通过自然语言描述来理解工具。在tools.py中继续添加：

def get_file_tool_descriptions() -> list: """返回文件工具的自然语言描述列表，用于提示词（Prompt）""" tools = [ { “name”: “read_file”, “description”: “读取指定路径的文本文件，并返回其全部内容。当你需要查看配置文件、日志、源代码或文档内容时使用此工具。”, “parameters”: { “type”: “object”, “properties”: { “file_path”: { “type”: “string”, “description”: “要读取的文件的路径，可以是相对路径（相对于工作区）或绝对路径。” } }, “required”: [“file_path”] } }, { “name”: “write_file”, “description”: “创建或覆盖一个文本文件，写入提供的内容。也可用于追加内容到现有文件。当你需要生成代码、修改配置、保存结果或记录日志时使用此工具。”, “parameters”: { “type”: “object”, “properties”: { “file_path”: { “type”: “string”, “description”: “要写入的文件的路径。” }, “content”: { “type”: “string”, “description”: “要写入文件的文本内容。” }, “append”: { “type”: “boolean”, “description”: “如果为true，则将内容追加到文件末尾；如果为false或未提供，则覆盖文件。默认为false。”, “default”: False } }, “required”: [“file_path”, “content”] } }, { “name”: “list_directory”, “description”: “列出指定目录下的所有文件和文件夹名称。用于探索项目结构、查找特定文件或了解工作区内容。”, “parameters”: { “type”: “object”, “properties”: { “dir_path”: { “type”: “string”, “description”: “要列出的目录路径。默认为当前工作目录（‘.’）。” }, “recursive”: { “type”: “boolean”, “description”: “如果为true，则递归列出所有子目录中的内容；如果为false，则仅列出直接子项。默认为false。”, “default”: False } }, “required”: [] } }, { “name”: “file_exists”, “description”: “检查指定路径的文件或目录是否存在。在尝试读取或写入文件前，可用于进行安全检查或条件判断。”, “parameters”: { “type”: “object”, “properties”: { “file_path”: { “type”: “string”, “description”: “要检查的路径。” } }, “required”: [“file_path”] } } ] return tools

这些描述至关重要。description字段要清晰、具体，说明使用场景。parameters的定义要符合JSON Schema格式，这样像Claude这样的模型才能正确解析并生成调用参数。

3.4 创建Agent核心：集成工具与ReAct循环

现在，我们创建agent_core.py，这是大脑和双手的连接中枢。

import os import json import re from typing import Dict, Any, Callable, Optional from openai import OpenAI # 或 from anthropic import Anthropic from dotenv import load_dotenv from pathlib import Path # 加载环境变量，你的API Key应该放在`.env`文件中 load_dotenv() class CodeAgent: def __init__(self, model: str = “claude-3-haiku-20240307”, api_key: Optional[str] = None, workspace: str = “./workspace”): """ 初始化代码助手Agent。 参数: model: 使用的模型名称。 api_key: API密钥，如果为None则从环境变量读取。 workspace: Agent的工作区根目录，所有文件操作将被限制在此目录下（安全措施）。 """ self.model = model self.api_key = api_key or os.getenv(“ANTHROPIC_API_KEY”) # 或 OPENAI_API_KEY if not self.api_key: raise ValueError(“未提供API_KEY，请通过参数传入或设置环境变量`ANTHROPIC_API_KEY`。”) # 初始化客户端，这里以Claude为例 self.client = Anthropic(api_key=self.api_key) # 如果使用OpenAI，则改为：self.client = OpenAI(api_key=self.api_key) # 设置安全的工作区 self.workspace = Path(workspace).resolve() self.workspace.mkdir(exist_ok=True) print(f“Agent工作区已设置为: {self.workspace}”) # 工具映射：将工具名映射到实际的函数 self.tools: Dict[str, Callable] = {} # 工具描述：用于构造提示词 self.tool_descriptions = [] self._init_tools() def _init_tools(self): """初始化文件工具集""" from tools import FileSystemTools, get_file_tool_descriptions # 注册工具函数 self.tools[“read_file”] = self._safe_wrapper(FileSystemTools.read_file) self.tools[“write_file”] = self._safe_wrapper(FileSystemTools.write_file) self.tools[“list_directory”] = self._safe_wrapper(FileSystemTools.list_directory) self.tools[“file_exists”] = self._safe_wrapper(FileSystemTools.file_exists) # 获取工具描述 self.tool_descriptions = get_file_tool_descriptions() def _safe_wrapper(self, func: Callable) -> Callable: """包装工具函数，增加路径安全检查和错误处理""" def wrapper(**kwargs): # 重点：安全检查！确保所有文件操作都在workspace内 if ‘file_path’ in kwargs: requested_path = Path(kwargs[‘file_path’]) # 如果请求的是绝对路径，将其转换为相对于workspace的路径（如果它在workspace下） # 更严格的策略：只允许相对路径，并直接拼接在workspace后 safe_path = self.workspace / requested_path # 防止目录遍历攻击：确保解析后的路径仍在workspace内 try: safe_path.resolve().relative_to(self.workspace.resolve()) except ValueError: raise PermissionError(f“访问路径 {requested_path} 被拒绝，因为它超出了工作区范围 {self.workspace}。”) kwargs[‘file_path’] = str(safe_path) elif ‘dir_path’ in kwargs: # 对list_directory做类似处理 requested_dir = kwargs.get(‘dir_path’, ‘.’) safe_dir = self.workspace / requested_dir try: safe_dir.resolve().relative_to(self.workspace.resolve()) except ValueError: raise PermissionError(f“访问目录 {requested_dir} 被拒绝，因为它超出了工作区范围 {self.workspace}。”) kwargs[‘dir_path’] = str(safe_dir) try: result = func(**kwargs) return result except Exception as e: # 返回错误信息，供模型观察 return f“工具执行出错: {type(e).__name__}: {str(e)}” return wrapper def _parse_model_response(self, response: str) -> tuple: """ 解析模型的响应，提取思考（Thought）和行动（Action）。 这是一个简单的解析器，实际应用可能需要更健壮的实现（如使用正则表达式或解析JSON）。 假设模型响应格式为： Thought: <思考内容> Action: <工具名>(<参数JSON>) """ thought = “” action = None action_args = {} lines = response.strip().split(‘\n’) for line in lines: if line.startswith(‘Thought:’): thought = line[8:].strip() elif line.startswith(‘Action:’): action_part = line[7:].strip() # 简单匹配，例如 Action: read_file({“file_path”: “test.txt”}) match = re.match(r‘(\w+)\((.*)\)’, action_part) if match: action = match.group(1) try: # 尝试解析参数为JSON args_str = match.group(2) action_args = json.loads(args_str) except json.JSONDecodeError: # 如果不是标准JSON，可能是简单字符串，这里简化处理 action_args = {“input”: args_str} return thought, action, action_args def run(self, task: str, max_steps: int = 10) -> str: """ 运行Agent处理一个任务。 参数: task: 用户提出的任务描述。 max_steps: 最大ReAct循环步数，防止无限循环。 返回: str: 任务的最终结果或总结。 """ print(f“\n=== 开始处理任务 ===\n任务: {task}”) # 构建系统提示词，包含工具描述和ReAct格式指令 system_prompt = f“”” 你是一个专业的编程助手，可以调用工具来操作文件系统。 你的工作区根目录是：{self.workspace} 你可以使用的工具： {json.dumps(self.tool_descriptions, indent=2)} 请严格按照以下格式回应： 1. 首先进行思考（Thought），分析当前情况和下一步计划。 2. 如果需要调用工具，则写一行 Action: <工具名>(<参数JSON>) 3. 工具调用结果会以‘Observation:’开头的形式提供给你。 4. 基于观察结果，继续思考，直到任务完成或无法继续。 5. 当任务完成时，用‘Final Answer:’开头给出最终答案。 现在，开始处理用户任务。 “”” messages = [ {“role”: “system”, “content”: system_prompt}, {“role”: “user”, “content”: task} ] for step in range(max_steps): print(f“\n--- 步骤 {step + 1} ---”) # 调用模型获取响应 try: response = self.client.messages.create( model=self.model, max_tokens=2048, messages=messages ) # 注意：Anthropic API返回结构可能与OpenAI不同，此处为示意 # 实际应根据API响应调整，例如 response.content[0].text model_output = response.content[0].text except Exception as e: return f“调用模型API失败: {e}” print(f“模型原始输出:\n{model_output}”) # 解析输出 thought, action, action_args = self._parse_model_response(model_output) if thought: print(f“Thought: {thought}”) # 检查是否是最终答案 if ‘Final Answer:’ in model_output: final_answer = model_output.split(‘Final Answer:’, 1)[1].strip() print(f“\n=== 任务完成 ===\n最终答案: {final_answer}”) return final_answer # 执行工具调用 if action and action in self.tools: print(f“Action: {action}({action_args})”) tool_func = self.tools[action] try: # 执行工具 observation = tool_func(**action_args) # 如果返回的是列表（如list_directory），将其转换为易读的字符串 if isinstance(observation, list): observation = ‘\n’.join(observation) except Exception as e: observation = f“工具调用异常: {e}” print(f“Observation: {observation}”) # 将观察结果添加到消息历史中，供模型下一轮思考 messages.append({“role”: “assistant”, “content”: model_output}) messages.append({“role”: “user”, “content”: f“Observation: {observation}”}) else: # 如果没有有效的Action，可能是模型在纯思考或格式错误 # 将当前输出作为assistant回复，并等待用户（或系统）下一步输入 # 这里我们简单地将无效行动视为观察，并提示模型 observation = “未识别到有效的Action格式。请确保使用‘Action: 工具名(参数JSON)’的格式调用工具。” print(f“Observation: {observation}”) messages.append({“role”: “assistant”, “content”: model_output}) messages.append({“role”: “user”, “content”: f“Observation: {observation}”}) return f“达到最大步数 ({max_steps}) 仍未完成任务。请检查任务是否过于复杂，或模型是否需要更清晰的指令。”

3.5 创建主程序并测试

最后，创建main.py来驱动一切。

from agent_core import CodeAgent def main(): # 初始化Agent，指定工作区 agent = CodeAgent( model=“claude-3-haiku-20240307”, # 根据你的API选择模型 workspace=“./my_workspace” # 所有文件操作将限制在此目录下 ) # 测试任务1：探索工作区并创建一个文件 print(“\n>>> 测试任务1: 列出工作区，然后创建欢迎文件”) result1 = agent.run(“请先列出当前工作区目录的内容，然后创建一个名为welcome.txt的文件，内容写上‘Hello from Claude Code!’”) # 测试任务2：读取并修改文件 print(“\n>>> 测试任务2: 读取刚才的文件并追加内容”) result2 = agent.run(“请读取welcome.txt文件的内容，然后在文件末尾追加一行‘This is written by an AI Agent.’”) # 测试任务3：一个更复杂的任务 print(“\n>>> 测试任务3: 创建一个简单的Python项目结构”) result3 = agent.run(“”” 请在工作区内完成以下操作： 1. 创建一个名为‘my_project’的文件夹。 2. 在my_project文件夹内，创建一个‘src’文件夹和一个‘tests’文件夹。 3. 在src文件夹内，创建一个‘main.py’文件，内容是一个简单的‘Hello World’程序。 4. 在项目根目录（my_project）创建一个‘README.md’文件，简要描述这个项目。 5. 最后，列出my_project的完整目录结构。 “””) if __name__ == “__main__”: main()

运行python main.py，你将看到Agent一步步地思考、调用工具、观察结果，最终完成任务。你的./my_workspace目录下会出现它创建的所有文件和文件夹。

4. 避坑指南与实战心得

第一次成功运行固然令人兴奋，但真正的挑战和精髓往往藏在细节里。以下是我在实现和调试这类文件操作Agent时积累的一些关键心得。

4.1 路径安全：绝不能忽视的“第一道闸”

在_safe_wrapper函数中实现的路径安全检查，是整个系统的生命线。这里有几个容易踩的坑：

• 相对路径的陷阱：用户请求file_path: “../../../etc/passwd”。如果你只是简单地将用户输入直接拼接在工作区后，self.workspace / “../../../etc/passwd”经过resolve()解析后，可能会跳出工作区。我们的防御代码safe_path.resolve().relative_to(self.workspace.resolve())正是为了捕获这种“目录遍历攻击”。如果路径无法转换为相对于工作区的路径，就会抛出ValueError，我们将其转化为PermissionError拒绝访问。
• 符号链接（Symlink）：如果工作区内存在指向外部目录的符号链接，通过它可能访问到外部文件。更严格的安全策略需要在工具函数中（或包装器里）检查safe_path.is_symlink()并解析其真实目标，确保目标也在工作区内。对于高安全要求场景，可以考虑在启动时禁用符号链接跟随。
• 工作区权限：确保运行Agent的进程对workspace目录只有必要的读写权限，没有执行权限或其他敏感目录的权限。

4.2 模型指令与提示工程：教会它“如何思考”

系统提示词（system_prompt）的质量直接决定了Agent能否正确使用工具。常见的失败案例和调整策略：

• 模型不调用工具，直接回答：比如你让它“创建文件”，它却回复“你可以使用open()函数…”。这说明模型没有进入“工具调用模式”。解决方法：强化指令。在提示词开头使用强引导句，如“你必须通过调用上述工具来完成任务。禁止直接给出操作建议，请直接执行。”同时，确保工具描述清晰，包含“当你需要…时使用此工具”这样的场景化语言。
• 参数格式错误：模型生成Action: read_file(./test.txt)，而你的解析器期望JSON格式Action: read_file({“file_path”: “./test.txt”})。解决方法：在示例（Few-shot）中明确展示格式。可以在system_prompt里加入一个完整的示例循环：

  示例： 用户：请查看当前目录下有什么文件。 助手： Thought: 用户想查看目录内容，我应该使用list_directory工具。 Action: list_directory({“dir_path”: “.”})

• 工具选择错误：比如该用write_file时用了read_file。这通常是因为工具描述不够区分度。解决方法：细化description，强调每个工具的独特用途。例如，write_file的description可以加上“此工具用于创建新文件或完全覆盖现有文件内容”，与append操作区分开。

4.3 错误处理与鲁棒性：让Agent更“坚韧”

工具执行总会出错，网络也可能中断。一个健壮的Agent需要妥善处理这些情况。

• 工具异常反馈：在_safe_wrapper中，我们用try…except捕获所有异常，并返回统一的错误信息格式（f“工具执行出错: {type(e).__name__}: {str(e)}”）。这比直接抛出异常崩溃要好，因为模型可以“观察”到这个错误，并有可能在下一步“思考”中纠正（例如，如果文件不存在，它可能先创建它）。
• 模型API容错：在run方法的API调用处，也有try…except。如果一次调用失败，可以考虑加入重试逻辑（例如，遇到速率限制错误时等待后重试），或者至少给用户一个友好的失败提示，而不是让整个程序崩溃。
• 状态管理：当前的简单实现中，每一轮对话都将全部历史消息发送给模型。对于长对话，这可能导致令牌数超限。进阶优化：可以实现消息窗口或摘要功能，只保留最近N条消息或对早期历史进行摘要，以节省上下文长度。

4.4 性能与扩展性思考

当工具变多、任务变复杂时，你需要考虑：

• 工具检索（Tool Retrieval）：当你有几十个工具时，把全部描述塞进提示词会占用大量上下文，且可能干扰模型。可以设计一个机制，让模型先输出它想做什么（“我想读写文件”），然后系统动态地只提供相关工具（文件读写类工具）的描述。
• 并行与异步：目前的ReAct循环是串行的。某些独立的任务（例如同时从多个URL获取数据）可以并行执行。你可以设计更复杂的Action格式来支持并行工具调用，但这需要更强大的模型（如Claude 3.5 Sonnet）和更复杂的框架来协调。
• 持久化与记忆：当前的Agent是“无状态”的，每次运行都是新的。为了实现跨会话的记忆，你需要将工作区的状态（文件内容）以及可能的重要交互历史保存下来，并在下次启动时加载。这涉及到更复杂的Agent架构设计。

5. 超越基础：从文件操作到真正的“Code Interpreter”

实现了基础的文件读写，你的Agent已经具备了强大的实操能力。但这仅仅是开始。沿着这个思路，你可以为它装备更多“双手”：

1. 终端命令执行：封装subprocess.run，让Agent能运行git,npm install,python script.py等命令。（警告：此工具极其危险，必须施加严格的命令白名单和权限控制）
2. 网络请求：封装requests库，让Agent能获取网页内容、调用外部API。
3. 数据库操作：封装简单的SQL查询或ORM操作，让Agent能读写数据库。
4. 代码分析与执行：集成一个安全的Python解释器沙箱（如piston或自定义docker环境），让Agent不仅能写代码，还能执行代码并获取输出。这才是真正意义上的“Claude Code”体验。

每增加一个工具，都重复“定义函数 -> 编写描述 -> 安全包装 -> 集成注册”的流程。你会发现，核心模式是不变的，变化的只是工具的具体能力。

当你把这些工具组合起来，并赋予Agent合理的规划能力（这很大程度上依赖于大模型本身的推理能力），它就能完成诸如“从GitHub拉取一个项目，安装依赖，运行测试，并将失败日志保存到文件”这样复杂的多步骤工作流。这时，它就不再是一个简单的聊天机器人，而是一个真正能替你处理繁琐事务的智能体。

回顾整个过程，我们从理解ReAct框架的原理出发，亲手实现了文件读写工具，并将其安全地集成到Agent中，最后通过实际的测试任务验证了其能力。最重要的是，我们深入探讨了其中的安全陷阱、调试技巧和扩展方向。现在，你的Claude Code已经拥有了“双手”，接下来，就看你如何指挥它去创造价值了。不妨从让它帮你整理桌面上的文档，或者自动生成每周的项目报告开始吧。