CodeBuddy · 腾讯云课程资料

多 Agent 协同架构

面向开发者的 AI 编程、上下文工程与多 Agent 协作。

返回专题 →智能体教程 →

来源：腾讯云培训认证中心 · CodeBuddy 架构师认证课程 · ch9

第 九 章 · Chapter 9

多 Agent 协同架构

本 章 学 什 么

  • 掌握四角色（FE / BE / Test / Review)的边界与越界原则

  • 掌握三阶段流程（规划 / 并行执行 / 交付）和每轮固定产物

  • 动手跑通建队 / 任务投递 / 冲突纠偏 / 失败降级的完整闭环

  • 建立证据链意识：输入 / 改动 / 验证 / 结论缺一不可

多 Agent 协同碰到的问题跟人类团队几乎一模一样——角色越界、信息不同步、冲突扯皮。所以本章核心不是"多开几个 AI 窗口"，而是像管真实团队一样管 AI 团队：清晰分工、共享看板、可回滚交付。

重 要 提 示

本模块基于 CodeBuddy CLI 的实验性功能 Agent Teams——可能随版本迭代发生变化。如遇与本讲解稿不符的情况，以官方最新文档（codebuddy.cn/docs）为准。

什么时候从单 Agent 迁移到多 Agent

三个信号——任务复杂度高（要同时推进多条独立任务线）/ 单 Agent 的 System Prompt 越来越臃肿（角色定义和约束互相干扰）/ 上下文窗口压力大（单 Agent 跟踪太多上下文，输出质量下降）。 把"一个什么都会的 Agent"拆成"多个各司其职的专家 Agent"——是解决上述问题的标准路径。

9.1 四角色定义与越界原则

多 Agent 协作第一步——把角色边界定清楚。边界不清，Agent 就互相抢活；边界清楚，协作才稳。

角色 负责 输入 / 输出 禁止项
Frontend 页面、组件、交互、状态展示 UI Speckit + 接口契约 / 前端实现 + 截图证据 不得私改后端契约
Backend API、数据模型、业务规则 Feature Speckit + 数据模型 / 接口实现 + 调用样例 不得跳过验收直接宣称完成
Test 回归用例、边界场景、失败复现 需求验收项 + 日志 / 测试结果 + 失败清单 不负责"顺手修代码"——独立验证、暴露问题
Review 规则一致性、风险审查、合并建议 以上所有产出 / 审查意见 + 合并决策 不直接大改代码，只给结论——是护栏不是执行者

考点：四角色不是名字好听，是为了防越界。考试如果问"某个 Agent 擅自改了不属于自己的契约"，答案就是越界——需要点名纠偏，回到 Speckit 或任务边界重新确认。

9.2 三阶段流程与执行清单

三阶段

阶段 关键动作
① 规划 锁定 Speckit 和接口契约 → 拆分任务 → 建共享看板（pending / in_progress / blocked / completed）。这步偷懒后面冲突一定多
② 并行执行 FE/BE 并行推进，Test 跟进回归，Review 收敛。每轮输出 Round 汇总。连续 2 轮不收敛立刻降级串行——这是保命机制
③ 交付 四件套齐了才能完成：功能验收 / 质量验收 / 风险验收 / 复盘产物

每轮固定产物

每个 Agent 每轮必须交五样：

  • 本轮目标

  • 实际改动

  • 验证结果

  • 风险与阻塞

  • 下一轮建议

少一个都不行——这个格式有点像项目周报，但更细，目的是让 Team Lead 能判断下一轮怎么调度。

任务指令四段式

每条任务都得包含四段

目标——它做什么。边界——它不碰什么。验收标准——什么时候算完。禁止项——红线在哪。 这是保证 Agent 不越界的核心格式。

快速判断 · 真题

场 景

FE Agent 和 BE Agent 连续 2 轮争论接口字段命名（totalCount vs total），始终没有收敛。怎么处理？ 标准答案：立即停止并行 → 回到 Speckit 修订接口契约 → 重新执行。连续 2 轮不收敛就触发降级，回到规约层面解决。直接指定字段名也可以，但必须记录并更新规约文档，不然下一轮 Agent 还是按旧的理解来执行。

9.3 实操全流程

开启 Agent Teams

方式一 · 终端配置

codebuddy /config

移动到 [Experimental] Agent Teams → Enter 切为 true → Esc 退出

方式二 · 环境变量

export CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS=1复制

Agent Teams 是实验性功能——开关没开，建队和协作都不会按预期跑。

一句话建队

在同一对话里发自然语言建队指令，CodeBuddy 自动建团队、生成成员、分配任务：

