夜雨聆风近期参与GOAI比赛，读了下 AgentTeams 源码，做一次相关解读
AgentTeams典型的场景有几个特征：角色多、链条长、人要随时插进来、权限要隔离、文件和状态要共享、过程是持续调和而不是一次跑完。代码协作、PRD 准入、长期调研、企业内受控自动化，都属于这一类。
拆开来看，它要管住四件事：
Agent 得有生命周期和期望状态，不能只是个进程里的对象 Agent 之间的通信得可见可审计，不能只是函数调用 Agent 不能直接拿真实凭证，得经过网关和最小权限 多角色协作得有明确的房间和边界，不能靠临时约定
如果把整条主链路压成一句话：
YAML/CLI/API -> Controller -> CRD 调和 -> Matrix/MinIO/Higress/Runtime -> 任务分派 -> 执行与回写 -> 再调和
AgentTeams 系统全景
下面按这条链路拆。
1. 入口是资源，不是对象
AgentTeams 不接 SDK 对象，只接声明式资源：
apiVersion: agentteams.io/v1beta1kind: Workermetadata: { name: codeops-executor }spec:model: qwen3.5-plusruntime: hermessoul: |谨慎的证据主义者，证据不足时明确输出"不确定"agents: |- 只在批准的范围内修改- 单提交点，副作用先查询再创建
第一步不是创建一个实例，而是把目标状态写进控制面。Controller 是标准的 controller-runtime：资源落进状态存储，Reconciler 比对差异，该建建该删删。
具体有三个动作：
apply只声明意图，不直接做业务 watcher 把外部 YAML 变化转成内部状态变化 reconciler 按当前状态和目标状态的差值，决定创建、更新、删除
这套做法和传统多 Agent 框架差在哪？后者把 Agent 放在进程里管，进程一停就没了；前者把 Agent 放进一个可持久化、可重建、可调和的资源系统里。
2. Controller 是控制面，不是调度器
Controller 下有四个 Reconciler：
Worker Team Human Manager
各管一类资源，控制目标也各不相同。
Worker Reconciler
创建一个 Worker 通常要做这些事：
起容器或 Pod 下发模型和角色配置 注册 Matrix 账号和房间 分配 MinIO 空间 生成 Higress Consumer Token 推送 SOUL.md和AGENTS.md
更新多半触发配置重建——模型变了、Skills 变了、权限变了。删除按依赖顺序清资源，不直接杀进程。
Team Reconciler
Team 是个带层级的组织单元，要建的东西包括：
Leader 多个 Worker Leader Room Team Room 每个 Worker 的独立房间
Team 一动不是多一个对象那么简单，成员关系、房间成员、权限关系要跟着一起动。
Human Reconciler
Human 是有权限级别的资源，不是旁观者账号。要做的事：
建 Matrix 用户 分房间访问权限 调 groupAllowFrom 管邀请和踢出
重点不在 UI，在权限边界。
Manager Reconciler
Manager 管协调，不越过层级直接指挥底层 Worker。管的事包括：
镜像和运行时配置 SOUL / AGENTS Skills MCP 认证 期望状态同步
这一层把"协调"和"执行"分开了。
3. 通信不走黑箱，走 Matrix 房间
Matrix 房间协作拓扑
AgentTeams 没把协作塞进内部消息队列，直接把通信放在 Matrix 上。
这么选有三个直接收益：消息路由现成、对话全程可见、人类随时能插进来。
房间分三层：
Leader Room Manager + Team Leader + Human 负责分发、汇报、确认 Team Room Team Leader + Workers 负责执行、分解、文件交换 Worker Room 单 Worker 私聊关键不在房间多，在权限边界：
Manager 只在 Leader Room Worker 不能穿透到上层 人类可以进任意可访问房间
通信方式用的是 m.mentions，靠 @mention 精确路由消息。好处是协作逻辑跟人类熟悉的聊天语义一致，不用另造一套消息协议。
和 Claude Code Agent Teams 的差别也在这：
Claude Code 更像文件邮箱 AgentTeams 更像可观察的协作房间
前者适合单机轻量强流程，后者适合多人协作、可见性和持续介入。
4. 状态放在存储和控制面，不放在 Agent 里
AgentTeams 里 Worker 本身是弱状态的，状态落在外面：
MinIO 存共享文件和任务文件 Controller 存资源状态 Matrix 存协作上下文 运行时只跑当前任务
这么设计的效果很直接：Worker 可以重建，任务和协作历史不用丢。
存储也不绑死某一种部署形态。embedded 模式用 kine + SQLite，incluster 模式用原生 K8s etcd，往上都抽象成同一层状态存储。
文件交换同理。大文件、任务产物、共享内容走 MinIO，不塞进聊天消息，减少消息膨胀，也把执行结果从通信层剥出来。
5. 凭证下沉到 Higress，不直接给 Worker
安全链路是整套系统里离"基础设施"最近的部分。
调用路径：
Worker -> Higress AI Gateway -> 真实服务
Worker 手里拿的是可吊销的 Consumer Token，不是真实 API Key。真实凭证留在网关侧，MCP Server 也通过网关托管。
拆开了就是两件事：
Worker 能发起调用 但不能直接持有真实密钥 真实服务访问走统一代理和审计
这套机制管的不是"Agent 会不会作恶"这种抽象问题，而是更具体的一件事：Agent 真出问题的时候，能拿走什么。
代价也现实：短期凭证要刷新、续期、失效处理。安全边界划得越清，生命周期管理越重。
6. 机制流转是一条控制回路
AgentTeams 控制回路
把上面几块合起来，流转过程分六步：
用户提交 YAML、CLI 或 REST 请求 Controller 把声明写进状态层 Reconciler 比对差异并创建资源 Matrix、MinIO、Higress、Runtime 一起编排 Manager 在 Leader Room 分派任务，Worker 在 Team Room 执行 执行结果和状态回写，触发下一轮调和
这是一条闭环，不是一次性流程。
所以整套系统的重点不在"Agent 能做什么"，在"Agent 团队怎么一直待在正确状态上"。
7. 这套设计的边界
AgentTeams 做对的三件事：把 Agent 资源化、把协作可视化、把凭证隔离化。
换来的代价也清楚：控制面复杂度高、存储和同步压力大、权限和刷新逻辑更重、调和系统本身就是一个要长期维护的系统。
它不是轻量框架，更像一个"协作操作系统"。
结尾
AgentTeams 并不一定是多agent的最优框架或方法论，而是把 Agent 当成系统来管，同时赋予其类似IM的可视化界面。
将资源、通信、权限、存储、在运行时拆开，再由 Controller 拼回一个可持续运转的协作回路。这套思路比它具体用了 Matrix、MinIO 还是 Higress 更值得记住。