要上进的柯同学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编排逻辑，或是对主控下沉、点对点协作更感兴趣，这篇文章应该能帮上忙。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
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加入房间后，会主动调用一次事件历史同步，把这个房间的前置消息拉到一个本地索引里。这个机制很像给新入群的成员补发一份聊天记录，没有这一步，协同根本无从谈起。
我还额外做了一件事：把房间名和任务元数据挂钩。房间建立的同时，HiClaw会在房间的topic字段里写入任务描述、负责人、依赖模块、预期交付物清单。这有点像一个会议室白板上写的会议主题和议程，任何一个Agent加入后，先读topic，再读历史事件，就能快速进入状态。
3. Matrix协议选型与HiClaw的接入方式
3.1 为什么是Matrix，而不是其他消息中间件
说到多Agent通信，市面上已经有不少选择，比如直接走Redis pub/sub、Kafka消息队列、gRPC双向流，甚至WebSocket自建协议。我没选这些更“后端主流”的方案，而是选择Matrix，核心原因有三个。
第一是事件结构足够开放。Matrix里的事件就是带type、room_id、sender、content、origin_server_ts的JSON对象，Agent之间交换信息时，根本不需要额外定义传输层协议模板，直接把结构化数据塞进content字段即可。而且任何消息在服务器端都会持久化，天然具备“每位参与者都能共享同一份上下文”的特质。
第二是标准生态成熟。Matrix有现成的Server SDK和Client SDK，Python生态里就有matrix-nio这种好用的客户端库，接入成本很低。同时，它有端到端加密和完整的访问控制，比起裸写一套WebSocket协议，安全和权限体系完全不用自己造轮子。
第三是它天然支持BOT模式。每个Agent就是一个登录用户，使用同一个Matrix服务器上的账号密码就能收发消息。你甚至不需要一个专门的消息网关，Matrix自带的事件推送机制就能把新消息推给HiClaw进程，HiClaw再根据消息内容决定要不要唤起某个Agent。
3.2 HiClaw在客户端侧做了什么封装
HiClaw并不是把每个Agent都做成一个永久驻留的Matrix bot，那样做资源占用太高，也不灵活。更实际的做法是：HiClaw进程内集成一个轻量Matrix客户端，统一负责事件监听和消息发送，Agent只是逻辑上的执行单元，通过回调方式被触发。
我举例描述一下这种接入方式。在HiClaw配置里，你会定义一组Agent，每个Agent对应一个Matrix账号和一组room的订阅列表。启动后HiClaw通过MQTT风格的订阅方式，监听房间里的新消息。当某个消息匹配到指定Agent的触发条件时，HiClaw就把该消息连同最近事件序列打包成一个“任务上下文”，递交给这个Agent的推理逻辑。Agent拿到上下文后，自行决定是直接回复、调用工具还是静默跳过。
有一次我做过一个实测，给“测试Agent”连发5条消息，其中3条是无关的闲聊，2条是新的bug报告。当时我并没有让HiClaw对每条消息都触发一次模型调用，而是先经过一层轻量的关键词和意图过滤，命中bug报告模式后才把全部5条消息作为上下文递交给测试Agent。这极大节省了token消耗，也避免Agent被无关消息反复打断。
所以HiClaw在这里的定位更像“调度壳”，它要解决的问题不是让Agent自己去连Matrix，而是帮开发者在Agent和Matrix之间建立一个可控制的连接层，让触发策略、上下文组装、结果回写都变得可以编程化和观察化。
3.3 自建还是使用托管服务器
如果你只是做概念验证，可以用一个公共的Matrix服务器，注册几个测试账号，然后直接在上面跑Agent。这大概几分钟就能完成，也不需要管部署。但如果在生产环境，我强烈建议自己用Synapse部署一个私有服务器。原因很简单——Agent之间交流的数据往往包含业务细节、需求文档摘录和运行日志，这些信息不应该落在第三方服务器上。自建的话，消息持久化在自己的对象存储和数据库里，访问控制也更干净。
Synapse的部署不算复杂，官方提供Docker镜像，一条docker run基本就能起服务。需要注意的点是，默认配置下Synapse会启用比较严格的rate limit，多Agent在密集通信时很容易触发429，所以在配置里要适当调高rc_messages_per_second和rc_message_burst_count。我之前就是因为没调整这个参数，导致Agent在某个高频协作节点上突然集体失声，排查了半天才发现是消息被限流了。
4. 任务编排与Agent触发的核心链路
4.1 一次典型任务从投递到完成的事件流
在HiClaw里，一次任务的生命周期可以用一系列Matrix事件来描述。我拿一个“给某个服务做代码审计并生成优化建议”的任务来完整拆一遍。
首先，用户在客户端的输入框提交任务，外部网关Agent会解析出任务类型、目标代码仓库、审计范围，然后调用Matrix创建房间API，建一个#task-20250110-003的新房间，并把任务描述写入房间topic。紧接着，网管Agent发送一条m.room.message事件，内容是标准化的任务指令，里面有“请audit-agent开始审阅仓库xxx分支代码，重点关注内存泄漏和未捕获异常”的语义。
HiClaw监听房间事件时，发现这是一条指令事件，随即检查任务状态机，判断现在是否处于“待启动”阶段。如果符合触发条件，它会向审计Agent发送一个唤醒信号，让它先拉取仓库元数据。审计Agent的返回也不是直接就抛结果，而是先把中间结论以“发现一个问题：第186行可能存在goroutine泄漏”的形式发到房间，作为事件流的一部分。
在传统的agent串联模式下，这种中间结论可能只存在于Agent记忆里，不会暴露给外部。而在Matrix消息模式下，这个中间结论成了房间里的一条可见消息，其他Agent可以基于它做联动分析。比如风险检查Agent监听到这条消息时，会把它和之前几个审计发现合并，计算整体的风险评级，然后主动发送一条“风险等级偏高风险”的提醒。最后，协调者Agent在收到审计Agent的“审计完毕”事件后，将所有结论整理成一份结构化报告，发到房间里，再由网管Agent把最终报告推送给用户。
整个链路里，没有一个Agent知道“完整任务”是什么，不需要维持一个巨大的全局状态，每个Agent只需关心自己收到的消息、本地维护的轻量状态和输出结果。这套模式的好处是可以在不改变其他Agent的前提下，随时把一个新的Agent拉进房间来补充视角，比如你可以在中间加入一个“并发边界分析Agent”，它只需订阅审计Agent的发现，就能输出并发冲突方面的独立意见。
4.2 事件协议字段怎么设计
直接往Matrix里发自然语言肯定能跑通，但如果不想让Agent的大脑浪费在解析消息格式上，最好从一开始就在内容层约定一套结构化协议。
我习惯在Matrix消息事件的content里再包一层业务结构，格式类似这样：
json复制{
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"body": "[EVENT] task.audit.finding#186",
"hi": {
"schema_version": "1.0",
"event_type": "task.audit.finding",
"task_id": "task-20250110-003",
"producer": "audit-agent",
"payload": {
"file": "src/core/pool.go",
"line": 186,
"severity": "high",
"summary": "goroutine leak detected",
"suggestion": "use errgroup with context"
},
"trace_id": "a3f2...9c",
"timestamp": 1739520000000
}
}
其中m.room.message是Matrix的定义，事件本身遵守标准结构；hi字段是业务协议层，用来传递Agent协同所需的控制信息。有了这个字段，Agent做决策时就不需要靠“阅读自然语言”来理解消息，直接从event_type和payload取值，准确率和效率都能上来。
trace_id需要重点说明，这是所有Agent在处理同一个任务时都必须保留的追踪标识。只要消息从网管Agent发出，HiClaw就会生成一个trace_id，后续所有Agent发消息时都把这个ID带进去。排查问题的时候，按trace_id在Matrix事件库里搜索，就能拿到整条任务的完整消息链，不需要像传统日志系统那样在多个Agent各自的日志文件里来回翻找。我在很早的版本里偷懒没加这个字段，实际调试时，几十条消息混在一起，根本分不清哪条对应哪个任务，加了之后整个世界清净了。
4.3 Agent触发策略与防抖
Matrix房间本身不会做语义过滤，所以HiClaw里一定要有触发策略。我的做法是把触发条件分三档：
- 硬触发：消息的
hi.event_type精确匹配某个Agent的注册事件类型，比如task.audit.finding只触发审计Agent和风险检查Agent。 - 内容触发：消息没有业务协议字段，但正文包含某些关键词，比如“帮我看下这个内存泄漏”，会由协调者Agent根据关键词分配到对应执行Agent。
- 人为触发：在测试或调试模式下，人类开发者可以直接在Matrix客户端里@某个Agent，强制唤醒它执行一次。
在触发过程中有个隐藏问题是Agent可能在短时间内收到多条性质相似的消息，如果每条消息都触发一次完整的模型推理，很容易因上下文不足而做出重复或片面的回答。我加了一个“消抖窗口”机制：同一Agent在收到消息后的80秒内，HiClaw不会触发新的推理，而是把新消息累积到待处理缓冲区里，直到窗口结束后，将这段时间的所有消息合并成一份增量上下文，一次性交给Agent处理。这个机制特别适配那种Agent之间连续来回对话的天蝎场景，可以大幅降低推理次数和账单金额。
5. 透明化：为什么这套架构更适合观察和复盘
5.1 把Agent的思考过程看成一出“多幕剧”
做多Agent系统的人，大多都遇到过这种痛苦：明明每个Agent单测是通的，连起来一跑就出错，而你很难定位是哪一步偏移了。原因在于，大多数Agent框架只在最后把结果写进日志，中间的过程全部封存在黑盒里。你看到的是“Agent A说完了，Agent B开始干”，至于Agent A到底说了什么、Agent B基于哪些上下文做的判断，一概不知。
Matrix协议天然解决了这个问题。所有Agent之间的消息都作为独立事件存储在服务器上，任何一个时间点，你都可以打开客户端查看“当时发生了什么”。为了便于复盘，我在HiClaw里还内置了一个小型索引器，它会实时监听房间事件，把每条事件归类到任务ID、Agent ID和事件类型三个维度，并追加写入本地SQLite数据库。复盘时直接按任务ID查询，就能还原出完整对话流和决策路径。
有一次在做一轮真实审计任务时，我发现最终报告里对某个缓存的优化理由写错了，按正常流程，这个错误可能被埋在后面所有环节中，当时我要从测试Agent那里找原因，一直没有线索。后来借助Matrix房间里的完整对话回溯，才发现是某个开发Agent在中间环节从一段示例代码中“学到”了错误的缓存淘汰策略，并且后续Agent全都没有质疑这一点。换句话说，错误的源头其实是跨Agent上下文传递时继承下来的，而不是某个Agent自己生成错误。放在传统黑盒模式里，这个根因几乎不可能被定位。
这也是我坚持在架构里保留完整事件历史的原因。你当然可以只让Agent把最终结果汇报给协调者，省点存储和网络开销，但“透明化”对多Agent系统的价值远高于那点成本。用一个不太严谨的类比：如果公司员工开会时没有会议纪要，指望最后交一份PPT就当复盘，那出了事谁也说不清楚是谁在哪个环节拍板造成的。
5.2 实时可视化时需要注意什么
既然Matrix本身是一个聊天协议，理论上可以直接用现成的Matrix客户端观察Agent的动作。但实践一段时间后我发现，直接用通用客户端看Agent交流，体验并不好——Agent之间消息密度太高，而且经常用重复的内容来回确认，很容易刷屏。
我后来在HiClaw上做了一层简单的“可视化视图”，其实本质就是把房间事件按方向和类型聚合成更易读的卡片列表。比如“谁在什么时间执行了什么模块、产出了什么结论、被谁采用了”，一眼扫过去就能掌握整个任务的推进节奏。实现这个视图的技术也不复杂，就是循环调用Matrix的/rooms/{roomId}/messages接口把事件拉取到本地，再按Agent维度和事件类型做统计。
不过要提醒一点，Matrix的sync接口默认可能不会同步全量历史，特别是房间刚刚创建时，如果服务器配置了消息保留策略，部分早期事件可能会被裁剪掉。所以如果你非常依赖透明化复盘，请在Synapse的配置里把消息保留期设置得足够长，或者直接关闭自动清理，将房间事件备份到独立的存储。
5.3 审计模式下要给关键节点打“检查点”
光有事件流还不够，在一些重要协作节点上，我会让Agent显式发送一条带event_type=task.checkpoint的事件。这相当于在会开一半的时候强制确认“大家对当前理解一致吗、有不同意见吗”。实现上，协调者Agent在收到各Agent反馈后会检查所有checkpoint消息的时间戳，如果有人超时未确认，就发一条提醒并要求相关Agent重新同步上下文。
我在一次模拟发布会风险控制的Demo任务里，让评审Agent在发放最终结论前人工确认审计Agent定义的“内存泄漏等级”口径。因为如果不做这一步，不同Agent对“high和medium”的判断可能基于不同的阈值标准，导致最终报告里出现自相矛盾的结论。加上checkpoint后，Agent会暂停执行下一步，等待所有相关Agent同步完毕，虽然多了一次消息往返，但显著减少了产生荒唐结论的可能。
这其实也从侧面反映，多Agent协同系统最重要的设计原则不是“显得聪明”，而是“能停下确认”。在真实团队里，成员讨论后对齐口径是常识；在多Agent系统里，你必须有明确的机制让Agent主动暂停下来对齐，否则它只会顺着自己的局部理解一路黑到底。
6. 实操部署：从零搭一套HiClaw+Matrix环境
6.1 服务端与账号配置清单
说完了思路，这节直接上手。我按自己常用的技术栈列一份清单，假设你的机器是Ubuntu 22.04，已经装好Docker。
我用的核心组件包括：
- Synapse容器：官方matrix-org/synapse镜像，版本建议1.98以上，老版本在事件同步上的性能差距比较大。
- HiClaw主程序：我用的是Python版本，主要负责监听事件、编排Agent生命周期、管理与大模型的交互。
- SQLite/PostgreSQL：Synapse默认SQLite也可以，但Agent数量超过5个、消息并发频繁后，PostgreSQL明显更稳。
- Redis：可选，用来做Agent会话锁和消抖窗口的临时状态存储。
账号准备阶段，我会先创建三个基础Agent账号和一个测试人类账号，按最小权限原则分配。注册方式有两种：一种是通过Synapse的注册接口开放后注册，另一种是管理员接口直接创建。我建议开发阶段用后者，因为可以一条命令完成，还不用处理邮件验证。
Synapse的Docker部署命令大致如下：
bash复制docker run -d --name synapse \
-v /srv/synapse/data:/data \
-p 8008:8008 \
matrixdotorg/synapse:latest generate
首次启动时Synapse会在/data下生成homeserver.yaml，你需要修改其中的server_name、数据库连接和消息保留配置。生成配置后再次启动就会真正拉起服务。
6.2 HiClaw侧的账号接入配置
HiClaw主程序里需要维护一个Agent registry，里面登记每个Agent的名称、Matrix用户名、密码、监听的事件类型列表。配置格式大概是这样的：
yaml复制agents:
- name: audit-agent
matrix_user: "@audit-agent:matrix.internal.local"
matrix_password: "xxxxx"
subscribe_to:
- event_type: task.audit.finding
- event_type: task.audit.checkpoint
llm_profile: "deepseek-v3"
max_steps: 10
model_timeout_ms: 120000
启动后HiClaw会遍历这个列表，逐个建立Matrix客户端会话并加入对应任务房间。注意HiClaw和Agent不是1对1进程绑定，而是共享一个客户端的连接池，HiClaw在主循环里以user_id为维度分发事件到对应处理函数。
我在这个步骤里吃过一次大亏，验证了两天都没跑通消息推送，最后发现是Synapse默认的enable_registration被关了，无法新建用户。虽然我可以直接用管理员接口创建，但因为我一开始没把管理员token写对，始终登录不上。所以一个体检建议就是先把管理员token放到环境变量里，再写自动化脚本创建账号，别手动在配置里粘贴。
6.3 启动后的连通性测试
环境起来后，先别急着放任务进去。我会用两种方式做连通性验证。
第一个是用Matrix客户端手动登录到某个Agent账号，选一个房间发一条普通文本消息，然后在HiClaw的日志里确认看没看到对应m.room.message事件。如果看不到，大概率是账号权限不足或监听房间没加对。
第二个是做一次最小化Agent测试，写一个临时Agent，它只做一件事：收到消息后原样返回一条带时间戳的回复。这样可以快速验证全链路从消息投递、事件监听、Agent回调、模型推理、结果回发是否通顺。这个最小化测试跑通后，再挂正式的Agent逻辑。
7. 实际运行中遇到的高频问题与排查思路
7.1 事件风暴：Agent之间互相循环触发
这是多Agent系统里最经典的灾难。有段时间我启用了两个Agent，一个负责方案设计，一个负责问题质疑。设计Agent提交方案，质疑Agent发现漏洞，返回让设计Agent修改；设计Agent改完才发现又有新漏洞——结果两个Agent在房间里无限来回对话，每次对话都消耗一次模型调用，账单飞快增长。
解决办法分两层。第一层是硬件层面的事件节流，HiClaw在触发Agent前判断它的“发言频率”，同一Agent如果在60秒内已经响应过3次，就不再直接触发，而是把新事件标记为“pending_consideration”。第二层是语义层面的终止条件，在协调者Agent下发的任务指令里，明确要求设计Agent和质疑Agent最多只能来回三轮。超出轮后，由协调Agent强制结束讨论，转入总结阶段。这两层机制叠加后，系统再没有出现过失控的循环对话。
如果你用的是别的Agent框架，同样建议从一开始就给每个Agent设计一个“发言预算”，这个比事后清理要省事一万倍。
7.2 消息幂等与重复消费
Matrix客户端的sync接口是按时间线增量同步的，如果你没有正确记录from token，很容易出现同一条消息被推送两次的情况。HiClaw早期的版本里，Agent在审计场景中收到相同的“内存泄漏发现”，重复发出了两条结论，进而导致测试Agent重复执行用例并汇报了一模一样的结果，最后报告里出现了重复片段。
修复方案是在HiClaw内部维护一个“已消费事件ID集合”，对每条消息事件用其event_id做去重判断，只有集合里不存在的事件才进入处理流程。这套机制听起来简单，但必须是第一批功能就做进去，因为任何没有去重的多Agent事件系统，迟早会出问题。
7.3 Agent状态不同步
还有一种常见的状况：不同Agent对同一个问题的认知产生了分歧。源头通常不是推理能力不足，而是不同Agent加入房间的时间点不同，它们看到的最近消息集合有差异。比如审计Agent在20点发送了“第186行是异常”，但风险检查Agent是20点03分才完成历史同步，如果同步过程出了故障，它可能就漏掉了这一条。
这个问题的解法是让每个Agent在每个任务关键节点都主动回读一次最近上下文，并把自己基于什么版本消息做出的判断写进结构化输出里。我在HiClaw的请求上下文中增加了last_event_id字段，Agent上报结果时都必须带上“我是基于哪条事件做出的这个判断”。一旦发现不同Agent的last_event_id差异较大，协调者会发起一次“状态对齐”，阻塞任务进度直到同步完成。
7.4 大模型幻觉顺着链路被放大
最后说说最根上的问题。单个Agent的幻觉，在多Agent协同下会被放大，因为后一个Agent看到前一个Agent的输出时，倾向于相信它是真的。为了对抗这个问题，我在HiClaw里给每个Agent配置了“证据要求”，比如代码审计Agent的推理结果必须带代码行号，测试Agent的结论必须带具体测试名称，产品Agent的需求描述必须引用上游文档段落号。没有证据链支持的结论，默认标记为“低置信度”，不允许直接进最终报告。
这套机制虽然不能说完全杜绝幻觉，但它能有效切断幻觉在Agent之间的“感染传播”，让错误停留在创建它的地方，而不是被后来者包装成可信结论。
8. 写在最后的几点个人心得
8.1 不要困在“主控Agent”的迷思里
很多多Agent框架的方案是把主控Agent塑造得像神谕一样，什么问题都先问主控，主控再分发任务。但真实业务里，这其实容易重蹈集成灾难：主控Agent承担了所有语义理解、任务拆解、状态追踪和报告生成，它反而成了最大的可扩展性瓶颈，也最容易成为幻觉源头。
在Matrix消息模型里，任务执行更像“投喂给房间，让最适合的Agent响应”，而不是“由某个Agent命令其他Agent执行”。我不否认某些场景仍然需要主控Agent做最终裁决，但我个人建议把它弱化成“协调员”而非“全知大脑”，真正干活的是各个工作Agent，协调员更多负责进程推进。你会发现系统的容错率会好很多，因为即便某个Agent输出有问题，其他Agent以平级视角更容易发现并纠正。
8.2 透明化是长期维护的前提
多Agent这类系统有个特点：短期看效果不错，长期看需要持续迭代。一旦进入迭代，你必须有足够的记录来判断每次改动到底改善了哪个环节。如果整个系统不透明，你只能靠“跑一次看结果”来判断好坏，很难定位到具体是哪一步的变化导致输出大幅漂移。
Matrix协议提供的事件历史，加上HiClaw在事件之上的结构化索引，让我可以在几秒内回顾一次任务中每个Agent的每一条输入输出，这对系统迭代的帮助无法估量。你可以对照“旧思考链”和“新思考链”的差异，清晰地看到某个Agent的行为在哪些环节发生了变化，再决定是调整模型参数、提示词还是触发策略。
8.3 如果只让你记住一件事
最后分享一个比较务实的小技巧：从最小的Agent团队开始，别一开始就追求大而全。先跑通一个“两个Agent加一个协调者”的最小闭环，把事件协议、触发策略、去重机制、状态对齐这些底层设施完整落地，再逐步加Agent角色。设施到位后，加Agent只是一个配置项变更，但如果设施还没成熟，Agent一多，问题就会像滚雪球一样涌过来。
我在这套HiClaw+Matrix架构上跑了近三个月，中途经历过Agent间无意义循环、事件风暴、上下文漂移和模型幻觉传染，最终把它们一个个压了下去。现在这套系统每次任务结束，都能交出一份带完整事件流的透明总结报告，这在很多传统Agent框架里是做不到的。如果你也正在折腾多Agent协同，不妨试试用Matrix这样的消息协议做底座，让Agent像一群真实同事一样，在同一个房间里有迹可循地对话和协作。