零基础复现Claude Code四双手篇——赋予读写文件的能力开篇从纸上谈兵到真刀真枪上一篇我们实现了ReAct循环的骨架——Agent已经会想了。它能输出Thought: 我需要读取main.py Action: read_file(main.py)但这只是一段文本文件并没有真的被读取。第3篇的成就我们实现了完整的ReAct循环——模型能思考、能输出Action、能看到Observation、能根据结果继续思考。但工具还是模拟的。回到实习生比喻现在的Agent就像一个只会嘴上说说的实习生。你问他“帮我修Bug。”他说“好的我需要先看看代码然后改一下最后跑测试。”你问“那你看了吗”他愣住了“呃…我只是说说而已我不知道怎么真的去看文件…”这一篇我们就要给实习生装上双手——让他真的能打开文件、修改文件。这一篇是整个系列的实操转折点——从模拟到真实从理论到实践。本节目标读完这篇文章你将理解工具调用的完整闭环从模型输出到函数执行到结果反馈的全流程实现真正的文件读写工具不再是硬编码而是真的操作文件系统掌握工具分发器的设计如何把字符串read_file(main.py)转换成真正的函数调用学会安全地操作文件避免误删、误改重要文件原理深潜工具调用的完整闭环 回到第一篇和第三篇的公式还记得我们在第一篇建立的公式吗循环 t 0, 1, 2, ... Thought_t, Action_t LLM(S_t) ← 第2篇解决了这部分 Observation_t Execute(Action_t) ← 第3篇实现了循环本篇实现真实执行 S_{t1} S_t (Thought_t, Action_t, Observation_t)第3篇我们实现了循环框架但Execute(Action_t)还是硬编码的模拟defexecute_action(self,action):ifread_fileinaction:return文件内容...# 假数据这一篇我们要实现真正的Execute(Action_t)defexecute_action(self,action):# 解析action字符串提取函数名和参数# 调用真正的read_file函数# 返回真实的文件内容工具调用闭环的4个步骤让我们用图解展示完整的闭环PC端完整版┌─────────────────────────────────────────────────────────┐ │ 步骤1模型输出 │ │ LLM → Thought: ...\nAction: read_file(main.py) │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 步骤2解析Action字符串 │ │ read_file(main.py) → { │ │ tool_name: read_file, │ │ args: [main.py] │ │ } │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 步骤3执行真实工具 │ │ 调用Python函数read_file(main.py) │ │ → 打开文件 → 读取内容 → 返回字符串 │ └─────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────┐ │ 步骤4格式化结果反馈给模型 │ │ Observation: 文件内容\ndef main():\n ... │ │ → 加入messages列表 → 模型看到结果 → 继续思考 │ └─────────────────────────────────────────────────────────┘手机端简化版模型输出 Action: read_file(main.py) ↓ 解析字符串 tool_nameread_file args[main.py] ↓ 执行真实函数 read_file(main.py) ↓ 返回结果 Observation: 文件内容... ↓ 反馈给模型关键洞察步骤2解析字符串是最容易出错的地方也是本篇的重点。两种工具定义方式的对比在真实的Agent系统中有两种主流的工具定义方式方式AJSON SchemaOpenAI Function Callingtools[{type:function,function:{name:read_file,description:读取文件内容,parameters:{type:object,properties:{path:{type:string,description:文件路径}},required:[path]}}}]优点模型直接输出JSON格式的工具调用不需要解析字符串缺点需要API支持Function Calling方式BPython函数签名我们的简化版defread_file(path:str)-str:读取文件内容withopen(path,r)asf:returnf.read()优点简单直观不依赖特殊API缺点需要解析模型输出的字符串我们的教学版用方式B因为它更容易理解模型输出什么我们怎么执行。动手实操实现真正的文件读写工具现在我们开始写代码。目标是替换第3篇中的硬编码模拟接入真实的文件操作。第一步实现read_file工具创建一个新文件tools.pyimportosdefread_file(path:str)-str: 读取文件内容 参数 path: 文件路径相对或绝对路径 返回 文件内容字符串 异常 如果文件不存在或无法读取返回错误信息 try:# 安全检查确保路径存在ifnotos.path.exists(path):returnf错误文件不存在 -{path}# 安全检查确保是文件而不是目录ifnotos.path.isfile(path):returnf错误{path}是一个目录不是文件# 读取文件内容withopen(path,r,encodingutf-8)asf:contentf.read()# 限制返回内容的长度避免超出Token限制MAX_LENGTH5000# 约1000个Tokeniflen(content)MAX_LENGTH:returnf{content[:MAX_LENGTH]}\n\n... (文件太长已截断共{len(content)}字符)returncontentexceptExceptionase:returnf错误无法读取文件 -{str(e)}代码解读用try-except捕获所有异常避免程序崩溃检查文件是否存在、是否是文件而不是目录限制返回内容长度避免超出模型的Token限制返回错误信息而不是抛出异常让Agent能看到错误并调整策略第二步实现write_file工具继续在tools.py中添加defwrite_file(path:str,content:str)-str: 写入文件内容 参数 path: 文件路径 content: 要写入的内容 返回 成功或错误信息 try:# 安全检查确保父目录存在parent_diros.path.dirname(path)ifparent_dirandnotos.path.exists(parent_dir):returnf错误父目录不存在 -{parent_dir}# 安全检查如果文件已存在先备份ifos.path.exists(path):backup_pathf{path}.backupwithopen(path,r,encodingutf-8)asf:backup_contentf.read()withopen(backup_path,w,encodingutf-8)asf:f.write(backup_content)# 写入文件withopen(path,w,encodingutf-8)asf:f.write(content)returnf成功文件已保存到{path}exceptExceptionase:returnf错误无法写入文件 -{str(e)}代码解读检查父目录是否存在避免写入到不存在的路径如果文件已存在先创建.backup备份防止误改用with open确保文件正确关闭第三步实现工具分发器核心这是本篇最关键的部分——如何把字符串read_file(main.py)转换成真正的函数调用继续在tools.py中添加importredefparse_action(action:str)-tuple: 解析Action字符串提取工具名和参数 参数 action: 字符串如 read_file(main.py) 或 write_file(test.py, content) 返回 (tool_name, args) 元组 例如(read_file, [main.py]) # 正则表达式解析工具名(参数1, 参数2, ...)# 匹配模式函数名 括号 参数列表matchre.match(r(\w)\((.*)\),action.strip())ifnotmatch:returnNone,[]tool_namematch.group(1)args_strmatch.group(2)# 解析参数列表# 安全注意使用ast.literal_eval而不是eval只能解析字面量防止代码注入ifargs_str.strip():try:importast# 将参数字符串包装成元组再解析argsast.literal_eval(f({args_str},))# 如果只有一个参数返回的是值本身需要转成列表ifnotisinstance(args,tuple):args(args,)returntool_name,list(args)except:returntool_name,[]returntool_name,[]defexecute_tool(action:str)-str: 执行工具调用 参数 action: 字符串如 read_file(main.py) 返回 工具执行结果字符串 # 步骤1解析action字符串tool_name,argsparse_action(action)iftool_nameisNone:returnf错误无法解析Action -{action}# 步骤2根据工具名分发到对应的函数iftool_nameread_file:iflen(args)!1:return错误read_file需要1个参数文件路径returnread_file(args[0])eliftool_namewrite_file:iflen(args)!2:return错误write_file需要2个参数文件路径, 内容returnwrite_file(args[0],args[1])else:returnf错误未知工具 -{tool_name}代码解读parse_action用正则表达式提取工具名和参数用eval解析参数简化版生产环境应该用ast.literal_evalexecute_tool根据工具名分发到对应的函数返回错误信息而不是抛出异常第四步集成到ReActAgent现在我们修改第3篇的react_agent.py替换硬编码的execute_action# 在文件开头导入tools模块fromtoolsimportexecute_toolclassReActAgent:# ... 其他代码保持不变 ...defexecute_action(self,action): 执行Action现在接入真实工具 参数 action: 字符串如 read_file(main.py) 返回 执行结果字符串 # 直接调用tools模块的execute_toolreturnexecute_tool(action)就这么简单我们只需要替换一个函数整个Agent就从模拟变成了真实。第五步测试真实的文件读写创建一个测试文件test_real_tools.pyfromreact_agentimportReActAgentimportos# 创建一个测试目录和测试文件os.makedirs(test_workspace,exist_okTrue)# 创建一个包含Bug的测试文件withopen(test_workspace/buggy.py,w)asf:f.write(def calculate(a, b): # Bug: 这里应该是加法但写成了减法 return a - b result calculate(5, 3) print(f5 3 {result}) )# 创建AgentagentReActAgent(max_iterations10)# 测试任务让Agent读取文件并找出Bugresultagent.run(请读取test_workspace/buggy.py文件找出里面的Bug并告诉我)print(\n*60)print(f最终结果{result})运行这段代码你会看到类似这样的输出用户请读取test_workspace/buggy.py文件找出里面的Bug并告诉我 [第 1 轮] Thought: 用户想让我读取buggy.py文件并找出Bug我应该先读取文件内容 Action: read_file(test_workspace/buggy.py) Observation: def calculate(a, b): # Bug: 这里应该是加法但写成了减法 return a - b result calculate(5, 3) print(f5 3 {result}) [第 2 轮] Thought: 我看到了Bug注释说应该是加法但代码写的是减法a - b。而且print语句也显示5 3但实际计算的是减法。 ✅ Answer: 找到Bug了在calculate函数中注释说应该是加法但代码写的是减法return a - b。应该改成 return a b。这会导致程序输出错误的结果5 - 3 2而不是5 3 8。 最终结果找到Bug了在calculate函数中注释说应该是加法但代码写的是减法return a - b。应该改成 return a b。这会导致程序输出错误的结果5 - 3 2而不是5 3 8。恭喜你的Agent现在真的能读取文件了⚠️ 安全警告必读⚠️在继续之前我们必须谈谈安全问题。让Agent能写文件是一把双刃剑——它能帮你修Bug也可能误删重要文件。安全原则在测试目录中运行# ✅ 好的做法os.chdir(test_workspace)# 切换到测试目录agent.run(帮我修Bug)# ❌ 危险的做法agent.run(帮我修Bug)# 在项目根目录运行可能误改重要文件写入前检查路径defwrite_file(path:str,content:str)-str:# 只允许写入test_workspace目录ifnotpath.startswith(test_workspace/):return错误只能写入test_workspace目录# ... 其他代码先用Git备份gitadd.gitcommit-m备份测试Agent前的状态# 现在可以放心测试了出问题就git reset --hard限制可执行的命令下一篇会讲# ❌ 危险允许任意命令run_cmd(rm -rf /)# ✅ 安全只允许只读命令ALLOWED_COMMANDS[ls,cat,grep,git status]真实案例一个误删文件的故事有个开发者让Agent清理临时文件Agent执行了Action:run_cmd(rm -rf temp*)结果把temp_important_data.json也删了。教训永远不要让Agent执行rm -rf写入/删除前先让Agent列出会影响哪些文件重要文件用Git管理与真实代码的对照在真实的Claude Code实现中rust版本这部分对应的是我们的实现真实代码位置关键差异read_file()crates/runtime/src/file_ops.rs的read_file()真实版支持二进制文件、大文件分块读取write_file()crates/runtime/src/file_ops.rs的write_file()真实版支持diff模式、权限检查execute_tool()crates/runtime/src/conversation.rs的ToolExecutortrait真实版用trait实现支持动态注册工具parse_action()不需要真实版用Function Calling API真实版模型直接输出JSON不需要解析字符串想深入研究的读者打开crates/runtime/src/file_ops.rs搜索pub fn read_file你会看到完整的文件操作逻辑打开crates/tools/src/lib.rs可以看到工具注册和分发的机制为什么我们用字符串解析真实版用JSON方案优点缺点适用场景字符串解析简单不依赖特殊API容易出错难以处理复杂参数教学版、原型Function Calling健壮模型直接输出结构化数据需要API支持生产环境我们的教学版用字符串解析是为了让你看清楚模型输出什么我们怎么执行。真实的Claude Code用OpenAI的Function Calling API或Anthropic的Tool Use API模型直接输出JSON格式的工具调用。工具设计的3个原则通过上面的实现我们总结出设计Agent工具的3个原则原则1工具应该返回字符串而不是抛出异常❌ 不好的设计defread_file(path):withopen(path,r)asf:# 文件不存在时抛出异常returnf.read()✅ 好的设计defread_file(path):try:withopen(path,r)asf:returnf.read()exceptFileNotFoundError:returnf错误文件不存在 -{path}为什么Agent需要看到错误信息才能调整策略。如果抛出异常循环就中断了。原则2工具应该有明确的输入输出格式❌ 不好的设计defprocess_file(path,modeNone,encodingNone,...):# 参数太多模型容易搞混✅ 好的设计defread_file(path:str)-str:读取文件内容defwrite_file(path:str,content:str)-str:写入文件内容为什么参数越简单模型越不容易出错。原则3工具应该有安全边界❌ 危险的设计defrun_cmd(cmd):returnsubprocess.run(cmd,shellTrue,capture_outputTrue).stdout✅ 安全的设计defrun_cmd(cmd):# 检查命令是否在白名单中ifnotis_safe_command(cmd):return错误不允许执行此命令# ... 执行命令为什么Agent可能会犯错安全边界能防止灾难性后果。 自检清单读完本篇请确认在进入下一篇之前请确认你能回答以下问题工具调用闭环的4个步骤是什么为什么工具应该返回字符串而不是抛出异常parse_action函数的作用是什么为什么需要限制read_file返回内容的长度你能说出3个让Agent写文件时的安全注意事项吗如果都能回答恭喜你Agent的双手部分你已经掌握了。下一篇见⚠️ 新手容易踩的坑坑1忘记处理文件不存在的情况后果Agent执行read_file时程序崩溃正确做法用try-except捕获异常返回错误信息坑2write_file没有创建父目录后果写入test/data/file.txt时如果test/data不存在会失败正确做法检查父目录是否存在或者用os.makedirs(parent_dir, exist_okTrue)坑3用eval解析参数时没有处理异常后果如果模型输出格式错误eval会抛出异常正确做法用try-except包裹eval或者用ast.literal_eval坑4没有限制文件读取的长度后果读取一个10MB的文件Token预算瞬间耗尽正确做法限制返回内容长度超过则截断下一步给Agent装上终端现在你已经学会了实现真正的文件读写工具设计工具分发器从字符串到函数调用处理工具执行中的异常设置安全边界但有一个关键能力还没有Agent还不能执行命令。比如Agent修改了代码后它不能自己运行pytest验证修改是否正确。它只能盲改然后等你手动测试。下一篇我们将实现终端工具——让Agent能够执行只读命令ls、cat、git status看到命令的输出根据输出调整策略这就是Agent从能改代码到能验证代码的关键一步。预告一个核心问题如何防止Agent执行危险命令如rm -rf答案在下一篇揭晓。系列进度✅ 第1篇总览与前置准备——Claude Code到底是什么✅ 第2篇地基篇——让模型开口说话System Prompt的艺术✅ 第3篇灵魂篇——ReAct循环的骨架✅ 第4篇双手篇——赋予读写文件的能力⏭️ 第5篇终端篇——赋予执行命令的超能力第6篇整合篇——组装Mini Claude Code第7篇上下文篇——让Agent看懂整个文件夹第8篇反思与展望——我们得到了什么还缺什么