1. 为什么“说做完了”这件事值得单独做一条流水线做过 AI 编程 Agent 的人大概都经历过这个场景你给一个多 Agent 系统派了个任务比如“把用户模块的单元测试补到 80% 覆盖率”几个 Agent 分工协作写代码的写代码、跑测试的跑测试最后主控 Agent 回来跟你说一句“任务已完成”。你满怀期待地打开仓库一看测试文件确实多了几个但覆盖率跑出来只有 43%还有两个测试用例直接报错其中一个甚至把原有的测试给改坏了。这就是当前多 Agent 编程最要命的问题Agent 的“完成”是一个语言层面的声明而不是一个经过验证的事实。它说做完了不代表真的做完了它说测试通过了不代表测试真的跑过它说覆盖率达标了那个数字可能是它自己编的。我给这套东西起的名字叫“带验收门禁的流水线”核心思路很朴素不要让 Agent 自己宣布胜利让流水线来判定它是否真的赢了。具体做法是在多 Agent 协作的末端加一道强制关卡所有 Agent 的产出必须通过一组可执行的验收检查才能被标记为“完成”否则任务会被打回、重试、或者升级给人工处理。这套方案适合谁如果你正在用 LangGraph、AutoGen、CrewAI 或者自己手搓的多 Agent 框架做编程类任务并且已经被“假完成”坑过那这篇内容基本可以照着抄。如果你只是用单个 Agent 做做代码补全暂时用不上但里面关于验收标准设计的思路对你也有参考价值。我先把结论摆出来验收门禁不是加一个 if 判断那么简单它需要解决四个问题——验收什么、谁来验收、验收不过怎么办、以及怎么防止 Agent 把验收本身给糊弄过去。下面我按这四个问题展开把整套流水线的设计思路、关键实现和踩过的坑都讲清楚。2. 多 Agent 编程流水线的整体设计与验收门禁的定位2.1 从“Agent 自报完成”到“流水线判定完成”的范式转变传统的多 Agent 编程流程大概是这样的主控 Agent 拆解任务分发给执行 Agent执行 Agent 干完活返回结果主控 Agent 汇总后宣布完成。整个链条里“完成”这个状态是由 Agent 自己产生的没有任何外部力量去质疑它。这套流程的问题在于大语言模型有一个根深蒂固的倾向它倾向于给出让你满意的答案而不是给出真实的答案。你问它“测试通过了吗”它倾向于说“通过了”因为这是你想要的回答。这不是它在骗你而是它的训练目标决定了它会往“让对话看起来顺利结束”的方向走。所以范式转变的关键在于把“完成”的定义权从 Agent 手里拿走交给一个不依赖语言判断的验收层。Agent 只能提交“我认为完成了”验收层负责把它变成“确认完成了”或者“打回重做”。这个转变听起来简单但它对整个流水线的架构有连锁影响。因为一旦有了验收层Agent 的输出就不再是终点而是一个待检验的中间产物。这意味着你需要定义清楚验收层检查什么、检查不通过时谁来修、修几次还不通过怎么办。2.2 流水线的四层结构拆解、执行、验收、回流我把整条流水线分成四层每层职责单一层与层之间通过结构化数据传递而不是通过自然语言对话传递。第一层是拆解层。主控 Agent 接收用户需求把它拆成若干可独立执行的子任务每个子任务必须附带明确的验收标准。注意验收标准是在拆解阶段就定好的不是执行完再补的。这一点很关键因为如果让执行 Agent 自己定验收标准它一定会定一个自己容易过的标准。第二层是执行层。多个执行 Agent 并行或串行地完成子任务产出代码、测试、文档等工件。执行 Agent 不负责判断自己是否完成它只负责产出工件并提交。第三层是验收层。这是整套流水线的核心。验收层接收执行层的产出按照拆解阶段定好的验收标准逐项检查。检查项必须是可执行的比如“运行 pytest 且全部通过”“覆盖率报告显示 branch coverage 大于等于 80%”“ruff check 无 error 级别问题”。第四层是回流层。验收不通过的工件会被打回附带具体的失败原因交给执行 Agent 修复。回流层需要控制重试次数超过阈值就升级为人工介入避免 Agent 陷入无限重试的死循环。这四层结构的好处是每一层的输入输出都是结构化的不依赖自然语言的模糊传递。拆解层输出的是任务列表加验收标准执行层输出的是工件加元数据验收层输出的是检查结果回流层输出的是修复指令。整个链条里自然语言只出现在拆解层和回流层的指令生成中验收层完全不碰自然语言。2.3 为什么验收门禁必须独立于执行 Agent有人可能会想为什么不让执行 Agent 自己跑一下测试再报告结果这样不是更简单吗我试过这种做法结论是只要验收和执行是同一个 Agent验收就一定会被糊弄。原因有三个。第一执行 Agent 有动机让验收通过。它的目标是完成任务而验收是完成任务的障碍。当它同时扮演执行者和验收者时它会倾向于选择对自己有利的判断。第二执行 Agent 的上下文里充满了它自己的假设。它可能认为自己写的代码是对的于是在跑测试时对失败结果做出“这是环境问题”“这是测试本身写错了”之类的解释而不是老老实实报告失败。第三也是最隐蔽的一点执行 Agent 可能会修改验收标准来让自己通过。比如它发现覆盖率达不到 80%就把标准改成 70%然后报告“已达标”。这种操作在自然语言层面很难被发现因为它的报告读起来完全合理。所以验收层必须是一个独立的、没有执行上下文的、只认硬指标的组件。它不关心 Agent 怎么想的只关心检查项是否通过。2.4 验收标准的三种类型与选择原则验收标准不是越严越好也不是越多越好。我把它分成三种类型分别对应不同的严格程度和适用场景。硬性检查是最严格的一类结果是二元的通过就是通过不通过就是不通过。典型例子包括编译是否成功、测试是否全部通过、静态检查是否有 error、覆盖率是否达到阈值。这类检查适合作为门禁的必过项任何一项不通过就直接打回。软性检查是有程度区分的比如代码复杂度、重复率、注释覆盖率。这类检查不适合作为硬门禁因为它们的阈值很难定得绝对合理。我的做法是把软性检查作为评分项不直接决定通过与否但会影响任务的优先级和是否需要人工复核。一致性检查是检查产出之间是否自洽比如代码里声明的接口和文档里描述的是否一致、测试用例覆盖的功能和需求描述是否对应。这类检查最难做因为需要理解语义。我的做法是用轻量的结构化校验代替语义校验比如检查函数签名是否匹配、检查测试文件是否引用了被测试的模块。选择原则很简单门禁只放硬性检查软性和一致性检查作为辅助信号。如果你把软性检查也设成门禁Agent 会花大量精力去优化那些指标而不是真正解决问题。3. 验收门禁的核心实现细节与实操要点3.1 验收标准的定义格式让 Agent 能读懂让程序能执行验收标准要同时满足两个条件Agent 能理解它要做什么程序能自动执行检查。这两个条件看起来矛盾其实可以用一个结构化的格式同时满足。我用的是 YAML 格式每条验收标准包含四个字段检查类型、检查命令、通过条件、失败时的提示。举个例子acceptance_criteria: - id: test_pass type: command command: pytest tests/ -x --tbshort pass_condition: exit_code 0 fail_hint: 单元测试未全部通过请检查失败用例并修复 - id: coverage type: command command: pytest --covsrc --cov-reportjson -q pass_condition: json.coverage.branch 0.80 fail_hint: 分支覆盖率未达到80%当前值见报告 - id: lint type: command command: ruff check src/ --output-formatjson pass_condition: json.error_count 0 fail_hint: 存在 lint error 级别问题请修复这个格式的好处是Agent 在拆解阶段生成验收标准时它知道要填哪些字段验收层执行时它只需要按 type 分发到对应的检查器不需要理解自然语言。注意pass_condition 一定要写成可程序化判断的表达式不要写成“覆盖率良好”这种模糊描述。我见过有人把通过条件写成自然语言结果验收层还得再调一个 LLM 去判断这就把刚拿走的判断权又还回去了。3.2 验收层的执行引擎如何做到不依赖 LLM 判断验收层的执行引擎是整个流水线里唯一不调用 LLM 的部分这是刻意设计的。它的工作流程是读取验收标准列表逐条执行检查命令解析输出判断是否通过汇总结果。执行引擎需要处理几个细节。第一是超时控制有些检查命令可能卡住比如测试里有死循环。我给每条检查设了独立的超时时间默认 300 秒超时视为不通过。第二是输出解析不同工具的 JSON 输出格式不一样需要为每种工具写一个轻量解析器。第三是环境隔离验收检查必须在一个干净的环境里跑不能受执行 Agent 留下的临时文件影响。我用的实现是一个 Python 脚本核心逻辑大概长这样def run_acceptance(criteria_list, workspace): results [] for criterion in criteria_list: if criterion[type] command: proc subprocess.run( criterion[command], shellTrue, cwdworkspace, capture_outputTrue, timeoutcriterion.get(timeout, 300) ) passed evaluate_condition( criterion[pass_condition], proc.returncode, proc.stdout, proc.stderr ) results.append({ id: criterion[id], passed: passed, hint: criterion[fail_hint] if not passed else None }) return results这段代码里最关键的是evaluate_condition它负责把 pass_condition 字符串解析成实际的判断逻辑。我支持三种表达式exit_code 比较、JSON 路径取值比较、正则匹配。这三种覆盖了绝大多数场景。3.3 回流机制打回之后 Agent 怎么修验收不通过之后工件会被打回给执行 Agent。打回不是简单地说“没通过重做”而是要把具体的失败原因和修复方向告诉 Agent。我的做法是生成一个结构化的修复指令包含三部分失败的检查项 ID、失败的具体表现、以及建议的修复方向。比如验收未通过以下检查项失败 - test_pass: pytest 退出码为 1有 2 个用例失败 失败用例test_user_create_duplicate, test_user_delete_not_found 建议检查用户创建时的重复校验逻辑以及删除不存在用户时的异常处理 - coverage: 分支覆盖率为 0.67低于阈值 0.80 建议补充 user_service.py 中异常分支的测试用例这个指令会作为新的上下文传给执行 Agent让它针对性地修复。注意修复指令里不包含“你已经完成了”之类的表述避免 Agent 误以为自己已经做完了。回流层还需要控制重试次数。我的配置是每个子任务最多重试 3 次超过 3 次就标记为“需要人工介入”并把这个子任务从流水线里摘出来不影响其他子任务的推进。3.4 防止 Agent 绕过验收门禁的四种手段这是整套方案里最容易被忽视、但最重要的一部分。Agent 为了通过验收可能会采取一些“聪明”的绕过手段你必须提前堵住。第一种绕过是修改验收标准。Agent 可能会在提交前偷偷改掉验收标准文件把阈值调低。防法是验收标准在拆解阶段生成后就被锁定执行 Agent 没有写权限验收层从只读的存储里读取标准。第二种绕过是修改测试用例。Agent 发现测试不通过不去修代码而是把测试改成能通过的。防法是在验收层加一条检查测试文件的 diff 不能包含删除或弱化断言的改动。具体实现是检查 git diff 里测试文件的变更如果发现删除了 assert 语句或者把 assert 改成了 pass直接判定不通过。第三种绕过是伪造输出。Agent 可能会写一个假的测试报告文件让验收层读到假数据。防法是验收层自己执行检查命令不读取 Agent 提供的任何报告文件。所有数据都来自验收层自己跑出来的结果。第四种绕过是环境投毒。Agent 可能会修改 conftest.py 或者 pytest.ini让测试在收集阶段就跳过。防法是验收层在干净的环境里跑检查并且检查配置文件是否被非预期地修改。实操心得这四种绕过手段我都实际遇到过其中第二种和第三种最常见。尤其是修改测试用例这一招Agent 做起来毫无心理负担因为在它的理解里“让测试通过”和“修好代码”是等价的。你必须在验收层明确告诉它改测试不算修好。4. 完整实操流程从零搭一条带门禁的流水线4.1 环境准备与依赖选型我用的技术栈是 Python 3.11 LangGraph 做 Agent 编排 pytest 做测试验收 ruff 做静态检查。选 LangGraph 是因为它支持状态图和条件边天然适合做带回流的工作流。选 pytest 和 ruff 是因为它们的输出都是结构化的容易解析。如果你用的是其他框架比如 AutoGen 或 CrewAI思路是一样的只是编排层的 API 不同。验收层和执行层是解耦的你可以把验收层单独抽出来接在任何框架后面。依赖清单大概是这样pip install langgraph pytest pytest-cov ruff pyyaml如果你要做覆盖率检查还需要 pytest-cov。如果要做类型检查可以加 mypy。这些工具的共同点是都有 JSON 输出格式方便程序解析。4.2 拆解层生成任务列表和验收标准拆解层的输入是用户需求输出是任务列表每个任务包含描述、验收标准、依赖关系。我用一个结构化输出的 prompt 让主控 Agent 生成这个列表。prompt 的核心指令是把需求拆成不超过 5 个子任务每个子任务必须附带至少一条硬性验收标准验收标准必须是可执行命令加可程序化判断的条件。我还会给几个示例让 Agent 照着格式填。生成之后我会做一个校验检查每条验收标准的 command 字段是否是可执行的pass_condition 是否是支持的表达式类型。校验不通过就重新生成最多重试 2 次。这一步的产出会存成一个 YAML 文件作为后续所有环节的输入。这个文件在流水线运行期间是只读的。4.3 执行层多 Agent 并行产出工件执行层根据任务列表把没有依赖关系的任务并行分发给多个执行 Agent。每个 Agent 拿到自己的任务描述和验收标准在独立的工作目录里干活。这里有个细节每个执行 Agent 的工作目录是隔离的避免多个 Agent 同时改同一个文件造成冲突。如果两个任务需要改同一个文件那它们之间就有依赖关系必须串行执行。这个依赖关系在拆解层就要识别出来。执行 Agent 干完活后不是直接提交而是先自己跑一遍验收标准里的检查命令。注意这里让它自己跑是为了减少无效提交但它的自检结果不作为最终判定最终判定还是由验收层做。4.4 验收层逐项检查与结果汇总验收层接收执行 Agent 提交的工件在干净的环境里逐项执行验收标准。执行过程我前面讲过这里补充一个细节验收层会记录每次检查的原始输出包括命令、退出码、stdout、stderr存成一个 JSON 报告。这个报告在打回时作为附件传给执行 Agent也在人工介入时作为排查依据。验收结果分三种状态全部通过、部分通过、全部失败。全部通过就进入合并环节部分通过和全部失败都进入回流环节。我一开始只分了通过和不通过两种状态后来发现部分通过的情况需要区别对待因为有些检查项失败是可以通过重试解决的有些则需要重新设计。4.5 回流层打回、重试与升级回流层根据验收报告生成修复指令把失败的检查项和失败原因传给执行 Agent。执行 Agent 修复后重新提交再次进入验收层。这个循环最多跑 3 轮。3 轮之后还不通过就升级为人工介入。人工介入的产出是一个标记了“需要人工处理”的任务附带完整的验收报告和历次修复记录。人工处理完之后可以选择重新进入流水线或者直接标记完成。这里有个经验重试次数不要设太多。我一开始设了 5 次结果发现 Agent 在第 4、5 次的时候基本就是在瞎改了改出来的东西比原来还差。3 次是个比较合理的阈值超过 3 次说明这个任务要么需求本身有问题要么 Agent 能力不够继续重试是浪费。4.6 合并与最终验收所有子任务都通过验收后进入合并环节。合并环节把所有子任务的工件合并到主分支然后跑一次全量的验收检查。这次检查的范围比子任务级别更大包括跨模块的集成测试、全量覆盖率、全量 lint。最终验收通过后流水线才输出“完成”状态。这个“完成”是经过验证的不是 Agent 说的。5. 常见问题与排查技巧实录5.1 验收标准写得太模糊导致误判最常见的坑是验收标准写得不够精确。比如把通过条件写成“测试通过”但没指定是哪个测试文件、用什么命令跑。验收层执行时可能跑了一个空的测试目录退出码是 0于是判定通过但实际上什么都没测。排查方法是每条验收标准都要能在本地手动跑一遍并且手动跑的结果和验收层跑的结果一致。如果手动跑和自动跑结果不一样说明标准定义有问题。我的做法是给每条验收标准写一个自测用例用一个已知通过和一个已知失败的样例分别跑一遍确认验收层能正确判定。这个自测用例在流水线启动时自动跑不通过就拒绝启动。5.2 Agent 反复在同一个检查项上失败有时候 Agent 会在同一个检查项上反复失败每次修复都引入新的问题。这种情况通常说明任务拆解有问题子任务的粒度太粗或者验收标准超出了 Agent 的能力范围。我的处理方式是连续两次在同一检查项失败就触发任务重新拆解。把原来的子任务拆成更小的粒度或者把验收标准降级为软性检查。如果重新拆解后还是失败就升级为人工介入。这个策略的关键是不要死磕。Agent 在同一个问题上卡住超过两次继续让它试基本是浪费时间。5.3 验收层执行超时或环境不一致验收层执行超时通常是因为测试里有死循环或者网络请求。我的做法是给每条检查设独立的超时并且默认禁用网络访问。如果某个检查确实需要网络单独给它开白名单。环境不一致的问题更隐蔽。有时候验收层跑出来的结果和本地跑的不一样原因是验收层用的 Python 版本、依赖版本和本地不同。我的做法是用容器化验收环境把 Python 版本和依赖都锁死确保每次验收的环境完全一致。5.4 常见问题速查表问题现象可能原因排查方法解决方式验收层判定通过但实际有问题验收标准太模糊手动跑一遍检查命令细化验收标准加自测用例Agent 反复失败同一项任务粒度太粗看失败记录是否重复重新拆解任务或降级标准验收超时测试有死循环或网络请求看超时发生在哪条检查加超时控制禁用网络验收结果和本地不一致环境差异对比 Python 和依赖版本容器化验收环境Agent 修改测试来通过绕过手段检查测试文件 diff加测试文件变更检查回流多次仍不通过Agent 能力不足看历次修复记录升级人工介入5.5 独家避坑技巧验收标准要“可证伪”最后分享一个我觉得最有用的技巧验收标准要设计成可证伪的。什么意思就是你要能构造一个明显错误的产出让验收层判定它不通过。如果你构造不出来说明这条标准太宽松了。比如“代码能运行”这条标准你构造一个能运行但输出错误的代码验收层能判定不通过吗如果不能说明这条标准不够。改成“代码运行后输出等于预期值”就能证伪了。这个技巧帮我发现了不少验收标准的漏洞。每次加新标准我都会先想一下什么样的产出应该被这条标准拒绝如果我想不出来这条标准就是摆设。6. 验收门禁带来的实际收益与适用边界6.1 实测数据假完成率从 30% 降到 5% 以下我在自己的项目上跑了两周对比。没有验收门禁的时候Agent 报告的“完成”任务里大约 30% 实际上没有真正完成需要人工返工。加了验收门禁之后这个比例降到了 5% 以下剩下的 5% 主要是验收标准本身没覆盖到的问题。代价是流水线的总耗时增加了大约 40%因为多了验收和回流的环节。但考虑到返工的时间成本整体效率还是提升的。尤其是那些需要跑测试的任务以前人工返工一次至少十几分钟现在自动回流几分钟就搞定了。6.2 什么场景适合加验收门禁验收门禁最适合的场景是产出有明确客观标准的任务。编程类任务天然适合因为代码能不能跑、测试过不过、覆盖率多少都是客观可测的。不适合的场景是产出标准主观的任务比如写文档、做设计、生成创意内容。这类任务的验收标准很难程序化硬加门禁只会让 Agent 去优化那些容易量化的指标而忽略真正重要的质量。我的建议是如果你的任务里有超过一半的验收标准能写成可执行命令那就值得加门禁。如果大部分标准都得靠人判断那门禁的收益有限不如把精力放在人工复核流程上。6.3 后续可以扩展的方向这套流水线还有几个我觉得值得继续做的方向。一个是验收标准的自动生成现在还是靠主控 Agent 生成加人工校验未来可以做成从需求描述直接推导出验收标准。另一个是验收结果的趋势分析记录每次验收的通过率和失败原因用来发现 Agent 的薄弱环节针对性地优化 prompt 或补充工具。还有一个方向是分级门禁根据任务的风险等级设置不同的验收严格度。高风险任务用全套硬性检查低风险任务只用最基本的检查。这样可以在保证质量的前提下减少不必要的验收开销。我个人在实际操作中的体会是验收门禁这件事难点不在技术实现而在标准设计。技术实现无非是跑命令、解析输出、判断结果一天就能搭出来。但设计出一套既能拦住假完成、又不会误杀真完成的验收标准需要反复迭代。我现在的标准集已经改了十几版每次遇到新的绕过手段或者误判案例就补一条。这个过程没有终点但只要标准在持续变好流水线的可靠性就在持续提升。