模块六：运营增长与高级话题 | 第07讲：Multi-Agent 协作——多 AI 协同开发的工业级实践
本讲偏「流程与风险控制」，可与 MCP、上下文工程联动使用。
课程项目：VibeNote 智能笔记
技术栈：Next.js、React、TypeScript（App Router）
本节目标：判断何时引入多智能体；用角色分工、上下文隔离与编排模式控制复杂改动的风险与审查成本；把并行开发建立在可验证契约之上。
一、开场：并行不是目的，可控才是
参考《工具链与开发框架》对 Claude Code Swarms 的概括：多智能体解决的并不是「同时开很多窗口更快」，而是让复杂任务不再被单一长上下文拖垮。当你让同一个对话既改数据库迁移、又改前端表单、又顺手重构工具函数，模型后期违反早期约束的概率会显著上升——这不是模型「变笨」，而是注意力与规格在长跑里被稀释。
VibeNote 进入协作版、团队版、AI 管道增强后，单次改动的扇出面会变大。此时 Multi-Agent 的价值是：把不确定性隔离在盒子里，让人类合并时仍能理解每一步。
二、单 Agent 失效的三个信号
- 规格反复回潮：前期说好不用某库，后期又出现 import。
- diff 不可读：一次提交动到 30+ 文件，审查变成「信任骰子」。
- 调试链路过长：工具调用与补丁交织，无法定位是哪一步引入 Bug。
出现任意两条，就该考虑任务拆分或多角色协作。
flowchart TD
S[单对话持续变长] --> N[噪声上升]
N --> V[违反早期约束概率上升]
V --> M[需要拆分/隔离]
三、何时用 Multi-Agent：决策树（落地版）
flowchart TD
A{是否跨子系统?}
A -- 否 --> B{是否仍可能产生\n大 diff?}
B -- 否 --> ONE[单 Agent + 强规格]
B -- 是 --> SPLIT[拆分 PR]
A -- 是 --> C{是否需要不同技能栈\n(DB/UI/AI/安全)?}
C -- 否 --> SPLIT
C -- 是 --> MA[多角色子代理]
经验法则：只要你能用「两个可独立验收的 PR」描述工作，就尽量不要塞进一个 Agent 会话。
四、编排模式：流水线、主从、对抗评审
1）流水线（Pipeline）
规划 → 实现 → 测试 → 文档。每一步输出必须可审查，再进入下一步。适合从 0 到 1 且需求仍可能变化的功能。
2）主从 Orchestrator-Worker
主控负责拆任务、定边界、合并结果；Worker 只在自己的目录与接口契约内动手。
flowchart TB
O[Orchestrator] --> W1[Worker: schema/migration]
O --> W2[Worker: API]
O --> W3[Worker: UI]
W1 --> O
W2 --> O
W3 --> O
3）实现者 + 评审者（Critic）
实现者写代码，评审者只找安全、边界、测试缺口。给 Critic 检查表（XSS、CSRF、鉴权、PII 日志、错误泄露），避免无限挑剔。
五、上下文隔离：allowlist 是最小可行纪律
- Worker A：
db/**、drizzle/** - Worker B：
app/(app)/**、components/** - Worker C：
lib/ai/**、app/api/ai/**
共享类型文件由 Orchestrator 或人类合并，避免「双头修改」。
六、任务工件：用仓库文件替代口头同步
design/goal.md：本周唯一目标与非目标design/api-contract.md：请求/响应/错误码design/test-plan.md：必须通过的用例列表
聊天会丢，工件必须可 diff。
七、人类红线审查：哪些文件不让 Agent「独自合并」
- 鉴权 / session / cookie 策略
- 支付、计费、发票
eval、动态执行、反序列化- 数据迁移与批量删除
八、VibeNote 实战剧本：协作评论功能
Orchestrator：里程碑与合并顺序
Worker DB：comment 表、索引、级联
Worker API：Server Actions、速率限制、Zod
Worker UI：Thread、a11y
Critic：XSS（Markdown 渲染）、越权、通知泄露
每轮合并后：lint + typecheck + 最小 e2e。
九、失败模式清单
- 双 Worker 改同一文件 → 明确文件所有权
- 没锁契约就并行 → 先接口后实现
- 集成堆到最后 → 持续集成小步合并
- 绕过 CI → 再快也不合并
十、与 MCP 协同
子代理需要稳定访问 VibeNote 数据时，用 MCP Server 暴露只读查询，统一工具面，便于审计与权限。
十一、节奏：单人多代理也要「集成检查点」
每 90 分钟回答三个问题：主干是否 green？契约变了吗？有没有两个 Worker 动到同一路径？
十二、值不值：用三个数自评
- 审查耗时 / PR 是否下降？
- 回滚率是否下降？
- 重复劳动是否减少？
若三项无改善，只是多开了聊天，没有真正编排。
你也可以把「集成检查点」写进日历提醒：它和写代码同等重要，却最容易被省略。
十三、Supervisor、Swarm、Pipeline：三种架构怎么选？
下面这张表把课程第四十七篇里的模式压缩成决策参考（场景以 VibeNote 为例）：
| 模式 | 结构 | 优点 | 风险 | 更适合 |
|---|---|---|---|---|
| Supervisor | 主管分解与汇总 | 边界清晰、易审计 | 主管瓶颈、分解质量决定上限 | 需求→设计→实现→测试链条明确 |
| Swarm | 多代理共享黑板 | 灵活、可探索 | 重复劳动、冲突多 | 文档共创、方案脑暴、边界不清的探索期 |
| Pipeline | 固定流水线 | 审查点清晰 | 上游错误会传导 | 成熟功能迭代、强流程团队 |
对 VibeNote 的默认建议：Supervisor/Orchestrator + 少量 Worker 作为主路径；在 PRD 尚未稳定前，用 短时间的 Swarm 脑暴生成方案，再收回 Supervisor 执行。
flowchart LR
BRAIN[Swarm 脑暴\n(短、可控)] --> LOCK[锁定 ADR/契约]
LOCK --> SUP[Supervisor 交付]
十四、冲突解决：当两个 Worker 都「有道理」
常见冲突类型：
- 数据模型 vs 交互体验：多一个字段能支持更好筛选，但表单变复杂。
- 严格鉴权 vs 分享便利：公开链接与权限体系天然拉扯。
- 性能 vs 功能：全文检索要预计算索引，开发量上升。
解决策略：把冲突上升为 ADR（Architecture Decision Record），写清取舍、替代方案、可回滚条件。Orchestrator 禁止在聊天里「口头拍板不留痕」。
十五、工具策略：少而准，避免「50 个工具」灾难
参考 Vercel 工程博客的经验：工具过多会提高决策噪声。多 Agent 场景里，每个 Worker 的工具集也应 单独裁剪。例如 UI Worker 不需要数据库管理工具；DB Worker 不需要浏览器自动化。
十六、与 Code Review 对齐：给人类审查者的最短路径
建议 PR 描述固定包含：
- 用户故事一句话
- 风险点 Top 3
- 如何验证（命令、账号、截图）
- 回滚方式
Agent 生成 PR 文案时，把模板贴在 PULL_REQUEST_TEMPLATE.md，能显著减少「我不知道怎么测」的返工。
十七、扩展阅读：从 Swarms 到日常迭代
你不必一开始就用「蜂群」。更现实的路线是：
- 先用 单 Agent + 强 AGENTS.md 跑到产品稳定；
- 当出现大改版，再引入 Orchestrator + 2 Workers；
- 只有在安全敏感或质量抖动时，再加 Critic。
十八、并行开发的前置条件：契约测试与 Mock
当你让 Worker B（前端）与 Worker A（后端）并行，最重要的是 API 契约先落地。推荐最小组合：
- 在
design/api-contract.md写明路径、方法、请求体、响应体、错误码。 - 用 Zod 或 OpenAPI 生成共享类型（或手写对齐）。
- 前端使用 MSW 或简单 Mock Route 先跑交互；后端用契约测试校验响应形状。
- 合并前做一次「对拍」：前端切到真实 API，跑关键路径 e2e。
没有契约的并行，只是同时制造两份技术债。
对 VibeNote 而言，「AI 摘要」「标签推荐」这类功能尤其要小心：前后端对「失败时返回什么」若不一致，UI 会出现看似随机空白。契约里务必写清 降级策略（例如返回 200 + 空数组 vs 422）。
十九、小结
- Multi-Agent 用于隔离风险与独立工作包，不是炫技。
- Orchestrator + Worker 最常见；Critic 需要检查表。
- allowlist + 工件化 + CI 是底座；工具集要按角色裁剪。
- 冲突用 ADR 固化；PR 模板让人类审查可走最短路径。
- 人类对安全与迁移红线文件保留审查权。
- 并行开发的前提是 API 契约 + Mock/对拍，否则只是并行欠债。
思考题
- 同一模型切换角色 vs 多会话隔离，你选哪种？为什么？
- Worker 只写 happy path 测试怎么办？你会给 Critic 哪些「必须检查的失败样例」？
- VibeNote 插件系统的多 Agent 边界画在哪？
- Supervisor 分解任务时，如何避免把「集成与发布」永远挤到最后才做？
- 如果蜂群模式出现重复劳动，你会改黑板规则还是改角色边界？
下节预告
下一讲：VibeNote V6.0 终章——MCP、AI 增强搜索、智能标签与团队协作闭环，以及上线验收清单。你会拿到一份「能演示、能卖、能维护」的最终检查表。
