多Agent编程的验收门禁：让“说做完了”变成可验证的事实

1. 为什么“说做完了”这件事在 AI 编程里根本不值钱如果你最近半年深度用过任何多 Agent 编程框架大概率经历过下面这个场景你给编排器丢了一个需求比如“给用户模块加一个手机号格式校验前后端都要改顺便补上单测”然后几个 Agent 开始噼里啪啦地跑。规划 Agent 拆任务编码 Agent 改文件测试 Agent 跑用例最后主控 Agent 给你回一句——“任务已完成所有改动已提交”。你满怀期待地点开 diff结果发现后端校验写了前端没动单测是补了但断言写的是assert True更离谱的是有个 Agent 把package.json里的依赖版本改成了它自己臆想的版本号构建直接挂掉。你回头去问它它还很自信地告诉你“已经全部完成”。这就是当前多 Agent 编程最要命的问题Agent 的“完成”是一个语言层面的声明不是一个可验证的事实。它说做完了和它真的做完了中间隔着一整个验收体系。而绝大多数开源的多 Agent 编排框架把精力全花在了“怎么让 Agent 协作得更顺”上却几乎没人认真做“怎么判断协作的产物到底合不合格”。我这次做的事情就是给多 Agent 编程流水线加了一道带验收门禁的关卡任何一个 Agent 声称完成的任务都必须穿过一道由确定性检查构成的闸门过不去就打回重做过不去就不允许进入下游。整套东西我开源了下面把设计思路、核心实现、踩过的坑和可直接抄的配置全部摊开讲。这篇文章适合三类人看一是正在用多 Agent 做真实项目、被“假完成”坑过的开发者二是想自己搭一套 Agent 编排流水线、但不知道验收环节怎么设计的人三是对 AI 编程持观望态度、想看看工程化到底能做到什么程度的技术负责人。不需要你精通某个特定框架我会把通用逻辑讲透你换成自己熟悉的编排工具也能落地。2. 整体设计把“验收”从 Agent 的嘴里抢回来2.1 核心思路让声明和验证彻底分离传统多 Agent 流水线的信任模型是这样的Agent A 做完交给 Agent BB 默认 A 做的是对的继续往下做。这个模型在 Demo 里跑得通因为 Demo 的任务足够简单Agent 不容易出错。但一旦任务变复杂错误就会沿着流水线一路放大到最后你拿到的是一个看起来完整、实际上千疮百孔的结果。我的设计原则只有一条Agent 只负责生产和声明验收权必须交给不依赖大模型的确定性检查。换句话说Agent 说“我做完了”只是触发验收的信号而不是验收通过的凭证。真正决定能不能放行的是一组可重复执行、结果确定的检查项。这个思路借鉴的是 CI/CD 里的质量门禁Quality Gate概念。你在 Jenkins 或者 GitHub Actions 里配过流水线就知道代码合并前必须过 lint、过单测、过构建任何一项挂了就不让合。我把同样的逻辑搬到了 Agent 流水线里只不过检查的对象从“人写的代码”变成了“Agent 产出的代码和文件”。2.2 为什么不用“让另一个 Agent 来验收”这是我最想先讲清楚的一个选型决策。很多人第一反应是既然单个 Agent 不可信那我再起一个“审查 Agent”让它去检查前一个 Agent 的产出不就行了我实测过这条路结论是用 Agent 验收 Agent等于用不确定性去校验不确定性。审查 Agent 同样会幻觉同样会偷懒同样会在你追问时给出看似合理的解释。更麻烦的是当生产 Agent 和审查 Agent 意见不一致时你还需要第三个 Agent 来仲裁复杂度直接爆炸而可靠性并没有实质提升。确定性检查则完全不同。pytest跑出来的结果是 pass 还是 fail不取决于任何人的心情tsc --noEmit报不报错是编译器说了算文件是否存在、JSON 是否合法、函数签名是否匹配这些都是布尔值没有解释空间。所以我的门禁层里主力全部是确定性检查大模型只在“生成检查项”这一个环节参与而且生成出来的检查项要经过人工确认才能进流水线。2.3 流水线的四层结构整套流水线我拆成了四层从下往上分别是层级名称职责是否依赖大模型L1任务编排层拆解需求、分配任务、调度 Agent是L2生产执行层各 Agent 实际改代码、写文件是L3验收门禁层对产出跑确定性检查决定放行或打回否L4反馈重试层把失败原因结构化后回传给生产 Agent部分关键在 L3。它不关心 Agent 说了什么只关心磁盘上的文件、命令的退出码、测试的输出。L4 的设计也有讲究打回时不能只说“你错了”而要把具体哪一项检查失败、失败输出是什么、期望是什么结构化地喂回去否则 Agent 重试十次还是错在同一个地方。2.4 门禁的三种放行策略不是所有检查项都同等重要所以我给门禁设计了三种策略对应不同的严格程度阻断型blocking任何一项失败整个任务直接打回不允许进入下游。适用于编译、类型检查、核心单测这类硬性要求。警告型warning失败只记录不阻断但会在最终报告里标红。适用于代码风格、注释覆盖率这类“最好有但不是必须”的项。累积型cumulative允许单次失败但同一任务累计失败超过阈值我默认设 3 次就升级为阻断。适用于那些 Agent 偶尔会翻车、但重试一次通常能过的检查。这套策略解决了一个很现实的问题如果所有检查都设成阻断Agent 会因为一个无关紧要的格式问题卡死如果都设成警告门禁就形同虚设。分级之后硬骨头必须啃下来软要求给点弹性。3. 核心细节验收门禁到底检查什么、怎么检查3.1 检查项的四个来源门禁里的检查项不是拍脑袋定的我设计了四个来源覆盖从通用到专用的全部场景。第一个来源是项目级基线检查这是所有任务都要过的。比如代码能不能编译、依赖能不能装、有没有引入语法错误。这部分我直接复用了项目原有的 CI 配置Agent 改完代码后跑一遍make build或者npm run build过不了就别谈别的。第二个来源是任务级动态检查由编排层在拆解需求时同步生成。比如需求是“加手机号校验”那对应的检查项就是“存在一个校验函数”“该函数对非法输入返回 false”“前端表单绑定了该校验”。这些检查项我会让大模型先生成一版草稿然后人工过一遍确认无误后固化成配置。第三个来源是回归检查也就是项目原有的测试套件。这一项特别重要因为 Agent 最容易犯的错就是“改好了新功能弄坏了老功能”。每次任务完成全量回归测试必须跑任何一条挂了都算失败。第四个来源是产物一致性检查专门对付 Agent 的“口是心非”。比如 Agent 声称“已修改文件 A”门禁就去检查文件 A 的 mtime 是不是在本次任务时间窗内Agent 声称“已添加依赖”门禁就去比对package.json的 diff。这一层能抓出大量“嘴上说改了、实际没动”的情况。3.2 检查项配置的数据结构配置我用的是一份 YAML结构尽量扁平方便人和 Agent 都能读写。核心字段如下gates: - id: build-check type: blocking command: npm run build timeout: 300 on_fail: 构建失败请检查类型错误和依赖问题 - id: phone-validation-exists type: blocking check: file_contains target: src/utils/validate.ts pattern: export function validatePhone on_fail: 未找到 validatePhone 导出函数 - id: phone-validation-behavior type: blocking command: npx jest tests/validate.test.ts timeout: 120 on_fail: 手机号校验单测未通过 - id: regression type: blocking command: npm test timeout: 600 on_fail: 回归测试失败改动破坏了既有功能 - id: file-touched type: warning check: file_modified target: src/components/UserForm.tsx window: 1800 on_fail: 前端表单文件在本次任务中未被修改这里有几个设计细节值得展开。timeout字段是必须的因为 Agent 有时候会写出死循环的测试没有超时保护整个流水线会挂死。on_fail字段是给反馈层用的失败时把这句话连同实际输出一起喂回给 Agent比干巴巴一句“失败了”有用得多。window字段是时间窗单位秒用来判断文件是不是本次任务改的避免 Agent 拿历史改动来邀功。3.3 门禁执行器的实现要点执行器本身不复杂核心就是一个循环遍历检查项按类型分发执行收集结果最后汇总。但有几个坑必须提前填。第一个坑是执行顺序。我一开始按配置顺序跑结果经常出现“构建还没过就去跑单测”的浪费。后来改成按成本排序先跑最快的文件存在性检查再跑中等成本的单测最后跑最慢的全量构建和回归。这样一旦前面的检查挂了后面的重活就不用跑了整体耗时能省一大半。第二个坑是输出截断。有些检查失败时会吐出几千行日志全塞给 Agent 反而干扰它判断。我的做法是只保留最后 50 行加上错误关键词附近的上下文其余折叠。实测下来 Agent 定位问题的准确率明显提升。第三个坑是并发安全。多个 Agent 可能同时触发门禁如果它们操作同一份工作目录检查结果会互相污染。我的方案是每个任务分配独立的工作副本门禁在副本里跑通过后再合并回主目录。这一步多花点磁盘但省掉了无数诡异的“我本地明明是过的”问题。3.4 反馈重试层怎么把失败讲清楚门禁失败后反馈层要做的事情是把失败信息翻译成 Agent 能理解、能行动的指令。我总结了一个三段式模板任务 [任务ID] 未通过验收门禁。 失败检查项[检查项ID][类型] 期望[on_fail 描述] 实际输出[截断后的日志] 请针对上述失败项修改不要改动其他无关文件。这个模板的关键在于最后一句“不要改动其他无关文件”。我踩过的坑是Agent 收到失败反馈后经常顺手把一堆不相关的东西也改了结果修好一个坏掉三个。加上这句约束后改动范围明显收敛。另外重试次数要设上限。我默认最多重试 3 次3 次还过不了就升级为人工介入把任务挂起并通知。无限重试只会烧钱不会解决问题。4. 实操过程从零搭起这条带门禁的流水线4.1 环境准备与依赖选型整套东西我是用 Python 写的编排层因为生态里做 Agent 编排的库大多在 Python 侧。核心依赖就三个一个 Agent 编排框架我用的是社区里比较活跃的开源方案你换成自己顺手的也行、pytest作为测试执行器、PyYAML读配置。门禁执行器本身是纯标准库实现没有额外依赖这样部署到任何环境都不会因为装不上包而卡住。工作目录结构我定成这样project/ ├── gates/ │ ├── config.yaml # 门禁配置 │ └── executor.py # 门禁执行器 ├── workspace/ │ ├── main/ # 主工作目录 │ └── task-{id}/ # 每个任务的独立副本 ├── reports/ │ └── task-{id}.json # 每次门禁执行的结果 └── orchestrator.py # 编排入口reports目录别省。每次门禁执行的结果都落盘成 JSON包含检查项、耗时、输出摘要、最终判定。出问题时翻报告比翻日志快得多而且这些报告本身就是很好的复盘材料。4.2 门禁执行器的核心代码执行器我写得尽量直白没有花哨设计。核心逻辑大概长这样import subprocess import time import yaml from pathlib import Path def run_gate(gate, workspace): gate_type gate.get(type, blocking) check gate.get(check) if check file_contains: target workspace / gate[target] if not target.exists(): return False, f文件不存在: {gate[target]} content target.read_text(encodingutf-8) if gate[pattern] not in content: return False, f未匹配到模式: {gate[pattern]} return True, ok if check file_modified: target workspace / gate[target] if not target.exists(): return False, f文件不存在: {gate[target]} age time.time() - target.stat().st_mtime if age gate.get(window, 1800): return False, f文件修改时间超出窗口: {age:.0f}s return True, ok if command in gate: try: result subprocess.run( gate[command], shellTrue, cwdworkspace, capture_outputTrue, textTrue, timeoutgate.get(timeout, 300), ) except subprocess.TimeoutExpired: return False, f命令超时: {gate[command]} if result.returncode ! 0: tail \n.join(result.stderr.splitlines()[-50:]) return False, f命令失败(exit{result.returncode}):\n{tail} return True, ok return False, f未知检查类型: {gate}这段代码里file_contains和file_modified是纯文件系统操作毫秒级完成command分支负责跑构建和测试带超时保护。返回的二元组里第一个是布尔判定第二个是给反馈层用的说明。整个函数没有一行依赖大模型这就是门禁可靠性的根基。4.3 编排层怎么调用门禁编排层的逻辑是Agent 完成一个子任务后不直接标记完成而是调用门禁执行器。伪代码大概是这样def execute_task(task, workspace): for attempt in range(MAX_RETRY): agent_result run_agent(task, workspace) gate_results run_all_gates(workspace, task.gates) blocking_failures [ r for r in gate_results if not r.passed and r.type blocking ] if not blocking_failures: return TaskResult(successTrue, attemptsattempt 1) feedback build_feedback(task, blocking_failures) task task.with_feedback(feedback) return TaskResult(successFalse, reason超过最大重试次数)注意run_all_gates里我做了成本排序先跑便宜的检查。另外build_feedback会把失败项和实际输出拼成前面说的三段式模板。这套逻辑跑下来一个中等复杂度的任务平均重试 1.2 次就能过比没有门禁时“看起来过了实际一堆问题”强太多。4.4 一次真实任务的完整记录拿我最近做的一个真实任务举例给一个 TypeScript 项目加“用户注册时校验邮箱格式前后端都要改补单测”。第一轮规划 Agent 拆出三个子任务后端校验函数、前端表单绑定、单测。编码 Agent 跑完后端和单测前端 Agent 跑完表单。门禁执行结果检查项类型结果说明build-checkblocking通过构建正常email-validation-existsblocking通过找到导出函数email-validation-behaviorblocking失败单测断言写反了regressionblocking通过老测试全过file-touchedwarning失败前端文件未修改门禁判定阻断打回。反馈层把“单测断言写反”和“前端文件未修改”两条结构化信息喂回去。第二轮编码 Agent 修正了断言前端 Agent 补上了表单绑定。再跑门禁全绿放行。整个过程从开始到通过大概 6 分钟其中门禁执行占了不到 1 分钟剩下都是 Agent 在干活。这个案例里如果没有门禁第一轮的产物就会被当成“完成”交上来而实际上单测是错的、前端根本没改。这就是门禁的价值。5. 常见问题与排查技巧实录5.1 门禁老是误报怎么办误报是门禁落地初期最常见的问题典型表现是明明代码是对的检查项却报失败。我遇到过的原因主要有三类。第一类是路径问题。Agent 在副本目录里改文件但检查项配置里写的是主目录的相对路径导致找不到文件。解决办法是门禁执行器统一以工作副本为根目录解析路径配置里全部用相对路径不要写绝对路径。第二类是时序问题。file_modified检查依赖文件 mtime但有些文件系统的时间精度不够或者 Agent 改完文件后又被格式化工具重写了一遍导致 mtime 落在窗口外。我的处理是把窗口从 1800 秒放宽到 3600 秒并且对格式化工具做白名单它改的文件不参与时序检查。第三类是环境差异。构建和测试在 Agent 环境里能过在门禁环境里过不了通常是环境变量或依赖版本不一致。解决办法是门禁和 Agent 共用同一份环境配置用容器或者虚拟环境锁死别让两边跑在不同的地基上。5.2 Agent 反复卡在同一个检查项上这种情况通常不是 Agent 笨而是反馈信息不够具体。我排查过一个案例Agent 连续 3 次都没通过“函数签名匹配”检查每次反馈都是“签名不匹配”。后来我把检查项改成输出期望签名和实际签名的逐字符对比Agent 一次就改对了。所以遇到反复卡壳先别急着调 Agent 的提示词先回头看门禁的失败信息是不是足够具体。反馈的颗粒度决定了重试的效率这句话我建议你贴在显示器上。5.3 门禁执行太慢拖垮流水线门禁慢通常慢在回归测试上。一个大型项目的全量测试跑十几分钟很正常如果每个子任务都跑全量流水线会被拖死。我的优化策略是分级子任务级别只跑受影响的测试文件通过分析改动文件的依赖关系确定任务整体完成后再跑一次全量回归。这样既保证了子任务的快速反馈又保证了最终产物的整体质量。另外构建产物和测试缓存要复用。node_modules、target、.pytest_cache这些目录在任务副本之间共享别每个副本都重新装一遍依赖那是纯浪费。5.4 常见问题速查表现象可能原因排查方向解决手段检查项找不到文件路径解析基准错误确认工作目录统一用相对路径时序检查误报mtime 精度或工具重写查看文件修改历史放宽窗口工具白名单构建本地过门禁不过环境不一致对比环境变量和依赖版本容器化统一环境Agent 反复卡同一项反馈信息太笼统检查 on_fail 描述细化到具体差异门禁耗时过长全量测试重复跑统计各检查项耗时分级测试缓存复用多个任务互相污染共享工作目录检查副本隔离每任务独立副本5.5 几条踩坑换来的经验第一条门禁配置要进版本控制。我一开始把配置放在本地结果换台机器跑就行为不一致。后来把gates/config.yaml纳入 git 管理谁改了配置一目了然回滚也方便。第二条新加检查项先设成警告型跑一周。直接上阻断型容易误伤先观察一周确认没有误报再升级为阻断。这个习惯帮我避免了好几次流水线集体卡死。第三条给门禁本身写测试。听起来有点套娃但门禁执行器也是代码也会有 bug。我给它写了一套单元测试用构造的假工作目录验证各种检查类型的行为确保门禁本身是可信的。门禁不可信整个流水线的信任就崩了。第四条失败报告要保留原始输出。截断是给 Agent 看的但原始输出要完整落盘。有一次 Agent 死活改不对我翻原始日志才发现是某个依赖的版本冲突这种信息截断后就看不到了。6. 门禁之外这套东西还能怎么扩展6.1 把门禁接到代码评审环节现在门禁是在 Agent 流水线内部跑的其实它完全可以复用到人工评审环节。我的做法是Agent 流水线通过门禁后自动生成一份门禁报告附在 PR 描述里评审人一眼就能看到哪些检查过了、哪些是警告。这样评审人可以把精力放在设计合理性上而不是重复检查格式和测试。6.2 用历史数据反哺检查项生成每次门禁执行的结果都落盘了这些数据攒多了就是金矿。我最近在做的实验是统计哪些检查项最常失败、哪些 Agent 最容易在哪些检查项上翻车然后针对性地优化提示词和任务拆解策略。比如发现某个 Agent 老是在类型检查上出错就在它的系统提示里强化类型相关的约束。这是数据驱动的 Agent 调优比拍脑袋改提示词靠谱得多。6.3 门禁作为多 Agent 协作的“共同语言”多 Agent 协作最难的是对齐。生产 Agent 觉得“差不多就行”审查 Agent 觉得“这不行”两边扯皮。门禁的引入相当于给所有 Agent 提供了一套客观标准过就是过不过就是不过没有中间地带。我实测下来有了门禁之后Agent 之间的无效争论明显减少因为大家都有了共同的裁判。6.4 扩展到非编程场景这套门禁思路其实不限于编程。任何“Agent 产出 需要验收”的场景都能套写文档的门禁检查字数、关键词覆盖、链接有效性做数据分析的门禁检查输出文件格式、行数、字段完整性做设计的门禁检查导出文件尺寸、图层命名规范。核心逻辑是一样的把主观的“做完了”翻译成客观的“通过了哪些检查”。7. 我个人在实际操作中的几点体会搭这套东西的过程中我最大的体会是多 Agent 编程的瓶颈从来不在 Agent 有多聪明而在工程约束有多硬。你给 Agent 的自由度越大它翻车的方式就越多你把验收标准定得越死它反而越能稳定产出。这跟带团队是一个道理靠谱的团队不是靠每个人自觉而是靠清晰的验收标准。第二个体会是门禁的粒度要跟任务复杂度匹配。太粗了抓不住问题太细了 Agent 寸步难行。我的经验值是一个中等任务配 5 到 8 个检查项比较合适其中阻断型占三分之二警告型占三分之一。这个比例是我试了好几轮才调出来的你可以根据自己的项目特点微调。第三个体会是别指望一次把门禁配完美。我第一版配置有十几个检查项结果 Agent 天天卡死后来砍到 6 个才跑顺。门禁是迭代出来的不是设计出来的。先跑起来观察哪些检查项真正抓到了问题哪些纯属添乱然后动态调整。最后分享一个小技巧给每个检查项加一个owner字段标明这个检查项是谁负责维护的。Agent 流水线跑久了检查项会越来越多没有归属就容易变成没人管的僵尸配置。有了 owner定期 review 的时候就知道该找谁确认这项还有没有必要留着。这个习惯是从开源项目管理里学来的用在门禁配置上同样好使。