多Agent自动编码框架：零干预交付完整项目的实战拆解

引言：让AI团队自动写代码不再是概念

一个完整的AI狼人杀游戏项目——包含WebSocket服务器、游戏引擎、AI玩家集成和可视化界面——由4个AI Agent协作完成，耗时3.5小时，全程零人工干预。更令人惊讶的是，整个过程仅使用了Gemini 2.5这一个模型，没有依赖Claude Opus、GPT-5等任何高级模型。

这套框架的核心思路并不复杂：用文件做状态机，用调度器做编排，用严格的提示词做约束，让多个AI实例像人类团队一样分工协作。下面我们来深入拆解它的设计原理和实现细节。

六大能力：从需求到交付的全自动流水线

这套多Agent编码框架覆盖了软件开发的完整生命周期，每个环节都由专门的Agent负责。值得注意的是，这里的"Agent"并非某种特殊程序，而是携带专属系统提示词、独立上下文窗口的LLM调用实例——这与微服务架构中每个服务只做一件事的设计哲学高度一致。

第一，自动拆分需求。 你只需要写一份PRD（产品需求文档），AI就会用Story Sweeper技能自动将PRD拆分成独立的Story。这里的Story源自敏捷开发方法论中的"用户故事"（User Story）概念，通常遵循"作为[角色]，我希望[功能]，以便[价值]"的格式，并附带明确的验收标准（Acceptance Criteria）。将PRD自动拆分为Story的过程，本质上是在模拟敏捷团队的需求细化会议（Backlog Refinement），使AI系统能够以工程团队熟悉的工作单元为粒度进行任务管理。每个Story包含明确的需求描述、验收标准和依赖关系。

第二，自动设计技术方案。 Designer Agent读取PRD和MVP参考代码，输出包含架构设计、接口定义、文件结构、测试策略的完整设计文档。

第三，自动审核并修改设计。 Reviewer Agent不是简单地提意见，而是直接审核设计方案并输出修改后的设计文档（Design V2）。

第四，自动编码并提交。 Coder Agent按照设计文档实现代码，运行真实的Type Check、Lint、Test、Build，全部通过后才执行Git Commit。

第五，自动验证并修复Bug。 Validator Agent进行代码审查、运行测试、甚至浏览器截图验证，发现Bug后自动打回给Coder修复，循环直到通过。

第六，实时监控全部进度。 WebUI面板实时显示总进度、每个Story的状态、Agent运行日志，随时可以点击查看设计文档和测试报告。

核心设计：为什么必须是多智能体

单Agent的致命缺陷

很多人的第一反应是：为什么不用一个Claude搞定全部？这里有一个关键认知——Claude官方明确指出，多智能体的拆分应该按照上下文边界来划分，而不是按照人类社会中的角色。

理解这一点需要先了解上下文窗口（Context Window）的本质限制。上下文窗口是大语言模型一次能处理的最大Token数量。即便是Gemini 2.5这类拥有百万Token上下文的模型，在长期复杂任务中也面临"注意力稀释"问题——随着上下文不断增长，模型对早期信息的关注度会显著下降，导致输出质量退化、前后不一致等问题。这是单Agent处理完整软件项目的根本瓶颈，而非算力或智能的限制。

单Agent面临四大问题：

• 上下文爆炸：需求、设计、代码、测试全部塞在一个会话里，很快就会触顶
• 角色混杂：一会儿做架构、一会儿编码、一会儿测试，AI容易"精神分裂"
• 无法自我验证：写代码和测代码是同一个Agent，既当裁判又当运动员
• 状态丢失：会话一断，所有推理过程全部丢失，恢复成本极高

多智能体协作的核心优势

多智能体系统（Multi-Agent System, MAS）起源于分布式人工智能领域，其核心思想是将复杂任务分解给多个具备自主决策能力的智能体协同完成。在大语言模型时代，这一概念被重新诠释：每个Agent拥有专属的系统提示词、独立的上下文窗口和工具调用权限，彼此之间的职责边界清晰，不会相互干扰。

多智能体架构天然解决了上述问题：上下文隔离让每个Agent只关注自己的专业领域，上下文始终保持精简高效；角色专一确保Designer只设计、Coder只编码、Validator只验证；互相验证形成质量保障闭环；文件即状态让所有产出写入文件，会话断了也能从文件恢复。

这种"写的人不验，验的人不写"的设计思路，本质上就是软件工程中的常识。

状态机与通信机制：文件驱动的协作模式

一个Story的完整生命周期

整个系统最关键的设计是：Agent之间不直接通信，只通过读写文件来传递信息。 这种文件状态机的设计在分布式系统领域有一个经典的对应物——"黑板系统"（Blackboard System）架构模式。黑板系统中，各个专家模块通过读写共享的"黑板"数据结构来协作，而非直接调用彼此。以文件系统作为状态存储，相比内存队列或直接API调用，最大优势是可观测性和持久性：每个中间状态都以人类可读的Markdown文件形式保存，进程崩溃后状态不会丢失，便于调试、审计和断点恢复。