我正在设计 TODO CLI 工具，请创建团队：UX 设计 / 技术架构 / 挑刺者。 先给出职责分工与首轮任务。复制

多 Agent 团队需要共享上下文和任务看板，拆到多个对话里就容易状态不一致。建队指令不用复杂，但角色和首轮任务得说清楚。

启动前检查 + 任务面板

检查项 目的
锁定工作目录 防止 Agent 改错项目
锁定 Speckit 版本 防止需求漂移
明确权限边界 控风险
设最大轮次（6-10轮） 防无限循环
建好证据目录 artifacts/round-logs/ 能复盘、能审查、能回滚

任务面板状态机：pending → in_progress → completed，in_progress 可转 blocked 再回来。blocked 必须写明原因 / 解锁条件 / 预计时间，completed 必须附证据。

写作铁律 · 防并发冲突

三条铁律： ① 先对齐再改码——契约没定好，不许动手写代码 ② 避免覆盖冲突——不同 Agent 改同一个文件 = 灾难 ③ 看板即事实——任务状态以看板为准，口头承诺不算

防并发冲突策略： 优先：任务拆分时规避——不同 Agent 负责不同文件 兜底（生产级）：分布式锁 / 消息队列序列化

收敛、降级、纠偏

动作 关键要点
每轮汇报 Team Lead 输出 Round N 汇总：完成 / 阻塞 / 新增风险 / 需人工决策 / 下一轮计划。冲突处理顺序：契约一致性 → 规则一致性 → 实现优先级
失败降级 触发条件：同类错误连续 2 轮没收住 / 跨模块修改不可控 / 验证结果跟结论矛盾。策略：停掉并行 → 保留主任务子任务串行 → 回到 Speckit 修订 → 重新执行。降级不是失败，是保命机制
点名纠偏 用 @成员名 点名，说清跑偏点 / 修改范围 / 禁止项。每次干预记录"触发原因 → 干预内容 → 结果变化"——这就是后续复盘和审查的日志

指令速查：@成员名 点名分派/纠偏 / @all 全员广播统一约束 / Tab 补全成员名 / Ctrl+T 查看看板。@all 慎用——适合统一规则和边界，不适合频繁发细碎指令。

9.4 实战三轮样例

演练目标 · Todo 列表模块

60-90 分钟交付一个可演示模块——列表展示、条件筛选、CSV 导出、空态/错误态。

任务拆分

  • FE-1 列表页 + 筛选栏 + 加载态（2 轮）

  • BE-1 查询接口 + 导出接口（2 轮）

  • TEST-1 冒烟 + 边界 + 回归（2 轮）

  • RV-1 规则审查 + 合并建议（1 轮）

三轮对话样例

轮次 核心动作 预期输出
Round 1 · 建队 + 看板 发建队消息创建四角色团队 看板初始化（FE-1 pending / BE-1 in_progress / TEST-1 pending / RV-1 pending）+ 首轮任务分配
Round 2 · 并行 + 冲突 @Backend / @Frontend / @Test 点名分派 Round 2 汇总：BE-1 可用 / FE-1 可渲染 / 导出字段名冲突（totalCount vs total） / 进入纠偏
Round 3 · 纠偏 + 交付 @Backend 修正字段；@Test 回归筛选 / 空结果 / CSV 字段 最终交付摘要：全部 completed / 字段冲突已解决 / 冒烟+5 条边界通过

DoD · Definition of Done

  • 列表与筛选联动正常

  • 导出文件可下载且字段正确

  • 空数据 / 异常有可见反馈

  • 无越权修改与危险操作

  • 有完整执行记录与复盘摘要

只做了列表展示但没导出？不算。导出能下载但字段不对？不算。功能能用但没记录没复盘？也不算。

9.5 安全与质量红线

多 Agent 协作效率高，但风险也更高——红线不是建议，是不能跨过去的线。

类别 红线
安全红线 不在命令和日志中明文暴露密钥 / 不允许未审查的危险文件操作 / 不允许跳过验收直接标记完成
质量红线 不接受"改动大但没验证" / 不接受"构建通过但没边界测试" / 不接受"成功结论跟证据对不上"
证据链 每个任务至少保留：输入指令 / 关键改动 / 验证输出 / 结论——少一项就不能标 completed
Agent Teams 边界 会话恢复后成员状态可能不完整 / 关键协作要可重放 / 单会话只维护一支团队 / 别搞"团队套团队"嵌套——复杂场景用"并行+降级串行"

9.6 练习与自测

