基于Matrix协议的多Agent协同架构设计与实践

1. 先聊清楚：为什么要用Matrix协议做多Agent协同

我大概是从去年开始认真研究HiClaw这套多Agent框架的，起因也很简单：单Agent在复杂任务上经常显得不够用，代码审查、需求拆解、跨模块联调这些活儿，一个Agent又要调工具、又要写文档、又要自查，很快就超出上下文窗口。干脆拆成多个Agent分工协作，让它们像一个小团队一样运转。

但这个“像团队一样运转”说起来容易，做起来全是坑。一开始我用的是简单的主从模式，主控Agent负责调度，子Agent负责执行。跑了一周发现一个很核心的问题：主从模式的本质，其实是把子Agent当成另一种形式的tool来调用，每个子Agent只跟主控通信，彼此之间没有交流。任务一复杂，主控就成了瓶颈，所有消息都从它那里过一道，既要理解子Agent的回报，又要协调下一步动作，结果就是上下文膨胀得飞快，而且整个过程的决策链路人眼根本看不清楚。

后来我把目光转向了Matrix协议，思路一下子变了。Matrix本来是给即时通讯设计的开放协议，核心概念是“房间”和“事件流”，你可以在一个房间里拉多人进来，每个人的发言都按时间顺序同步到所有参与者手里。这不就是一个天然的多Agent消息总线吗？把Agent当作房间里的成员，把任务状态当作房间里的消息，Agent之间可以直接对话，也可以按需收听其他Agent的中间产出。HiClaw的定位也在这里发生了转变——不再是一个中心化调度器，而是一层用来管理和编排这些Agent身份、倾听房间内事件、触发对应Agent行动的薄薄的中控层。

这个方案的直接好处有两个。第一，透明化程度非常高。Agent和Agent之间交流的每一句话，都明文落在Matrix的事件流里，任何一个人或者另一个Agent，都可以回溯全过程。调试的时候，不用再靠日志脑补内部状态，直接像看聊天记录一样看Agent的协作轨迹就行。第二，解耦。某个子Agent逻辑上就是一个独立的Matrix账号，它不关心是谁给它发的请求，也不关心任务最终由谁落地，它只按协议响应消息。用这套机制，新增一个Agent就相当于把一个新人拉进群，老Agent完全不需要改代码。

这篇内容我打算从设计一路聊到部署、调度、排障，把我实际在HiClaw里基于Matrix搭的那套多Agent协作架构完整拆一遍。如果你正在纠结怎么写多Agent编排逻辑，或是对主控下沉、点对点协作更感兴趣，这篇文章应该能帮上忙。

2. 整体设计思路：把Agent团队变成一套“会议系统”

2.1 为什么不能把Agent都塞进一个“巨型提示词”

很多人理解多Agent，第一反应是“把任务拆成几块，每个Agent负责一块”，然后用自然语言把它们串起来。这是典型的流程驱动思维，在环节少、顺序强的小任务里确实够用，但一旦进入真实业务场景，问题就暴露了。

举个例子，我最初在HiClaw里同时挂了三个Agent：需求分析Agent、研发Agent、测试Agent。做法也很直观，主控Agent收到用户的一个需求，先让需求Agent产出PRD，再把PRD发给研发Agent写代码，最后让测试Agent出测试报告。看起来各司其职，但实际跑起来，经常出现一个情况：研发Agent写完第一版代码后，紧接着又按照测试Agent提出的边界问题改了一版，可需求Agent并不知道实现已经偏移了，于是后续方案还停留在旧理解上。

这就是流程驱动的盲区。任务现实不是一条单向流水线，而是一张持续变化的网，一个Agent的输出经常会影响另一个Agent的输入。如果设计里没有“反馈回路”和“广播通道”，所谓协同就只能停留在死板的分工上。

所以在HiClaw里，我放弃了把所有Agent串成一条链路的思路，改成了一种近似“项目群聊”的架构。整体上分为两层：Matrix服务器作为消息中枢，所有Agent都在上面以独立身份接入；HiClaw作为控制侧，负责任务级调度、会话生命周期管理、Agent行为触发与观察。每个Agent只跟Matrix房间打交道，对外部任务本身不需要知道完整上下文。

2.2 Agent之间怎么区分角色和边界

既然要像团队一样工作，就得有角色、有权责、有边界。用Matrix协议的术语来说，每个Agent账号在房间里都可以有不同的权限级别，默认情况我分成四类角色：

• 协作者Agent：负责具体执行，比如“前端助手”“后端助手”“文档助手”，它们是干活的主力，可以发送消息、上传事件，但不能踢人、不能改房间配置。
• 观察者Agent：只订阅事件流，不发言也不执行，比如“风险检查Agent”“合规自查Agent”，它们存在的意义是随时盯住房间里的关键节点，发现问题再提醒主要负责人。
• 协调者Agent：这层不是传统意义上拥有全部记忆的超级大脑，更像会议主持人，主要负责会话创建、任务分片、关键节点裁决。它在正常执行路径里不参与干活，只有拿到提交结果时才出现。
• 外部网关Agent：这是给人或外部系统留的入口，它负责把用户的自然语言需求转换成结构化任务，再按类型投递到特定的Matrix房间。

角色定好之后，权限配置也相对简单。Matrix的房间级别有Admin、Moderator、Member等，建议不要让执行Agent拿到Admin权限，否则一个Agent异常循环时可能导致整个房间配置被改坏。HiClaw启动时会校验各账号的角色，如果账号角色不符合预期，会直接拒绝启动并在控制台给出警告。

2.3 房间划分与任务上下文隔离

房间怎么划分，是整个架构里最关键的一个设计决策。我在HiClaw里采用“一个任务一个房间”的模式，任务开始时动态创建房间，任务结束时归档并退出成员。房间名字里会带上任务编号和任务类型前缀，比如#task-20250110-001: 高并发接口优化。这样做的原因一是物理隔离上下文，每个任务内部的讨论不会串味；二是方便做历史回溯，出问题的时候直接打开对应房间，就能看整个任务从立项到收官的所有Agent行动。

但这里有个容易踩的坑：Matrix房间里所有消息是持续累积的，Agent加进来之后如果不去拉取历史，那它只能看到加入之后的“新消息”，看不到之前的上下文。所以HiClaw在每个Agent加入房间后，会主动调用