一个Story的完整流转过程如下：

1. Story创建 → 进入待处理队列
2. Designer 读取Story + PRD + MVP → 输出 design_v1.md
3. Reviewer 审核 design_v1.md → 直接修改输出 design_v2.md
4. Coder 读取 design_v2.md → 实现代码，输出 implementation.md
5. Validator 读取 implementation.md → 测试验证，输出 test_report.md

验证失败的自动回退机制

这是整个系统最有价值的部分——错误可以被自动发现、自动记录、自动修复。这一机制在工程实践上与持续集成/持续交付（CI/CD）流水线中的"门禁"（Quality Gate）概念一脉相承：传统CI/CD中，代码提交后会触发自动化测试，失败则阻断合并。此框架将这一机制内化为Agent间的协作协议，Validator相当于自动化的Code Reviewer和QA Engineer，其输出的test_report.md则类似于GitHub Actions的失败日志，为Coder提供精确的修复指引。

具体流程如下：

1. Validator发现Bug后，将Story状态从"Coding Complete"回退到"Coding"
2. Retry Count加1，记录尝试次数
3. 写入详细的test_report.md，包含失败原因
4. Coder读取测试报告，定位问题并修复代码
5. 修复完成后再次进入Validator验证

这个闭环确保了代码质量，不需要任何人工介入。

调度器的工作原理

主控程序（Worker）通过轮询状态文件来决定启动哪个Agent：

• 扫描所有Story的Status，找到Phase不是"Done"的Story
• 根据当前Phase决定启动对应的Agent
• Agent完成后更新Phase，形成闭环

每个Agent启动时都有强制的前置检查：读取Worker State确认当前Agent是否是自己、确认Phase是否正确、检查必要的输入文件是否存在——缺一个就停止。

MVP的关键作用：给AI一个参考锚点

为什么一定要提供MVP（最小可行产品）代码？因为AI需要参考实现来降低幻觉。没有MVP的设计就是空中楼阁。

这一设计有其深刻的认知科学依据。大语言模型在生成代码时，若缺乏具体参考，往往会产生技术栈选择随机、接口风格不一致等"幻觉"问题。提供MVP代码相当于为模型建立了一个约束空间，将无限的可能解压缩到与现有代码库风格一致的子集中——这与Few-Shot Prompting（少样本提示）的原理高度相似：通过具体示例引导模型输出符合预期格式和风格的结果，而非依赖模型自由发挥。从认知科学角度看，这正是"锚定效应"（Anchoring Effect）的正向应用。

MVP不是最终产品，而是给Agent的示范代码，就像新员工入职时看的老项目代码。MVP放在共享目录下，被所有Agent读取参考。这个设计极大地提升了AI输出的准确性和一致性。

实战效果：可视化监控与自动交付

启动Worker后，系统自动开启WebUI监控面板，提供三大核心功能：

1. 总进度圆环：实时显示完成百分比，直观了解整体进度
2. Story列表：每个Story的当前阶段、文件产出情况一目了然
3. 工作日志：实时滚动显示Worker和Agent的运行日志

从实际运行截图可以看到，9个Story大部分已完成，Coder正在处理最后一个Story。点击任意Story可以查看从需求到测试的完整产出链条，每个环节都有据可循。

最终交付的AI狼人杀游戏支持9人标准局（3狼人、预言家、女巫、猎人、3平民），9个独立的AI Agent自主推理、发言、投票，通过WebSocket实时推送游戏状态，前端可视化展示完整游戏进程。

总结：三步启动你的AI开发团队

这套多Agent自动编码框架的使用门槛极低：

1. 拆分PRD为Stories
2. 启动Worker
3. 打开监控面板

然后你就可以去喝咖啡了。

这套方案的核心启示在于：不要试图让一个AI做所有事情，而是用工程化的思维去编排多个AI实例。 文件做状态机、调度器做编排、严格提示词做约束——这三个要素组合在一起，就能让廉价模型也产出高质量的完整项目。这背后的工程逻辑与分布式系统设计、敏捷开发方法论、CI/CD流水线一脉相承，只是执行者从人类工程师换成了AI Agent。这不仅是一个技术方案，更是一种面向AI时代的软件工程范式。

核心要点

• 多Agent架构按上下文边界拆分（设计、编码、验证），而非按人类角色划分，实现上下文隔离和互相验证
• Agent之间不直接通信，完全通过文件读写传递信息（类似黑板系统架构），实现状态持久化和断点恢复
• Validator发现Bug后自动回退状态并打回Coder修复，形成类CI/CD门禁的自动化质量保障闭环
• 仅使用Gemini 2.5单一模型，通过工程化编排在3.5小时内零干预完成包含WebSocket、游戏引擎、AI玩家和可视化界面的完整项目
• MVP参考代码作为AI的锚点，通过Few-Shot Prompting原理有效降低幻觉，提升输出准确性和一致性