Synapse · 多智能体协作框架

📎 演示材料外链

资料	链接	提取码
🎬 讲解视频	Baidu 网盘	u81y
📊 答辩 PPT	Baidu 网盘	qnb7

视频 / PPT 因体积较大未入仓,见根目录 讲解视频链接.txt / PPT链接.txt 同步保留。

作品概述

Synapse是一个面向多智能体协作的低开销通信、状态传递与共享记忆机制原型系统。该系统针对当前主流多Agent系统以自然语言或JSON作为通信媒介所带来的问题，提出了三大核心创新：结构化通信协议、非文本状态传递机制、共享记忆复用模块，为多智能体协作提供高效的基础设施支持。本作品最终采用S3.1主方案设计，在T1重构任务上实现turns从120降至36（-78%）的显著优化，60个e2e cell和3个s31_main cell全部PASS，系统稳定性验证充分。

本系统实现了多Agent运行时、结构化通信协议、非文本状态传递、共享记忆模块和CodeAct沙箱五大核心功能。多Agent运行时基于Agent Loop模式，支持Coordinator、Coder、Reviewer、Retriever四种角色协同运行。结构化通信协议采用自定义DSL，在T3任务上实现tc减少91.6%、bytes减少77.3%、elapsed_s减少84.0%的极端压缩效果。非文本状态传递采用BGE-M3嵌入编码，在T1任务上让工具调用数减少38.8%。共享记忆模块采用三层架构，Hybrid RRF在T3任务上memory_hits提升40%。S3.1闭环控制层包含门控拦截、修复循环、卡死检测三个安全网，确保系统稳定运行。

系统的技术架构分为三层。自底向上依次是基础设施层提供协议解析、状态传递、记忆存储等底层能力；Agent层构建多角色协同运行的运行时环境；实验评测层提供任务定义、实验执行、数据采集等支撑功能。

🎯 赛题要求逐项对照

操作系统开源创新大赛 · 多智能体协作赛题 12 项要求映射。

