1. 项目概述一个能自动修 Bug 的 AI 副驾最近在折腾一个老项目的重构面对一堆历史遗留的 Bug 和报错日志手动排查和修复的效率低到让人抓狂。相信很多开发者都有过类似的体验深夜被警报吵醒对着满屏的异常堆栈一边查文档一边试修好一个可能又引入新的问题。这种重复、耗时的“救火”工作极大地消耗了开发者的创造力和精力。就在这个当口我注意到了 Anthropic 推出的 Claude Agent SDK。这个 SDK 的核心思想是让 Claude 模型能够调用你提供的工具函数从而自主完成一系列任务而不仅仅是进行对话。这让我灵光一闪能不能让 Claude 扮演一个“资深调试工程师”的角色我只需要把运行报错和相关的代码上下文扔给它它就能自动分析、定位甚至直接生成修复代码说干就干。经过一番探索和踩坑我成功用大约 20 行核心 Python 代码搭建了一个能自动分析 Python 代码错误并尝试修复的 AI Agent。这个 Agent 的工作流程非常直观它接收错误信息和代码理解问题所在然后调用一个“代码执行器”工具来验证它的修复假设最终给出可行的解决方案。整个过程我只需要扮演“产品经理”和“代码评审者”的角色把脏活累活都交给了 AI。这不仅仅是偷懒更是一种工作范式的转变。它把开发者从繁琐的、模式化的调试中解放出来让我们能更专注于架构设计和核心逻辑。接下来我就把这个“自动修 Bug 副驾”的搭建思路、核心代码以及我踩过的那些坑毫无保留地分享给你。2. 核心思路与 Claude Agent SDK 能力解析在动手之前我们必须先理解 Claude Agent SDK 到底能做什么以及我们如何利用它来构建一个“修 Bug Agent”。这决定了我们整个项目的架构设计。2.1 Claude Agent 的核心工作模式传统的 AI 对话模型比如直接调用 Claude 的 API你给它一段提示词Prompt它返回一段文本。这个过程是“一次性”的模型无法主动执行任何外部操作。而 Claude Agent SDK 引入了一个关键概念工具Tools。你可以将工具理解为模型可以调用的函数。SDK 会将你定义的工具列表及其描述以结构化格式告诉 Claude 模型。当模型认为需要调用某个工具来完成你的请求时它会生成一个格式化的调用请求SDK 接收到这个请求后会实际执行对应的 Python 函数并将执行结果返回给模型。模型根据这个结果再决定下一步是继续调用工具还是生成最终答案回复给用户。这个过程形成了一个“思考-行动-观察”的循环思考模型分析用户请求决定是否需要以及调用哪个工具。行动SDK 执行模型指定的工具函数。观察模型获得工具执行的结果成功或失败包括输出内容。再思考模型基于观察结果决定下一步行动直到任务完成或无法继续。对于“修 Bug”这个任务模型的核心能力是代码理解和逻辑推理但它缺少一个关键环节验证。它提出的修复方案是否真的能解决报错会不会引入新的运行时错误这时我们就需要为它提供一个最重要的工具一个安全的代码执行环境。2.2 为 Agent 设计“双手”代码执行工具我们的 Agent 需要一双能“运行代码”的手。这里有几个关键考量安全性绝对不能让 Agent 执行的代码危害到主机系统。这意味着需要隔离比如在一个沙箱、容器或严格限制的子进程中运行代码。资源限制需要限制运行时间、内存和CPU防止陷入死循环或耗尽资源。信息捕获需要准确捕获代码的标准输出stdout、标准错误stderr以及返回值这些是判断代码行为的关键。交互性对于某些调试场景可能需要模拟多轮输入输出但作为初版我们优先处理简单的脚本执行。基于这些考量我选择了 Python 内置的subprocess模块来创建隔离的执行环境。虽然不如 Docker 容器彻底但通过巧妙的参数配置可以在大多数场景下提供足够的安全性和便利性。我将这个工具命名为run_python_code它的核心职责是接收一段 Python 代码字符串在一个全新的子进程中运行它并返回执行结果成功输出或错误信息。有了这个工具Agent 的工作流就清晰了输入用户提供报错信息和问题代码片段。分析Claude 模型分析错误如NameError,TypeError,IndexError等理解代码意图。假设与验证模型生成一个修复假设即修改后的代码然后主动调用run_python_code工具来运行这段新代码。迭代如果运行再次报错模型会收到新的错误信息并基于此进行下一轮分析和修复形成循环。输出当代码运行成功或模型判断无法自动修复时它将总结问题根源和已尝试的修复方案交付给用户。这个设计巧妙地将模型的“脑”推理分析和我们提供的“手”执行验证结合起来形成了一个可以自主行动的调试智能体。3. 环境准备与核心依赖安装工欲善其事必先利其器。这个项目对环境的依赖非常简洁核心就是 Claude 的 SDK 和 API 密钥。3.1 创建虚拟环境与安装 SDK强烈建议使用虚拟环境来管理依赖避免污染系统级的 Python 环境。这里我使用venv你也可以选择conda或pipenv。# 1. 创建项目目录并进入 mkdir auto-bug-fixer-agent cd auto-bug-fixer-agent # 2. 创建 Python 虚拟环境 python -m venv venv # 3. 激活虚拟环境 # 在 macOS/Linux 上 source venv/bin/activate # 在 Windows 上 # venv\Scripts\activate # 4. 安装 Claude Agent SDK pip install anthropic安装anthropic库时它会自动包含 Agent 所需的依赖。目前Agent 功能在anthropic库的较新版本中例如 0.25.0 以上提供支持直接安装最新稳定版即可。3.2 获取并配置 Claude API 密钥Claude Agent SDK 需要合法的 API 密钥来调用 Claude 模型。你需要前往 Anthropic 的官方平台注册并获取 API Key。注意API 密钥是私密信息绝对不能直接硬编码在代码中或提交到版本控制系统如 Git。泄露密钥可能导致未经授权的使用和财务损失。标准的做法是使用环境变量来管理密钥# 在 macOS/Linux 的终端中将你的密钥添加到当前 shell 环境 export ANTHROPIC_API_KEY你的-actual-api-key-here # 在 Windows 的 PowerShell 中 # $env:ANTHROPIC_API_KEY你的-actual-api-key-here为了方便开发和不同项目切换我推荐使用python-dotenv库。首先安装它pip install python-dotenv。然后在项目根目录创建一个名为.env的文件ANTHROPIC_API_KEY你的-actual-api-key-here并在你的 Python 代码开头通过dotenv加载这个文件。这样密钥管理既安全又方便。3.3 模型选择与初步测试Claude Agent SDK 支持 Claude 3 系列的各种模型如claude-3-5-sonnet-20241022、claude-3-opus-20240229等。对于代码理解和推理任务claude-3-5-sonnet在能力和性价比上取得了很好的平衡也是我本次项目的主力模型。在搭建完整 Agent 之前我们可以先写一个简单的脚本来测试环境和 API 连通性是否正常import anthropic import os from dotenv import load_dotenv load_dotenv() # 从 .env 文件加载环境变量 client anthropic.Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) # 测试普通对话 response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens100, messages[{role: user, content: Hello, Claude!}] ) print(response.content[0].text)如果这段代码能成功打印出 Claude 的问候回复说明你的环境和 API 密钥配置正确可以开始构建 Agent 了。4. 核心代码实现20行构建自动调试引擎一切准备就绪现在进入最核心的部分编写 Agent 的“大脑”和“双手”。我将代码拆解为几个关键部分你会发现它的核心逻辑非常紧凑。4.1 定义代码执行工具Tool这是 Agent 的“双手”是所有自动验证的基础。我们使用subprocess.run来安全地执行代码。import subprocess import tempfile import os def run_python_code(code: str) - str: 在一个安全的子进程中运行提供的 Python 代码字符串。 返回标准输出、标准错误或执行成功的信息。 # 使用临时文件来存储代码避免命令行转义问题 with tempfile.NamedTemporaryFile(modew, suffix.py, deleteFalse) as f: f.write(code) temp_file_path f.name try: # 使用超时限制防止死循环代码 # 设置 textTrue 以获取字符串而非字节 # 捕获所有输出stdout 和 stderr result subprocess.run( [python, temp_file_path], capture_outputTrue, textTrue, timeout30, # 设置30秒超时 cwdos.path.dirname(temp_file_path) # 在临时文件所在目录运行 ) # 清理临时文件 os.unlink(temp_file_path) if result.returncode 0: # 执行成功返回标准输出 return fExecution successful.\nStdout:\n{result.stdout} else: # 执行失败返回标准错误 return fExecution failed with return code {result.returncode}.\nStderr:\n{result.stderr} except subprocess.TimeoutExpired: # 超时处理 os.unlink(temp_file_path) # 确保清理临时文件 return Error: Code execution timed out (exceeded 30 seconds). except Exception as e: # 其他意外错误 if os.path.exists(temp_file_path): os.unlink(temp_file_path) return fError running code: {str(e)}工具设计要点解析临时文件为什么不直接用python -c “code”因为复杂的代码包含多行字符串、特殊符号在命令行中容易引发转义错误。写入临时文件是最可靠的方式。超时控制timeout30参数至关重要。它防止了 Agent 因执行一个无限循环而永远卡住保障了系统的响应性。资源隔离虽然subprocess不是完美的沙箱但它在新进程中运行代码与主 Agent 进程隔离。结合超时和cwd设置为临时目录提供了基础的安全保障。清晰的返回格式工具返回的字符串是给 Claude 模型“看”的。因此返回信息必须结构化、清晰例如明确标注 “Execution successful” 和 “Stdout:”帮助模型准确理解执行结果。4.2 构建 Agent 并定义系统指令System Prompt系统指令System Prompt是 Agent 的“人格设定”和“任务宪章”它决定了 Agent 如何思考和行为。这部分提示词工程的质量直接决定了 Agent 的调试效果。from anthropic import Anthropic # 初始化客户端 client Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) # 定义工具列表。SDK 需要工具的函数对象和描述。 tools [{ name: run_python_code, description: Executes the provided Python code string in a safe, isolated subprocess and returns the output or error. Use this to test if a code fix actually works., input_schema: { type: object, properties: { code: { type: string, description: The Python code to execute. } }, required: [code] } }] # 将我们的函数与工具定义关联起来。 # 注意SDK 需要一个字典将工具名映射到可调用函数。 tool_map { run_python_code: run_python_code } # 核心系统指令 SYSTEM_PROMPT 你是一个专业的 Python 调试专家 AI 助手。你的唯一目标是分析和修复用户提供的 Python 代码中的错误。 工作流程 1. **分析**首先仔细阅读用户提供的错误信息和相关代码。理解错误的类型如 SyntaxError, NameError, TypeError, IndexError 等和发生位置。 2. **推理**推断导致错误的原因。是变量未定义类型不匹配索引越界函数调用参数错误 3. **提出修复**根据你的推理生成一个修复后的完整代码版本。修复应尽可能最小化更改并符合 Python 最佳实践。 4. **验证**你必须使用 run_python_code 工具来执行你修复后的代码。这是强制步骤不要仅仅在理论上告诉我修复了。 5. **迭代**如果工具返回执行失败新的错误分析新的错误信息并重复步骤 2-4尝试新的修复方案。你最多可以进行 5 轮修复尝试。 6. **报告** - 如果验证成功向用户解释最初的错误原因展示你的修复方案并附上成功的执行输出作为证明。 - 如果多次尝试后仍失败向用户详细说明你尝试过的所有方法、遇到的障碍并提出最有可能的手动修复方向。 重要规则 - 你只能修改用户提供的代码部分。不要添加无关的示例代码。 - 每次调用 run_python_code 时必须提供完整的、可独立运行的代码片段如果需要可以包含必要的 import 语句。 - 保持冷静和逻辑性。一次只解决一个最根本的错误。 系统指令设计心得角色明确“专业的 Python 调试专家”设定了清晰的边界。流程化将复杂的调试任务分解为“分析、推理、修复、验证、迭代、报告”六个步骤引导模型按顺序思考避免了它东一榔头西一棒子。强制验证明确要求“必须使用工具验证”这是实现自动化的关键。没有这一步Agent 就退化为一个普通的代码建议模型。迭代与终止设定“最多5轮尝试”防止在无解的问题上无限循环消耗 API 费用。输出规范明确成功和失败两种场景下的报告格式确保最终输出对用户友好。4.3 启动 Agent 会话与任务执行这是将所有部分组合起来并与用户交互的环节。我们使用client.beta.messages.create来创建一个支持工具的会话。def create_debug_agent(): 创建并返回一个配置好的调试 Agent # 实际上Anthropic SDK 的 Agent 会话是通过 messages.create 的 tools 参数来启用的。 # 我们不需要显式创建一个“Agent”对象而是在每次对话时传入工具定义。 # 但我们可以封装一个函数来保持工具和系统提示的一致性。 return { client: client, tools: tools, tool_map: tool_map, system_prompt: SYSTEM_PROMPT } def run_debug_session(agent_info, user_message): 运行一次调试会话 messages [{role: user, content: user_message}] # 第一步发送用户消息和工具定义给模型 response agent_info[client].messages.create( modelclaude-3-5-sonnet-20241022, max_tokens4096, # 调试过程可能需要较长的思考链 systemagent_info[system_prompt], messagesmessages, toolsagent_info[tools] ) # 处理模型响应。模型可能直接回复也可能请求调用工具。 final_message None # 这里需要一个循环来处理多轮工具调用简化示例实际需处理更复杂的消息序列 # 注意Anthropic SDK 的 messages.create 在流式或非流式响应中如果模型决定使用工具 # 响应会包含 stop_reason 为 ‘tool_use‘并附带工具调用的详细信息。 # 我们需要手动处理这个循环。以下是概念性代码 current_messages messages[:] current_messages.append({role: assistant, content: response.content}) # 检查响应中是否有工具调用 for block in response.content: if block.type tool_use: tool_name block.name tool_input block.input # 1. 执行工具 tool_function agent_info[tool_map].get(tool_name) if tool_function: tool_result tool_function(**tool_input) else: tool_result fError: Tool {tool_name} not found. # 2. 将工具执行结果作为新消息追加 current_messages.append({ role: user, content: [ { type: tool_result, tool_use_id: block.id, content: tool_result } ] }) # 3. 再次调用模型让它基于工具结果继续思考 next_response agent_info[client].messages.create( modelclaude-3-5-sonnet-20241022, max_tokens4096, systemagent_info[system_prompt], messagescurrent_messages, toolsagent_info[tools] ) current_messages.append({role: assistant, content: next_response.content}) # 更新最终响应 response next_response # 如果 block.type 是 ‘text‘则说明是模型的直接回复 # 提取模型的最终文本回复 final_text for block in response.content: if block.type text: final_text block.text return final_text # 使用示例 if __name__ __main__: agent create_debug_agent() user_input 我的代码出错了请帮我修复。 错误信息 Traceback (most recent call last): File test.py, line 5, in module result calculate_average(numbers) File test.py, line 2, in calculate_average return sum(num_list) / len(num_list) ZeroDivisionError: division by zero 相关代码 def calculate_average(num_list): return sum(num_list) / len(num_list) numbers [] result calculate_average(numbers) print(fThe average is {result}) result run_debug_session(agent, user_input) print( Debug Agent 修复报告 ) print(result)核心交互逻辑解析初始化会话将用户的问题错误信息代码和系统指令、工具定义一起发送给 Claude 模型。模型决策模型分析后可能直接给出文本回答也可能决定调用run_python_code工具。如果调用工具响应中会包含tool_use块。工具执行循环我们检测到tool_use后从tool_map中找到对应的函数并执行。将工具执行结果封装成特定格式type: “tool_result“并附上对应的tool_use_id追加到消息历史中。将包含工具结果的新消息历史再次发送给模型。模型根据工具返回的结果成功或新的错误进行下一轮思考可能继续调用工具或生成最终答案。输出最终结果当模型的响应中不再包含tool_use只有text块时循环结束。我们将所有文本内容拼接起来作为 Agent 的最终调试报告返回给用户。这个过程完美实现了我们设计的“思考-行动-观察”循环。上面展示的run_debug_session函数是一个简化版本实际处理消息列表和工具调用循环需要更严谨的逻辑来拼接user、assistant和tool_result消息。但核心思想就是如此我们搭建了一个管道让模型可以自主地、反复地测试它的代码修复方案直到问题解决或达到尝试上限。5. 实战踩坑记录与优化策略理论很美好但实践过程中我遇到了不少预料之外的问题。下面是我总结的几个关键“坑”以及对应的解决方案这些经验能帮你节省大量调试时间。5.1 坑一工具调用格式与消息历史管理这是最初让我困惑最久的地方。Anthropic 的 Messages API 对于工具调用的消息格式有严格的要求。问题现象我按照直觉在模型请求调用工具后直接将工具执行结果以普通文本 (role: “user“) 的形式发送回去导致模型无法识别这是上一个工具调用的结果会话逻辑混乱。根本原因工具调用的输入和输出必须是结构化格式。当模型请求调用工具时它生成的是一个tool_use块。作为用户我们在返回工具结果时必须使用tool_result块并且其中的tool_use_id必须与模型请求中的id字段严格对应。这样 SDK 和模型才能正确地将结果与请求关联起来。解决方案严格按照 API 文档要求的格式构建消息。以下是处理单轮工具调用的正确代码片段# 假设 response 是模型包含 tool_use 的响应 tool_use_block None for block in response.content: if block.type ‘tool_use‘: tool_use_block block break if tool_use_block: # 1. 执行工具 tool_result_content run_python_code(tool_use_block.input[‘code‘]) # 2. 构建格式正确的 tool_result 消息 tool_result_message { “role“: “user“, “content“: [{ “type“: “tool_result“, “tool_use_id“: tool_use_block.id, # 关键ID 必须匹配 “content“: tool_result_content }] } # 3. 将 assistant 的响应包含 tool_use和 tool_result 一起作为历史 messages_for_next_round messages_history [ {“role“: “assistant“, “content“: response.content}, tool_result_message ] # 4. 发送下一轮请求 next_response client.messages.create( modelMODEL, messagesmessages_for_next_round, toolstools, max_tokens4096 )关键心得消息历史 (messages) 的管理是 Agent 编程的核心。你必须维护一个包含所有user,assistant,tool_use,tool_result的完整、有序的列表。每次请求都将整个历史发送过去模型才能理解完整的对话上下文。5.2 坑二代码执行环境与依赖隔离问题现象Agent 尝试修复一个需要requests库的脚本它生成的修复代码包含了import requests但在工具执行时失败了提示ModuleNotFoundError: No module named ‘requests‘。根本原因我们的run_python_code工具在一个全新的子进程中运行这个子进程继承的是系统环境或虚拟环境的 Python 路径。如果项目依赖了额外的第三方包而这个包没有安装在工具执行的环境中就会导致导入失败。解决方案有两种思路安装依赖到工具环境在启动 Agent 前确保所有可能用到的依赖都已安装在当前 Python 环境中。对于通用 Agent这不现实。动态安装依赖有风险让工具函数在执行代码前尝试解析import语句并动态安装。但这种方法非常危险因为它赋予了 AI 在系统上安装任意包的能力存在安全风险。我的折中方案在系统指令中明确告知 Agent 当前环境的限制。修改SYSTEM_PROMPT重要环境限制 - 你只能使用 Python 标准库如 os, sys, json, math 等和以下已安装的第三方库[requests, numpy]。 - 如果你的修复方案需要其他未列出的库请在回复中明确指出“此修复需要安装 XXX 库”并给出安装命令如 pip install xxx但不要尝试在工具中自动安装。同时在项目初期我会手动将常用库如requests,pandas,numpy安装到虚拟环境中。对于特定项目可以创建一个requirements.txt文件并在启动 Agent 前运行pip install -r requirements.txt。5.3 坑三复杂错误与“修复-引入新错误”循环问题现象Agent 在修复一个复杂的逻辑错误时成功解决了第一个TypeError但修改后的代码又产生了AttributeError然后它陷入了几轮尝试问题变得越来越复杂。根本原因模型的“思维”有时会过于聚焦于当前报错行进行局部修补而忽略了代码的整体逻辑和数据结构。这类似于一个新手程序员在调试时的表现。优化策略强化系统指令在SYSTEM_PROMPT中加入更明确的指导“在修改代码前先通读并理解整个代码片段的业务逻辑和数据流。你的修复应该保持代码的原始意图。如果错误是连锁反应请尝试定位最根本的、最初的数据错误或设计缺陷。”提供更丰富的上下文在用户提问时不仅提供报错代码行也提供相关的函数定义、类结构、甚至是一小段示例输入输出帮助模型建立更完整的上下文。设置尝试次数上限与总结这是防止无限循环和经济损失的关键。在系统指令中明确“最多尝试5次”并在达到上限后强制模型停止调用工具转而生成一份详细的诊断报告列出所有尝试过的路径和剩余疑点。这能将无解的消耗转化为有价值的分析输出。5.4 坑四执行超时与资源控制问题现象Agent 在处理一个潜在的死循环代码时工具调用卡住整个程序无响应。根本原因最初的subprocess.run调用没有设置timeout参数。当代码包含while True:这样的结构时子进程会永远运行下去。解决方案如前文代码所示为subprocess.run设置timeout参数例如30秒。同时做好异常处理在subprocess.TimeoutExpired异常被捕获时返回明确的超时信息给模型。try: result subprocess.run(..., timeout30, ...) except subprocess.TimeoutExpired: return “Error: Code execution timed out (exceeded 30 seconds). The code might contain an infinite loop.“这个超时信息对于模型来说是一个清晰的信号它会明白自己的代码存在逻辑问题如无限循环从而调整修复策略例如增加循环终止条件。6. 效果评估与典型应用场景经过多轮测试和优化这个“自动修 Bug Agent”已经能处理相当一部分常见的 Python 运行时错误。它的优势在于不知疲倦、执行迅速并且能严格遵循“假设-验证”的科学调试流程。6.1 它能出色处理的 Bug 类型语法错误SyntaxError例如缺少冒号、括号不匹配、错误的关键字。模型能精准定位并修正。示例if x 5 print(“Large“)修复为if x 5: print(“Large“)名称错误NameError变量或函数名拼写错误、在作用域外使用变量。示例prin(“Hello“)修复为print(“Hello“)或为未定义的变量添加初始化。类型错误TypeError操作或函数应用于不适当类型的对象如字符串与数字相加。示例“Total: “ 100修复为“Total: “ str(100)。索引/键错误IndexError/KeyError访问列表、元组、字典的不存在索引或键。示例list[10]列表长度只有5模型可能会建议先检查长度或修改为安全访问list[10] if len(list) 10 else default_value。零除错误ZeroDivisionError如开篇例子模型能识别出空列表导致除零并建议添加条件判断。属性错误AttributeError对象没有某个属性或方法。示例“abc“.append(‘d‘)修复为list(“abc“).append(‘d‘)或直接使用字符串方法。对于这类错误Agent 的修复成功率在我的测试中能达到 85% 以上。它不仅能改对很多时候提供的修复方案比如添加边界检查、类型转换还体现了良好的编程习惯。6.2 它的局限性以及何时需要人工介入尽管强大但目前的 Agent 并非万能。在以下场景中它可能力不从心需要人类开发者接手涉及复杂业务逻辑的 Bug如果错误源于对业务规则的理解偏差例如计算折扣的公式本身是错的模型缺乏业务背景知识可能只会修复表面上的语法或运行时错误而无法纠正根本的逻辑。需要设计模式或架构调整的 Bug有些 Bug 是糟糕代码结构导致的比如全局变量滥用、函数职责过于庞大。模型通常只能进行局部修补无法提出“重构这个函数为两个独立函数”或“引入一个单例模式”这样的架构级建议。依赖外部系统或API的 Bug例如代码调用了一个外部 REST API但返回的数据格式与预期不符。模型无法感知外部系统的状态和契约变化其修复可能基于错误假设。极其罕见或复杂的第三方库错误对于某些库的深度用法或晦涩错误信息模型可能没有足够的训练数据来准确理解。性能问题与内存泄漏这类 Bug 通常没有直接的异常抛出需要通过 profiling 工具分析。我们的 Agent 目前只处理异常Exception不处理性能瓶颈。因此这个 Agent 的最佳定位是“第一响应者”或“初级调试助手”。它能快速消灭那些简单、重复的“低级错误”把开发者从繁琐的体力劳动中解放出来。当它尝试几次后仍然失败或者提出的修复方案明显违背业务逻辑时它生成的详细诊断报告包括它尝试过的路径和遇到的错误也能为人类开发者提供宝贵的上下文加速真正的人工调试过程。7. 扩展思路与未来展望这个基础版本的 Agent 已经打开了思路的大门。基于此框架我们可以从多个方向进行扩展让它变得更强大、更智能。7.1 扩展工具集成为全能开发助手目前 Agent 只有“运行代码”这一只手。我们可以为它装备更多工具让它能处理更广泛的任务文件读写工具让 Agent 能够读取项目中的其他源文件来获取更全面的上下文或者将修复后的代码写回到原文件需谨慎授权。Git 操作工具让 Agent 可以执行git diff,git log等命令理解代码变更历史甚至创建修复分支和提交。静态分析工具集成pylint,mypy等让 Agent 在运行前就能发现代码风格问题和类型隐患。网络搜索工具需谨慎在模型遇到未知错误信息时允许它安全地搜索公开的编程问答网站如 Stack Overflow 摘要获取解决方案思路。这需要严格的内容过滤和安全控制。7.2 集成到开发工作流中CI/CD 流水线集成在持续集成阶段让 Agent 自动分析测试失败的日志尝试修复并重新运行测试。如果修复成功且通过测试可以标记为“AI 辅助修复”供开发者审查合并。IDE 插件开发一个 IDE如 VS Code、PyCharm插件当开发者遇到运行时异常时一键调用本地或云端的这个 Agent将错误信息和当前文件上下文发送过去并直接在编辑器中应用建议的修复。日志监控告警响应与日志系统如 ELK、Sentry对接当生产环境出现特定频率或类型的错误时自动触发 Agent 进行分析并生成初步的修复报告或提交一个修复 PR大大缩短平均修复时间MTTR。7.3 提升安全性与可控性当前的代码执行工具仍有安全风险。为了在生产环境中更放心地使用可以考虑使用 Docker 沙箱将subprocess.run替换为在一次性 Docker 容器中执行代码。可以定制一个包含基础 Python 和常用库的轻量级镜像实现彻底的资源隔离和安全控制。代码扫描与白名单在执行前对 AI 生成的代码进行简单的静态扫描禁止导入如os.system,subprocess.Popen,__import__(‘os‘).system等明显危险的模块或函数调用。人工审核环节对于涉及文件系统修改、Git 操作或网络请求的“高风险”工具调用设计一个“暂停并等待人工批准”的机制。Agent 可以提出操作建议但执行前需要开发者点击确认。这个用 Claude Agent SDK 搭建的自动修 Bug Agent虽然核心代码只有 20 多行但它清晰地展示了大模型与工具结合后产生的“行动力”。它不再是一个被动的知识库而是一个能主动验证、迭代的智能体。对于每一位开发者而言真正的价值不在于完全取代自己而是利用这样的工具将我们的时间从重复性劳动中赎回投入到更有创造性的设计、架构和解决真正复杂的问题中去。 基于Claude Agent SDK构建Python自动调试AI助手：20行代码实现Bug智能修复
1. 项目概述一个能自动修 Bug 的 AI 副驾最近在折腾一个老项目的重构面对一堆历史遗留的 Bug 和报错日志手动排查和修复的效率低到让人抓狂。相信很多开发者都有过类似的体验深夜被警报吵醒对着满屏的异常堆栈一边查文档一边试修好一个可能又引入新的问题。这种重复、耗时的“救火”工作极大地消耗了开发者的创造力和精力。就在这个当口我注意到了 Anthropic 推出的 Claude Agent SDK。这个 SDK 的核心思想是让 Claude 模型能够调用你提供的工具函数从而自主完成一系列任务而不仅仅是进行对话。这让我灵光一闪能不能让 Claude 扮演一个“资深调试工程师”的角色我只需要把运行报错和相关的代码上下文扔给它它就能自动分析、定位甚至直接生成修复代码说干就干。经过一番探索和踩坑我成功用大约 20 行核心 Python 代码搭建了一个能自动分析 Python 代码错误并尝试修复的 AI Agent。这个 Agent 的工作流程非常直观它接收错误信息和代码理解问题所在然后调用一个“代码执行器”工具来验证它的修复假设最终给出可行的解决方案。整个过程我只需要扮演“产品经理”和“代码评审者”的角色把脏活累活都交给了 AI。这不仅仅是偷懒更是一种工作范式的转变。它把开发者从繁琐的、模式化的调试中解放出来让我们能更专注于架构设计和核心逻辑。接下来我就把这个“自动修 Bug 副驾”的搭建思路、核心代码以及我踩过的那些坑毫无保留地分享给你。2. 核心思路与 Claude Agent SDK 能力解析在动手之前我们必须先理解 Claude Agent SDK 到底能做什么以及我们如何利用它来构建一个“修 Bug Agent”。这决定了我们整个项目的架构设计。2.1 Claude Agent 的核心工作模式传统的 AI 对话模型比如直接调用 Claude 的 API你给它一段提示词Prompt它返回一段文本。这个过程是“一次性”的模型无法主动执行任何外部操作。而 Claude Agent SDK 引入了一个关键概念工具Tools。你可以将工具理解为模型可以调用的函数。SDK 会将你定义的工具列表及其描述以结构化格式告诉 Claude 模型。当模型认为需要调用某个工具来完成你的请求时它会生成一个格式化的调用请求SDK 接收到这个请求后会实际执行对应的 Python 函数并将执行结果返回给模型。模型根据这个结果再决定下一步是继续调用工具还是生成最终答案回复给用户。这个过程形成了一个“思考-行动-观察”的循环思考模型分析用户请求决定是否需要以及调用哪个工具。行动SDK 执行模型指定的工具函数。观察模型获得工具执行的结果成功或失败包括输出内容。再思考模型基于观察结果决定下一步行动直到任务完成或无法继续。对于“修 Bug”这个任务模型的核心能力是代码理解和逻辑推理但它缺少一个关键环节验证。它提出的修复方案是否真的能解决报错会不会引入新的运行时错误这时我们就需要为它提供一个最重要的工具一个安全的代码执行环境。2.2 为 Agent 设计“双手”代码执行工具我们的 Agent 需要一双能“运行代码”的手。这里有几个关键考量安全性绝对不能让 Agent 执行的代码危害到主机系统。这意味着需要隔离比如在一个沙箱、容器或严格限制的子进程中运行代码。资源限制需要限制运行时间、内存和CPU防止陷入死循环或耗尽资源。信息捕获需要准确捕获代码的标准输出stdout、标准错误stderr以及返回值这些是判断代码行为的关键。交互性对于某些调试场景可能需要模拟多轮输入输出但作为初版我们优先处理简单的脚本执行。基于这些考量我选择了 Python 内置的subprocess模块来创建隔离的执行环境。虽然不如 Docker 容器彻底但通过巧妙的参数配置可以在大多数场景下提供足够的安全性和便利性。我将这个工具命名为run_python_code它的核心职责是接收一段 Python 代码字符串在一个全新的子进程中运行它并返回执行结果成功输出或错误信息。有了这个工具Agent 的工作流就清晰了输入用户提供报错信息和问题代码片段。分析Claude 模型分析错误如NameError,TypeError,IndexError等理解代码意图。假设与验证模型生成一个修复假设即修改后的代码然后主动调用run_python_code工具来运行这段新代码。迭代如果运行再次报错模型会收到新的错误信息并基于此进行下一轮分析和修复形成循环。输出当代码运行成功或模型判断无法自动修复时它将总结问题根源和已尝试的修复方案交付给用户。这个设计巧妙地将模型的“脑”推理分析和我们提供的“手”执行验证结合起来形成了一个可以自主行动的调试智能体。3. 环境准备与核心依赖安装工欲善其事必先利其器。这个项目对环境的依赖非常简洁核心就是 Claude 的 SDK 和 API 密钥。3.1 创建虚拟环境与安装 SDK强烈建议使用虚拟环境来管理依赖避免污染系统级的 Python 环境。这里我使用venv你也可以选择conda或pipenv。# 1. 创建项目目录并进入 mkdir auto-bug-fixer-agent cd auto-bug-fixer-agent # 2. 创建 Python 虚拟环境 python -m venv venv # 3. 激活虚拟环境 # 在 macOS/Linux 上 source venv/bin/activate # 在 Windows 上 # venv\Scripts\activate # 4. 安装 Claude Agent SDK pip install anthropic安装anthropic库时它会自动包含 Agent 所需的依赖。目前Agent 功能在anthropic库的较新版本中例如 0.25.0 以上提供支持直接安装最新稳定版即可。3.2 获取并配置 Claude API 密钥Claude Agent SDK 需要合法的 API 密钥来调用 Claude 模型。你需要前往 Anthropic 的官方平台注册并获取 API Key。注意API 密钥是私密信息绝对不能直接硬编码在代码中或提交到版本控制系统如 Git。泄露密钥可能导致未经授权的使用和财务损失。标准的做法是使用环境变量来管理密钥# 在 macOS/Linux 的终端中将你的密钥添加到当前 shell 环境 export ANTHROPIC_API_KEY你的-actual-api-key-here # 在 Windows 的 PowerShell 中 # $env:ANTHROPIC_API_KEY你的-actual-api-key-here为了方便开发和不同项目切换我推荐使用python-dotenv库。首先安装它pip install python-dotenv。然后在项目根目录创建一个名为.env的文件ANTHROPIC_API_KEY你的-actual-api-key-here并在你的 Python 代码开头通过dotenv加载这个文件。这样密钥管理既安全又方便。3.3 模型选择与初步测试Claude Agent SDK 支持 Claude 3 系列的各种模型如claude-3-5-sonnet-20241022、claude-3-opus-20240229等。对于代码理解和推理任务claude-3-5-sonnet在能力和性价比上取得了很好的平衡也是我本次项目的主力模型。在搭建完整 Agent 之前我们可以先写一个简单的脚本来测试环境和 API 连通性是否正常import anthropic import os from dotenv import load_dotenv load_dotenv() # 从 .env 文件加载环境变量 client anthropic.Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) # 测试普通对话 response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens100, messages[{role: user, content: Hello, Claude!}] ) print(response.content[0].text)如果这段代码能成功打印出 Claude 的问候回复说明你的环境和 API 密钥配置正确可以开始构建 Agent 了。4. 核心代码实现20行构建自动调试引擎一切准备就绪现在进入最核心的部分编写 Agent 的“大脑”和“双手”。我将代码拆解为几个关键部分你会发现它的核心逻辑非常紧凑。4.1 定义代码执行工具Tool这是 Agent 的“双手”是所有自动验证的基础。我们使用subprocess.run来安全地执行代码。import subprocess import tempfile import os def run_python_code(code: str) - str: 在一个安全的子进程中运行提供的 Python 代码字符串。 返回标准输出、标准错误或执行成功的信息。 # 使用临时文件来存储代码避免命令行转义问题 with tempfile.NamedTemporaryFile(modew, suffix.py, deleteFalse) as f: f.write(code) temp_file_path f.name try: # 使用超时限制防止死循环代码 # 设置 textTrue 以获取字符串而非字节 # 捕获所有输出stdout 和 stderr result subprocess.run( [python, temp_file_path], capture_outputTrue, textTrue, timeout30, # 设置30秒超时 cwdos.path.dirname(temp_file_path) # 在临时文件所在目录运行 ) # 清理临时文件 os.unlink(temp_file_path) if result.returncode 0: # 执行成功返回标准输出 return fExecution successful.\nStdout:\n{result.stdout} else: # 执行失败返回标准错误 return fExecution failed with return code {result.returncode}.\nStderr:\n{result.stderr} except subprocess.TimeoutExpired: # 超时处理 os.unlink(temp_file_path) # 确保清理临时文件 return Error: Code execution timed out (exceeded 30 seconds). except Exception as e: # 其他意外错误 if os.path.exists(temp_file_path): os.unlink(temp_file_path) return fError running code: {str(e)}工具设计要点解析临时文件为什么不直接用python -c “code”因为复杂的代码包含多行字符串、特殊符号在命令行中容易引发转义错误。写入临时文件是最可靠的方式。超时控制timeout30参数至关重要。它防止了 Agent 因执行一个无限循环而永远卡住保障了系统的响应性。资源隔离虽然subprocess不是完美的沙箱但它在新进程中运行代码与主 Agent 进程隔离。结合超时和cwd设置为临时目录提供了基础的安全保障。清晰的返回格式工具返回的字符串是给 Claude 模型“看”的。因此返回信息必须结构化、清晰例如明确标注 “Execution successful” 和 “Stdout:”帮助模型准确理解执行结果。4.2 构建 Agent 并定义系统指令System Prompt系统指令System Prompt是 Agent 的“人格设定”和“任务宪章”它决定了 Agent 如何思考和行为。这部分提示词工程的质量直接决定了 Agent 的调试效果。from anthropic import Anthropic # 初始化客户端 client Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) # 定义工具列表。SDK 需要工具的函数对象和描述。 tools [{ name: run_python_code, description: Executes the provided Python code string in a safe, isolated subprocess and returns the output or error. Use this to test if a code fix actually works., input_schema: { type: object, properties: { code: { type: string, description: The Python code to execute. } }, required: [code] } }] # 将我们的函数与工具定义关联起来。 # 注意SDK 需要一个字典将工具名映射到可调用函数。 tool_map { run_python_code: run_python_code } # 核心系统指令 SYSTEM_PROMPT 你是一个专业的 Python 调试专家 AI 助手。你的唯一目标是分析和修复用户提供的 Python 代码中的错误。 工作流程 1. **分析**首先仔细阅读用户提供的错误信息和相关代码。理解错误的类型如 SyntaxError, NameError, TypeError, IndexError 等和发生位置。 2. **推理**推断导致错误的原因。是变量未定义类型不匹配索引越界函数调用参数错误 3. **提出修复**根据你的推理生成一个修复后的完整代码版本。修复应尽可能最小化更改并符合 Python 最佳实践。 4. **验证**你必须使用 run_python_code 工具来执行你修复后的代码。这是强制步骤不要仅仅在理论上告诉我修复了。 5. **迭代**如果工具返回执行失败新的错误分析新的错误信息并重复步骤 2-4尝试新的修复方案。你最多可以进行 5 轮修复尝试。 6. **报告** - 如果验证成功向用户解释最初的错误原因展示你的修复方案并附上成功的执行输出作为证明。 - 如果多次尝试后仍失败向用户详细说明你尝试过的所有方法、遇到的障碍并提出最有可能的手动修复方向。 重要规则 - 你只能修改用户提供的代码部分。不要添加无关的示例代码。 - 每次调用 run_python_code 时必须提供完整的、可独立运行的代码片段如果需要可以包含必要的 import 语句。 - 保持冷静和逻辑性。一次只解决一个最根本的错误。 系统指令设计心得角色明确“专业的 Python 调试专家”设定了清晰的边界。流程化将复杂的调试任务分解为“分析、推理、修复、验证、迭代、报告”六个步骤引导模型按顺序思考避免了它东一榔头西一棒子。强制验证明确要求“必须使用工具验证”这是实现自动化的关键。没有这一步Agent 就退化为一个普通的代码建议模型。迭代与终止设定“最多5轮尝试”防止在无解的问题上无限循环消耗 API 费用。输出规范明确成功和失败两种场景下的报告格式确保最终输出对用户友好。4.3 启动 Agent 会话与任务执行这是将所有部分组合起来并与用户交互的环节。我们使用client.beta.messages.create来创建一个支持工具的会话。def create_debug_agent(): 创建并返回一个配置好的调试 Agent # 实际上Anthropic SDK 的 Agent 会话是通过 messages.create 的 tools 参数来启用的。 # 我们不需要显式创建一个“Agent”对象而是在每次对话时传入工具定义。 # 但我们可以封装一个函数来保持工具和系统提示的一致性。 return { client: client, tools: tools, tool_map: tool_map, system_prompt: SYSTEM_PROMPT } def run_debug_session(agent_info, user_message): 运行一次调试会话 messages [{role: user, content: user_message}] # 第一步发送用户消息和工具定义给模型 response agent_info[client].messages.create( modelclaude-3-5-sonnet-20241022, max_tokens4096, # 调试过程可能需要较长的思考链 systemagent_info[system_prompt], messagesmessages, toolsagent_info[tools] ) # 处理模型响应。模型可能直接回复也可能请求调用工具。 final_message None # 这里需要一个循环来处理多轮工具调用简化示例实际需处理更复杂的消息序列 # 注意Anthropic SDK 的 messages.create 在流式或非流式响应中如果模型决定使用工具 # 响应会包含 stop_reason 为 ‘tool_use‘并附带工具调用的详细信息。 # 我们需要手动处理这个循环。以下是概念性代码 current_messages messages[:] current_messages.append({role: assistant, content: response.content}) # 检查响应中是否有工具调用 for block in response.content: if block.type tool_use: tool_name block.name tool_input block.input # 1. 执行工具 tool_function agent_info[tool_map].get(tool_name) if tool_function: tool_result tool_function(**tool_input) else: tool_result fError: Tool {tool_name} not found. # 2. 将工具执行结果作为新消息追加 current_messages.append({ role: user, content: [ { type: tool_result, tool_use_id: block.id, content: tool_result } ] }) # 3. 再次调用模型让它基于工具结果继续思考 next_response agent_info[client].messages.create( modelclaude-3-5-sonnet-20241022, max_tokens4096, systemagent_info[system_prompt], messagescurrent_messages, toolsagent_info[tools] ) current_messages.append({role: assistant, content: next_response.content}) # 更新最终响应 response next_response # 如果 block.type 是 ‘text‘则说明是模型的直接回复 # 提取模型的最终文本回复 final_text for block in response.content: if block.type text: final_text block.text return final_text # 使用示例 if __name__ __main__: agent create_debug_agent() user_input 我的代码出错了请帮我修复。 错误信息 Traceback (most recent call last): File test.py, line 5, in module result calculate_average(numbers) File test.py, line 2, in calculate_average return sum(num_list) / len(num_list) ZeroDivisionError: division by zero 相关代码 def calculate_average(num_list): return sum(num_list) / len(num_list) numbers [] result calculate_average(numbers) print(fThe average is {result}) result run_debug_session(agent, user_input) print( Debug Agent 修复报告 ) print(result)核心交互逻辑解析初始化会话将用户的问题错误信息代码和系统指令、工具定义一起发送给 Claude 模型。模型决策模型分析后可能直接给出文本回答也可能决定调用run_python_code工具。如果调用工具响应中会包含tool_use块。工具执行循环我们检测到tool_use后从tool_map中找到对应的函数并执行。将工具执行结果封装成特定格式type: “tool_result“并附上对应的tool_use_id追加到消息历史中。将包含工具结果的新消息历史再次发送给模型。模型根据工具返回的结果成功或新的错误进行下一轮思考可能继续调用工具或生成最终答案。输出最终结果当模型的响应中不再包含tool_use只有text块时循环结束。我们将所有文本内容拼接起来作为 Agent 的最终调试报告返回给用户。这个过程完美实现了我们设计的“思考-行动-观察”循环。上面展示的run_debug_session函数是一个简化版本实际处理消息列表和工具调用循环需要更严谨的逻辑来拼接user、assistant和tool_result消息。但核心思想就是如此我们搭建了一个管道让模型可以自主地、反复地测试它的代码修复方案直到问题解决或达到尝试上限。5. 实战踩坑记录与优化策略理论很美好但实践过程中我遇到了不少预料之外的问题。下面是我总结的几个关键“坑”以及对应的解决方案这些经验能帮你节省大量调试时间。5.1 坑一工具调用格式与消息历史管理这是最初让我困惑最久的地方。Anthropic 的 Messages API 对于工具调用的消息格式有严格的要求。问题现象我按照直觉在模型请求调用工具后直接将工具执行结果以普通文本 (role: “user“) 的形式发送回去导致模型无法识别这是上一个工具调用的结果会话逻辑混乱。根本原因工具调用的输入和输出必须是结构化格式。当模型请求调用工具时它生成的是一个tool_use块。作为用户我们在返回工具结果时必须使用tool_result块并且其中的tool_use_id必须与模型请求中的id字段严格对应。这样 SDK 和模型才能正确地将结果与请求关联起来。解决方案严格按照 API 文档要求的格式构建消息。以下是处理单轮工具调用的正确代码片段# 假设 response 是模型包含 tool_use 的响应 tool_use_block None for block in response.content: if block.type ‘tool_use‘: tool_use_block block break if tool_use_block: # 1. 执行工具 tool_result_content run_python_code(tool_use_block.input[‘code‘]) # 2. 构建格式正确的 tool_result 消息 tool_result_message { “role“: “user“, “content“: [{ “type“: “tool_result“, “tool_use_id“: tool_use_block.id, # 关键ID 必须匹配 “content“: tool_result_content }] } # 3. 将 assistant 的响应包含 tool_use和 tool_result 一起作为历史 messages_for_next_round messages_history [ {“role“: “assistant“, “content“: response.content}, tool_result_message ] # 4. 发送下一轮请求 next_response client.messages.create( modelMODEL, messagesmessages_for_next_round, toolstools, max_tokens4096 )关键心得消息历史 (messages) 的管理是 Agent 编程的核心。你必须维护一个包含所有user,assistant,tool_use,tool_result的完整、有序的列表。每次请求都将整个历史发送过去模型才能理解完整的对话上下文。5.2 坑二代码执行环境与依赖隔离问题现象Agent 尝试修复一个需要requests库的脚本它生成的修复代码包含了import requests但在工具执行时失败了提示ModuleNotFoundError: No module named ‘requests‘。根本原因我们的run_python_code工具在一个全新的子进程中运行这个子进程继承的是系统环境或虚拟环境的 Python 路径。如果项目依赖了额外的第三方包而这个包没有安装在工具执行的环境中就会导致导入失败。解决方案有两种思路安装依赖到工具环境在启动 Agent 前确保所有可能用到的依赖都已安装在当前 Python 环境中。对于通用 Agent这不现实。动态安装依赖有风险让工具函数在执行代码前尝试解析import语句并动态安装。但这种方法非常危险因为它赋予了 AI 在系统上安装任意包的能力存在安全风险。我的折中方案在系统指令中明确告知 Agent 当前环境的限制。修改SYSTEM_PROMPT重要环境限制 - 你只能使用 Python 标准库如 os, sys, json, math 等和以下已安装的第三方库[requests, numpy]。 - 如果你的修复方案需要其他未列出的库请在回复中明确指出“此修复需要安装 XXX 库”并给出安装命令如 pip install xxx但不要尝试在工具中自动安装。同时在项目初期我会手动将常用库如requests,pandas,numpy安装到虚拟环境中。对于特定项目可以创建一个requirements.txt文件并在启动 Agent 前运行pip install -r requirements.txt。5.3 坑三复杂错误与“修复-引入新错误”循环问题现象Agent 在修复一个复杂的逻辑错误时成功解决了第一个TypeError但修改后的代码又产生了AttributeError然后它陷入了几轮尝试问题变得越来越复杂。根本原因模型的“思维”有时会过于聚焦于当前报错行进行局部修补而忽略了代码的整体逻辑和数据结构。这类似于一个新手程序员在调试时的表现。优化策略强化系统指令在SYSTEM_PROMPT中加入更明确的指导“在修改代码前先通读并理解整个代码片段的业务逻辑和数据流。你的修复应该保持代码的原始意图。如果错误是连锁反应请尝试定位最根本的、最初的数据错误或设计缺陷。”提供更丰富的上下文在用户提问时不仅提供报错代码行也提供相关的函数定义、类结构、甚至是一小段示例输入输出帮助模型建立更完整的上下文。设置尝试次数上限与总结这是防止无限循环和经济损失的关键。在系统指令中明确“最多尝试5次”并在达到上限后强制模型停止调用工具转而生成一份详细的诊断报告列出所有尝试过的路径和剩余疑点。这能将无解的消耗转化为有价值的分析输出。5.4 坑四执行超时与资源控制问题现象Agent 在处理一个潜在的死循环代码时工具调用卡住整个程序无响应。根本原因最初的subprocess.run调用没有设置timeout参数。当代码包含while True:这样的结构时子进程会永远运行下去。解决方案如前文代码所示为subprocess.run设置timeout参数例如30秒。同时做好异常处理在subprocess.TimeoutExpired异常被捕获时返回明确的超时信息给模型。try: result subprocess.run(..., timeout30, ...) except subprocess.TimeoutExpired: return “Error: Code execution timed out (exceeded 30 seconds). The code might contain an infinite loop.“这个超时信息对于模型来说是一个清晰的信号它会明白自己的代码存在逻辑问题如无限循环从而调整修复策略例如增加循环终止条件。6. 效果评估与典型应用场景经过多轮测试和优化这个“自动修 Bug Agent”已经能处理相当一部分常见的 Python 运行时错误。它的优势在于不知疲倦、执行迅速并且能严格遵循“假设-验证”的科学调试流程。6.1 它能出色处理的 Bug 类型语法错误SyntaxError例如缺少冒号、括号不匹配、错误的关键字。模型能精准定位并修正。示例if x 5 print(“Large“)修复为if x 5: print(“Large“)名称错误NameError变量或函数名拼写错误、在作用域外使用变量。示例prin(“Hello“)修复为print(“Hello“)或为未定义的变量添加初始化。类型错误TypeError操作或函数应用于不适当类型的对象如字符串与数字相加。示例“Total: “ 100修复为“Total: “ str(100)。索引/键错误IndexError/KeyError访问列表、元组、字典的不存在索引或键。示例list[10]列表长度只有5模型可能会建议先检查长度或修改为安全访问list[10] if len(list) 10 else default_value。零除错误ZeroDivisionError如开篇例子模型能识别出空列表导致除零并建议添加条件判断。属性错误AttributeError对象没有某个属性或方法。示例“abc“.append(‘d‘)修复为list(“abc“).append(‘d‘)或直接使用字符串方法。对于这类错误Agent 的修复成功率在我的测试中能达到 85% 以上。它不仅能改对很多时候提供的修复方案比如添加边界检查、类型转换还体现了良好的编程习惯。6.2 它的局限性以及何时需要人工介入尽管强大但目前的 Agent 并非万能。在以下场景中它可能力不从心需要人类开发者接手涉及复杂业务逻辑的 Bug如果错误源于对业务规则的理解偏差例如计算折扣的公式本身是错的模型缺乏业务背景知识可能只会修复表面上的语法或运行时错误而无法纠正根本的逻辑。需要设计模式或架构调整的 Bug有些 Bug 是糟糕代码结构导致的比如全局变量滥用、函数职责过于庞大。模型通常只能进行局部修补无法提出“重构这个函数为两个独立函数”或“引入一个单例模式”这样的架构级建议。依赖外部系统或API的 Bug例如代码调用了一个外部 REST API但返回的数据格式与预期不符。模型无法感知外部系统的状态和契约变化其修复可能基于错误假设。极其罕见或复杂的第三方库错误对于某些库的深度用法或晦涩错误信息模型可能没有足够的训练数据来准确理解。性能问题与内存泄漏这类 Bug 通常没有直接的异常抛出需要通过 profiling 工具分析。我们的 Agent 目前只处理异常Exception不处理性能瓶颈。因此这个 Agent 的最佳定位是“第一响应者”或“初级调试助手”。它能快速消灭那些简单、重复的“低级错误”把开发者从繁琐的体力劳动中解放出来。当它尝试几次后仍然失败或者提出的修复方案明显违背业务逻辑时它生成的详细诊断报告包括它尝试过的路径和遇到的错误也能为人类开发者提供宝贵的上下文加速真正的人工调试过程。7. 扩展思路与未来展望这个基础版本的 Agent 已经打开了思路的大门。基于此框架我们可以从多个方向进行扩展让它变得更强大、更智能。7.1 扩展工具集成为全能开发助手目前 Agent 只有“运行代码”这一只手。我们可以为它装备更多工具让它能处理更广泛的任务文件读写工具让 Agent 能够读取项目中的其他源文件来获取更全面的上下文或者将修复后的代码写回到原文件需谨慎授权。Git 操作工具让 Agent 可以执行git diff,git log等命令理解代码变更历史甚至创建修复分支和提交。静态分析工具集成pylint,mypy等让 Agent 在运行前就能发现代码风格问题和类型隐患。网络搜索工具需谨慎在模型遇到未知错误信息时允许它安全地搜索公开的编程问答网站如 Stack Overflow 摘要获取解决方案思路。这需要严格的内容过滤和安全控制。7.2 集成到开发工作流中CI/CD 流水线集成在持续集成阶段让 Agent 自动分析测试失败的日志尝试修复并重新运行测试。如果修复成功且通过测试可以标记为“AI 辅助修复”供开发者审查合并。IDE 插件开发一个 IDE如 VS Code、PyCharm插件当开发者遇到运行时异常时一键调用本地或云端的这个 Agent将错误信息和当前文件上下文发送过去并直接在编辑器中应用建议的修复。日志监控告警响应与日志系统如 ELK、Sentry对接当生产环境出现特定频率或类型的错误时自动触发 Agent 进行分析并生成初步的修复报告或提交一个修复 PR大大缩短平均修复时间MTTR。7.3 提升安全性与可控性当前的代码执行工具仍有安全风险。为了在生产环境中更放心地使用可以考虑使用 Docker 沙箱将subprocess.run替换为在一次性 Docker 容器中执行代码。可以定制一个包含基础 Python 和常用库的轻量级镜像实现彻底的资源隔离和安全控制。代码扫描与白名单在执行前对 AI 生成的代码进行简单的静态扫描禁止导入如os.system,subprocess.Popen,__import__(‘os‘).system等明显危险的模块或函数调用。人工审核环节对于涉及文件系统修改、Git 操作或网络请求的“高风险”工具调用设计一个“暂停并等待人工批准”的机制。Agent 可以提出操作建议但执行前需要开发者点击确认。这个用 Claude Agent SDK 搭建的自动修 Bug Agent虽然核心代码只有 20 多行但它清晰地展示了大模型与工具结合后产生的“行动力”。它不再是一个被动的知识库而是一个能主动验证、迭代的智能体。对于每一位开发者而言真正的价值不在于完全取代自己而是利用这样的工具将我们的时间从重复性劳动中赎回投入到更有创造性的设计、架构和解决真正复杂的问题中去。