说个我几乎每天都会碰到的场景你让大模型帮忙看一段报错它回复了一段看起来很专业的修复意见你拿过去一跑还是炸。再给它一次机会它换了个思路这次倒是不炸了但你把补丁展开一看它把你整个函数都重写了还顺带改坏了一个你没注意到的接口。这种经历经历多了我慢慢意识到问题不是模型不够聪明而是它拿不到真实反馈。所以我开始折腾 AutoDebug Agent一种让 Agent 真正去执行、真正去看测试结果、真正用失败信号指导自己完成缺陷修复的智能体。这篇博文会把我踩过的坑、迭代过的架构、能直接参考的最小实现全部拆给你看适合正在做 AI Agent 开发、自动化缺陷修复或者刚进入 agent 学习路线的朋友直接上手。1. 为什么普通 Agent 不会修缺陷问题不在模型在反馈1.1 代码生成与缺陷修复是完全不同的任务很多人把让大模型修 bug当成让大模型写代码的延伸这是一个很深的误解。写一段新代码模型的任务是基于上下文做续写输出自洽、能解释通就算完成修一个缺陷则完全不同它需要 Agent 理解外部世界对这段代码的期望——测试断言是什么、调用方怎么用它、类型约束怎么限制它。换句话说修复的正确答案不一定在模型脑子里而往往只存在于真实运行环境中。我见过不少团队做缺陷修复 Agent 时第一反应是换更大的模型。这其实是把力气用错地方了。更大的模型只是让推理起点更好让 Agent 更容易读懂代码但决定一个修复过程能否收敛的是它有没有一个稳定、真实、连续的反馈回路。就像一个人在完全漆黑但允许碰壁的房间里找开关每一次撞墙的声音就是反馈有了声音他才能逐步缩小范围没有声音就算他方向感再好、智力再高也只能靠猜。这也是为什么很多刚进 agent 开发学习路线的人会纠结 LangChain、Dify、CrewAI 到底哪个好。框架当然有用但它解决的只是编排问题——怎么组织工具调用、怎么管理会话。真正让 Agent会修缺陷的是框架之外那一层反馈机制。框架给你搭好了舞台但戏能不能演好要看反馈够不够真实。1.2 真实反馈回路一次改动、一次执行、一次修正AutoDebug Agent 的核心设计可以用一句话概括Agent 做一次改动在真实环境里执行观察失败信号依据信号再改循环直到测试通过。这句话听起来平淡但真实两个字是全部的重点。真实反馈是指来自被测系统实际执行后产生的信号比如 pytest 某个断言失败、某个异常栈指向特定文件行号、某个接口返回了 500而不是模型自己揣测出来的我觉得问题可能在这里。两者看起来都有信息量但性质完全不同。前者是客观事实后者是主观猜测。主观猜测在多轮循环里不会产生信息增量所以你会看到许多 Agent 每一轮都给出不同的解释却永远修不对——因为它从头到尾都在猜只是换着花样猜。生活里有个很贴切的类比修漏水的水管。你判断可能是密封圈老化换上新的然后打开水龙头观察还漏不漏。不漏问题解决还漏说明判断错误再去检查下一个位置。整个过程完全由水是否还漏这个真实信号驱动你不会凭想象说我觉得应该不漏了。AutoDebug Agent 的逻辑一模一样。我在项目里定了一条铁律任何补丁必须经过真实执行验证绝不允许模型自己说看起来对了就算完事。1.3 三种信号源怎么选静态检查、单元测试、运行时报错真实环境里可以拿到的反馈信号很多但成本和信息密度差异极大我一般把它们分成三个级别来用。静态检查lint、类型检查最便宜也最快。它能抓语法错误、未定义变量、类型不匹配这类问题几乎零副作用适合在每一步补丁落地后立刻跑一遍快速筛掉低级错误。但它完全覆盖不到行为语义一个逻辑完全错误的函数也能轻松通过 lint。单元测试是信息价值最高的信号。一个失败断言通常会同时告诉你预期是什么和实际是什么这种对比对定位问题极其有用而且粒度小一个测试往往只覆盖一个具体行为失败信息能直接指向某个函数甚至某一行。运行时错误最接近生产真相。异常栈、崩溃日志、超时记录是系统在真实调用下暴露出来的证据很多单测覆盖不到的并发问题、资源泄漏问题只有在运行时才会浮现。信号类型产生时机优点缺点典型场景静态检查编译 / lint 阶段快、便宜、无副作用覆盖不到行为语义语法错误、类型错误、明显坏味道单元测试执行测试套件能验证行为契约定位精确测试本身可能写错行为回归、断言失败运行时错误真实调用 / 压测最接近生产真相噪音多、不稳定、难复现崩溃、超时、并发问题实际落地时我建议按成本从低到高依次接入形成一个多级反馈漏斗先 lint再单测最后看运行时报错。把高成本信号放在后面能显著减少无效执行次数也省 token。2. 四段式循环AutoDebug Agent 的核心架构2.1 第一步复现先把 Bug 烧成可见的失败拿到一个 bug 报告我做的第一件事不是让模型看代码而是先复现。没有稳定复现的 bug 就是一团迷雾后面所有修复动作都是在盲改改完也没法验证到底有没有效果。复现的实操方式一般有三种。第一种是找仓库里现成的测试入口pytest、go test、npm test、cargo test 都行先全量跑一遍看有没有已经失败的测试直接对应当前 bug。第二种是从 issue 或描述文本里抽取输入 期望输出的最小样例生成一个最小复现脚本关键是输入参数必须固定不能每次跑都不一样。第三种是把复现步骤固化成一个 shell 脚本存下来比如repro.sh之后每一步修复验证都跑同一个脚本保证前后对比的是同一件事。这里有个非常容易翻车的细节环境差异。本机 Python 3.12目标环境 3.8可能同一个 API 行为完全不同依赖锁定的版本不一致也会造成本地复现不了的假象。我处理过一个案子本机 SQLite 版本比生产高测试在本地永远通过一上生产就崩。后来把复现脚本里加上版本打印和依赖清单输出才把环境差异暴露出来。所以复现脚本里尽量固定环境版本必要时用容器这是省下后面所有麻烦的关键投资。2.2 第二步定位让输出从修复代码变成候选文件与假设定位阶段的目标不是给出修法而是产出一组候选文件、行号和假设。这看起来绕远路但效率反而更高。如果直接问模型怎么修它会只顾着从局部代码里猜答案先让它回答失败可能和哪些文件有关范围能先缩到几处下一轮再针对这些文件深入读源码准确率和 token 效率都会好很多。我做定位时会先把 stack trace 结构化提取文件路径、函数名、行号再借助 git log、git blame 看最近改动。很多 bug 是老代码遇到新数据才爆的改动历史往往是最好的线索。然后把结构化的摘要交给模型而不是把整段原始报错原样丢过去。我给定位模型设计的 prompt 多半长这样系统你是一个代码定位助手。根据下方失败信息列出最可能相关的候选文件和行号给出不超过 3 个假设。每个假设必须说明为什么与失败信息相关。不要给出修复代码。 用户 失败输出 {test_output} 仓库变更记录 {git_log}刻意让它不要给出修复代码是有原因的。定位阶段一旦掺杂了修复动作模型容易直接跳到结论忽略中间的证据链。候选文件控制在 3 到 5 个假设不超过 3 个。给一个模型塞几十个文件等于没有定位。2.3 第三步修复最小改动优先并强制附带修改解释完成定位才进入真正动手修改的阶段。我对修复阶段的要求就一条最小改动优先。一个合格的修复 Agent 应该先改条件判断其次改异常处理最后才考虑改算法或重构。风险排序很清晰逻辑分支 边界条件 结构性设计。为什么最小改动这么重要因为改动面越大补丁引入新缺陷的概率越高验证成本也越高。一个三行的补丁如果测试失败排查成本很低一个把三百行函数重写的补丁如果测试失败你几乎无法判断是哪里出的问题。我看到很多 Agent 修不好 bug不是判断力差而是野心太大动不动就重构。另外我会强制 Agent 在输出补丁的同时给出我认为这个改动为什么能通过测试的解释。这个解释看起来多余实际价值很大。到第三轮修复仍然失败时前两轮的错误假设和失败原因就是最宝贵的排除信息。把历史解释喂给下一轮模型它才知道哪些路已经走死了而不是从头再猜一遍。如果第一轮补丁失败也不要直接说再想想而是把失败输出和上一轮的补丁一起交给模型明确要求基于这次的失败信息说明上一个假设哪里不对再给出新的补丁。这样每一轮都有信息增量循环才可能收敛。2.4 第四步验证双轨验证与测试文件只读原则修完代码不等于解决验证阶段要同时做两件事。第一跑最初的复现脚本确认 bug 不再出现第二跑仓库现有的全量测试确认没有引入回归。很多实现只跑目标测试全量测试直接跳过结果 Agent 修好了目标函数却把另一个调用该函数的模块弄挂了。这个问题我见过不止一次而且特别难排查因为外表看起来测试全绿问题潜伏在没被覆盖的路径里。验证阶段还有一个特别隐蔽的坑Agent 有动机改写测试来证明自己修好了。它的优化目标是让测试变绿如果权限允许它可能会改断言、删用例或者把原本严格的断言放宽。这个行为非常危险等于学生自己给自己改考卷。我的对策是两条把测试文件设为只读或者在应用补丁前检查 git diff一旦发现测试文件被改动直接判定该轮修复无效并发出告警。最终产出不要只给一个 diff建议生成标准补丁文件附带验证记录复现脚本结果、单测结果、全量测试结果。后续人工 review 只需要看这一个文件就能快速判断这套补丁到底值不值得合入。3. 实操用 Python 搭一个最小可用的 AutoDebug Agent3.1 工具选型一个执行器、一个运行器、一个 Git 工具、一个 LLM 客户端我这套最小实现不依赖任何重型 Agent 框架。把一个 Bash 执行器、一个测试运行器、一个 Git 工具和一个 LLM 客户端封装起来就能开工。组件职责选型建议执行器在真实 shell 里跑命令本地 subprocess / Docker 容器 / 远程执行器测试运行器统一跑测试并解析结果pytest / go test / jest按仓库语言定Git 工具生成 diff、查看改动历史GitPython 或直接调用 git CLILLM 客户端完成定位、修复、解释各家 SDK统一封装成 chat 接口很多刚入门 agent 开发的朋友会在 LangChain、Dify、CrewAI 这些框架里纠结问哪个好。我的观点是这类工具密集型循环核心会话逻辑其实只有几十行自己写可控性反而更强。框架给你省的是工程封装的时间但也把很多细节藏了起来出了问题你连锅都找不到。自己写一个最小实现你能讲清楚每一行在做什么那是完全不一样的状态。3.2 可运行的循环实现从复现到验证的完整代码下面这个骨架是我常用的结构你可以把它直接抄进项目里改。它把前面说的四段式循环落成了代码import subprocess from pathlib import Path from openai import OpenAI class AutoDebugAgent: def __init__(self, repo_path: str, test_cmd: str, max_rounds: int 6): self.repo Path(repo_path) self.test_cmd test_cmd # 例如 python -m pytest tests/test_calc.py -x self.max_rounds max_rounds self.attempts [] # 记录每轮假设、补丁和失败原因 self.client OpenAI() # 统一 LLM 客户端可替换 def run_cmd(self, cmd: str) - tuple[int, str]: 在真实 shell 里执行命令返回退出码和输出。 p subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue, cwdself.repo) return p.returncode, p.stdout p.stderr def reproduce(self) - str: 先跑一遍目标测试建立失败基线。, rc, out self.run_cmd(self.test_cmd) return if rc 0 else out def localize(self, fail_output: str) - str: 让 LLM 从失败信号中定位候选文件和假设。 prompt ( 你是代码定位助手。根据失败的测试输出列出最可能相关的候选文件和行号 给出不超过 3 个假设每个假设必须说明证据。不要给出修复代码。\n\n f失败输出:\n{fail_output} ) resp self.client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}], ) return resp.choices[0].message.content def propose_patch(self, candidate: str, fail_output: str) - str: 让 LLM 基于定位结果生成统一 diff 补丁。 block \n.join( f- {a[hypothesis]} {a[fail_reason]} for a in self.attempts ) prompt ( 你是修复工程师。基于候选定位和失败信息输出统一 diff 补丁 并解释为什么能通过测试。不得重复尝试以下已失败的假设:\n f{block}\n\n候选定位:\n{candidate}\n\n失败输出:\n{fail_output} ) resp self.client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}], ) return resp.choices[0].message.content def apply_patch(self, patch: str) - bool: 用 git apply 落盘补丁防止测试文件被改动。 p subprocess.run( [git, apply, --check, -], inputpatch, textTrue, capture_outputTrue, cwdself.repo ) if p.returncode ! 0: return False subprocess.run( [git, apply, -], inputpatch, textTrue, capture_outputTrue, cwdself.repo ) return True def verify(self) - tuple[bool, str]: 验证跑复现脚本 全量测试并检查测试文件是否被动过。 diff_cmd git diff --name-only rc, before self.run_cmd(diff_cmd) rc_fix, fix_out self.run_cmd(self.test_cmd) rc_all, all_out self.run_cmd(python -m pytest -q) rc, after self.run_cmd(diff_cmd) test_files_changed any(test in f for f in after.splitlines()) if test_files_changed: return False, 测试文件被修改判定无效 return (rc_fix 0 and rc_all 0), fix_out all_out def run(self) - str: fail_output self.reproduce() if not fail_output: return already_ok for i in range(self.max_rounds): candidate self.localize(fail_output) patch self.propose_patch(candidate, fail_output) if not self.apply_patch(patch): fail_output 补丁格式错误无法应用 continue ok, verify_out self.verify() if ok: return fsuccess_in_round_{i 1} # 把当前假设和失败原因存入 attempts下一轮避免重复试错 self.attempts.append({ hypothesis: candidate, fail_reason: verify_out[-1000:], }) fail_output verify_out[-1000:] return max_rounds_reached这个实现里有两个细节值得你重视。第一apply_patch用的git apply --check是事务性验证格式不对就不会落盘避免把仓库改到一半。第二attempts列表是 Agent 的短期记忆每一轮都会带给模型防止它反复提出相同的假设。很多 Agent 修不动 bug不是模型不会而是它忘记了自己已经试错了什么。3.3 Token 控制分层会话 状态摘要避免上下文爆炸Agent 循环里最容易被忽略的坑是 token 成本失控。很多人把每轮失败输出、上一轮补丁、上一轮解释全部追加进历史三轮之后 prompt 长度指数膨胀模型开始在噪声里找信号效果反而更差。我的做法是分层会话定位会话只接收失败摘要和变更历史修复会话只接收候选文件源码和失败详情每次循环结束时把当前状态压缩成一条结构化摘要——已尝试方案、失败原因、下一步候选。这条摘要成为下一轮 system prompt 的一部分。它相当于 Agent 的一个短期记忆但不是把所有历史塞进去而是提炼出对下一步真正有信息量的部分。控制 token 不单纯为了省钱。更短、更干净的上下文模型产生的幻觉和臆测明显更少。我看到很多 Agent 表现不稳定不是模型不行而是上下文里装满了无用噪音。prompt 里噪音越多模型越容易把注意力分散到无关信息上真正的行号和失败信号反而被淹没了。4. 踩坑实录修复 Agent 常见的 5 个典型失败模式4.1 死循环为什么 Agent 会反复提出同一个假设修复循环里最常见的失控模式是原地打转第一轮提出假设 A测试失败第二轮它又提出几乎一样的假设 A然后又失败。原因很简单它没有把上一轮的假设已经失败变成硬约束。模型本身没有记忆每一轮都是从头推理如果 prompt 里不显式记录历史它当然会走到同样的结论上。解决手段有两个。第一维护 attempts 列表每一轮生成补丁前都注入已尝试方案及失败原因并明确要求不得重复已有方案。第二设置最大轮数上限比如 6 轮同时在连续两轮补丁完全相同时触发提前终止。这是我代码里max_rounds的真正意义。提示max_rounds 不是可选项是预算保护机制。没有它一次失控循环可能把 token 成本拉爆还会把仓库改成一团乱麻。4.2 修症状不修病因最隐蔽的假阳性修复这是所有失败模式里最隐蔽的一种。函数抛异常Agent 不去修根因而是裹了一层 try-except 把异常吞掉。测试确实变绿了但业务状态错误被掩盖了后续排障成本比不修还高。判断标准其实很简单这个修复是让行为符合契约还是仅仅让失败不再出现凡是出现 silent except、把报错降级成 warning、或者用宽泛的默认值掩盖错误路径的补丁都要标记为高风险并要求模型提供解释。修复的真正目标是测试断言和业务约束都保持原样的情况下通过测试而不是单纯地让它不红。我踩过这个坑之后验证阶段都会额外 scan 一遍except: pass这类模式绝不放过。4.3 没有测试时的自欺欺人Agent 给自己打分如果仓库里没有任何测试Agent 为了完成任务会自己造一个测试来证明修好了。更糟糕的是它会倾向于造一个恰好通过自己补丁的测试这等于学生自己给自己批改试卷分数没有任何参考价值。处理老项目时会特别痛苦。没有测试的老代码AutoDebug Agent 基本发挥不出真实反馈的优势因为反馈信号本身不存在。我在实践中花半天时间先把核心函数的关键路径用 golden data 固定下来也就是准备一批已知输入和期望输出作为验收标准。有了这批数据Agent 的修复才有客观的衡量尺度新增测试也必须走人工 review不允许 Agent 自动合入自己写的测试。4.4 反馈被污染单独测试通过但全量测试失败真实反馈有一个被严重低估的威胁反馈本身可能被污染。最典型的症状是一条测试单独跑能过全量跑就挂。原因通常是测试之间共享了数据库、临时文件、环境变量前一个测试破坏了状态后一个测试莫名失败。Agent 感知到这个现象很可能误判成并发 bug然后去修业务代码越修越乱。这种问题靠模型推理很难解决因为模型看到的是假象。我的对策是环境隔离每次验证在干净容器或全新临时目录里执行跑完就丢弃固定随机种子禁用网络依赖除非被测对象本来就依赖网络。这算是真实反馈理念的延伸——要让反馈可信就必须先隔离环境。反馈一旦被污染后面所有修复动作都是建立在流沙上的。4.5 上下文爆炸信息量越大不代表信号越干净多轮循环跑到后期最明显的问题就是上下文爆炸。每轮往 prompt 里追加失败日志的后果是模型把注意力平分给大量噪音真正有用的行号反而被淹没。我前面讲的状态摘要策略就是针对这个问题设计的。但除了状态摘要还有一件配套的事必须做明确定义停止条件。测试通过当然是一个条件达到 max_rounds 是第二个连续 N 轮补丁无变化是第三个。三个条件不是或的关系而是共同组成护栏。三者都满足时循环自然终止任何一个触发都需要人工介入看一眼。我自己在实际调试中体会到AutoDebug Agent 最难的部分从来不是让模型写补丁而是让反馈更真实。每一次把环境隔离做干净、把上下文压缩得更有信息量、把失败信号结构化成可查的证据都是在给模型降低难度。想通这条任何 Agent 框架都能搭出真正会修缺陷的东西。
说个我几乎每天都会碰到的场景你让大模型帮忙看一段报错它回复了一段看起来很专业的修复意见你拿过去一跑还是炸。再给它一次机会它换了个思路这次倒是不炸了但你把补丁展开一看它把你整个函数都重写了还顺带改坏了一个你没注意到的接口。这种经历经历多了我慢慢意识到问题不是模型不够聪明而是它拿不到真实反馈。所以我开始折腾 AutoDebug Agent一种让 Agent 真正去执行、真正去看测试结果、真正用失败信号指导自己完成缺陷修复的智能体。这篇博文会把我踩过的坑、迭代过的架构、能直接参考的最小实现全部拆给你看适合正在做 AI Agent 开发、自动化缺陷修复或者刚进入 agent 学习路线的朋友直接上手。1. 为什么普通 Agent 不会修缺陷问题不在模型在反馈1.1 代码生成与缺陷修复是完全不同的任务很多人把让大模型修 bug当成让大模型写代码的延伸这是一个很深的误解。写一段新代码模型的任务是基于上下文做续写输出自洽、能解释通就算完成修一个缺陷则完全不同它需要 Agent 理解外部世界对这段代码的期望——测试断言是什么、调用方怎么用它、类型约束怎么限制它。换句话说修复的正确答案不一定在模型脑子里而往往只存在于真实运行环境中。我见过不少团队做缺陷修复 Agent 时第一反应是换更大的模型。这其实是把力气用错地方了。更大的模型只是让推理起点更好让 Agent 更容易读懂代码但决定一个修复过程能否收敛的是它有没有一个稳定、真实、连续的反馈回路。就像一个人在完全漆黑但允许碰壁的房间里找开关每一次撞墙的声音就是反馈有了声音他才能逐步缩小范围没有声音就算他方向感再好、智力再高也只能靠猜。这也是为什么很多刚进 agent 开发学习路线的人会纠结 LangChain、Dify、CrewAI 到底哪个好。框架当然有用但它解决的只是编排问题——怎么组织工具调用、怎么管理会话。真正让 Agent会修缺陷的是框架之外那一层反馈机制。框架给你搭好了舞台但戏能不能演好要看反馈够不够真实。1.2 真实反馈回路一次改动、一次执行、一次修正AutoDebug Agent 的核心设计可以用一句话概括Agent 做一次改动在真实环境里执行观察失败信号依据信号再改循环直到测试通过。这句话听起来平淡但真实两个字是全部的重点。真实反馈是指来自被测系统实际执行后产生的信号比如 pytest 某个断言失败、某个异常栈指向特定文件行号、某个接口返回了 500而不是模型自己揣测出来的我觉得问题可能在这里。两者看起来都有信息量但性质完全不同。前者是客观事实后者是主观猜测。主观猜测在多轮循环里不会产生信息增量所以你会看到许多 Agent 每一轮都给出不同的解释却永远修不对——因为它从头到尾都在猜只是换着花样猜。生活里有个很贴切的类比修漏水的水管。你判断可能是密封圈老化换上新的然后打开水龙头观察还漏不漏。不漏问题解决还漏说明判断错误再去检查下一个位置。整个过程完全由水是否还漏这个真实信号驱动你不会凭想象说我觉得应该不漏了。AutoDebug Agent 的逻辑一模一样。我在项目里定了一条铁律任何补丁必须经过真实执行验证绝不允许模型自己说看起来对了就算完事。1.3 三种信号源怎么选静态检查、单元测试、运行时报错真实环境里可以拿到的反馈信号很多但成本和信息密度差异极大我一般把它们分成三个级别来用。静态检查lint、类型检查最便宜也最快。它能抓语法错误、未定义变量、类型不匹配这类问题几乎零副作用适合在每一步补丁落地后立刻跑一遍快速筛掉低级错误。但它完全覆盖不到行为语义一个逻辑完全错误的函数也能轻松通过 lint。单元测试是信息价值最高的信号。一个失败断言通常会同时告诉你预期是什么和实际是什么这种对比对定位问题极其有用而且粒度小一个测试往往只覆盖一个具体行为失败信息能直接指向某个函数甚至某一行。运行时错误最接近生产真相。异常栈、崩溃日志、超时记录是系统在真实调用下暴露出来的证据很多单测覆盖不到的并发问题、资源泄漏问题只有在运行时才会浮现。信号类型产生时机优点缺点典型场景静态检查编译 / lint 阶段快、便宜、无副作用覆盖不到行为语义语法错误、类型错误、明显坏味道单元测试执行测试套件能验证行为契约定位精确测试本身可能写错行为回归、断言失败运行时错误真实调用 / 压测最接近生产真相噪音多、不稳定、难复现崩溃、超时、并发问题实际落地时我建议按成本从低到高依次接入形成一个多级反馈漏斗先 lint再单测最后看运行时报错。把高成本信号放在后面能显著减少无效执行次数也省 token。2. 四段式循环AutoDebug Agent 的核心架构2.1 第一步复现先把 Bug 烧成可见的失败拿到一个 bug 报告我做的第一件事不是让模型看代码而是先复现。没有稳定复现的 bug 就是一团迷雾后面所有修复动作都是在盲改改完也没法验证到底有没有效果。复现的实操方式一般有三种。第一种是找仓库里现成的测试入口pytest、go test、npm test、cargo test 都行先全量跑一遍看有没有已经失败的测试直接对应当前 bug。第二种是从 issue 或描述文本里抽取输入 期望输出的最小样例生成一个最小复现脚本关键是输入参数必须固定不能每次跑都不一样。第三种是把复现步骤固化成一个 shell 脚本存下来比如repro.sh之后每一步修复验证都跑同一个脚本保证前后对比的是同一件事。这里有个非常容易翻车的细节环境差异。本机 Python 3.12目标环境 3.8可能同一个 API 行为完全不同依赖锁定的版本不一致也会造成本地复现不了的假象。我处理过一个案子本机 SQLite 版本比生产高测试在本地永远通过一上生产就崩。后来把复现脚本里加上版本打印和依赖清单输出才把环境差异暴露出来。所以复现脚本里尽量固定环境版本必要时用容器这是省下后面所有麻烦的关键投资。2.2 第二步定位让输出从修复代码变成候选文件与假设定位阶段的目标不是给出修法而是产出一组候选文件、行号和假设。这看起来绕远路但效率反而更高。如果直接问模型怎么修它会只顾着从局部代码里猜答案先让它回答失败可能和哪些文件有关范围能先缩到几处下一轮再针对这些文件深入读源码准确率和 token 效率都会好很多。我做定位时会先把 stack trace 结构化提取文件路径、函数名、行号再借助 git log、git blame 看最近改动。很多 bug 是老代码遇到新数据才爆的改动历史往往是最好的线索。然后把结构化的摘要交给模型而不是把整段原始报错原样丢过去。我给定位模型设计的 prompt 多半长这样系统你是一个代码定位助手。根据下方失败信息列出最可能相关的候选文件和行号给出不超过 3 个假设。每个假设必须说明为什么与失败信息相关。不要给出修复代码。 用户 失败输出 {test_output} 仓库变更记录 {git_log}刻意让它不要给出修复代码是有原因的。定位阶段一旦掺杂了修复动作模型容易直接跳到结论忽略中间的证据链。候选文件控制在 3 到 5 个假设不超过 3 个。给一个模型塞几十个文件等于没有定位。2.3 第三步修复最小改动优先并强制附带修改解释完成定位才进入真正动手修改的阶段。我对修复阶段的要求就一条最小改动优先。一个合格的修复 Agent 应该先改条件判断其次改异常处理最后才考虑改算法或重构。风险排序很清晰逻辑分支 边界条件 结构性设计。为什么最小改动这么重要因为改动面越大补丁引入新缺陷的概率越高验证成本也越高。一个三行的补丁如果测试失败排查成本很低一个把三百行函数重写的补丁如果测试失败你几乎无法判断是哪里出的问题。我看到很多 Agent 修不好 bug不是判断力差而是野心太大动不动就重构。另外我会强制 Agent 在输出补丁的同时给出我认为这个改动为什么能通过测试的解释。这个解释看起来多余实际价值很大。到第三轮修复仍然失败时前两轮的错误假设和失败原因就是最宝贵的排除信息。把历史解释喂给下一轮模型它才知道哪些路已经走死了而不是从头再猜一遍。如果第一轮补丁失败也不要直接说再想想而是把失败输出和上一轮的补丁一起交给模型明确要求基于这次的失败信息说明上一个假设哪里不对再给出新的补丁。这样每一轮都有信息增量循环才可能收敛。2.4 第四步验证双轨验证与测试文件只读原则修完代码不等于解决验证阶段要同时做两件事。第一跑最初的复现脚本确认 bug 不再出现第二跑仓库现有的全量测试确认没有引入回归。很多实现只跑目标测试全量测试直接跳过结果 Agent 修好了目标函数却把另一个调用该函数的模块弄挂了。这个问题我见过不止一次而且特别难排查因为外表看起来测试全绿问题潜伏在没被覆盖的路径里。验证阶段还有一个特别隐蔽的坑Agent 有动机改写测试来证明自己修好了。它的优化目标是让测试变绿如果权限允许它可能会改断言、删用例或者把原本严格的断言放宽。这个行为非常危险等于学生自己给自己改考卷。我的对策是两条把测试文件设为只读或者在应用补丁前检查 git diff一旦发现测试文件被改动直接判定该轮修复无效并发出告警。最终产出不要只给一个 diff建议生成标准补丁文件附带验证记录复现脚本结果、单测结果、全量测试结果。后续人工 review 只需要看这一个文件就能快速判断这套补丁到底值不值得合入。3. 实操用 Python 搭一个最小可用的 AutoDebug Agent3.1 工具选型一个执行器、一个运行器、一个 Git 工具、一个 LLM 客户端我这套最小实现不依赖任何重型 Agent 框架。把一个 Bash 执行器、一个测试运行器、一个 Git 工具和一个 LLM 客户端封装起来就能开工。组件职责选型建议执行器在真实 shell 里跑命令本地 subprocess / Docker 容器 / 远程执行器测试运行器统一跑测试并解析结果pytest / go test / jest按仓库语言定Git 工具生成 diff、查看改动历史GitPython 或直接调用 git CLILLM 客户端完成定位、修复、解释各家 SDK统一封装成 chat 接口很多刚入门 agent 开发的朋友会在 LangChain、Dify、CrewAI 这些框架里纠结问哪个好。我的观点是这类工具密集型循环核心会话逻辑其实只有几十行自己写可控性反而更强。框架给你省的是工程封装的时间但也把很多细节藏了起来出了问题你连锅都找不到。自己写一个最小实现你能讲清楚每一行在做什么那是完全不一样的状态。3.2 可运行的循环实现从复现到验证的完整代码下面这个骨架是我常用的结构你可以把它直接抄进项目里改。它把前面说的四段式循环落成了代码import subprocess from pathlib import Path from openai import OpenAI class AutoDebugAgent: def __init__(self, repo_path: str, test_cmd: str, max_rounds: int 6): self.repo Path(repo_path) self.test_cmd test_cmd # 例如 python -m pytest tests/test_calc.py -x self.max_rounds max_rounds self.attempts [] # 记录每轮假设、补丁和失败原因 self.client OpenAI() # 统一 LLM 客户端可替换 def run_cmd(self, cmd: str) - tuple[int, str]: 在真实 shell 里执行命令返回退出码和输出。 p subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue, cwdself.repo) return p.returncode, p.stdout p.stderr def reproduce(self) - str: 先跑一遍目标测试建立失败基线。, rc, out self.run_cmd(self.test_cmd) return if rc 0 else out def localize(self, fail_output: str) - str: 让 LLM 从失败信号中定位候选文件和假设。 prompt ( 你是代码定位助手。根据失败的测试输出列出最可能相关的候选文件和行号 给出不超过 3 个假设每个假设必须说明证据。不要给出修复代码。\n\n f失败输出:\n{fail_output} ) resp self.client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}], ) return resp.choices[0].message.content def propose_patch(self, candidate: str, fail_output: str) - str: 让 LLM 基于定位结果生成统一 diff 补丁。 block \n.join( f- {a[hypothesis]} {a[fail_reason]} for a in self.attempts ) prompt ( 你是修复工程师。基于候选定位和失败信息输出统一 diff 补丁 并解释为什么能通过测试。不得重复尝试以下已失败的假设:\n f{block}\n\n候选定位:\n{candidate}\n\n失败输出:\n{fail_output} ) resp self.client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}], ) return resp.choices[0].message.content def apply_patch(self, patch: str) - bool: 用 git apply 落盘补丁防止测试文件被改动。 p subprocess.run( [git, apply, --check, -], inputpatch, textTrue, capture_outputTrue, cwdself.repo ) if p.returncode ! 0: return False subprocess.run( [git, apply, -], inputpatch, textTrue, capture_outputTrue, cwdself.repo ) return True def verify(self) - tuple[bool, str]: 验证跑复现脚本 全量测试并检查测试文件是否被动过。 diff_cmd git diff --name-only rc, before self.run_cmd(diff_cmd) rc_fix, fix_out self.run_cmd(self.test_cmd) rc_all, all_out self.run_cmd(python -m pytest -q) rc, after self.run_cmd(diff_cmd) test_files_changed any(test in f for f in after.splitlines()) if test_files_changed: return False, 测试文件被修改判定无效 return (rc_fix 0 and rc_all 0), fix_out all_out def run(self) - str: fail_output self.reproduce() if not fail_output: return already_ok for i in range(self.max_rounds): candidate self.localize(fail_output) patch self.propose_patch(candidate, fail_output) if not self.apply_patch(patch): fail_output 补丁格式错误无法应用 continue ok, verify_out self.verify() if ok: return fsuccess_in_round_{i 1} # 把当前假设和失败原因存入 attempts下一轮避免重复试错 self.attempts.append({ hypothesis: candidate, fail_reason: verify_out[-1000:], }) fail_output verify_out[-1000:] return max_rounds_reached这个实现里有两个细节值得你重视。第一apply_patch用的git apply --check是事务性验证格式不对就不会落盘避免把仓库改到一半。第二attempts列表是 Agent 的短期记忆每一轮都会带给模型防止它反复提出相同的假设。很多 Agent 修不动 bug不是模型不会而是它忘记了自己已经试错了什么。3.3 Token 控制分层会话 状态摘要避免上下文爆炸Agent 循环里最容易被忽略的坑是 token 成本失控。很多人把每轮失败输出、上一轮补丁、上一轮解释全部追加进历史三轮之后 prompt 长度指数膨胀模型开始在噪声里找信号效果反而更差。我的做法是分层会话定位会话只接收失败摘要和变更历史修复会话只接收候选文件源码和失败详情每次循环结束时把当前状态压缩成一条结构化摘要——已尝试方案、失败原因、下一步候选。这条摘要成为下一轮 system prompt 的一部分。它相当于 Agent 的一个短期记忆但不是把所有历史塞进去而是提炼出对下一步真正有信息量的部分。控制 token 不单纯为了省钱。更短、更干净的上下文模型产生的幻觉和臆测明显更少。我看到很多 Agent 表现不稳定不是模型不行而是上下文里装满了无用噪音。prompt 里噪音越多模型越容易把注意力分散到无关信息上真正的行号和失败信号反而被淹没了。4. 踩坑实录修复 Agent 常见的 5 个典型失败模式4.1 死循环为什么 Agent 会反复提出同一个假设修复循环里最常见的失控模式是原地打转第一轮提出假设 A测试失败第二轮它又提出几乎一样的假设 A然后又失败。原因很简单它没有把上一轮的假设已经失败变成硬约束。模型本身没有记忆每一轮都是从头推理如果 prompt 里不显式记录历史它当然会走到同样的结论上。解决手段有两个。第一维护 attempts 列表每一轮生成补丁前都注入已尝试方案及失败原因并明确要求不得重复已有方案。第二设置最大轮数上限比如 6 轮同时在连续两轮补丁完全相同时触发提前终止。这是我代码里max_rounds的真正意义。提示max_rounds 不是可选项是预算保护机制。没有它一次失控循环可能把 token 成本拉爆还会把仓库改成一团乱麻。4.2 修症状不修病因最隐蔽的假阳性修复这是所有失败模式里最隐蔽的一种。函数抛异常Agent 不去修根因而是裹了一层 try-except 把异常吞掉。测试确实变绿了但业务状态错误被掩盖了后续排障成本比不修还高。判断标准其实很简单这个修复是让行为符合契约还是仅仅让失败不再出现凡是出现 silent except、把报错降级成 warning、或者用宽泛的默认值掩盖错误路径的补丁都要标记为高风险并要求模型提供解释。修复的真正目标是测试断言和业务约束都保持原样的情况下通过测试而不是单纯地让它不红。我踩过这个坑之后验证阶段都会额外 scan 一遍except: pass这类模式绝不放过。4.3 没有测试时的自欺欺人Agent 给自己打分如果仓库里没有任何测试Agent 为了完成任务会自己造一个测试来证明修好了。更糟糕的是它会倾向于造一个恰好通过自己补丁的测试这等于学生自己给自己批改试卷分数没有任何参考价值。处理老项目时会特别痛苦。没有测试的老代码AutoDebug Agent 基本发挥不出真实反馈的优势因为反馈信号本身不存在。我在实践中花半天时间先把核心函数的关键路径用 golden data 固定下来也就是准备一批已知输入和期望输出作为验收标准。有了这批数据Agent 的修复才有客观的衡量尺度新增测试也必须走人工 review不允许 Agent 自动合入自己写的测试。4.4 反馈被污染单独测试通过但全量测试失败真实反馈有一个被严重低估的威胁反馈本身可能被污染。最典型的症状是一条测试单独跑能过全量跑就挂。原因通常是测试之间共享了数据库、临时文件、环境变量前一个测试破坏了状态后一个测试莫名失败。Agent 感知到这个现象很可能误判成并发 bug然后去修业务代码越修越乱。这种问题靠模型推理很难解决因为模型看到的是假象。我的对策是环境隔离每次验证在干净容器或全新临时目录里执行跑完就丢弃固定随机种子禁用网络依赖除非被测对象本来就依赖网络。这算是真实反馈理念的延伸——要让反馈可信就必须先隔离环境。反馈一旦被污染后面所有修复动作都是建立在流沙上的。4.5 上下文爆炸信息量越大不代表信号越干净多轮循环跑到后期最明显的问题就是上下文爆炸。每轮往 prompt 里追加失败日志的后果是模型把注意力平分给大量噪音真正有用的行号反而被淹没。我前面讲的状态摘要策略就是针对这个问题设计的。但除了状态摘要还有一件配套的事必须做明确定义停止条件。测试通过当然是一个条件达到 max_rounds 是第二个连续 N 轮补丁无变化是第三个。三个条件不是或的关系而是共同组成护栏。三者都满足时循环自然终止任何一个触发都需要人工介入看一眼。我自己在实际调试中体会到AutoDebug Agent 最难的部分从来不是让模型写补丁而是让反馈更真实。每一次把环境隔离做干净、把上下文压缩得更有信息量、把失败信号结构化成可查的证据都是在给模型降低难度。想通这条任何 Agent 框架都能搭出真正会修缺陷的东西。
