1. 项目概述当AI Agent在Monorepo中“群聊”最近在折腾一个挺有意思的工程实践在一个大型的Monorepo项目中同时部署了5个不同专长的AI Coding Agent让它们协同工作目标是在Linear这样的项目管理工具上自动创建、评审和合并Pull Request。听起来是不是有点未来感但实际操作起来你会发现最棘手的不是单个Agent的代码生成能力而是如何让这5个“聪明”但“固执”的AI在同一个代码库、同一套流程里和谐共处高效协作。这个项目的核心我称之为“Symphony”交响乐。它要解决的本质上是一个协调问题。想象一下一个负责前端React组件的Agent一个专精后端API设计的Agent一个处理数据库迁移的Agent一个优化构建配置的Agent还有一个负责代码审查和测试的Agent。它们各自能力都很强但如果缺乏指挥结果可能就是前端Agent改了API接口后端Agent毫不知情数据库Agent生成了迁移文件构建Agent的配置却没更新代码审查Agent提出的修改建议可能被其他Agent无视或重复提交。最终Linear上会堆满冲突、重复或逻辑断裂的PR团队反而需要花更多时间去“解围”而不是享受AI带来的效率提升。Symphony项目就是这套“指挥系统”。它不是一个全新的AI模型而是一套建立在现有Monorepo架构和AI Agent工具链之上的协调层与工作流引擎。它的目标是定义清晰的规则、建立有效的通信机制、管理共享的上下文确保每个Agent在正确的时机、基于正确的信息、执行正确的任务最终像一支训练有素的交响乐团一样输出和谐、高质量的代码变更。接下来我会详细拆解我们是如何设计并实现这套系统的包括架构思路、技术选型、实操步骤以及我们踩过的那些坑。2. 核心架构与设计哲学2.1 为什么是Monorepo AI Agent选择Monorepo作为战场是协调问题复杂性的根源也是其解决方案价值最大化的地方。在单体或多仓库架构中AI Agent的协作边界相对清晰一个仓库通常对应一个明确的业务域或服务。但在Monorepo中所有包package共享同一个代码库、同一套依赖管理和构建工具。一个看似微小的改动比如更新一个被多个包共享的底层工具函数或者调整一个通用类型定义都可能产生广泛的涟漪效应。这种强耦合性恰恰是AI Agent单打独斗的噩梦却是Symphony这类协调系统发挥作用的舞台。Monorepo提供了统一的“事实来源”Single Source of Truth包括统一的依赖图所有包之间的依赖关系清晰可见。统一的变更历史所有修改都在同一个git历史中便于追踪影响。统一的工具链一致的lint、format、test、build命令。Symphony的设计哲学基于三个核心原则上下文隔离与共享的平衡每个Agent需要有自己专注的工作上下文避免被无关信息干扰同时对于可能影响他人的变更必须能及时、准确地获取共享上下文。动作的原子性与可观测性每个Agent执行的任务如“创建组件”、“修改API”必须是原子的、可描述的并且其输入、输出、状态变化对协调器是透明的。流程的编排与冲突预判工作流不是静态的脚本而是能根据任务类型、代码变更范围和Agent反馈进行动态编排并能在冲突发生前进行预判和调度。2.2 Symphony协调层架构拆解我们的Symphony协调层主要由以下几个核心模块构成它们共同工作管理着整个AI Agent集群。[外部触发器] - [任务解析与分发器] - [Agent执行队列] | v [共享上下文管理器] -- [Agent A] [Agent B] [Agent C] | | | v v v [工作流状态机] ---- [冲突检测与仲裁器] ---- [PR生命周期管理器] ---- [Linear/GitHub]1. 任务解析与分发器这是系统的入口。触发器可能来自Linear中新创建的任务Issue、GitHub的Webhook如对新commit的响应、或定时任务。分发器的核心职责是解析意图分析任务描述判断其涉及的范围前端、后端、基础设施等、类型新功能、Bug修复、重构和复杂度。任务分解将一个复杂任务拆解成一系列原子性子任务。例如“实现用户登录功能”可能被分解为“设计用户表”、“创建认证API”、“实现登录页面组件”、“编写集成测试”。Agent匹配根据子任务类型将其分配给最合适的Agent。这里我们维护了一个Agent能力注册表记录了每个Agent擅长的领域如react-agent,api-agent,db-agent。2. 共享上下文管理器这是协调的“中央情报局”。它维护着一个动态的、结构化的项目上下文知识库包括代码图谱当前Monorepo中各包的依赖关系、关键接口、类型定义。变更集所有正在处理中的、已提交的变更及其状态。环境状态当前各分支状态、CI/CD流水线状态、测试覆盖率等。会话历史Agent与系统、Agent与Agent之间的关键对话和决策记录。 上下文管理器通过监听文件系统变更、Git操作和Agent的事件输出来更新自己。它为每个执行中的Agent提供“上下文窗口”只注入与其任务高度相关的信息避免提示词Prompt过度膨胀导致模型性能下降。3. 工作流状态机它定义了不同类型任务的标准处理流程SOP。例如一个“数据库迁移”任务的工作流可能包含[待分配] - [db-agent设计] - [上下文同步] - [api-agent适配] - [生成测试] - [人工审核] - [合并]。状态机驱动着任务在不同Agent和状态间流转并可以基于规则或Agent的反馈如“此变更需要先更新共享库X”进行动态跳转或分支。4. 冲突检测与仲裁器这是系统的“交通警察”。它持续监控文件锁冲突多个Agent是否试图同时修改同一个文件。逻辑依赖冲突Agent A的变更是否会使Agent B已生成的代码失效例如删除了一个正在被使用的函数。流程顺序冲突任务顺序是否违背了依赖关系例如API还没定义前端就开始调用。 一旦检测到潜在冲突仲裁器会介入。策略可能包括暂停后触发任务、要求相关Agent重新协商方案、或者将冲突升级到“人工仲裁队列”。5. PR生命周期管理器这是与Linear/GitHub等外部系统对接的模块。它负责创建PR根据Agent生成的变更集自动生成具有清晰标题、描述和关联Issue的Pull Request。更新PR在后续的协作中如根据Review意见修改自动更新PR的代码和评论。管理状态同步PR的审查状态、合并状态回Symphony系统以触发后续工作流如合并后触发部署。2.3 技术选型与工具链实现这套架构我们选用了以下工具链主要基于其生态成熟度、可编程性和与AI的亲和力Monorepo管理工具Turborepo。选择它而非Lerna或Nx主要是看中其极快的增量构建和缓存机制。当多个Agent并行修改不同包时Turborepo能智能地判断哪些包需要重新构建和测试这对于维持开发环境的一致性至关重要。其管道pipeline定义也可以被Symphony的工作流状态机所驱动。AI Agent框架LangChain 自定义Agent。LangChain提供了构建Agent所需的基础组件如Tools, Memory, Chains但其开箱即用的Agent通常过于通用。我们基于其BaseAgent类为每个专长领域定制了Agent并为其装备了领域特定的工具Tools例如db-agent的工具集就包括generate_migration、inspect_schema等。协调层运行时Node.js TypeScript。整个Symphony协调层本身就是一个Node.js应用。TypeScript的强类型系统对于管理复杂的Agent间消息格式、上下文数据结构来说是不可或缺的能极大减少运行时错误。Agent间通信基于事件的发布/订阅Pub/Sub。我们使用了Redis作为消息后端。每个Agent和协调模块都是事件的生产者和消费者。例如当api-agent完成一个接口定义时它会发布一个api.interface.defined事件并携带相关类型文件路径。frontend-agent如果订阅了此事件就会被自动触发开始生成调用该接口的客户端代码。这种松耦合的方式比直接的函数调用更灵活易于扩展。上下文存储与向量检索Supabase (PostgreSQL) pgvector。我们将结构化的项目元数据如依赖图存在PostgreSQL中。而对于非结构化的知识如代码注释、文档片段、过往的决策记录我们将其转换为向量嵌入使用OpenAI的text-embedding-3-small存入pgvector扩展中。当Agent需要理解一段代码的“意图”或寻找类似解决方案时协调器可以通过向量检索快速提供相关上下文。外部系统集成Linear SDK GitHub API。使用官方的SDK和API进行深度集成实现任务的自动创建、状态同步和PR管理。注意工具链的选择高度依赖于团队现有技术栈和具体需求。例如如果你的团队主要用Python那么协调层用FastAPI来构建用Celery管理任务队列也是完全可行的方案。核心在于理解各模块的职责而非拘泥于具体工具。3. 核心模块实现与实操要点3.1 定制化AI Agent的打造一个只会调用/v1/chat/completions的“裸”大模型并不是真正的Agent。一个有效的Coding Agent需要具备以下特质我们以api-agent为例进行说明1. 身份与角色固化在每次与模型交互的System Prompt中我们必须清晰地定义其角色、职责和边界。const systemPromptForApiAgent 你是一个资深的后端API架构师专注于设计和实现RESTful/GraphQL API。 你的知识截止日期是2023年10月。你精通Node.js (Express/Fastify)、Python (FastAPI) 和 Go (Gin) 等框架。 你的职责是根据需求设计清晰、安全、高效的API接口并生成相应的控制器、服务层代码以及OpenAPI/Swagger文档。 **边界**你只负责API层逻辑。数据库模型定义由db-agent负责身份验证、授权中间件由共享库提供前端交互逻辑与你无关。 你生成的所有代码必须遵循项目已有的ESLint和Prettier配置。 在开始工作前你必须先通过协调器查询当前的数据库Schema和相关的业务领域模型。 ;通过反复强化这个身份Agent的输出会变得更加稳定和符合预期。2. 装备领域专用工具ToolsTools是Agent感知和操作世界的“手”和“眼”。我们为api-agent装备了queryContext(topic: string): Promisestring向协调器查询与当前任务相关的上下文如相关的数据模型、已有的接口。readFile(path: string): Promisestring读取Monorepo中指定文件的内容。writeFile(path: string, content: string): Promisevoid将生成的代码写入指定路径。协调器会确保路径在正确的包内。runTests(packageName: string): PromiseTestResult运行指定包的测试确保新代码不会破坏现有功能。createPullRequest(title, description, changes): PromisePRLink将一组变更创建为PR草稿。每个Tool的执行都会被协调器记录和监控这是实现可观测性的基础。3. 实现链式思考与自我验证我们要求Agent在输出最终代码前必须输出一个“思考过程”Chain of Thought特别是当任务复杂时。例如任务为“用户资料更新”创建API端点。 思考 1. 需要确认“用户”模型的字段协调器查询User模型。 2. 这是一个PATCH操作因为只更新部分字段。 3. 需要验证传入的数据确保只允许更新特定字段如用户名、头像。 4. 需要身份验证中间件确保用户只能更新自己的资料。 5. 需要生成相应的OpenAPI文档。 6. 需要编写单元测试覆盖成功、验证失败、未授权等情况。协调器可以解析这个思考过程提前发现可能的问题比如User模型是否已存在或者将其作为有价值的上下文提供给后续的测试生成Agent。3.2 共享上下文管理器的实现细节这是Symphony的“大脑”其实现质量直接决定协作效率。数据结构设计我们设计了一个分层级的上下文存储interface ProjectContext { // 1. 静态图谱层 dependencyGraph: Mapstring, string[]; // 包名 - 依赖的包名数组 interfaceRegistry: Mapstring, InterfaceDefinition; // 接口名 - 定义文件路径、类型 // 2. 动态变更层 activeChanges: Mapstring, ChangeSet; // 变更ID - 变更集文件列表、状态、所属Agent // 3. 环境状态层 branchStatus: Mapstring, BranchInfo; // 分支名 - CI状态、最后提交等 // 4. 会话记忆层 agentConversations: ArrayConversationTurn; // 记录关键的决策点 }上下文的获取与注入当frontend-agent被分配任务“创建用户列表页”时协调器不会把整个Monorepo的代码都塞给它。它会执行一个“上下文组装”流程确定范围任务涉及web/app这个包。分析依赖从dependencyGraph中找出web/app直接依赖的包比如shared/types和api/client。检索接口从interfaceRegistry中找出api/client包中所有与User相关的接口定义。检查冲突查询activeChanges看是否有其他Agent正在修改shared/types中的User类型或api/client中的相关方法。组装Prompt将以上筛选后的、高度相关的信息依赖包版本、关键接口定义、类型、可能的冲突警告作为上下文注入给frontend-agent的Prompt。这种方式极大地提升了模型处理相关信息的效率并减少了因无关信息导致的“幻觉”。3.3 基于事件的工作流编排我们使用了一个轻量级的状态机库如xstate来定义和管理工作流。每个工作流都是一个状态机配置。例如一个功能开发工作流可能包含以下状态idle: 初始状态。analyzing: 任务解析器正在分解需求。backend_design:db-agent和api-agent并行设计数据层和API层。context_sync: 等待后端设计完成并将变更的接口同步给前端Agent。frontend_implementation:frontend-agent和ui-agent实现前端界面。testing: 测试Agent生成并运行单元/集成测试。review: 生成PR进入人工或自动化审查。merged: 任务完成。状态之间的转换由事件触发。这些事件可以是Agent完成事件如api_agent:task_completed。外部系统事件如linear:issue_updated。协调器超时或错误事件如conflict_detected。工作流引擎监听这些事件根据当前状态和事件类型决定下一个状态并触发相应的动作如分配新任务给某个Agent。所有状态流转和事件都被持久化便于调试和复盘。4. 实战演练一个用户登录功能的协同实现让我们通过一个具体的例子看看5个Agent是如何在Symphony的协调下完成“实现用户登录功能”这个Linear Issue的。第1步任务触发与解析我们在Linear上创建一个新Issue标题为“Implement user login”并添加详细描述。Linear的Webhook通知Symphony协调器。任务解析器分析描述识别出关键词user,login,authentication。它判断这是一个全栈功能涉及数据库、后端API、前端页面和测试。解析器将任务分解为原子子任务并创建初始工作流实例状态为analyzing。第2步后端设计与上下文同步工作流进入backend_design状态。协调器并行分配任务子任务ST-1(设计用户认证数据模型) -db-agent子任务ST-2(设计登录/注册API) -api-agentdb-agent接收到ST-1。它通过queryContext工具询问当前项目是否已有User模型。协调器返回“暂无”。于是它开始设计生成包含id,email,password_hash,created_at等字段的SQL迁移文件或Prisma Schema并写入packages/db/migrations/目录。完成后发布事件db.migration.created。api-agent接收到ST-2。它同样查询上下文得知User模型正在由db-agent创建中。协调器可能会让它稍等或者提供一个“模型草案”作为临时上下文。一旦db-agent完成并发布事件协调器立即将最终的模型定义同步给api-agent。api-agent基于最终模型生成POST /api/auth/login和POST /api/auth/register的控制器代码、请求验证逻辑、JWT令牌生成逻辑以及OpenAPI文档。完成后发布事件api.auth.endpoints.created。协调器的冲突检测器会检查db-agent和api-agent的变更确保字段类型匹配如password_hash是string类型。第3步前端实现工作流状态转为context_sync。协调器确认后端API已就绪并将API接口定义、类型TypeScript和示例请求组装成上下文包。状态转为frontend_implementation。协调器分配任务子任务ST-3(创建登录页面组件) -frontend-agent子任务ST-4(创建注册页面组件) -frontend-agent子任务ST-5(创建API调用客户端hooks) -frontend-agentfrontend-agent接收到任务和上下文包。它基于项目现有的UI库如Chakra UI, MUI生成登录表单组件LoginForm.tsx、注册表单组件以及使用react-query或swr的认证hooksuseAuth.ts。这些文件被写入apps/web/目录。第4步测试生成与PR创建工作流状态转为testing。协调器分配任务子任务ST-6(生成并运行后端API测试) -test-agent子任务ST-7(生成并运行前端组件测试) -test-agenttest-agent读取已生成的API代码和组件代码利用模式识别自动生成对应的单元测试和集成测试用例如测试登录成功/失败、表单验证并执行它们。所有测试通过后工作流状态转为review。PR生命周期管理器开始工作。它收集db-agent、api-agent、frontend-agent、test-agent产生的所有变更集git diff自动生成一个结构清晰的PR标题feat(auth): implement user login and registration描述自动列出所有关联的Linear Issue ID并概要说明本次变更内容由各Agent的提交信息汇总而成。分支从主分支创建一个形如auth/login-feature-timestamp的特性分支并将所有变更推送上去。在Linear中该Issue的状态会自动更新为In Review。至此一个完整的、由多个AI Agent协作开发的功能就以一个准备就绪的PR形式呈现在团队面前等待人工最终的审查和合并。5. 踩坑实录与避坑指南在实际运行这套系统的过程中我们遇到了无数挑战。以下是一些最具代表性的“坑”和我们的解决方案。坑1Agent的“创造力”导致架构漂移现象每个Agent都力求完美地完成自己的子任务。api-agent可能会引入一套全新的错误处理中间件而frontend-agent可能用另一种状态管理方案重写了已有的逻辑。虽然单个模块看都很优秀但合在一起项目架构变得不一致且臃肿。解决方案强化“项目约束”上下文。我们在共享上下文中明确加入了项目架构规范这是一个强约束文件定义了必须使用的核心库如状态管理只能用ZustandHTTP客户端只能用axios。目录结构规范。错误处理、日志记录的统一模式。API响应体的标准格式。 在每个Agent的System Prompt中都会强调“你必须严格遵守《项目架构规范》”。协调器在代码生成后也会用简单的规则引擎如AST解析做一次合规性检查。坑2上下文过时与“脏读”现象frontend-agent基于10分钟前的API接口定义生成了代码但在此期间api-agent已经根据Review意见修改了接口。导致前端代码一生成就过时。解决方案实现“上下文版本戳”和“订阅-通知”机制。共享上下文中的每个关键实体如API接口定义都有一个版本号。当Agent要基于某个实体工作时会在其任务中记录所依赖的实体版本号。当该实体被其他Agent修改时协调器会递增其版本号并通知所有依赖了旧版本的任务所属的Agent。收到通知的Agent可以选择a) 立即暂停等待新上下文b) 基于旧上下文继续但最终提交前必须解决冲突。我们通常建议选择a这要求工作流设计得有更强的容错和重试能力。坑3循环依赖与死锁现象api-agent说“我需要先知道前端表单字段才能设计验证逻辑。”frontend-agent说“我需要先知道API的验证规则和错误码才能设计表单。” 两者互相等待陷入死锁。解决方案工作流状态机需要识别这种“设计时依赖”并引入“约定先行”的步骤。在backend_design和frontend_implementation之前新增一个api_contract_design状态。由一个更上层的“架构师Agent”或人工先定义一份简单的API契约如使用OpenAPI Spec片段明确接口路径、方法、基本的请求/响应格式和验证规则。这份契约不包含具体实现。将这份契约作为共享上下文同时分发给api-agent和frontend-agent。两者可以基于这份稳定的契约并行工作。这实际上是将人类架构师的部分工作前置并自动化了。坑4PR描述与提交信息质量低下现象Agent生成的提交信息是“Update file”或“Fix bug”PR描述是生成的代码拼接对人类评审者极不友好。解决方案定制化“提交信息与PR描述生成器”。我们训练了一个轻量级的文本生成模型或精心设计Prompt专门用于分析代码Diff。该生成器会读取本次变更的所有文件Diff识别出功能模块、修复的问题、新增的特性等。按照Conventional Commits规范生成提交信息如feat(auth): add login endpoint with JWT。PR描述则采用模板填充包含变更动机、实现概要、测试情况、对其他模块的影响等章节使Reviewer一目了然。坑5Agent“自信”地引入错误现象AI生成的代码有时会引入一些微妙的逻辑错误、安全漏洞或性能问题并且Agent对自己生成的代码“信心十足”在自我检查环节无法发现。解决方案引入“红队Agent”和强制性检查关卡。红队Agent一个专门负责“挑刺”的Agent。它的任务不是创造而是破坏和质疑。在代码进入PR之前红队Agent会对其进行审查尝试找出潜在问题如SQL注入可能、未处理的边界条件、可能的竞态条件并提出质疑。这模拟了人类团队中的代码审查环节。强制性检查关卡在PR创建前必须通过一系列自动化检查这些检查比常规CI更严格安全扫描使用npm audit,snyk等。性能模式检测如是否在循环中进行了数据库查询。依赖许可证检查。 任何一项检查失败工作流都会暂停并将问题反馈给对应的开发Agent进行修复。6. 效能评估与未来展望实施Symphony协调系统后我们对效能进行了为期一个季度的跟踪。量化指标显示PR创建速度对于中等复杂度的功能如CRUD套件从创建Issue到生成可Review的PR时间从平均2-3人日缩短到2-4小时。上下文切换成本降低开发者无需在多个仓库、多个技术栈间切换AI Agent处理了大部分跨模块的适配工作。代码一致性提升由于强约束的存在代码风格和架构模式的一致性从约70%提升到95%以上。初期投入搭建Symphony协调层和训练/定制Agent大约花费了2个人月。然而最大的价值并非完全替代人力而是改变了开发者的角色。开发者从代码的“打字员”和“粘合剂”转变为目标的定义者、流程的设计者和质量的最终仲裁者。他们更专注于产品逻辑、架构设计和解决那些真正复杂、模糊的问题而将重复性、模式化的编码工作交给AI Agent联盟去执行。这个项目目前仍在迭代中。我们正在探索的方向包括更细粒度的Agent比如拆解出performance-agent专门做性能优化建议accessibility-agent确保前端组件符合无障碍标准。学习与进化让协调器能够从人工对PR的合并、修改、评论中学习优化任务分解策略和Agent的Prompt形成一个反馈闭环。多模态协作未来Agent的输入输出可能不仅是代码和文本还包括设计稿生成前端代码、架构图生成部署配置等Symphony需要协调的媒介将更加丰富。回过头看Symphony项目最深刻的体会是在AI时代个体的“智能”固然重要但系统性的“协调智能”才是将潜力转化为生产力的关键。构建一个能让多个AI高效、可靠协作的“操作系统”其挑战和回报丝毫不亚于研发AI模型本身。这或许就是下一代工程实践的核心战场。