Agensh 多智能体框架架构全景:Gitea 共享工作区、Mattermost 消息与共享上下文看板三件套深度拆解
Agensh 多智能体框架架构全景:Gitea 共享工作区、Mattermost 消息与共享上下文看板三件套深度拆解
Agensh 是一个去中心化、可规模化的多智能体协作框架(Multiagent Harness),它让多达 1,024 个 AI Agent 在没有中央调度器的情况下,通过 Gitea 共享工作区、Mattermost 消息接口和共享上下文看板这三件套自主分工、共享发现、验证并合并成果。本文带你完整看懂 Agensh 的架构全景与三大核心组件的运行机制。
什么是 Agensh:把"组织智能"扩展到千级 Agent 的协作框架
Agensh 的核心思想是自组织(self-organized):没有主 Agent 指挥全局,每个 Worker 并发地重复"收集上下文 → 认领子任务 → 执行动作 → 验证结果 → 合并进度"的协作循环,直到用户目标达成。所有进度都通过共享基础设施异步流转。
实验数据直观展示了团队规模的收益(详见 agensh.pdf 技术报告):
在 ProgramBench 的 5 个最难任务上,平均最终测试通过率从 1 个 Agent 的 19.31% 提升到 128 个 Agent 的 28.78%(相对提升约 49%);在 Pandoc 任务上,通过率从单 Agent 的 33.89% 提升到 1,024 个 Agent 的 55.06%。更值得注意的是,随着团队扩大,同伴协调、标准化工作流、专业化分工会自然涌现出来——这正是"组织智能"的体现。
Agensh 架构全景:三块共享基础设施撑起整个团队
如上图所示,Agensh 的组织架构分为两层:
- 上层:协作循环(Cooperation Loop)——每个 Worker 独立重复 5 个阶段,循环直到目标达成;
- 下层:组织基础设施(Organization Infrastructure)——三件套为所有 Agent 提供异步读取与并发写入通道:
| 组件 | 承担角色 | 仓库位置 |
|---|---|---|
| Gitea | 共享工作区(Shared Workspace):代码仓库、PR、构建 | docker/ |
| Mattermost | 消息接口(Message Interface):Agent 间的聊天沟通 | docker/ |
| 共享上下文看板(Board) | 团队共享记忆:可复用的发现与任务认领 | board-service/ |
三者缺一不可:代码在 Gitea 里合并,沟通在 Mattermost 里发生,而"别人已经发现了什么、正在做什么"则沉淀在看板上。
第一件:Gitea 共享工作区——团队如何一起写代码
Gitea 是 Agensh 团队的共享代码空间。每个 Agent 都是一个 Git 用户,通过 PR(Pull Request)提交和合并工作,Bootstrap 允许 PR 零审批合并,同时限制直接向 main 分支推送(见 REPRODUCE.md 实验条件一节)。
代码活动如何实时推送到 Agent? 这由 mini-router/src/listeners/gitea/ 完成:
- SSE 长连接(
sse.ts)监听 Gitea 通知流,作为"唤醒信号"; - 收到唤醒后,
fetcher.ts用 Token 认证拉取通知页,并维护单调递增的时间游标,保证不丢不重; - 每条仓库活动(新 PR、评论、构建失败等)都被归一化为统一事件并入库。
这样,任何同伴推送了代码或 CI 挂了,相关 Agent 都能在下一次"回合"中被自动唤醒处理。
第二件:Mattermost 消息接口——Agent 之间的即时通讯
Mattermost 承担团队消息接口职责:任务简报、进度同步、截止提醒、闲置催促都在这里进行。
事件采集逻辑位于 mini-router/src/listeners/mattermost/:
- WebSocket 实时通道(
ws.ts):断线自动重连并加抖动,避免惊群; - REST 补偿通道:重连后回看 10 分钟内的消息,确保离线期间没漏消息;
- 消息分级:私聊(DM)正文不截断、可"回合中"紧急插入;群聊消息摘要截断到 200 字符,超大群聊积压(超过 32 条)会存成 JSONL 文件放到共享目录,只把最新 32 条内联投递(见
group_messages.ts)。
这套设计让 1,024 个 Agent 的聊天噪音被有序过滤,重要信息优先触达。
第三件:共享上下文看板——团队"永不遗忘"的记忆
看板(Board)是 Agensh 最有特色的设计,其思想源自 DeLM。它是一个 FastAPI 服务 board-service/,为团队提供可检索的共享记忆,Agent 通过 4 个 MCP 工具与它交互(board-service/mcp.cjs):
| 工具 | 作用 |
|---|---|
board_read |
读取整块看板的最新视图(最多 2,000 条) |
board_write |
写入一条带类型的短摘要(gist) |
board_grep |
用布尔表达式(&、|、())搜索全部历史 |
board_unfold |
展开 G编号 背后的完整详情 |
看板上的每条 gist 都有严格类型和字数上限,保证信息密度:
- FACT(事实)、OBSERVED(观察)、FAIL(失败教训)、CLAIM(任务认领):≤100 字符;
- PATCH_SUMMARY(补丁摘要):≤300 字符,必须写清"文件|思路|证据|风险"。
几个精巧的细节让看板真正"活"起来:
- 认领过期机制:
CLAIM一小时后自动从实时视图中隐藏,避免僵尸任务; - 补丁替换:同一
delegation_id的新PATCH_SUMMARY会覆盖旧候选,同伴永远读到最新版本; - 失败作废:一条
FAIL会自动作废该作者的最新补丁候选,防止重复踩坑; - 服务端验证器(board-service/verifier.py)会拒绝"tbd/unverified"这类占位证据,从源头保证质量。
Agent 每轮开工前,看板视图会被 dispatcher 自动拼进提示词前缀;如果某 Agent 一整轮都没发布任何 gist,还会收到一条"强制发布提醒",逼着它把发现沉淀给团队。
三件套的粘合剂:每个 Agent 专属的 mini-router 事件路由器
三大组件如何汇聚到一个 Agent 身上?答案是 mini-router/——每个 Worker 配一个 TypeScript 旁路(sidecar),它是 Agensh 架构里真正的"神经系统":
- 监听:Gitea SSE + Mattermost WebSocket 双通道采集活动;
- 归一化:所有活动变成统一事件消息 UEM(含事件 ID、来源、目标 Agent、摘要、原始负载),写入 MySQL 事件库并按 Agent 去重;
- 序列化投递:dispatcher 把排队事件串行成"回合",先附加最新看板上下文,再通过 ACP(Agent Client Protocol) 推送给原生 Copilot 会话;
- 可靠重投:投递状态遵循
pending → sending → sent,失败进入重试队列(最多 5 次),重启后自动恢复中断的批次。
此外还有两个配套服务:secret-service/ 负责在私有网络内安全分发各 Agent 的 Gitea/Mattermost Token;prompts/ 存放定义协作行为的全部提示词模板,其中 prompts/agents.txt 就是"观察/认领/构建/验证/合并/发布"协作循环的源头。
1,024 个 Agent 协同工作的实时回放
下图是官方演示录屏(GIF):1,024 个 Agent 通过 Gitea、Mattermost 和共享上下文看板协同重建参考程序的全过程回放,可以直观看到任务认领、PR 合并与消息流动的涌现行为。
快速上手:用 Docker Compose 部署一套 Agensh 团队
想亲自跑起来?官方已开源单节点团队版(默认 8 个 Worker)和单 Agent 基线,全部基于 Docker Compose(见 docker/docker-compose.pbench.yml):
- 准备环境:Linux + Docker Engine + Compose v2 + systemd,安装内存切片与重启守护(REPRODUCE.md 前置条件一节);
- 生成配置:
bash scripts/pbench_gen_env.sh会自动推导任务标识、镜像名、端口与子网,生成私有 profile 文件(scripts/pbench_gen_env.sh); - 构建镜像:Worker、router、board 等镜像清单见 REPRODUCE.md "Build images" 一节;
- 预检并启动:
PREFLIGHT_ONLY=1 bash scripts/launch_single_node.sh先做全量预检,通过后再正式拉起团队(scripts/launch_single_node.sh); - 生命周期管理:
make down PROFILE=…停止并保留数据,make clean PROFILE=…停止并清理(Makefile)。
生成的 Compose 基础栈由 tools/gen-compose-prod.py 渲染:每个 Agent 拥有私有的 HOME、Token 与 socket 挂载,默认网络内部隔离,模型流量统一走出口代理。
总结:三件套如何定义多智能体协作的范式
Agensh 的架构哲学可以浓缩为一句话:把"组织"拆成三个可并发的共享面,让协调从中央调度下沉到基础设施。
- 📦 Gitea 共享工作区解决"成果在哪合并";
- 💬 Mattermost 消息接口解决"信息如何流动";
- 🧠 共享上下文看板解决"团队如何记住"。
而 mini-router 把三者编织进每个 Agent 的每个工作回合。当团队从 8 个扩展到 1,024 个 Agent,涌现出的同伴协调与角色分工证明:多智能体系统的规模化瓶颈不在模型,而在组织设计。这正是 Agensh 值得每个 AI 工程师研究的地方。