练习目标不是写多少代码，而是把多 Agent 协作流程练熟——边界要清楚、blocked 要会处理、降级要敢触发。

三个层级的练习

练习 目标与关键动作
① 双 Agent 并行（必做） 选已有项目的一个功能，拆成 FE 和 BE 两条并行任务——锁定契约 → 并行推进 → 完成一次合并审查。重点检查 FE 和 BE 是不是真的边界清楚：前端不改接口，后端不改页面，两边通过契约对齐
② 三 Agent 回归（必做） 在练习 ① 基础上加 Test Agent——增加 5 条回归用例 / 记录至少 1 条 blocked 原因 / 完成解锁并复测。重点是 blocked 状态：练习怎么写阻塞原因、解锁条件、复测结果——能把 blocked 处理清楚比"从来不卡住"更有价值
③ 失败降级演练（进阶） 故意制造一次契约冲突（比如字段名不一致），完整走一遍：发现冲突 → 暂停并行 → 回到 Speckit 修订 → 重新执行并通过验收。失败降级不丢人，它恰恰是多 Agent 系统可控性的体现——只有在失败时才练得出降级流程

自测清单 · 三组问题

三组问题都能答上来，说明本章主线已经掌握：

能力维度 自测问题
建队与看板 能在同一对话用一句话完成建队？/ 能独立创建四角色任务看板（pending / in_progress / blocked / completed）？
任务与纠偏 能写出 FE / BE / TEST 三类任务指令的四段式（目标 / 边界 / 验收 / 禁止）？/ 能在冲突出现时做一次点名纠偏（@成员名 + 跑偏点 + 修改范围）？
收敛与交付 能给出至少 1 份 Round 汇总和最终交付摘要？/ 能说出"并行 vs 降级串行"的切换条件（连续 2 轮未收敛 / 跨模块不可控 / 证据不一致）？

建队是启动能力，纠偏是执行能力，收敛是结尾能力——三组都过，多 Agent 协同就真正掌握了。

9.7 核心收获

通用架构对照 · Orchestrator / Sub-Agent

考 点 集 中

本讲实操是"Team Lead + FE/BE/TEST/RV 四角色"具体实现，考试用通用术语 Orchestrator / Sub-Agent 描述同一架构模式。Orchestrator = Team Lead，负责拆任务、调度 Sub-Agent、监控、汇总——不亲自执行，自己又协调又执行是反模式。

通信模式 · Hub and Spoke

Orchestrator 作为中心节点（Hub），所有 Sub-Agent 只与 Orchestrator 通信（Spoke），Sub-Agent 之间不直接互通——通信路径清晰、Orchestrator 掌握全局状态。对应实操：FE/BE/TEST/RV 各自向 Team Lead 汇报，Team Lead 统一协调。

通信方式与状态共享

通信方式 适用场景
消息队列 异步解耦，发送方不需等接收方响应
共享状态存储（Redis / 数据库） 多 Agent 读写同一份数据，实时同步
直接 API 调用 需即时响应的同步通信——耦合较强，调用链复杂时难排查

考试重点：多 Agent 间传递任务结果和指令的标准架构是消息队列或共享状态存储，而非直接互相调用。 状态共享对应：CodeBuddy 实操的"共享看板（四状态机）" = 通用系统的"共享状态存储（Redis、数据库）"——两者本质一样，都是中心化的状态源。

可观测性三要素

  • 日志（Logs）——每个 Agent 的每个操作都要记录。本讲的"证据链要求"就是手动日志规范

  • 链路追踪（Distributed Tracing）——可视化任务在多 Agent 间的执行路径。常见工具：OpenTelemetry / Jaeger

  • 指标监控（Metrics）——聚合统计：任务成功率、平均耗时、错误率

本讲的*"每轮汇报"和"Round 汇总"*是手动可观测性；生产级系统需要自动化的链路追踪和指标监控。

本章小结

  • 角色边界——FE/BE/Test/Review 四角色 + 禁止越界。边界不清就互相抢活，边界清楚才稳

  • 并行协作——共享看板（四状态机）+ 成员互通 + 每轮汇报。任务指令四段式：目标 / 边界 / 验收 / 禁止项

  • 降级保命——连续 2 轮不收敛立刻串行 + 回到 Speckit 修订。降级不是失败，是可控性的体现

  • 证据链——输入 / 改动 / 验证 / 结论，缺一不可。结论必须跟证据一致

下一模块（最后一章）进入**「CI/CD 自动化流程」**——把前面所有能力真正落到团队的日常开发流程里，让 AI 成为流水线上的一道自动化工序。