#	赛题要求	实现	证据
1	≥3 Agent 协同,覆盖规划/检索/执行/总结等角色	Coordinator / Coder / Reviewer / Retriever 4 类 AgentDefinition	src/synapse/agents/default_definitions.py:6
2	结构化通信(动作类型/输入/返回/能力描述)+ 握手/能力发现/协议映射	verb / params_json / result_json (Envelope) + Capability / AgentDescriptor proto + AgentDefinition.required_capabilities 静态校验	src/synapse/runtime/gen/synapse_pb2.py · capability_pb2.py · src/synapse/agents/capability.py
3	纯文本 + 结构化协议双模式,可复现对比	text_protocol.py / protobuf_protocol.py / dsl_protocol.py 三实现,通过 mode 切换;CSV 含 mode 列,3 seed 复现	src/synapse/protocol/ · experiments/results/*.csv
4	非文本中间状态传递(embedding/语义向量)	BGE-M3 1024d 编码器,生成→传递→接收→使用 4 段完整:encode / encode_raw / decode / cosine_sim	src/synapse/agents/state.py
5	共享记忆 + 5 项元数据	MemoryUnit 字段齐全:memory_id / source_agent / created_at / task_topic / summary	src/synapse/memory/base.py:17
6	关键词/标签/语义检索 + 跨 Agent 复用	KeywordMemoryStore (BM25) + HybridMemoryStore (BM25 + BGE 向量 + RRF 融合);search_memory 工具注册给所有 Agent	src/synapse/memory/ · src/synapse/agents/tools/search_memory.py
7	≥2 组关联性连续任务,验证减少重复计算/降低协作开销/提升效率	T1→T2→T3 代码考古连续链 + S3.1 修复闭环;cumulative_hits / Δhit_rate 跨任务指标	tests/integration/test_5schemes_3tasks.py · tests/integration/test_s31.py · docs/experiments/eval-report-final.md §4
8	统计消息次数/token 字符开销/非文本状态规模/单任务耗时/记忆命中率/整体性能	CSV 列齐全:messages / tokens / bytes / state_passes / elapsed_s / memory_hits / memory_queries;Web 仪表盘 4 页面	experiments/results/*.csv · dashboard/
9	架构 5 模块 + ≥10 轮连续任务	多 Agent 运行时 / 协议解析与调度 / 状态交换 / 共享记忆 / 评测;60 e2e cells (5×4×3) + 60 ablate + 3 s31_main = 123 cell	src/synapse/runtime/ · src/synapse/protocol/ · src/synapse/agents/state.py · src/synapse/memory/ · dashboard/
10	完整源码 + 设计文档 + 部署文档 + 实验报告 + 演示视频	源码入库 + docs/superpowers/specs/ 设计 + docs/achieve/deployment.md 部署 + docs/experiments/eval-report-final.md 实验报告 + 视频外链(本页顶部)	docs/ 全集
11	系统技术加成(IPC/共享内存/Socket/向量库/沙箱/eBPF)	SharedBoard (RLock + CAS 原子认领) = 共享内存;Hybrid RRF = 向量库;Pyodide WASM = 沙箱;Mailbox 异步编排	src/synapse/agents/board.py · src/synapse/sandbox/ · src/synapse/agents/mailbox.py
12	CodeAct (LLM 生成 Python + 沙箱执行)	ExecutePythonTool 走 PyodideRunner WASM 沙箱,失败安全 + trace 埋点	src/synapse/agents/tools/execute_python.py · src/synapse/sandbox/pyodide_runner.py

核心数字(3-seed, e2e_main.csv): S3.1 主方案 T1 turns 36 vs S0 120 (-78%),T3 tokens -89%,T1 elapsed -93%,Hybrid RRF 跨任务累积命中 8.00 (4 任务)。

✨ 核心特性

特性	一句话	实测亮点
DSL 协议层通信	用指令式极简语法替代自然语言往返,4 种协议可插拔	T3 任务压缩 tokens -89%
bge-m3 非文本状态	1024d 向量代替自然语言复述语义证据,纯 ONNX Runtime(不依赖 torch)	T1 任务 elapsed -93%
Hybrid RRF 记忆	BM25 关键词 + bge 向量双通道融合,跨 case pickle 持久化	T1 任务 Hybrid vs BM25 加速 49x
Registry 能力握手	AgentDefinition 声明 required_capabilities / provided_capabilities,启动前静态校验依赖	类 K8s readinessProbe
Mailbox 多 Agent 协作	持久化 inbox/outbox,TeammateSpawner 后台线程拉起,poll_task / delegate_task / send_message 异步编排
S3.1 闭环控制	Delegate 门控 + Checker-in-the-loop(修复循环)+ 卡死检测 + 严格 turn budget 隔离	T1 任务 3 seed 全部首次通过
Web 仪表盘 + TraceWriter	FastAPI 4 页面(/ /e2e /ablate /memory /audit),每个 case 同步生成 JSONL trace

---

5 方案梯度

方案	通信	状态	记忆	协作
S0	文本	文本	—	Coordinator
S1	DSL	文本	BM25	Coordinator
S2	DSL	bge	Hybrid RRF	Coordinator
S3.1 ★	DSL	bge	Hybrid	Coordinator + 闭环控制(Delegate 门控 + Checker + 卡死检测)
S4	DSL	bge	Hybrid	共享白板 + 自主认领

★ = 推荐主方案

---

架构总览

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 3 — 评测与可视化                                              │
│  pytest 集成测试 · 6 CSV + 130+ trace JSONL · Web 仪表盘 (FastAPI)   │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 2 — Agent 运行时 + 多 Agent 协同                              │
│  Agent Loop · Mailbox · TeammateSpawner · SharedBoard               │
│  工具:read/write/diff/grep/search/run_tests/exec_python             │
│        delegate/send_message/poll_task/board_*                       │
│        write_memory/search_memory                                  │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 1 — 四大可插拔机制 (A 通信 / B 状态 / C 记忆 / D 握手)         │
│  A Protocol:    Text · Protobuf · DSL · JSON                         │
│  B State:       TextState · BGEStateEncoder (bge-m3, 1024d)          │
│  C Memory:      NoMemory · Keyword (BM25) · Hybrid (RRF)            │
│  D Registry:    AgentDefinition + capability + cost_hint            │
└─────────────────────────────────────────────────────────────────────┘

---

快速开始

1. 装环境 + 装项目

git clone <repo-url> synapse
cd synapse

pip install -r requirements.txt
pip install -e .

2. 跑单元测试验证(~5s,无需 API key)

pytest tests/unit/ -v

3. (可选)下载 bge-m3 模型

只有用到 bge 状态 / Hybrid 记忆时才需要。模型 INT8 ONNX,~600MB,首次自动下载。两种路径任选:

路径 A:HuggingFace Hub

python3 -c "
from huggingface_hub import snapshot_download
snapshot_download('BAAI/bge-m3', allow_patterns=['onnx/*', '*.json', 'tokenizer*'])
"

路径 B:ModelScope(国内推荐)

pip install modelscope
modelscope download --model onnx-community/bge-m3-ONNX

验证编码

python3 -c "
from src.synapse.agents.state import BGEStateEncoder
import numpy as np
e = BGEStateEncoder()
v = e.encode_raw('hello')
print(f'OK: shape={v.shape}, dtype={v.dtype}, norm={np.linalg.norm(v):.3f}')
"

---

跑完整评测

bash scripts/run_full_eval.sh    # ~7h on openEuler,需 OPENAI_API_KEY

跑完数据自动落 experiments/results/*.csv,可通过 Web 仪表盘查看:

python dashboard/scripts/dashboard_gen.py
python -m uvicorn dashboard.app:app --host 127.0.0.1 --port 8000
# 浏览器打开 http://localhost:8000

---

文档导航

📊 docs/experiments/eval-report-final.md — v7 3-seed 完整评测报告(60 cell + 4 维度 ablate + S3.1 闭环 + 排雷叙事)