agency-agents 实战：让多角色协作真正跑起来

多智能体系统最常见的混乱来源是角色边界不清。Planner 在写代码、Coder 在做架构决策、Reviewer 只说"看起来没问题"——每个人都做了不该做的事，结果谁都不对输出负责。我目前的做法是把角色拆成四类，严格定义输入和输出：

1. Planner：只负责任务拆解和步骤排序，输出一份"做什么、按什么顺序、每步的验收标准"的清单。不直接写业务代码。Planner 的价值在于把模糊需求变成明确步骤，这是整个协作链路的起点。
2. Coder：根据 Planner 的清单改代码，遇到信息不全就回提问题，不自作主张扩需求。扩需求是 Planner 的活，Coder 只管"按图施工"。这条边界看起来死板，但能有效防止 AI 在写代码过程中"顺手改了个不相关的东西"。
3. Reviewer：聚焦风险和可维护性，给出修改建议和验证点。不重写代码，只提建议——重写是 Coder 的事。Reviewer 的输出应该是结构化的：哪些地方有风险、风险等级、建议改法。
4. Runner：只做执行和回传结果（跑测试、跑构建），保证日志完整、可复现。不做分析，分析是 Reviewer 的事。Runner 的关键要求是"忠实回传"——成功就是成功，失败就是失败，不要用自然语言包装结果。

关键原则：每个角色只对自己的输出质量负责，不要越界。Planner 不评价代码质量，Coder 不决定任务优先级，Reviewer 不动手改代码。边界清晰了，出了问题才知道是哪个环节的责任。

刚开始做多智能体的人容易设计一个很长的流程：Planner 规划 → Coder 写 → Reviewer 审 → Runner 跑 → 回到 Planner。看起来很完整，但实际上每一轮都走完整个闭环的话，调试和迭代会非常慢——任何一个环节出问题都要从头来过。我更推荐"短回路"模式：

1. 一次只处理一个明确任务，避免同一轮里同时改 UI、改接口、改部署脚本。不同类型的变更混在一起，出了问题很难定位是哪个环节引入的。拆小之后，每轮的输出可以独立验证。
2. 每一轮输出都包含"做了什么 + 为什么 + 下一步建议"，方便后续角色快速理解上下文，不用从头读历史。这个格式看起来啰嗦，但在多智能体场景下能极大减少信息丢失。
3. 把工具调用结果当成一等公民——比如"测试通过/失败"应该是一个结构化结果（通过数、失败数、失败详情），而不是让下一个角色从"嗯测试基本都跑过了"这种自然语言描述里猜。