1. 为什么“定位”和“修复”不能塞进同一个任务里1.1 一个让所有 Agent 开发者都踩过的坑如果你最近在折腾 AI Agent 自动修 bug大概率遇到过这种场景你写了一个提示词让模型“找到这个报错的原因并修复它”然后满怀期待地跑起来。结果模型要么在代码库里漫无目的地翻来翻去要么直接给你一个看起来像那么回事、实际上完全跑不通的补丁要么改了一堆不该改的文件把原本正常的逻辑也搞坏了。我最早做这类工具的时候也是这么干的一个 prompt 打天下结果调试了两周才发现问题根本不在模型能力上而在于任务设计本身。把“定位 bug”和“修复 bug”合并成一个任务本质上是在让模型同时做两件认知模式完全不同的事情这就像让一个人一边在迷宫里找出口一边还要顺手把墙上的画重新挂正——他大概率两件事都做不好。后来我把这两个环节拆开定位归定位、修复归修复整个系统的成功率肉眼可见地往上走。这篇文章就把这套拆分思路完整讲清楚包括为什么要拆、怎么拆、拆完之后每个环节具体怎么做、中间怎么传递信息、以及我在实操中踩过的那些坑。不管你是刚接触 Agent 开发还是已经在做多 AI 协作的自动化流程这套方法论都能直接拿去用。1.2 定位和修复认知模式到底差在哪先说清楚这两件事的本质区别不然后面的设计都是空中楼阁。定位Localization的核心是“收敛”。你手里有一个现象——报错信息、异常行为、测试失败——需要从整个代码库、日志、调用链里一步步缩小范围最终锁定到具体的文件、函数、甚至某一行。这个过程是搜索和排除是信息不断收窄的过程。它考验的是模型对代码结构的理解、对错误信息的解析能力、以及对“哪里可能出问题”的直觉判断。修复Repair的核心是“构造”。你已经知道问题在哪了现在需要生成一段正确的代码来替换或补充原有的逻辑。这个过程是生成和验证是信息从少到多的过程。它考验的是模型对编程语言语义的掌握、对上下文约束的理解、以及对“改成什么样才不会引入新问题”的判断。你看一个是做减法一个是做加法。一个要求广撒网再收口一个要求精准打击。把它们塞进同一个 prompt模型在“搜索模式”和“生成模式”之间反复横跳注意力被严重分散出错概率自然飙升。1.3 合并任务的三个致命问题我总结下来合并任务主要有三个绕不过去的坑。第一个坑是上下文污染。定位阶段模型需要读大量代码、日志、堆栈信息这些内容会塞满上下文窗口。等到该修复的时候模型已经被一堆无关信息淹没了真正关键的约束比如“这个函数不能改签名”“这个变量是全局共享的”反而被挤到了边缘生成质量断崖式下降。第二个坑是目标冲突。定位的目标是“找得准”修复的目标是“改得对”。当模型同时背负这两个目标时它会产生一种很微妙的偏差为了让修复看起来合理它可能会倾向于选择一个“好修”的定位结果而不是真正正确的那个。这在复杂 bug 上尤其明显模型会挑软柿子捏。第三个坑是无法独立评估。合并之后你根本不知道是定位错了还是修复错了。测试没通过是没找到真正的问题点还是找到了但改错了你没法归因也就没法针对性优化。拆开之后定位有定位的评估指标命中率、Top-K 准确率修复有修复的评估指标编译通过率、测试通过率每个环节都能单独调优。2. 拆分之后的任务架构怎么设计2.1 两个 Agent 还是一条流水线的两个阶段拆分的第一种做法是搞两个独立的 Agent一个专门定位、一个专门修复中间通过结构化数据传递信息。第二种做法是同一条流水线里的两个阶段共享部分上下文但各自有独立的提示词和工具集。我两种都试过最后倾向于在简单场景用流水线两阶段在复杂场景用双 Agent。区别在于如果 bug 类型比较固定、代码库规模不大流水线足够用实现简单、延迟低如果 bug 类型多样、代码库庞大、需要多轮交互才能定位那双 Agent 更合适因为定位 Agent 可以有自己的记忆和探索策略不被修复任务干扰。具体怎么选可以看这个对照维度流水线两阶段双 Agent实现复杂度低中高适用代码库规模中小型大型支持多轮定位有限完整上下文隔离程度部分隔离完全隔离调试难度低中延迟低较高2.2 定位 Agent 的职责边界定位 Agent 只干一件事给定一个 bug 现象输出一个或多个可疑位置附带置信度和推理依据。它不负责改代码一行都不改。它的输出应该是一个结构化的东西比如{ bug_id: issue-1234, suspected_locations: [ { file: src/service/order.py, function: calculate_discount, line_range: [45, 67], confidence: 0.85, reason: 该函数在传入负数数量时未做边界检查与报错日志中的 ValueError 一致 }, { file: src/utils/validator.py, function: validate_quantity, line_range: [12, 20], confidence: 0.6, reason: 校验逻辑可能被上游绕过 } ], evidence: [报错堆栈, 相关日志片段, 调用链分析] }这个结构很关键它让定位和修复之间的接口变得清晰。修复 Agent 拿到这个结构就知道该去看哪些文件、哪些函数不用重新做一遍搜索。2.3 修复 Agent 的职责边界修复 Agent 拿到定位结果后只在这些候选位置上做文章。它的任务是生成补丁、验证补丁、必要时回退重试。这里有个设计要点修复 Agent 不应该被允许“自由发挥”去改定位结果之外的地方。我见过太多案例修复 Agent 觉得“顺便把这个也优化一下”结果引入了新 bug。所以要在提示词里明确约束只改候选位置及其直接依赖改动范围最小化。修复 Agent 的输出同样要结构化{ bug_id: issue-1234, target_location: src/service/order.py:calculate_discount, patch: diff内容, explanation: 在函数入口增加数量非负校验负数时抛出明确的业务异常, verification: { compile_passed: true, tests_passed: true, test_command: pytest tests/test_order.py -k discount } }2.4 中间层信息怎么传才不丢两个阶段之间的信息传递是最容易出问题的地方。传少了修复 Agent 信息不足传多了又把定位阶段的噪音带过去了。我的经验是传三类信息定位结果本身、关键证据摘要、以及约束条件。约束条件包括“这个函数被哪些地方调用”“有没有相关测试”“代码风格要求”等。证据摘要不要传原始日志全文而是传定位 Agent 提炼过的关键片段通常三五条就够了。注意千万不要把定位 Agent 的完整思考过程传给修复 Agent。那些“我一开始以为是 A后来发现是 B”的中间推理对修复没有任何帮助只会干扰判断。3. 定位环节的实操要点3.1 怎么让模型“找得准”定位准确率是整个系统的天花板。定位错了修复再厉害也是白搭。提升定位准确率我总结了几个实操要点。第一给足现象描述。不要只给一句“这个功能坏了”要给完整的报错信息、复现步骤、预期行为、实际行为。信息越具体模型收敛越快。如果只有模糊描述模型只能靠猜命中率自然低。第二提供代码结构地图。在提示词里附上项目的目录结构、关键模块说明、以及可能的入口文件。这相当于给模型一张地图让它不用从零开始摸索。对于大型项目这一步能显著提升效率。第三用工具辅助搜索。定位 Agent 应该配备代码搜索工具比如基于关键词或语义的检索、日志查询工具、以及调用链分析工具。让模型主动调用这些工具去缩小范围而不是一次性把所有代码塞进上下文。第四要求输出推理链。让模型在给出位置的同时说明“为什么怀疑这里”这个推理链不仅能提升准确率因为模型被迫想清楚还方便你事后复盘定位逻辑对不对。3.2 定位结果的置信度怎么用定位 Agent 输出的置信度不是摆设它在后续流程里有两个用途。一是决定是否直接进入修复。如果最高置信度超过某个阈值我一般设 0.8就直接修如果低于阈值要么让定位 Agent 再跑一轮要么转人工确认。二是决定修复策略。高置信度时修复 Agent 可以大胆改低置信度时修复 Agent 应该更保守比如只做最小改动、或者生成多个候选补丁让人来选。置信度的校准是个技术活。模型自己报的置信度往往偏乐观我一般会用一个小的验证集来校准把模型报的 0.9 映射到实际的 0.7 左右这样阈值才有意义。3.3 多候选位置的处理策略真实场景里定位 Agent 经常给出多个候选位置这时候怎么处理我的做法是按置信度排序逐个尝试修复。先修置信度最高的如果测试通过就结束如果不通过回退再试第二高的。这样既保证了效率又不会因为第一个猜错就全盘失败。但要注意设置尝试上限一般不超过 3 个。超过 3 个还没修好说明定位阶段就有问题应该回到定位重新分析而不是继续在修复阶段硬试。3.4 定位阶段的常见误区误区一追求一次定位到位。复杂 bug 往往需要多轮探索指望一次就找准是不现实的。要给定位 Agent 设计多轮交互的能力允许它先粗筛再精确定位。误区二忽略历史信息。如果这个 bug 之前有人修过、或者相关代码最近有改动这些信息对定位极有价值。要把 git 历史、issue 讨论等纳入定位 Agent 的输入。误区三定位粒度太粗。只说“问题在 order 模块”是没用的要精确到函数甚至行。粒度越细修复越容易。如果模型只能给到模块级说明它还没真正理解问题。4. 修复环节的实操要点4.1 修复提示词怎么写才有效修复 Agent 的提示词和定位完全不同核心是约束而不是探索。我一般包含这几块任务说明明确告诉它“你只需要修改以下位置不要动其他地方”定位结果把定位 Agent 的输出结构化地放进去代码上下文目标函数及其直接依赖的代码约束条件编码规范、不能改的接口、必须保留的行为验证要求改完必须能通过哪些测试这里有个细节代码上下文要给多少。给太少模型不了解全貌容易改错给太多又浪费上下文。我的经验是给目标函数加上它的直接调用者和被调用者通常两三层就够了。4.2 补丁生成的质量控制补丁生成出来不能直接用要过几道关。第一道是语法检查。用对应语言的解析器跑一遍确保没有语法错误。这一步能过滤掉相当一部分低级错误。第二道是编译检查。如果是编译型语言直接编译如果是解释型语言至少做一次导入检查。第三道是测试验证。跑相关测试用例这是最硬的指标。测试通过才算真正修好。第四道是差异审查。检查补丁的改动范围是否合理有没有改到不该改的地方。这一步可以用规则做也可以让另一个模型来做审查。我实测下来这四道关能把大部分劣质补丁拦下来。尤其是差异审查能抓到很多“看起来对但改多了”的问题。4.3 修复失败后的回退与重试修复失败是常态关键是怎么优雅地失败和重试。回退要干净。每次修复尝试前先打快照失败后完整回退不要留下半成品。我见过因为回退不干净导致后续修复基于错误状态进行的案例排查起来极其痛苦。重试要有策略。不要简单重复同样的提示词要把上次失败的原因反馈进去。比如“上次的补丁导致测试 X 失败错误是 Y请重新生成”。这样模型能吸取教训。重试要有上限。同一个位置重试超过 3 次还不成功就应该放弃转人工或者回到定位阶段。无限重试只会浪费资源。4.4 修复阶段的常见误区误区一允许模型自由重构。修复就是修复不要夹带重构。重构会让改动范围失控引入不可预测的风险。误区二忽略测试覆盖。如果目标位置没有测试覆盖修复的正确性就无法验证。这种情况下要么先补测试要么明确标记为“未验证”让人工介入。误区三不做回归检查。修好了当前 bug但可能破坏了其他功能。所以除了跑相关测试还要跑一遍回归测试集确保没有引入新问题。5. 两个环节之间的协作与信息传递5.1 结构化接口的设计原则定位和修复之间的接口我遵循三个原则。原则一只传必要信息。定位 Agent 的完整推理过程、读过的所有代码、调用的所有工具记录都不传。只传最终的定位结果和关键证据。原则二格式固定。用 JSON Schema 约束确保修复 Agent 拿到的永远是预期格式。格式不稳定会导致解析失败进而整个流程崩溃。原则三可追溯。每个定位结果要带 bug_id 和来源方便出问题时回溯是哪一步出的错。5.2 上下文怎么裁剪才不丢关键信息上下文裁剪是门手艺。我的做法是分层裁剪第一层目标函数完整代码必留第二层直接调用者和被调用者的签名及关键逻辑必留第三层相关测试用例尽量留第四层更远的依赖按需留裁剪的时候要注意保留注释和文档字符串这些往往包含关键约束信息。我见过因为裁掉了注释导致模型误解函数用途的案例。5.3 反馈循环修复结果怎么反哺定位修复阶段的结果对定位阶段是有价值的反馈。如果某个定位结果反复修复失败说明定位可能有问题应该把这个信号传回去让定位 Agent 重新分析。具体做法是维护一个定位结果的“修复成功率”统计。某个位置修复成功率低下次定位时就要降低它的优先级或者提示定位 Agent 重新审视。这个反馈循环能让整个系统越用越准是长期优化的关键。6. 常见问题与排查技巧实录6.1 定位不准怎么办定位不准是最常见的问题排查思路如下现象可能原因排查方法解决方向定位到完全无关的文件现象描述不清检查输入的报错信息是否完整补充复现步骤和日志定位到相关模块但不对代码结构信息不足检查是否提供了目录结构补充模块说明和入口文件多个候选都不对问题跨多个模块检查调用链是否完整提供跨模块的调用关系置信度普遍偏低模型对项目不熟检查是否有项目背景说明补充技术栈和架构说明我踩过最深的坑是报错信息不完整。有一次只给了一句“接口返回 500”模型定位了半天定位到路由层实际问题是数据库连接池耗尽。后来补上完整的错误日志和监控指标一次就定位准了。6.2 修复引入新 bug 怎么防修复引入新 bug 主要有两个原因改动范围过大、以及没有回归验证。防范措施我总结成三条最小改动原则提示词里明确要求“只改必要的地方”并在差异审查时检查改动行数超过阈值就人工复核回归测试必跑不管改动多小回归测试都要跑一遍灰度验证如果条件允许先在测试环境验证再上生产6.3 两个 Agent 互相甩锅怎么破双 Agent 架构下定位说“我找对了是修复没改好”修复说“定位给的位置根本不对”这种扯皮很常见。破解方法是建立客观的中间验证。在定位和修复之间加一个验证步骤拿定位结果去实际检查比如在那个位置打断点、加日志看能不能复现问题。能复现说明定位对不能复现说明定位错。这样就有了客观依据不用靠嘴说。6.4 成本和延迟怎么平衡拆分之后调用次数增加了成本和延迟都会上升。怎么平衡我的做法是分级处理。简单 bug比如空指针、类型错误用轻量模型快速定位和修复复杂 bug 才启用完整的双 Agent 流程。同时定位阶段的结果可以缓存相似 bug 直接复用避免重复劳动。实测下来分级处理能把平均成本压到全量双 Agent 的三成左右而准确率只下降几个百分点性价比很高。7. 一些实操中的个人体会这套拆分方案我用了大半年从最初的流水线两阶段到后来的双 Agent中间迭代了不知道多少版。最大的体会是AI 修 bug 的瓶颈从来不在模型能力而在任务设计。你把任务拆对了用中等能力的模型也能跑出不错的效果任务设计错了用最强的模型也是一团糟。另一个体会是评估体系比什么都重要。没有评估你根本不知道改动是变好了还是变坏了。我现在的做法是维护一个 bug 修复的基准测试集每次调整流程都跑一遍用数据说话。最后分享一个小技巧让定位 Agent 和修复 Agent 用不同的模型。定位需要强推理用能力强的修复需要强代码生成用代码专精的。这样组合往往比用同一个模型效果更好成本也更可控。这套东西后续还可以往几个方向扩展比如加入自动生成测试用例的环节、或者把修复经验沉淀成知识库供后续复用。不过那是另一个话题了先把定位和修复这两件事拆明白、做扎实已经能解决大部分实际问题。